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:
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:
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.
The 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.
Image Creation Process
Using the build command you can simplify your production image components to 3 main components:
.yaml file 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:
Further details and usage on each of these can be found on TorizonCore Builder Tool “build” command.
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.
To use our Secure Update Features, you should provision an image using the same yaml configuration file used to customize your TorizonCore. Once that image is installed on a device, that device will be provisioned to Torizon Platform Services.
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:
Image Installation Process
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.
Tip: This section is optional, and only applies to those making use of our Torizon Platform Services.
Warning: 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.
Provisioning at scale
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 credentialis.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:
Note: 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.
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. For example:
input:
easy-installer:
local: <INPUT_IMAGE>
output:
easy-installer:
local: <OUTPUT IMAGE>
provisioning:
mode: "online"
shared-data: <SHARED-DATA TARBALL>
online-data: <ONLINE-DATA STRING>
Warning: 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 yaml file.
For more details see the provisioning property under the Output section of the build command’s 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:
# journalctl -f -u auto-provisioning
# 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:
[Service]
RestartSec=60
Once created you can capture this override using TorizonCore Builder.
