Production Programming in Torizon
This article will go over the recommended workflow to prepare your TorizonCore based product for production in the Torizon environment.
This includes details on the production programming of your software and the provisioning of your device to Torizon Platform Services, so you can benefit from our secure update features.
Not all methods will be covered here, but the commonly recommended ones will. If you have a specific use case that does not fit into this guide feel free to contact Toradex to discuss it further.
If you are not using TorizonCore, please see our Production Programming for Linux article to learn the recommended methods outside Torizon.
This article complies to the Typographic Conventions for the Toradex Documentation.
In order to perform production programming in Torizon, you should have:
- The TorizonCore OS images and/or application files readily available
- TorizonCore Builder installed on your host machine
- Commercial license for your Torizon Platform Services account
- Toradex Easy Installer download in your host machine
Production programming refers to the at-scale methods and processes used to program multiple modules with your product’s unique software. It’s important to have a reliable and consistent method for this, as any issues at this stage will be scaled with the number of products you ship, affecting the production capacity and cost.
At this stage, the most important steps to consider are:
- How to create your master TorizonCore image, the initial image that will be used to flash your devices in production.
- How to install your image on the device in a practical and easily reproducible way.
Creating the image - TorizonCore Builder
Our TorizonCore Builder tool is the recommended way to customize a TorizonCore OS image to suit your product requirements. This tool allows easy customization of nearly all aspects of the OS, however for a more detailed look at its features please take a look at TorizonCore Builder Tool - Customizing TorizonCore Images.
For now, we’ll highlight the most important features of this tool that are relevant for production programming.
build command is how you will be producing your custom image once in production. The build command takes in a
.yaml file that acts as a script for TorizonCore Builder. This allows the creation of your custom image to be automated and reproducible.
The result will be a TorizonCore image that can be installed using Toradex Easy Installer.
Creating the OS image
build command you can simplify your production image components to 3 main components:
- The input TorizonCore image: This is the base image that your changes and customizations will be based on top off.
- The customized components: These can be things like device-trees, device-tree overlays, or container-related components. Basically, the things that will be used to customize the input image.
- The build command
.yamlfile itself: This is how you will configure TorizonCore Builder to apply your customizations to your input image.
These 3 types of components can be version-controlled using Git or other version-control tools. In this way you ensure that your product's TorizonCore image can be reliably reproduced or modified as it matures.
Afterward, let’s highlight some key features and customization options that are relevant to production programming:
- Set an image to be auto-installed upon detection by Toradex Easy Installer - our installation tool. This allows for unmanned programming of devices.
- Set an image to be auto-rebooted once the installation is complete. This can be important for some systems that need to boot into the installed image right after installation in order to perform any needed setup.
- Accept any licenses or EULAs that are present in the image. This is especially useful for NXP-based modules since many of these have NXP EULAs that must be explicitly accepted.
- Capture changes that you want to be reproduced in every device, such as update configuration, network configuration and many others.
Further details and usage on each of these can be found on TorizonCore Builder Tool “build" command.
Bundling the Application
To bundle your application containers to the image used for production programming, you will also be using the same
yaml configuration file used to customize your TorizonCore image. When you run the
build command to build your image, your application containers will automatically be bundled into the image. This is how you will be installing your applications in your custom image and having them run upon boot.
Preparing the Devices for Torizon Torizon Platform Services
For using your device with our Torizon Platform Services, you should provision an image using the same
yaml configuration file used to customize your TorizonCore. Once that image is installed on a device, it will be provisioned automatically and will be ready for using our secure remote or offline update, devices monitoring, and new features to be released.
Installing the image - Toradex Easy Installer
The recommended way to flash your TorizonCore image is by using our Toradex Easy Installer tool. This is available on all TorizonCore-supported modules.
The most usual ways to accomplish production programming with Toradex Easy Installer are:
- Auto-install images in external media, such as SD cards and USB drives.
- Usage of unattended ethernet auto-install for devices that don’t have external media access available.
For more information on the usage and details of this tool please see the Detailed manual. Any details regarding Toradex Easy Installer that are specific to Torizon systems will be covered in this article.
Provisioning at Scale
This section is optional, and only applies to those making use of our Torizon Platform Services.
To use provisioning at scale as documented below, requires at least TorizonCore version 5.7.0.
With TorizonCore based products there is also the option of provisioning your devices to our Torizon Platform Services. By provisioning your device this allows it to connect to your specific account on our services website. This then enables your device to be updated in the future allowing ongoing software updates and maintenance. Being provisioned will also allow your device to leverage other services such as device monitoring and any other future feature we may add to our platform.
Getting Provisioning Data
The first step in the provisioning process is getting provisioning data that is specific to your account. Typically you will only have to run this step once since provisioning data can be reused multiple times.
Before we proceed you’ll need the
credentials.zip file for the account to which you want to provision devices. Since credentials access and other sensitive data are involved, this step should be run by your system admin or those with proper access to such information.
Next, let’s briefly cover the different types of provisioning data:
- Shared-Data: This type of provisioning data is used for provisioning a device for offline and online updates. This data is not security-sensitive. In our system, we distribute the data as a tarball that contains the data.
- Online-Data: This type of provisioning data is used only in provisioning for online updates. This data is security-sensitive and should be handled carefully. In our system we distribute the data as a base64 encoded string, making it easy to use in a CI pipeline or store in a secrets manager. Given the nature of this information avoid storing it in Git or other similar revision control systems.
A device that is provisioned for online updates is also capable of offline updates.
Now in order to get either provisioning data, TorizonCore Builder will be used. The
platform provisioning-data command can be used to fetch both types of provisioning data:
$ torizoncore-builder platform provisioning-data --credentials credentials.zip --shared-data shared-data.tar.gz --online-data DEFAULT
The command will then produce a tarball containing the shared-data and output the string that is the online-data. This data can then be stored for future provisioning use. For a detailed guide on the usage of this command please see the specific section in the commands manual
Installing Provisioning Data
Now that you have obtained your provisioning data, you need to apply it. The idea here is that you want to create a single TorizonCore image that, when flashed to multiple devices, will allow each device to provision itself automatically. This is the way to achieve the "at scale" part of provisioning at scale.
Now, to do this, you use TorizonCore Builder again. The previously discussed
build command can also be used to produce TorizonCore images with provisioning data installed.
Make sure that you performed the proper configuration of the device for using online or offline updates and captured the changes to the image in the customization section of the file.
local: <OUTPUT IMAGE>
shared-data: <SHARED-DATA TARBALL>
online-data: <ONLINE-DATA STRING>
Recall that the online-data string is sensitive information. You’ll most likely want to make use of variable substitution, rather than inserting this string in plain text in your
For more details see the
provisioning property under the
Output section of the
yaml file schema.
Alternatively, for quick tests outside of production, you can also use the stand-alone command
images provision in order to produce a provisioned image.
$ torizoncore-builder images provision --mode online --shared-data shared-data.tar.gz --online-data <your-well-kept-sensitive-string> <PATH TO INPUT IMAGE> <PATH TO WHERE OUTPUT IMAGE WILL BE PRODUCED>
As seen this command as input takes the output of the previous platform provisioning-data command. The command will then output a TorizonCore image containing your provisioning information. This image can then be installed on a device using Toradex Easy Installer. For more details on the exact usage of this command refer to the TorizonCore builder commands manual.
The final step is to get your devices provisioned. Fortunately, this is fairly simple now that you have your TorizonCore image with provisioning data prepared. Using Toradex Easy Installer you can install your provisioned image. Once installed on a device, the provisioning is almost done. After the device initially boots into the new image for the first time, software services on the system will automatically finish the provisioning process.
Beyond the basics, there are some points to be aware of:
- If you've created your TorizonCore image with online mode provisioning, the device will require an internet connection after boot in order complete the provisioning process. Specifically, it will need internet access to our platform services domain. This is not the case for offline mode provisioning.
- As the device needs to boot at least once after image installation in order to complete provisioning. It can be helpful to set the "auto-reboot" flag on your image so that this reboot can occur automatically on your production line.
- If there are any unexpected issues or errors with the automatic provisioning service you can check the logs for the service using the command:
# journalctl -f -u auto-provisioning
- In case of transient issues like network connection, the auto-provisioning service has a default timeout of 5mins before it retries again. If you wish to change this timeout period you can do so by overriding the default value in the service using the command:
# systemctl edit auto-provisioning
This will open a text editor where you can create an override for this service. For example, if you want to reduce the timeout to 1 min, then your override would look something like this:
Once created you can capture this override using TorizonCore Builder.