hydro/Installation/OpenEmbedded

General Information

The OpenEmbedded build framework [1] provides a general cross-compilation environment. This environment allows developers to set up a tool chain for their application and to create a complete Linux distribution for their embedded system. It supports various hardware architectures and embedded boards through board support packages.

The OpenEmbedded framework consists of the Bitbake build tool [9], OpenEmbedded-Core and various board and application-specific layers. Bitbake is the build tool to create cross-compiler tool chains and the Linux images. Bitbake recipes instruct Bitbake to set up dependent packages, download sources, configure, compile and package the resulting files. Bitbake recipes are collected and organized in layers. The base layer OpenEmbedded-Core provides recipes and associated files that are commonly used among many different OpenEmbedded-derived systems. Further layers provide support for different boards and several applications. The meta-ros layer [2] provides recipes for common ROS packages and general support to specify cross-compiler tool chains for your ROS packages.

The Yocto open-source collaboration project [3], backed by the Linux Foundation, develops and maintains OpenEmbedded-Core and several other layers. They assemble the framework and layers to a Yocto project release, called Poky.

This page provides simple instructions to set up the OpenEmbedded framework with support for ROS applications. Furthermore, it shows how to invoke the tool chain, create a Linux image with ROS and run the image on a virtual machine. In the end, it provides a few hints how to extend the cross-compile environment with recipes for the own ROS packages.

The page is kept minimal and self-contained. However, it does not cover the setup of the OpenEmbedded framework in all its facets; for this, you can examine the OpenEmbedded documentation and manuals [4].

Setting up the Cross-Compile Environment

First, we install all required packages for the OpenEmbedded framework. For Ubuntu distributions, you must install these packages with:

sudo apt-get install build-essential chrpath diffstat gawk git-core libsdl1.2-dev texinfo unzip wget xterm

For the other Linux distributions, refer to sections "The Linux Distribution" and "The Packages" in the Yocto Project Quick Start [5]. This section describes how to set up the distro-less OpenEmbedded-Core system. For the Yocto project release Poky, follow the instructions in section "Building an Image" of the Yocto Project Quick Start and continue with adding the layers for ROS.

The setup requires three simple steps: downloading the needed source code repositories, initializing the build environment, and tweaking a few local configurations.

First, clone the Bitbake repository, the openembedded-core repository, the meta-openembedded repository and the meta-ros repository into a fresh directory, e.g. the user "me" would download it to /home/me/devel/. To do this, execute

mkdir ~/devel && cd ~/devel
git clone git://git.openembedded.org/bitbake/
git clone git://git.openembedded.org/openembedded-core
git clone git://git.openembedded.org/meta-openembedded
git clone https://github.com/bmwcarit/meta-ros.git

These commands download the latest versions of the repositories.

The meta-ros layer provides the recipes for ROS hydro, indigo and kinetic:

For the hydro distribution, you can use the deprecated version 0.2 of the meta-ros repository. Simply checkout the tag v0.2 with:

cd meta-ros && git checkout v0.2 && cd ..

At its release time in May 2015, version 0.2 worked with poky fido and the Openembedded-Core master branch. If you use version 0.2 with recent releases of poky (e.g., jethro or krogoth in 2016 and later) and the evolving Openembedded-Core master branch, you must expect to invest some effort to backport commits from the current head of meta-ros.
For the indigo distribution, you can use the current head of the meta-ros repository. This is currently the best supported distribution in meta-ros.
For the kinetic distribution, you can use the experimental local branch at https://github.com/bulwahn/meta-ros/tree/kinetic-experimental-v3-alpha1. But remember that this is an experimental local branch: First, do not expect that this branch has been tested with many different build configurations, so possibly, your build configuration could cause build failure we are unaware of. Second, this branch is work in progress, and hence, the commits of this branch will be rebased and modified, and the git history will change in a non-monotonic way in the future. Nevertheless, try this branch and report issues if you encounter them.

For the exceptional case that the chosen version of the meta-ros repository causes problems, you should check the meta-ros issue tracker for reported problems.

Then, to initialize the build environment, execute

ln -s ~/devel/bitbake ~/devel/openembedded-core/bitbake
source openembedded-core/oe-init-build-env

The oe-init-build-env script creates an initial build directory with a default local.conf configuration file. Now, adjust the settings in the local.conf for your use case and your machine:

Set the MACHINE setting to the machine architecture that you want to target. By default, it is set to qemux86 to target to a x86 qemu virtual machine.
Important are the parallelism options. Even with the right settings for a large multi-core machine, building an image takes over an hour. Without the parallelism options, the machine only uses one core and does one task at a time and hence, building an image probably takes a whole day or more. So, you better change the parallelism options if you want to see results today. With an eight-core machine and SSD harddisk, we suggest to use BB_NUMBER_THREADS ?= "12" and PARALLEL_MAKE ?= "-j 8".

Now, the OpenEmbedded-Core build environment is set up. Next, add the required layers, meta-oe and meta-ros, to the build environment by modifying the bblayers.conf to set the variable BBLAYERS with these lines:

BBLAYERS ?= "\
  /home/me/devel/openembedded-core/meta \
  /home/me/devel/meta-openembedded/meta-oe \
  /home/me/devel/meta-ros \
"

Note that you must provide absolute paths and adjusts the paths in the example to the path you have chosen to download the repositories.

Invoking the Toolchain

After the cross-compile environment is set up, you can invoke the tool chain in the build directory with:

bitbake <recipe-name>

For example, 'bitbake roslaunch' cross-compiles and packages everything to execute roslaunch. Note that invoking the command for the first time downloads and cross-compiles all required software packages, so this can take a couple of hours depending on your internet connection and machine's performance. The complete list of recipes can be found by simply scanning through the recipes-ros directory of the meta-ros layer.

Creating a Linux Image with ROS

To create a Linux image to run roscore, you simply execute

bitbake core-image-ros-roscore

Running the Image

You start this system in the qemu virtual machine with

runqemu <MACHINE> core-image-ros-roscore

The <MACHINE> is the identifier that is set in the local.conf, e.g., qemux86. On the Linux virtual machine system, you can log in as root with the empty password. Now, you ensure that the own host's name in resolved by adding

127.0.0.1    <HOSTNAME>.localdomain        <HOSTNAME>

to the /etc/hosts file, and set up the environment with

export ROS_ROOT=/opt/ros/<ros-distro>
export PATH=$PATH:/opt/ros/<ros-distro>/bin
export LD_LIBRARY_PATH=/opt/ros/<ros-distro>/lib
export PYTHONPATH=/opt/ros/<ros-distro>/lib/python2.7/site-packages
export ROS_MASTER_URI=http://localhost:11311
export CMAKE_PREFIX_PATH=/opt/ros/<ros-distro>
touch /opt/ros/<ros-distro>/.catkin

Note that <ros-distro> must be replaced with hydro or indigo, depending which ROS distribution you have chosen.

Finally, you can start roscore with

roscore

Extending the Environment with own ROS packages

The meta-ros layer provides the recipes for most common ROS packages. For your own packages and images, you can add further recipes that build on top of the existing ones. To learn how to write Bitbake recipes for ROS, we refer to the OpenEmbedded Manual, Victor Mayoral's tutorial [6] and the guidelines for ROS recipes in the meta-ros wiki [7]. If you write recipes that are of general interest, you are welcome to provide them back to the meta-ros repository.

Obtaining Support for an OpenEmbedded Installation

If you need support for an OpenEmbedded installation, you have these options:

Star the meta-ros github project [2]. This makes the meta-ros maintainers aware that you are using the meta-ros layer. The issue tracker on github is open to everyone and can be used for troubleshooting, bug reports and discussions.
Join the OpenEmbedded category on discourse.ros.org [8] and introduce yourself and your interest there. The category informs everyone about current issues, progress, new users and collaborators.
Contribute the recipes that you need for your application and are of general interest to the github repository. In discussion with current developers, the recipes are often improved.
Discuss on the mailing list what you wish to see contributed in the future.

References

[1] http://www.openembedded.org/wiki/Main_Page

[2] https://github.com/bmwcarit/meta-ros/

[3] https://www.yoctoproject.org/

[4] http://www.openembedded.org/wiki/Documentation

[5] https://www.yoctoproject.org/docs/current/yocto-project-qs/yocto-project-qs.html

[6] https://github.com/vmayoral/diving-meta-ros

[7] https://github.com/bmwcarit/meta-ros/wiki/Guidelines-for-ROS-recipes

[8] http://discourse.ros.org/c/openembedded

[9] https://www.yoctoproject.org/tools-resources/projects/bitbake