Testing a Yocto Image with Custom U-Boot and Mender OTA

Hello everyone,

I want to test my Yocto-generated image on a Toradex board. So far, I have tested by flashing my .gptimg file to an SD card, and it works with the pre-installed U-Boot on the board.

My goal now is to test the full system integrity, including my own U-Boot binary built with Yocto, because I need to implement modifications in U-Boot so that OTA updates via Mender can interact correctly with the bootloader.

However, I am not sure how to properly deploy my U-Boot binary on the board, along with my .gptimg partitioning.

Currently, the only working setup is:

  • Pre-installed U-Boot on the board
  • SD card flashed with my Yocto-generated .gptimg

The issue is that I cannot access Mender OTA features, because the pre-installed U-Boot does not support the Mender environment.

Could someone advise me on the best way to test my custom U-Boot with my .gptimg, while keeping the ability to use Mender OTA?

Environment details:

  • Machine: verdin-imx8mp
  • BSP: toradex-bsp-7.5.0
  • Branch: scarthgap

Thanks in advance for your help!

Hi, I’m the Toradex AI Assistant.

I might make mistakes or occasionally get you wrong. Our support team will step in if needed.


Deploying Custom U-Boot with Mender OTA Support

Based on your requirements, you need to deploy your custom U-Boot binary to test the complete system integration with Mender OTA. Here’s how to approach this:

U-Boot Configuration for Verdin iMX8MP

For the Verdin iMX8MP, you’ll need to build U-Boot with the correct configuration(1). The U-Boot configuration for your module is verdin-imx8mp_defconfig(1), and the binary output will be imx-boot(1).

Building U-Boot from Source

To build your custom U-Boot with Mender support:

1. Set Up Cross-Compilation Environment

For 64-bit modules like the Verdin iMX8MP, prepare the environment variables(1):

$ export ARCH=arm64
$ export DTC_FLAGS="-@"
$ export PATH=~/gcc-linaro-aarch64/bin/:$PATH
$ export CROSS_COMPILE=aarch64-none-linux-gnu-

(1)

2. Configure and Build U-Boot

$ cd ~/workdir/u-boot
$ make mrproper
$ make verdin-imx8mp_defconfig
$ make -j$(nproc) 2>&1 | tee build.log

(1)

Deploying Your Custom U-Boot

Understanding U-Boot Environment Variables

When deploying your custom U-Boot, be aware that U-Boot uses environment variables stored in a key-value store in RAM(2). The environment can come from two sources:

  1. Default Environment Variables: Built into the U-Boot binary at compilation time(2)
  2. Persistent Environment: Stored in non-volatile memory (eMMC or NAND)(2)

Important Considerations

When you save environment variables using saveenv, the entire environment is written to persistent memory, not just the changed variable(2). This can have unexpected consequences, as dynamically calculated variables may become static(2).

Recommended Approach for Testing

Since you’re working with Mender OTA integration, I recommend using Torizon Remote Updates instead of custom Mender implementation. Torizon is specifically designed for Toradex hardware and provides integrated OTA functionality(3).

Why Torizon Remote Updates?

Torizon Remote Updates is the recommended OTA solution for Toradex customers(3). It’s built from the ground up to be fully integrated with Toradex hardware and offers companion tooling for better developer experience(3). The system uses OSTree technology for atomic updates with rollback capabilities(3).

Alternative Testing Strategy

If you must proceed with your custom U-Boot deployment:

  1. Flash your custom U-Boot to the eMMC boot partition
  2. Deploy your .gptimg to the main storage
  3. Configure U-Boot environment variables to support Mender integration

However, be extremely careful when modifying the persistent U-Boot environment, as incorrect changes can affect the boot process(2).

Best Practices

  • Never copy the entire environment from one module to another, as this can permanently change the MAC address(2)
  • Use fw_printenv and fw_setenv tools from Linux to interact with U-Boot environment variables(2)
  • Always test your custom U-Boot thoroughly before deploying to production devices

Best regards, Toradex AI Assistant.


Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

Hey @ToradexAI

Unfortunately, Mender is the only OTA solution we can use for our project, so I need to continue working in this direction.

However, when trying to use the installation via Toradex Easy Installer, I’m facing some issues.
I’m using the following layer:

meta-toradex-tezi:
  url: "https://github.com/toradex/meta-toradex-tezi.git"
  refspec: "scarthgap-7.x.y"

And in my local.conf, I have the following configuration:

INHERIT += "mender-toradex"
IMAGE_CLASSES += "image_type_mender_tezi"
IMAGE_FSTYPES:append = " mender_tezi"
IMAGE_FSTYPES:remove = " tezirunimg"

This generates two different TEZI folders:

:one: The standard one:
Verdin-iMX8MP_Reference-Minimal-Image-Tezi_7.5.0-devel-20251113125926+build.0.tar

I flash it manually to the SD card using these commands:

sudo fdisk /dev/sda
# o → new DOS table (MBR)
# n → create primary partition
# w → write changes
sudo mkfs.vfat -F 32 /dev/sda1
sudo dosfslabel /dev/sda1 MYUSB
sudo mount /dev/sda1 /mnt
sudo cp -r Verdin-iMX8MP_Reference-Minimal-Image-Tezi_7.5.0-devel-20251113125926+build.0/* /mnt/
sync
sudo umount /mnt

So my SD card contains:

image.json
LA_OPT_NXP_SW.html
prepare.sh
Reference-Minimal-Image-imx8mp-verdin.tar.xz
Reference-Minimal-Image-imx8mp-verdin.bootfs.tar.xz
imx-boot
u-boot-initial-env-sd
wrapup.sh
toradexlinux.png

When I flash it using the Toradex Easy Installer interface, it boots, but I get the following U-Boot errors:

No EFI system partition
Failed to persist EFI variables
bad MBR sector signature 0x8052
...
Failed to load '/tezi.itb'
Wrong Image Type for bootm command
ERROR -91: can't get kernel image!

:two: The Mender version:
Verdin-iMX8MP_Reference-Minimal-Image.mender_tezi.tar

This one contains:

image.json
imx-boot
uboot.env
Reference-Minimal-Image-imx8mp-verdin.gptimg
marketing_mender_toradex.tar
mender_toradex_linux.png
prepare.sh
wrapup.sh

But when I try to install it via Toradex Easy Installer, I get this error:

“The image has not been written completely. Please restart the process otherwise you might end up in a non-bootable system.”

So, I’m not sure what I’m missing here.
How can I correctly integrate my custom U-Boot binary built with Yocto and flash my Mender-enabled .gptimg using the Toradex Easy Installer?

Thanks for your help!

Let me help you troubleshoot the TEZI deployment issues with your custom U-Boot and Mender integration.

Understanding the Boot Errors

The U-Boot errors you’re seeing indicate several issues with the TEZI image configuration:

Standard TEZI Image Issues

The errors like “Failed to load ‘/tezi.itb’” and “Wrong Image Type for bootm command” suggest that the TEZI bootloader is looking for specific files that may not be properly configured in your image(1).

Mender TEZI Image Issues

The incomplete installation error indicates that the Mender-enabled TEZI image may have configuration problems or missing components required for proper deployment(1).

Deploying Custom U-Boot with TEZI

Based on the Toradex documentation, here’s how to properly deploy your custom U-Boot binary:

1. Start with a Working Base Image

Download and extract one of the Toradex prebuilt images as a starting point(2). Choose the appropriate image for your Verdin iMX8MP from the Reference Images downloads(2).

2. Replace the U-Boot Binary

After building your custom U-Boot with the correct configuration for Verdin iMX8MP, you need to replace the bootloader in your TEZI image(2):

# Extract your TEZI image
$ tar xvf <your-tezi-image>.tar --no-same-owner

# Replace the U-Boot binary with your custom one
$ sudo cp <your-custom-uboot-folder>/imx-boot imx-boot
$ sudo sync

(2)

3. Verify TEZI Image Structure

Your TEZI image should contain the essential files for proper installation(1). The standard structure should include:

  • image.json - Configuration file
  • imx-boot - Your custom U-Boot binary
  • Image files (.tar.xz or .gptimg)
  • Installation scripts (prepare.sh, wrapup.sh)

Troubleshooting the Mender TEZI Integration

Check Image Configuration

The image.json file is crucial for TEZI operation(1). Ensure that:

  1. The file paths in image.json match your actual files
  2. The partition layout is correctly defined for Mender
  3. The bootloader configuration points to your custom U-Boot

Verify File Integrity

The “image has not been written completely” error suggests potential file corruption or size mismatches(1). Verify that:

  • All files referenced in image.json are present
  • File sizes match the expected values
  • The .gptimg file is properly generated with Mender partitions

Best Practices for TEZI Deployment

Use Proper TEZI Installation

Instead of manually copying files to SD card, use the official TEZI installation process(1):

  1. Display Interface: Connect a display to your carrier board’s DVI-I/HDMI port(1)
  2. Network Interface: Use USB OTG connection with IP address 192.168.11.1 for VNC access(1)
  3. Follow TEZI GUI: Use the graphical interface to select and install your image(1)

Validate Your Build Configuration

Ensure your Yocto build properly generates TEZI-compatible images(3). The build output should be located at build/deploy/images/${MACHINE}/(3), and you should deploy the generated TEZI image using the Toradex Easy Installer(3).

Recommended Debugging Steps

  1. Test Standard TEZI First: Verify that a standard Toradex TEZI image works on your hardware
  2. Incremental Changes: Start with the working TEZI image and gradually replace components
  3. Check Build Logs: Review your Yocto build logs for any warnings or errors related to TEZI generation
  4. Validate U-Boot Environment: Ensure your custom U-Boot has the correct environment variables for Mender integration

The key is to ensure that your custom U-Boot binary is properly integrated into a valid TEZI image structure while maintaining compatibility with both the TEZI installer and Mender requirements.

Best regards, Toradex AI Assistant.


Did you like my answer? :+1: :-1:

If I answered your question, please tick the “Solution” checkbox.

For follow-up questions to me, please use @ToradexAI in your post.

@ToradexAI after checking everything carefully, I still don’t see where the problem could be.
Here’s the content of my TEZI-Mender folder (the one I put on the SD card):

❯ ls Reference-Minimal-Image-imx8mp-verdin/
image.json
marketing_mender_toradex.tar
prepare.sh
uboot.env
imx-boot
mender_toradex_linux.png
Reference-Minimal-Image-imx8mp-verdin.gptimg
wrapup.sh

And here’s the content of my image.json file:

{
    "config_format": "4",
    "autoinstall": false,
    "name": "Toradex Embedded Linux Reference Minimal Image",
    "description": "Minimal image without graphical interface that just boots",
    "version": "Mender scarthgap",
    "release_date": "2025-11-12",
    "prepare_script": "prepare.sh",
    "wrapup_script": "wrapup.sh",
    "marketing": "mender-tezi-metadata/marketing_mender_toradex.tar",
    "icon": "mender-tezi-metadata/mender_toradex_linux.png",
    "supported_product_ids": [
        "0058", "0061", "0063", "0064", "0065", "0066", "0070"
    ],
    "blockdevs": [
        {
            "name": "mmcblk1",
            "table_type": "gpt",
            "content": {
                "rawfiles": [
                    {
                        "dd_options": "bs=8M",
                        "filename": "Reference-Minimal-Image-imx8mp-verdin.gptimg"
                    }
                ]
            }
        },
        {
            "name": "mmcblk1boot0",
            "erase": true,
            "content": {
                "filesystem_type": "raw",
                "rawfiles": [
                    {
                        "filename": "imx-boot",
                        "dd_options": "seek=0"
                    }
                ]
            }
        }
    ]
}

From what I can see, everything looks correct — the structure matches the expected TEZI format, and all files are present.
Moreover, I tested my .gptimg manually, and it boots fine when using the preloaded U-Boot on the board.

Do you see anything here that could cause the issue during the TEZI installation ?

Hi @stan!

We’re going to continue the support in this other thread.

Best regards.