Sign and Push Torizon OS Packages to Torizon Cloud

Introduction

The Torizon Cloud allows customers to push their own customized versions of Torizon OS to the hosted service. It means that, after customizing an image, you must sign and push it to Torizon Cloud before you can deploy it to your devices.

In this article, you learn how to use the TorizonCore Builder Tool for signing and pushing Torizon OS packages to the Torizon Cloud. To push application packages, see Sign and Push Torizon Application Packages to Torizon Cloud.

This article complies with the Typographic Conventions for Torizon Documentation.

Prerequisites

The prerequisites to complete these instructions are:

• A host machine with TorizonCore Builder installed.
• A .tar file containing the Torizon OS Image with no-container pre-provisioned for offline installation.
• A credentials.zip file downloaded from your account on the Torizon Cloud dashboard.

Make sure your working directory has the following structure, including credentials.zip and the Torizon OS installation image torizoncore-image-tezi-format.tar:

$ tree
.
├── credentials.zip
└── torizoncore-image-tezi-format.tar

Also make sure you can run TorizonCore Builder:

$ torizoncore-builder --help

Generating a Torizon OS image

The 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, and for a more detailed evaluation at its features please take a look at TorizonCore Builder Tool - Customizing Torizon OS Images.

With TorizonCore Builder, you always generate OS images that are suitable to be pushed to the Torizon Cloud for updates.

The output of this process is either an OSTree reference or a Toradex Easy Installer compatible image - ready to be installed with Toradex Easy Installer (TEZI), usually during production programming.

• Using standalone commands: the deploy command generates a TEZI format image, while the union command generates an OSTree branch.
• Using the build command, you can set the output section of the configuration file for either options.

info

Do not bundle container images into a Torizon OS image if you plan to update your devices with Torizon Cloud. Bundled containers only reach a device when you flash the image with Toradex Easy Installer, so they cannot be delivered as an update. To deploy the OS and the application together, use the synchronous update feature of Torizon Cloud instead.

Signing and Pushing the Image to Torizon Cloud

The TorizonCore Builder tool is also used to push your OS image and your application to the server.

The command platform push from TorizonCore Builder can be used to push a new Torizon OS image to Torizon Cloud.

$ torizoncore-builder platform push --credentials <credentials file> <ostree reference>

The command requires the credentials.zip file from Torizon Cloud and a reference to the OSTree repository that should be pushed to the Platform Services server.

If you are pushing Toradex Easy Installer compatible images, first you should run the images unpack command to generate a base OSTree reference.

$ torizoncore-builder images unpack <base Toradex Easy Installer image of Torizon>

After running the images unpack command, you should use base as the ostree reference.

As an example, the command following pushes the customized and unpacked image to Torizon Cloud:

$ torizoncore-builder platform push --credentials credentials.zip base

Now, if you log in to Torizon Cloud and initiate an update, you should see the customized image, ready to be used to update a device:

And, if everything went fine with the update, you shall see your board rebooting when the process is completed, and the splash screen shown in the device initialization is the one defined in the new image.

There are also some additional arguments that can be passed to further customize this image update package.

$ torizoncore-builder platform push --credentials <credentials file> --package-name <name for this image update> --package-version <version for this image update> <ostree reference> --hardwareid <supported hardware for this image update>

The --package-name argument applies whatever is passed as the name for this image update package. Simply put, this is the name that your update appears under in the Torizon Cloud web UI. However, this argument is optional and, if not used, defaults to the OSTree reference.

The --package-version argument is the version that this image update package shows up as in the web UI. This doesn't have to be a numerical version and can be any legitimate string. This argument is optional, and if not used, the version defaults to the OSTree subject.

The --hardwareid argument defines which hardware IDs the image to be uploaded is compatible with. This argument can be repeated multiple times, adding extra supported hardware IDs to the image. It's important to notice this argument overrides the default image's hardware ID. Under the Supported Hardware tab at the Torizon Cloud web UI, you can confirm the changes. This argument is optional, and if not used, the supported hardware ID defaults to the original image's hardware ID.

Also, check the using a static-delta section. Using this approach makes updating an existing package, on the deployed device, more efficient.

Creating and Deploying a Static Delta OS Image Update

Static delta generation pre-computes a binary diff between two specific OS packages, making that particular upload path more efficient.

As an example, you pushed a customized image to Torizon Cloud:

$ torizoncore-builder platform push --credentials credentials.zip base

And deployed the image to the modules on the field.

Later on, you updated that image to a newer version and pushed the updated version to Torizon Cloud:

$ torizoncore-builder platform push --credentials credentials.zip --package-version newer base

From this point, you have 2 options:

• Initiate the update on the module;
  • This requires the module to download all new and changed objects before updating.
• Create a static-delta and update the module with the delta;
  • This way, the module downloads only difference between the versions in the changed files.

To create a static-delta and push it to Torizon Cloud, you need the hashes of the old version and the new version.

info

The OS package Hash can be found by inspecting the OS package on your Torizon Cloud Platform account. The OS package must be accessible on your Platform account.

$ torizoncore-builder platform static-delta create --credentials credentials.zip <FROM_HASH> <TO_HASH>

From the Torizon Cloud, click the package you created the static-delta for. You can see the push worked from this new field, "Deltas"