Skip to main content
Version: 5.0

TorizonCore Builder Tool - Customizing TorizonCore Images

Introduction​

TorizonCore Builder is a tool that allows you to easily generate a custom image of TorizonCore with device configuration changes, a custom device tree and overlays, pre-provisioned containers, external kernel modules, and a splash screen. In the end, you will have a custom TorizonCore image that you can flash onto the SoM using the Toradex Easy Installer, deploy to the SoM through SSH, or push to Torizon Platform Services for deploying it remotely. The tool is designed to be used on production programming and on development as well.

TorizonCore Builder Workflow

*OS Customization Files are device tree and overlays source codes, external kernel modules source files, a splash screen image, and a directory with the configuration changes captured from the device. They can be also called version-controlled artifacts.

Easily Customizing TorizonCore Images With TorizonCore Builder Tool​

Resources​

Browse for TorizonCore Builder resources from the tabs below.

This article complies to the Typographic Conventions for Torizon Documentation.

Requirements​

  • A Toradex SoM with Torizon installed

Typical Use Cases​

TorizonCore builder tool provides multiple commands to be used in different situations. We will describe below typical TorizonCore Builder use cases and on which section the customization related to these use cases is:

Customizing a TorizonCore Image for Production​

TorizonCore Builder provides standalone commands that allow you to easily customize a TorizonCore image. Such changes could be:

info

If you want to add a kernel module that is available in the kernel source, or in-tree, please make a request in our community. If you tell us the exact kernel config that must be enabled and it does not have a negative impact on TorizonCore, we'll add it as a module.

Deploying TorizonCore OS Images​

Users can deploy the image in three different ways:

To learn how to do it, refer to the Deploying the image section of this page.

Installing TorizonCore Builder​

OS Compatibility​

TorizonCore Builder executes in a Docker Runtime and it was tested on the following Operating Systems:

  • Linux
  • Windows 10 with Windows Subsystem for Linux (WSL2)
caution

WSL2 requires Windows 10, updated to version 2004 (also known as the Windows 10 May 2020 Update) or higher.

Shell Compatibility​

All our tests are run on Bash. TorizonCore Builder might work with other shells, but we don't ensure it.

That said, if you face a bug in a shell that is not Bash, please report it on our community website. We'll evaluate it and make our best effort to fix it, as long as the fix is compatible with Bash and the increase in maintenance is low.

Note for Users Installing TorizonCore Builder on Windows Machine​

TorizonCore Builder support on a Windows desktop requires the "Windows Subsystem for Linux 2" (WSL 2). This is due to TorizonCore Builder relying on a Linux-based filesystem.

Before proceeding with any TorizonCore Builder instructions please set up a WSL 2 distro and Docker on your development host as shown on Configure Build Environment for Torizon Containers. As a reminder, any and all TorizonCore Builder commands should be run in your WSL 2 distro.

Finally, as a quick tip, you'll occasionally need to transfer files to and from your WSL 2 distro and your Windows host. You can actually do this by using the built-in Windows file explorer utility. This and other Windows utilities can actually be invoked from within your WSL 2 Distro. For example by doing the following in your WSL 2 Distro:

$ explorer.exe .

The above command will open the Windows file explorer in your current directory. From here you'll be able to copy/paste and move files between the WSL 2 world and the normal Windows world.

Setup Script​

To install TorizonCore Builder, read our statements on OS and shell compatibility, then 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

For advanced usage, run source tcb-env-setup.sh -h, or see the project README.

If using Windows, you must pass extra parameters to the script when using the following commands:

tip

The setup script installs a bash completion script for TorizonCore Builder, making it possible to autocomplete commands and parameters by just pressing the TAB key.

Verify that the command torizoncore-builder is available:

$ torizoncore-builder --help
caution

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.

Using TorizonCore Builder​

This section shows how to use TorizonCore Builder in a simple way, yet covering almost all use cases. It is based on the build command, which allows the full image customization in a single step, using a configuration YAML file. The other commands that are necessary in conjunction with the build command in order to cover most use cases are also explained in this section.

If your use case is not covered here, please refer to the TorizonCore Builder - Commands Manual section for a detailed explanation of all TorizonCore Builder commands.

Workflow​

  • Create a configuration file with the desired settings (the build command can even help you with that);
  • Customize the configuration file in order to select the desired input image, include the desired customization, and get the desired outputs. Also, run the auxiliary commands where needed so all local artifacts possibly referenced by the configuration file are available;
  • Run the build command;
  • Deploy the output to the board or to Torizon Platform Services server;

To learn about TorizonCore Builder workflow and the different approaches to use the tool, with explanatory diagrams, please refer to the TorizonCore Builder - Workflow article.

Creating a Configuration File​

The easiest and thus recommended way for creating an initial configuration file is by running:

$ torizoncore-builder build --create-template

The previous command will create a file named tcbuild.yaml containing all possible configuration parameters accepted by the command.

The configuration file is in a standard YAML format which should be recognized by most modern programming editors. Any other name can be chosen for the file, but tcbuild.yaml is the name that the build command will expect by default when running in build mode. Most parameters in the generated file will be commented out which can be seen by the # character at the beginning of each line. Lines having the characters >> are just explaining the contents of the file and should be left as-is or removed if desired.

The contents of the file are organized in a tree structure where the leaves are configurable properties. In order to set a certain property, you need to make sure all its parent properties are also uncommented (by removing the first # character).

The configuration file follows the YAML format and syntax. The tool expects it to be made up of three sections, represented by the top-level properties (keys): input, customization, and output as outlined below:

tcbuild.yaml
# Configuration file outline:
input:
# Input section items (required).
customization:
# Customization section items.
output:
# Output section items (required).

Customizing The Configuration File​

Minimal Configuration File​

A minimal configuration file has to specify at least one input and one output. Below we assume that the input is a previously downloaded Toradex Easy Installer image that is stored in a directory called images relative to the working directory (set by the alias of the tool).

When downloading a Toradex Easy Installer image, be sure to download an image without evaluation containers, because the input image to be customized MUST NOT contain bundled container images. To download the image, go to the Toradex Download Links (Torizon, Linux BSP, WinCE and Partner Demos) article.

tcbuild.yaml
# Sample configuration file:
input:
easy-installer:
local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

The directory structure of such a "project" would look like this:

.
├── images
│ └── torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
└── tcbuild.yaml
Fetching Remote Images​

The input to the tool can also be specified as a URL to a remote server instead of a directory with a downloaded image, as in the Minimal Configuration section. If the input is passed as a remote image, the image will be downloaded every time the image is built.

In the sample configuration below, we directly download an image from Toradex's artifacts server:

tcbuild.yaml
# Sample configuration input, specifying a remote:
input:
easy-installer:
remote: "https://artifacts.toradex.com:443/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/7/colibri-imx6/torizon-upstream/torizon-core-docker/oedeploy/torizon-core-docker-colibri-imx6-Tezi_5.3.0%2Bbuild.7.tar;sha256sum=49fc6a32ab3fc21a184fb8333c19ad53f22875975219883c1087d929bedf470f"

Notice the presence of the sha256sum parameter which can be used to ensure that the downloaded file has a certain SHA-256 checksum – the tool will stop if the actual file checksum does not match that value. For more information about how a remote location can be specified please refer to the build command Detailed Manual.

Fetching remote images: URL autogenerated​

Another way to specify an input is the sample configuration below:

tcbuild.yaml
# Sample configuration input, specifying parameters for URL autogeneration:
input:
easy-installer:
toradex-feed:
version: "5.3.0"
release: quarterly
machine: colibri-imx6
distro: torizon-upstream
variant: torizon-core-docker
build-number: "7"
#build-date: "202107"

The build command then autogenerates the URL shown in the remote parameter of the Fetching Remote Images section. For monthly and nightly releases the parameter build-date is needed.

Splash Screen​

To customize the splash screen, insert the configuration below:

tcbuild.yaml
#Sample customization: insert a Splash Screen
customization:
# >> Splash screen:
splash-screen: splash.png

The file splash.png should be available before running the build command. A demo image can be downloaded by clicking on the button below:

Example Splash Screen Image

Check the Splash Screen on TorizonCore article for more details.

Device Tree​

This customization can be used both with Toradex's device trees and overlays as well as any other compatible device tree and overlay. The files containing the source code of the device trees and overlays should be available before running the build command.

You just need to execute this once. In order to clone the right branch of the repository, you should first download an image and unpack it accordingly with your device.

If you have not unpacked an image yet, download a base TorizonCore image (preferably without containers) inside the TorizonCore Builder working directory, then run the command below to unpack it. In the example below the torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar image is used as a reference:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar

If you want to change the TorizonCore base image, download the new image and run the images unpack command again, passing the new image as the argument.

For more details about the images unpack command, please check the images unpack command in the commands manual.

Instead of using the images unpack you can use the images download command. This command checks which is the connected Toradex SoM, downloads the compatible latest quarterly release of a TorizonCore image without containers, and unpacks this image.

$ torizoncore-builder images download --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

For more details on how the images download command works, please check the images download command in the commands manual.

Then, to get the source code of the Toradex supplied device tree files (including overlays), one could use the command below:

$ torizoncore-builder dt checkout

For more details about the dt checkout command, please check the dt checkout command in the commands manual.

To see the available device trees and select the appropriate one for your device, run the command below, passing the parameter -name accordingly to your device.

$ find device-trees/dts-arm32 -name "*imx6q-apalis*.dts"

device-trees/dts-arm32/imx6q-apalis-ixora-v1.2.dts
device-trees/dts-arm32/imx6q-apalis-ixora.dts
device-trees/dts-arm32/imx6q-apalis-ixora-v1.1.dts
device-trees/dts-arm32/imx6q-apalis-eval.dts

Then to check the available overlays names for a particular device tree (imx6dl-colibri-eval-v3.dtb in this case), run the command below:

$ torizoncore-builder dto list --device-tree ./device-trees/dts-arm32/imx6dl-colibri-eval-v3.dts

Overlays compatible with device tree imx6dl-colibri-eval-v3.dts:
- device-trees/overlays/colibri-imx6_atmel-mxt-adapter_overlay.dts
- device-trees/overlays/colibri-imx6_atmel-mxt-connector_overlay.dts
- device-trees/overlays/colibri-imx6_hdmi_overlay.dts
- device-trees/overlays/colibri-imx6_parallel-rgb-lvds_overlay.dts
- device-trees/overlays/colibri-imx6_parallel-rgb_overlay.dts
- device-trees/overlays/colibri-imx6_stmpe-ts_overlay.dts
- device-trees/overlays/display-dpi-lt170410_overlay.dts
- device-trees/overlays/display-edt5.7_overlay.dts
- device-trees/overlays/display-edt7_overlay.dts
- device-trees/overlays/display-fullhd_overlay.dts
- device-trees/overlays/display-lt161010_overlay.dts
- device-trees/overlays/display-vga_overlay.dts

Then to include the device tree and the overlays in the image, use the customization below:

tcbuild.yaml
#Sample customization: insert the resistive 7" display overlay in the IMX6 device tree with Aster Carrier Board
customization:
device-tree:
include-dirs:
- device-trees/include/
custom: device-trees/dts-arm32/imx6dl-colibri-eval-v3.dts
overlays:
add:
- device-trees/overlays/display-edt7_overlay.dts

See the following articles for more information:

Also, for more details on how the dt commands work, please check the dt command in the commands manual.

Kernel Modules​

The build command allows you to build and install kernel modules into the deployed OS image. This is demonstrated in this configuration:

tcbuild.yaml
# Sample customization: build hello-mod module into the image
customization:
kernel:
modules:
- source-dir: hello-mod/
autoload: no

The directory hello-mod containing the source code files of the kernel modules should be available before running the command. To get the hello-mod module from our Github repository, run the command below:

$ git clone https://github.com/toradex/hello-mod

For more general information about the subject, please refer to Building External Kernel Modules With Torizon article.

Kernel Arguments (Parameters)​

Kernel arguments (parameters) can be included in the OS image or modified, if they already exist, with the build command. This is done in the configuration file below:

tcbuild.yaml
# Sample customization: include or change (if already exists) key1 and key2 kernel arguments
customization:
kernel:
arguments:
- key1=val1
- key2=val2

For more general information about the subject, please refer to Customizing Kernel Arguments in Torizon article.

Capturing Configuration Changes in the Target Device​

If the user made configuration changes on TorizonCore in the SoM, this command is necessary to capture them. For more details about what it does and for which cases it is applicable, please check the Typical Use Cases section.

To capture the configuration changes made in the target device, run the command below:

$ torizoncore-builder isolate --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --changes-directory changes1

Then to include these changes in the image, use the customization below:

tcbuild.yaml
#Sample customization: insert the configuration changes made in the device
customization:
filesystem:
- changes1/

See the Capturing Changes in the Configuration of a Board on TorizonCore article for detailed instructions.

Also, for more details on how the isolate command works, please check the isolate command in the commands manual.

Pre-provisioning Docker Container Images​

The build command also simplifies the process of bundling container images into an installer image. A sample configuration leveraging that feature is this:

tcbuild.yaml
#Sample customization: insert pre-provisioned Docker container images
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
bundle:
compose-file: custom/docker-compose.yml

With such an input, the tool will fetch the container images referenced by the specified docker-compose.yml file and combine them with the installer image.

A sample Docker Compose YAML file can be downloaded, based on your device, by clicking in one of the links below:

Pre-provisioning Docker Container Images: Pre-bundled Container Images​

If you don't want the tool to download the images every time the build command is run, you can pass a directory with the pre-bundled container images instead of the Docker Compose file as a parameter.

To create a tarball with the container images from a Docker Compose file, in the directory bundle, use the command below:

$ torizoncore-builder bundle docker-compose.yml --bundle-directory bundle --platform linux/arm/v7

Then to include these pre-bundled container images in the image, through the directory, use the configuration below:

tcbuild.yaml
#Sample customization: insert pre-provisioned Docker container images with pre-built container images
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
bundle:
dir: bundle/

Find more details in the Pre-provisioning Docker Containers onto a TorizonCore image article.

For more details on how the bundle command works, please check the bundle command in the commands manual.

Building The Custom Image of TorizonCore​

To run the tool one would simply execute:

$ torizoncore-builder build

...
1091 metadata, 12741 content objects imported; 412.2 MB content written
Pulling done.
Deploying OSTree with checksum 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
Deploying done.
Copy files not under OSTree control from original deployment.
Packing rootfs...
Packing rootfs done.

=>> Build command successfully executed!

Once the build process finishes, the custom Easy Installer image would be present in the directory defined in the local of the output section of the configuration file, as it can be seen in the Minimal Configuration File section.

Different configuration file name​

The default configuration file used is the tcbuild.yaml file, created in the Creating a Configuration file section. In case of using a configuration file with a different name, run the command specifying the configuration file name:

$ torizoncore-builder build -f <configuration_file_name>
Variable substitution​

A feature that can be especially useful in CI scripts is called variable substitution which allows the replacement of property values (or parts of them) based on parameters passed on the command line of the tool. To use this feature, click on the link below and follow the steps.

Variable Substitution

The following configuration file employs that feature:

tcbuild.yaml
# Sample configuration input with variable substitution
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-with-containers
name: "${IMAGE_NAME-Default image name}"
description: "${IMAGE_DESC?Please provide a description for this image}"

The value of the property output/easy-installer/name in the example is set to the value of variable IMAGE_NAME or to "Default image name" when the variable is not set. The property output/easy-installer/description depends on IMAGE_DESC which is required and if not set will cause the tool to exit showing the specified message. Running the build command by itself would fail like this:

$ torizoncore-builder build

Building image as per configuration file 'tcbuild.yaml'...

** Exiting due to user-defined error: Please provide a description for this image

In order to successfully build an image with the previous configuration file (using the default value for IMAGE_NAME), one could run:

$ torizoncore-builder build --set IMAGE_DESC="This is the required description"

For more information on the notation for replacing variables in the configuration file, please refer to the build command Detailed Manual.

Deploying The Custom Image Of TorizonCore​

The output image can be deployed in three ways to the board:

  • Using Toradex Easy Installer, the recommended method for production programming.
  • Directly on the board through SSH, the recommended method during development.
  • Through Torizon Platform Services server, the recommended method to perform updates on a device already deployed to the field.
info

Despite the recommendations, it is also possible to use a different method, using the Torizon Platform Services method during development for example.

To learn more about when to use each method, please refer to the Deployment Methods Comparison section of the TorizonCore Builder - Workflow article.

Toradex Easy Installer​

Toradex Easy Installer Tool allows users to install an image into the internal flash memory of Toradex modules in an extremely simple way.

Copy the output image into a USB stick and follow the steps in the Toradex Easy Installer article linked above. The copy of the output image can be done with the command below:

$ cp -a torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM /media/user/myUSBstick

Where, in my case, /media/user/myUSBstick is the path to USB stick mount point and torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM is the directory containing the custom Toradex Easy Installer image.

Directly, through SSH​

In this case, before deployment the output image needs to be unpacked, using the command below:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the argument torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM to the directory containing your custom Toradex Easy Installer image.

For more details on how this command works, please check the images unpack command in the commands manual.

To deploy it directly to the board, through SSH, use the command below:

$ torizoncore-builder deploy --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --reboot

For more details on how this command works, please check the deploy command in the commands manual.

Change the arguments --remote-host,--remote-username and --remote-password to your board IP Address, username and password, respectively.

tip

From TorizonCore Builder 3.1.0 after, the default value of --remote-username and --remote-password is torizon, so if the username or the password is torizon the argument can be omitted.

caution

This way does not support the deployment of the pre-provisioned containers.

Torizon Platform Services​

In this case, before deployment the output image needs to be unpacked, using the command below:

$ torizoncore-builder images unpack torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the argument torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM to the directory containing your custom Toradex Easy Installer image.

For more details on how this command works, please check the images unpack command in the commands manual.

To deploy it to the Torizon Platform Update Service, use the command below:

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

For more details on how this command works, please check the platform push command documentation in the Commands Manual.

caution

This way does not support the deployment of the pre-provisioned containers, so their Docker Compose file will need to be deployed separately in the server.

To deploy the image from the Torizon Platform Remote Update Service to the board, please follow the steps in the OTA Web Interface article.

To obtain credentials (credentials.zip file) and to obtain more information on how to sign and securely deploy a custom image using Torizon Platform Updates, check the Signing and pushing the image to Torizon OTA article.

Verifying The New Custom Image On The Device​

After rebooting, in your target device's terminal, verify that your new custom image of TorizonCore is active on the device with the command below:

# sudo ostree admin status

Password:
* torizon 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a.0
Version: 5.3.0+build.7-tcbuilder.20211008140217
origin refspec: tcbuilder:58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a
torizon 36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc.0 (rollback)
Version: 5.3.0+build.7
origin refspec: tcbuilder:36ad904617b170339b6ded7b9dce87ed8cf0f76473b897fdd832d91e82eb1ddc

Where 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a is the OSTree commit hash and should be the same as the one in the "Deploying OSTree with checksum ..." part of the output of the build command.

Additional Resources​

Proceed to the Documentation tab on this page.

Send Feedback!