Article updated
at 31 May 2022
This document provides generic help for issues that may happen during the usage of our extensions.
Check this document before opening a new issue on our community and please report any issue that you don't manage to fix or any unexpected behavior you experience by applying the suggestions of this document, so we improve it and fix potential undiscovered issues in the software.
Currently, we provide a Visual Studio Extension For Torizon (supporting C/C++ applications) and a Visual Studio Code Extension for Torizon (supporting C/C++, Python, and C#), the latter running on Windows and Linux. Some of the suggestions may apply to one specific extension or a specific host OS. Otherwise explicitly stated, the information should work across all the different extensions/language and OS combinations.
This article complies to the Typographic Conventions for the Toradex Documentation.
- It is a good practice to use the latest release of the extensions, as they may have bug fixes and improvements that may fix your issue.
- Keep in mind that the article Torizon Frequently Asked Questions (FAQ) may have additional answers to questions not related to the IDE Extensions.
-
Vscodeextbar
- Please check our installation guides for VS2019 and Visual Studio Code to ensure that you installed all the prerequisites.
- Both extensions can be installed from the extension-management UI of VS2019 (extensions dialog) and VSCode (Extensions activity bar). The installation is performed automatically by the IDE and may require a restart of the development environment. A restart may be required also after an update of the extension.
- Each extension is provided in two versions. A stable release, with fully tested features and an early access one that provides all the latest features and bug fixes. The stable channel is updated less frequently and if you need a specific feature or bugfix this may be available in the early access channel weeks before it's published also on the stable one. Projects created with the stable version can be opened by the early access one, the opposite may not always be granted.
- It's not possible to install both stable and early access releases on the same machine. Every time you want/need to move between the two versions you have to install the version you are currently using and then install the other one.
- In Visual Studio Code you may want to disable the Torizon extension in workspaces that don't use it or, vice-versa, enable it only in workspaces that require it. If you choose to disable it by default some commands may not be accessible unless you re-enable it.
Devices can be detected in two ways:
- via serial port
- via SSH connection
If detection of a serial device fails check the following things:
- Verify that the device is actually connected to the serial port you use for detection. Turn it on and try to connect via the terminal at 115200 baud 8 bits, one stop bit, and no-parity. If this does not work, check that the device is correctly configured for serial connection (on some EVBs you can use jumpers to choose between RS-232 connector and USB to UART adapter, other boards may have two or more USB device ports, one used for serial console and the other for USB-device features like mass-storage or network).
- Try to reboot your device before attempting detection. The detection process tries to handle different scenarios, including users already logged in, but may fail if you have an application using the console on the client. Rebooting should lead to the device waiting for a login on the serial console.
- If you rebooted your device, wait at least 60'' before attempting detection. This will ensure that the device is fully booted and ready to accept a login request.
- If the tool reports that detection has been completed and the target device reboots, but then you don't see any information about images, containers, etc. in the UI then move to the next session (issues collecting information from devices). Detection has been successful, but there are issues connecting to your device over the network.
If detection fails when attempting it via SSH you may check the following things:
- Try to ping the device using the same name you used for detection, if this does not work and you haven't used an IP address it may be possible that your PC can't solve the device name. Try to append ".local" to the hostname to force usage of mDNS or use the device's IP address directly. Once you have an address you can ping you can try using it for detection.
- If you had to use IP address for detection, consider the idea of fixing it on the router or the server that assigns them, otherwise, you may not be able to reconnect after a reboot or when IPs are re-assigned by your network DHCP server.
- Use your ssh client to attempt a connection to the device, this may help understanding if username/password are correct or if something blocks connections to port 22 on the client. If the ssh client works, check that you use your password and that no firewall is preventing connection attempts from the ide-backend process (moses on Linux, moses.exe on Windows).
- If you have a module that is still in pre-production and has been released only recently consider the fact that only an early-access version of the IDE extension may be able to successfully identify it.
- If detection does not work, please check the "Troubleshooting guide for the IDE extensions" chapter and open an issue in our community.
Once a device is connected you should be able to see it in the device list inside your IDE and to interact with it.
-
Nonworkingdevices
If you don't see up to date information about your device you may check the following issues:
- Check that the device is powered-up and connected to the network.
- If other devices are offline then refreshing the list of devices may take some time and information may appear after a couple of minutes since you opened the IDE.
- If you re-installed Torizon on your target device the keys used for the SSH connections that the IDE tools use to collect information have been erased. You can restore them by detecting the device again. You don't need to remove it before re-attempting the detection, just re-execute the detect operation and wait until your device has completed its reboot. If you used the OS ssh client to connect to the device and saved its ssh key fingerprint, that may have been changed too and prevented from connecting until cleaned up.
- If you performed some operations (ex: starting a container, downloading a container image) on the device and what you see in the device status does not match your expectation, please remember that this information isn't refreshed automatically. You can refresh it manually when needed.
- If you get connection failures, please check that you don't have a firewall blocking outbound connections to port 22 on the device.
- If you use a hostname to connect to your device and this stops working, it may be due to changes in your network configuration (ex: activating a VPN). Appending ".local" to the device name will use mDNS to resolve the name and should work on local networks, otherwise, you can use the device IP.
- If you use IP to connect to your device, please check that it hasn't changed after rebooting the device or the DHCP server.
In VS2019 the template for Torizon applications is available in the new project wizard.
- If you can't find it, please check that the extension has been installed correctly.
In Visual Studio Code you can create new applications by invoking the command palette.
-
Commandpalette
- If the command isn't there, please check that the extension has been installed. Check also that initialization has been completed (you can see a message in the status bar at the bottom of VSCode windows). Torizon extension initializes in the background, to not slow down VSCode startup, but this means that it may take a few seconds to have all the commands in place after the tool has been started.
- If you use VSCode to develop C/C++ applications you may have your current workspace open inside a container, this prevents the extension from creating new projects and you'll get an error message if you try to do this. Just select "Close remote connection" from the file menu and retry the operation.
When you are building a Torizon application you actually build your application code (unless you are using Python) and then a container ready to "host" it when running on the device.
Issues during code build are not different from those you may experience building code in a standard Linux environment, but there are still some things you need to consider:
- You are building a Linux application for a different architecture. The templates we provide already configure the right build environment, but this may not be true if you are trying to build an existing application or incorporate existing code inside your own app.
- Some optional build properties you may specify like
arg, env or preinstallcommands require a valid Dockerfile command that will be executed during the build. If you get syntax errors or other issues during the build container stage, please check those commands.
- Docker and some commands executed during container builds (ex: apt-get install) download contents from the internet, please check that your network doesn't have limitations in place that may block those downloads. This will usually lead to an error on the FROM statement (no access to docker hub) or running apt-get commands (no access to the Debian package feeds).
- Other properties like
extrapackages or appname are used inside existing Dockerfile commands and using invalid characters/syntax may lead to errors.
- Build commands for the target container are performed using emulation. ARM emulation is enabled by default when running the IDE extensions, but may not be enabled if you try to build your container by processing the generated Dockerfile via docker build. For this kind of build, we suggest using the Torizon IDE Backend Command-line Interface.
- If you use VS2019 you'll have to use ms-build to build your code. This is not a very commonly used build system on Linux and so porting existing code may require additional configuration of preprocessor defines and build options.
- In VS2019 the SDK container is used to build code and operations are executed over a local ssh connection. If you have issues running the SDK container please check that docker on your machine is configured to run Linux containers. Check also that antivirus/firewall configuration does not prevent local SSH connections, even on non-standard ports. This may prevent the execution of the build commands.
- The SDK container is used also in VSCode, but this doesn't leverage SSH. You only need to have docker and the remote-containers extension installed.
- If your C/C++ build fails because a header file is missing or a function cannot be found during linking, you may need to add some development packages to your SDK container. This can be done by adding them to the
devpackages property. If your package has an architecture-dependent version (and most do, as long as they contain native libs) you have to specify it in the package name. For example, you have to add libpng-dev:arm64 (or armhf) to your container and not just libpng-dev that will add files for the native (x64) toolchain or libpng that will add only runtime components.
- If you are using VS Code to build an existing code base, it may be that build reference additional tools on top of those already provided in the SDK container. If you have build instructions for Debian or Ubuntu you could probably find them listed there. Adding them to the
sdkpackages property and rebuilding your SDK may solve such an issue.
- Not all existing code bases are designed to be cross-compiled, check that your project uses a tool that supports cross-compilation (ex: CMake) or, at least, env variables like CC for the compiler and LD for the linker, otherwise it will try to invoke the native toolchain and fail.
- Some projects also invoke tests during the default build, while this is good practice in general, it's quite possible that those tests will fail when executed inside the SDK container since they may involve running non-x64 binaries and reference dynamic libraries built for a different architecture. You may consider skipping those tests during the build and running them on the target instead.
- If the build or publish tasks fail, please check that you have the right dotnet SDK installed and that dotnet (dotnet.exe on Windows) is in your PATH and can be invoked with no errors. Open a command prompt/terminal and type:
dotnet --version
- If you plan to use .NET 5 for your application, check that the version reported by the dotnet tool is at least 5.0.0. If it's older than that, please update your dotnet setup.
- If you add packages to the requirements.txt file those will be installed using python package manager (pip). Some packages may include C/C++ code that had to be built during installation, this may lead to issues since the target container does not include a toolchain. Adding the toolchain may solve the issue but will increase container size and build times. Consider using a Debian package instead (if that exists) or building native binaries in a separate step.
- Check that your device is connected to the network and reachable using the hostname/IP configured for it (you can see it in the device properties)
- By default deployment uses an ssh connection. If you can't see up-to-date information from the device, check the suggestion in the issues collecting information from devices part.
- If you configured deployment using a Docker registry running on your PC, as described in Visual Studio Code Extension for Torizon - Configure a Local Docker Registry (Optional) you may need to make sure that incoming connections to your machine are not blocked by a firewall. If you use a registry hosted on your LAN, check that both your PC and the device can access it.
- Check that you have enough free space on the target. Docker error messages in that situation may not be very clear. To recover some space you may connect to the device and run:
docker system prune
- When running the application in debug mode, binaries and data files of the application are transferred using
rsync. Check that rsync is installed on your system (for Windows users, this will be part of the Linux distribution installed for WSL)
- Debuggers also use network connections, so if your container and application are deployed but debugging does not start you may need to check (again) that firewalls are not blocking connections used by the debugger. The .NET debugger uses SSH, C/C++ debugging uses gdb-server, and Python debugging uses debugpy on ports that are assigned at runtime on the device.
- It may also happen that the debugger starts and quits immediately or is not able to start the debuggee. For those issues, please check the next chapter.
- One of the issues you may experience is that your application does not start or terminates immediately after startup. This may be due to some libraries missing in the runtime container. To check this you can first of all check container logs (documented in the "how to collect useful information about an issue" chapter).
- The ldd command may help discover missing dependencies. To use it you may first generate a Docker command line for your application, then add bash at the end of it, as the command. If you run that command line on your device after having deployed your container you will reach a command prompt. Then you can use ldd to list all the libraries linked by your app, including missing ones:
## cd /<yourappdir>
## ldd ./<yourappname>
- Searching packages.debian.org for the filename could help in finding the packages that you'll have to add to your
extrapackages configuration.
- If your application does not find some data/configuration files check that you mounted the right folders in the volume configuration (if those data are supposed to be permanently stored on the host device filesystem) and that the user you choose to run your application has enough access rights on those folders. If those files are supposed to be part of your application setup, please check that they are in your application folder under appconfig_?/work inside your code directory. Only files that are stored there are synchronized with the target during debugging or included in the container during the release build. Deploying them to the right place may require changes to your project/build files.
- If you access resources on the host system (shared directory, files, sockets, devices) check that your user from the container (can be root with UID 0 or torizon with UID 1000) has access to them.
- In addition to access rights, performing some operations may require some additional capabilities, described here. By default, Docker drops some capabilities from processes running in containers. You may re-enable them using the cap_add
extraproperty in configuration.
- If you don't need to access a single device but all devices matching some minor-major device IDs, you can use device_cgroup_rules to grant your container access to all the devices matching your type. See this page for more information about the syntax.
- If you suspect that your application does not run because of some access/capabilities limitations, you may try to run your container in privileged mode. You can do this by adding an entry named "privileged" to
extraparms and setting its value to true. Please be aware that running containers in privileged mode is a potential security issue, so use this option only to understand if the issue preventing your container/application from running may be related to access rights. Then remove the flag and try to apply a more specific fix, as explained in the Torizon Best Practices Guide.
If you reached this point probably the tips in this guide didn't help solve your issue. We are sorry for this, but if you report the problem on our community website we will try to investigate and solve it.
To help you in the analysis there are a few things you can do to help us reproduce and hopefully solve the issue.
- Please provide clear information about your hardware and software setup. This includes the module you are using, the OS and version/distribution on your development machine, the version of Torizon on your device, the version of ide extension (stable/early access).
- Provide also information about the kind of project you are working on. If it would be possible to share a minimal sample that reproduces the issue, that would be great.
- Please share any error message you get from the IDE, on the device console.
- Provide the output you get from the IDE backend process.
In Visual Studio Code this is one of the tabs inside the terminal window.
In VS2019 the IDE-backend process is executed in a separate console window. To see it, you have to enable an option inside the VS2019 configuration:
- You can get some additional information in some IDE panels.
For Visual Studio Code, check the "Torizon" tab of the Output panel, the debug console and the container output terminal may provide some useful information. Please attach the messages you see in those windows to your support request, that can help our tech support people in understanding and solving the issue.
In Visual Studio 2019 you can see the application output in the "Linux Console" tab, while the "Torizon build" and "Debug" panes of the output tab may provide useful information about the build/deploy and startup of your application.
-
Vs2019 Linux Console
-
Vs2019 Debug Output
