Update cloud-init scripts and documentation for enhanced DNS management and provisioning steps</message>

<message>Modify the first-boot.sh script to include an additional step for managing screen brightness during the provisioning process. Update user-data.bootstrap to improve DNS configuration by ensuring NetworkManager manages /etc/resolv.conf correctly, and remove obsolete scripts related to systemd-resolved. Enhance documentation to reflect these changes and clarify the setup process for users, improving overall network boot functionality and user experience.
2026-03-06 14:45:23 +02:00
parent 8233304ee2
commit 0844adbcbe
22 changed files with 2021 additions and 86 deletions
--- a/emmc-provisioning/docs/DEVICE-DNS-DHCP-RESOLVCONF.md
+++ b/emmc-provisioning/docs/DEVICE-DNS-DHCP-RESOLVCONF.md
@@ -20,13 +20,13 @@ This document describes how to configure provisioned devices (e.g. Raspberry Pi

 ## What to change in cloud-init

-### Option A: user-data.bootstrap (systemd-resolved)
+### Option A: user-data.bootstrap (uses Option B for RPi OS)

 **File:** `cloud-init/user-data.bootstrap`

 - **manage_resolv_conf: false** — already set; cloud-init must not overwrite resolv.conf.
- **systemd-resolved** — runcmd enables/starts resolved and makes `/etc/resolv.conf` a symlink to `stub-resolv.conf`. Resolved gets DNS from NetworkManager (and from the hooks in write_files).
- **NetworkManager** — `99-use-resolved.conf` has `dns=systemd-resolved` and `rc-manager=unmanaged` so NM doesn’t write resolv.conf; resolved does.
+- **NetworkManager** — `99-resolv-dhcp.conf` has `rc-manager=symlink` so NM creates `/etc/resolv.conf` with DHCP DNS. RPi OS does not use systemd-resolved by default.
+- **runcmd** — removes static resolv.conf and restarts NM so it creates the symlink with DHCP option 6.
 - **Bootstrap script** — must **not** write `nameserver 8.8.8.8` (or any fixed server) into `/etc/resolv.conf`. Our `bootstrap.sh` no longer does that.

 No extra changes needed if you use `user-data.bootstrap` as-is; just ensure your bootstrap script does not touch resolv.conf.
--- a/emmc-provisioning/docs/LITE-WAYLAND-KIOSK-DEPLOYMENT.md
+++ b/emmc-provisioning/docs/LITE-WAYLAND-KIOSK-DEPLOYMENT.md
@@ -0,0 +1,280 @@
+# 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.
--- a/emmc-provisioning/docs/SCREEN-BRIGHTNESS-MANUAL-SETUP.md
+++ b/emmc-provisioning/docs/SCREEN-BRIGHTNESS-MANUAL-SETUP.md
@@ -0,0 +1,276 @@
+# Screen Brightness Service — Manual Setup on Existing Device
+
+This guide describes how to install and configure the **screen-brightness** daemon on an existing reTerminal DM (e.g. a device that was not provisioned with the first-boot flow that includes step 14). The daemon controls LCD backlight from the ambient light sensor and raises brightness when the buzzer is active (alarm), with behaviour aligned to bridge display regulations.
+
+**See also:** [SCREEN-BRIGHTNESS-REGULATIONS.md](SCREEN-BRIGHTNESS-REGULATIONS.md) for the regulatory references.
+
+---
+
+## 1. Prerequisites
+
+- **Hardware:** reTerminal DM (Raspberry Pi CM4-based) with built-in light sensor and buzzer.
+- **OS:** Raspberry Pi OS (or compatible) with:
+  - Python 3
+  - Sysfs nodes present (see [Verify hardware](#2-verify-hardware-below)).
+
+No extra Python packages are required (stdlib only).
+
+---
+
+## 2. Verify hardware
+
+On the device, confirm that the backlight, buzzer, and light sensor are available:
+
+```bash
+# Backlight (values 0–5)
+cat /sys/class/backlight/lcd_backlight/brightness
+cat /sys/class/backlight/lcd_backlight/max_brightness
+
+# Buzzer (0 = off, 1 = on)
+cat /sys/class/leds/usr-buzzer/brightness
+
+# Ambient light (lux)
+cat /sys/bus/iio/devices/iio:device0/in_illuminance_input
+```
+
+If any of these paths are missing, install the reTerminal DM drivers first (Seeed wiki: [reTerminal DM Getting Started](https://wiki.seeedstudio.com/reterminal-dm/)).
+
+---
+
+## 3. Install the service (manual copy)
+
+### 3.1 Create directories and copy files
+
+Run as **root** (or with `sudo`):
+
+```bash
+# Script
+install -m 755 screen-brightness.py /usr/local/bin/screen-brightness.py
+
+# Systemd unit
+install -m 644 screen-brightness.service /etc/systemd/system/screen-brightness.service
+
+# Optional: default config (skip if you already have vessel-specific /etc/screen-brightness.conf)
+install -m 644 screen-brightness.conf /etc/screen-brightness.conf
+```
+
+Use the files from this repo:
+
+- `emmc-provisioning/cloud-init/fileserver/screen-brightness.py`
+- `emmc-provisioning/cloud-init/fileserver/screen-brightness.service`
+- `emmc-provisioning/cloud-init/fileserver/screen-brightness.conf`
+
+Copy them to the device first (e.g. via SCP, USB stick, or the deployment script below), then run the `install` commands on the device.
+
+### 3.2 Runtime directory and tmpfiles
+
+Ensure the daemon’s runtime directory exists and is recreated after reboot:
+
+```bash
+mkdir -p /run/screen-brightness
+
+# Create tmpfiles.d rule so the directory exists after reboot
+cat > /etc/tmpfiles.d/screen-brightness.conf << 'EOF'
+d /run/screen-brightness 0755 root root -
+EOF
+```
+
+### 3.3 Enable and start
+
+```bash
+systemctl daemon-reload
+systemctl enable screen-brightness.service
+systemctl start screen-brightness.service
+```
+
+Check status and logs:
+
+```bash
+systemctl status screen-brightness.service
+journalctl -u screen-brightness.service -f
+```
+
+---
+
+## 4. Install using the deployment script
+
+A helper script can install or update the service from **either** a local directory (repo clone/USB) **or** a URL (e.g. your file server). The script lives in the repo at:
+
+`emmc-provisioning/scripts/deploy-screen-brightness-to-device.sh`
+
+### 4.1 On the device (files already on the device)
+
+If you have the three files in a directory on the reTerminal DM (e.g. copied from USB or repo):
+
+```bash
+cd /path/to/dir   # directory containing screen-brightness.py, .service, .conf
+sudo ./deploy-screen-brightness-to-device.sh
+```
+
+The script will install the files, create the tmpfiles.d rule, and start/enable the service. It will **not** overwrite an existing `/etc/screen-brightness.conf` (so vessel-specific tuning is preserved).
+
+### 4.2 On the device (download from URL)
+
+If your file server serves the three files (e.g. from the provisioning portal), pass the base URL as the **first argument** (recommended — works even when `sudo` does not preserve environment variables):
+
+```bash
+sudo ./deploy-screen-brightness-to-device.sh "http://file.server:5000/files"
+```
+
+Alternatively, if your `sudo` preserves the environment:
+
+```bash
+sudo -E BOOTSTRAP_URL="http://file.server:5000/files" ./deploy-screen-brightness-to-device.sh
+```
+
+The script will download `screen-brightness.py`, `screen-brightness.service`, and `screen-brightness.conf` from that base URL and show progress per file.
+
+### 4.3 From a host (deploy via SSH)
+
+From your laptop or build host, with the repo checked out and SSH access to the device:
+
+```bash
+cd /path/to/repo/emmc-provisioning/scripts
+./deploy-screen-brightness-to-device.sh root@192.168.1.100
+```
+
+The script will copy the files from `../cloud-init/fileserver/` and run the install steps over SSH.
+
+### 4.4 From a host via a jump server (bastion)
+
+If the reTerminal DM is only reachable through a jump host, set `SSH_JUMP_HOST` and pass the device as the first argument:
+
+```bash
+cd /path/to/repo/emmc-provisioning/scripts
+SSH_JUMP_HOST="user@jump.example.com" ./deploy-screen-brightness-to-device.sh pi@10.0.0.5
+```
+
+The script uses OpenSSH’s `-J` / `ProxyJump` so `ssh` and `scp` go through the jump host to the device.
+
+**Alternative:** put the jump in your SSH config so no env var is needed:
+
+```
+# ~/.ssh/config
+Host reterminal-guard
+  HostName 10.0.0.5
+  User pi
+  ProxyJump user@jump.example.com
+```
+
+Then run:
+
+```bash
+./deploy-screen-brightness-to-device.sh reterminal-guard
+```
+
+---
+
+## 5. Configuration
+
+- **Config file:** `/etc/screen-brightness.conf` (INI format, optional).  
+  If the file is missing, the daemon uses built-in defaults.
+- **Reload config without restart:**  
+  `sudo systemctl reload screen-brightness`
+- **Override (navigator preset):**  
+  - Force a fixed level (1–5):  
+    `echo 3 | sudo tee /run/screen-brightness/override`  
+  - Return to automatic (ambient + buzzer):  
+    `echo auto | sudo tee /run/screen-brightness/override`
+
+See comments in `screen-brightness.conf` for lux thresholds and level mapping (NIGHT / DUSK / DAY).
+
+### 5.1 Crew brightness overlay (manual control)
+
+To satisfy the requirement that the navigator can manually control brightness (MSC.191(79) §8.1.2), you can use the **brightness overlay**: a small panel that sits on top of the kiosk (Wayland layer-shell or X11) with buttons **1** **2** **3** **4** **5** and **Auto**.
+
+- **brightness-api.service** — HTTP API on `127.0.0.1:8765`. Accepts `POST /brightness` with `level=1|2|3|4|5|auto`. Runs as root and writes `/run/screen-brightness/override`.
+- **brightness-overlay.py** — Gtk3 overlay (same pattern as five-tap-close-chromium). Starts from session autostart; calls the API when a button is tapped.
+
+If step 14 installed them, the overlay appears at the **bottom-right** after login. To install manually on an existing device:
+
+```bash
+# API (run as root)
+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
+
+# Overlay (run as pi, autostart)
+install -m 755 brightness-overlay.py ~/brightness-overlay.py
+# Then add brightness-overlay.desktop to ~/.config/autostart/ (Exec path = your $HOME/brightness-overlay.py)
+```
+
+Dependencies: Python 3, PyGObject (Gtk3). On Wayland, `gir1.2-gtklayershell-0.1` for the overlay layer.
+
+---
+
+## 6. State and dashboard integration
+
+The daemon writes a state file for other services (e.g. your alarm dashboard):
+
+```bash
+cat /run/screen-brightness/state
+```
+
+Example:
+
+```
+mode=ALERT
+level=5
+lux=12
+buzzer=1
+override=0
+updated=1741266000
+```
+
+Your dashboard can read this to show current brightness mode or to drive a “night mode” indicator.
+
+---
+
+## 7. Testing buzzer and brightness
+
+To confirm that the screen goes to full brightness when the buzzer is active and stays up during cooldown, run a short beep test on the device:
+
+```bash
+# From the device (if you have the script in place)
+sudo ./test-buzzer-brightness.sh
+```
+
+If the script is not on the device, fetch and run it from your file server (replace with your portal URL):
+
+```bash
+curl -fsSL "http://10.130.60.141:5000/files/first-boot/test-buzzer-brightness.sh" -o /tmp/test-buzzer-brightness.sh
+chmod +x /tmp/test-buzzer-brightness.sh
+sudo /tmp/test-buzzer-brightness.sh
+```
+
+The script beeps four times. While it runs, the screen should go to maximum brightness (ALERT) and stay high for about 10 seconds after the last beep (COOLDOWN), then return to ambient level.
+
+---
+
+## 8. Troubleshooting
+
+| Symptom | Check |
+|--------|--------|
+| Service fails to start | `journalctl -u screen-brightness.service -n 50`; confirm sysfs paths exist (step 2). |
+| Brightness never changes | Verify light sensor: `cat /sys/bus/iio/devices/iio:device0/in_illuminance_input` (value should change when you shade the sensor). |
+| Buzzer does not raise brightness | 1) Ensure service is running: `systemctl status screen-brightness.service`. 2) Use `test-buzzer-brightness.sh` (it uses the buzzer’s `max_brightness`, often 255). 3) Confirm buzzer sysfs updates while ON: `cat /sys/class/leds/usr-buzzer/brightness` (non-zero means ON), then `cat /run/screen-brightness/state` (mode=ALERT / COOLDOWN). |
+| No logs from brightness service | Check that the unit is active: `systemctl is-active screen-brightness.service`. Then `journalctl -u screen-brightness.service -f` (follow). If the service exits, check `journalctl -u screen-brightness.service -n 50` for Python or path errors. |
+| Brightness overlay not visible | 1) **Start it now:** from a terminal on the device (VNC or local), run: `python3 /home/pi/brightness-overlay.py` (or `~/brightness-overlay.py`). The panel should appear bottom-right; any errors will show in the terminal. 2) **After deploy:** autostart runs at login — log out and log back in so the overlay starts (it uses a 6 s delay). 3) **API required:** ensure `systemctl status brightness-api.service` is active; the overlay calls 127.0.0.1:8765. 4) **Dependencies:** need PyGObject (Gtk3); on Wayland, `gir1.2-gtklayershell-0.1` for the layer. |
+| Config change not applied | Run `sudo systemctl reload screen-brightness` (or restart the service). |
+
+---
+
+## 9. File locations (reference)
+
+| Item | Path |
+|------|------|
+| Daemon script | `/usr/local/bin/screen-brightness.py` |
+| Systemd unit | `/etc/systemd/system/screen-brightness.service` |
+| Config | `/etc/screen-brightness.conf` |
+| Override (navigator) | `/run/screen-brightness/override` |
+| State (read-only) | `/run/screen-brightness/state` |
+| tmpfiles.d | `/etc/tmpfiles.d/screen-brightness.conf` |
+| Brightness API (crew control) | `/usr/local/bin/brightness-api.py` |
+| Brightness API unit | `/etc/systemd/system/brightness-api.service` |
+| Overlay script | `$HOME/brightness-overlay.py` |
+| Overlay autostart | `$HOME/.config/autostart/brightness-overlay.desktop` |
--- a/emmc-provisioning/docs/SCREEN-BRIGHTNESS-REGULATIONS.md
+++ b/emmc-provisioning/docs/SCREEN-BRIGHTNESS-REGULATIONS.md
@@ -0,0 +1,163 @@
+# Screen Brightness — Maritime Regulations and References
+
+This document summarises the international regulations and standards that apply to **display brightness and dimming** on ship bridges, and how the **screen-brightness** daemon on the reTerminal DM is aligned with them. It is intended for vessel operators, integrators, and auditors.
+
+---
+
+## 1. Overview
+
+Bridge equipment that presents navigation-related or alarm information on a display is subject to:
+
+- **IMO** (International Maritime Organization) resolutions, which set performance standards.
+- **IEC** (International Electrotechnical Commission) and **IHO** (International Hydrographic Organization) standards, which give technical and test requirements.
+
+The reTerminal DM screen-brightness daemon implements behaviour that satisfies the relevant clauses for:
+
+- Adjustable brightness that is **never extinguished** (“not to extinction”).
+- A **navigator-resettable** brightness/contrast preset (override).
+- **High luminous intensity** for alarm/alert states.
+- **Night mode** that does not degrade crew night vision.
+- **Three operating modes** (NIGHT / DUSK / DAY) consistent with ECDIS-type display practice.
+
+---
+
+## 2. IMO MSC.191(79) — Navigational displays
+
+**Full title:**  
+*Performance Standards for the Presentation of Navigation-Related Information on Shipborne Navigational Displays*
+
+**Adoption:** 6 December 2004  
+
+**Applicability:** Displays that present navigation-related information on the bridge (including ECDIS and other navigational displays). Often referenced for equipment installed after 1 July 2008.
+
+**Source (external):**  
+- [imorules.com – MSC.191(79)](https://www.imorules.com/MSCRES_191.79.html)  
+- IMO official: MSC.191(79) in the IMO Publications catalogue.
+
+### 2.1 §8.1 Display adjustment
+
+| Requirement | Text (summary) | Implementation in screen-brightness |
+|-------------|-----------------|-------------------------------------|
+| Adjustability | Contrast and brightness shall be adjustable as applicable to the display technology. | Brightness is controlled in steps 1–5 from ambient sensor and/or override. |
+| Dimming | The display shall be capable of being **dimmed**. | NIGHT and DUSK modes set low backlight levels (1–2). |
+| Legibility | The range of control shall allow the display to be **legible under all ambient light conditions**. | Lux thresholds map to levels 1–5 so the display remains usable from night to bright day. |
+| **Not to extinction** | Implicit in “dimmed” and “legible under all conditions”: the display must not be turned off. | **Level 0 is never used.** Minimum level is 1 (“not to extinction”). |
+
+### 2.2 §8.1.2 Preset / default
+
+| Requirement | Text (summary) | Implementation in screen-brightness |
+|-------------|-----------------|-------------------------------------|
+| Reset to preset | The navigator shall be able to **reset** contrast and/or brightness to a **preset or default condition**. | Override file: `echo <1–5> \| sudo tee /run/screen-brightness/override` sets a fixed level; `echo auto` restores automatic (ambient + buzzer) behaviour. |
+
+**Reference (section 8.1):**  
+- [imorules.com – 8.1 Display adjustment](https://www.imorules.com/GUID-6B14EB44-F913-4C8F-8E36-F74CE6E8E3DE.html)
+
+### 2.3 Position of the brightness control
+
+**MSC.191(79), MSC.302(87), IHO S-52, and IEC 62288 do not specify where the brightness (or contrast) control must be located on the screen or in the user interface.** They only require that:
+
+- Brightness be adjustable and dimmable.
+- The navigator be able to reset to a preset or default.
+
+So the **position of the brightness control** (e.g. bottom-right overlay icon on the reTerminal DM) is an **implementation and design choice**, not a regulatory requirement. Placement can follow human-factors or vessel-specific guidelines (e.g. readily accessible, non-intrusive) as long as the above requirements are met.
+
+---
+
+## 3. IMO MSC.302(87) — Bridge alert management
+
+**Full title:**  
+*Adoption of Performance Standards for Bridge Alert Management*
+
+**Adoption:** 17 May 2010  
+
+**Applicability:** Bridge Alert Management (BAM) and presentation of alerts on the bridge. Recommended for central alert management (CAM) and CAM human-machine interface (CAM-HMI) installed on or after 1 July 2014.
+
+**Source (external):**  
+- [imorules.com – MSC.302(87)](https://www.imorules.com/MSCRES_302.87.html)  
+- IMO official: MSC.302(87) PDF in IMO Knowledge Centre.
+
+### 3.1 Visual alarms and night vision
+
+| Requirement | Text (summary) | Implementation in screen-brightness |
+|-------------|-----------------|-------------------------------------|
+| Night vision | Visual alarms and indicators shall **not interfere with night vision**. | In ambient mode, NIGHT/DUSK use low levels (1–2); transitions are smooth (one step per poll) to avoid sudden bright flashes. |
+| Dimming not to extinction | **Dimming facilities** shall be incorporated, **though not to extinction**. | Same as MSC.191(79): level 0 is never used; minimum is level 1. |
+| High luminous intensity for alerts | Supplemental **visual indicators** (e.g. for alarms) shall be of **high luminous intensity**. | When the **buzzer** is ON (alarm), backlight is set to **level 5 (maximum)** immediately, with no smooth stepping. |
+| Persistence after alarm | Alerts must remain visible/audible long enough for crew response. | After the buzzer stops, brightness is held at level 5 for a **cooldown period** (default 10 s), then stepped down; duration is configurable in `/etc/screen-brightness.conf`. |
+
+**Reference:**  
+- IMO MSC.302(87) Annex — Performance Standards for Bridge Alert Management (Modules A–D).  
+- [imorules.com – MSC.302(87) Annex](https://www.imorules.com/MSCRES_302.87_ANN.html)
+
+---
+
+## 4. IHO S-52 and IEC 62288 — ECDIS and display presentation
+
+**IHO S-52** (International Hydrographic Organization) specifies chart content and **display aspects** for ECDIS, including colour and luminance behaviour. **IEC 62288** implements and tests these and related IMO requirements for shipborne navigational displays.
+
+### 4.1 Three colour / luminance modes
+
+| Mode | Typical use | Implementation in screen-brightness |
+|------|-------------|-------------------------------------|
+| **Day** | Bright ambient; high contrast. | DAY-DIM, DAY-NORMAL, DAY-BRIGHT (levels 3–5) by lux bands. |
+| **Dusk/Dawn** | Transition; reduced luminance. | DUSK mode → level 2. |
+| **Night** | Low luminance so as **not to affect the mariner’s night vision**. | NIGHT mode → level 1 (minimum). |
+
+**IHO S-52** (e.g. Edition 6.1.1):  
+- “The ambient lighting on the bridge varies between the extremes of bright sunlight … and night, when the **light emitted by the display has to be low enough that it does not affect the mariner's night vision**.”  
+- Three colour/luminance modes (day, dusk/dawn, night) are defined for ECDIS; the screen-brightness daemon provides a compatible **three-mode luminance framework** (NIGHT / DUSK / DAY-*).
+
+**IEC 62288** (e.g. IEC 62288:2021):  
+- General requirements, test methods, and required results for the **presentation of navigation-related information** on shipborne navigational displays.  
+- Supports IMO MSC.191(79) and MSC.302(87).  
+- Full luminance limits (e.g. numerical cd/m² for night) are in the purchased standard; the daemon’s “minimum level 1” and “never 0” satisfy the “dimmed but not to extinction” and “night vision” intent.
+
+**Sources (external):**  
+- IHO S-52 — Specifications for chart content and display aspects of ECDIS (IHO publication).  
+- [IEC 62288:2021](https://webstore.iec.ch/publication/64659) — Maritime navigation and radiocommunication equipment and systems – Presentation of navigation-related information on shipborne navigational displays.
+
+---
+
+## 5. Summary table — Regulation vs implementation
+
+| Regulation | Clause / topic | Daemon behaviour |
+|------------|----------------|------------------|
+| **MSC.191(79)** | §8.1.1 Brightness adjustable, dimmable | Levels 1–5 from ambient sensor; configurable lux→level mapping. |
+| **MSC.191(79)** | §8.1.1 Legible in all ambient conditions | NIGHT / DUSK / DAY-* modes with configurable lux thresholds. |
+| **MSC.191(79)** | §8.1.1 Not to extinction | Level **0 never used**; minimum level 1. |
+| **MSC.191(79)** | §8.1.2 Reset to preset | Override file: fixed level 1–5 or `auto`. |
+| **MSC.302(87)** | Visual alarms high luminance | Buzzer ON → **immediate** level 5. |
+| **MSC.302(87)** | Dimming not to extinction | Same as above; min level 1. |
+| **MSC.302(87)** | Night vision not degraded | NIGHT/DUSK low levels; smooth stepping on transitions. |
+| **MSC.302(87)** | Alert persistence | Cooldown (e.g. 10 s) at level 5 after buzzer stops. |
+| **IHO S-52 / IEC 62288** | Three modes (day / dusk / night) | NIGHT, DUSK, DAY-DIM, DAY-NORMAL, DAY-BRIGHT. |
+| **IHO S-52** | Night luminance low for night vision | NIGHT mode → level 1. |
+
+---
+
+## 6. Configuration and audit
+
+- **Config file:** `/etc/screen-brightness.conf` — lux thresholds, levels per mode, cooldown, hysteresis.  
+- **Override (preset):** `/run/screen-brightness/override` — navigator preset (1–5 or `auto`).  
+- **State (read-only):** `/run/screen-brightness/state` — current mode, level, lux, buzzer, override.  
+- **Reload:** `systemctl reload screen-brightness` (no restart).
+
+For vessel-specific tuning or audits, adjust thresholds and levels in `/etc/screen-brightness.conf` and document the chosen values and the fact that level 0 is never used.
+
+---
+
+## 7. References (URLs and documents)
+
+| Reference | Description | URL or source |
+|-----------|-------------|----------------|
+| IMO MSC.191(79) | Performance standards for presentation of navigation-related information on shipborne navigational displays | https://www.imorules.com/MSCRES_191.79.html |
+| IMO MSC.191(79) §8.1 | Display adjustment (brightness, dimming, preset) | https://www.imorules.com/GUID-6B14EB44-F913-4C8F-8E36-F74CE6E8E3DE.html |
+| IMO MSC.302(87) | Performance standards for Bridge Alert Management | https://www.imorules.com/MSCRES_302.87.html |
+| IMO MSC.302(87) Annex | BAM performance standards (Modules A–D) | https://www.imorules.com/MSCRES_302.87_ANN.html |
+| IHO S-52 | Specifications for chart content and display aspects of ECDIS (e.g. Ed. 6.1.1) | IHO publication; see https://iho.int |
+| IEC 62288 | Presentation of navigation-related information on shipborne navigational displays | IEC 62288:2021 (and amendments); https://webstore.iec.ch |
+| reTerminal DM wiki | Hardware interfaces (backlight, buzzer, light sensor) | https://wiki.seeedstudio.com/reterminal-dm/ |
+
+---
+
+*This document is for guidance only. For formal compliance, refer to the official IMO, IHO, and IEC publications and your flag state / classification society.*
--- a/emmc-provisioning/docs/SCREEN-BRIGHTNESS-SUMMARY.md
+++ b/emmc-provisioning/docs/SCREEN-BRIGHTNESS-SUMMARY.md
@@ -0,0 +1,62 @@
+# Screen Brightness Control — Summary
+
+Short overview of how the reTerminal DM brightness system works.
+
+---
+
+## What it does
+
+
+
+---
+
+## Components
+
+| Component | Role |
+|-----------|------|
+| **screen-brightness** (daemon) | Reads sensor and override, drives backlight and buzzer; writes `/run/screen-brightness/state`. |
+| **brightness-api** (HTTP) | Listens on `127.0.0.1:8765`. POST sets override (level 1–5 or auto); GET returns current state. |
+| **brightness-overlay** (UI) | Small icon in bottom-right of screen; click to expand/collapse panel with buttons 1–5 and Auto. Talks to the API. |
+
+---
+
+## Levels and modes
+
+- **Levels 1–5:** 1 = dimmest, 5 = brightest. Written to `/sys/class/backlight/lcd_backlight/brightness` (0 is never used).
+- **Auto:** Override file set to `auto` (or missing). Daemon uses ambient light to pick level.
+- **Manual:** Override file contains `1`–`5`. Daemon keeps that level until user switches back to Auto.
+
+Override file: `/run/screen-brightness/override`  
+State file (read-only): `/run/screen-brightness/state` (mode, level, lux, override=0|1).
+
+---
+
+## On-screen overlay
+
+- **Icon:** Brightness (sun) icon in the bottom-right corner; transparent when retracted.
+- **Click icon:** Panel expands with “Brightness”, buttons **1 2 3 4 5**, and **Auto**. Semi-transparent background behind the buttons.
+- **Active state:** The current level or Auto is highlighted so you can see which is active.
+- **Click again:** Panel retracts to icon only.
+
+Overlay uses the local API; if GtkLayerShell is available (Wayland), it stays on top of fullscreen apps.
+
+---
+
+## Services and boot
+
+- **screen-brightness.service** — Starts the daemon. `ExecStartPre` writes `auto` into the override file so every boot starts in Auto.
+- **brightness-api.service** — Starts the HTTP API (after `screen-brightness`).
+- **brightness-overlay** — Started from the user session (e.g. autostart) so it appears on the desktop.
+
+---
+
+## Quick reference
+
+| Action | How |
+|--------|-----|
+| Set level 3 | Overlay: expand → click **3**. Or: `echo 3 > /run/screen-brightness/override` (root). |
+| Set Auto | Overlay: expand → click **Auto**. Or: `echo auto > /run/screen-brightness/override`. |
+| Read state | `curl http://127.0.0.1:8765/state` or `cat /run/screen-brightness/state`. |
+| Config | `/etc/screen-brightness.conf` (optional); `systemctl reload screen-brightness` to apply. |
+
+For full setup and regulations, see [SCREEN-BRIGHTNESS-MANUAL-SETUP.md](SCREEN-BRIGHTNESS-MANUAL-SETUP.md) and [SCREEN-BRIGHTNESS-REGULATIONS.md](SCREEN-BRIGHTNESS-REGULATIONS.md).