Search by Tags

Flashing Embedded Linux to Vybrid Modules


Article updated at 20 Aug 2020
Compare with Revision

This article shows how to flash Embedded Linux onto Toradex Colibri VF50/VF61 modules using the flashing utilities provided by the Toradex image. For Vybrid the following flashing methods are currently possible:

  • Using an SD card
  • Using a USB flash drive aka memory stick
  • Using TFTP over Ethernet

The recommended way of flashing Embedded Linux onto Colibri VF50/VF61 modules is using the installed version of the boot loader (Normally Eboot) to upgrade the device. In case the boot loader got corrupted and does no longer work please refer to the VFxx Recovery Mode article. For release specific information please also consult the Vybrid Release Notes.


The preparation steps need to be executed on a x86-64 development host running a Linux distribution (e.g. Fedora or Ubuntu). Please note that there is no support for 32 bit hosts.

The following host applications and libraries are a pre-requisite for executing the update script and the 64-bit host tools contained in the image tarball.

E.g. for Ubuntu 14.04 (64-bit)

sudo apt-get update
sudo apt-get install dosfstools e2fsprogs gawk mtools parted
sudo apt-get install zlib1g liblzo2-2 libuuid1 libusb-1.0-0

E.g. for Fedora 21 (64-bit)

yum install dosfstools e2fsprogs gawk mtools parted 
yum install zlib lzo libuuid libusbx

On older distros (e.g. Ubuntu 12.04) the tool to create a FAT filesystem was named mkfs.vfat while the script uses mkfs.fat. If you get an error that mkfs.fat is missing then find the full path to mkfs.vfat and create a symlink by doing the following:

trdx@trdx:~$ sudo sh -c "command -v mkfs.vfat"
trdx@trdx:~$ sudo ln -s /sbin/mkfs.vfat /sbin/mkfs.fat


Note: Due to the limited amount of RAM available on Colibri VF50, the full LXDE demo image simply won't fit. Please use the console-tdx-image aka Colibri-VF_Console-Image instead.

It is possible to flash an embedded Linux image to a target module using two methods:

  • Toradex Easy Installer flashing: the preferred method for flashing. Check out the Toradex Easy Installer article for comprehensive information, including supported and pre-installed modules.
  • Legacy flashing: the flashing method prior to Toradex Easy Installer, uses bash script.

Note: Legacy flashing method does not imply that the embedded Linux image is legacy. There are pre-built Toradex images that are provided in both legacy and Toradex Easy Installer formats. Consult the image releases for a list of images in both formats.

Attention: If your Computer on Module is supported by the Toradex Easy Installer, the legacy flashing method is considered deprecated and you shouldn't use it.

This prepares a SD card or USB flash drive for later use on the carrier board with the module which is to be flashed.

  1. Download the binary image and extract it with root permissions. The binary image files are named as follows:
    • Starting with version 2.7.2: <module-type>_<image-name>_<version>.tar.bz2 where <module_type> is one of Apalis TK1, Apalis T30, Apalis/Colibri iMX6, Colibri iMX7, Colibri-T20, Colibri-T30, or Colibri-VF and is one of LXDE-Image or Console-Image.
    • Older versions: <module_type>_LinuxImageVx.yz.tar.bz2 where <module_type> is one of Colibri_T20, Colibri_T30 or Colibri_VF.

You can find all the latest pre-built images in Binary Images, both in the legacy as well as the Toradex Easy Installer formats, or conveniently in the tables below, only in the legacy image format:

Toradex Embedded Linux Stable Releases

OS Image Supported Modules/Download Link Summary Overview
Tux Linux LXDE Image Apalis TK1 (2.8.7 | 2020-06-10)
Apalis TK1 Mainline (2.8.7 | 2020-06-10)
Apalis T30 (2.8.7 | 2020-06-10)
Apalis iMX6 (2.8.7 | 2020-06-10)
Colibri T30 (2.8.7 | 2020-06-10)
Colibri T20 (2.8.7 | 2020-06-10)
Colibri iMX6 (2.8.7 | 2020-06-10)
Colibri iMX7 (2.8.7 | 2020-06-10)
Colibri VFxx (2.8.7 | 2020-06-10)
Angstrom LXDE desktop environment image
Tux Linux Console Image Colibri VFxx (2.8.7 | 2020-06-10) Linux Image without graphical user interface
Older releases
  1. Use any FAT formatted SD/uSD card or USB flash drive with enough free space (1GB or more recommended).

    Note: U-Boot expects a partition table (MBR) on the SD card or USB flash drive and the FAT partition to be the first partition!

  2. Find the mount point of your SD/uSD card or USB flash drive by e.g. using df or lsblk:

    [user@host ~]$ df
    Filesystem              1K-blocks      Used Available Use% Mounted on
    /dev/mmcblk0p1            7582228   2808272   4773956  38% /media/KERNEL
    [user@host ~]$ lsblk
    NAME                         MAJ:MIN RM   SIZE RO TYPE  MOUNTPOINT
    mmcblk0                      179:0    0   7.3G  0 disk  
    └─mmcblk0p1                  179:1    0   7.3G  0 part  /media/KERNEL
  1. Run the script with the -o argument pointing to the mount point of the SD card or USB flash drive. For example assuming the SD card is mounted at /media/KERNEL:
    ./ -o /media/KERNEL/

At this point the SD/uSD card or USB flash drive should contain U-Boot, optionally the Linux kernel, the flashing scripts and the ext3 (for eMMC modules) resp. UBI (for NAND modules) root file system images.

Flashing using Eboot (WinCE Toradex Bootloader)

By default, Colibri VF50/VF61 modules will be shipped with Eboot. This steps need to be followed the first time in order to switch to U-Boot.

  1. Prepare an SD card using Linux as described in the preparation step.
    The Linux image needs to be on a SD card, a USB flash drive is not recognized by Eboot.
  2. Connect the Colibri's UART_A to your host PC. Run a terminal program on your host PC and open the COM-Port that you just connected.
  3. On your PC, select your terminal application to get the focus. Press the SPACE key and keep it pressed while turning on the Toradex system.
    This procedure will stop the bootloader and you will see the bootloader menu in the terminal application:
    Toradex Bootloader 1.1 BETA 2 for Colibri Built Apr 28 2015
    CPU: MVF61 500 Mhz
    Flash: 512 MB  
    RAM: 256 MB
    Using ECC Type: 7
    Booting from fuses.
    Colibri VF61 module version 1.2A

    Press [SPACE] to enter Bootloader Menu

    Initiating image launch in 1 seconds. 
    BootLoader Configuration:

    C) Clear Flash Registry
    X) Enter CommandPrompt Mode
    D) Download image to RAM now
    F) Download image to FLASH now
    L) Launch existing flash resident image now

    Enter your selection:
  1. While in the main menu press X to enter CommandPrompt Mode
  2. Then enter flashloader colibri_vf/u-boot-nand.imx to flash U-Boot. Enter reboot or power-cycle the board.

    Note: BSP versions prior to V2.5 beta 2 did not yet use any module type specific folders therefore leave the colibri_vf/ part away.

    Enter your selection: x

    >flashloader colibri_vf/u-boot-nand.imx
    Bootloader image size: 424728 bytes.

    Loading done.
    Flashing bootloader.
    Writing 208 sector(s) of bootloader code from sector 64.

    Erasing block 1
    Erasing block 2
    Erasing block 3
    Erasing block 4
    Flashing completed.

  1. Hit any key immediately to stop auto booting
  2. The UBI partition needs to be erased before use, hence the command nand erase.part ubi before the update procedure is needed:
    Colibri VFxx # nand erase.part ubi
    Colibri VFxx # run setupdate
    Colibri VFxx # run update

Flashing from U-Boot

Follow the steps below to upgrade or re-flash the module.

  1. Insert the prepared media into carrier board
    • SD card into SD card/MMC SDIO-socket (X15 on Evaluation Board, X10 on Iris)
    • USB flash drive using a standard USB host plug (e.g. X31/X32 on Evalution Board, X11 on Iris, top X6 on Viola)
  2. Connect the serial console to your host PC

    • Evaluation Board V3.1a/V3.2a: 115200 baud on UART_A (lower X25 resp. X27 depending on JP17/19) without any handshake
    • Iris V1.1a: 115200 baud on UART_A (X13) without any handshake

    Note: U-Boot provides only a serial console. To get to that console of U-Boot one needs to open the /dev/ttySx or /dev/ttyUSBx port with a terminal emulation program like minicom on Linux or a CoMx port on Windows with PuTTY, with baud rate 115200, 8 data bits, no parity and one stop bit without any hardware/software flow control.

  3. Apply power or reset

  4. Hit any key immediately to stop auto booting
    U-Boot 2014.10 (Feb 03 2015 - 17:54:12)

    CPU:   NXP/Freescale Vybrid VF610 at 500 MHz
    Reset cause: EXTERNAL RESET
    Board: Colibri VF61
    DRAM:  256 MiB
    NAND:  512 MiB
    MMC:   FSL_SDHC: 0
    In:    serial
    Out:   serial
    Err:   serial
    Net:   FEC
    Hit any key to stop autoboot:  0
    Colibri VFxx # 

At this point the U-Boot prompt should be visible.

  1. Use run setupdate and run update command to update the module
    Colibri VFxx # run setupdate
    Colibri VFxx # run update
**Note:** Modules flashed with images V2.3 Beta 3 and older need to be flashed with the latest V2.3 release V2.3 Beta 7, otherwise the configuration block might be lost. Alternatively, the modules can be Flashed from Scratch (see below).

**Note:** For old U-Boot versions instead of using ``run setupdate`` to load the update script use the following command:

    Colibri VFxx # mmc rescan; fatload mmc 0:1 ${loadaddr} flash_mmc.img; source ${loadaddr}

Flashing from Scratch

In case the module doesn't show any boot loader output or hangs at very early stages refer to the VFxx Recovery Mode article to download U-Boot directly into RAM. From the U-Boot command prompt some additional commands makes sure that the whole NAND is erased and rewritten including the first boot configuration block (BCB). Within the boot configuration block the Toradex config block (production data such as serial number) is stored too, hence recreating the BCB also requires to restore the Toradex config block.

Colibri VFxx # nand erase.chip
Colibri VFxx # run setupdate
Colibri VFxx # run create_bcb
Colibri VFxx # cfgblock create
Is the module an IT version? [y/N] y
Enter the module version (e.g. V1.1B): V1.1B
Enter module serial number: 04815386
Toradex config block successfully written
Colibri VFxx # run update

Note: When U-Boot was started using the recovery mode the module will hang with the last output "resetting ...". This is because the Vybrid SoC stores the "enter recovery mode" flag beyond a hardware or software reset. To clear the "enter recovery mode" flag power the module off and back on (power cycle).

Note: The cfgblock create command is available since BSP release V2.4 Beta 1 (U-Boot 2015.04). To recover the config block for older U-Boot versions use the script and copy the configblock.bin file to the SD-card. Then, use run setupdate && run update_configblock.

Downgrade to an earlier Version

While downgrading between some versions might work, the scripts do not generally take care of this use case (e.g. the scripts do not downgrade the NAND format or configuration block). Hence, the recommended way to downgrade is to use U-Boot of the (older) target versions and flash from scratch. There are two methods to boot into the old U-Boot: either using the Vybrid Recovery Mode, or, if a recent version of U-Boot 2015.04 is already on the module, using the U-Boot bmode command.

  • If you plan to flash a version older than V2.4 Beta 1, use to create a config block for your module.
  • Prepare a SD-Card as usual (see above). If you plan to use the U-Boot bmode command, make sure to use which creates a bootable SD-Card.
  • Depending on the method used to download U-Boot, use either

    a) the Vybrid recovery mode, or

    b) the bmode command

    Colibri VFxx # bmode esdhc1
  • Flash from scratch using the instructions provided in the chapter Flashing from Scratch above. If you flash a version older than V2.4 Beta 1, remember to flash the config block using run setupdate && run update_configblock.


The update scripts should cope with the standard update and upgrade cases. However sometimes things can go wrong. This section helps to recover the module in those situations.

Upgrading fails with UBI init error 22

Since V2.4 we try not to delete the UBI volume to retain the erase counters and hence proper wear leveling information. This can lead to problems when using NAND flash with incompatible ECC modes or file systems (Windows CE). In this case the UBI stack of U-Boot claims an "init error":

UBI: default fastmap pool size: 200
UBI: default fastmap WL pool size: 25
UBI: attaching mtd1 to ubi0
UBI: scanning is finished
UBI init error 22

To solve this issue a proper cleaning of the UBI partition is required before starting the update process:

Colibri VFxx # nand erase.part ubi
Colibri VFxx # run update

Creating the BCB fails

Creating the BCB fails with "Skipping bad block at 0x00000000"

Colibri VFxx # run create_bcb

NAND erase.part: device 0 offset 0x0, size 0x20000
Skipping bad block at  0x00000000

Block 0x00000000 is guaranteed to be good by the NAND manufacturer so this block should not be a bad block. However some Eboot versions marked the block accidentally as bad. To recover from this situation a sufficient recent U-Boot version is needed. The following commands clean the block completely (including its bad block marker) and also remove the U-Boot/Linux bad block table (use them with care):

Colibri VFxx # nand scrub -y 0x00000000 0x20000
Colibri VFxx # nand scrub -y 0x07f80000 0x80000 # For Colibri VF50
Colibri VFxx # nand scrub -y 0x1ff80000 0x80000 # For Colibri VF61
Colibri VFxx # nand scrub -y 0x3ff80000 0x80000 # For Colibri VF61 (initial samples with 1 GB NAND flash)