Network Connection in the IDE Extensions
The purpose of this article is to describe the different kinds of network connections used by IDE extensions. This may help find problems that may affect some of the features.
Connection between IDEs and IDE-extensions backend
Since the extensions implement similar functionality, most of those are implemented inside a common component, the IDE-backend, also known as Moses, that is executed in the background.
This service exposes a REST API, described in Swagger/OpenAPI2.0 format. By default, the service is exposed on port 5000 and accepts connections only from local clients, so it's not possible to connect to it from a different machine.
The port number can be configured in the extension setting on the different IDEs.
If you have a firewall or an antivirus system on your machine (this happens more frequently on Windows systems), it may prompt you to enable connections to moses/moses.exe on port 5000. You need to enable this to be able to use the extensions. A failure to connect to the backend will prevent the extensions from working and you'll get an error as soon as they are loaded.
Connection to local Docker
The backend needs to access the local Docker daemon to perform build and other operations. This uses a filesystem socket on Linux (you have to ensure that your user is able to access it, this usually means being part of the
docker group). On Docker Desktop for Windows, this should be enabled by default.
The Docker service may take some time to start at boot or may be restarted after an update. In this case, you may get an error when you start the IDE but the service will keep retrying and the issue will be solved without user intervention. You may also configure Docker to not start at boot. In this case, you have to remember to start it before opening the IDE.
The IDE backend collects information using an SSH connection to port 22 on the device (this is the default port for SSH on Torizon). It is an outbound connection and usually not blocked by firewalls unless they are explicitly configured to do so. Also, information collected by the Docker instance running on the device is tunneled via SSH, not requiring the use of an additional port.
The backend uses the device hostname that you specified during detection or modified later in the UI. You may also use an IP address if you don't have hostname resolution on your network. If you use the ".local" suffix after your hostname, the system will use mDNS to solve the name. It may happen that changes in network configuration or enablement of additional connections (ex: a VPN) change the way hostnames are solved by your system. In this case, adding ".local" to the hostname or using an IP may help fix the problem.
The connection is authenticated using a private/public key pair. Those keys are generated during device detection and the public key is stored on the client under
/home/<username>/.ssh/authorized_keys. This file is deleted when the OS is reinstalled, so, after you updated Torizon on your modules by re-flashing a new release, the IDE extension may no longer be able to connect to it. This can be fixed by detecting the device again in the IDE extension.
The system does not store fingerprints of the connected devices, which avoids issues if a device is re-installed or moved to an IP address used by another device. Fingerprint information stored by another SSH client, used for manual connections to the device, on the other side, can be an issue and prevent you from connecting after you re-flashed your device or use an IP that was previously assigned to a different device. If you can't connect to your device, running the local ssh client manually may help detect this kind of issue.
Multicast DNS (mDNS) is designed to support name resolution on small networks that don't have a dedicated name server (DNS). It works broadcasting UDP packets on port 5353, checking if a device recognizes its name and provides back the right IP. The IDE backend uses mDNS if a hostname can't be resolved using a standard DNS query. mDNS packets are broadcasted on the main network connection, if you have multiple networks names of devices on secondary networks may not be solved. In this case, you'll have to use a fixed IP address.
IDE-backed in containers (VSCode)
When developing C/C++ applications in VSCode the extension and IDE backend run inside a container. This is done to allow a full Linux development environment to run on Windows and to have a toolchain that does not rely on the underlying distribution when running on a Linux host. In this case, a different instance of the IDE backend is executed and it will try ports from 5001 up (one port for each VSCode instance running). Since the SDK container has host networking enabled this port may be accessible also from clients on the host OS and may trigger some blocking mechanism on firewalls/antivirus.
Application build (VS2019 only)
In VS2019 the system is configured to build the code on a "remote" machine that is actually a container running on the developer's PC and exposing SSH connectivity. Since multiple instances of SDK containers can be running at the same time the port used to expose SSH from the container is not fixed, it will be assigned by docker. Usually, connections to local containers are not blocked by firewalls or antivirus, but if you get an error connecting to a remote machine when building your code you may need to verify your configuration.
By default, the IDE-backend will deploy the container images using SSH, in the same way used to collect monitoring information or control the remote docker daemon. This will ensure that, as long as SSH is enabled and supported, no additional steps are needed to deploy applications to devices. This solution requires no additional configuration effort in addition to what is needed for basic connectivity and should work out of the box on most developers' PCs. On another hand, this will require that the whole container image is transferred each time it is rebuilt. Deployment will happen every time some configuration changes, triggering the rebuild of the image.
To improve the deployment speed of the image users can configure usage of a local or shared docker registry. This will deploy only part of the image that has been changed by a rebuild, decreasing download time.
When running the local registry the backend will run a docker container providing the registry service. This container will expose its services on a system-assigned port (not fixed) and clients will be instructed to connect to that port for downloads. This, of course, may generate issues if your firewall/antivirus is blocking incoming connections by default. You should enable them, at least for the devices you plan to use. A shared registry can run on the same machine or on a local server, in this case configuring and running it it's up to the user. You will also have to ensure that both the developer machines and the target devices are able to connect to the registry.
Application deployment (VS2019)
In VS2019 the application is deployed using
rsync from the SDK container to the container running on the target device. The IDE-backend will ensure that the device hostname is correctly solved also inside the container (provided that it can be solved from the developer OS) and the target container will expose an SSH server on a system-assigned port.
The connection is outbound, firewalls or antiviruses usually don't block this type of connection, but you may have to check in case you have issues.
Application deployment (VSCode)
VSCode deploys the application from the developer's PC to the target (in a subfolder of the user home) using
rsync and the same SSH connectivity used for the other features.
The different tools/languages use different ports/protocols to connect to the remote debugger. Usually, debug connections are outbound from the point of view of the developer's machine and this should not be an issue for firewalls or antiviruses.
The debugger will connect to the container using SSH on a system-assigned port.
VSCode will run
gdb inside a local container and connect to gdb-server running in a container. gdb-server will use internal port 6502, but this will be exposed outside the container using a system-assigned port, unless networkmode for the target container is configured as "host", in this case, port 6502 will be used always.
The .NET debugger will use SSH to connect to the application container (exposing internal port 2222 on a system-assigned port, unless networkmode is configured to host) and tunnel connection to the remote debugger over it.
The Python connection will use debugpy. The debugger will accept connections on internal port 6502, exposed to a system-assigned port (unless networkmode is configured as host). The connection will use a custom protocol.