About starterkit-embedded-erni-yocto (AKA ideafix)

The Erni Embedded Community has developed Ideafix, an embedded GNU/Linux distribution. It is intended to get started about yocto/poky, and learn as much as possible about it. We'd love to get your contributions so that it becomes a features-plenty distribution.

Why Ideafix? Because Ideafix is the most loyal Operative System of our Gaulish village aka Erni Embedded Community.

features

this yocto layer contains the minimal configuration to start working with yocto/poky
it builds an image (bootloader + sourcetree + initramfs + kernel + partition table + rootfs) which can be used to boot a Raspberry Pi 3b+/4
the image can be tested on a on Qemu-based virtual machine

prerequisites (host OS)

Both Ubuntu 22.04 and 20.04 are elegible as host OS.

installation

Get the apt required packages + repo cloning.

get required packages

The following commands are required to get the apt packages.

sudo apt update

sudo apt install \
    gawk wget git-core git diffstat unzip build-essential chrpath socat cpio \
    python3 python3-pip zstd libsdl1.2-dev xterm make xsltproc fop xmlto libssl-dev pv

pip3 install kas==3.0.2

clone the repo

Clone the ideafix repo, then cd to the cloned repo folder.

git clone https://github.com/ERNI-Academy/starterkit-embedded-erni-yocto.git
cd starterkit-embedded-erni-yocto.git

generation

This project uses KAS to generate and build the image. KAS is a wrapper for the yocto bitbake standard tool, that makes things easier for newcomers to yocto. It uses yml files as input, and from there it downloads the required repositories, and generates the bitbake recipes & output folders.

The generation consists in checking out the ideafix configuration file, and then issuing the corresponding build command, that in ideafix can either be for qemu or rPI.

layers checkout

The first thing to do is to checkout the main kas file, in our case, ideafix.yml.

kas checkout conf/ideafix.yml

This will download all the necessary yocto stuff.

The checkout command does not need to be executed on different sessions, it has persistency on the same repo clone folder. It is only required to be re-executed when you know an update of the yocto is needed.

image build

The image can be built both for rPI (ARM cross-compiling) and for qemu (native simulation). The rPI build generates a file that can be flashed into a microSD disk that can be inserted into the rPI. It is suggested to start with the qemu for the first build, and then the successive experimental changes.

The KAS_BUILD_DIR environment variable configures the build folder. It is highly recommended to isolate the build between the different targets. Thus, it could be used one of the following examples if it is more convenient:

export KAS_BUILD_DIR=qemu
export KAS_BUILD_DIR=raspberrypi

This variable has to be set on every session. Otherwise the output will be in the build folder.

# build the image for testing in qemu
kas build conf/qemu.yml

# build the image for deploying in the raspberry pi3
kas build conf/rpi3.yml

Clarification: In case you are familiar with bitbake (yocto's default tool) the 2 above kas commands are equivalent to the following bitbake commands:

kas shell conf/qemu.yml -c "bitbake core-image-minimal"

kas shell conf/rpi3.yml -c "bitbake core-image-minimal"

Note: The build process may take several hours. The build cache is stored in the sstate folder. The first of each rpi3 and qemu builds will take a lot of time, but subsequent ones, specially if changes are small, will take much less, even if the output folder is changed.

test & deployment

Once the images are built, it is possible to either test the generated qemu or deploy to rPI.

It is important to set again the KAS_BUILD_DIR var in case the build was performed in a different shell session.

qemu verification

To run the image with qemu, execute the following commands depending if a GUI frontend is desired or not.

kas shell conf/qemu.yml -c "runqemu qemuarm serialstdio"

kas shell conf/qemu.yml -c "runqemu qemuarm serialstdio nographic"

Then it is possible to login with the root user or even to ssh to the qemu machine address.

In order to properly stop the qemu it is best to issue the shutdown command (inside the qemu!).

rpi deployment

Once the image has been satisfactorily tested, it is now possible to deploy it with the getImageReady2Flash.sh script. The images files are located in tmp-glibc/deploy/images/raspberrypi3 below the build folder.