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

Device Tree Overlays on Torizon

Introduction​

Linux Device Tree is a data structure describing a system's hardware.

Sometimes, it is necessary to modify the Device Tree. Some use cases that require Device Tree modifications include (but not limited to):

Device Tree is built with the Kernel when building the distribution. However, Device Tree Overlays provide a way to modify the overall device tree without the need for re-compiling the complete device tree.

Overlays are small pieces, or fragments, of a complete device tree, and can be added or removed as needed, often enabling/disabling hardware components in the system.

Due to its flexible nature, overlays provide an advantageous way of describing peripheral hardware added or removed from the system. It is also useful for tweaking the existing hardware parameters before committing it to a complete device tree. You can find rich information about overlays available on the web.

In a very brief description, the process of designing for a Device Tree Overlay comprises three macro steps:

  1. Write a Device Tree Overlay (.dts) file.
  2. Build the dts file
  3. Enable the overlay

Device trees and overlays in human-readable format (dts files) must be compiled to binary format (dtb for complete device-trees, dtbo for overlays) to be parsed by the kernel.

This article will show the tools available for making and applying device tree overlays on Toradex SoMs that use Torizon OS as the operating system. If you want to use device tree overlays with our Reference Images for Yocto Project, read Build Device Tree Overlays from Source Code.

There are different phases of development with different methods for customizing Torizon OS with device tree overlays:

This article complies with the Typographic Conventions for Torizon Documentation

Prerequisites​

Checking applied overlays​

From monthly 6.1.0-devel-202212 onwards, it is possible to check if the overlays specified in overlays.txt were applied successfully. For each overlay that we try to apply, a device tree property is created and can be checked at /proc/device-tree/chosen/overlays, as a file named <device_tree_overlay_name>.dtbo. This property will have a value, and if it is 0 it means that this overlay was applied successfully. For instance, on a Verdin iMX8M Mini:

# ls /proc/device-tree/chosen/overlays/
name  verdin-imx8mm_dsi-to-lvds_panel-cap-touch-10inch-lvds_overlay.dtbo  verdin-imx8mm_spidev_overlay.dtbo
# cat /proc/device-tree/chosen/overlays/verdin-imx8mm_dsi-to-lvds_panel-cap-touch-10inch-lvds_overlay.dtbo                                                                         
0
# cat /proc/device-tree/chosen/overlays/verdin-imx8mm_spidev_overlay.dtbo                                  
0

From that we can see that the system tried to apply 2 overlays, namely verdin-imx8mm_dsi-to-lvds_panel-cap-touch-10inch-lvds_overlay.dtbo and verdin-imx8mm_spidev_overlay.dtbo, and since cat showed that both properties were 0, that means they were applied successfully.

Evaluation and Prototyping only: Quickly Enabling Displays, Touch Controllers, Adapters, and other Add-on Products Provided by Toradex​

danger

The instructions provided in this session are intended for prototype and proof-of-concept only. For production, skip directly to the next section of this article for information about TorizonCore Builder usage.

There are two possible approaches to quickly evaluate overlays on the device, by executing a TorizonCore Builder command or by changing the text of the overlays.txt file directly on the board.

Approach 1: Applying Device Tree Overlays to an Image Using a Single TorizonCore Builder Command​

If you want to quickly test a device tree overlay, you can apply the overlay on a running device with a single TorizonCore Builder command. Behind the scenes, TorizonCore Builder will execute all the steps necessary to deploy an image to your device.

Before using this command, it is necessary to install TorizonCore Builder and have the source code of the desired overlays available in the working directory.

Additional prerequisites​

Install TorizonCore Builder​

To install TorizonCore Builder, click on the link below and follow the steps.

Install TorizonCore Builder

To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.

  1. Download the setup script into some writable directory in your system (here we use ~/tcbdir/):

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

    If you did this before then you can skip this step unless you want to update the setup script. When you source the script (next step) it will show you a warning message if it determines an update is advisable.

  2. Source the script:

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

    Make sure to do this from every shell instance that you intend to use with TorizonCore Builder. For advanced usage, run source tcb-env-setup.sh -h, or see the project README. The latter has information about using the early-access version of the tool for those interested.

    tip
    • Remember to source the setup script every time you start a new terminal (or shell instance).
    • 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.

    Beware that under Windows, you must pass extra parameters to the script when the use of the following commands is intended:

  3. Verify that the command torizoncore-builder is available:

    $ torizoncore-builder --help

Clone Toradex Device Tree and Overlays Repository​

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 Torizon OS 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 Torizon OS 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 Torizon OS 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 commands below:

$ git clone -b toradex_5.15-2.2.x-imx git://git.toradex.com/linux-toradex.git linux
$ git clone -b toradex_5.15-2.2.x-imx git://git.toradex.com/device-tree-overlays.git device-trees

Select the Desired Overlay​

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 ./linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts

Overlays compatible with device tree imx6dl-colibri-eval-v3.dts:
- device-trees/overlays/colibri-imx6_hdmi_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-10inch-lvds_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-7inch_adapter_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-7inch_overlay.dts
- device-trees/overlays/colibri-imx6_panel-res-touch-7inch_overlay.dts
- device-trees/overlays/colibri-imx6_spidev_overlay.dts
- device-trees/overlays/colibri-imx6_vga-640x480_overlay.dts

Apply the Overlay to the Image​

To enable a display using the display-edt7_overlay.dts overlay, you will only need to run the following command:

$ torizoncore-builder dto deploy --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --force --reboot device-trees/overlays/display-edt7_overlay.dts

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

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

Approach 2: Applying Device Tree Overlays to an Image Directly on the Device​

On Torizon OS image there are pre-built Device Tree Overlays for Add-on Products available in Toradex's webshop. You can see a complete list of the available overlays at the end of this article.

First, get the hash of the current OSTree deployment with the command below:

cat /proc/cmdline
enable_wait_mode=off galcore.contiguousSize=50331648 root=LABEL=otaroot rootfstype=ext4 quiet logo.nologo vt.global_cursor_default=0 plymouth.ignore-serial-consoles splash ostree=/ostree/boot.0/torizon/4ed13802dd58a0bed6fe3fe64c02dc9a2c976e75941403d633418ae316be0ea7/0

See a list of available pre-built overlays (*.dtbo files):

# ls /sysroot/boot/ostree/torizon-4ed13802dd58a0bed6fe3fe64c02dc9a2c976e75941403d633418ae316be0ea7/dtb/overlays

To enable these overlays, you need to modify the file /sysroot/boot/ostree/torizon-*/dtb/overlays.txt in your SoM, adding the desired overlays. You can create it, if not existing.

This file will contain the string fdt_overlays= followed by a space-separated list of overlays.

For example, to enable the DSI to HDMI converter and the CSI Camera Module OV5640 on the Verdin iMX8M Mini module, use the following commands:

# cd /sysroot/boot/ostree/torizon-4ed13802dd58a0bed6fe3fe64c02dc9a2c976e75941403d633418ae316be0ea7/dtb/
# sudo sh -c "echo 'fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo verdin-imx8mm_ov5640_overlay.dtbo' > overlays.txt"
# sync

In this example, this will be the content of the overlays.txt file:

/sysroot/boot/ostree/torizon-4ed13802dd58a0bed6fe3fe64c02dc9a2c976e75941403d633418ae316be0ea7/dtb/overlays.txt
fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo verdin-imx8mm_ov5640_overlay.dtbo

To enable the DSI to HDMI converter only, use the following command:

# sudo sh -c "echo 'fdt_overlays=verdin-imx8mm_lt8912_overlay.dtbo' > overlays.txt"
# sync

After changing the overlays.txt file, reboot the board. To do it, you can use the following command:

# sudo reboot

If you want to obtain the source code of the Device Tree Overlays provided by Toradex for the products available on the webshop, see the Clone Toradex Device Tree and Overlays Repository section of the prior approach.

danger

If you add a device tree overlay that breaks the kernel boot, you can set the U-Boot environment variable skip_fdt_overlays to 1. In U-Boot, execute setenv skip_fdt_overlays 1 and then boot.

Development and Production: Using TorizonCore Builder​

The TorizonCore Builder Tool is the recommended method for customizing Torizon OS for development and production.

Additional prerequisites​

Installing TorizonCore Builder​

To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.

  1. Download the setup script into some writable directory in your system (here we use ~/tcbdir/):

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

    If you did this before then you can skip this step unless you want to update the setup script. When you source the script (next step) it will show you a warning message if it determines an update is advisable.

  2. Source the script:

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

    Make sure to do this from every shell instance that you intend to use with TorizonCore Builder. For advanced usage, run source tcb-env-setup.sh -h, or see the project README. The latter has information about using the early-access version of the tool for those interested.

    tip
    • Remember to source the setup script every time you start a new terminal (or shell instance).
    • 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.

    Beware that under Windows, you must pass extra parameters to the script when the use of the following commands is intended:

  3. Verify that the command torizoncore-builder is available:

    $ torizoncore-builder --help

Writing a Device Tree Overlay​

The most recommended way to create a new overlay is to start looking at similar overlays and then adapt to your project's needs. The next chapters of this article will show how you can obtain Device Tree Overlays source files for peripherals sold by Toradex.

However, if you need to build overlays for different hardware, the Linux Kernel source provides binding documentation for specific peripherals.

To access this information, visit The Linux Kernel Archives website and browse the Linux Kernel source for your board's specific version. You will find the particular bindings information in the Linux kernel source at the Documentation/devicetree/bindings directory.

As an example, you can look at the binding documentation for the version v4.14.184.

To find out the Linux Kernel version on your board, type on the board's Linux terminal:

# uname -r

Applying Device Trees and Overlays to a Custom Image​

There are two possible approaches to apply the customization and generate a custom Toradex Easy Installer image, described in the next two sections Approach 1 and Approach 2. These approaches in some cases are interchangeable and in some not as described in the next sections.

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.

danger

Both approaches generate a custom Toradex Easy Installer image as output, so the approaches should be followed alternatively and not in sequence.

Approach 1: Applying a Device Tree and Device Tree Overlays to a Custom Image Using the Build Command​

TorizonCore Builder build command generates a custom Torizon OS image with the specified device-tree and overlays, ready to be installed with Toradex Easy Installer, named torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM in the example below. This is achieved using a configuration YAML file, tcbuild.yml as default.

This is the recommended approach on production programming and on CI/CD (continuous integration / continuous development) pipelines.

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.

It requires a Toradex Easy Installer image of Torizon OS (preferably without containers), torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar in this case, as input. The device-tree is passed as customization: device-tree: custom: , also passing the directory containing the files included in the device tree (defined with #include in the source code) as customization: device-tree: include-dirs: . Each overlay is passed as customization: device-tree: overlays: add: .

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

The files containing the source code of the device trees and overlays should be available before running the build command. To get the source code of the Toradex supplied device-tree files (including overlays), please refer to the next section. Also, to see how to write your own device tree overlay, please refer to the Writing a Device Tree Overlay section.

Clone The Toradex Repositories and Check The Available Device Trees and Overlays​

Toradex provides source files of Device Trees and Device Tree Overlays for the add-on products available in the webshop. For information about these overlays, see the Toradex Device Tree Overlays repository and the Setting up Displays with Torizon article.

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 Torizon OS 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 Torizon OS 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 Torizon OS 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.

To get the source code of the Toradex-supplied device tree files (including overlays), you need to clone two repositories:

  • Linux kernel: it contains the device trees and headers that both device trees and overlays might reference. For i.MX 6/6ULL/7, we use the upstream kernel directly from kernel.org, and for i.MX 8/8X/8M Mini/8M Plus we provide our own fork based on the NXP downstream kernel.
  • Device tree overlays: this is a repository with overlays provided by Toradex. You need to use a specific branch and commit depending on the Torizon OS version and whether it uses the upstream kernel or our fork based on the NXP downstream.
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.

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

$ git clone -b toradex_5.15-2.2.x-imx git://git.toradex.com/linux-toradex.git linux
$ git clone -b toradex_5.15-2.2.x-imx git://git.toradex.com/device-tree-overlays.git device-trees

You will end up with linux and device-trees directories.

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 linux -name "*imx8mp-verdin*.dts"
linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-wifi-yavia.dts
linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-nonwifi-dev.dts
linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-nonwifi-yavia.dts
linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-wifi-dahlia.dts
linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-wifi-dev.dts
linux/arch/arm64/boot/dts/freescale/imx8mp-verdin-nonwifi-dahlia.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:

Make sure to copy the full path of the device tree file, as device trees for different modules can be located in different paths.

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

Overlays compatible with device tree imx6dl-colibri-eval-v3.dts:
- device-trees/overlays/colibri-imx6_hdmi_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-10inch-lvds_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-7inch_adapter_overlay.dts
- device-trees/overlays/colibri-imx6_panel-cap-touch-7inch_overlay.dts
- device-trees/overlays/colibri-imx6_panel-res-touch-7inch_overlay.dts
- device-trees/overlays/colibri-imx6_spidev_overlay.dts
- device-trees/overlays/colibri-imx6_vga-640x480_overlay.dts

To generate a custom Torizon OS image using the build command, use the target device-tree file in the customization: device-tree: custom section and linux/include folder in the customization: include-dirs: section: For example, to build a custom image with the colibri-imx6_hdmi_overlay.dts overlay, the tcbuild.yaml file should be:

tcbuild.yaml
# Sample configuration file:
input:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-Tezi_6.1.0+build.1.tar
# Sample customization: insert the hdmi overlay in the IMX6
customization:
  device-tree:
    include-dirs:
      - linux/include
    custom: linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts
    overlays:
      add:
        - device-trees/overlays/colibri-imx6_hdmi_overlay.dts

output:
  easy-installer:
    local: torizon-core-docker-colibri-imx6-Tezi_6.1.0+build.CUSTOM

Alternatively, you can use the dto deploy command with the --device-tree option. For example, to deploy the colibri-imx6_hdmi_overlay.dts overlay, run the command below:

$ torizoncore-builder dto deploy --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --reboot --device-tree ./linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts device-trees/overlays/colibri-imx6_hdmi_overlay.dts

Keep in mind that the repositories will need to be cloned again every time you start working on a new directory. A recommended solution to this problem, if your project where you have the configuration YAML file is on a Git repository, would be to create a git submodule inside your repository pointing to the Kernel and Toradex Device Tree Overlays Repositories.

Build The Custom Image​

To generate the Torizon OS image, run the command below, in the same directory where the tcbuild.yaml file is:

$ 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!

In case of using a configuration file with a different name than tcbuild.yaml, run the command specifying the configuration file name:

$ torizoncore-builder build --file <configuration_file_name>

Deploy The Custom Toradex Easy Installer Image​

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

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 Cloud 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 Cloud 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 Cloud​

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 Cloud 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 Cloud 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 Cloud Updates, check the Signing and pushing the image to Torizon Cloud article.

Approach 2: Applying a Device Tree and Device Tree Overlays to a Custom Image Using Standalone Commands​

In this second approach, instead of using a configuration YAML file and a one-step command, the generation of the custom Torizon OS with the device tree and overlays is done using standalone commands, each performing one step towards this generation.

This approach is especially useful when making incremental changes, generating multiple images with different device tree overlays (or other customizations like different external kernel modules). As you will see, applying a device tree or including a device tree overlay on an image of Torizon OS that has other customizations (including other device tree overlays) is just a matter of performing the apply, merge and deploy stages.

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.

To generate a custom Toradex Easy Installer image with the desired device tree and overlays follow the sequence of steps below.

Unpack an Input Image​

You just need to execute this once. Then, you are ready to apply multiple changes to the image. For example, in addition to applying a new device tree or different overlays, you can also apply an external kernel module, a new splash screen, among other possibilities.

If you have not unpacked an image yet, download a base Torizon OS 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 Torizon OS 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 Torizon OS 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.

Clone the Toradex Device Tree and Overlays Repository with dt checkout​

You just need to execute this once. This does the same as Clone The Toradex Repository of Approach 1. However, as you have already unpacked the right image for your device, you do not need to worry about the branch that will be cloned. You simply need to run the dt checkout command below.

$ torizoncore-builder dt checkout

The repository contains device tree source files and device tree overlays, which have the .dts extension, and .dtsi and .h files. Also, it has the following directory organization:

  • dts-arm32 - source files of device trees for Toradex modules of 32-bit architectures.
  • dts-arm64 - source files of device trees for Toradex modules of 64-bit architectures.
  • overlays - source files of device tree overlays for Toradex modules.
info

The dt checkout --update command can be used to update an already existing device trees and overlays folder.

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

Compile and Apply a Device Tree​

To identify the current device tree of the image, use the following command:

$ torizoncore-builder dt status

Current device tree is: imx6q-apalis-eval.dtb

In the above command, note that the device tree has the .dtb extension, meaning that it's a compiled device tree.

info

Some images of Toradex modules don't set the device tree upfront, delaying the selection of a device tree for boot time. In these cases, dt status won't be able to show the current device tree of the image.

To compile a given device tree source file and then set it to be used in the image, use the following command:

$ torizoncore-builder dt apply device-trees/dts-arm32/imx6q-apalis-ixora-v1.1.dts
info

When applying a device tree with dt apply, all overlays that were eventually applied are reset.

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

Compile and Apply Device Tree Overlays​

To list the overlays under device-trees/overlays that are compatible with the current device tree, use dto list:

$ torizoncore-builder dto list

Overlays compatible with device tree imx6q-apalis-ixora-v1.1.dtb:
- device-trees/overlays/apalis-imx6_atmel-mxt_overlay.dts
- device-trees/overlays/apalis-imx6_hdmi_overlay.dts
- device-trees/overlays/apalis-imx6_lcd_overlay.dts
- device-trees/overlays/apalis-imx6_lvds_overlay.dts
- device-trees/overlays/apalis-imx6_stmpe-ts_overlay.dts
- device-trees/overlays/apalis-imx6_vga_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-lt170410_overlay.dts

To compile a given device tree overlay source file and then set it to be applied to the device tree during boot, use dto apply:

$ torizoncore-builder dto apply device-trees/overlays/apalis-imx6_hdmi_overlay.dts

In the above example:

  1. The device tree overlay source apalis-imx6_hdmi_overlay.dts was successfully compiled to apalis-imx6_hdmi_overlay.dtbo.
  2. For testing, the compiled overlay apalis-imx6_hdmi_overlay.dtbo modified successfully a temporary copy of the current device tree imx6q-apalis-ixora-v1.1.dtb. This is just a sanity verification that the overlay won't fail when applied during booting the module. This step can be bypassed with option --force to dto apply.
  3. On successful execution of the previous steps, the compiled overlay was added to the list of overlays that are applied to the current device tree of the module during boot.

Overlays can be applied incrementally; if you want to enable more overlays, use dto apply again.

To identify the device tree overlays that are currently applied to the device tree in the image, use dto status:

$ torizoncore-builder dto status

Enabled overlays over device tree imx6q-apalis-ixora-v1.1.dtb:
- apalis-imx6_hdmi_overlay.dtbo

In the above example, note that the overlays have the .dtbo extension, meaning they are compiled files.

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

Remove Device Tree Overlays​

To remove an applied overlay, use dto remove and pass the overlay blob name as given by dt status in the section above:

$ torizoncore-builder dto remove apalis-imx6_hdmi_overlay.dtbo

For more details about the dto remove commands, please check the dto remove command in the commands manual.

Merge Changes​

Merge the new device tree and the different overlays (as well as other customizations like an external kernel module or a new splash screen) into the base Toradex Easy Installer image of Torizon OS - use whatever branch name you want.

As an example, to commit changes into a branch named custom-branch use the command below, accordingly with the TorizonCore Builder version:

$ torizoncore-builder union custom-branch

Applying changes from STORAGE/dt.
Commit 58629613a342197c31c5911d0874aac1b0fcb46b68a63f59760c03bacc4df08a has been generated for changes and is ready to be deployed.
caution

We recommend that you switch to the latest version of TorizonCore Builder to enjoy its simpler and more consistent user interface besides other improvements and bug fixes.

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

Deploy The Custom Toradex Easy Installer Image​

To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.

Deploy The Custom Toradex Easy Installer Image

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

However, the commands have differences in comparison to the deploy in Approach 1.

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.

First, to generate a Toradex Easy Installer image, into the output directory torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM, use the command below:

$ torizoncore-builder deploy custom-branch --output-directory torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM

Change the arguments custom-branch to the branch where you merged the changes (with the union command).

Copy the output image into a USB stick and follow the steps in the Toradex Easy Installer Tool 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 /media/user/myUSBstick is, in my case, the path to USB stick mount point.

Directly, through SSH​

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

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

Change the arguments custom-branch, --remote-host,--remote-username and --remote-password to the branch where you merged the changes (with the union command), 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.

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

caution

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

Torizon Cloud Remote Update Service​

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

$ torizoncore-builder push --credentials credentials.zip custom-branch

Change the argument custom-branch to the branch where you merged the changes (with the union command).

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 Cloud 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 Over-the-Air (OTA) updates, check the Signing and pushing the image to Torizon Cloud article.

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

Verifying The New Custom Image On The Device​

After rebooting, in your target device's terminal, verify that your new custom image of Torizon OS 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 output of the union command in the case of the standalone commands
  • The one in the "Deploying OSTree with checksum ..." part of the output of the build command.

Rollback Mechanism​

In case you find yourself with a non-working kernel (usually stuck at the "Loading kernel..." message) when applying a device tree overlay with TorizonCore Builder, after a few boot tries (3 by default), the system will roll back to the previous version of the operating system. For more information on the rollback mechanism, please refer to Update Rollbacks.

Device Tree Overlays Examples​

Device tree examples, including overlays, can be found on Device Tree Customization Examples. See a list of remarkable examples available:

ExampleDescription
GPIO pinmuxSome pins are not configured as GPIO by default. Learn how to configure a pin as GPIO.

Some examples are available in other articles:

info

At the moment, there are no device tree overlay examples outside the Device Tree Customization Examples.

List of Device Tree Overlays for Peripherals and Add-on Products Provided by Toradex​

Toradex provides Device Tree Overlays for SoM peripherals and add-on products available in the webshop. For information about these overlays, see the Toradex Device Tree Overlays repository on Github and the Setting up Displays with Torizon article.

Displays​

info

Default resolution with these overlays: 1920x1080

Native Interface:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_hdmi_overlay.dtbo
Apalis iMX8 QuadMax6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0apalis-imx8_hdmi_overlay.dtbo
Apalis iMX66.0.0apalis-imx6_hdmi_overlay.dtbo
Colibri iMX66.0.0colibri-imx6_hdmi_overlay.dtbo

Using Verdin DSI to HDMI adapter:

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.1.0verdin-imx8mp_dsi-to-hdmi_overlay.dtbo
Verdin iMX8M Mini6.1.0verdin-imx8mm_dsi-to-hdmi_overlay.dtbo
Verdin AM626.4.0verdin-am62_dsi-to-hdmi_overlay.dtbo

Using Colibri DSI to HDMI adapter:

ModuleStarting from versionOverlay
Colibri iMX8X6.2.0colibri-imx8x_dsihdmi_overlay.dtbo

SPIDEV​

Native Interface:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus6.0.0SPIverdin-imx8mp_spidev_overlay.dtbo
Verdin iMX8M Mini6.0.0SPIverdin-imx8mm_spidev_overlay.dtbo
Verdin AM626.4.0SPIverdin-am62_spidev_overlay.dtbo
Apalis iMX8 QuadMax6.1.0SPI 1apalis-imx8_spi1_spidev_overlay.dtbo
Apalis iMX8 QuadMax6.1.0SPI 2apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0SPI 1apalis-imx8_spi1_spidev_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0SPI 2apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX66.0.0SPI 1apalis-imx6_spi1_spidev_overlay.dtbo
Apalis iMX66.0.0SPI 2apalis-imx6_spi2_spidev_overlay.dtbo
Colibri iMX8X6.1.0SPIcolibri-imx8x_spidev_overlay.dtbo
Colibri iMX6ULL eMMC6.1.0SPIcolibri-imx6ull_spidev_overlay.dtbo

CAN​

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Mini6.1.0CAN 1 [20MHz]verdin-imx8mm_20mhz_can1.dtbo
Verdin iMX8M Mini6.0.0CAN 1 [Disable]verdin-imx8mm_disable_can1.dtbo

Using Mezzanine add-on boards:

ModuleStarting from versionInterfaceOverlay
Apalis iMX8 QuadMax6.1.0CANapalis-imx8_mezzanine_can_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0CANapalis-imx8_mezzanine_can_overlay.dtbo

Camera​

OV5640 CSI Camera​

See the OV5640 CSI Camera in the Developer Wesite.

Native Interface:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus6.0.0CSIverdin-imx8mp_ov5640_overlay.dtbo
Verdin iMX8M Mini6.0.0CSIverdin-imx8mm_ov5640_overlay.dtbo
Verdin AM626.4.0CSIverdin-am62_ov5640_overlay.dtbo

Using Mezzanine add-on boards:

ModuleStarting from versionInterfaceOverlay
Verdin iMX8M Plus [Default jumper setting]6.1.0CSIverdin-imx8mp_mezzanine_ov5640-default-jumpers_overlay.dtbo
Verdin iMX8M Plus [Alternate jumper setting]6.1.0CSIverdin-imx8mp_mezzanine_ov5640-alt-jumpers_overlay.dtbo
Apalis iMX8 QuadMax6.1.0CSIapalis-imx8_ov5640_overlay.dtbo
apalis-imx8_mezzanine_ov5640_overlay.dtbo
Apalis iMX8 QuadPlus6.1.0CSIapalis-imx8_ov5640_overlay.dtbo
apalis-imx8_mezzanine_ov5640_overlay.dtbo

Verdin Mezzanine jumper settings:

Jumper SettingJP3JP4JP5JP6
Default2-32-32-32-3
Alternate2-32-31-21-2

HMP​

Heterogeneous Multicore Processing Overlays:

ModuleStarting from versionOverlay
Verdin AM626.6.0verdin-am62_hmp_overlays.dtbo
Verdin iMX8M Plus6.3.0verdin-imx8mp_hmp_overlay.dtbo
Verdin iMX8M Mini6.2.0verdin-imx8mm_hmp_overlay.dtbo
Colibri iMX8X6.4.0colibri-imx8x_hmp_overlay.dtbo

BTL Audio Output on NAU8822​

Verdin Development Board features an analog audio interface based on the NAU8822 24-bit audio codec IC with integrated DSP with specific functions

ModuleStarting from versionOverlay
Verdin iMX8M Plus6.2.0verdin-imx8mp_nau8822-btl_overlay.dtbo
Verdin iMX8M Mini6.2.0verdin-imx8mm_nau8822-btl_overlay.dtbo
Verdin AM626.4.0verdin-am62_nau8822-btl_overlay.dts

Pre-enabled Device Tree Overlays​

By default, the following overlays are enabled to simplify the use of Toradex carrier boards and modules. Note that these overlays may cause conflicts with other peripherals.

ModuleSupported PeripheralsOverlays
Apalis iMX8HDMI
SPIDEV		apalis-imx8_hdmi_overlay.dtbo
apalis-imx8_spi1_spidev_overlay.dtbo
apalis-imx8_spi2_spidev_overlay.dtbo
Apalis iMX6HDMI
SPIDEV		apalis-imx6_hdmi_overlay.dtbo
apalis-imx6_spi1_spidev_overlay.dtbo
apalis-imx6_spi2_spidev_overlay.dtbo

RTC​

OverlayDevice
apalis-imx8qm-st-m41t0-overlay.dtsEnable the external m41t0 RTC from ST on Apalis iMX8


Send Feedback!