Select the version of your OS from the tabs below. If you don't know the version you are using, run the command cat /etc/os-release or cat /etc/issue on the board.
Remember that you can always refer to the Torizon Documentation, there you can find a lot of relevant articles that might help you in the application development.
During the development process with TorizonCore, usually it is required to capture configuration changes on the /etc directory that needs to be committed to the TorizonCore image.
Here are some examples of procedures that require changes in the configuration of the system:
This article shows how to capture these system configurations.
This article complies to the Typographic Conventions for Torizon Documentation.
The pre-requisite to complete these instructions are:
To install TorizonCore Builder, read our statements on OS and shell compatibility, then follow the instructions below, in order.
Create and enter a working directory where your customization will be stored:
$ mkdir ~/tcbworkdir
$ cd ~/tcbworkdir
Use the setup script named tcb-env-setup.sh, available on the Toradex Github, to setup TorizonCore Builder:
$ wget https://raw.githubusercontent.com/toradex/tcb-env-setup/master/tcb-env-setup.sh
$ source tcb-env-setup.sh
For advanced usage, run source tcb-env-setup.sh -h, or see the project README.
If using Windows, you must pass extra parameters to the script when using the following commands:
ostree serve: consult the ostree serve reference.Tip: 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.
Verify that the command torizoncore-builder is available:
$ torizoncore-builder --help
Warning: Make sure to: (1) source the script, (2) every time you open a new terminal, (3) inside the working directory you have previously created. Otherwise, it will not work as intended and, most importantly, the torizoncore-builder alias will not be created properly.
If you have made any configuration changes, they will be saved in the /etc directory of your board. The isolate command will fetch all those changes (modifications, addition, deletion, and files and directories permissions and ownership). It requires an SSH connection for the communication between the host PC and the target board.
Get configuration changes from the target board, saving them in a specific directory, in this case changes1, with this command:
$ torizoncore-builder isolate --remote-host 192.168.1.117 --remote-username torizon --remote-password torizon --changes-directory changes1
Changes in /etc successfully isolated.
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.
Tip: In order to keep credentials (files and directories permissions and ownership) the isolate command will create the file /etc/.tcattr which will be automatically used later by the union command.
For more details about the isolate command, please check the isolate command in the commands manual.
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.
Attention: Both approaches generate a custom Toradex Easy Installer image as output, so the approaches should be followed alternatively and not in sequence.
TorizonCore Builder build command generates a custom TorizonCore image with the captured configuration changes, 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.yaml 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 TorizonCore (preferably without containers), torizon-core-docker-colibri-imx6-Tezi_5.3.0+build.7.tar in this case, as input. The directory (or directories) with the captured configuration changes is passed as customization: filesystem.
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 configuration changes made in the device customization: filesystem: - changes1/ output: easy-installer: local: torizon-core-docker-colibri-imx6-Tezi_5.3.0.CUSTOM
To generate the TorizonCore 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>
To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.
In this second approach, instead of using a configuration YAML file and a one-step command, the generation of the custom TorizonCore with the captured configuration changes 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 captured configuration changes (or other customizations like different device tree overlays). Including a directory with captured changes on an image of TorizonCore is just a matter of passing it as a --changes-directory argument to the union command. Therefore, it is just necessary to perform the union and deploy stages (also the isolate step is necessary if you want to capture the new configuration changes from the device).
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 directories with captured configuration changes follow the sequence of steps below.
You just need to execute once. Then, you are ready to apply multiple changes to the image. For example, in addition to applying configuration changes captured from the device, you can also apply a custom splash screen, a new device tree, among other possibilities.
If you have not unpacked an image yet, download a base TorizonCore 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 TorizonCore 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 TorizonCore 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.
As a reminder, you must have captured changes as explained previously.
Merge the captured configuration changes (as well as other customizations like a kernel module or a device tree) into the base Toradex Easy Installer image of TorizonCore - 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.
$ torizoncore-builder union --union-branch=custom-branch
Warning: 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.
To deploy the custom Toradex Easy Installer image to the board, click on the link below and choose between the available options.
After rebooting, in your target device's terminal, verify that your new custom image of TorizonCore 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:
union command in the case of the standalone commandsbuild command.
