ROS

meta-ros OpenEmbedded layers are designed to add support for the Robot Operating System (ROS) for embedded Linux systems based on Yocto.

These instructions are for building ROS 2 Jazzy using Scarthgap (Yocto 5.0), ROS 2 Humble and ROS 1 Noetic using Dunfell (Yocto 3.1) or Kirkstone (Yocto 4.0) on IoT Yocto. An overview of OpenEmbedded/Yocto can be found in the Yocto Project Overview and Concepts Manual. Additional information on meta-ros can be found in Superflore OE Recipe Generation Scheme.

Important

Users can only choose RO2 or ROS1 to install, we do not support both versions existing in the system at the same time

Add ROS to Image

In conf/local.conf , change MACHINE to your desired platform and comment out multilib-relevant configuration:

# change MACHINE to your desired platform, default is i300a-pumpkin
MACHINE ??= "genio-700-evk"

# Define multilib target
#require conf/multilib.conf
#MULTILIBS = "multilib:lib32"
#DEFAULTTUNE:virtclass-multilib-lib32 = "armv7athf-neon"

# Video Encode on i300a is only supported in the 32-bits binaries
#IMAGE_INSTALL:remove:i300a = "mtk-vpud"
#IMAGE_INSTALL:append:i300a = "lib32-mtk-vpud"

Build ROS on Kirkstone

Please run following command to download the meta-ros layer:

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

If not already kirkstone Modify the compatible series in configuration file to kirkstone

vim src/meta-ros/meta-ros-common/conf/ros-distro/ros-distro.conf

# change ROS_OE_RELEASE_SERIES to kirkstone, default is honister
ROS_OE_RELEASE_SERIES = "kirkstone"

Add ROS2 Layer

  1. Add meta-ros layers to conf/bblayers.conf

<absolute_path_to_rity-kirkstone>/src/poky/../meta-ros/meta-ros2 \
<absolute_path_to_rity-kirkstone>/src/poky/../meta-ros/meta-ros-common \
<absolute_path_to_rity-kirkstone>/src/poky/../meta-ros/meta-ros2-humble \

  1. Add this to the bottom of conf/local.conf

ROS_DISTRO = "humble"
EXTRA_IMAGE_FEATURES ?= "ros-implicit-workspace"
IMAGE_INSTALL:append = " ros-core "

# Add subsequent desired ROS2 packages as below:
IMAGE_INSTALL:append = " demo-nodes-cpp "

Note

Currently we only support ROS2 on Kirkstone.

Important

You might get build failed log for libcamera similar to the following content

ERROR: Multiple versions of libcamera are due to be built
($PROJ_DIR/src/poky/../meta-ros/meta-ros2-humble/generated-recipes/libcamera/libcamera_0.1.0-1.bb
$PROJ_DIR/src/poky/../meta-openembedded/meta-multimedia/recipes-multimedia/libcamera/libcamera.bb). Only one version of a given PN should be built in any given build.
You likely need to set PREFERRED_VERSION_libcamera to select the correct version or don't depend on multiple versions.

We are getting this error because both the recipes, libcamera from OpenEmbedded as well as the one provided by ROS2 share the same name and version. The best way forward for now is to change the name of this ROS2 recipe from libcamera to ros-libcamera. The below steps work:

i. Navigate to your project directory
    # cd $PROJ_DIR/src/meta-ros/meta-ros2-humble/generated-recipes

ii. Rename libcamera directory to ros-libcamera, also the recipe
    # mv libcamera ros-libcamera
    # cd ros-libcamera
    # mv libcamera_0.1.0-1.bb ros-libcamera.bb

iii. Edit the recipe (`ros-libcamera.bb`) and rename ROS_CN and ROS_BPN from libcamera to ros-libcamera:
    # ROS_CN = "ros-libcamera"
    # ROS_BPN = "ros-libcamera"

iv. Navigate to $PROJ_DIR/src/meta-ros/meta-ros2-humble/recipes-bbappends/
    # mv libcamera ros-libcamera
    # cd ros-libcamera
    # mv libcamera_0.1.0-1.bbappend ros-libcamera.bbappend

v. ROS2 package camera-ros (generated-recipes/camera-ros/camera-ros*.bb) depends on ros2 package
libcamera. Rename ``libcamera`` to ``ros-libcamera``.

If you want to add libcamera ROS2 package to the image, simply add IMAGE_INSTALL:append = " ros-libcamera " in conf/local.conf.

  1. Build image. Please refer to Build Image section for details.

Build ROS on Scarthgap

Please run following command to download the meta-ros layer:

git clone https://github.com/ros/meta-ros.git -b scarthgap $PROJ_ROOT/src/meta-ros

The compatible series in the configuration file is already scarthgap on this branch — no edit needed. Just verify:

grep ROS_OE_RELEASE_SERIES src/meta-ros/meta-ros-common/conf/ros-distro/ros-distro.conf

# expected output
ROS_OE_RELEASE_SERIES = "scarthgap"

Note

Do not use the kirkstone branch of meta-ros on Scarthgap. Every meta-ros sub-layer sets LAYERSERIES_COMPAT_* to its own series, so a kirkstone meta-ros on a Scarthgap poky is rejected by bitbake at parse time.

Add ROS2 Layer

  1. Add meta-ros layers to conf/bblayers.conf

<absolute_path_to_rity-scarthgap>/src/poky/../meta-ros/meta-ros-common \
<absolute_path_to_rity-scarthgap>/src/poky/../meta-ros/meta-ros2 \
<absolute_path_to_rity-scarthgap>/src/poky/../meta-ros/meta-ros2-jazzy \

The layer order does not matter (priorities are set inside each layer: ros-common=10, ros2=11, ros2-jazzy=12), but all three are required — meta-ros2-jazzy alone will fail its LAYERDEPENDS check.

meta-ros also depends on layers you should already have in a Rity build: meta-oe, meta-python (from meta-openembedded) and poky/meta.

  1. Add this to the bottom of conf/local.conf

ROS_DISTRO = "jazzy"
IMAGE_INSTALL:append = " ros-core"

# Add subsequent desired ROS2 packages as below:
IMAGE_INSTALL:append = " demo-nodes-cpp "

Important

Do not add EXTRA_IMAGE_FEATURES ?= "ros-implicit-workspace" on Scarthgap. ros-implicit-workspace is only declared valid by ros_image.bbclass, which the Rity images do not inherit. Bitbake will reject every rity-*-image with “‘ros-implicit-workspace’ in IMAGE_FEATURES is not a valid image feature”.

Source the ROS environment explicitly instead (see step 4). If you do want the feature accepted, add IMAGE_CLASSES += "ros_image" and ROS_IMAGE_BASENAME_APPEND = "" to prevent -jazzy being appended to every image name.

  1. Build image. Please refer to Build Image section for details.

  2. On the target, source the ROS environment before use — everything is installed under /opt/ros/${ROS_DISTRO}:

$ source /opt/ros/jazzy/setup.sh
$ ros2 run demo_nodes_cpp talker

To get it on every login, drop a one-liner into /etc/profile.d:

$ echo '. /opt/ros/jazzy/setup.sh' > /etc/profile.d/ros.sh

Note

On Scarthgap the supported ROS 2 distro is Jazzy Jalisco (ROS_DISTRO = "jazzy", EOL Apr 2028). Humble is still buildable from the scarthgap branch (meta-ros2-humble, EOL May 2027) if you must stay ABI-compatible with an existing Humble deployment; replace meta-ros2-jazzy with meta-ros2-humble and set ROS_DISTRO = "humble". Kilted (EOL Dec 2026) and Lyrical (EOL Apr 2028) sub-layers also exist on the branch.

Build ROS on Dunfell

Please run following command to download the meta-ros layer:

git clone https://github.com/ros/meta-ros.git -b dunfell $PROJ_ROOT/src/meta-ros

Add ROS2 Layer

  1. Add meta-ros layers to conf/bblayers.conf

<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros2 \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros-common \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros2-galactic \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros-backports-gatesgarth \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros-backports-hardknott \

  1. Add this to the bottom of conf/local.conf

ROS_DISTRO = "galactic"
EXTRA_IMAGE_FEATURES ?= "ros-implicit-workspace"
IMAGE_INSTALL:append = " ros-core "

# Add subsequent desired ROS2 packages as below:
IMAGE_INSTALL:append = " demo-nodes-cpp "

  1. Build image. Please refer to Build Image section for details.

Add ROS1 Layer

  1. Add meta-ros layers to conf/bblayers.conf

<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros1 \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros-common \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros1-noetic \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros-backports-gatesgarth \
<absolute_path_to_rity-dunfell>/src/poky/../meta-ros/meta-ros-backports-hardknott \

  1. Add this to the bottom of conf/local.conf

ROS_DISTRO = "noetic"
EXTRA_IMAGE_FEATURES ?= "ros-implicit-workspace"
IMAGE_INSTALL:append = " ros-core "

  1. Comment out the blacklisted roslisp and genlisp to avoid the building rejection

vim src/meta-ros/meta-ros1-noetic/conf/ros-distro/include/noetic/ros-distro-recipe-blacklist.inc

# Comment out the following lines
#PNBLACKLIST[roslisp] ?= "${@bb.utils.contains('ROS_WORLD_SKIP_GROUPS', 'lisp', 'depends on sbcl for which there is no OE recipe', '', d)}"
#PNBLACKLIST[genlisp] ?= "${@bb.utils.contains('ROS_WORLD_SKIP_GROUPS', 'lisp', 'depends on sbcl for which there is no OE recipe', '', d)}"

  1. Build image. Please refer to Build Image section for details.

Build Image

Please refer to Build from Source Code to build the demo images of each board.

Note

Various WARNING-s will be issued by Bitbake when building these images. They can be ignored. After a successful build of an image, it can be found under TMPDIR/deploy/images/MACHINE.

Image Sanity Testing

ROS 2 Sanity Test

Note

Without a network connection, there’s no output from ROS2 topic echo /chatter.

$ source /etc/profile.d/ros/setup.sh

$ ros2 topic list
/parameter_events
/rosout

$ (sleep 5; ros2 topic pub /chatter std_msgs/String "data: Hello world") &

$ ros2 topic echo /chatter
publisher: beginning loop
publishing #1: std_msgs.msg.String(data='Hello world')

data: Hello world

publishing #2: std_msgs.msg.String(data='Hello world')

data: Hello world

ROS 1 Sanity Test

For now, only the barest minimum sanity testing is done on the images.

$ source /opt/ros/noetic/setup.sh

$ roscore &
...
started core service [/rosout]

$ rosnode list
/rosout

$ rosnode info /rosout
Node [/rosout]
Publications:
 * /rosout_agg [rosgraph_msgs/Log]

Subscriptions:
 * /rosout [unknown type]

Services:
 * /rosout/get_loggers
 * /rosout/set_logger_level


contacting node http://genio-700-evk:40943/ ...
Pid: 967