| name | anthias-hardware |
| description | Hard-won per-board hardware knowledge for Anthias — display stack (linuxfb/eglfs/wayland-cage), video HW-vs-SW decode per chip (Pi 2/3/4/5, x86, Rock Pi 4), the Qt6 presentation bottleneck, rotation convention, WebGL, boot splash, audio, and the Pi 2 armhf toolchain SIGBUS. Read before touching viewer rendering, codec, rotation, display-power, or Qt build code. |
Anthias board / display / codec knowledge
Durable engineering findings from field debugging across the board fleet. Each
bullet carries the mechanism plus the fixing PR / CalVer release where known;
OPEN items are called out. Boards map to a rendering stack by userspace arch, so
read the display-stack section first.
Display stack fundamentals (QPA: linuxfb / eglfs / wayland-cage)
- Board → QPA plugin mapping. Pi 1/2/3-32 (armhf/Qt5) run
QT_QPA_PLATFORM=linuxfb (needs /dev/fb0); Pi 3-64/Pi 4 (arm64/Qt6) run eglfs (DRM/GBM, holds DRM master, no fb0); Pi 5/x86/Rock Pi 4 (arm64/Qt6) run cage/wlroots wayland. Pi 4 switched linuxfb→eglfs in #2904 for HW video. Stale start_viewer.sh comments claiming "Pi 4 runs linuxfb" were corrected in #2962.
- DRM master ownership determines what can blank/rotate/recover. On eglfs/linuxfb the Qt app (or drm_fb_helper) owns DRM master; on wayland the cage compositor owns the connector. This single fact drives blanking, hotplug recovery, and rotation mechanism per stack.
- Board selection is by userspace arch (
dpkg --print-architecture), NOT uname -m or model string. 32-bit Raspberry Pi OS ships a 64-bit kernel by default on Pi 3 (arm_64bit=1), so uname -m=aarch64 while docker/apt are armhf. Gating on kernel arch mispicked pi3-64 and pulled linux/arm/v8 (no matching manifest). Fixed in PR #3076 (2026-06-16) to gate on userspace arch. catch-all branch still uses (no armhf image for generic SBCs). No in-place arch switch — only reflash changes streams.
