Getting Started

This page is supposed to give a simple to follow guide of the first steps one have to do to assemble a setup for embedded development, preparing a first build via Yocto, build it and test-run it on the development device.

Links to Yocto Documentation

Most of the following documentation has a steep learning curve, but will become useful after completion of this guide:

Yocto Documentation : https://docs.yoctoproject.org/
Bitbake Documentation : https://docs.yoctoproject.org/bitbake/2.4/index.html
- Especially helpful: the "Variables Glossary"
Yocto Project Wiki : https://wiki.yoctoproject.org/wiki/Main_Page

Material Needed

Embedded development always have the problem that you need some material additional to a development computer.

The most important components that one always should have:

development board
power supply for the development board
micro SD card as main storage of the development board
a micro SD card writer/reader
Ethernet network cable

Optional

The following parts often make sense, but usually are not needed in the beginning:

a RS232-USB adapter for low level debugging of startup problems of the development board

Preparation for Yocto Build

Here we do a few things:

Prepare a Docker container with the required Yocto dependencies, in which the Yocto build will happen.
Checkout a configuration of the KDE Demo image and set it up

Preparation of Docker Container and Yocto Configurations

The basic source code repository for this step is kde:packaging/yocto-manifest (https://invent.kde.org/packaging/yocto-manifest). Select a location where you have a lot (and this really means >200 GB) of free space. In the following, we assume that /opt/yocto is such a location; just replace it in the commands if it is different.

# get Yocto sources
export YOCTODIR=/opt/yocto
git clone kde:packaging/yocto-manifest manifest

# step: prepare docker container with name "yocto-kirkstone"
docker build ${YOCTODIR}/manifest/containers/kirkstone  -t yocto-kirkstone

# step: obtain Google's repo tool
curl https://storage.googleapis.com/git-repo-downloads/repo > ${YOCTODIR}/repo
chmod a+x ${YOCTODIR}/repo

# step: prepare Yocto folder structure; using Yocto release "mickledore"
mkdir ${YOCTODIR}/mickledore && cd ${YOCTODIR}/mickledore
${YOCTODIR}/repo init -u https://invent.kde.org/packaging/yocto-manifest.git -m mickledore.xml
${YOCTODIR}/repo sync

Your First Yocto Build

In this step, we run the Docker container and inside it, we "source" the Bitbake environment. That means, by running the commands, we first enter the Docker container, which make it safe to not introduce unwanted environment variables and have all the tools needed. Secondly, the Bitbake compiling mode (called the "cooker" mode) essentially means that many environment variables are configured in your shell and we doing this by sourcing a script.

Please note that the call of the Docker container is created in a way that it mounts your host folder ${YOCTODIR} (which need to be set like in the previous step here) inside the Docker container, such that you can reuse data from one Yocto build to the next.

docker run -it --rm -v ${YOCTODIR}:/opt/yocto yocto-kirkstone
cd /opt/yocto/mickledore

# the MACHINE value decides which system is being built for, see below
MACHINE=raspberrypi4 . ./setup-environment
bitbake kde-demo-image --runall=fetch # first only fetch all the source code
bitbake kde-demo-image                # then start the build, which will take several hours

Available Images

With the default KDE configuration the following machine times are available and are recommended:

raspberrypi4
visionfive2
raspberrypi3

Image Flashing

This section will explain how to use bmaptool to copy image in the SD card. Or alternatively, dd.

Accessing the Device

Usually there are to main ways to get access to your embedded device:

- serial console (sTTY) - network connection via Ethernet

Setting-up Serial Console

For being able to access your device via a serial console, you first need a "RS232-USB" Adapter. Those are very cheap and available in most online electronic stores. There are those with a 9-PIN D-SUB adapter and with "raw" small PINs connected. You want to have the latter one because than you can connect the single PINs as needed to your devices. The connection figures should be part of the device documentation.

Having connected the RS232-adapter to the device as well as the USB connector to your computer, you should find a new device `/dev/ttyUSB0`. For accessing it on most distributions your user must be part of the dialout group or you have to use sudo (using the correct group is preferred).

There are many application to connect to the serial console, here are only a few choices listed (usually, the baud rate is 115200):

picocom -b 115200 /dev/ttyUSB0 : picocom is a very simple serial console reader that is very easy to use for beginners.

When you connect your serial console application to your USB-adapter and then power-on your device, you should be able to see the Kernel outputs from the device. After the Kernel startup, the systemd service systemd-getty should start and provide you with a login prompt.

Note: Those outputs or the serial console could be deactivated and you might need to enable them explicitly. For example, this is the case for RaspberryPi.

Handling First Startup Issues