Visual Studio Extension For Torizon
This article complies to the Typographic Conventions for Torizon Documentation.
Introduction
Torizon offers a Microsoft Environment for developers familiar with Visual Studio. This article will show how to install, configure and use it to build a "hello world" application and deploy it to a target device.
There is also a trend towards using Visual Studio Code (which by the way is very different from Visual Studio, only the name is similar). If you are interested in learning more, check our article Visual Studio Code Extension for Torizon.
Prerequisites
- Development Computer
- Windows 10 version 2004 (a.k.a. May 2020 update) or higher.
- Toradex Hardware with TorizonCore installed.
info
Make sure that the board and development computer are on the same network.
- Docker Desktop
info
Make sure Docker is running.
- Visual Studio 2019:
- Installed Visual Studio Workloads
- Desktop development with C++
- Linux development with C++
- Installed Visual Studio Workloads
How to Debug C/C++ Applications on Visual Studio with Torizon Extension
To begin, see here a short video showing how easy is to debug C/C++ applications on Torizon devices using Torizon Extension with Visual Studio:
Then, let's go with our step-by-step guide.
Known Issues
The SDK Build will not work if buildkit is enabled in Docker
When buildkit
is enabled you can't reference local images. This prevents multi-stage builds or Dockerfile referencing a local image from working. Toradex SDK uses a container that is generated on the fly and kept on the local machine and this fails with buildkit
enabled.
To fix that, please disable buildkit on the local Docker installation by or removing it from your Docker daemon configuration file at "features" section, or setting its value to false.
Behavior of printf function on debug session
You must add a \n
(new line) at the end of each line to be printed through printf()
, so you can see the lines being printed during the debug session at the Linux Console Window in Visual Studio.
Without this, the output will only appear at the end of the debug session.
Installing the Extension
The latest versions of the Toradex Torizon Support extension can be found on the Visual Studio marketplace, in two versions:
- Toradex Torizon C/C++ Support: stable version, with a slower release cycle.
- Toradex Torizon C/C++ Support (Early Access): preview version, always gets the latest features but is more subject to bugs.
Close all running instances of Visual Studio. Choose one of Torizon extensions from the above, download and install it.
tip
The extension is available for Visual Studio 2019 only!
Check that the installation was successful by opening the extension list under Extensions > Manage Extensions:
Setting Up Torizon Environment
After installation, open Visual Studio for a first configuration of the work environment for Torizon. After opening Visual Studio click on Continue without code:
Torizon IDE Backend Configuration
The IDE extension talks to a back-end service named Moses via a REST API. Learn more about it on Torizon IDE Backend Architecture and Internals and Torizon IDE Backend Command-line Interface.
Directly from Visual Studio, you have access to configure important options:
- Backend port: The port that the Moses service will use.
- Log file: The path where the log file will be saved.
- Show backend console: Shows the Moses console along with the Visual Studio.
caution
Currently, Windows usernames with spaces (example: FirstName LastName) are not supported and will result in a fatal error on the Moses service.
Download Base SDK Image Containers
Visual Studio Extension For Torizon uses Docker container images that have all the toolchain and SDK for C/C++ development for Toradex Boards. It is recommended to download these container images before starting development. Select menu Tools -> Download update base and sdk containers :
Downloading and updating container images may take a few minutes. Wait until you have the following message in the output:
Torizon Devices
Visual Studio Extension For Torizon needs to be connected to a target device, which will be the context for deploying the developed applications. To connect to Toradex devices with Visual Studio Extension For Torizon use the Torizon Devices Explorer. Select the menu View -> Other Windows -> Torizon devices:
On the Torizon Devices Explorer click on the Detect device on the network:
The window below will be shown:
Enter the IP address of the Toradex board, which will be the target device, and the Torizon user credentials then click the Detect
button.
info
These credentials are the same that were added during the first Torizon boot.
This detection process will perform an exchange of credentials between Visual Studio and the Toradex board to pair the board with the Torizon Visual Studio Extension.
After detection, we should have in Torizon Devices Explorer a new entry for the target device. Click on Refresh to download information...
button to list the information about the Docker Images, Containers and Processes running on the target device:
It's also possible to open an SSH Terminal directly from the Torizon Devices Explorer, just right click on the device and choose SSH Terminal option:
You will end up with an OpenSSH Client with access to the board:
Torizon Toolbar
Another feature that must be enabled before we create our first project is the Torizon Toolbar. Right click on the Visual Studio toolbar and select Torizon Toolbar:
After this first environment setup, we are ready to create our projects.
Create New Project
To create a new Torizon C/C++ project select File -> New -> Project ...:
On the Create a new project
window search for torizon
templates and double click the Torizon C/C++ Application
template:
On the Configure your new project
window:
- Enter the
Project name
; - Select storage
Location
for the project files or leave the pre-defined location; - Be sure to check (leave checked) the "Place solution and project in the same directory."
- Click the
Create
button;
On the create task Visual Studio will ask for Select supported platforms
. Select the platform that matches with the architecture of the target device. For this guide, we are using the Apalis iMX8QM that contains a hexa-core arm64v8 processor, so we select the option debian arm64v8 bullseye
:
info
Please notice that the list of platforms may change as new platforms supporting new releases of debian or providing some pre-installed libs for specific usage scenarios will be added.
This will create a blank Torizon C/C++ Application template.
Deploy and Debug
After the development of your application, in the case of this guide a simple message to be written, it is time to run the application to test and debug it on the target device.
To debug your application you can enable breakpoints selecting the lines of code that you want debug:
After selecting any breakpoint in your source code, run the application to debug it. For this, click on the Deploy and debug torizon Application
, the "play" button, from Torizon Toolbar:
As shown in the GIF above, when clicking on Deploy and debug torizon Application
a window will be displayed warning that the application is not up to date, click on yes
button to build and update the application container. This will start the build, deploy and debug process.
The first time the application containers are built takes some time:
You will get the following messages in the output tab when the application container build has completed successfully:
When the build of the application container finishes Visual Studio will start the deployment onto the target device. A window to Select device...
will be shown. Select your target device to deploy from the list and click Ok
button:
The deployment of the container application to the target device can take some time during the first deployment. Wait until the deployment finishes successfully. After this, the application will wait until the deployment finishes successfully. After that the application will be running on the target device and the breakpoint will be reached. Click on the Continue
button, or press the F5 key, to continue to the next instructions of the program:
After the first time, future deployments with the Deploy and debug torizon Application
command will become faster, because the container will only have to be updated on the target device, a much faster process than deploying the container as a whole:
Deploy and Release
When the application is ready, debugged and tested, it can be deployed and released. To do this switch the Debug_debian_bullseye-slim_<your_arch>
option to Release_debian_bullseye-slim_<your_arch>
in the Visual Studio toolbar Solution Configurations
:
Next step is to put the extension in release mode. To do this, select Project -> Properties -> Torizon C/C++ Application -> Configuration -> HelloWorld Properties (the project name in the example below is HelloWorld) and change the combo box Configuration
from Common
to Release
:
For the Release configuration you will need to add two new properties. Click on the New Property...
button. In the Name:
field enter targetcommands
and in the Value:
field enter CMD [ "/bin/<your_project_name>.out" ]
(the project name in the example below is HelloWorld), click OK
to apply it.
For the second property click on the New Property...
button again. In the Name:
field enter targetfiles
and in the Value:
field enter COPY work/bin/ /bin/
, click OK
to apply it:
Setting the targetcommands
property is the same as adding CMD
to a Dockerfile. Here we are adding the output generated by the compiler as CMD
. In order to place the executable file we created in to the path referenced by CMD
we must copy that file to the container image. The targetfiles
property allows us to COPY
to the Dockerfile. Here we are adding the output files, bin
folder, to be copied to Docker image.
Click Save
button to apply the changes and close the Property Pages
window. Now in release mode build the application clicking on the Build Torizon Application
from the Torizon Toolbar
:
Wait until the build is completed. After that it is necessary to build the application container, so click on the Deploy Torizon application and container
from the Torizon Toolbar
:
After the deployment, refresh the list of images and containers on Torizon Devices Explorer:
You can see that now there are two images and two containers. One of these containers and image is for the debug, it will no longer be needed and can be deleted to free up space. First, remove the debug container and then the image. Still using Torizon Devices Explorer click on the names listed in Containers
. The one that contains debug in your name, right click and select Delete
:
After that, the same can be done for the debug image. Using Torizon Devices Explorer click on the names listed in Images
. The one that contains debug in your name, right click and select Delete
:
Deploy to the Torizon Platform Services
Request access to evaluate the Torizon Platform Services premium features |
After a development cycle, you have to deploy the application to your devices. The easiest way to use the Torizon Platform Services, since it comes with integrated remote updates.
tip
Before proceeding, make sure that the latest version of your application is built in release mode.
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.
To start the publishing process, select Tools\Torizon: publish application as Torizon OTA package
. You will be prompted with a dialog box in which you must setup some fields:
- Tag: it must be a valid docker tag and must include a repository name, image name, and a tag. Additionally, if not using Docker Hub, it must also contain the Docker registry. For example,
mydockerhubaccount/myimagename:mytag
andhttps://mycustomregistry.com:8080/myaccount/myimagename:mytag
are valid tags. - 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, like1.0.0
. - Account info: valid account and password for Docker Hub or your custom registry.
- Torizon Platform credentials: the path to the
credentials.zip
file. - (optional) Save credentials: if you want to securely store your credentials (username, password and location of the credentials.zip file), select the "Store credentials safely on this machine" checkbox. Credentials will be stored only if the operation completes successfully. If you choose to save the information, you won't be prompted again and the version number will be increased automatically.
Once the operation finishes, your new package will be available for deployment in the Torizon OTA Web Interface.
If you want to delete the credentials and be prompted for the information again, choose the Tools\Torizon: clear stored credentials
option from the VS2019 menu.
Credentials are safely stored in a file named "credentials.json" inside your application's folder. The information is encrypted and will work only for the user who saved it and only on the specific machine where the credentials have been saved. You are encouraged to add the file to your .gitignore
list since moving it to other machines/users won't work, credentials will be erased and the user will be prompted again.
Next Steps
Now that you have the extension set up and deployed your first hello world application, how about continuing with something more advanced?
C/C++ Development for Torizon
- C/C++ Developer Workflow on Windows
- Browse for other related articles in the Torizon Documentation.
Production Programming
You can use the release image 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.