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

The are essentially two ways how to flash images: Either you flash an image to an SD-card and boot from it, or alternatively (if the device supports that) you flash your image to the persistent device memory. Especially for starting, whenever possible due to the used device, use the SD-card variant because it is much more fault-tolerant; if anything goes wrong, you just rewrite the SD-card and the board will start again.

For all devices listed under Yocto/DemoDevices the following approach will work:

Install bmaptool on your system (on Debian package bmap-tools
Insert an SD-card reader with the SD-card into your computer
Select the correct device:
- BE VERY CAREFUL HERE, BECAUSE OTHERWISE YOU MIGHT OVERWRITE DATA ON YOUR COMPUTER!
- Look at the output of command dmesg to check as which device your SD-card was detected. The following output shows an example where the SD-card is named /dev/sdd:

[17778.024029] sd 5:0:0:0: Attached scsi generic sg4 type 0
[17778.383537] sd 5:0:0:0: [sdd] 62333952 512-byte logical blocks: (31.9 GB/29.7 GiB)
[17778.384576] sd 5:0:0:0: [sdd] Write Protect is off
[17778.384588] sd 5:0:0:0: [sdd] Mode Sense: 23 00 00 00
[17778.385530] sd 5:0:0:0: [sdd] Write cache: disabled, read cache: enabled, doesn't support DPO or FUA
[17778.391820]  sdd: sdd1 sdd2
[17778.392345] sd 5:0:0:0: [sdd] Attached SCSI removable disk

Check that no partition was automatically mounted:
- Check that no partition is mounted with lsblk and, if needed, unmount those partitions
Flash the image:
- enter your Yocto build folder at build/tmp/deploy/images/MACHINE/
- the image that you want to flash is named IMAGE-MACHINE.wic.gz and can be flashed with: sudo bmaptool copy IMAGE-MACHINE.wic.gz /dev/sdX
- an example looks like: sudo bmaptool copy kde-demo-image-visionfive2.wic.gz /dev/sdd
Wait until the bmap command finishes and after it you can safely pull out the card from your system.

Further in-depth information can be found in the Yocto Project documentation: https://docs.yoctoproject.org/dev/dev-manual/bmaptool.html

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