Skip to main content
Version: Torizon OS 6.x.y

Production Programming with Torizon

Introduction​

This article will go over the recommended workflow to prepare your Torizon OS 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 Cloud, 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 Torizon OS, please see our Production Programming for Linux article to learn the recommended methods outside Torizon.

This article complies with the Typographic Conventions for the Toradex Documentation.

Prerequisites​

In order to perform production programming in Torizon, you should have:

If you need provisioning at scale:

Production Programming​

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 Torizon OS 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 Torizon 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 Torizon OS 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 Torizon OS image that can be installed using Toradex Easy Installer.

Image Creation Process

Creating the OS image​

Using the build command you can simplify your production image components to 3 main components:

  • The input Torizon OS 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 .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 Torizon OS 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 Torizon OS 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 Cloud​

For using your device with our Torizon Cloud, you should provision an image using the same yaml configuration file used to customize your Torizon OS. 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.

Serving the Custom Image on the LAN​

TorizonCore Builder includes the capability to serve an Easy Installer image over LAN. It has a pre-configured Avahi Zeroconf service, so that Easy Installer automatically see it as an image source over the LAN.

Learn how to use it on TorizonCore Builder Tool - Commands Manual - images serve.

Installing the image - Toradex Easy Installer​

The recommended way to flash your Torizon OS image is by using the Toradex Easy Installer tool. This is available on all Torizon OS-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 Easy Installer 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​

tip

This section is optional, and only applies to those making use of our Torizon Cloud.

caution

To use provisioning at scale as documented below, requires at least TorizonCore version 5.7.0.

With Torizon OS based products there is also the option of provisioning your devices to our Torizon Cloud. 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

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

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 Torizon OS 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 Torizon OS 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.

For example:

input:
  easy-installer:
    local: <INPUT_IMAGE>
customization:
  <YOUR_CUSTOMIZATIONS>
output:
  easy-installer:
    local: <OUTPUT IMAGE>
    provisioning:
      mode: "online"
      shared-data: <SHARED-DATA TARBALL>
      online-data: <ONLINE-DATA STRING>
caution

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 Torizon OS 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.

Provisioning Devices​

The final step is to get your devices provisioned. Fortunately, this is fairly simple now that you have your Torizon OS 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.

Provisioning for Online Updates​

If you've created your Torizon OS image with online mode provisioning, the device will require an internet connection after boot in order to complete the provisioning process. Specifically, it will need internet access to our Torizon Cloud domain.

After provisioning for online updates, the logs available with the command below will display Offline Updates are disabled.

# journalctl -f -u aktualizr*

Provisioning for Offline Updates​

In this case, you will not need an internet connection to complete the provisioning process. All the information needed to check for trustworthy offline updates is received from the shared-data.

After provisioning for offline updates, the logs available with the command below will display Offline Updates are enabled. Any warnings related to the online update process can be safely ignored.

# journalctl -f -u aktualizr*

Check and Customize Auto-Provisioning Process​

Beyond the basics, there are some points to be aware of:

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

[Service]
RestartSec=60

Once created you can capture this override using TorizonCore Builder.



Send Feedback!