Customizing an image with Torizon Core Builder

From RidgeRun Developer Wiki





Follow Us On Twitter LinkedIn Email Share this page


NXP i.MX95
Table of Contents [Sticky]


Preferred Partner Logo 3



Install TorizonCore Builder and Build Custom Torizon OS Images

Introduction

This page shows the overall process of customizing a Torizon OS image with Toradex Core Builder

At a high level, the process is:

  1. Prepare the Linux development machine with the required dependencies.
  2. Install and initialize TorizonCore Builder.
  3. Organize a project directory containing all customization inputs.
  4. Obtain the sources and base image required for customization.
  5. Create and edit a tcbuild.yaml configuration file.
  6. Run the build process to generate a custom image.
  7. Deploy the resulting image using Toradex Easy Installer, SSH, or Torizon Cloud.
  8. Verify that the deployed image matches the generated OSTree commit.

Linux Host Requirements

Your Linux development machine must provide:

  • Docker Engine
  • A Bash shell environment
  • SELinux disabled on distributions where it is enabled by default, such as Fedora
TorizonCore Builder is primarily intended to be used from Bash. Other shells may work, but they are not officially guaranteed.

Install TorizonCore Builder

Create a writable working directory, download the setup script, and source it: 

mkdir -p ~/tcbdir/ && cd ~/tcbdir/
wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh

cd ~/tcbdir/
source tcb-env-setup.sh

Sourcing the setup script does the following:

  • Mounts the current directory into the TorizonCore Builder container
  • Creates a Docker volume named storage for internal tool state, unpacked images, artifacts, and metadata
  • Enables Bash completion for the torizoncore-builder command

The first time you source the script, the output should look like the following: 

TorizonCore Builder is not installed. Pulling the latest version from Docker Hub...
Setting up TorizonCore Builder with version 3.

Pulling TorizonCore Builder...
3: Pulling from torizon/torizoncore-builder
17506cf4b1b4: Pull complete 
b8a01e377f9b: Pull complete 
d377482a9262: Pull complete 
0d7ae4096be9: Pull complete 
d0ff22a59d7d: Pull complete 
7922c1285cd0: Pull complete 
ddbc799f3aa1: Pull complete 
0ebdfaea376f: Pull complete 
53169aaa8556: Pull complete 
26cf267d0c1c: Pull complete 
f2160f89f74d: Pull complete 
bbf176b9336a: Pull complete 
8b3fdcf7db93: Pull complete 
f9d43853e9c9: Pull complete 
15c8046bf82a: Pull complete 
6f70b09add96: Pull complete 
07b3e2bcfeae: Pull complete 
020da16a0be1: Pull complete 
4752dfb63bec: Pull complete 
66f85ac782da: Pull complete 
4151984e74ab: Pull complete 
Digest: sha256:b9c854de01337c597473189a99b5c6e983fbc431a85a6a0a6414d1cbd34d3794
Status: Downloaded newer image for torizon/torizoncore-builder:3
docker.io/torizon/torizoncore-builder:3
Done!

Setup complete! TorizonCore Builder is now ready to use.
TorizonCore Builder internal status and image customizations will be stored in Docker volume named 'storage'.
********************
Important: When you run TorizonCore Builder, the tool can only access the files inside the current working directory. Files and directories outside of the current working directory, or links to files and directories outside of the current working directory, won't be visible to TorizonCore Builder. So please make sure that, when running TorizonCore Builder, all files and directories passed as parameters are within the current working directory.
Your current working directory is: /home/chidalgo/work/devdirs/imx95-rnd/torizoncorebuilder/tcbdir
********************
For more information, run 'torizoncore-builder -h' or go to https://developer.toradex.com/knowledge-base/torizoncore-builder-tool

After sourcing the environment, verify that the command is available: 

torizoncore-builder --help

the help on this command is the following: 

usage: torizoncore-builder [-h] [--verbose] [--log-level LOG_LEVEL] [--log-file LOG_FILE]
                           [-v]
                           {build,bundle,combine,deploy,dt,dto,images,isolate,kernel,ostree,platform,push,secboot,splash,ubootenv,union}
                           ...

TorizonCore Builder is an utility that allows to create customized TorizonCore OSTree
commits and Toradex Easy Installer images without rebuilding the complete operating
system.

optional arguments:
  -h, --help            show this help message and exit
  --verbose             show more output
  --log-level LOG_LEVEL
                        set global log level (debug, info, warning, error, critical)
  --log-file LOG_FILE   write logs to a file instead of console
  -v, --version         show program's version number and exit

Commands:
  {build,bundle,combine,deploy,dt,dto,images,isolate,kernel,ostree,platform,push,secboot,splash,ubootenv,union}
    build               Customize a Toradex Easy Installer image based on settings
                        specified via a configuration file.
    bundle              Create container bundle from a Docker Compose file. Can be used
                        to combine with a TorizonCore base image.
    combine             Combines a container bundle with a specified Torizon OS image
                        (Toradex Easy Installer or raw/WIC)
    deploy              Deploy unpacked image as a Toradex Easy Installer image or raw
                        disk format.
    dt                  Manage device trees
    dto                 Manage device tree overlays
    images              Manage Toradex Easy Installer Images.
    isolate             capture /etc changes.
    kernel              Manage and modify TorizonCore Linux Kernel.
    ostree              OSTree operational commands
    platform            Execute operations that interact with the Torizon Platform
                        Services (app.torizon.io) or a compatible server
    push                Push artifact to OTA server as a new update package.
    secboot             Sign different components of an unpacked Torizon OS image in
                        Toradex Easy Installer format.
    splash              change splash screen
    ubootenv            Manage U-Boot environment for Torizon OS images.
    union               Create a commit out of isolated changes for unpacked Toradex Easy
                        Installer Image

Learn more on https://developer.toradex.com/knowledge-base/torizoncore-builder-tool

What the Build Workflow Does

Torizon Core Builder allows for different customizations. Typical customizations include:

  • Device tree changes
  • Device tree overlays
  • Splash screens
  • External kernel modules
  • Configuration captured from a device
  • Application container configuration

The build is driven by a YAML file, usually named tcbuild.yaml, which defines:

  • The input image
  • The modifications to apply
  • The desired output image

Set Up a Project Directory

TorizonCore Builder runs inside a Docker container and only sees files that are inside the directory mounted when the environment is sourced. For that reason, all build inputs should be placed under a dedicated project directory.

A typical layout looks like this: 

.
├── linux
├── device-trees
│  └── overlays
│       └── verdin-imx95_dsi-to-hdmi_overlay.dts
├── tcbuild.yaml
└── torizon-docker-verdin-imx95-Tezi_7.5.0+build.30

Where:

  • linux contains the kernel source tree or headers
  • device-trees contains Toradex device tree material
  • tcbuild.yaml is the build configuration
  • torizon-docker-verdin-imx95-Tezi_7.5.0+build.30 is the unpacked base Torizon OS image

Download the Required Sources

To customize images, TorizonCore Builder may need access to:

  • A splash screen image
  • Device tree and overlay source files
  • Source code for external kernel modules
  • Captured configuration files
  • Application container configuration
  • A base Torizon OS image in Easy Installer format

Linux Kernel Source

The Linux kernel source tree provides headers and referenced include files used by device trees and overlays.

Torizon OS is based on Toradex BSP releases. Depending on the module, the kernel may be upstream or downstream. For supported combinations and lifecycle details, consult the relevant Toradex release documentation.

For example, for selected i.MX 8 family targets: 

git clone -b toradex_6.6-2.2.x-imx git://git.toradex.com/linux-toradex.git linux --depth 1
--depth 1 is used to fetch only the latest commit to shorten clone time.

Device Trees and Overlays

After cloning the kernel, you can inspect available device trees for your target platform. For example: 

find linux -name "*imx95-verdin*.dts"

#example output
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-dev.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-dahlia.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-wifi-mallow.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-wifi-dev.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-ivy.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-mallow.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-yavia.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-wifi-ivy.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-wifi-dahlia.dts
./linux/arch/arm64/boot/dts/freescale/imx95-verdin-wifi-yavia.dts

Toradex also provides device tree overlays in a separate repository. For example: 

git clone -b toradex_6.6-2.2.x-imx git://git.toradex.com/device-tree-overlays.git device-trees

To list compatible overlays for a given device tree, use: 

torizoncore-builder dto list --device-tree ./linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-dev.dts

#example output
Overlays compatible with device tree imx95-verdin-nonwifi-dev.dts:
- device-trees/overlays/verdin-imx95_dsi-to-hdmi_overlay.dts
- device-trees/overlays/verdin-imx95_dsi-to-lvds_panel-cap-touch-10inch-lvds_overlay.dts
- device-trees/overlays/verdin-imx95_mezzanine_panel-cap-touch-10inch-lvds_overlay.dts
- device-trees/overlays/verdin-imx95_mezzanine_panel-lvds-dual-channel-1080p_overlay.dts
- device-trees/overlays/verdin-imx95_nau8822-btl_overlay.dts
- device-trees/overlays/verdin-imx95_ov5640_overlay.dts
- device-trees/overlays/verdin-imx95_panel-cap-touch-10inch-dsi_overlay.dts
- device-trees/overlays/verdin-imx95_panel-cap-touch-10inch-lvds_overlay.dts
- device-trees/overlays/verdin-imx95_panel-cap-touch-7inch-dsi_overlay.dts
- device-trees/overlays/verdin-imx95_reserve-cm7-uart_overlay.dts
- device-trees/overlays/verdin-imx95_spidev_overlay.dts
Use the full path to the selected device tree source file, since DTS paths differ between SoCs and module families.

Obtain a Base Torizon OS Image

To generate a custom image, TorizonCore Builder needs a base Torizon OS image.

When choosing the image:

  • Use a Torizon OS 7.x image matching your target needs
  • Prefer a recent quarterly release for stability
  • Avoid images that already include evaluation or pre-provisioned containers

The input image should not contain bundled container images if it will be used as the source for customization.

Input Images: Local or Remote

TorizonCore Builder supports two main ways of supplying the base image:

  • A local Easy Installer archive or unpacked image
  • A remote image fetched directly from the Toradex artifacts server

Using a Local Image

A minimal configuration using a local image may look like this: 

input:
  easy-installer:
    local: images/torizon-docker-verdin-imx95-Tezi_7.5.0+build.30.tar

output:
  easy-installer:
    local: torizon-docker-verdin-imx95-Tezi_7.5.0.CUSTOM

Example project structure: 

.
├── images
│   └── torizon-docker-verdin-imx95-Tezi_7.5.0
└── tcbuild.yaml
The input image must not include bundled application containers.

Using a Remote Image with a Hard-Coded URL

Instead of manually downloading the image, you can specify the full URL: 

input:
  easy-installer:
    remote: "https://tezi.toradex.com/artifactory/torizoncore-oe-prod-frankfurt/scarthgap-7.x.y/release/30/verdin-imx95/torizon/torizon-docker/oedeploy/torizon-docker-verdin-imx95-Tezi_7.5.0+build.30.tar"

The optional sha256sum parameter is used to verify the integrity of the downloaded artifact. If the checksum does not match, the process stops.

Another complete example with output settings: 

input:
  easy-installer:
    remote: "https://tezi.toradex.com/artifactory/torizoncore-oe-prod-frankfurt/scarthgap-7.x.y/release/30/verdin-imx95/torizon/torizon-docker/oedeploy/torizon-docker-verdin-imx95-Tezi_7.5.0+build.30.tar"

output:
  easy-installer:
    local: torizon-docker-verdin-imx95-Tezi_7.5.0.CUSTOM
    name: "My customized image"

Create a Configuration File

To generate a template configuration with all supported parameters, run: 

torizoncore-builder build --create-template

This creates a tcbuild.yaml file. Although another filename can be used later with the -f option, tcbuild.yaml is the conventional and expected default.

Minimal Configuration Requirements

A valid build configuration must define at least:

  • One input
  • One output

Example: Device Tree Customization

The following example customizes a Verdin iMX8M Plus image by:

  • Selecting imx95-verdin-nonwifi-dev.dts as the main device tree
  • Adding the verdin-imx95_dsi-to-hdmi_overlay.dts overlay
input:
  easy-installer:
      local: torizon-docker-verdin-imx95-Tezi_7.5.0+build.30

customization:
  device-tree:
    include-dirs:
      - linux/include
      - device-trees/overlays
    custom: linux/arch/arm64/boot/dts/freescale/imx95-verdin-nonwifi-dev.dts
    overlays:
      add:
        - device-trees/overlays/verdin-imx95_dsi-to-hdmi_overlay.dts

output:
  easy-installer:
    local: custom-torizon-docker-verdin-imx95
    name: Torizon OS - DSI TO HDMI

This assumes a project structure like: 

.
├── linux
├── device-trees
│  └── overlays
│       └── verdin-imx95_dsi-to-hdmi_overlay.dts
├── tcbuild.yaml
└── torizon-docker-verdin-imx95-Tezi_7.5.0+build.30

Run the Build

Once the configuration and inputs are ready, build the custom image with: 

torizoncore-builder build

If your configuration file has a different name: 

torizoncore-builder build -f <configuration_file_name>

If the command was succesful, you see a message like the following at the end: 

=>> Build command successfully executed!

If the build succeeds, TorizonCore Builder writes the changes into an OSTree repository and reports the resulting commit checksum. That checksum can later be used to verify that the target device is actually running the built image.

Deploy the Custom Image

There are three typical deployment paths:

  • Toradex Easy Installer
  • SSH deployment with torizoncore-builder deploy
  • Torizon Cloud

Deploy with Toradex Easy Installer

The generated output is compatible with Toradex Easy Installer. A common workflow is to copy the produced image directory to a USB drive or otherwise make it available to the installer, then:

  1. Boot Toradex Easy Installer
  2. Select the generated image
  3. Flash the module

Deploy over SSH

You can also deploy directly over SSH. In this mode, TorizonCore Builder updates the device’s active OSTree commit while preserving previous commits for rollback.

Before deploying, unpack the image: 

torizoncore-builder images unpack torizon-docker-verdin-imx95-Tezi_7.5.0+build.30

Then deploy it: 

torizoncore-builder deploy --remote-host <BOARD-IP> --remote-username <USERNAME> --remote-password <PASSWORD> --reboot

What this deployment does:

  • Finds the newest built image in the host OSTree repository
  • Transfers only missing OSTree objects to the device
  • Registers the new commit for the next boot
This method only updates the OSTree content. It does not deploy pre-provisioned containers.

Confirm the Deployed Image

After deployment, verify that the device is booting the OSTree commit produced during the build.

On the target device, run: 

sudo ostree admin status

Example output: 

* torizon 288b719a297f1ab75d95a166b1b916cdbbc4f65a7fb75f796e0ca9fbad6c81df.0               
  Version: 7.5.0+build.30-tcbuilder.20260316174306                                       
  origin refspec: torizon

The active entry should match the commit generated by the build process. The rollback entry represents the previous version preserved on the system.



Retrieved from "https://developer.ridgerun.com/wiki/index.php?title=NXP_i.MX95_Technical_Guide/Customizing_an_image_with_Torizon_Core_Builder&oldid=78147"