Torizon 5.0.0

Introduction

Toradex offers a VS Code extension to help users to develop, deploy, and debug applications on TorizonCore. The following programming languages are currently supported:

• C/C++
• Python 3.9
• .NET Core Framework 3.1 (EOL December 03, 2022), 5.0 (EOL May 08, 2022) and 6.0 (LTS)

This article demonstrates how to set up the recommended configuration comprising:

• Visual Studio Extension for Torizon
• .NET Code SDK (Required for .NET Core applications only)
• Windows Subsystem for Linux - WSL2 (Only for Windows host machine )

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

• Toradex Computer on Module (CoM) with TorizonCore installed.
• Development Computer with:
  • Build Environment for Torizon Containers set up
  • Visual Studio Code
  • Know how to open and run commands on the VS Code command palette
  • One of the OS below:
    • Windows 10 version 2004 (a.k.a. May 2020 update) or newer
    • Linux (it was validated using Ubuntu 18.04 and Ubuntu 20.04)

Attention: On Ubuntu 22.04 it is necessary to manually install libssl1.1, by following the commands below

$ wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_1.1.1l-1ubuntu1.6_amd64.deb

$ sudo apt install ./libssl1.1_1.1.1l-1ubuntu1.6_amd64.deb

Note: Make sure that the board and development computers are on the same network.

Install the Visual Studio Code Extension for Torizon

The latest versions of the Toradex Torizon Support extension can be found on the Visual Studio Code marketplace, in two versions:

• Toradex Torizon Support: stable version, with a slower release cycle.
• Toradex Torizon Support (Early Access): preview version, always gets the latest features but is not as thoroughly tested as the stable release.

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:

• 

  Toradex Torizon Support Extension for Visual Studio Code

Verify that the extension has been enabled:

• 

  Torizon extension

Choose your development PC OS from the tabs below:

• Windows
• Linux

$ dotnet

$ wsl

$ wslfetch

$ sudo apt-get update && sudo apt-get install rsync ssh

$ wsl -l -v

$ wsl -s Ubuntu-20.04

$ dotnet --info

.NET Core SDK (reflecting any global.json):
Version: 3.1.102
Commit: 573d158fea

Runtime Environment:
OS Name: ubuntu
OS Version: 18.04
OS Platform: Linux
RID: ubuntu.18.04-x64
Base Path: /usr/share/dotnet/sdk/3.1.102/

Host (useful for support):
Version: 3.1.2
Commit: 916b5cba26

.NET Core SDKs installed:
3.1.102 [/usr/share/dotnet/sdk]

.NET Core runtimes installed:
Microsoft.AspNetCore.App 3.1.2 [/usr/share/dotnet/shared/Microsoft.AspNetCore.App]
Microsoft.NETCore.App 3.1.2 [/usr/share/dotnet/shared/Microsoft.NETCore.App]

To install additional .NET Core runtimes or SDKs:
https://aka.ms/dotnet-download

Add Target Device Connection In Visual Studio Code

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:

• Network: you must make sure that your SoM is on the same network as your development PC, and your PC can reach this address. You must know in advance the IP address or the hostname. If using the hostname, make sure to add the suffix .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.
• Serial Port: you must have access to the serial port and know what is the corresponding device, usually /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:

• Network: Torizon: Detect device via network connection
• Serial Port: Torizon: Detect device via serial port connection

• 

  Adding a Torizon device using the command palette

Setup of SSH 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.

Create and Configure a Project

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:

• .NET Core Development and Debugging on Torizon Using Visual Studio Code
• Python Development and Debugging on TorizonCore Using Visual Studio Code
• C/C++ Development and Debugging on TorizonCore Using Visual Studio Code

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.

Deploy and Debug

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.

Add Breakpoints

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.

Start Debugging

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

Get Debug Information in the Right Places

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 + ´.

• 

  VS Code Terminal, Output and Debug Tabs

In the Output, you can choose the Torizon output to get more information about the build and debug process, and more:

• 

  VS Code Torizon Output

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:

• 

  VS Code Terminals

In the Debug, you can see and search for specific debug output:

• 

  VS Code Debug

Configure Multi Container Services with Docker Compose

Docker-compose is used to define and run multi-container applications, and on our Visual Studio Extension is no different, there are two scenarios:

• On graphical projects, such as a Python Qt QML Application, a docker-compose.yml.debug file for 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.

• On headless applications, such as a Python Console Application, there is no docker-compose.yml.debug file on the /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

Deploy and Release

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:

• Build images
• Deploy to the board
• Run images on the board
• Deploy to the Torizon Platform Services
• Push images to a container registry

Build Release Container Image

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.

Deploy Release Container Image

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.

Run Release Container Image

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

Deploy a Release Container Image to the Torizon Platform Services

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:

• Tag: 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.
• Package name: provide a package name for the Torizon Platform Services.
• Version: provide a version for your package. You are advised to use a major.minor.build format, like 1.0.0.
• Account credentials: valid account and password for Docker Hub or your custom registry.
• Torizon Platform credentials: Provide the path for the 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.

Push a Release Container Image to a Registry

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.

Beyond the Release and Production Programming

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.

Generate a Dockerfile for the Application

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

Generate a Docker Command to Run the Application

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:

• Either running 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.
• Or running a 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

Generate a Docker Compose File to Deploy the Application With Torizon OTA

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:

• Create a custom TorizonCore image with pre-provisioned using the TorizonCore Builder tool.
• Deploy frequent application updates from the Torizon OTA Web Interface to your device fleets in the field.

Get Started With the Torizon Platform

• Export Docker Compose Files for Debug and Release then Upload to Torizon OTA

Remove IDs and Keys Before Publishing Source-code to a Public Repository

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).

Visual Studio Code Extension Commands

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

Next Steps

Now that you have the extension set up, choose what you want to do next.

Application Development for Torizon

• Torizon Best Practices Guide
• .NET Core Development and Debugging on Torizon Using Visual Studio Code
• Python Development and Debugging on TorizonCore Using Visual Studio Code
• C/C++ Development and Debugging on TorizonCore Using Visual Studio Code
• Qt C++ Application Development on Torizon Using Visual Studio Code
• How to Import a C/C++ Application to Torizon
• How to build a GUI with Qt for Python and TorizonCore
• How to Build a GUI with ASP.NET Core and Blazor for TorizonCore
• Browse for other related articles in the Torizon Documentation

Production Programming

You can use release images for production programming. There are two phases and tools:

• TorizonCore Builder Tool: use this tool to deploy container images to a TorizonCore custom binary image, then install it on your computer on modules using the Toradex Easy Installer.
• Torizon OTA: use this tool to deploy and update containers remotely to fleets of devices.

Get Started With the Torizon Platform

Webinars

Visual Studio Code related-webinars that you can watch on-demand.

Zero to Hero: Visual Studio Code for Embedded Linux Development

Update to a Newer Debian Container Version

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:

• How to Update an Existing VS Code Project to a Newer Debian Container Version