Yocto Project for iMX6ULL Part 2: Customizing image used in the installation process.

So far in this series, we've shown how to set up the development environment and integrate a meta-layer to include our custom device tree file.

This time, I am begging with one question: have you ever flashed a Linux image to the Toradex SoM module? If yes, you may have needed to customize the image name and the screens displayed during installation by adding your screens.

Well, guess what? This article can help you with that!

So, let's get started!

Other articles related to the iMX6ULL module

• Yocto Project for iMX6ULL Part 0: Concepts, Setting up, and Building.
• Yocto Project for iMX6ULL Part 1: Creating a meta layer and adding a custom device tree.
• Qt on iMX6ULL Part 0: Installation and Initial Setup.
• Qt on iMX6ULL Part 1: Hello, LED On/Off.
• Qt on iMX6ULL Part 2: Logging messages and settings for debugging.

Hardware requirements

I'll use the following hardware configuration:

• Toradex SoM: Colibri iMX6ULL 512MB IT V1.1A.
• Toradex Board: Aster V1.1B.
• Toradex Display: Resistive Touch Display 7" Parallel.

Create the logo and screen image slide files.

The Toradex company provides the Easy Installer tool for flashing Linux images onto SoM modules — a straightforward method to flash your image!

This tool allows us to perform some customization, such as changing the image name, updating the accompanying logo, and altering the screens displayed during the installation.

First, we'll create a custom logo to accompany the image's name displayed in the Easy Installer's main window. I'm talking about the classic and well-known Tux used by default!

Explore the image folder we built and search for the toradexlinux.png file. Notice its properties: it's a PNG file with dimensions of 40×40 pixels.

Following this model, I resized a LinkedIn logo in PNG format to 40×40 pixels. Simple!

Now, let's focus on the screens during image installation. You might have noticed a series of screens displayed in a loop, five to be precise.

The Easy Installer window supports a VGA resolution. Considering the bottom bar, the images should ideally be about 640×400 pixels.

I've chosen to use four image slides, as illustrated below:

Could you revise the image folder we built and look for the marketing.tar file? Peek inside. What do you find?

To replace the logo and the screens, one could take their own PNG logo image, ensure it's the same pixel size, and rename it to toradexlinux.png. Place it inside the image folder. Repeat the process by substituting the marketing.tar file with your own. Voilà!

It works! But let's be honest, this isn't quite the professional approach for a Yocto Project article series, is it?

Note: Store the 640×400 pixels image file inside the slides_vga folder in the marketing.tar.

Create the recipes to customize the images.

Back to our Yocto Project, we focus on the layers/meta-toradex-bsp-common/recipes-bsp/tezi-metadata/files/ folder. Inside, you'll find key files such as toradexlinux.png and the marketing.tar.

You might think updating these files directly is enough. But there's a better approach by using a bbappend file, just as we did in Yocto Project for iMX6ULL Part 1.

Inside layers/meta-toradex-bsp-common/recipes-bsp/tezi-metadata/, there's a recipe called tezi-metadata_0.3.bb, our appending target.

layers/meta-toradex-bsp-common/
├── ...
...
├── recipes-bsp
│   ├── mwifiexconf
│   │   ├── ...
│   ├── tezi-metadata
│   │   ├── files     <= toradexlinux.png and marketing.tar
│   │   └── tezi-metadata_0.3.bb   <= We have to append to this file
│   └── u-boot
│       ├── ...
...        

Start by creating the tezi-metadata folder within layers/meta-article/recipes-bsp/ and add a tezi-metadata_%.bbappend file. Then, create a files directory within layers/meta-article/recipes-bsp/tezi-metadata/. Place your custom logo and marketing.tar here.

The names of the logo and the files within marketing.tar don't have to match the default ones. You can just rename them.

Remember: The images, sized at 640×400 pixels, should be housed inside the slides_vga folder within the marketing.tar.

The tezi-metadata_%.bbappend file takes care of copying the logo and screen files to the final image package for installation. The '%' symbol in the filename acts as a wildcard, allowing this bbappend to apply to any version of the tezi-metadata recipe.

Insert the following content into tezi-metadata_%.bbappend:

FILESEXTRAPATHS:prepend := "${THISDIR}/files:"

# Modify the variables below to select correct files.
MKT = "marketing_article.tar"
ICON = "toradexlinux_article.png"

SRC_URI:append = " \
    file://${MKT};unpack=false \
	file://${ICON} \
"

do_deploy:append(){
    rm ${DEPLOYDIR}/marketing.tar
    install -m 644 ${WORKDIR}/${MKT} ${DEPLOYDIR}/marketing.tar

    rm ${DEPLOYDIR}/toradexlinux.png
    install -m 644 ${WORKDIR}/${ICON} ${DEPLOYDIR}/toradexlinux.png
}        

This .bbappend file contains instructions for BitBake to customize the build process by specifying two new files: a marketing tarball (marketing_article.tar) and an icon (toradexlinux_article.png).

During the deployment phase, the script removes any pre-existing marketing and icon files in the deployment directory. It replaces them with these custom versions, preserving their original names for compatibility with the system expecting them. Additionally, it sets the permissions of the newly copied files to be readable and writable by the owner, and readable by everyone else.

This ensures that the custom images appear during the installation process of the Linux image on the target device.

With these steps, the project folder structure should now look like this:

layers/meta-article/
├── conf
│   ├── layer.conf
│   └── machine
│       └── colibri-imx6ull-extra.conf
├── COPYING.MIT
├── README
├── recipes-bsp
│   ├── tezi-metadata
│   │   ├── files
│   │   │   ├── marketing_article.tar
│   │   │   └── toradexlinux_article.png
│   │   └── tezi-metadata_%.bbappend
│   └── u-boot
│       └── u-boot-toradex_%.bbappend
├── recipes-example
│   └── example
│       └── example_0.1.bb
└── recipes-kernel
    └── linux
        ├── linux-toradex
        │   └── my-custom-devicetree-file.dts
        └── linux-toradex%.bbappend        

Building the image

To start building your custom image, navigate to the project folder, mine is named Yocto-Project-for-iMX6ULL.

From there, initiate the Docker image to set up your build environment. It's important to always use the latest version of the image for optimal results.

$ docker run --rm -it -v ~/.gitconfig:/etc/gitconfig -v $(pwd):/home/imx6ull/oe-core charlesdias/yocto_imx6ull_bsp6:latest        

Upon starting the image, be sure to source the environment variables with the following command:

$ . export        

Before proceeding to the build, make a final adjustment to the local.conf file. At the end of the file, add the following lines:

TORADEX_PRODUCT_IDS[0036] = "my-custom-devicetree-file.dtb"
TORADEX_PRODUCT_IDS[0040] = "my-custom-devicetree-file.dtb"
TORADEX_PRODUCT_IDS[0044] = "my-custom-devicetree-file.dtb"
TORADEX_PRODUCT_IDS[0045] = "my-custom-devicetree-file.dtb"        

This addition effectively overrides the TORADEX_PRODUCT_IDS variable, ensuring the custom device tree is included in the final image.json file. This eliminates the need for manual updates to image.json, as was done in the previous article.

Now it's time to build the image:

$ bitbake -k tdx-reference-multimedia-image        

After the build process concludes, go to the image folder and extract the contents of the Colibri-iMX6ULL_Reference-Multimedia-Image-...build.0.tar file.

Verify that your custom toradexlinux.png and marketing.tar files are present and correspond to your files. Additionally, inspect the image.json file and check the "rawfiles" key to see if it includes the custom device tree.

The next step is to transfer the newly built Linux image onto a USB memory stick and flash it onto the SoM.

Enjoy the results of your custom installation!

Conclusion

Isn't it amazing?

I'm just wondering if you noticed my image appeared with a different name.

How did I do this?

Here's a hint: Could you take a look at the tdx-reference-multimedia-image.bb recipe and consider creating a bbappend for it. 😉

See you in the following article!

Links:

• Yocto Project for iMX6ULL Part 0: Concepts, Setting up, and Building.
• Yocto Project for iMX6ULL Part 1: Creating a meta layer and adding a custom device tree.
• Toradex Easy Installer.