Skip to main content
Version: 5 LTS

Visual Studio Code Extension for Torizon

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:
danger

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

Install libssl1.1 manually (necessary for using the VS Code Extension for Torizon on Ubuntu 22.04)

Download the latest version of libssl1.1 from http://security.ubuntu.com/ubuntu/pool/main/o/openssl/. The package name should be the look like libssl1.1_<version>_amd64.deb in which <version> should be the latest one. At the time of writing, the latest package is libssl1.1_1.1.1f-1ubuntu2.16_amd64.deb.

$ wget http://security.ubuntu.com/ubuntu/pool/main/o/openssl/libssl1.1_<version>_amd64.deb

Then install it on the system:

$ sudo apt install ./libssl1.1_<version>_amd64.deb
info

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:

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:

Install the .Net Core SDK on Windows​

caution

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.

Expected result

Dotnet expected result

Install the Windows Subsystem for Linux (WSL2)​

To obtain the Linux subsystem, please refer to the Microsoft instructions. After following all the steps, reboot your machine.

caution

WSL2 requires Windows 10, updated to version 2004 (also known as the Windows 10 May 2020 Update) or higher.

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

Wsl 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

Check if Ubuntu 20.04 LTS is the default wsl distro on your system by running the command below:

$ wsl -l -v

wsl -l -v output

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

wsl -s Ubuntu-20.04 output

Using VS Code and Torizon IDE Extension on Windows​

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 extension can be correctly installed from there.

Extensions appearance for VS Code running inside WSL

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:

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:

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​

danger

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.

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:

docker-compose.yml.debug

danger

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:

info

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.

Deploy and Release​

danger

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.

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 platform services 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 Platform Services Web Interface.

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​

caution

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.

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.

Continuous Integration and Continuous Delivery​

info

Right now this feature is available just on the Early Access version of the Torizon extension

The CI/CD is inteded to provide a pipeline (workflow) that replicates the following steps performed on VSCode:

  • Loading of the application on the workspace (also building and loading the SDK container, in case of C/C++ applications), performed by opening the application on VSCode, with the Torizon Extension enabled.
  • Compile and install of the source code and build the release application container, performed by the Torizon Extension in VSCode with the command Torizon: Build release container for the application.
  • Push the application release image to DockerHub the configured DockerHub repository, performed by the Torizon Extension in VSCode with the command Torizon: Push application container to a docker registry.
  • Publish the application Docker Compose YAML file to Torizon Platform Website, by the Torizon Extension in VSCode with the command Torizon: Publish application to OTA server.

CI/CD Pipeline Generation Command​

caution

Before you execute the command, make sure you have:

Also, make sure the GitHub repository of your application have exactly the same name as your VSCode application.

Open the command palette and run Torizon: Export GitHub Actions YAML file. The command will generate the CI/CD pipeline described above, that can be executed on GitHub Actions.

This pipeline consists of the following steps:

  • Downloading and running moses (the VSCode Torizon extension backend).
  • Accepting the EULA.
  • Enabling ARM emulation.
  • Loading the Application.
  • Building the SDK container (devcontainer) used on VSCode, if the application is C/C++.
  • Compiling and installing the source code, placing everything needed for the code to be executed on appconfig_0/work.
  • Building the application release image.
  • Performing the login at DockerHub.
  • Pushing the application release image to DockerHub.
  • Publishing the application Docker Compose YAML file to Torizon Platform Website.

To push your application to DockerHub it is necessary to create a DockerHub token and save it on GitHub repostory secrets of your application with the name DOCKERHUB_TOKEN. Also, the command generates a string of the credentials.zip file using base64 enconding, which also should be save on the repository secrets, with the name TORIZON_OTA_CREDENTIALS.

The file generated is saved on the directory .github/workflows, with the name github-actions.yml. If this file already exists and you run the command the file is replaced with a newly generated one and the old file is saved on the directory .github/workflows/old, with the name github-actions-<integer-incremental-value>.yml

Environment variables for the SDK container can be customized using a file called customEnv. Also, for C/C++ applications, there is a file containerEnv that contains the environment variables captured from the devcontainer and is the one used this application SDK container (the customEnv file is merged into this containerEnv file).

danger

Be aware to not push your credentials.zip to the GitHub repository of your application as it contains your confidential information to push packages to your Torizon Platform account.

This video below shows the generation of this pipeline and it's execution on GitHub, producing the application release image on DockerHub and the Docker Compose YAML file on the Torizon Platform Website. You can then execute your application on the board bydoing the steps described on Torizon Platform Website to perform a application update.

This GitHub actions generated can be customized as needed. If you need a step that is not included on this generated file, please check the command-line interface of moses documentation.

tip

If you want to have more than one GitHub actions pipeline at the same time, copy the GitHub actions YAML files to the .github/workflows directory.

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 Platform Services, 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.

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:

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.

Generate a Docker Compose File to Deploy the Application With Torizon Platform​

info

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 the creation of Torizon Platform Packages 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 Platform Services. With them you can:


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:

Next Steps​

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

Application Development for Torizon​

Production Programming​

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

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:

Send Feedback!