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

Customize Torizon OS Images

Introduction​

This article will guide you through the first steps for using TorizonCore Builder to customize Torizon OS images.

Prerequisites​

Set up Development Environment​

TorizonCore Builder runs inside a Docker container, mounting your current directory into it. This means it only has access to files within that directory.

To ensure all required files are accessible, we recommend the following:

  1. Create a dedicated project directory that contains everything required for customization.
  2. Source the tcb-env-setup.sh script from within this directory.

An example project directory structure is as follows:

.
├── linux
├── device-trees
│  └── overlays
│       └── verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dts
├── tcbuild.yaml
└── torizon-docker-verdin-imx8mp-Tezi_7.3.0+build.18

Where:

  • linux contains the Linux kernel sources or headers.
  • device trees is the Toradex device tree directory.
  • tcbuild.yaml is the configuration file.
  • torizon-docker-verdin-imx8mp-Tezi_7.3.0+build.18 is the unpacked base Torizon OS image directory.
info

Unless otherwise specified, run all subsequent TorizonCore Builder commands from your project directory. This ensures the container has access to everything it needs via the mounted working directory.

For more information about the TorizonCore Builder script, see Install TorizonCore Builder.

Download Source​

TorizonCore Builder needs the source for both the Linux kernel and Toradex device trees to customize Torizon OS images.

Linux Kernel​

The Linux kernel contains the device trees and headers that both device trees and overlays might reference.

Torizon OS images are built on top of Toradex BSPs. Depending on the module, they may use the upstream Linux kernel or vendor-specific downstream kernel. For more information, see the Release Matrix page. For details about lifecycle and OS releases, see Embedded Linux Support Strategy.

From the tabs below, clone the kernel for your specific module's SoC.

git clone -b toradex_6.6-2.2.x-imx git://git.toradex.com/linux-toradex.git linux
tip

Cloning the linux or linux-toradex repositories may take a while. You can use the --depth 1 option to clone only the latest commit. For more information, see the Git documentation.

Device Trees and Overlays​

With the Linux Kernel repository cloned, you can view the available device trees for your device. From the tabs below, select the appropriate one for your device:

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

For a complete list of device trees, see Device Trees on Toradex System on Modules.

Toradex provides device trees for different carrier boards. Device tree overlays that enable peripherals such as displays and cameras are also provided. From the tabs below, clone the kernel for your specific module's SoC.

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

You can check the available overlays for your device tree by passing a carrier board-level device tree to the torizoncore-builder dto list command. For example, for the imx6dl-colibri-eval-v3.dtb file, run the following command:

torizoncore-builder dto list --device-tree ./linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts
info

Make sure to copy the full path of the device tree file. Device trees for different modules may be in different paths.

Download a Torizon OS image​

To create your customized image, TorizonCore Builder also needs a Torizon OS image to use as a base. This image provides the complete root file system, kernel, and configuration that will be modified.

You can download Torizon OS images from the Download Links page:

Create a Configuration File​

You can create an initial configuration file with the following command:

torizoncore-builder build --create-template

The previous command will create a tcbuild.yaml file containing all possible configuration parameters accepted by the command. TorizonCore Builder expects this configuration file to be named tcbuild.yaml. For more information, see the Configuration File page.

As an example, below is a minimal configuration file that customizes an image for the Verdin iMX8M Plus. This custom tcbuild.yaml file does the following:

  • Uses the imx8mp-verdin-wifi-dahlia.dts device tree (instead of the default imx8mp-verdin-wifi-dev.dts).
  • Applies the verdin-imx8mp-dsi-7inch-overlay.dts overlay.
tcbuild.yaml
input:
  # Target image
  easy-installer:
      local: torizon-docker-verdin-imx8mp-Tezi_7.3.0+build.18
customization:
  device-tree:
    include-dirs:
    # Folder that contains common kernel header files like gpio.h
      - linux/include
    # Folder containing overlays included by verdin-imx8mp-dsi-7inch-overlay.dts
      - device-trees/overlays
    # Top-level device tree source file that will be used.
    # This file's name includes the name of the target SoC and carrier board.
    # Note that we are including a a device tree source file (dts) and not a dtsi file.
    custom: linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-wifi-dahlia.dts
      add:
      # Overlay to be applied
        - device-trees/overlays/verdin-imx8mp-dsi-7inch-overlay.dts

output:
easy-installer:
    # Output folder
    local: custom-torizon-docker-verdin-imx8mp
    # Image name
    name: Torizon OS - DSI 7" Touch

The snippet below considers a project folder structured as follows:

.
├── linux
├── device-trees
│  └── overlays
│       └── verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dts
├── tcbuild.yaml
└── torizon-docker-verdin-imx8mp-Tezi_7.3.0+build.18

Build the Custom Image​

To build the image, you can simply run:

torizoncore-builder build

If you are using a file name different from tcbuild.yaml, specify it with the -f flag:

torizoncore-builder build -f <configuration_file_name>

If the build completes successfully, TorizonCore Builder commits the changes to an OSTree repository. You can use the commit checksum later to verify that your device is running your custom image. The commit checksum is highlighted in the output example below:

torizoncore-builder build output
  Building image as per configuration file 'tcbuild.yaml'...

  =>> Handling input section
  Copying Toradex Easy Installer image.
  Unpacking TorizonCore Toradex Easy Installer image.
  Importing OSTree revision 80078437b2cf6070717a424bb28982cf447621e93400c560da5877b89724635b from local repository...
  1285 metadata, 9777 content objects imported; 649.7 MB content written
  0 metadata, 0 content objects imported; 0 bytes content written
  Unpacked OSTree from Toradex Easy Installer image:
    Commit checksum: 80078437b2cf6070717a424bb28982cf447621e93400c560da5877b89724635b
    TorizonCore Version: 7.3.0+build.18

  =>> Handling customization section

  => Handling device-tree subsection

  => Selecting custom device-tree 'linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-wifi-dahlia.dts'
  'imx8mp-verdin-wifi-dahlia.dts' compiles successfully.
  warning: removing currently applied device tree overlays
  Device tree imx8mp-verdin-wifi-dahlia.dtb successfully applied.

  => Adding device-tree overlay 'device-trees/overlays/verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dts'
  'verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dts' compiles successfully.
  /tmp/tmpz82gq6x4: Device Tree Blob version 17, size=90080, boot CPU=0, string block size=7160, DT structure block size=82864
  'verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dtbo' can successfully modify the device tree 'imx8mp-verdin-wifi-dahlia.dtb'.
  Overlay verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dtbo successfully applied.

  =>> Handling output section
  Applying changes from STORAGE/dt.
  Commit 18b812aba3a51cdeb53d8413848a64c6fd7c550c48760604538592bae2887045 has been generated for changes and is ready to be deployed.
  Deploying commit ref: tcbuilder-20250814200735
  Pulling OSTree with ref tcbuilder-20250814200735 from local archive repository...
    Commit checksum: 18b812aba3a51cdeb53d8413848a64c6fd7c550c48760604538592bae2887045
    TorizonCore Version: 7.3.0+build.18-tcbuilder.20250814200736
    Default kernel arguments: quiet logo.nologo vt.global_cursor_default=0 plymouth.ignore-serial-consoles splash fbcon=map:3

  1285 metadata, 9777 content objects imported; 649.7 MB content written
  Pulling done.
  Deploying OSTree with checksum 18b812aba3a51cdeb53d8413848a64c6fd7c550c48760604538592bae2887045
  Bootloader found in unpacked image: U-Boot
  Deploying done.
  Copy files not under OSTree control from original deployment.
  Packing rootfs...
  Packing rootfs done.

  =>> Build command successfully executed!

Deploy the Custom Image​

You can deploy your image in different ways:

  • Using Toradex Easy Installer: Install the image locally via USB stick, SD card or network.
  • With the deploycommand: Deploy your image directly through SSH with a TorizonCore lsBuilder command.
  • Using Torizon Cloud: Remotely deploy your image to one or more devices, enabling large-scale or field deployments.

Toradex Easy Installer​

TorizonCore Builder generates images compatible with Toradex Easy Installer. You can copy the generated folder to a USB stick, for example, and proceed as follows:

  1. Load Toradex Easy Installer
  2. Flash your image

SSH​

You can deploy your custom image directly to the board over SSH with the torizoncore-builder deploy command. This command replaces the active OSTree commit with a new one, while keeping the previous commits available for rollback. When you run this command, TorizonCore Builder:

  1. Finds the latest built image in your local (host machine) OSTree repository.
  2. Transfers only the missing objects to the board via SSH.
  3. Registers the new commit for the next boot.
info

This operation only alters the OSTree, so it does not support deploying pre-provisioned containers.

To deploy your image:

  1. Unpack your image. pass the image folder generated in the build process. For example:

    torizoncore-builder images unpack torizon-docker-verdin-imx8mp-Tezi_7.3.0+build.18/

  2. Deploy your image to the board:

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

    Starting with TorizonCore Builder 3.1.0, the default values for --remote-username and --remote-password are torizon. If either the username or password is torizon, you can omit the corresponding argument.

For more information about the images unpack and deploy commands, see TorizonCore Builder Tool - Commands Manual.

Torizon Cloud​

You can also push images to Torizon Cloud using TorizonCore Builder commands. This method allows you to update devices in the field remotely, without physical access.

info

This operation does not support deploying pre-provisioned containers.

The steps are as follows:

  1. Unpack your image. Pass the image folder generated in the build process. For example:

    torizoncore-builder images unpack torizon-docker-verdin-imx8mp-Tezi_7.3.0+build.18/

  2. Get a Torizon Cloud credentials file.

  3. Deploy your image to Torizon Cloud:

    torizoncore-builder platform push --credentials credentials.zip --package-name <PACKAGE_NAME> --package-version <PACKAGE_VERSION> <UNPACKED-DIRECTORY>

  4. Remotely deploy your device.

Confirm the Image Deployment​

After deploying your custom image, you can check whether it contains the same OSTree commit TorizonCore Builder generated.

To confirm your image deployment, run the following command on your target device:

# sudo ostree admin status

*  torizon 80078437b2cf6070717a424bb28982cf447621e93400c560da5877b89724635b.0
    Version: 7.3.0+build.18
    origin refspec: tcbuilder:80078437b2cf6070717a424bb28982cf447621e93400c560da5877b89724635b
  torizon 95dd4ed187473a623a5989ad9d44ff7528fb96f638f26dc2e3102b8584fa583d.0 (rollback)
    Version: 7.3.0+build.18-tcbuilder.20250725030111
    origin refspec: torizon

The output lists OSTree commits. Note that the latest and active commit is the one generated in the Build the Custom Image step.

Send Feedback!