Repository files navigation

This README file is a step-by-step tutorial on how to add and use ROS on a Yocto image for Raspberry Pi 4. In the process of research, I have found that the "official"meta-ros layer is depricated, full of bugs, and most importantly has no support for the latest LTS version of The Yocto Project: Kirkstone---at the time of writing this (2/2024). So, here I will document the entire process of building it: starting from cloningpoky andopenembedded to runningroscore on the Pi.

As stated earlier, the target hardware is a Raspberry Pi 4 8GB Rev 1.5C with the following pin configuration. Knowing the pin configuration will be important later on in order to communicate with the Pi later on via a serial terminal likegtkterm using a USB-to-TTL device as shown below.

I have built this Yocto image on a PC with the specifications stated below. I made sure to record the time it took me to build the image for reference. Bare in mind that performance may differ duo to multiple reasons such as: temperature---a laptop is more likely to throttle than a PC; disk speed---I built it entirely on an SSD and it took over 2 hours, I can hardly imagine how long it would take to build an image on an HDD; and lastly the performance of your machine---I am running a native/real Ubuntu 22.04 machine, not a VM.

With all the exposition out of the way, let us begin.

1. Start things off with by updating and upgrading packages.

   sudo apt update && upgrade -y

2. The Yocto Project documentation recommends installing the following packages.

   sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev python3-subunit mesa-common-dev zstd liblz4-tool file locales libacl1

1. Now, in the project folder, clone the reference distropoky.

   https://github.com/yoctoproject/poky.git

2. Next, in the same project folder (besidepoky), clone theopenembedded layer repository.

   https://github.com/openembedded/meta-openembedded.git

3. Since the target hardware is a Raspberry Pi board, it is time to clone the Board Support Package (BSP) made for Raspberry Pi---meta-raspberrypi

   https://github.com/agherzan/meta-raspberrypi.git

4. Finally, it is time to clone the star of the show:meta-ros. As stated earlier, the "official"---as in the one you can find in Openembedded Layer Index---is deprecated and full of bugs; so I will not use it. Luckily,RethinkRobotics-opensource forked a repository that was forked from a fork of the originalmeta-ros that is up-to-date and fully functional. Huge shoutout to them. For now, I will simply clone their repository.

   https://github.com/RethinkRobotics-opensource/meta-ros.git

As of the time this tutorial is written, the latest LTS version of The Yocto Project is Kirkstone. So, I will be using that. Make sure to checkout the correct branch in each of the layers we had cloned.

1. To see which branch you are currently on:

   git status

2. To view all the branches available in said repository:

   git branch -a

3. To checkout a branch in a repository:

   git checkout BRANCH_NAME_Kirkstone

VIMP: For themeta-ros layer, since I want to useROS1 Noetic, make sure to checkout the branchsuperflore/noetic/2023-09-15.

1. Change directory into the project folder where all layers' folders are visible to you.

2. Source the script located in thepoky folder to startbitbake and create a new image folder. Here, I named my imagebuild-RPi4-ROS. Conventionally, all image names start withbuild to make them distinct. Sourcing this script will change your directory to a new folder named the same as the image name and start bitbake.

   source poky/oe-init-build-env build-RPi4-ROS

3. The layers added to the image can be viewed by inserting the command:

   bitbake-layers show-layers

4. Next, we will start adding layers one by one to the image using the commandbitbake-layers add-layer. Note thatmeta-raspberrypi depends on other layers to function correctly, hence they will be added before it. Same story goes tometa-ros. Ergo, add the layers in the same order as written here to avoid any unnecessary errors.

   bitbake-layers add-layer ../meta-openembedded/meta-oebitbake-layers add-layer ../meta-openembedded/meta-pythonbitbake-layers add-layer ../meta-openembedded/meta-networkingbitbake-layers add-layer ../meta-openembedded/meta-multimediabitbake-layers add-layer ../meta-raspberrypibitbake-layers add-layer ../meta-ros/meta-ros-commonbitbake-layers add-layer ../meta-ros/meta-ros1bitbake-layers add-layer ../meta-ros/meta-ros1-noetic

1. Change directory to wherelocal.conf is located in the image folder.

   cd conf

2. Openlocal.conf using a text editor. Here, I open it usinggedit

   gedit local.conf

   Essential Additions

   Comment any line that specifies a certainMACHINE and add this one:

   ## Machine Name: MUST INCLUDEMACHINE = "raspberrypi4-64"

   UART must be enabled in order to be able to communicate with the Pi using serial terminal.

   ENABLE_UART = "1"

   Expanding the size of root filesystem can be beneficial. I have set mine to 5GB since I used a 64GB SD card.

   ## Extend Root Filesystem Size to 5GB (size written in bytes)IMAGE_ROOTFS_EXTRA_SPACE = "5242880"

   Optional Additions

   1. You can add certain applications to your image via the commandIMAGE_INSTALL:append. Make sure to add ones that do not need you to create a recipe to fetch and install them. Here, I addedconnman-client,htop, andnano. Bro Tip:gotocto is an online tool that helps you create a recipe.

      ## Additional PackagesIMAGE_INSTALL:append = " htop"IMAGE_INSTALL:append = " nano"IMAGE_INSTALL:append = " connman-client"

   2. There are multiple options that range from enabling communication protocols like UART, SPI, and I2C; to enabling support for a CAN module and a camera. In order to explore all of these options, feel free to explore themeta-raspberrypi Official Documentation.

   3. You can add extra software features like SSH using the commandEXTRA_IMAGE_FEATURES. I enabled SSH and added features like package management---although I could not get it to work yet, it is worth including for now.

      ## Features like SSHENABLE_SSH_SERVER = "1"EXTRA_IMAGE_FEATURES ?= "debug-tweaks ssh-server-openssh package-management"

   4. Another feature that I could not get to work is makingbash the default shell in the yocto image. I will add the lines used to enable this feature and hopefully update them when I succeed.

      ## Change Default Shell to BashINITSCRIPT_NAME = "bash"BB_ENV_PASSTHROUGH_ADDITIONS = "SHELL"SHELL = "/bin/bash"

Now, all that remains is to run a single command and leave your machine to build the image for the next few hours.Change directory to thebuild-RPi4-ROS folder and run the following command:

time bitbake ros-image-core

My PC took just over 3 hours to complete it as shown below.

Once the previous step is complete, go to the directoryYOUR_YOCTO_DIR/build-RPi4-ROS/tmp/deploy/images/raspberrypi4-64. A file namedros-image-core-noetic-raspberrypi4-64.wic.bz2 should be present. This is the final image that will be burned to the SD card.

The best tool to do this isbalena etcher. You can download it by clickinghere.

Then, follow the steps:

1. Open the downloadedbalena etcher file.Make sure that the file is given the permission to be executable.
2. Choose the file namedros-image-core-noetic-raspberrypi4-64.wic.bz2.
3. Choose the installation medium (SD card).
4. Wait for it to finish---it took about 30 minutes in my case.
5. Remove the SD card and insert it in the Pi.

1. My serial terminal of choice isgtkterm. In order to install it, simply:

   sudo apt install gtkterm -y

2. A common problem with USB-to-TTL devices is that they keep getting disconnected once it is connected to the PC. To solve this, write:

   sudo apt remove brltty

3. Another common issue isgtk saying permission denied for this user. To solve this, add your user to the dialout group:

   sudo usermod -a -G dialout YOUR_USERNAME

1. Insert the SD card into the Pi.
2. Connect the Pi to USB-to-TTL as follows:
   1. GND --> GND
   2. Tx --> Rx
   3. Rx --> Tx
3. Connect USB-to-TTL to the PC via USB.
4. Launchgtkterm using the following command:

   gtkterm -p /dev/ttyUSB0 -s 115200

5. Power on the Pi. You should see the starting screen ongtkterm.

See for yourself :D

You can useconnmanctl to connect to wifi. To do so, follow the steps:

connmanctl

enable wifi

agent on

scan wifi

connect wifi_LOTS_OF_GIBBIRISH_managed_psk

WIFI_PASSWORD

quit

That's all, folks!