Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release
or cat /etc/issue
on the board.
Remember that you can always refer to the Torizon Documentation, there you can find a lot of relevant articles that might help you in the application development.
Toradex offers a VS Code extension to help users to develop, deploy, and debug applications on TorizonCore. The following programming languages are currently supported:
This article demonstrates how to set up the recommended configuration comprising:
This article complies to the Typographic Conventions for Torizon Documentation.
Attention: On Ubuntu 22.04 it is necessary to manually install libssl1.1, by following the commands below
Note: Make sure that the board and development computers are on the same network.
The latest versions of the Toradex Torizon Support extension can be found on the Visual Studio Code marketplace, in two versions:
Click on the Extensions
button in Visual Studio Code as shown in the image below and search for Toradex Torizon Support, then select the option you prefer among the ones presented above:
Verify that the extension has been enabled:
Choose your development PC OS from the tabs below:
Warning: Required for .NET Core applications only
Download the latest .NET Core SDK on Microsoft Official Website and follow the setup installation. To check if everything went well, open up a command prompt, and run the following command:
$ dotnet
If the installation was successful, you should see the .NET options on the command prompt.
To obtain the Linux subsystem, please refer to the Microsoft instructions. After following all the steps, reboot your machine.
Warning: WSL2 requires Windows 10, updated to version 2004 (also known as the Windows 10 May 2020 Update) or higher.
WSL Setup
You may want to install Windows Terminal from the Microsoft Store to improve your experience using wsl.
Open the Microsoft Store and install a distro. We recommend Ubuntu 20.04 LTS. When the process ends, open CMD
and run the following command:
$ wsl
It will ask for your username
and password
, write it. After setting up your credentials, run the command below to see some information about the distro:
$ wslfetch
After evaluating the Windows Subsystem for Linux works, install rsync
and ssh
from the Linux prompt:
$ sudo apt-get update && sudo apt-get install rsync ssh
Check if Ubuntu 20.04 LTS is the default wsl distro on your system by running the command below:
$ wsl -l -v
Your default distro is represented by the *. If your output is similar to the one above (docker-desktop or another distro being the default), make Ubuntu default distribution by typing the following command:
$ wsl -s Ubuntu-20.04
The Torizon IDE Extension is designed to be used with a Visual Studio Code running locally on Windows and not inside WSL. Therefore, installing Visual Studio Code Torizon IDE Extension inside WSL may result in unexpected bugs and behaviors from the extension.
The image below shows how VS Code Extensions Manager looks like when VS Code is running inside WSL. It is possible to observe that it has two places where the Torizon IDE Extension can be installed, local and WSL. If the extension is installed the WSL location unexpected bugs and behaviors may happen. If it has just one location it means that VS Code is running on the Windows machine, so the extenstion can be correctly installed from there.
Warning: Required for .NET Core applications only
Follow the .NET Microsoft Documentation to install it on Linux, and make sure you select the correct distribution on the left.
You can test if everything went well by running the following command:
$ dotnet --info
To debug and test our application, we need a device to deploy it. Go to the Torizon tab and see that your "devices" view is empty. Click on Add Device
and choose to either add the device using the Network
connection or over the Serial Port
. The end result will be the same, regardless of the method chosen:
.local
. If you don't have either, then learn how to find your IP or learn how to find your hostname or try registering the device using the Serial Port
method./dev/ttyUSBx
on Linux or COMx
on Windows.Either way, you will be prompted to enter a valid username and password that is on your Torizon device (remember that the default is torizon
and torizon
, but you should change the password on the first boot). Once you type in the credentials, the device will reboot. The device will be listed in the Devices
view of the Torizon tab and, as soon as the reboot is complete, you'll be able to see some device info. You should see some dialog in the Terminal
output of VS code that shows whether the connection was a success or not.
See how both methods work:
Adding a Torizon Device
If you prefer to use the VS Code command palette, open it by pressing F1
or Ctrl + Shift + P
, then use the following commands with the same instructions above:
Torizon: Detect device via network connection
Torizon: Detect device via serial port connection
Please make sure to have followed the instructions for installing the WSL2 if you are running Windows.
Connecting to the board via SSH is made easy with the extension.
Read the section Using the Visual Studio Code Extension for Torizon from the SSH article to learn how.
The creation and setup of a new project is dependent of the programming language you choose. Therefore, we expect that you follow one of the articles below, since they are the entry point for those languages:
After you finish following them through, come back to the current article and proceed to the next sections, which are again common to all programming languages.
Attention: on Windows, make sure to disable buildkit as explained on Configure Build Environment for Torizon Containers, otherwise, build errors may happen.
The deploy and debug process, from your perspective, is common to all supported languages. Under the hood, each language has its own debugging setup, but that is made transparent.
Open your source-code files and click on the left side of a line number to add a breakpoint. If you right-click, you can choose to add a conditional breakpoint or a logpoint.
If you have issues adding breakpoints, enable the use of breakpoints everywhere. Go to File --> Preferences --> Settings and search for Debug: Allow Breakpoints Everywhere
, then tick the box Allow setting breakpoints in any file
.
To start the process, all you have to do is press F5
. Alternatively, you can select the menu Run and click on Start Debugging
. A third method would be to open the command palette and type Debug: Start Debugging
. The extension will build your application along with the debug container, deploy them to the board, and start the debugging session. You may be prompted to select a device if you have more than one added to the extension.
If you make changes to your application source-code and run the process again, only the application will be redeployed, making the process faster. On the other hand, if you add development or runtime packages, update the project configuration or add any other resources that impact the containers, they will be rebuilt and the process will take a bit longer for that specific run.
If your application has an infinite loop, you can simply stop the debugger to kill it.
Vscode Debug Session in C, Python and .NET
Most problems will be printed to the Terminal, Problems, Output and Debug Console tabs of VS Code. You can open them by going to the View
menu, or with the shortcut Ctrl + Shift + ´
.
In the Output, you can choose the Torizon
output to get more information about the build and debug process, and more:
In the Terminal, you can choose some terminals with useful information, depending on the project you are running, etc. The Torizon IDE backend process
will always be available, and as you run commands on the command palette, you can find other terminals with the name of the tasks. A few examples are Task - deploy
and the Torizon - Container Application Output
:
In the Debug, you can see and search for specific debug output:
Docker-compose is used to define and run multi-container applications, and on our Visual Studio Extension is no different, there are two scenarios:
torizon/weston
is generated on the /appconfig_0/work/
folder on the first time you build the application:Attention: Do not edit the autogenerated docker-compose.yml.debug file! It is overridden by the Torizon extension every time you rebuild your project, and therefore your changes will be lost. Keep on reading to learn how to properly add your own docker-compose.yml to a Torizon project.
/appconfig_0/work/
folder, in order to configure your project, you need to create the docker-compose file as exemplified in the next paragraph.For the two scenarios above, let's suppose that you want to add an environment variable to Weston or, do you need to start a container after any other container, as explained and exemplified on the Using Multiple Containers with TorizonCore article, how could you do that?
It's simple, just create a docker-compose.yml (for graphical projects, you might want to copy the docker-compose.yml.debug
and then add your changes) file on the root of appconfig_0
and apply it on the configurations view of the Torizon extension, just like in the video below:
Note: the video creates the file inside appconfig_0/work
by mistake. A rebuild of the project may delete the contents inside appconfig_0/work
. Stick to the instruction of adding the file directly on appconfig_0
so it is persistent.
Creating and using your own docker-compose file
Attention: on Windows, make sure to disable buildkit as explained on Configure Build Environment for Torizon Containers, otherwise, build errors may happen.
The deploy and release commands are common to all supported languages. They consist of tasks to:
To build a release container, on the VS Code command palette, run Torizon: Build release container for the application
. It may take several minutes.
Please note that building a release container is not related to switching between debug
and release
configuration, if the language supports both. If you build a release container while in debug
mode, the application deployed will have the debug symbols and everything else that is defined by the debug
configuration.
In addition, you can add a custom property named tag
to the project. You must use a regular Docker tag and the extension will tag your release container image accordingly, for example, my-user/my-container:my-version
.
To deploy a release container to the board, on the VS Code command palette, run Torizon: Deploy release container
. It will deploy to the board the image built in the previous step.
On the VS Code command palette, run Torizon: Run/restart release container
. It will run on the board the image deployed in the previous step.
Before the application container starts, all other containers described in the Docker Compose files appconfig_0/work/docker-compose.yml
, appconfig_0/work/docker-compose.yml.debug
or appconfig_0/work/docker-compose.yml.release
, depending on the present project configuration, will also be started on the board by the IDE.
Building, Deploying and Running a Release Container
This is a feature available on prime-tiers of the Torizon Platform Services. If you want to learn more about the Torizon Platform Services pricing and plans, please contact us.
Request access to evaluate the Torizon Platform Services premium features |
At some point in your development, you will need to push the container to a registry and then to one or many boards. You can learn more about it on Deploying Container Images to TorizonCore. In this section, you will learn how to deploy the images to a registry and the Torizon Platform Services, so they are ready to be deployed to many devices as a remote update.
Before deploying, build a release container as described in the previous steps.
Download a credentials.zip
file from your account on the Torizon Platform Services account and save it on your PC. You can find it under My Account > Download Credentials.
In the command palette, run Torizon: publish application to OTA server
. You will be prompted to provide some data:
major.minor.build
format, like 1.0.0
.credentials.zip
file.If the operation completes successfully, the extension will ask if you want to safely store your credentials on the local machine. This will avoid prompting you for username, password, and path of credentials file in the future. You may remove those stored credentials by running the Torizon: delete security credentials for the application
command.
The container image tag and OTA package name are stored in the application's configuration, so you won't have to re-insert them for future upload, but you can change them in the project properties.
On the next execution of the publish command, the package version number will be automatically incremented if you keep it in the major.minor.build format.
Now you can see your new package and deploy it to your devices using the Torizon OTA Web Interface.
Publish the container image to the Torizon Platform Services
Tip: you can also push images to repositories other than Docker Hub. In the tag
property you can specify the registry, as long as you use a compatible Docker tag. If, for instance, you have a local registry that is not protected with credentials, you can leave the fields username
and password
empty when prompted by the push command.
Warning: the previous command Deploy a Release Container Image to the Torizon Platform Services
implicitly executes this step. If you chose to use it, you can skip this section.
At some point in your development, you will need to push the container to a registry. You can learn more about it on Deploying Container Images to TorizonCore.
Before pushing the container, build a release container as described in the steps above.
Push the release container by opening the command palette and running Torizon: Push application container to a docker registry
. It will ask you to add a tag if you haven't done it before, and you must use a regular Docker tag. If you are using Docker Hub, make sure that it begins with your user name, because your username is also your namespace). The extension will also ask you to enter the registry username and password.
Pushing a Container Image to Docker Hub
Tip: you can also push images to repositories other than Docker Hub. In the tag
property you can specify the registry, as long as you use a compatible Docker tag. If, for instance, you have a local registry that is not protected with credentials, you can leave the fields username
and password
empty when prompted by the push command.
Additional commands to generate a command-line to run the application without the extension, and to generate a Docker Compose file, useful in many scenarios such as deploying the application through the TorizonCore Builder Tool or Torizon OTA, are explained in this section. You may find it useful to read the conceptual article Deploying Container Images to TorizonCore.
Since the IDE Extension builds a container image for your application under the hood, that means that there is a Dockerfile behind it somewhere. There are actually two Dockerfiles, one for debug and the other for release. We advise you not modify it manually, but it may be useful to check for debugging corner cases, or simply if you want to keep it for any reason.
The Dockerfiles are available under appconfig_0/work/<project name>/
and they are named Dockerfile.debug
and Dockerfile.release
. If any of them is missing that is because you haven't yet followed through the previous sections Deploy and Debug and Deploy and Release from this article.
For C/C++, additional Dockerfile_SDK.debug
and Dockerfile_SDK.release
may be available. Those are the Dockerfiles that create the SDK containers, as explained on C/C++ Development and Debugging on TorizonCore Using Visual Studio Code.
Create and Open the Release and Debug Dockerfiles
The IDE extension runs containers on the board. In some cases, you may need to know how to run the containers manually, either because you are done with development or for some other reason you want to run it outside the IDE. On Torizon, currently, that means:
docker run
commands, from the command-line or Portainer, as explained in the article Run and Manage Containers with Portainer and the Command-line on Torizon.docker-compose
command, with a Docker Compose file as the descriptor, as explained in the article Using Multiple Containers with TorizonCore. This is preferred over docker run
because the Docker Compose file automatically documents how to bring up multiple containers, their interactions, shared networks, etc.This section explains how to generate a docker run
command from the IDE, and the next section explains how to generate a Docker Compose file.
Open the command palette and run Torizon: export docker command line
, select if you want to export it for debug
or release
. The docker command-line will be printed in the Torizon output tab.
Export the Docker Run Command Lines for Debug and Release
Note: an easier, fully integrated command for deploying applications directly to the Torizon Platform Services is described in the section Deploy a Release Container Image to the Torizon Platform Services. You don't need to export the Docker Compose file and deploy it manually to the platform.
Tip: this is very different from the Docker Compose file presented on Deploy and Debug - Configure Multi Container Services with Docker Compose. The purpose of the former is to configure project dependencies using a Compose file to achieve that goal. The purpose of this section is to generate a final Compose file to easily run your project without the IDE Extension, being Torizon OTA one of the main use cases.
Open the command palette and run Torizon: export docker-compose file
, select if you want to export it for debug
or release
, and a text editor with the file content will open. Notice that you must save the file.
This is a very useful command, because it bridges the IDE Extension to the TorizonCore Builder Tool and Torizon OTA. With them you can:
Get Started With the Torizon Platform
Export Docker Compose Files for Debug and Release then Upload to Torizon OTA
IDs and keys are automatically generated by the extension. Before sharing it with others or publishing it to a public repository, for instance on GitHub or similar, those IDs and keys should be removed to avoid that all forks of a project will have the same container names and keys.
Open the command palette and run Torizon: Remove IDs and keys from application
. A warning will show up explaining that you will need to close and re-open the project before being able to build, deploy and debug the app again. Accept it and add your source-code to your version control system (such as Git).
On Visual Studio Code, executing commands is easy: you need to press F1
to open the command palette then type the command you want. It is easy to find all commands inside VS Code, you just have to go to the Extensions
tab, select the Torizon extension, and click on the Feature Contributions
tab:
Find Extension Commands
Now that you have the extension set up, choose what you want to do next.
You can use release images for production programming. There are two phases and tools:
Get Started With the Torizon Platform
Visual Studio Code related-webinars that you can watch on-demand.
Debian Containers for Torizon are subject to updates, including major updates to newer versions of Debian. Learn more about it, including how to update your VS Code project:
Debian Containers for Torizon are subject to updates, including major updates to newer versions of Debian. Learn more about it, including how to update your VS Code project:
Toradex offers a VS Code extension to help users to develop, deploy, and debug applications on TorizonCore. The following programming languages are currently supported:
This article demonstrates how to set up the recommended configuration comprising:
This article complies to the Typographic Conventions for Torizon Documentation.
Development Computer with
One of the OS below:
Toradex Computer on Module (CoM) with TorizonCore installed.
Note: Make sure that the board and development computers are on the same network.
The latest versions of the Toradex Torizon Support extension can be found on the Visual Studio Code marketplace, in two versions:
Click on the Extensions
button in Visual Studio Code as shown in the image below and search for Toradex Torizon Support, then select the option you prefer among the ones presented above:
Verify that the extension has been enabled:
Choose your development PC OS from the tabs below:
Warning: Required for .NET Core applications only
Download the latest .NET Core SDK on Microsoft Official Website and follow the setup installation. To check if everything went well, open up a command prompt, and run the following command:
$ dotnet
If the installation was successful, you should see the .NET options on the command prompt.
To obtain the Linux subsystem, please refer to the Microsoft instructions. After following all the steps, reboot your machine.
Warning: WSL2 requires Windows 10, updated to version 2004 (also known as the Windows 10 May 2020 Update) or higher.
Open the Microsoft Store and install a distro. We recommend Ubuntu 18.04 LTS. When the process ends, open CMD
and run the following command:
$ wsl
It will ask for your username
and password
, write it, and re-run the command to see the following output:
After evaluating the Windows Subsystem for Linux works, install rsync
and ssh
from the Linux prompt:
$ sudo apt-get update && sudo apt-get install rsync ssh
Warning: Required for .NET Core applications only
Follow the .NET Microsoft Documentation to install it on Linux, and make sure you select the correct distribution on the left.
You can test if everything went well by running the following command:
$ dotnet --info
The VS Code extension needs ARM emulation mode enabled through binfmt. To allow it, press F1 and type "Torizon: Enable ARM emulation for Docker containers":
Click on continue in the following window:
If everything goes well, you should see the ARM emulation enabled
message in your Visual Studio Code.
To debug and test our application, we need a device to deploy it. Open Visual Studio Code and press F1 to open the command bar, then you can run one of two commands below to add a device connected over the network or over serial.
The command torizon.detectSerialDevice
will add a serial connection to a Torizon device. The interface will prompt to specify the port on your development PC connected to the device over serial.
The command torizon.detectNetworkDevice
will add a network connection to your Torizon device. The interface will request to specify the IP address of your Torizon device. Just make sure that your SoM is on the same network as your development PC, and your PC can reach this address.
Either way, you will then be prompted to enter a valid username and password that is on your Torizon device; this will make it briefly reboot. You should see some dialog in the Terminal
output of the VS code that shows whether the connection was a success or not. Also, if you’ve already created a Torizon Project, then the device will be listed via the Torizon extension sidebar menu.
Expected Result:
On Visual Studio Code, executing command is easy: you need to press F1 to open the command bar then type the command you want. Here is a list with every command and its respective action and category
Command | Action | Category |
---|---|---|
torizon.createPythonApp | Create Python Application | Torizon/Python |
torizon.createDotNetCoreApp | Create .NET Core Application | Torizon/.NET |
torizon.createAspDotNetCoreApp | Create ASP.NET Application | Torizon/.NET |
torizon.detectSerialDevice | Detect device via serial port connection | Torizon |
torizon.detectNetworkDevice | Detect device via network connection | Torizon |
torizon.deleteDevice | Remove device from device list | Torizon |
torizon.selectDevice | Select default deployment device | Torizon |
torizon.buildPythonReleaseContainer | Build release container for Python application | Torizon/Python |
torizon.enableARMEmulation | Enable ARM emulation for docker containers | Torizon |
torizon.deployReleaseContainer | Deploy release container | Torizon |
torizon.runReleaseContainer | Run/restart release container | Torizon |
torizon.updateContainers | Download/update base containers | Torizon |
torizon.buildDotNetReleaseContainer | Build release container for .NET application | Torizon/.NET |
config.yaml
in the appconfig_0 folder. See Moses IDE Backend for reference.