Search by Tags

Flashing Embedded Linux to iMX7 Modules

Applicable for


Article updated at 17 Jun 2019
Compare with Revision

Subscribe for this article updates

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.

This article shows how to flash Embedded Linux onto Toradex Colibri iMX7S/iMX7D modules using the legacy flashing utilities provided by Toradex images.

Warning: Colibri iMX7 Dual 1GB (eMMC) modules are not supported by the legacy update scripts. This article is not applicable! Please use the Toradex Easy Installer.


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


Warning: V2.7 Beta 1 release suffers a bug which does not allow to use an USB flash drive for flashing.

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 | 2019-04-01)
Apalis TK1 Mainline (2.8 | 2019-04-01)
Apalis T30 (2.8 | 2019-04-01)
Apalis iMX6 (2.8 | 2019-04-01)
Colibri T30 (2.8 | 2019-04-01)
Colibri T20 (2.8 | 2019-04-01)
Colibri iMX6 (2.8 | 2019-04-01)
Colibri iMX7 (2.8 | 2019-04-01)
Colibri VFxx (2.8 | 2019-04-01)
Angstrom LXDE desktop environment image
Tux Linux Console Image Colibri VFxx (2.8 | 2019-04-01) 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
  3. 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.

Note: With the V2.6 Alpha 1 release updating using the USB flash drive does not work on Colibri iMX7S.

Flashing from U-Boot

Follow this step 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
  3. Apply power or reset
  4. You should see U-Boot starting up

    • Hit any key immediately to stop auto booting

      U-Boot 2015.04+fslc+g10bc451 (Jun 28 2016 - 13:08:25)
      CPU:   Freescale i.MX7SOLO rev1.0 at 792 MHz
      CPU:   Temperature 37 C
      Reset cause: POR
      I2C:   ready
      DRAM:  256 MiB
      PMIC: RN5T567 LSIVER=0x1 OTPVER=0xd
      NAND:  512 MiB
      MMC:   FSL_SDHC: 0
      No panel detected: default to vga-rgb
      Display: vga-rgb (640x480)
      Video: 640x480x18
      In:    serial
      Out:   serial
      Err:   serial
      Model: Toradex Colibri iMX7 Solo 256MB V1.1A, Serial# 02794104
      Net:   FEC0
      Normal Boot
      Hit any key to stop autoboot:  0 
      Colibri iMX7 # 
    • At this point the U-Boot prompt should be visible.

    • Use run setupdate and run update command to update the module

      Colibri iMX7 # run setupdate
      Colibri iMX7 # run update

      Note: When updating from a release prior to V2.7, after running run update a reset is required and a second update step using run setupdate && run recreate_bcb && run update will be required to upgrade the Boot Configuration Block (BCB). The update scripts will print a warning to remind you when this additional step is necessary.

    • Alternatively, you can use individual commands to flash only the kernel, device tree or the root file system like this:

      Colibri iMX7 # run setupdate
      Colibri iMX7 # run prepare_ubi
      Colibri iMX7 # run update_kernel
      Colibri iMX7 # run update_fdt
      Colibri iMX7 # run update_kernel

Note: V2.6 Alpha 1, Colibri iMX7S: After flashing the environment is cleared, and the standard device tree imx7d-colibri.dtb gets loaded. Use the following commands to load the Colibri iMX7S device tree:

Colibri iMX7 # setenv fdt_file imx7s-colibri.dtb
Colibri iMX7 # saveenv

Note: On older V1.1A modules a direct update to 2.7b2 or later is not easy to do and we recommend updating to V2.6.1Beta1 first.

Flashing from Scratch

In case the module doesn't show any boot loader output or hangs at very early stages, follow the iMX Recovery Mode to restore the module.

Warning: Make sure there is no SD card inserted in the carrier board in order to enter recovery mode properly

  1. Download a U-Boot into the device memory using ./ -d (from within the unpacked Toradex image):

    $ ./ -d
    Colibri iMX7 rootfs detected
    Put the module in recovery mode and press [ENTER]...
    [sudo] password for user: 
    config file imx_flash/imx_usb.conf
  2. On the target, use the following commands to erase the flash completely and rewrite the boot configuration block as well as the Toradex config block:

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