reterminal-dm4/emmc-provisioning/docs/LITE-WAYLAND-KIOSK-DEPLOYMENT.md

Deploying Lite + Wayland Kiosk on reTerminal DM

This guide describes how to deploy a minimal kiosk on the reTerminal DM (Raspberry Pi CM4-based) using Raspberry Pi OS Lite plus a Wayland compositor (no full PIXEL desktop). The result is a device that boots to Chromium in kiosk mode with your brightness overlay on top; if Chromium exits, you can relaunch it so the user has no other UI to access.

See also:

• SCREEN-BRIGHTNESS-MANUAL-SETUP.md — brightness daemon, API, and overlay installation.
• SCREEN-BRIGHTNESS-SUMMARY.md — overview of the brightness system.

---

1. Overview

Component	Role
Raspberry Pi OS Lite	Base OS; no PIXEL, no full desktop.
Wayland compositor (Weston)	Minimal display server; runs Chromium and the brightness overlay.
Chromium	Kiosk browser (fullscreen, single URL).
screen-brightness + brightness-api	System services; backlight and HTTP API (unchanged).
brightness-overlay	GTK + GtkLayerShell; stays on top of Chromium on Wayland.

Benefits of Lite + Wayland (vs Lite + X11):

• Brightness overlay uses GtkLayerShell natively, so it stays above fullscreen Chromium without window-manager hacks.
• No full desktop; fewer packages and a smaller attack surface.
• Wayland’s input and security model.

---

2. Prerequisites

• Hardware: reTerminal DM (CM4) with display, and (for brightness) backlight, buzzer, and light sensor (see SCREEN-BRIGHTNESS-MANUAL-SETUP.md).
• Base image: Raspberry Pi OS Lite (64-bit recommended). Either:
  • Flash Raspberry Pi OS Lite from raspberrypi.com/software, or
  • Start from an existing full OS and remove the desktop (more work; starting from Lite is simpler).
• Network: Device can reach the internet (or your mirror) for apt.
• reTerminal DM drivers: Installed so /sys/class/backlight/lcd_backlight and IIO light sensor exist (Seeed reTerminal DM wiki).

---

3. Install base system (Lite)

If you are not already on Lite:

1. Download Raspberry Pi OS Lite (e.g. 64-bit) and write it to the eMMC/SD as usual.
2. Boot, expand filesystem if needed, set hostname/locale, and ensure the reTerminal DM kernel/drivers are installed (e.g. from Seeed’s repo or your image).
3. (Optional) Configure cloud-init or your first-boot flow so new images get the same base.

---

4. Install Wayland and Weston

On the device (or in your image build):

sudo apt-get update
sudo apt-get install -y \
  weston \
  chromium-browser \
  xwayland

• weston — Reference Wayland compositor; suitable for kiosks and supports layer-shell (used by the brightness overlay).
• chromium-browser — Use the Raspberry Pi OS / Debian package so it runs natively on Wayland when WAYLAND_DISPLAY is set.
• xwayland — Optional; only needed if you have X11-only apps.

Verify Weston runs (for a quick test, start a temporary session):

weston --tty=1
# You should see a Weston desktop. Exit with Ctrl+Alt+Backspace or by killing weston.

---

5. Install brightness stack (daemon + API + overlay)

Install the screen-brightness daemon and the brightness API as system services (they do not require a desktop). Then install the overlay so it can be started from the Weston session.

5.1 Daemon and API (systemd)

Use the same procedure as SCREEN-BRIGHTNESS-MANUAL-SETUP.md. From the repo or your file server:

# Option A: deployment script (from device, with files present or via URL)
sudo ./deploy-screen-brightness-to-device.sh
# Or: sudo ./deploy-screen-brightness-to-device.sh "http://your-fileserver:5000/files"

# Option B: manual install (see SCREEN-BRIGHTNESS-MANUAL-SETUP.md)
sudo install -m 755 screen-brightness.py /usr/local/bin/
sudo install -m 644 screen-brightness.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now screen-brightness.service

Then install the brightness API:

sudo install -m 755 brightness-api.py /usr/local/bin/
sudo install -m 644 brightness-api.service /etc/systemd/system/
sudo systemctl daemon-reload && sudo systemctl enable --now brightness-api.service

Confirm both are running:

systemctl status screen-brightness.service brightness-api.service
curl -s http://127.0.0.1:8765/state

5.2 Overlay (session app)

Install the overlay binary and its Wayland layer-shell dependency:

sudo apt-get install -y gir1.2-gtklayershell-0.1
sudo install -m 755 brightness-overlay.py /usr/local/bin/brightness-overlay.py

The overlay will be started by the Weston session script (below); no desktop autostart is needed.

---

6. Weston session: Chromium kiosk + overlay

Create a session that starts Weston with a custom script that launches Chromium in kiosk mode and the brightness overlay. When Chromium exits, you can either leave the session as-is or relaunch Chromium so the user cannot use anything else.

6.1 Kiosk URL and Chromium flags

Choose the URL your kiosk should open (e.g. your bridge or portal). Example:

• https://your-portal.example.com/
• Or a local page: file:///usr/share/kiosk/index.html

Chromium flags used here:

• --kiosk — Fullscreen, no browser chrome.
• --noerrdialogs — No error dialogs.
• --disable-infobars — No "Chrome is being controlled" bar.
• --no-first-run — Skip first-run experience.
• --disable-session-crashed-bubble — No "Restore pages?".
• --start-fullscreen
• Optional: --autoplay-policy=no-user-gesture-required if you need autoplay.

6.2 Weston startup script

Create a script that Weston will run as the session. It starts the overlay and Chromium; optionally restarts Chromium when it exits.

sudo install -d /usr/local/share/weston
sudo nano /usr/local/share/weston/kiosk-session.sh

Contents (replace KIOSK_URL with your URL):

#!/bin/bash
# Weston session: brightness overlay + Chromium kiosk.
# Run in Weston's compositor process so WAYLAND_DISPLAY is set.

KIOSK_URL="${KIOSK_URL:-https://example.com/}"

# Start overlay (uses GtkLayerShell; stays on top)
/usr/local/bin/brightness-overlay.py &
OVERLAY_PID=$!

# Optional: restart Chromium when it exits (user cannot escape to desktop)
while true; do
  chromium-browser \
    --kiosk \
    --noerrdialogs \
    --disable-infobars \
    --no-first-run \
    --disable-session-crashed-bubble \
    --disable-restore-session-state \
    --start-fullscreen \
    "$KIOSK_URL"
  sleep 2
done

# If not using the loop, just run chromium-browser once (user sees Weston when it closes).

Make it executable:

sudo chmod +x /usr/local/share/weston/kiosk-session.sh

Set the URL (e.g. via environment or by editing the script):

# Example: set default URL
echo 'KIOSK_URL="https://your-portal.example.com/"' | sudo tee /etc/default/weston-kiosk
# Then in kiosk-session.sh, source it: . /etc/default/weston-kiosk 2>/dev/null || true

6.3 Launch Weston with the session script

You need Weston to start with your script instead of the default shell. Options:

Option A — Weston and shell (common):
Start Weston so it runs a shell that runs your script:

weston -- -- /usr/local/share/weston/kiosk-session.sh

Option B — systemd user or getty replacement:
Create a systemd service that runs on the console (e.g. tty1) and executes:

/usr/bin/weston --tty=1 -- -- /usr/local/share/weston/kiosk-session.sh

That way the kiosk starts automatically at boot (see Autologin and starting Weston at boot).

---

7. Autologin and starting Weston at boot

To have the device boot straight into the kiosk (no login):

1. Autologin — Configure getty or your login manager so the kiosk user is logged in on tty1 (e.g. Raspberry Pi OS "Auto login" or getty@tty1 override with ExecStart=-/sbin/agetty --autologin pi --noclear %I $TERM).

2. Run Weston from the autologin shell — In the kiosk user's .bash_profile or .profile, start Weston only when on the console (so you don't start a second session over SSH):

   # In ~/.profile or ~/.bash_profile (for user e.g. pi)
   if [ -z "$WAYLAND_DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
     exec /usr/bin/weston --tty=1 -- -- /usr/local/share/weston/kiosk-session.sh
   fi
   

   Then reboot; the kiosk should start after autologin.

Alternatively, use a systemd service that runs on boot and starts Weston on tty1 (replacing the getty for tty1). That avoids depending on shell profile and gives a single place to manage the kiosk.

---

8. Weston background (optional)

Weston can show a background image or colour. It is visible when Chromium is not fullscreen (e.g. at session start, or if Chromium exits and you are not auto-restarting it).

Configure in weston.ini (e.g. ~/.config/weston.ini or /etc/xdg/weston/weston.ini). In the [shell] section:

• Solid colour: background-color=0xff002244 (ARGB hex)
• Image: background-image=/path/to/your/wallpaper.png

---

9. Summary checklist

Step	Action
1	Use Raspberry Pi OS Lite (or convert to it).
2	Install reTerminal DM drivers (backlight, sensor, buzzer).
3	Install weston, chromium-browser, and (for overlay) gir1.2-gtklayershell-0.1.
4	Install screen-brightness and brightness-api as systemd services.
5	Install brightness-overlay.py and start it from the Weston session script.
6	Create kiosk-session.sh that starts overlay + Chromium (with optional Chromium restart loop).
7	Start Weston at boot (autologin + .profile or systemd) with kiosk-session.sh.

After this, the device runs Lite + Wayland with no full GUI, only Chromium in kiosk mode and the brightness overlay on top. Your existing screen brightness control (daemon + API + overlay) continues to work; the overlay uses GtkLayerShell so it stays above Chromium.

---

10. Optional: hardening

• Restrict TTYs — Disable or limit getty on other TTYs so users cannot switch to a shell (e.g. mask getty@tty2 … getty@tty6 or restrict access).
• Kiosk user — Use a dedicated user (e.g. kiosk) with minimal privileges and no password or a random one; autologin that user on tty1.
• Read-only root — For maximum lock-down, consider a read-only root filesystem and overlayfs for temporary writes (document separately).
• Network — Restrict outbound traffic if the kiosk only needs to reach specific hosts.

---

11. References

• Weston — Wayland reference compositor.
• Raspberry Pi OS — Lite image.
• Seeed reTerminal DM — Hardware and drivers.
• SCREEN-BRIGHTNESS-MANUAL-SETUP.md — Brightness daemon, API, and overlay installation and configuration.