KioskConfig/PLAN-drm-kms.md

DRM/KMS Direct Mode — Deferred to Post-Launch

Status: Deferred (too much risk before launch) Created: 2026-08-17

---

Goal

Remove Cage (Wayland compositor) from -dev kiosk variants and run RadiantWave directly on DRM/KMS via SDL3's built-in SDL_VIDEODRIVER=drm backend. This simplifies the stack, removes compositor overhead, and is better suited for embedded/hardware kiosks.

Decision: Deferring until after the current launch. Cage works, and the transition touches every variant's boot pipeline.

---

What Cage Currently Provides

Feature	How Cage Does It	DRM/KMS Replacement
Display mode setting	Opens /dev/dri/card* via libseat, selects connector/CRTC/mode	SDL3 DRM backend opens DRM devices directly
Fullscreen surface	Creates Wayland surface, manages lifecycle	SDL3 creates DRM framebuffer surface
Page flipping / VSync	Handles drmHandlePageFlip()	SDL3 DRM backend handles page flip
Input devices	Opens /dev/input/* via libseat, generates Wayland events	SDL3 DRM backend reads evdev directly
Keyboard mapping	XKB keymap loading, key repeat	SDL3 handles keymap translation
Seat management	Connects to seatd via libseat	Not needed — group permissions (video, input) suffice

---

What Stays Safe Without Cage

Concern	Why It's Safe
Audio	PipeWire/ALSA works independently of the compositor. App uses SDL3_mixer -> ALSA. Audio init service still runs before launch.
WiFi	NetworkManager uses system bus (sd_bus_open_system() in network_manager.cpp). No session bus needed. networkmanager group handles D-Bus access.
Keyboard/input	SDL3's DRM backend reads /dev/input/* evdev directly. input group grants access.
DRM/display	SDL3's DRM backend opens /dev/dri/card* directly. video group grants access.
Plymouth	sudo -n plymouth quit --wait still works — Plymouth runs as root on DRM/KMS.
Auto-login	getty autologin still works on tty1.
Health check	pgrep -f '.radiantwave-unwrapped' still works — no wrapper changes.
Backup service	Runs as kiosk user, rsyncs ~/.local/radiantwave. No compositor dependency.

---

Implementation Plan — 4 Phases

All changes are in kioskconfig only. The radiantwave app needs no code changes — SDL3 handles DRM/KMS internally when SDL_VIDEODRIVER=drm is set. The NixOS system already provides Mesa/EGL/GBM via hardware.graphics.enable = true.

Only -dev variants are modified. Production configs stay on Cage.

New module: kiosk-drm.nix

A NixOS module that overrides the Wayland/cage setup:

• environment.systemPackages = mkForce [...] — same list as configuration.nix but without pkgs.cage
• environment.loginShellInit = mkForce ''... — same script but:
  • Sets SDL_VIDEODRIVER=drm instead of wayland
  • Removes WLR_RENDERER, WLR_NO_HARDWARE_CURSORS, QT_QPA_PLATFORM, XDG_SESSION_TYPE, GODEBUG
  • Launches exec /run/current-system/sw/bin/radiantwave directly (no dbus-run-session cage --)
  • Keeps: network wait, audio init, Plymouth quit
• services.seatd.enable = mkForce false — nothing uses libseat anymore

---

Phase 1: radiantwavekiosk-dev (Intel NUC)

Files:

• Create kiosk-drm.nix
• Modify flake.nix: add ./kiosk-drm.nix to extraModules for radiantwavekiosk-dev
• dev-iso.nix already targets radiantwavekiosk-dev — no change needed

Verify: nix build .#nixosConfigurations.radiantwavekiosk-dev.config.system.build.toplevel

---

Phase 2: radiantwavekiosk-commercial-dev (commercial HW)

Files:

• Modify flake.nix: add ./kiosk-drm.nix to extraModules for radiantwavekiosk-commercial-dev
• Create commercial-dev-iso.nix (same pattern as dev-iso.nix, targeting radiantwavekiosk-commercial-dev)
• Add commercial-dev-iso config to flake.nix

Verify: nix build .#nixosConfigurations.radiantwavekiosk-commercial-dev.config.system.build.toplevel

---

Phase 3: radiantwavekiosk-android-dev (rotated display)

Files:

• Create radiantwavekiosk-android-dev in flake.nix (currently only production radiantwavekiosk-android exists)
• Create android-kiosk-drm.nix — DRM/KMS mode + display rotation

Challenge: rotated_display.nix uses wlr-randr (Wayland tool) for 90-degree rotation. Without Cage/Wayland, this won't work. Alternatives:

• Option A: Use modetest from libdrm to set DRM rotation property
• Option B: Handle rotation in the app (query display orientation, render rotated)
• Option C: Kernel DRM rotation via modprobe params or udev rule

This is the hardest phase — needs investigation.

Verify: nix build .#nixosConfigurations.radiantwavekiosk-android-dev.config.system.build.toplevel

---

Phase 4: radiantwavekiosk-rpi-dev (RPi 5)

Files:

• Modify flake.nix: add ./kiosk-drm.nix to extraModules for radiantwavekiosk-rpi-dev
• Modify build-rpi.sh: update to build radiantwavekiosk-rpi-dev instead of radiantwavekiosk-rpi

RPi 5 uses VC4/V3D GPU driver — hardware.graphics.enable = true + nixos-raspberrypi.nixosModules.raspberry-pi-5.display-vc4 already handles this.

Verify: ./build-rpi.sh (builds SD card image)

---

Risks and Unknowns

1. SDL3 DRM backend maturity — Less commonly used than the Wayland backend. Needs testing on NUC (Intel i915) and RPi 5 (VC4/V3D) hardware.

2. Android rotation — wlr-randr won't work without Wayland. Needs an alternative rotation strategy.

3. Input device permissions — SDL3's DRM backend reads /dev/input/* directly. Need to verify input group is sufficient and udev rules don't block access.

4. Multi-GPU/multi-output — DRM/KMS needs to select the right connector. SDL3 handles this, but edge cases exist (e.g., multiple monitors).

5. Plymouth -> app handoff — Plymouth runs on DRM/KMS too. The handoff should work, but timing might differ without a Wayland compositor in between.

---

radiantwave Repo — No Changes Needed

The app doesn't directly use DRM/KMS APIs. SDL3 handles the DRM backend internally when SDL_VIDEODRIVER=drm is set. The Nix package doesn't need changes — SDL3 dynamically loads DRM libraries at runtime.

The only change is the environment variable in the kiosk startup script (SDL_VIDEODRIVER=drm vs wayland), which lives in kioskconfig.