Building Yocto Images for Robotics Edge Platform

Building Yocto Images for Robotics Edge Platform#

1. Host Setup#

To achieve the expected behavior of the Yocto Project on a Linux host machine, install the packages and utilities described below. An important consideration is the hard disk space required in the host machine. For example, when building on a machine running Ubuntu, the minimum hard disk space required is about 120 GB. It is recommended that at least 250 GB is provided, which is enough to compile all backends together. The recommended minimum Ubuntu version is 22.04 or later.

1.1 Host Packages#

To build a Yocto Project, a few packages must be installed. These packages are documented under the Yocto Project. Go to Yocto Project Quick Build and check for the packages that must be installed for your build machine.

The essential Yocto Project host packages are:

sudo apt-get install build-essential chrpath cpio debianutils diffstat file gawk gcc git iputils-ping libacl1 locales python3 python3-git python3-jinja2 python3-pexpect python3-pip python3-subunit socat texinfo unzip wget xz-utils zstd

You must also ensure that you have the en_US.UTF-8 locale enabled:

locale --all-locales | grep en_US.utf8

If this is not the case, you can reconfigure the locales package to add it (requires an interactive shell):

sudo dpkg-reconfigure locales

1.2 Install the `repo` utility#

Repo is a tool based on Git that makes it easier to manage projects containing multiple repositories, provided they do not need to be on the same server. Repo complements very well the layered nature of the Yocto Project, making it easier for users to add their own layers to the Board Support Package (BSP).

mkdir ~/bin
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo
PATH=${PATH}:~/bin

2. Robotics Edge Platform Yocto Setup#

First, make sure that Git is set up properly using the commands below:

git config --global user.name "Your Name"
git config --global user.email "Your Email"
git config --list

The Robotics Edge Platform Yocto Project Release directory contains a sources directory. This directory contains the recipes used to build one or more build directories, and a set of scripts used to set up the environment.

The recipes used to build the project come from both the community and Robotics Edge Platform. The Yocto Project layers are downloaded to the sources directory. In this directory, the recipes that are used to build the project are set up.

The following example shows how to download the Robotics Edge Platform recipe layers. For this example, a directory called robotics-edge is created for the project. Any other name can also be used instead of this name.

mkdir robotics-edge
cd robotics-edge
repo init -u https://github.com/nxp-imx/imx-manifest.git -b robotics-edge-walnascar -m robotics-edge-1.0.0.xml
repo sync

When this process is completed, the source code is checked out into the directory robotics-edge/sources. You can perform repo synchronization with the command repo sync periodically to update to the latest code.

If errors occur during repository initialization, try deleting the .repo directory and running the repo initialization command again.

The repo init is configured for the latest patches in the line.

3. Image Building#

3.1 Setup the Build Environment#

Robotics Edge Platform provides the script robotics-edge-setup.sh, which simplifies the setup for i.MX boards. To use the script, the name of the specific machine to be built for and the desired distro must be specified. The script sets up a directory and the configuration files for the specified machine and distro.

Robotics Edge Platform supports the following NXP hardware platforms:

imx8mp-lpddr4-evk
imx8mp-lpddr4-frdm
imx95-19x19-lpddr5-evk

Each build folder must be configured in such a way that it uses only one distro. Each time the variable DISTRO_FEATURES is changed, a clean build folder is needed. Distro configurations are saved in the local.conf file in the DISTRO setting and are displayed when the bitbake command is run.

DISTRO defaults to robotics-edge.

Note: The tmp folder is distro-specific but not machine-specific. All machines can be built in the same tmp folder as long as the distro is the same. It is common to use a different build folder for each distro required. It is possible to switch the distro of a build folder, but the tmp folder must be deleted before rebuilding. Be warned that this will delete the output of the previous build, which is contained in tmp/deploy.

The syntax for the robotics-edge-setup.sh script is shown below:

[DISTRO=<distro name>] [MACHINE=<machine name>] source robotics-edge-setup.sh -b <build dir> -r <ROS2_DISTRO>

Parameters:

DISTRO=<distro name> - The distro that configures the build environment and is stored in: meta-robotics-edge/conf/distro
MACHINE=<machine name> - The machine name that points to the configuration file in conf/machine in meta-imx
-b <build dir> - Specifies the name of the build directory created by the script
-r [ROS2_DISTRO] - Optional parameter that specifies the ROS 2 distribution to use. If not specified, ROS2_DISTRO defaults to jazzy

When the script is run, it prompts the user to accept the End User License Agreement (EULA). Once the EULA is accepted, the acceptance is stored in the local.conf file within each build folder. The EULA acceptance query is no longer displayed for that build folder.

After the script runs, it creates a working directory that was specified using the -b option. A conf folder is created, which contains the bblayers.conf and local.conf files.

The <build dir>/conf/bblayers.conf file contains all the metalayers used in the Robotics Edge Yocto Project release. The local.conf file contains the machine and distro specifications:

MACHINE ??= 'imx8mp-lpddr4-evk'
DISTRO ?= 'robotics-edge'
ACCEPT_FSL_EULA = "1"

The MACHINE configuration can be changed by editing this file, if necessary.

ACCEPT_FSL_EULA in the local.conf file indicates that you have accepted the conditions of the EULA.

Use an existing build folder:

If you want to build in an existing build folder:

cd robotics-edge
source setup-environment build

3.2 Build an Image#

The Yocto Project build uses the bitbake command. For example, bitbake <component> builds the named component. Each component build has multiple tasks, such as fetching, configuration, compilation, packaging, and deploying to the target rootfs. The bitbake image build gathers all the components required by the image and builds in the order of the dependency per task. The first build is the toolchain along with the tools required for the components to build.

The following command is an example of how to build an image:

bitbake <IMAGE-RECIPE>

Image Recipes:

Image Name	Description
robotics-edge-image-core	Image with i.MX core and ROS core
robotics-edge-image-multimedia	Image with i.MX multimedia and ROS base
robotics-edge-image-full	Image with i.MX multimedia, machine learning, Qt and ROS full

Example:

bitbake robotics-edge-image-full

3.3 Build Output#

The compiled image can be found in the deploy directory:

ls tmp/deploy/images/<MACHINE>/

The main image file will be named according to the image recipe you built, such as:

robotics-edge-image-full-jazzy-imx8mpevk.rootfs.wic.zst

4. Board-Specific Build Instructions#

This section provides complete build instructions for each supported board.

4.1 FRDM-IMX8MPLUS#

Step 1: Initialize the Repository

mkdir robotics-edge
cd robotics-edge
repo init -u https://github.com/nxp-imx/imx-manifest.git -b ros2-walnascar -m robotics-edge.xml
repo sync

Step 2: Setup Build Environment

DISTRO=robotics-edge MACHINE=imx8mp-lpddr4-frdm source robotics-edge-setup.sh -b build -r jazzy

Step 3: Build Image

bitbake robotics-edge-image-full

Step 4: Build Output

The compiled image can be found in:

ls tmp/deploy/images/imx8mp-lpddr4-frdm/

Main files:

robotics-edge-image-full-jazzy-imx8mp-lpddr4-frdm.rootfs.wic.zst - Root filesystem image
imx-boot-imx8mp-lpddr4-frdm-sd.bin-flash_evk - Bootloader

4.2 i.MX8M PLUS EVK#

Step 1: Initialize the Repository

mkdir robotics-edge
cd robotics-edge
repo init -u https://github.com/nxp-imx/imx-manifest.git -b ros2-walnascar -m robotics-edge.xml
repo sync

Step 2: Setup Build Environment

DISTRO=robotics-edge MACHINE=imx8mp-lpddr4-evk source robotics-edge-setup.sh -b build -r jazzy

Step 3: Build Image

bitbake robotics-edge-image-full

Step 4: Build Output

The compiled image can be found in:

ls tmp/deploy/images/imx8mp-lpddr4-evk/

Main files:

robotics-edge-image-full-jazzy-imx8mpevk.rootfs.wic.zst - Root filesystem image
imx-boot-imx8mp-lpddr4-evk-sd.bin-flash_evk - Bootloader

4.3 i.MX95 EVK#

Step 1: Initialize the Repository

mkdir robotics-edge
cd robotics-edge
repo init -u https://github.com/nxp-imx/imx-manifest.git -b ros2-walnascar -m robotics-edge.xml
repo sync

Step 2: Setup Build Environment

DISTRO=robotics-edge MACHINE=imx95-19x19-lpddr5-evk source robotics-edge-setup.sh -b build -r jazzy

Step 3: Build Image

bitbake robotics-edge-image-full

Step 4: Build Output

The compiled image can be found in:

ls tmp/deploy/images/imx95-19x19-lpddr5-evk/

Main files:

robotics-edge-image-full-jazzy-imx95evk.rootfs.wic.zst - Root filesystem image
imx-boot-imx95-19x19-lpddr5-evk-sd.bin-flash_a55 - Bootloader

5. Advanced Build Options#

5.1 Building Specific Images#

You can build different image variants depending on your needs:

Core Image (Minimal):

bitbake robotics-edge-image-core

Multimedia Image:

bitbake robotics-edge-image-multimedia

Full Image (with ML and Qt):

bitbake robotics-edge-image-full

5.2 Parallel Build Configuration#

To speed up builds, you can configure parallel compilation in conf/local.conf:

# Number of parallel make jobs (typically number of CPU cores)
PARALLEL_MAKE = "-j 8"

# Number of parallel BitBake tasks
BB_NUMBER_THREADS = "8"

5.3 Shared State Cache#

To speed up subsequent builds, configure a shared state cache:

# In conf/local.conf
SSTATE_DIR = "/path/to/shared/sstate-cache"

5.4 Download Directory#

Configure a persistent download directory to avoid re-downloading sources:

# In conf/local.conf
DL_DIR = "/path/to/shared/downloads"

5.5 Building Individual Packages#

You can build individual ROS 2 packages or components:

# Build a specific ROS 2 package
bitbake ros-jazzy-<package-name>

# Example: Build rclcpp
bitbake ros-jazzy-rclcpp

# Build a specific component
bitbake <component-name>

5.6 Cleaning Build Artifacts#

Clean a specific recipe:

bitbake -c clean <recipe-name>

Clean all build artifacts for a recipe:

bitbake -c cleanall <recipe-name>

Clean shared state for a recipe:

bitbake -c cleansstate <recipe-name>

6. Troubleshooting#

6.1 Build Errors#

If you encounter build errors:

Clean a specific recipe:

bitbake -c cleanall <recipe-name>

Clean all and rebuild:

rm -rf tmp
bitbake robotics-edge-image-full

Check build logs:

# Logs are located in:
tmp/work/<machine>/<recipe>/<version>/temp/log.do_<task>

# Example:
tmp/work/imx8mp_lpddr4_evk-poky-linux/robotics-edge-image-full/1.0/temp/log.do_rootfs

View detailed error information:

# Use bitbake with verbose output
bitbake -v robotics-edge-image-full

# Or with debug output
bitbake -D robotics-edge-image-full

6.2 Repository Sync Issues#

If repo sync fails:

rm -rf .repo
repo init -u https://github.com/nxp-imx/imx-manifest.git -b ros2-walnascar -m robotics-edge.xml
repo sync

Force sync all projects:

repo sync --force-sync

Sync with network retry:

repo sync --network-only --jobs=4

6.3 Disk Space Issues#

Check disk space:

df -h

Clean up build artifacts:

# Remove temporary build files
rm -rf tmp

# Clean up old downloads (be careful!)
# This will remove all downloaded sources
rm -rf downloads/*

Clean up shared state cache:

# Remove old sstate files
./scripts/sstate-cache-management.sh --remove-duplicated --cache-dir=sstate-cache

Find large directories:

du -h --max-depth=1 | sort -hr | head -20

6.4 Common Error Messages#

Error: “No space left on device”

Solution: Free up disk space or use a larger disk
Check: df -h to see disk usage

Error: “Fetcher failure”

Solution: Check internet connection
Try: bitbake -c cleanall <recipe> and rebuild
Check: Proxy settings if behind a firewall

Error: “do_compile failed”

Solution: Check tmp/work/.../temp/log.do_compile for details
Try: bitbake -c cleanall <recipe> and rebuild

Error: “EULA not accepted”

Solution: Set ACCEPT_FSL_EULA = "1" in conf/local.conf

Error: “Nothing PROVIDES”

Solution: Check recipe name spelling
Verify: Recipe exists in the layers
Try: bitbake-layers show-recipes | grep <recipe-name>

Error: “Task failed with exit code”

Solution: Check the specific task log in tmp/work/.../temp/
Try: Clean and rebuild the specific recipe

6.5 Network and Download Issues#

Configure proxy settings:

# In conf/local.conf
HTTP_PROXY = "http://proxy.example.com:8080"
HTTPS_PROXY = "http://proxy.example.com:8080"
FTP_PROXY = "http://proxy.example.com:8080"
NO_PROXY = "localhost,127.0.0.1"

7. Useful BitBake Commands#

List all recipes:

bitbake-layers show-recipes

Search for a recipe:

bitbake-layers show-recipes | grep <recipe-name>

Show recipe dependencies:

bitbake -g <recipe-name>

Show recipe information:

bitbake -e <recipe-name> | less

List all layers:

bitbake-layers show-layers

Show what provides a package:

bitbake -s | grep <package-name>

Dry run (show what would be built):

bitbake -n <recipe-name>

Building Yocto Images for Robotics Edge Platform

Contents

Building Yocto Images for Robotics Edge Platform#

1. Host Setup#

1.1 Host Packages#

1.2 Install the `repo` utility#

2. Robotics Edge Platform Yocto Setup#

3. Image Building#

3.1 Setup the Build Environment#

3.2 Build an Image#

3.3 Build Output#

4. Board-Specific Build Instructions#

4.1 FRDM-IMX8MPLUS#

4.2 i.MX8M PLUS EVK#

4.3 i.MX95 EVK#

5. Advanced Build Options#

5.1 Building Specific Images#

5.2 Parallel Build Configuration#

5.3 Shared State Cache#

5.4 Download Directory#

5.5 Building Individual Packages#

5.6 Cleaning Build Artifacts#

6. Troubleshooting#

6.1 Build Errors#

6.2 Repository Sync Issues#

6.3 Disk Space Issues#

6.4 Common Error Messages#

6.5 Network and Download Issues#

7. Useful BitBake Commands#

8. Additional Resources#

Building Yocto Images for Robotics Edge Platform

Contents

Building Yocto Images for Robotics Edge Platform#

1. Host Setup#

1.1 Host Packages#

1.2 Install the repo utility#

2. Robotics Edge Platform Yocto Setup#

3. Image Building#

3.1 Setup the Build Environment#

3.2 Build an Image#

3.3 Build Output#

4. Board-Specific Build Instructions#

4.1 FRDM-IMX8MPLUS#

4.2 i.MX8M PLUS EVK#

4.3 i.MX95 EVK#

5. Advanced Build Options#

5.1 Building Specific Images#

5.2 Parallel Build Configuration#

5.3 Shared State Cache#

5.4 Download Directory#

5.5 Building Individual Packages#

5.6 Cleaning Build Artifacts#

6. Troubleshooting#

6.1 Build Errors#

6.2 Repository Sync Issues#

6.3 Disk Space Issues#

6.4 Common Error Messages#

6.5 Network and Download Issues#

7. Useful BitBake Commands#

8. Additional Resources#

1.2 Install the `repo` utility#