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.
This commit is contained in:
nearxos
280
emmc-provisioning/docs/LITE-WAYLAND-KIOSK-DEPLOYMENT.md
Normal file
280
emmc-provisioning/docs/LITE-WAYLAND-KIOSK-DEPLOYMENT.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user