Building Your Own Yocto for MaaXBoard

INTRO

This tutorial is based on the Yocto Lite Development Guide for MaaXBoard that you can find on Element14. Last week, I created a guide for using the prebuilt Yocto image on MaaXBoard and MaaXBoard Mini. This week we'll be diving deeper into Yocto by building our own image. It's a good exercise to understand how Yocto works under the hood, and it's also useful for when you want to build custom images that incorporate your own layers and recipes.

REFERENCES

These references are totally optional reading, but I wanted to include them at the beginning of the tutorial because they're a good place to turn if you get stuck or want to go deeper on a concept.

• Yocto Project Overview (Overview of how the pieces of the Yocto project fit together)
• Yocto Project brief (short tutorial with steps for building an image)
• Yocto complete reference manual (comprehensive)
• https://source.codeaurora.org/ - NXP’s layers/recipes are all here I think
• NXP’s Yocto user’s guide (April 2021)

SETTING UP THE BUILD ENVIRONMENT

REQUIREMENTS:

Hardware: At least 40GB of disk space and 2GB of RAM

Software: Ubuntu 64bit OS, 18.04 LTS version or later LTS version (Ubuntu Desktop or Ubuntu Server version). You could also run the Ubuntu 64 bit OS on virtual machine (that's what I'll be doing).

Install the following packages:

sudo apt-get update && sudo apt-get install -y gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat libsdl1.2-dev xterm sed cvs subversion coreutils texi2html docbook-utils python-pysqlite2 help2man make gcc g++ desktop-file-utils libgl1-mesa-dev libglu1-mesa-dev mercurial autoconf automake groff curl lzop asciidoc u-boot-tools cpio sudo locales

Install the repo tool:

chmod -R a+x /usr/bin
curl http://commondatastorage.googleapis.com/git-repo-downloads/repo > /usr/bin/repo

META LAYERS

We'll be building using a variety of meta-layers. This includes generic meta layers like poky and meta-openembedded (the core Yocto layers from openembedded), as well as meta-browser, and meta-qt5.

We'll also use meta layers from NXP (meta-freescale, meta-freescale-3rdparty, meta-freescale-distro, meta-fsl-bsp-release, and optionally meta-imx-machinelearning).

Finally, we use a layer that is specific to MaaXBoard: meta-maaxboard.

This is the layer that contains MaaXBoard specific recipes, such as firmware, connectivity for bluetooth and wifi, and Tensorflow libraries in the case of sumo-eiq. You can find all the meta-maaxboard layers on Avnet's github here.

There are two supported versions of Yocto Project for MaaXBoard, and there are separate branches on Github for the corresponding meta-maaxboard layers:

• Sumo (Yocto 2.5.3)
• Zeus (Yocto 3.0.4) - I haven't personally tested this one but I've included instructions taken from the github

There's also a third branch that's Sumo and also includes NXP's machine learning layers:

• sumo-eiq

Download meta layers from NXP

Make a new directory called imx-yocto-bsp. We'll be downloading the board support package (BSP) and other meta layers here:

mkdir imx-yocto-bsp
sudo chown -R [USERNAME] imx-yocto-bsp
cd imx-yocto-bsp

When downloading the repo, you'll be prompted to configure your github account if you haven't already.

Install the i.MX BSP repo and download the Yocto Project Layers. I'll be using Sumo here:

repo init -u https://source.codeaurora.org/external/imx/imx-manifest -b imx-linux-sumo -m imx-4.14.98-2.2.0.xml 
repo sync

Download meta layers - Zeus

If using Yocto Project 3.0 (Zeus): you'll have to specify that in both the branch (-b flag) and manifest (-m flag) when setting up your repo:

repo init -u https://source.codeaurora.org/external/imx/imx-manifest -b imx-linux-zeus -m imx-5.4.24-2.1.0.xml
repo sync

Download MaaXBoard Source Code

Download the source code for MaaXBoard from GitHub:

cd sources 
git clone https://github.com/Avnet/meta-maaxboard.git
cd ..

If you look inside of the sources directory, you will now be able to see the meta layers. Inside each meta layer folder are recipe folders, and inside each of these folders are the recipe files (ending in.bb). This is what we'll be bitbaking in the build step.

If using eIQ layers:

cd meta-maaxboard
git checkout sumo-eiq
cd ../../

If using Zeus:

cd meta-maaxboard
git checkout zeus
cd ../../

Install patch

Each unique distro (fsl-imx-wayland in this case) has a hook, and each unique board (imx8mqevk if using MaaXBoard, imx8mmevk if using MaaXBoard Mini) has a "patch." You must specify both when initializing a new build. From the imx-yocto-bsp directory, make a new directory and then define the hook and patch:

mkdir imx8mqevk
DISTRO=fsl-imx-wayland MACHINE=imx8mqevk source fsl-setup-release.sh -b imx8mqevk

Read and accept the licensing agreement. You can then remove the patch folder:

cd ..
rm -rf imx8mqevk

If usingMaaXBoard Mini: the commands will be as follows:

mkdir imx8mmevk
DISTRO=fsl-imx-wayland MACHINE=imx8mmevk source fsl-setup-release.sh -b imx8mmevk
cd ..
rm -rf imx8mmevk

If building Zeus: update fsc-setup-release.sh to imx-setup-release.sh:

mkdir imx8mqevk
DISTRO=fsl-imx-wayland MACHINE=imx8mqevk source imx-setup-release.sh -b imx8mqevk

CUSTOMIZE

If building for machine learning, you will need to clone the meta-imx-machinelearning repo into sources:

cd sources
git clone -b sumo https://source.codeaurora.org/external/imx/meta-imx-machinelearning.git

You can find more packages that you could add either at https://source.codeaurora.org or the OpenEmbedded Layer Index (all officially registered Yocto packages are here). Note that many layers contain dependencies, and most haven't been tested on MaaXBoard yet.

To add new layers, simply clone the source and then edit the image recipe.

E.G. If you wanted to include Anaconda in your build, you would find the layer for it on OpenEmbedded's Layer Index. Clone it:

git clone git://git.yoctoproject.org/meta-anaconda.git

You will then need to edit the image recipe (lite-image.bb) in this folder: meta-maaxboard/images.

To get a list of available recipes in your current environment you can run commands like:

bitbake-layers show-recipes

Or:

bitbake-layers show-recipes | grep *anaconda*

Add each new recipe under after the CORE_IMAGE_EXTRA_INSTALL= line in lite-image.bb, E.G.

CORE_IMAGE_EXTRA_INSTALL += " \

packagegroup-anaconda-support \

The README for meta-anaconda shows that has some dependencies, so you will need to make sure you add those as well.

You can refer to the Yocto reference manual for more information about how to customize the image recipe.

You can also edit the distro features in meta-maaxboard/conf/distro/fsl-imx-wayland-lite.conf

CONFIGURE BUILD

Create the build directory inside imx-yocto-bsp and then run the oe-init-build-env environment setup script and add the default build configuration:

mkdir -p maaxboard/build 
source sources/poky/oe-init-build-env maaxboard/build

This operation will generate two conf files under the path maaxboard/build/conf if there is no existing conf file:

• local.conf
• bblayers.conf

You will need to modify both of the conf files according to your settings. Under the path imx-yocto-bsp/sources/meta-maaxboard/conf there are sample config files that you can use to replace your existing conf files.

• local.conf.sample
• bblayers.conf.sample

cd ~/imx-yocto-bsp/sources/meta-maaxboard/conf
mv local.conf.sample ~/imx-yocto-bsp/maaxboard/build/conf/local.conf
mv bblayers.conf.sample ~/imx-yocto-bsp/maaxboard/build/conf/bblayers.conf

If building for machine learning, copy the samples that include machine learning (only included in the sumo-eiq branch of the repo):

mv local.conf.eiq.sample ~/imx-yocto-bsp/maaxboard/build/conf/local.conf
mv bblayers.conf.eiq.sample ~/imx-yocto-bsp/maaxboard/build/conf/bblayers.conf

If building for Zeus, you'll need to edit local.conf and make sure MACHINE is set to the version of the MaaXBoard that you'll be using:

MaaXBoard: 'maaxboard-ddr4-2g-sdcard'

MaaXBoard Mini: 'maaxboard-mini-ddr4-2g-sdcard'

MaaXBoard Nano: 'maaxboard-nano-ddr4-1g-sdcard'

You should also uncomment this line:

MAAXBOARD_GIT_HOST_MIRROR = "git://git@github.com/Avnet"

BUILD YOCTO

From imx-yocto-bsp directory, set up the shell environment for builds and then run bitbake:

cd ../../..
source sources/poky/oe-init-build-env maaxboard/build
bitbake lite-image

If building sumo-eiq: the image should be built with Qt 5 support, because some OpenCV examples requires Qt 5 to be enabled in the image:

bitbake lite-image-qt5

NOTE: this could take a very long time depending on RAM. Possibly all day.

Build output

Once it's done building, the build output is located under path: imx-yocto-bsp/maaxboard/build/tmp/deploy/images/maaxboard-ddr4-2g-sdcard/.

Below is an example of build output:

BURN THE IMAGE TO SD CARD

The default version of MaaXBoard supports SD Cards. Avnet Manufacturing Services also provides eMMC versions for users to customize. It's also possible to burn the image via MaaXBoard's USB ports To burn the system image to the eMMC or using a USB Port, refer to MaaXBoard UUU Burning Guide.

Insert your SD card into your build machine and get the name. It should be something like /dev/sdb:

sudo fdisk -l /dev/sdb

Your SD card should show up here (here it's /dev/sdb1)

If you're like me and all of your SD cards are in use, it's best to reformat a card to use. You can use gparted to format your card:

sudo apt-get install gparted
gparted /dev/sdb

Then follow the steps in the GUI to unmount and then format your SD card as FAT32

Burn entire system image

Extract the bz2 and burn it:

NOTE: lite-image-maaxboard-ddr4-2g-sdcard-20200810075427.rootfs.sdcard is an example. Replace it with your actual image name:

bunzip2 -fls lite-image-maaxboard-ddr4-2g-sdcard-*.rootfs.sdcard.bz2 
sudo dd if=lite-image-maaxboard-ddr4-2g-sdcard-20200810075427.rootfs.sdcard of=/dev/sdb bs=10M conv=fsync

For Zeus: if burning a Zeus image, the file will be saved as a.wic file instead of a.sdcard file, so the commands to unzip and burn it would be something like:

bunzip2 -f lite-image-maaxboard-ddr4-2g-sdcard-20210315060135.rootfs.wic.bz2
sudo dd if=lite-image-maaxboard-ddr4-2g-sdcard-20210315060135.rootfs.wic of=/dev/sdb bs=256M conv=fsync

Conclusion

And that's it! You've successfully built, configured and burned Yocto for MaaXBoard. Remember to check out the resources listed at the beginning of this project if you want to go deeper, and stay tuned for the next project in this series: getting started on Machine Learning on Yocto on MaaXBoard!