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

Configuration File

Introduction​

With TorizonCore Builder, you can customize Torizon OS images by:

  1. Creating a YAML configuration file that defines the changes you want to apply, such as device tree overlays, splash screens, kernel modules and more.
  2. Generating a custom image using the build command.

This article describes the customization options available through the YAML configuration file, covering the following use cases:

For more information about TorizonCore Builder commands, see TorizonCore Builder Tool - Commands Manual.

Prerequisites​

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. The configuration file is in YAML format, which is compatible with most modern code editors. Most parameters in the generated file are commented out with # character at the beginning of each line. You will also see lines that begin with >>, which provide inline explanations — these are optional and can be left as-is or removed.

The file structure follows a nested tree, where each leaf is a configurable property. To enable a setting, you must uncomment the relevant line and all its parent levels by removing the leading #. A valid configuration file consists of three main sections, represented by top-level keys:

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

Modify the OS Splash Screen​

To customize the splash screen, add the highlighted line under the customization section of your tcbuild.yaml:

tcbuild.yaml
customization:
  # >> Splash screen:
  splash-screen: splash-screen.png

Note that your splash-screen.png file must be placed in the same folder as tcbuild.yaml. For information about supported splash screen formats and other customization methods, see Splash Screen on Torizon OS.

Switch Device Trees​

By default, the bootloader (U-Boot) selects the device trees for development carrier boards. For example, the default device trees for Verdin SoMs are the Verdin Development Board device trees, with source files ending in *-verdin-wifi-dev.dts. To use a device tree for a different carrier board, you can specify it with the device-tree property. For example:

tcbuild.yaml
# 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
customization:
  device-tree:
    custom: linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-wifi-dahlia.dts

To learn how to get the Linux kernel source code and locate the appropriate device tree file for your carrier board, see Customize Torizon OS Images. For more information about device trees, see Device Tree Technical Overview.

Apply Device Tree Overlays​

To include device tree overlays to the image, use the overlays property. For example:

tcbuild.yaml
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
    overlays:
      add:
      # Overlay to be applied
        - device-trees/overlays/verdin-imx8mp-dsi-7inch-overlay.dts

Depending on the header files your device tree overlay includes, such as shared macros or macros, you may also need to specify directories in the build environment using the include-dirs property. This lets TorizonCore Builder locate all dependent files during compilation. For more information, see Customize Torizon OS Images.

To understand the technical aspects of device tree overlays, see Device Tree Overlays Technical Overview.

Install Kernel Modules​

TorizonCore Builder can build and install external kernel modules in your custom OS image. Specify the module's source directory in the configuration file, as shown below:

tcbuild.yaml
customization:
  kernel:
    modules:
      - source-dir: <kernel-module-repository/>
        autoload: no

Note that your kernel-module-repository/ must be in the same folder as tcbuild.yaml. The autoload property indicates whether the modules should load at startup. For more information, see Building External Kernel Modules with Torizon.

Modify Kernel Arguments​

You can modify or include kernel arguments (parameters) in OS images through your tcbuild.yaml. For example:

tcbuild.yaml
customization:
  kernel:
    arguments:
      - console=ttyLP0,115200
      - loglevel=3

For more information, see Customizing Kernel Arguments in Torizon.

Capture Configuration Changes​

If you have made manual modifications on your Torizon OS device—such as changing the device hostname, disabling services, or changing file permissions—you can preserve those changes and include them in a custom OS image.

To capture the configuration changes made on the target device:

  1. Run the torizoncore-builder isolate command:

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

    For details on how the isolate command works, see the Commands Manual.

  2. Include these changes in the image through the configuration file:

    tcbuild.yaml
    #Sample customization: insert the configuration changes made in the device
    customization:
      filesystem:
        - <path-to-changes-directory>/

For more information about this feature, see Capturing Changes in the Configuration of a Board on Torizon OS.

Pre-provision Container Images​

TorizonCore Builder lets you bundle Docker container images directly into your installer image.

Auto-Pull Containers​

With the configuration below, TorizonCore Builder reads the specified docker-compose.yml file, pulls the referenced container images, and packages them along with the base Torizon OS image.

tcbuild.yaml
#Sample customization: insert pre-provisioned Docker container images
output:
  easy-installer:
    local: <path>
    bundle:
      compose-file: custom/docker-compose.yml

Pre-bundled Directories​

If you do not want TorizonCore Builder to download container images every time you build your image, you can pre-download (pre-bundle) them and reference the resulting directory directly in your configuration.

To create a pre-bundled container image directory from a Docker Compose file:

  1. Run the torizoncore-builder bundle command, pointing to the Docker Compose file you want to bundle. For example:

    torizoncore-builder bundle docker-compose.yml --bundle-directory bundle --platform linux/arm64

    This command downloads all container images referenced in docker-compose.yml and saves them to a directory named bundle/. For details on how the command works, see the Commands Manual.

  2. Include the pre-bundled container images in your output image. For example:

    tcbuild.yaml
    output:
        easy-installer:
        local: path/to/your/custom-image-folder
        bundle:
            dir: bundle/

For more information about this feature, see Pre-provisioning Docker Containers onto a Torizon OS image.

Fetch Remote Images​

Rather than downloading and extracting images manually, TorizonCore Builder can download them directly from the Toradex artifacts server during build time. This is useful for creating CI/CD pipelines and automating the image customization process.

Hard-Coded URL​

Manually specify the full URL of the image archive. For example:

tcbuild.yaml
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"

Note the presence of the optional sha256sum parameter. It ensures file integrity. If the checksum of the downloaded file does not match the provided value, the tool will stop the operation.

Dynamic URL​

Instead of specifying the URL manually, you can provide the image specs and let TorizonCore Builder generate the URL. To do so, set the toradex-feed property. For example:

tcbuild.yaml
input:
  easy-installer:
    toradex-feed:
      version: "5.3.0"
      release: quarterly
      machine: colibri-imx6
      distro: torizon-upstream
      variant: torizon-core-docker
      build-number: "7"
      # Required for monthly or nightly releases
      #build-date: "202107"
info

For monthly and nightly releases, the build-date is required.

Variable Substitution​

To simplify configuration file usage when some values differ between build command invocations, we provide a feature commonly offered by command line shells: variable substitution.

If the feature is enabled, all occurrences of $VAR in string values are replaced by the corresponding value of the variable named VAR, which should be provided as part of the torizoncore-builder build command line invocation.

The following notations are allowed:

  • ${VAR}: Same as $VAR; when the variable is not set in command line, torizoncore-builder will issue a warning and assume the variable value is the empty string.
  • ${VAR:-default}: If VAR is not set or empty, use default as its value.
  • ${VAR-default}: If VAR is not set, use default as its value.
  • ${VAR:?error}: If VAR is not set or is empty, issue the message error and exit the tool
  • ${VAR?error}: If VAR is not set, issue the message error and exit the tool.
tip

The notation $$ can be used to insert a single literal $ sign within strings in the configuration file.

The following is an example of a configuration file with variable substitution:

output:
  easy-installer:
    bundle:
      compose-file: "${COMPOSE_FILE:?Path to the Docker Compose file is required}"
      username: "${REGISTRY_USER?Container registry username is required}"
      password: "${REGISTRY_PASS?Container registry password is required}"
      registry: "${REGISTRY_HOST:-docker.io}"

Without setting the COMPOSE_FILE variable in the torizoncore-builder build command, you will see:

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

** Exiting due to user-defined error: Path to the Docker Compose file is required

To proceed with the build, you must provide the missing values. For example:

torizoncore-builder build \
  --set COMPOSE_FILE=docker-compose.yml \
  --set REGISTRY_USER=myusername \
  --set REGISTRY_PASS=mypassword
Send Feedback!