Skip to main content

Yocto for reTerminal

pir

Overview​

What is Yocto Project®?​

The Yocto Project is an open source collaboration project that helps developers create custom Linux-based systems for embedded products, regardless of the hardware architecture.

The project provides a flexible set of tools and a space where embedded developers worldwide can share technologies, software stacks, configurations and best practices which can be used to create tailored Linux images for embedded devices.

The project provides a standard to delivering hardware support and software stacks, allowing the interchange of software configurations and builds. The tools allow users to build and support customizations for multiple hardware platforms and software stacks in a maintainable and scalable way.

Why Use Yocto?​

Yocto Project has a development model for embedded Linux creation which distinguishes it from other simple build systems. It is called the Layer Model.

The Layer Model is designed to support both collaboration and customization at the same time. Layers are repositories containing related sets of instructions which tell the build system what to do. Users can collaborate, share, and reuse layers. Layers can contain changes to previous instructions or settings at any time.

This powerful override capability is what allows you to customize previous collaborative or community supplied layers to suit your product requirements.

Use different layers to logically separate information in your build. As an example, you could have a BSP layer, a GUI layer, a distro configuration, middleware, or an application. Putting your entire build into one layer limits and complicates future customization and reuse. Isolating information into layers, on the other hand, helps simplify future customizations and reuse.

Features of Yocto​

Yocto has the following features:

  • CII Best Practices: The Linux Foundation (LF) Core Infrastructure Initiative (CII) Best Practices badge is a way for Free/Libre and Open Source Software (FLOSS) projects to show that they follow best practices. The Yocto Project is registered and has the following badge level.

  • Binary Reproducibility: If a distribution isn’t specific about which packages to pull in to support dependencies, or their order, build systems can arbitrarily include packages based on when dependencies are filled. The Yocto Project controls dependencies avoiding contamination and has achieved reproducibility of 99.8% in “core-image minimal” and slightly less in expanded tests.

  • Cross Platform Development Framework (CROPS): CROPS is an open source, cross-platform development framework that leverages Docker containers to provide an easily managed, extensible environment which allows developers to build binaries for a variety of architectures of Windows, Linux and Mac OS X hosts.

  • Extensible SDK: The Yocto Project Extensible SDK (eSDK) has tools that allow you to easily add new applications and libraries to an image, modify the source of an existing component and test changes on the target hardware.

  • Toaster: Toaster is a web interface to OpenEmbedded and BitBake, the build system used by the Yocto Project. Toaster allows you configure and run your builds, and provides information and statistics about the build process.

  • Multi-Config: The build system can automatically and efficiently build multiple specified architectures with one command.

  • Binary Builds: The Yocto Project allows binary files to be included in the build without including the corresponding source code files.

  • Open Source License Manifest Generation: The Yocto Project can keep track of all open source licenses used in the build and provide you with a manifest of those licenses and source references.

By following the guide below, you will be able to build your own reTerminal system image using Yocto. So let's get started!

Compile Yocto Source Code​

Manual Compilation on Local Machine - Using Bitbake (Command Line)​

Now we will move on to manually compiling the system image for reTerminal using Yocto via the command line.

Note: This guide was written after testing on a host PC with Ubuntu 20.04 installed. However, it will work for other Linux systems.

Compile with the default configuration for reTerminal​

Follow the steps below to start compiling with the default reTerminal configuration

  • Step 1. Prepare the development environment on the host PC by installing the following packages
sudo apt update
sudo apt install gawk wget git-core diffstat unzip texinfo gcc-multilib build-essential chrpath socat python3-distutils

Note: If the host PC is running a different Linux distribution, please check here

  • Step 2. Create a new working directory and enter it
mkdir reterminal-yocto
cd reterminal-yocto
  • Step 3. Create a new directory to add layers and enter it
mkdir layers 
cd layers
  • Step 4. Clone the following GitHub repo
git clone -b dunfell git://git.yoctoproject.org/poky
  • Step 5. Clone the following repos
git clone -b dunfell https://github.com/Seeed-Studio/meta-seeed-cm4.git
git clone -b master git://git.yoctoproject.org/meta-raspberrypi
git clone -b dunfell https://github.com/meta-qt5/meta-qt5.git
git clone -b dunfell https://github.com/openembedded/meta-openembedded.git
  • Step 6. Change kernel version from 5.4 to 5.10 in meta-raspberrypi layer
cd meta-raspberrypi/
cp -r recipes-kernel/linux/ ../
git checkout dunfell
rm -r recipes-kernel/linux/
mv -f ../linux/ recipes-kernel/
cd ../../
  • Step 7. Initialize the build environment
source layers/poky/oe-init-build-env
  • Step 8. Add the layers to the build environment
bitbake-layers add-layer ../layers/meta-raspberrypi
bitbake-layers add-layer ../layers/meta-seeed-cm4
bitbake-layers add-layer ../layers/meta-qt5
bitbake-layers add-layer ../layers/meta-openembedded/meta-oe
bitbake-layers add-layer ../layers/meta-openembedded/meta-python
  • Step 9. Move back to the build directory and execute the following to start compiling
MACHINE="seeed-reterminal" bitbake rpi-test-image

Find the Compiled Image​

After compilation is finished, go to the build directory and run the following command to check whether the system image is sucessfully generated

cd tmp/deploy/images/seeed-reterminal/;ls -lh rpi-test-image*.wic.bz2

pir

As shown in the image above, rpi-test-image-seeed-reterminal.rootfs.wic.bz2 is the generated system image

Useful Bitbake Commands​

Refer to the following to get familiarized with some useful Bitbake commands

Start compiling the image​
  • bitbake < image >

This command will start compiling the image. You can add -k to continue compiling even errors are found. While the target that failed and anything depending on it cannot be built, as much as possible will be built before stopping.

Example 1:

bitbake rpi-test-image

Example 2:

bitbake rpi-test-image -k
Show packages in the image​
  • bitbake -g < image > && cat pn-buildlist | grep -v -e '-native' | grep -v digraph | grep -v -e '-image' | awk '{print $1}' | sort | uniq

This will save the packages inside the image into a file named pn-buildlist and then list them on console

Example:

bitbake -g rpi-test-image && cat pn-buildlist | grep -v -e '-native' | grep -v digraph | grep -v -e '-image' | awk '{print $1}' | sort | uniq

pir

Show package dependencies​
  • bitbake -g < package > && cat pn-buildlist | grep -v -e '-native' | grep -v digraph | grep -v -e '-image' | awk '{print $1}' | sort | uniq

This will save the package dependencies into a file named pn-buildlist and then list them on console

Example:

bitbake -g i2c-tools && cat pn-buildlist | grep -v -e '-native' | grep -v digraph | grep -v -e '-image' | awk '{print $1}' | sort | uniq

pir

Task dependency explorer UI​
  • bitbake < image > -g -u taskexp

This is will helpful to show the Task Dependency Explorer UI. It shows dependencies between tasks

Example:

bitbake rpi-test-image -g -u taskexp

pir

Launch devshell for a package​
  • bitbake < package > -c devshell

This will open a new shell where with the neccesary system values already defined for the package

Example:

bitbake evtest -c devshell

pir

List package tasks​
  • bitbake -c listtasks

This will list all tasks for a package

Example:

bitbake evtest -c listtasks

pir

Interactive kernel configuration​
  • bitbake virtual/kernel -c menuconfig

This will open an interactive kernel configuration window where you can change the settings according to your needs

pir

Show layers​
  • bitbake-layers show-layers

This will show a list of the layers currently in use, and their priorities. If a package exists in two or more layers, it will be built from the layer with higher priority

pir

Show recipes​
  • bitbake-layers show-recipes

This will show all the available recipes

If you type the following, you can check for the recipe that we used previously, which is rpi-test-image

bitbake-layers show-recipes | grep rpi

pir

Check for package​
  • bitbake -s | grep

This will check if a certain package is present on current Yocto Setup

bitbake -s | grep openssl

pir

Save verbose build log​
  • bitbake -v < image > 2>&1 | tee image_build.log

This will print (on console) as the image starts building and store the output in image_build.log with verbose mode

Example:

bitbake -v rpi-test-image 2>&1 | tee image_build.log
Clean the build environment​
  • bitbake -c cleanall [package]

This will remove everything in the work directory, state cache, and all previously downloaded source files related to the package. This will be helpful if you are running into build problems for a particular package

Example:

bitbake -c cleanall i2c-tools

Manual Compilation on Local Machine - Using Toaster (GUI)​

Now we will move on to manually compiling the system image for reTerminal using Toaster.

Toaster is a web interface to OpenEmbedded and BitBake, the build system used by the Yocto Project®. Toaster allows you configure and run your builds, and provides information and statistics about the build process.

Note: This guide was written after testing on a host PC with Ubuntu 20.04 installed.

  • Step 1. Update the packages list
sudo apt update
  • Step 2. Prepare the development environment on the host PC by installing the following packages
sudo apt-get install 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 \
     pylint3 xterm

Note: If your host PC is running a different flavor of Linux, click here to check the packages that needs to be installed according to your OS

  • Step 3. Clone the following GitHub repo
git clone -b master git://git.yoctoproject.org/poky
  • Step 4. Navigate to the poky directory
cd poky
  • Step 5. Install the following toaster packages
pip3 install --user -r bitbake/toaster-requirements.txt
  • Step 6. Revert to the following commit for the poky directory
git reset --hard 7ade8346b3a09983257589d22aaada47e0eec010
  • Step 7. Source the build environment script
source oe-init-build-env
  • Step 8. From the build directory, start toaster
source toaster start
  • Step 9. To access the Toaster web interface, open your favorite browser and enter the following
http://127.0.0.1:8000

Note: By default, Toaster starts on port 8000. You can use the WEBPORT parameter to set a different port. For example, the following command sets the port to "9000"

source toaster start webport=9000
  • Step 10. Once you are inside the Toaster web interface, click on New project

pir

  • Step 11. Enter a Project name, set the project type to New project, under Release, select Local Yocto Project and finally click Create project

pir

  • Step 12. Inside the Configuration tab, under Machine, change the name to raspberrypi4-64 and click Save

pir

  • Step 13. Click Import layer

pir

pir

  • Step 18. Navigate to BitBake variables and add a new variable with the following
- Variable:RPI_KERNEL_DEVICETREE_OVERLAYS_append
- Value: overlays/reTerminal.dtbo overlays/i2c3.dtbo

Note: Make sure to add a space before overlays/xxxx

  • Step 19. Repeat the same to add the following
- Variable:PACKAGECONFIG_append_pn-qtbase
- Value: eglfs

Note: Make sure to add a space before eglfs

- Variable:DISTRO_FEATURES_remove
- Value: x11 wayland vulkan

Note: Make sure to add a space before x11 xxx

pir

  • Step 20. Finally type rpi-test-image and click on Build to start building the project

pir

Now you will see the building process as follows

pir

Once the build is finished, you will see the following

pir

  • Step 21. Click on rpi-test-image to find more details about the image build

  • Step 22. Under Image files, click on tar.bz2 to download the compiled image

pir

  • Step 23. Go further down on this page to learn more about the Build Summary

pir

Download Already Compiled Image​

If you want to download a reTerminal system image which is already compiled using Yocto, you can proceed to the steps below.

  • Step 1. Open this link to enter the Actions page of meta-seeed-reterminal GitHub repo

  • Step 2. Click on the latest Seeed reTerminal Yocto embedded linux workflow

pir

  • Step 3. Under Artifacts, click on yocto deploy to start downloading the image

pir

  • Step 4. After downloading the image, the image will be named as yocto deploy.zip. Extract this .zip file and you will find a file named yocto-image.tar.xz

  • Step 5. Extract this yocto-image.tar.xz file and you will find a file named yocto-image.tar

  • Step 5. Extract this yocto-image.tar file and navigate to deploy > images > raspberrypi4-64. Look for a file with extension .rootfs.wic.bz2. That is the system image file

pir

Flash the Image to reTerminal​

Now we will move onto flashing the image to the eMMC of the CM4 on the reTerminal.

Follow the steps in this wiki and pay attention to the following step:

Note: When you open Raspberry Pi Imager, click CHOOSE OS, select Use custom and choose the downloaded .rootfs.wic.bz2 file.

pir

First Boot on reTerminal​

After we flash the system image to the reTerminal, power on the reTerminal. Here you will see the kernel log pop up on the reTerminal LCD and at last a demo application will open which is made using Qt.

The boot up time of the default system image is around 17 seconds

pir

Login to reTerminal from PC via Serial Console​

It is recommended to login to the OS inside the reTerminal using a serial console connection. Check this wiki to make the hardware connections and login as root

Test Yocto Image​

To test the above Yocto image with reTerminal, you can visit the reTerminal Hardware and Interfaces Usage wiki and refer to the steps mentioned.

Talk at Yocto Project Summit 2021​

This talk mainly focuses on explaining how easily you can create custom Linux images for CM4 Carrier Boards, X86, and STM32 Boards using Yocto project. Also, at the end of the talk, there are two HMI demos based on Qt, LVGL, and a demo to showcase secure and robust OTA updates to these SBCs using Mender.

Resources​

Tech Support​

Please submit any technical issue into our forum.

Loading Comments...