Graphical support: Wayland and LVGL

redpesk OS can be used with standard Linux graphical stacks and with LVGL applications on embedded targets.

Two test packages are available to validate the graphical stack:

• cage-gtk-demo runs the GTK4 demo application inside the Cage Wayland compositor;
• lv-port-linux provides LVGL demo executables built for several Linux display backends.

These packages are intended for integration and graphical stack validation. They are not application frameworks and the availability of a backend still depends on the graphics hardware, kernel drivers and device nodes provided by the target BSP.

Graphical stack overview

The packaged tests cover both direct display access and compositor-based rendering:

GTK4 demo -----------------> Cage/Wayland -----> DRM/KMS -----> display

LVGL -- Wayland -----------> Cage/Wayland -----> DRM/KMS -----> display
     \
      +-- DRM/EGL -----------------------------> DRM/KMS -----> display
      +-- framebuffer -------------------------> /dev/fb* ----> display

The following validation applications are currently packaged:

Building a graphical BeaglePlay image with rp-mkosi

rp-mkosi provides a graphical profile. The profile installs cage-gtk-demo-test and sets graphical.target as the default systemd target in the generated image.

For example, build a BeaglePlay image with:

PATH="/usr/sbin:/sbin:/usr/lib/systemd:$PATH" \
mkosi -I mkosi-beagleplay.conf \
    --debug \
    --force \
    --debug-workspace \
    -E REDPESK_DISTRO=corn-3.0-update \
    --profile smack,minimal,localrepo,graphical \
    --output-directory output_beagleplay

The current graphical profile installs the Cage/GTK validation package. Install lv-port-linux separately when LVGL validation is required:

dnf install lv-port-linux

Alternatively, add lv-port-linux to the package list of the image configuration when it must be present in the generated image.

Validating Wayland with Cage and GTK4

The cage-gtk-demo package provides gtk-demo.service. The service starts Cage as a kiosk Wayland compositor and launches gtk4-demo as the graphical client.

The service runs with the dedicated test_gtk user and relies on systemd-logind and seatd for access to the graphical seat. The package also ships a systemd preset enabling the service.

After boot, check that the service is enabled and running:

systemctl is-enabled gtk-demo.service
systemctl is-active gtk-demo.service
systemctl status gtk-demo.service

If the service does not start, inspect its journal:

journalctl -u gtk-demo.service -b

The expected output is the GTK4 demo application displayed through Cage:

Running the LVGL validation applications

Install the package if it is not already present:

dnf install lv-port-linux

List the packaged applications with:

rpm -ql lv-port-linux | grep '/usr/bin/lvglsim-'

Wayland backend

An LVGL Wayland executable is a Wayland client and therefore requires a running Wayland compositor.

To test it directly with Cage, first stop the GTK demo so that Cage is not already using the display:

systemctl stop gtk-demo.service

Prepare the runtime directory used by the graphical test user and start the LVGL client in Cage:

install -d -m 0700 -o test_gtk -g test_gtk /tmp/xdg-runtime-dir

runuser -u test_gtk -- \
    env XDG_RUNTIME_DIR=/tmp/xdg-runtime-dir \
    cage /usr/bin/lvglsim-wayland

For the EGL/OpenGL ES Wayland variant, use:

runuser -u test_gtk -- \
    env XDG_RUNTIME_DIR=/tmp/xdg-runtime-dir \
    cage /usr/bin/lvglsim-wayland-egl

Direct DRM/EGL backend

The DRM variants access the DRM/KMS device directly. Stop any compositor using the same display before starting them:

systemctl stop gtk-demo.service
lvglsim-drm-egl-2d

The 3D-enabled build can be started with:

lvglsim-drm-egl-3d

By default, the LVGL Linux DRM backend uses /dev/dri/card0. Override it when required:

LV_LINUX_DRM_CARD=/dev/dri/card1 lvglsim-drm-egl-2d

Framebuffer backend

When the BSP exposes a Linux framebuffer device, run:

lvglsim-fbdev

The default framebuffer is /dev/fb0. A different device can be selected with:

LV_LINUX_FBDEV_DEVICE=/dev/fb1 lvglsim-fbdev

The framebuffer test is only applicable when a /dev/fb* device is provided by the target kernel/BSP.

Graphical non-regression test

The cage-gtk-demo-test subpackage provides a graphical non-regression test based on HDMI capture.

The test requires an HDMI/UVC capture device visible through V4L2. The system running the test must see the capture device, by default as /dev/video0.

The validation flow is:

1. run gtk4-demo through Cage on the target display;
2. capture the HDMI output through a UVC capture device;
3. compare the captured frame with the packaged reference image;
4. report an error when the image similarity is below the required threshold.

The packaged checker uses a 1920x1080 MJPEG stream at 30 FPS, discards the first 30 frames to let the stream stabilize, and requires at least 95% image similarity.

Run it manually with:

/usr/libexec/cage-gtk-demo/check-video.sh \
    /usr/share/cage-gtk-demo/tests/capture_ref.jpg \
    /dev/video0

The command returns:

• 0 when the image matches the reference;
• 1 when the similarity is below the threshold;
• 2 for a setup, capture or tool error.

The test package also provides a Redtest check under:

/usr/libexec/redtest/cage-gtk-demo/checks/grafic-check.sh

The Redtest wrapper writes the graphical result in TAP format.

Troubleshooting

Check the graphical devices

Inspect the graphics and input device nodes available on the target:

ls -l /dev/dri/
ls -l /dev/fb* 2>/dev/null
ls -l /dev/input/

Check seat access

Cage uses seatd and the graphical test user is expected to have access to the video, input and seat groups:

systemctl status seatd.service systemd-logind.service
id test_gtk

Check the HDMI capture device

List V4L2 devices:

v4l2-ctl --list-devices

Then inspect the formats supported by the selected capture device:

v4l2-ctl -d /dev/video0 --list-formats-ext

The packaged graphical checker expects MJPEG capture at 1920x1080 and 30 FPS.

Direct DRM application fails while Wayland is running

A direct DRM/KMS application and a Wayland compositor normally compete for the same display resources. Stop gtk-demo.service before running lvglsim-drm-egl-2d or lvglsim-drm-egl-3d directly:

systemctl stop gtk-demo.service

Restart the Wayland validation service afterwards with:

systemctl start gtk-demo.service

Upstream projects

• LVGL Linux port: https://github.com/lvgl/lv_port_linux
• LVGL: https://github.com/lvgl/lvgl