ROS 2 has become an important platform for robot development. For embedded devices or commercial products, using Yocto to build ROS 2 systems offers high control, flexibility, and stability. This article will share the complete method for building ROS 2 images based on Yocto.

1. Preparing the Build Environment

1.1 System and Hardware Environment

To build a ROS 2 image based on Yocto, a high-performance Linux host is required as the build environment. The recommended configuration is as follows:

Operating System: Ubuntu 20.04 LTS or higher (Debian systems are also compatible)
CPU: 4 cores or more (8 cores recommended)
Memory: At least 16GB, 32GB is recommended for better build efficiency
Disk Space: At least 100GB of free space (including source code, cache, and build output)
Network: A stable high-speed network for pulling code and dependencies

Note: The Yocto build process is sensitive to IO performance, so it is recommended to use an SSD.

1.2 Installing Dependency Packages

Yocto builds require the installation of numerous tools and libraries. Ensure the following commands execute successfully:

sudo apt update
sudo apt install -y \
  gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential \
  chrpath socat cpio python3 python3-pip python3-pexpect xz-utils \
  debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa \
  libsdl1.2-dev xterm

Among them:

gawk, diffstat, etc. are BitBake dependency tools
chrpath is used to modify the rpath in binary files
python3-pexpect supports interactive build shells
libegl1-mesa and other graphics libraries are dependencies for the subsequent graphical interface

Ensure that the installation is completed correctly before executing the Yocto build commands.

2. Obtaining Source Code and Version Selection

2.1 Code Repositories

Poky: The reference distribution of Yocto, integrating BitBake and the core Layer

git clone -b kirkstone https://git.yoctoproject.org/poky.git

meta-ros: The official support Layer for ROS 2

git clone -b kirkstone https://github.com/ros/meta-ros.git

Ensure that the branch versions of both match to avoid build conflicts.

2.2 ROS 2 Versions

The meta-ros supports multiple ROS 2 distributions:

Foxy (LTS)
Galactic
Humble (LTS)

Select the appropriate version based on project requirements. It is recommended to use Humble, which supports the latest features and has a longer maintenance cycle.

3. Initializing the Yocto Build Environment

Enter the poky directory:

cd poky
source oe-init-build-env

This command will create and switch to the build/ directory, initializing the environment variables.

build/ directory structure is as follows:

conf/: Stores build configuration files
tmp/: Intermediate build data and output cache
downloads/: Source code cache directory

4. Adding Layers and Configuration Management

4.1 Configuring bblayers.conf

Edit build/conf/bblayers.conf to add the meta-ros2 Layer path:

BBLAYERS ?= " \
  ${TOPDIR}/../poky/meta \
  ${TOPDIR}/../poky/meta-poky \
  ${TOPDIR}/../meta-ros/meta-ros2 \
"

Ensure the paths are correct to avoid build failures.

4.2 Configuring local.conf

Edit build/conf/local.conf, key configuration example is as follows:

MACHINE ??= "qemux86-64"
DISTRO ?= "poky"
ROS_VERSION = "humble"
IMAGE_FEATURES += "ssh-server-openssh"
EXTRA_IMAGE_FEATURES = "debug-tweaks"
PACKAGE_CLASSES = "package_rpm"

MACHINE should be adjusted according to the target hardware
ROS_VERSION controls the version of meta-ros
IMAGE_FEATURES is used to enable debugging and service support

5. Detailed Explanation of Image Customization

The types of images provided by meta-ros are:

Image Name	Description
ros-image-core	Contains only the core packages of ROS 2
ros-image-world	Contains most ROS 2 packages and development tools

To add custom packages (e.g., custom drivers or applications):

Create a new Layer and write a Recipe
Add the package name to IMAGE_INSTALL_append:

IMAGE_INSTALL_append = " my-custom-package"

In this way, business code can be integrated into the system image.

6. Image Build Commands and Process

Execute:

bitbake ros-image-core

Build process:

Download source code and dependencies
Configure the build environment
Compile the kernel, root filesystem, and ROS 2 packages
Generate image files

The build time depends on hardware performance; the first build usually takes several hours, while incremental builds are faster.

7. Introduction to Build Products

After the build is complete, the products are located in:

build/tmp/deploy/images/<machine>/

Common files include:

.wic / .sdcard image files
.rootfs.tar.bz2 root filesystem package
.kernel kernel image
.manifest image manifest

These files can be used to write to storage media or for simulation.

8. Practical Suggestions for Flashing and Deployment

Use dd or Etcher tools to flash the .wic image to the SD card
Insert the flashed storage card into the target device to boot
Log in via serial port or SSH to verify that the ROS 2 nodes are running

9. Debugging and Troubleshooting Tips

For build failures, check tmp/work/<recipe>/temp/log.do_compile
Use bitbake -c cleansstate <recipe> to clean again
bitbake -c devshell <recipe> to enter the build environment for interactive debugging
Pay attention to dependency version conflicts and path errors

10. Experience Summary and Optimization Suggestions

Use sstate cache to speed up builds
Simplify IMAGE_FEATURES to reduce image size
Reasonably split Layers to enhance reusability
Combine with CI/CD for automated build and deployment

Author: Ling Zhaoge Focused on robotic systems and embedded platforms with Linux system builds. Feel free to follow for more practical content.

A Complete Guide to Building ROS 2 Systems Based on Yocto