Mender on Toradex: How-to guide

Introduction

This white paper documents how to get a Yocto build with Mender integrated running on the Toradex Colibri-iMX7 board using the onboard NAND flash to store the root filesystem. It is possible to use other storage media such as SD/MMC or USB Mass Storage however those are not considered for this document.

This has been tested on an Ubuntu 16.04 build host with the branches of the various git repositories as of November 29, 2017. Your mileage may vary with other host systems and newer sources although it should be possible to resolve issues with those environments. Feel free to join the Mender mailing list or contact us for Consulting Services if you require additional assistance.

Initial Setup

To be able to build a Mender-enabled Yocto configuration, you need to first setup your build host with the necessary development packages to do Yocto development. Please follow the setup in the Yocto Project Quick Start to ensure you have the proper setup.

Branches and Sources

At the time of this writing, the Toradex repositories have a morty branch and a rocko-next branch which is an unsupported work-in-progress. Similarly, Mender currently supports pyro and has work-in-progress on both rocko and master. Since Mender’s and Toradex’s branches do not line up we have tested the following combinations. Note that these are not officially supported configurations but have been developer tested with minimal validation.

  • master branch (Mender and Yocto) + rocko-next branch (Toradex)

    • git://git.yoctoproject.org/poky.git, branch=master
    • git://git.yoctoproject.org/meta-freescale.git, branch=master
    • https://github.com/Freescale/meta-freescale-3rdparty.git, branch=master
    • https://github.com/drewmoseley/meta-toradex-bsp-common.git, branch=wip-master
    • git://git.toradex.com/meta-toradex-nxp.git, branch=rocko-next
    • git://github.com/mendersoftware/meta-mender.git, branch=master

  • pyro branch (Mender and Yocto) + morty branch (Toradex)

    • git://git.yoctoproject.org/poky.git, branch=pyro
    • git://git.yoctoproject.org/meta-freescale.git, branch=pyro
    • https://github.com/drewmoseley/meta-freescale-3rdparty.git, branch=wip-pyro
    • https://github.com/drewmoseley/meta-toradex-bsp-common.git, branch=wip-pyro
    • https://github.com/drewmoseley/meta-toradex-nxp.git, branch=wip-pyro
    • git://github.com/mendersoftware/meta-mender.git, branch=pyro

Note the repositories showing wip-pyro or wip-master branches are changes needed specifically to support this environment. They are intended for demo purposes only and we will be working with Toradex to remove the need for changes outside of their stock branches.

Building

Once you have completed the initial build host setup and checked out the appropriate combination of git repositories, you need to run the following steps to configure your bitbake build directory. Note that the call to oe-init-build-env will create a new directory using either a full path or a relative path depending on the parameter passed. If no parameter is provided, a new directory call build/ will be created in the current working directory.

$ . <full-path-to-source>/poky/oe-init-build-env \
                           <full-path-to-build-dir>
$ bitbake-layers add-layer <full-path-to-source>/meta-freescale
$ bitbake-layers add-layer <full-path-to-source>/meta-freescale-3rdparty
$ bitbake-layers add-layer <full-path-to-source>/meta-toradex-bsp-common
$ bitbake-layers add-layer <full-path-to-source>/meta-toradex-nxp
$ bitbake-layers add-layer \
              <full-path-to-source>/meta-mender/meta-mender-core
$ bitbake-layers add-layer \
              <full-path-to-source>/meta-mender/meta-mender-demo
$ bitbake-layers add-layer \
              <full-path-to-source>/meta-mender/meta-mender-toradex-nxp

Now you need to edit your `/conf/local.conf and setup the Mender-specific settings as detailed in our documentation. At a minimum, you need to add the following to your local.conf file, but there may be additional settings for Mender or Yocto needed depending on your project requirements.

MACHINE="colibri-imx7"
INHERIT += "mender-full-ubi"
DISTRO_FEATURES_append = " systemd"
VIRTUAL-RUNTIME_init_manager = "systemd"
DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
VIRTUAL-RUNTIME_initscripts = ""

Finally, you can build the core-image-full-cmdline image using the following:

`$ MACHINE=colibri-imx7-mender bitbake core-image-full-cmdline

Note that passing the MACHINE name in via the environment variable is mandatory for Toradex based builds. This requirement is due to the state of the Toradex layers and the Yocto master branch at the time of this writing. It’s possible that this requirement will be removed with ongoing development in both repositories.

Provisioning the Board

These steps assume you have a freshly formatted SD Card mounted at /media/SDCard in your build system. This SD Card is used for transferring the binaries from your build system to the board. This card should be formated with the vfat filesystem.

You also need to have the imx_usb utility. There are three methods that will likely work for this.

  1. Your host OS may have a package containing this utility.
  2. You can get a pre-built binary as part of the Toradex Easy Installer here: http://developer.toradex.com/software/toradex-easy-installer
  3. You can build it directly from your Yocto build using the following. The executable will then be available in the tmp/sysroots-components/x86_64/imx-usb-loader-native/usr/bin/ directory.

$ bitbake imx-usb-loader-native

Copy the necessary files from your build tree to the SD Card:

$ cd <full-path-to-build-dir>/tmp/deploy/images/colibri-imx7-mender/
$ cp --dereference u-boot-nand.imx \
                   core-image-full-cmdline-colibri-imx7-mender.ubimg \
              /media/SDCard
$ umount /media/SDCard

Move the SD Card with the new build contents from your build system to your target board. Now, connect the board. You will need an Ethernet cable connected to your network, and power. Either the barrel connector or the USB connector will work. Please consult the Toradex documentation if you have issues with these instructions. Their documentation should be supersede anything in this howto.

The USB power port also provides a serial port connection to your host for interacting with the serial console which is required to use U-Boot to copy the binaries into the flash memory.

Finally you need to have the microUSB port (labelled X10 on the Aster carrier board) connected to your PC for interaction with the imx_usb utility.

With the board disconnected from power, you need to short the two recovery mode pads on the SOM card and then power the board on. You can use sharp tweezers to do this however it may be easier to solder wires to the test points so that you can more easily connect them when needed. See chapter 7 of the Toradex SOM documentation for more details. This will put the board into recovery mode. You can then load your U-Boot image from your build directory into the device and execute it.

$ sudo \
<full-path-to-build-dir>/tmp/sysroots-components/x86_64/imx-usb-loader-native/usr/bin/imx_usb \
--configdir=<full-path-to-build-dir>/tmp/sysroots-components/x86_64/imx-usb-loader-native/etc/imx-loader.d/ \
<full-path-to-build-dir>/tmp/deploy/images/colibri-imx7-mender/u-boot-nand.imx

Note, the above assumes you are using the imx_usb utility from your bitbake build directory. If you use the Toradex provided binary or one provided by your host OS, you may not need to explicitly specify the "--configdir" parameter. Please consult the documentation for your chosen provider of this utility for more details.

Once this is done, you will see U-Boot running on the serial port device. Note that this device node for the serial port will not exist until the Colibri board is connected to the USB port of your host and the board is powered on. Hit any key to stop the autoboot sequence and you will be at the U-Boot prompt.

Insert the SDCard you prepared above into the Colibri board and run the following U-Boot commands. This will install your U-Boot image and ubimg file into the nand flash and then reboot into the newly installed Mender-enabled Yocto configuration.

nand erase.part u-boot1
nand erase.part u-boot2
load mmc 0:1 ${loadaddr} u-boot-nand.imx
nand write ${loadaddr} u-boot1 ${filesize}
nand write ${loadaddr} u-boot2 ${filesize}
nand erase.part u-boot-env
nand erase.part ubi
load mmc 0:1 ${loadaddr} core-image-full-cmdline-colibri-imx7-mender.ubimg
nand write ${loadaddr} ubi ${filesize}
reset

The following are the same instructions without newlines for easy copy/paste:

nand erase.part u-boot1; nand erase.part u-boot2; load mmc 0:1 ${loadaddr} u-boot-nand.imx; nand write ${loadaddr} u-boot1 ${filesize}; nand write ${loadaddr} u-boot2 ${filesize}; nand erase.part u-boot-env; nand erase.part ubi; load mmc 0:1 ${loadaddr} core-image-full-cmdline-colibri-imx7-mender.ubimg; nand write ${loadaddr} ubi ${filesize}
reset

Once the above is complete, you can remove the SD Card from the target board.