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

Subsystem Updates Overview


This article shows how the Subsystem Updates feature from Torizon Cloud helps you to provide secure, reliable and decoupled updates to different software or hardware subcomponents and subsystems of your Torizon OS device.

Why Use Torizon Subsystem Updates​

It is common to have different subsystems connected to a main device, each one having an independent maintenance lifecycle, and a particular set of properties, including separated software or hardware resources.

When you have a main device connected to Torizon Cloud, it is possible to easily maintain all of those subsystems updated, with minimal configuration and implementation required. Torizon Subsystem Updates extends the capabilities of Torizon Cloud robust solutions for OS, Application, and Bootloader updates. Check how it is reliable and secure, and learn how it works to get a better insight.

Use Cases​

With Subsystem Updates, it is possible to upload, host, sign, identify, report, and trigger the installation of packages for subsystems of your Torizon OS device.

While there is a huge number of possibilities for your subsystems or components, some interesting cases are:

  • Software Payload: images, configuration files, and license files
  • Software Subsystems which do not use a container format
  • Software or firmware for hardware components on a custom carrier board
  • Software or firmware for hardware externally connected to your device
  • Application for Cortex-M cores or Real-Time units available on some SoCs

It also provides resources to enable custom update scenarios such as:

  • Conditional and scheduled updates
  • Custom rollback trigger and procedures
  • Check for complex expected behavior of subsystems
  • Multi-step installation - complete after reboot or other process from your device

How it Works​


There are several components involved in this feature:

  • Subsystem: Any subsystem or component from your application or device you want to update.

  • Target: This is the component or subsystem identification in the Torizon Cloud. This name will be used to identify the target subsystem for the packages you want to update. Torizon OS, Container application, and Bootloader are targets provided out-of-the-box with Torizon. You need to create a target for each of the subsystems you want to update.

  • Payload Binaries: These are the binaries to be installed in your subsystem. You don’t need to change anything in the process of generating the payload for your subsystem. Your files will be securely and reliably provided in a file path in your target device for you to deploy according to your target subsystem needs. See the action handler section for more information.

  • Packages (Payload + metadata): After the creation of your target subsystem in Torizon Cloud, whenever you upload a payload to this target subsystem, a package is created in the server, and the file is hosted along with all the security metadata created for it.

  • Torizon Cloud UI: The Torizon Cloud WebUI provides the interface used to create your target subsystem and to quickly upload your payload to create a package

  • TorizonCore Builder: The CLI Tool provided by Torizon enables you to quickly upload your payload and create your package for upload using a CLI, enabling automation and convenience for the development cycle. Read more on our TorizonCore Builder documentation

  • Aktualizr - Update Client: The Torizon OS Device uses a service called Aktualizr, which takes care of managing all the updates and their security and reliability. Aktualizr is the agent capable of validating and delivering your packages for updates after they are triggered on the server side.

  • Aktualizr - Configuration File: In the configuration file, you should specify parameters for each subsystem, such as paths where the payload is delivered and the assigned action handler.

  • Action handler: Torizon OS handles the updates for OS, application, and bootloader, it also takes care of all the particularities of each component, ensuring rollback capabilities, for example. The subsystem updates enable you to update any kind of subsystem while providing a simple interface for you to implement the action handlers, so any needed process can be implemented, maintaining a high level of reliability and security.

  • Environment Variables to Action Handler: To make your life easier while implementing the action handler, the Subsystem Update feature loads environment variables to provide any information that may be needed for handling the update process.

  • Custom Medatada on your packages: JSON payload that can be appended when creating your packages. It will be delivered to your action handler so you can use it to help manage updates.

  • Output from Action handler: To close the loop and keep the logs in the device and the Torizon Cloud well served with up-to-date information, the Subsystem Update feature provides a channel to get information back from your update process.

Subsystem Update Process​

The process to get the subsystem components updated can be summarized as follows:

  1. The user provisions the device with Torizon OS to the Torizon Cloud: the device receives all the security metadata to make it capable of communicating with the server and validating update packages.
  2. The user creates the payload and uploads in Torizon Cloud: Torizon Cloud hosts the payload binaries and all the security metadata is created to ensure the update is trustworthy, generating a ready-to-use update package.
  3. The device checks for updates: the Aktualizr update client running in the Torizon OS device reports the installed versions for its components, including the subsystems, and checks for updates.
  4. The update package is downloaded and validated: the update client delivers the payload to the custom-built action handler, ready for the installation process.
  5. The custom-built action handler performs the update: the Torizon OS device performs all the programmed actions until the download is concluded or failed.
  6. The device reports the update status: the success or fail status along with any desired custom message are logged and delivered to the Torizon Cloud.


The general workflow for using the feature is:

  1. Provision the Torizon OS device to Torizon Cloud.
  2. Configure the Aktualizr update client to handle the target subsystem packages on the device.
  3. Write a custom action handler script to report the subsystem package version and execute the installation process, including any particularities, such as checks and rollbacks.
  4. Create the target subsystem in Torizon Cloud.
  5. Upload the update payload to Torizon Cloud, thus creating an update package.
  6. Initiate the update with the new package.

Learn how to use the feature in the First Steps with Subsystem Updates article.


Toradex has presented webinars about Subsystem Updates and you can watch them on demand.

Updating Cortex-M Firmware and other external devices Securely Over-the-Air​

Learn more about this webinar on the landing page, or watch it below:

Send Feedback!