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](SCREEN-BRIGHTNESS-MANUAL-SETUP.md) — brightness daemon, API, and overlay installation.
- [SCREEN-BRIGHTNESS-SUMMARY.md](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](SCREEN-BRIGHTNESS-MANUAL-SETUP.md#2-verify-hardware)).
- **Base image:** Raspberry Pi OS **Lite** (64-bit recommended). Either:
  - Flash **Raspberry Pi OS Lite** from [raspberrypi.com/software](https://www.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](https://wiki.seeedstudio.com/reterminal-dm/)).

---

## 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):

```bash
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):

```bash
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](SCREEN-BRIGHTNESS-MANUAL-SETUP.md). From the repo or your file server:

```bash
# 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**:

```bash
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:

```bash
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:

```bash
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.

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

Contents (replace `KIOSK_URL` with your URL):

```bash
#!/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:

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

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

```bash
# 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:

```bash
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:

```bash
/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)).

---

## 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):

   ```bash
   # 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](https://wayland.freedesktop.org/docs/html/) — Wayland reference compositor.
- [Raspberry Pi OS](https://www.raspberrypi.com/software/) — Lite image.
- [Seeed reTerminal DM](https://wiki.seeedstudio.com/reterminal-dm/) — Hardware and drivers.
- [SCREEN-BRIGHTNESS-MANUAL-SETUP.md](SCREEN-BRIGHTNESS-MANUAL-SETUP.md) — Brightness daemon, API, and overlay installation and configuration.