TorizonCore Builder Tool - Customizing Torizon OS Images
Introduction
TorizonCore Builder is a tool that allows you to easily generate a custom image of Torizon OS with device configuration changes, a custom device tree and overlays, pre-provisioned containers, external kernel modules, and a splash screen. In the end, you will have a custom Torizon OS image that you can flash onto the SoM using the Toradex Easy Installer, deploy to the SoM through SSH, or push to Torizon Cloud for deploying it remotely. The tool is designed to be used on production programming and on development as well.
*OS Customization Files are device tree and overlays source codes, external kernel modules source files, a splash screen image, and a directory with the configuration changes captured from the device. They can be also called version-controlled artifacts.
Easily Customizing Torizon OS Images With TorizonCore Builder Tool
Resources
Browse for TorizonCore Builder resources from the tabs below.
This article complies with the Typographic Conventions for Torizon Documentation.
Requirements
- A Toradex SoM with Torizon installed
Typical Use Cases
TorizonCore builder tool provides multiple commands to be used in different situations. We will describe below typical TorizonCore Builder use cases and on which section the customization related to these use cases is.
Some use cases are not covered by TorizonCore Builder. Check the section Use cases not covered by TorizonCore Builder.
Customizing a Torizon OS Image for Production
TorizonCore Builder provides standalone commands that allow you to easily customize a Torizon OS image. Such changes could be:
Pre-provisioning Docker Container Images: As a method for Deploying Container Images to Torizon OS, TorizonCore Builder can download user Docker containers images and combine them with an off-the-shelf Torizon OS image to generate a new, monolithic, image. This process is especially useful when preparing an image to be flashed on several units in production. Its usage is described in the Pre-provisioning Docker Container Images sections.
Setting the System's Splash Screen: You can replace the System's Splash Screen using TorizonCore Builder as described in the Splash Screen section.
Adding New Hardware to the System: When setting up new hardware, for example, adding a display to the board, or changing some SoC's pin functionality, sometimes a developer will have to make changes to the Linux Device Tree by applying a Device Tree Overlays. TorizonCore Builder can build a full device tree or apply device tree overlays. See the Device Tree section to learn how to use it.
Building External Kernel Modules: It is often necessary to build an external kernel module (a.k.a. out-of-tree module) when this module doesn't exist in the standard Linux tree. Some examples where this is necessary are when adding support to some device/peripheral. Check the Building Kernel Module section to learn how to do it.
Customizing Kernel Arguments: It is possible to configure aspects of the Linux Kernel of Torizon OS and it's modules by setting certain custom boot-time arguments (parameters). Learn how to customize kernel arguments on the Kernel Arguments section.
Capturing Configuration Changes in a Device: If a user has made any configuration changes in Torizon OS ( e.g., the
/etc
directory) in a SoM, the tool is able to capture all those changes (modifications, addition, and deletion) through an ssh connection between the host PC and the target board and prepare it to deploy into a new custom Torizon OS image.
Here are some examples of configuration that modify/etc
:Storage of Docker data on an external storage device (USB/SD Card)
For more details on how to do it, please refer to the Capturing Configuration Changes in the Target Device section.
If you want to add a kernel module that is available in the kernel source, or in-tree, please make a request in our community. If you tell us the exact kernel config that must be enabled and it does not have a negative impact on Torizon OS, we'll add it as a module.
Deploying Torizon OS Images
Users can deploy the image in three different ways:
To learn how to do it, refer to the Deploying the image section of this page.
Use cases not covered by TorizonCore Builder
Due to project requirements, it is possible that customizations on the kernel source code and/or on builtin in-tree kernel modules are needed.
These customizations are not covered by TorizonCore Builder at the moment. Therefore, to perform such customizations, using Yocto Project to build your image with these kind of custom changes is the recommended approach.
Please note that on Yocto Project, it is possible to modify every detail of the final image. Therefore you might need to test and validate these implementations so that the custom build of your Torizon OS image will seamless integrate with the other elements of Torizon Ecosystem.
Keep in mind that it is possible to use the customized Torizon OS with TorizonCore Builder, Torizon Cloud, containers and the VS Code IDE Extension.
Here is a list of some customizations that should be done leveraging Yocto Project resources:
- Bootloader (U-Boot)
- InitRAM Filesystem (
initramfs
) - Kernel source code modifications
- Add In-tree Kernel modules
Installing TorizonCore Builder
OS Compatibility
TorizonCore Builder executes in a Docker Runtime and it was tested on the following Operating Systems:
- A Linux distribution with:
- A filesystem compatible with the overlay2 Docker storage driver.
- Windows 10 or newer with Windows Subsystem for Linux (WSL2).
- The same Linux distribution requisites from above also apply to the Linux distribution chosen to be used in WSL2.
WSL2 requires Windows 10, updated to version 2004 (also known as the Windows 10 May 2020 Update) or higher.
Shell Compatibility
All our tests are run on Bash. TorizonCore Builder might work with other shells, but we don't ensure it.
That said, if you face a bug in a shell that is not Bash, please report it on our community website. We'll evaluate it and make our best effort to fix it, as long as the fix is compatible with Bash and the increase in maintenance is low.
Note for Users Installing TorizonCore Builder on Windows Machine
TorizonCore Builder support on a Windows desktop requires the "Windows Subsystem for Linux 2" (WSL 2). This is due to TorizonCore Builder relying on a Linux-based filesystem.
Before proceeding with any TorizonCore Builder instructions please set up a WSL 2 distro and Docker on your development host as shown on Configure Build Environment for Torizon Containers. As a reminder, any and all TorizonCore Builder commands should be run in your WSL 2 distro.
Finally, as a quick tip, you'll occasionally need to transfer files to and from your WSL 2 distro and your Windows host. You can actually do this by using the built-in Windows file explorer utility. This and other Windows utilities can actually be invoked from within your WSL 2 Distro. For example by doing the following in your WSL 2 Distro:
$ explorer.exe .
The above command will open the Windows file explorer in your current directory. From here you'll be able to copy/paste and move files between the WSL 2 world and the normal Windows world.
Setup Script
To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.
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.shnoteIf 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.
Source the script:
$ cd ~/tcbdir/
$ source tcb-env-setup.shMake 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:
ostree serve
: consult the ostree serve reference.
Verify that the command
torizoncore-builder
is available:$ torizoncore-builder --help
Using TorizonCore Builder
This section shows how to use TorizonCore Builder in a simple way, yet covering almost all use cases. It is based on the build command, which allows the full image customization in a single step, using a configuration YAML file. The other commands that are necessary in conjunction with the build
command in order to cover most use cases are also explained in this section.
If your use case is not covered here, please refer to the TorizonCore Builder - Commands Manual section for a detailed explanation of all TorizonCore Builder commands.
Workflow
- Create a configuration file with the desired settings (the build command can even help you with that);
- Customize the configuration file in order to select the desired input image, include the desired customization, and get the desired outputs. Also, run the auxiliary commands where needed so all local artifacts possibly referenced by the configuration file are available;
- Run the build command;
- Deploy the output to the board or to Torizon Cloud server;
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.
Creating a Configuration File
The easiest and thus recommended way for creating an initial configuration file is by running:
$ torizoncore-builder build --create-template
The previous command will create a file named tcbuild.yaml containing all possible configuration parameters accepted by the command.
The configuration file is in a standard YAML format which should be recognized by most modern programming editors. Any other name can be chosen for the file, but tcbuild.yaml is the name that the build command will expect by default when running in build mode. Most parameters in the generated file will be commented out which can be seen by the # character at the beginning of each line. Lines having the characters >> are just explaining the contents of the file and should be left as-is or removed if desired.
The contents of the file are organized in a tree structure where the leaves are configurable properties. In order to set a certain property, you need to make sure all its parent properties are also uncommented (by removing the first # character).
The configuration file follows the YAML format and syntax. The tool expects it to be made up of three sections, represented by the top-level properties (keys): input, customization, and output as outlined below:
# Configuration file outline:
input:
# Input section items (required).
customization:
# Customization section items.
output:
# Output section items (required).
Customizing The Configuration File
Minimal Configuration File
A minimal configuration file has to specify at least one input and one output. Below we assume that the input is a previously downloaded Toradex Easy Installer image that is stored in a directory called images
relative to the working directory (set by the alias of the tool).
When downloading a Toradex Easy Installer image, be sure to download an image without evaluation containers, because the input image to be customized MUST NOT contain bundled container images. To download the image, go to the Toradex Download Links (Torizon, Linux BSP, WinCE and Partner Demos) article.
# Sample configuration file:
input:
easy-installer:
local: images/torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
The directory structure of such a "project" would look like this:
.
├── images
│ └── torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar
└── tcbuild.yaml
Fetching Remote Images
The input to the tool can also be specified as a URL to a remote server instead of a directory with a downloaded image, as in the Minimal Configuration section. If the input is passed as a remote image, the image will be downloaded every time the image is built.
In the sample configuration below, we directly download an image from Toradex's artifacts server:
# Sample configuration input, specifying a remote:
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"
Notice the presence of the sha256sum
parameter which can be used to ensure that the downloaded file has a certain SHA-256 checksum – the tool will stop if the actual file checksum does not match that value. For more information about how a remote location can be specified please refer to the build command Detailed Manual.
Fetching remote images: URL autogenerated
Another way to specify an input is the sample configuration below:
# Sample configuration input, specifying parameters for URL autogeneration:
input:
easy-installer:
toradex-feed:
version: "5.3.0"
release: quarterly
machine: colibri-imx6
distro: torizon-upstream
variant: torizon-core-docker
build-number: "7"
#build-date: "202107"
The build
command then autogenerates the URL shown in the remote
parameter of the Fetching Remote Images section. For monthly and nightly releases the parameter build-date
is needed.
Splash Screen
To customize the splash screen, insert the configuration below:
#Sample customization: insert a Splash Screen
customization:
# >> Splash screen:
splash-screen: splash.png
The file splash.png should be available before running the build
command. A demo image can be downloaded by clicking on the button below:
Check the Splash Screen on Torizon OS article for more details.
Device Tree
This customization can be used both with Toradex's device trees and overlays as well as any other compatible device tree and overlay. The files containing the source code of the device trees and overlays should be available before running the build
command.
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.
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.cn/linux-toradex.git linux
$ git clone -b toradex_5.15-2.2.x-imx git://git.toradex.cn/device-tree-overlays.git device-trees
$ git clone -b linux-6.1.y git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
$ git clone -b master git://git.toradex.cn/device-tree-overlays.git device-trees
$ git clone -b toradex_ti-linux-6.1.y git://git.toradex.cn/linux-toradex.git linux
$ git clone -b toradex_ti-linux-6.1.y git://git.toradex.cn/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.
- Verdin iMX8M Plus
- Verdin iMX8M Mini
- Verdin AM62
- Apalis iMX8
- Apalis iMX6
- Colibri iMX8X
- Colibri iMX7
- Colibri iMX6
- Colibri iMX6ULL
$ 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
$ find linux -name "*imx8mm-verdin*.dts"
linux/arch/arm64/boot/dts/freescale/imx8mm-verdin-wifi-yavia.dts
linux/arch/arm64/boot/dts/freescale/imx8mm-verdin-nonwifi-dev.dts
linux/arch/arm64/boot/dts/freescale/imx8mm-verdin-nonwifi-dahlia.dts
linux/arch/arm64/boot/dts/freescale/imx8mm-verdin-nonwifi-yavia.dts
linux/arch/arm64/boot/dts/freescale/imx8mm-verdin-wifi-dahlia.dts
linux/arch/arm64/boot/dts/freescale/imx8mm-verdin-wifi-dev.dt
$ find linux -name "*am62*-verdin*.dts"
linux/arch/arm64/boot/dts/ti/k3-am625-verdin-nonwifi-dahlia.dts
linux/arch/arm64/boot/dts/ti/k3-am625-verdin-wifi-dev.dts
linux/arch/arm64/boot/dts/ti/k3-am625-verdin-nonwifi-yavia.dts
linux/arch/arm64/boot/dts/ti/k3-am625-verdin-wifi-yavia.dts
linux/arch/arm64/boot/dts/ti/k3-am625-verdin-wifi-dahlia.dts
linux/arch/arm64/boot/dts/ti/k3-am625-verdin-nonwifi-dev.dts
### For Apalis iMX8 QuadMax versions
$ find linux -name "*imx8qm-apalis*.dts"
linux/arch/arm64/boot/dts/freescale/imx8qm-apalis-v1.1-ixora-v1.1.dts
linux/arch/arm64/boot/dts/freescale/imx8qm-apalis-v1.1-eval.dts
linux/arch/arm64/boot/dts/freescale/imx8qm-apalis-eval.dts
linux/arch/arm64/boot/dts/freescale/imx8qm-apalis-ixora-v1.1.dts
linux/arch/arm64/boot/dts/freescale/imx8qm-apalis-v1.1-ixora-v1.2.dts
### For Apalis iMX8 QuadPlus versions
$ find linux -name "*imx8qp-apalis*.dts"
linux/arch/arm64/boot/dts/freescale/imx8qp-apalis-v1.1-ixora-v1.1.dts
linux/arch/arm64/boot/dts/freescale/imx8qp-apalis-v1.1-ixora-v1.2.dts
linux/arch/arm64/boot/dts/freescale/imx8qp-apalis-v1.1-eval.dts
$ find linux -name "*imx6q-apalis*.dts"
linux/arch/arm/boot/dts/imx6q-apalis-ixora-v1.2.dts
linux/arch/arm/boot/dts/imx6q-apalis-ixora.dts
linux/arch/arm/boot/dts/imx6q-apalis-ixora-v1.1.dts
linux/arch/arm/boot/dts/imx6q-apalis-eval.dts
### For Colibri iMX8QuadXPlus versions
$ find linux -name "*imx8qxp-colibri*.dts"
linux/arch/arm64/boot/dts/freescale/imx8qxp-colibri-iris.dts
linux/arch/arm64/boot/dts/freescale/imx8qxp-colibri-iris-v2.dts
linux/arch/arm64/boot/dts/freescale/imx8qxp-colibri-eval-v3.dts
linux/arch/arm64/boot/dts/freescale/imx8qxp-colibri-aster.dts
### For Colibri iMX8DualX versions
$ find linux -name "*imx8dx-colibri*.dts"
linux/arch/arm64/boot/dts/freescale/imx8dx-colibri-eval-v3.dts
linux/arch/arm64/boot/dts/freescale/imx8dx-colibri-aster.dts
linux/arch/arm64/boot/dts/freescale/imx8dx-colibri-iris-v2.dts
linux/arch/arm64/boot/dts/freescale/imx8dx-colibri-iris.dts
$ find linux -name "*imx7d-colibri*.dts"
linux/arch/arm/boot/dts/imx7d-colibri-eval-v3.dts
linux/arch/arm/boot/dts/imx7d-colibri-iris.dts
linux/arch/arm/boot/dts/imx7d-colibri-iris-v2.dts
linux/arch/arm/boot/dts/imx7d-colibri-emmc-iris.dts
linux/arch/arm/boot/dts/imx7d-colibri-emmc-iris-v2.dts
linux/arch/arm/boot/dts/imx7d-colibri-emmc-eval-v3.dts
linux/arch/arm/boot/dts/imx7d-colibri-aster.dts
linux/arch/arm/boot/dts/imx7d-colibri-emmc-aster.dts
$ find linux -name "*imx6dl-colibri*.dts"
linux/arch/arm/boot/dts/imx6dl-colibri-iris.dts
linux/arch/arm/boot/dts/imx6dl-colibri-aster.dts
linux/arch/arm/boot/dts/imx6dl-colibri-eval-v3.dts
linux/arch/arm/boot/dts/imx6dl-colibri-iris-v2.dts
$ find linux -name "*imx6ull-colibri*.dts"
linux/arch/arm/boot/dts/imx6ull-colibri-wifi-iris-v2.dts
linux/arch/arm/boot/dts/imx6ull-colibri-wifi-aster.dts
linux/arch/arm/boot/dts/imx6ull-colibri-eval-v3.dts
linux/arch/arm/boot/dts/imx6ull-colibri-emmc-iris-v2.dts
linux/arch/arm/boot/dts/imx6ull-colibri-wifi-iris.dts
linux/arch/arm/boot/dts/imx6ull-colibri-wifi-eval-v3.dts
linux/arch/arm/boot/dts/imx6ull-colibri-iris-v2.dts
linux/arch/arm/boot/dts/imx6ull-colibri-emmc-iris.dts
linux/arch/arm/boot/dts/imx6ull-colibri-emmc-aster.dts
linux/arch/arm/boot/dts/imx6ull-colibri-iris.dts
linux/arch/arm/boot/dts/imx6ull-colibri-aster.dts
linux/arch/arm/boot/dts/imx6ull-colibri-emmc-eval-v3.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:
# 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
Then to include the device tree and the overlays in the image, use the customization below:
#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
See the following articles for more information:
- Device Tree Overlays on Torizon: a broad article that covers the process of building Device Tree Overlays targeting Torizon OS.
- Setting up Displays with Torizon: A common use case that requires applying Device Tree Overlays.
Also, for more details on how the dt
commands work, please check the dt command in the commands manual.
Kernel Modules
The build
command allows you to build and install kernel modules into the deployed OS image. This is demonstrated in this configuration:
# Sample customization: build hello-mod module into the image
customization:
kernel:
modules:
- source-dir: hello-mod/
autoload: no
The directory hello-mod
containing the source code files of the kernel modules should be available before running the command. To get the hello-mod
module from our Github repository, run the command below:
$ git clone https://github.com/toradex/hello-mod
For more general information about the subject, please refer to Building External Kernel Modules With Torizon article.
Kernel Arguments (Parameters)
Kernel arguments (parameters) can be included in the OS image or modified, if they already exist, with the build
command. This is done in the configuration file below:
# Sample customization: include or change (if already exists) key1 and key2 kernel arguments
customization:
kernel:
arguments:
- key1=val1
- key2=val2
For more general information about the subject, please refer to Customizing Kernel Arguments in Torizon article.
Capturing Configuration Changes in the Target Device
If the user made configuration changes on Torizon OS in the SoM, this command is necessary to capture them. For more details about what it does and for which cases it is applicable, please check the Typical Use Cases section.
To capture the configuration changes made in the target device, run the command below:
$ torizoncore-builder isolate --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --changes-directory changes1
Then to include these changes in the image, use the customization below:
#Sample customization: insert the configuration changes made in the device
customization:
filesystem:
- changes1/
See the Capturing Changes in the Configuration of a Board on Torizon OS article for detailed instructions.
Also, for more details on how the isolate
command works, please check the isolate command in the commands manual.
Pre-provisioning Docker Container Images
The build command also simplifies the process of bundling container images into an installer image. A sample configuration leveraging that feature is this:
#Sample customization: insert pre-provisioned Docker container images
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
bundle:
compose-file: custom/docker-compose.yml
With such an input, the tool will fetch the container images referenced by the specified docker-compose.yml file and combine them with the installer image.
A sample Docker Compose YAML file can be downloaded, based on your device, by clicking in one of the links below:
Pre-provisioning Docker Container Images: Pre-bundled Container Images
If you don't want the tool to download the images every time the build command is run, you can pass a directory with the pre-bundled container images instead of the Docker Compose file as a parameter.
To create a tarball with the container images from a Docker Compose file, in the directory bundle, use the command below:
$ torizoncore-builder bundle docker-compose.yml --bundle-directory bundle --platform linux/arm/v7
Then to include these pre-bundled container images in the image, through the directory, use the configuration below:
#Sample customization: insert pre-provisioned Docker container images with pre-built container images
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
bundle:
dir: bundle/
Find more details in the Pre-provisioning Docker Containers onto a Torizon OS image article.
For more details on how the bundle
command works, please check the bundle command in the commands manual.
Building The Custom Image of Torizon OS
To run the tool one would simply execute:
$ 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!
Once the build process finishes, the custom Easy Installer image would be present in the directory defined in the local
of the output
section of the configuration file, as it can be seen in the Minimal Configuration File section.
Different configuration file name
The default configuration file used is the tcbuild.yaml file, created in the Creating a Configuration file section. In case of using a configuration file with a different name, run the command specifying the configuration file name:
$ torizoncore-builder build -f <configuration_file_name>
Variable substitution
A feature that can be especially useful in CI scripts is called variable substitution which allows the replacement of property values (or parts of them) based on parameters passed on the command line of the tool. To use this feature, click on the link below and follow the steps.
Variable Substitution
The following configuration file employs that feature:
# Sample configuration input with variable substitution
output:
easy-installer:
local: torizon-core-docker-colibri-imx6-with-containers
name: "${IMAGE_NAME-Default image name}"
description: "${IMAGE_DESC?Please provide a description for this image}"
The value of the property output/easy-installer/name
in the example is set to the value of variable IMAGE_NAME or to "Default image name" when the variable is not set. The property output/easy-installer/description
depends on IMAGE_DESC which is required and if not set will cause the tool to exit showing the specified message. Running the build command by itself would fail like this:
$ torizoncore-builder build
Building image as per configuration file 'tcbuild.yaml'...
** Exiting due to user-defined error: Please provide a description for this image
In order to successfully build an image with the previous configuration file (using the default value for IMAGE_NAME), one could run:
$ torizoncore-builder build --set IMAGE_DESC="This is the required description"
For more information on the notation for replacing variables in the configuration file, please refer to the build command Detailed Manual.
Deploying The Custom Image Of Torizon OS
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.
- It's also possible to use a static-delta approach, which is more network efficient.
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.
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.
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.
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.
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 "Deploying OSTree with checksum ..." part of the output of the build
command.
Additional Resources
Proceed to the Documentation tab on this page.
Extra Resources for Torizon OS Customization
See below more documents related to TorizonCore Builder and Torizon OS Customization
Article | Brief Description | |
---|---|---|
TorizonCore Builder Tool - Customizing Torizon OS Images | Create a custom Torizon OS image that you can use in production programming with Toradex Easy Installer, or push your changes to Torizon Cloud | |
TorizonCore Builder - Workflow | Workflow of TorizonCore Builder, with a comparison between the approaches to use the tool and diagrams to graphically present the workflow and each approach | |
TorizonCore Builder VS Code Integration | How to use TorizonCore Builder from Visual Studio Code | |
TorizonCore Builder Tool “build" command | Learn how to fully customize an image as a single step using the build command from TorizonCore Builder | |
Device Tree Overlays on Torizon | How to modify the device tree without having to re-compile it | |
Device Tree Customization Examples | Some examples of Device Tree Customization | |
Pin Multiplexing - Changing Pin Functionalities in the Linux Device Tree | How to create a dts file to change the pin muxing configuration | |
Building External Kernel Modules With Torizon | How to deploy an external kernel module using TorizonCore Builder with an example | |
Customizing Kernel Arguments in Torizon | How to use TorizonCore Builder to customize kernel arguments in Torizon | |
Splash Screen Customization on Torizon OS | Learn how to change the splash screen using initramfs | |
Touch Screen Calibration (Torizon) | How to use weston-touch-calibrator to calibrate the touch | |
Capturing Changes in the Configuration of a Board on Torizon OS | Use TorizonCore Builder to save and reproduce board customization | |
Pre-provisioning Docker Containers onto a Torizon OS image | How to preinstall a Docker Container onto a Torizon OS image using your PC | |
TorizonCore Builder - Commands Manual | Commands manual of TorizonCore Builder, showing all commands of the tool and explaining them | |
Torizon OS Boot Time Optimization | How to measure and optimize Torizon OS boot time | |
Reliability on Torizon | Learn how to improve reliability on Torizon OS | |
How to Store Docker Data on an External Storage Device (USB/SD Card) | How to storage Docker data on an external device like an SD Card or a USB stick | |
Persistent Journald Logging | How switch from in-RAM to persistent Journald logging | |
Using Private Registries With Torizon Cloud | How to deploy private registry credentials to your devices |