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

Customization Examples

Introduction​

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

Please refer to the following specific articles for additional resources:

This article complies with the Typographic Conventions for the Toradex Documentation.

Prerequisites​

Apply the Customization Examples​

The examples from this article require you to use the TorizonCore Builder build command to generate the custom image.

$ torizoncore-builder build

The produced Torizon OS image will be available at the directory configured in the output section of your YAML file. The customized image is already prepared to be flashed through the Toradex Easy Installer.

tcbuild.yaml
output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-custom-dt

Read our dedicated Build Custom Torizon OS Images article for a comprehensive explanation about building and deploying customized Torizon OS images.

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 the 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, U-Boot (the bootloader) 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 select the appropriate device tree for a different carrier board, you can specify it using the device-tree property:

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 complete 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 locate the appropriate device tree file for your carrier board on the Linux kernel source code, see Customize Torizon OS Images. For more information about device trees, see Device Tree Technical Overview.

Apply Device Tree Overlays​

Use the overlays property to include device tree overlays in the image:

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_panel-cap-touch-7inch-dsi_overlay.dts
      - device-trees/overlays
    overlays:
      add:
      # Overlay to be applied
        - device-trees/overlays/verdin-imx8mp_panel-cap-touch-7inch-dsi_overlay.dts

Depending on the header files your device tree overlay includes, such as shared macros defined in common headers, you may also need to specify include 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.

In this sample configuration file we customize the device-tree to be deployed with an image:

# Sample configuration:
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

customization:
  device-tree:
    include-dirs:
      - device-trees/include/
    custom: device-trees/dts-arm32/imx6dl-colibri-eval-v3.dts
    overlays:
      add:
        - device-trees/overlays/colibri-imx6_hdmi_overlay.dts
        - device-trees/overlays/colibri-imx6_atmel-mxt-connector_overlay.dts

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-custom-dt

This example selects the imx6dl-colibri-eval-v3.dts device tree for the image, and applies the two overlays on top of it: colibri-imx6_hdmi_overlay.dts and colibri-imx6_atmel-mxt-connector_overlay.dts.

The overlays used in this customization example are available at Toradex's device-tree-overlays repository. To get the specific overlays for your module, clone the repository following the instructions available at Build Custom Torizon OS Images.

tip

If using Git, you can also manage external device trees from your project's repository using the Git submodules tool. This ensures that all required source files are available in your project's source tree.

The directory structure for this "project" would look like this:

.
├── device-trees
│   ├── dts-arm32
│   │   ├── imx6dl-colibri-eval-v3.dts
│   ├── include
│   │   └── dt-bindings
│   │       ├── ...
│   ├── overlays
│   │   ├── ...
│   │   ├── colibri-imx6_atmel-mxt-adapter_overlay.dts
│   │   ├── colibri-imx6_atmel-mxt-connector_overlay.dts
│   │   ├── colibri-imx6_hdmi_overlay.dts
│   │   ├── colibri-imx6_parallel-rgb-lvds_overlay.dts
│   │   ├── colibri-imx6_parallel-rgb_overlay.dts
│   │   ├── ...
│   │   └── Makefile
│   └── README.md
├── images
│   └── torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar
└── tcbuild.yaml

You should get the device-trees directory subtree from the Toradex supplied device-tree files (including overlays), by cloning the repositories according to the specific instructions form our Build Custom Torizon OS Images.

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 the <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.

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

# Sample configuration: build virtual touchscreen into the image
input:
  easy-installer:
    local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0-devel-202105+build.12.tar

customization:
  kernel:
    modules:
      - source-dir: virtual_touchscreen/
        autoload: no

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-vt

After running the build command over this configuration file, the tool would build the kernel module from the sources located in the directory virtual_touchscreen and create a custom Torizon OS image in the directory torizon-core-docker-colibri-imx6-vt. The image would then be ready to be flashed through Toradex Easy Installer.

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

Modify Kernel Arguments​

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

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

For more information, see Customizing Kernel Arguments in Torizon.

Capture Device 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 on another custom OS image.

To capture the configuration changes made on the target device, run the command below - remember to replace the <remote-host-ip>, <username>, and <password> to match your target device information: :

  1. Run the torizoncore-builder isolate command:

    $ torizoncore-builder isolate --remote-host <remote-host-ip> --remote-username <username> --remote-password <password> --changes-directory <changes-dir>

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

  2. Include the extracted 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>/

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

Additionally, for more details on how the isolate command works, please check the isolate command on the Commands Manual article.

Configure Device for Torizon Cloud Provisioning​

There are cases where you want to customize an image for automatic provisioning during production programming, so your devices can be ready for using with our Torizon Cloud. The devices will automatically be registered for using our secure remote or offline update, devices monitoring, and the new features to be released.

For this, you should get the provisioning data and apply in the configuration file.

You’ll need the credentialis.zip file for the account to which you want to provision devices. Since credentials access and other sensitive data are involved, this step should be run by your system admin or those with proper access to such information.

There are two types of provisioning data:

  • Shared-Data: This type of provisioning data is used for provisioning a device for offline and online updates. This data is not security-sensitive. In our system, we distribute the data as a tarball that contains the data.
  • Online-Data: This type of provisioning data is used only in provisioning for online updates. This data is security-sensitive and should be handled carefully. In our system we distribute the data as a base64 encoded string.

In order to get either provisioning data, use the platform provisioning-data command can be used to fetch both types of provisioning data:

$ torizoncore-builder platform provisioning-data --credentials credentials.zip --shared-data shared-data.tar.gz --online-data DEFAULT

The command will then produce a tarball containing the shared-data and output the string that is the online-data. This data can then be stored for future provisioning use. For a detailed guide on the usage of this command please see the specific section in the commands manual

Now that you have obtained your provisioning data, you need to apply it. The idea here is that you want to create a single Torizon OS image that, when flashed to multiple devices, will allow each device to provision itself automatically.

A sample configuration file for applying the provisioning data is this:

input:
  easy-installer:
    local: <INPUT_IMAGE>

output:
  easy-installer:
    local: <OUTPUT IMAGE>
    provisioning:
      mode: "online"
      shared-data: <SHARED-DATA TARBALL>
      online-data: <ONLINE-DATA STRING>
      hibernated: <true|false>
caution

Recall that the online-data string is sensitive information. You'll most likely want to make use of variable substitution, rather than inserting this string in plain text in your yaml file.

For more details see the provisioning property under the Output section of the build command's yaml file schema.

Pre-Provision Containers - Pre-Install Applications​

TorizonCore Builder allows you to bundle Docker container images directly into your customized 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​

The build command also simplifies the process of bundling container images into an installer image. It is ideal for generating the image to be used during production programming and provisioning multiple devices.

If you want to install both the OS and the application during an update, you should not use the Bundling feature. Instead, you should use the synchronous update feature of Torizon Cloud.

The sample configuration file below leverages that feature:

# Sample configuration file:
input:
  easy-installer:
    remote: "https://artifacts.toradex.com:443/artifactory/torizoncore-oe-prod-frankfurt/dunfell-5.x.y/release/1/colibri-imx6/torizon-upstream/torizon-core-docker/oedeploy/torizon-core-docker-colibri-imx6-Tezi_5.1.0%2Bbuild.1.tar;sha256sum=5d11dc0b6be688f6a7d159280e9bca15e26bc58732724e3e1dd66b0d0a6ada08"

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-with-containers
    name: "My customized image with container images"
    bundle:
      compose-file: custom/docker-compose.yml

Using this feature, the tool will fetch the container images referenced by the specified docker-compose.yml file and combine them with the installer-ready image.

If you don't want the tool to download the container images at every build command, you can download them beforehand via the torizoncore-builder bundle command, and specify the bundle output directory in the output.easy-installer.bundle.dir property. This procedure is detailed in the steps below:

  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.

Next Steps​

Refer to the Detailed Manual tab for a detailed description of the build command schema and its parameters.

Send Feedback!