Introduction

Torizon OTA allows customers to push their own customized versions of TorizonCore to our hosted service. It means that, after customizing the image, you must sign and push it to Torizon OTA.

In this article, you will learn how to use the TorizonCore Builder Tool, the recommended way to customize a TorizonCore image, sign it, and push the image to Torizon OTA, so the system update can be initiated there.

This article complies to 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 TorizonCore Image with no-container pre-provisioned for offline installation.
• A credentials.zip file downloaded from your account on the Torizon OTA dashboard.
• A splash screen image called splash.png, like this one (Obs.: the splash screen image needs to be a png file with a maximum size of your screens resolution - typically a resolution around 600x400 is used).
• A docker-compose file if pushing an application update.

Make sure your working directory has the following structure, including credentials.zip, splash.png, docker-compose.yml, and a directory called image containing the uncompressed TorizonCore installation image:

$ tree
.
├── credentials.zip
├── image
│   ├── image.json
│   ├── marketing.tar
│   ├── prepare.sh
│   ├── SPL
│   ├── toradexlinux.png
│   ├── torizon-core-docker-apalis-imx6.ota.tar.zst
│   ├── u-boot.img
│   ├── u-boot-initial-env-spl
│   └── wrapup.sh
└── splash.png
└── docker-compose.yml

Also make sure you can run TorizonCore Builder:

$ torizoncore-builder --help

Generating a customized TorizonCore image

Let's modify a TorizonCore image. In this example, we will apply a custom splash screen to illustrate the process.

To install TorizonCore Builder, follow the instructions below, in order.

Create and enter a working directory where your customization will be stored:

$ mkdir ~/tcbworkdir
$ cd ~/tcbworkdir

Use the setup script named tcb-env-setup.sh, available on the Toradex Github, to setup TorizonCore Builder:

$ wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh
$ source tcb-env-setup.sh

Verify that the command torizoncore-builder is available:

$ torizoncore-builder --help

Warning: Make sure to: (1) source the script, (2) every time you open a new terminal, (3) inside the working directory you have previously created. Otherwise, it will not work as intended and, most importantly, the torizoncore-builder alias will not be created properly.

Applying Customization

Apply the custom splash screen image – when using torizoncore-builder versions 3.0.0 or later:

torizoncore-builder splash splash.png

Or, if using versions of the tool before 3.0.0:

torizoncore-builder splash --image splash.png

Now create a new TorizonCore OSTree image – when using torizoncore-builder versions 3.0.0 or later:

torizoncore-builder union my-custom-image

Or, if using versions of the tool before 3.0.0:

torizoncore-builder union --union-branch my-custom-image

Note: For a more detailed description of splash, union and other TorizonCore Builder commands, see TorizonCore Builder Tool article.

Signing and pushing the image to Torizon OTA

The command push from TorizonCore Builder can be used to push a new TorizonCore image to Torizon OTA.

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

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

In our example, the OSTree reference is called my-custom-image (defined in the union command above), so the command below will push the customized image to Torizon OTA:

torizoncore-builder push --credentials credentials.zip my-custom-image

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

• 

  Torizon OTA customized image

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

Signing and pushing the docker-compose file to Torizon OTA

The command push can also be used to push docker-compose files to Torizon OTA.

For this credentials.zip is also required along with the path to the docker-compose file. Your compose file can have any name, as long as it ends in .yml, or .yaml. If it does not have either of these file endings then the command will assume you passed an OSTree reference instead.

torizoncore-builder push --credentials <credentials file> <path to docker-compose file>

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

torizoncore-builder push --credentials <credentials file> --package-name <name for this update> --package-version <version for this update> <path to docker-compose file>

The --package-name argument will apply whatever is passed as the name for this update package. Simply put, this is the name that your update will appear under in our Torizon OTA web UI. This argument is however optional and if not used will default to docker-compose.yml. The other argument --package-version is the version that this package will show up as in the web UI. This doesn't have to be a numerical version and can be any legitimate string. This argument is also optional and if not used will default to the date of upload at UTC time in the format of yyyy-mm-dd.

For example running the following command:

torizoncore-builder push --credentials credentials.zip --package-name tcb-test --package-version 1.1 docker-compose.yml

Will result in the following appearing in your account's web UI:

• 

  Torizon OTA docker-compose package