Building custom Yocto Linux distribution: adding Wayland/Weston image

Previous article has explained how to create python based application and add it to custom Yocto image. The limitation of that approach was the fact that image used was console only, without GUI support. Such image could not be used to run electric motorcycle dashboard, so in this tutorial we will create new image which is heavily inherited from corresponding Wayland/Weston image from ST and explain how to start electric motorcycle dashboard application at boot using systemd.

Add new image to meta-cybbed with following content:

$ cat recipes-core/images/st-image-cybbed-weston.bb
SUMMARY = "Cybbed image for electric motorcycle with Wayland support"
LICENSE = "Proprietary"

# Common code for generating core reference images
inherit core-image features_check

# Ensure Wayland distro is enabled
REQUIRED_DISTRO_FEATURES = "wayland"

# Install addons
CORE_IMAGE_EXTRA_INSTALL += " \
    resize-helper \
    \
    packagegroup-framework-core-base    \
    packagegroup-framework-tools-base   \
    \
    packagegroup-framework-core         \
    packagegroup-framework-tools        \
    \
    packagegroup-framework-core-extra   \
    \
    ${@bb.utils.contains('COMBINED_FEATURES', 'optee', 'packagegroup-optee-core', '', d)} \
    ${@bb.utils.contains('COMBINED_FEATURES', 'optee', 'packagegroup-optee-test', '', d)} \
    \
    ${@bb.utils.contains('COMBINED_FEATURES', 'tpm2', 'packagegroup-security-tpm2', '', d)} \
    "

# Add custom applications
IMAGE_INSTALL += " pygui"

This image requires Wayland distro to be enabled. A distro layer refers to a collection of metadata that defines the configuration and customization options for distribution. It contains configuration files and scripts that specify the packages and features to be included in the distribution, as well as any customizations or modifications to the default settings of the Yocto build system.
Instructions on how to add Wayland distro will be provided later in this article.

CORE_IMAGE_EXTRA_INSTALL specifies the list of packages to be added to the image. This variable applies if image is based on core-image as is in our case (we have inherited core-image class at the beginning of recipe).

Additionally we add our custom recipe to the image using IMAGE_INSTALL variable. pygui is python based dashboard application which was described in previous article.

Once new image is added, let’s add Wayland based distro to meta-cybbed layer.

$ mkdir conf/distro
$ cat conf/distro/cybbed-distro-weston.conf
require conf/distro/include/st-default-distro-rules.inc
require conf/distro/include/st-default-distro-providers.inc
require conf/distro/include/openstlinux.inc

DISTRO = "cybbed-distro-weston"
DISTRO_NAME = "Xwayland Yocto Project"
DISTRO_FEATURES:append = " opengl"
DISTRO_FEATURES:append = " xwayland"

Our distro is mainly based on corresponding ST distro with added Xwayland support. Xwayland is a display server that allows applications using the X11 to run on modern systems that use the Wayland display server. Xwayland is required for pygui to run properly.

Now our Yocto distribution has all the required to display electric motorcycle dashboard. The only limitation is that we need to manually launch the GUI app each time the system boots.
Let’s improve this by adding dashboard application to systemd.
Systemd is a system and service manager for Linux OS. It is responsible for controlling the startup and shutdown of system services, as well as managing and monitoring their run-time behavior.

Good example of adding systemd Yocto recipes can be found at Toradex website.
To add our application to systemd, we will to need to create new Yocto recipe that adds a service file that describes how the application should be run and managed by systemd. A service file is a configuration file that specifies the details of a system service, such as the command to be run, any dependencies that the service has, and how the service should be restarted if it fails.

Create new folder gui-autoboot and add gui-autoboot.bb recipe:

$ mkdir recipes-gui/gui-autoboot
$ cat recipes-gui/gui-autoboot/gui-autoboot.bb
SUMMARY = "Wayland application autostart"
DESCRIPTION = "This will start a wayland application after the wayland socket has been created."
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"

inherit allarch systemd

RDEPENDS:${PN} += "weston-init weston"

S = "${WORKDIR}"

SRC_URI = " \
    file://gui-autoboot.service \
    file://gui-autoboot.sh \
"
FILESEXTRAPATHS:prepend := "${THISDIR}/gui-autoboot:"

do_install () {
    install -d ${D}/${bindir} ${D}${systemd_unitdir}/system/
    install -m 0644 ${WORKDIR}/gui-autoboot.service ${D}${systemd_unitdir}/system
    install -m 0755 ${S}/gui-autoboot.sh ${D}/${bindir}
}

SYSTEMD_PACKAGES = "${PN}"
SYSTEMD_SERVICE:${PN} = "gui-autoboot.service"

The recipe takes gui-autoboot.service and gui-autoboot.sh files and add them to corresponding systemd directories on rootfs. Let’s add these files:

$ mkdir recipes-gui/gui-autoboot/gui-autoboot
$ cat recipes-gui/gui-autoboot/gui-autoboot/gui-autoboot.service
[Unit]
Description=Start a emoto GUI application
After=weston-launch.service
Requires=weston-launch.service

[Service]
Restart=on-failure
Type=forking
User=weston
ExecStart=/usr/bin/gui-autoboot.sh
RestartSec=1

[Install]
WantedBy=multi-user.target

$ cat recipes-gui/gui-autoboot/gui-autoboot/gui-autoboot.sh
#!/bin/sh

cd /usr/share/pygui
python3 emoto_dash.py &

gui-autoboot.service is systemd file which describes what service to start and how. Unit section describes the service itself and specifies other services dependencies (if any). Our service depends on and should be started after weston-launch.service was launched.
Service section specify what executable/script to run, how to restart the service and what username will launch it.

Last step is to include gui-autoboot recipe to st-image-cybbed-weston.bb image:

...
# Add custom applications
IMAGE_INSTALL += " pygui gui-autoboot"
...

Rebuild the image and flash to SD card:

$ bitbake st-image-cybbed-weston
$ sudo ./flash.sh /dev/mmcblk0

Once STM32MP1 has started, new GUI application will be launch automatically immediately after boot.