Enhance first-boot script and documentation for eMMC provisioning: add structured logging, improve package installation process, and implement one-shot autostart for rotation and wallpaper setup. Update dashboard to manage portal file descriptions and enhance admin interface with new navigation links.

This commit is contained in:
nearxos
2026-02-20 08:42:53 +02:00
parent 9c533e95f9
commit 9098e820e6
22 changed files with 861 additions and 206 deletions

View File

@@ -0,0 +1,2 @@
[Seat:*]
user-session=plasmax11

View File

@@ -0,0 +1,3 @@
[greeter]
wallpaper=/usr/share/rpd-wallpaper/splash.png
wallpaper_mode=crop

View File

@@ -0,0 +1,13 @@
# Config files for first-boot (file server)
first-boot.sh downloads these from `FILE_SERVER` (e.g. `http://10.130.60.141:5000/files/first-boot`) and installs them to the paths below. Upload each file into the **first-boot** subfolder of portal-files (e.g. `/var/lib/cm4-provisioning/portal-files/first-boot/`).
| File on server | Destination on device |
|----------------|------------------------|
| 99-wallpaper.conf | /etc/lightdm/lightdm.conf.d/99-wallpaper.conf |
| 99-default-session.conf | /etc/lightdm/lightdm.conf.d/99-default-session.conf |
| kdeglobals | /home/pi/.config/kdeglobals |
| kwinrc | /home/pi/.config/kwinrc |
| maliit-keyboard.desktop | /home/pi/.config/autostart/maliit-keyboard.desktop |
| set-rotation-once.desktop | /home/pi/.config/autostart/set-rotation-once.desktop (with set-rotation-once.sh) |
| set-wallpaper-once.desktop | /home/pi/.config/autostart/set-wallpaper-once.desktop (with set-wallpaper-once.sh) |

View File

@@ -0,0 +1,2 @@
[General]
ForceFontDPI=120

View File

@@ -0,0 +1,4 @@
[Windows]
BorderlessMaximizedWindows=true
[Plugins]
touchpointsEnabled=true

View File

@@ -0,0 +1,5 @@
[Desktop Entry]
Type=Application
Name=Maliit Keyboard
Exec=maliit-keyboard -r
X-GNOME-Autostart-enabled=true

View File

@@ -0,0 +1,5 @@
[Desktop Entry]
Type=Application
Name=Set rotation once
Exec=/home/pi/set-rotation-once.sh
X-GNOME-Autostart-enabled=true

View File

@@ -0,0 +1,5 @@
[Desktop Entry]
Type=Application
Name=Set wallpaper once
Exec=/home/pi/set-wallpaper-once.sh
X-GNOME-Autostart-enabled=true

View File

@@ -0,0 +1,30 @@
# Files for the file server
first-boot.sh downloads from **`.../files/first-boot/`** (e.g. `http://10.130.60.141:5000/files/first-boot`). Put all first-boot assets in a **first-boot** subfolder of portal-files so provisioning works.
## Required files (host under `.../files/first-boot/`)
| File | Purpose |
|------|--------|
| **start-chromium.sh** | Chromium kiosk launcher (executable). |
| **chromium-kiosk.desktop** | Autostart entry for the kiosk. |
| **splash.png** | Boot splash + login + desktop wallpaper (single image). |
| **custom.plymouth** | Plymouth theme config (from `plymouth-custom/`). |
| **custom.script** | Plymouth script that displays splash.png (from `plymouth-custom/`). |
| **99-wallpaper.conf** | LightDM greeter wallpaper (from `config-files/`). |
| **99-default-session.conf** | LightDM default session plasmax11 (from `config-files/`). |
| **kdeglobals** | KDE font DPI (from `config-files/`). |
| **kwinrc** | KDE window/touch (from `config-files/`). |
| **maliit-keyboard.desktop** | Maliit on-screen keyboard autostart (from `config-files/`). |
| **set-rotation-once.sh** + **.desktop** | One-shot: DSI-1 rotation at first login. |
| **set-wallpaper-once.sh** + **.desktop** | One-shot: desktop wallpaper at first login. |
---
## Whats in this folder
- **plymouth-custom/splash.png** — Example splash image; host as `splash.png`.
- **plymouth-custom/custom.plymouth** — Plymouth theme definition; host as `custom.plymouth`.
- **plymouth-custom/custom.script** — Plymouth script that draws splash.png; host as `custom.script`.
- **lightdm/RPiSystem_dark.png** — Unused; only `splash.png` is used now.
- **set-rotation-once.sh** and **set-wallpaper-once.sh** live in `cloud-init/`; copy them into `portal-files/first-boot/` on the file server.

Binary file not shown.

After

Width:  |  Height:  |  Size: 460 KiB

View File

@@ -0,0 +1,8 @@
[Plymouth Theme]
Name=Custom Splash
Description=Custom boot splash screen
ModuleName=script
[script]
ImageDir=/usr/share/plymouth/themes/custom
ScriptFile=/usr/share/plymouth/themes/custom/custom.script

View File

@@ -0,0 +1,40 @@
screen_width = Window.GetWidth();
screen_height = Window.GetHeight();
theme_image = Image("splash.png");
image_width = theme_image.GetWidth();
image_height = theme_image.GetHeight();
scale_x = image_width / screen_width;
scale_y = image_height / screen_height;
if (scale_x > 1 || scale_y > 1)
{
if (scale_x > scale_y)
{
resized_image = theme_image.Scale(screen_width, image_height / scale_x);
image_x = 0;
image_y = (screen_height - ((image_height * screen_width) / image_width)) / 2;
}
else
{
resized_image = theme_image.Scale(image_width / scale_y, screen_height);
image_x = (screen_width - ((image_width * screen_height) / image_height)) / 2;
image_y = 0;
}
}
else
{
resized_image = theme_image.Scale(image_width, image_height);
image_x = (screen_width - image_width) / 2;
image_y = (screen_height - image_height) / 2;
}
if (Plymouth.GetMode() != "shutdown")
{
sprite = Sprite(resized_image);
sprite.SetPosition(image_x, image_y, -100);
}
fun message_callback(text) {
}

Binary file not shown.

After

Width:  |  Height:  |  Size: 205 KiB

View File

@@ -4,6 +4,22 @@ This script runs once on first boot via cloud-init (see `user-data-remote-gnss.e
---
## Structure (sections)
1. **Constants**`FILE_SERVER`, `PI_USER`, paths, log file.
2. **Logging** — All output teed to `/var/log/first-boot.log`.
3. **Helpers**`install_oneshot(name)` downloads `${name}.sh` from the file server and installs it as a one-shot autostart (runs once at pis first login, then deletes itself).
4. **Packages** — git, Chromium, wmctrl, SSH, KDE Plasma, kscreen, maliit, xinput-calibrator.
5. **Kiosk files** — Download `start-chromium.sh` and `chromium-kiosk.desktop`; create autostart dir.
6. **Boot splash and wallpaper** — Download `splash.png`; install Plymouth custom theme; copy image for LightDM and desktop.
7. **LightDM** — Download `99-default-session.conf` and `99-wallpaper.conf` to `/etc/lightdm/lightdm.conf.d/`.
8. **KDE + Maliit** — Download `kdeglobals`, `kwinrc`, `maliit-keyboard.desktop` from file server to pis `.config` and autostart.
9. **reTerminal DM drivers** — Seeed repo clone and `reTerminal.sh`.
10. **One-shots** — Download `set-rotation-once.sh` + `.desktop` and `set-wallpaper-once.sh` + `.desktop` from file server.
11. **Reboot.**
---
## Script header and environment
- **`set -e`** — Exit immediately if any command fails.
@@ -11,6 +27,16 @@ This script runs once on first boot via cloud-init (see `user-data-remote-gnss.e
---
## Logging
All script output (stdout and stderr) is appended to **`/var/log/first-boot.log`** so you can review what ran after first boot (e.g. over SSH: `cat /var/log/first-boot.log`).
- **`LOGFILE`** — Path of the log file (`/var/log/first-boot.log`).
- **`log "..."`** — Prints a timestamped line (ISO format); used for section headers.
- **`exec > >(tee -a "$LOGFILE") 2>&1`** — Sends all subsequent stdout and stderr to both the console and the log file.
---
## Packages
Installs the software needed for the rest of the script and for the kiosk:
@@ -22,6 +48,7 @@ Installs the software needed for the rest of the script and for the kiosk:
| **wmctrl** | Window control; used to force Chromium into fullscreen. |
| **openssh-server** | SSH access (often also enabled in user-data). |
| **kde-plasma-desktop** | KDE Plasma desktop (X11 session used for Chromium). |
| **kscreen** | KDE display control; provides `kscreen-doctor` for screen rotation (same as GUI “Right”). |
| **maliit-keyboard** | On-screen keyboard for touch input. |
| **xinput-calibrator** | Touchscreen calibration (optional; run manually if needed). |
@@ -35,9 +62,9 @@ Creates `/home/pi/.config/autostart` so that `.desktop` files placed there are s
## Chromium kiosk files (from file server)
Does **not** create the kiosk files locally; it downloads them from your file server:
Downloads from `FILE_SERVER` (no local creation):
- **`FILE_SERVER`** — Base URL (default: `http://10.130.60.141:5000/files`). Change this if your server is elsewhere.
- **`FILE_SERVER`** — Base URL for first-boot assets (default: `http://10.130.60.141:5000/files/first-boot`). All first-boot files are served from a **first-boot** subfolder on the file server. Change this if your server or path is different.
- **`start-chromium.sh`** — Downloaded to `/home/pi/start-chromium.sh`, made executable (755), owned by `pi`. This script waits for the desktop, starts Chromium in kiosk mode (e.g. `--app=...`), and uses `wmctrl` to force fullscreen.
- **`chromium-kiosk.desktop`** — Downloaded to `/home/pi/.config/autostart/chromium-kiosk.desktop`, mode 644, owned by `pi`. This autostart entry runs `start-chromium.sh` when `pi` logs in.
@@ -45,6 +72,16 @@ Ensure the `.desktop` file on the server has `Exec=/home/pi/start-chromium.sh` (
---
## Boot splash and wallpaper (single image from file server)
A **single image** (`splash.png`) is used for the boot splash, login screen, and desktop wallpaper. Host it at **`${FILE_SERVER}/splash.png`** (e.g. `http://10.130.60.141:5000/files/splash.png`).
- **Plymouth (boot splash):** Downloads `splash.png`, `custom.plymouth`, and `custom.script` from the file server → installs to `/usr/share/plymouth/themes/custom/` → sets `Theme=custom` in `/etc/plymouth/plymouthd.conf` → runs `update-initramfs -u`. If any download fails, logs a warning and continues.
- **LightDM (login screen):** Copies the same image to `/usr/share/rpd-wallpaper/splash.png` and writes `/etc/lightdm/lightdm.conf.d/99-wallpaper.conf` with `wallpaper=...` and `wallpaper_mode=crop`.
- **Desktop wallpaper:** A one-shot autostart runs when **pi** first logs in and runs `plasma-apply-wallpaperimage /usr/share/rpd-wallpaper/splash.png`. The script then deletes itself. If `plasma-apply-wallpaperimage` is not installed, the step no-ops and the one-shot still removes itself.
---
## KDE Plasma: default session (X11)
Writes `/etc/lightdm/lightdm.conf.d/99-default-session.conf` so the display manager (LightDM) uses the **Plasma X11** session (`plasmax11`) instead of Wayland. Chromium kiosk is configured for X11, so this is required for it to run correctly.
@@ -92,14 +129,26 @@ These changes take effect after a reboot.
---
## Screen rotation (portrait → landscape, “Right”)
The reTerminal DM default is portrait. Rotation is set the **same way as in the GUI** (Display settings → Orientation → Right), using KDEs **kscreen-doctor**, so nothing is written to `/boot/firmware/config.txt`.
- **One-shot autostart** — A small script runs once when user `pi` first logs into the graphical session:
- **`/home/pi/set-rotation-once.sh`** — Waits 5 seconds, then runs `kscreen-doctor output.DSI-1.rotation.right` (only the reTerminal DM DSI-1 display; no other screen is used).
- **`/home/pi/.config/autostart/set-rotation-once.desktop`** — Autostart entry that runs the script. Both the script and this desktop file **delete themselves** after a successful run, so rotation is applied only once.
- **Effect** — Same as choosing “Right” in System Settings → Display → Orientation. Rotation applies after the first login; no reboot needed for rotation (only for the Seeed drivers).
---
## Reboot
Runs **`reboot`** so the kernel and display stack load the new Seeed drivers. After reboot, the screen and touch should work, and the next login as `pi` will start the Chromium kiosk and Maliit via the autostart entries.
Runs **`reboot`** so the kernel and display stack load the new Seeed drivers. After reboot, the screen and touch work; on **pi**s first login the one-shot sets rotation to “Right” (landscape), and the Chromium kiosk and Maliit start via autostart.
---
## Customisation
- **File server** — Edit `FILE_SERVER` if your `start-chromium.sh` and `chromium-kiosk.desktop` are served from another host/port.
- **File server** — Edit `FILE_SERVER` if your assets are served from another host/port. Host all files listed in **`files-from-guard/README.md`** and **`config-files/README.md`** (kiosk, splash, Plymouth, LightDM, KDE, Maliit, one-shots and their .desktop files).
- **Kiosk URL** — The URL Chromium opens is defined in `start-chromium.sh` on your file server (e.g. `--app=http://127.0.0.1:8080`); change it there.
- **User** — If you use a user other than `pi`, replace `pi` in this script and in the files on the file server (paths and ownership).
- **Screen rotation** — The one-shot runs `kscreen-doctor output.DSI-1.rotation.right`. To use another orientation, edit the script and change `rotation.right` to `rotation.left`, `rotation.inverted`, or `rotation.none`.

View File

@@ -1,81 +1,96 @@
#!/bin/bash
# First-boot script: install packages, Chromium kiosk, KDE Plasma + touch.
# Intended to be downloaded and run by cloud-init (see user-data-remote-gnss.example).
# Run as root.
# First-boot: packages, Chromium kiosk, KDE Plasma + touch, reTerminal DM drivers.
# Run by cloud-init (user-data-remote-gnss.example). Run as root.
set -e
export DEBIAN_FRONTEND=noninteractive
# Packages
# --- Constants ---
# All first-boot assets live in portal-files/first-boot/ on the file server.
FILE_SERVER="http://10.130.60.141:5000/files/first-boot"
PI_USER="pi"
PI_HOME="/home/$PI_USER"
AUTOSTART="$PI_HOME/.config/autostart"
LOGFILE="/var/log/first-boot.log"
PLYMOUTH_DIR="/usr/share/plymouth/themes/custom"
WALLPAPER_PATH="/usr/share/rpd-wallpaper/splash.png"
# --- Logging ---
log() { echo "[$(date -Iseconds)] $*"; }
exec > >(tee -a "$LOGFILE") 2>&1
log "=== first-boot.sh started ==="
# --- Helpers ---
# Download script + .desktop from FILE_SERVER and install as one-shot autostart (runs once at pi's first login, then deletes itself).
install_oneshot() {
local name="$1"
log "--- Installing one-shot: $name ---"
curl -fsSL "${FILE_SERVER}/${name}.sh" -o "$PI_HOME/${name}.sh" || { log "WARNING: Could not download ${name}.sh"; return 1; }
curl -fsSL "${FILE_SERVER}/${name}.desktop" -o "$AUTOSTART/${name}.desktop" || { log "WARNING: Could not download ${name}.desktop"; return 1; }
chmod 755 "$PI_HOME/${name}.sh" && chmod 644 "$AUTOSTART/${name}.desktop"
chown "$PI_USER:$PI_USER" "$PI_HOME/${name}.sh" "$AUTOSTART/${name}.desktop"
}
# --- 1. Packages ---
log "--- Installing packages ---"
apt-get update -qq
apt-get install -y -qq \
git \
chromium-browser \
wmctrl \
openssh-server \
kde-plasma-desktop \
maliit-keyboard \
xinput-calibrator
apt-get install -y -qq git chromium-browser wmctrl openssh-server \
kde-plasma-desktop kscreen maliit-keyboard xinput-calibrator
# Autostart dir for user pi
mkdir -p /home/pi/.config/autostart
# --- 2. Dirs and kiosk files from file server ---
log "--- Kiosk files ---"
mkdir -p "$AUTOSTART"
curl -fsSL "${FILE_SERVER}/start-chromium.sh" -o "$PI_HOME/start-chromium.sh"
curl -fsSL "${FILE_SERVER}/chromium-kiosk.desktop" -o "$AUTOSTART/chromium-kiosk.desktop"
chmod 755 "$PI_HOME/start-chromium.sh" && chmod 644 "$AUTOSTART/chromium-kiosk.desktop"
chown -R "$PI_USER:$PI_USER" "$PI_HOME/start-chromium.sh" "$AUTOSTART/chromium-kiosk.desktop"
# Chromium kiosk files from file server
FILE_SERVER="http://10.130.60.141:5000/files"
curl -fsSL "${FILE_SERVER}/start-chromium.sh" -o /home/pi/start-chromium.sh
chmod 755 /home/pi/start-chromium.sh
chown pi:pi /home/pi/start-chromium.sh
curl -fsSL "${FILE_SERVER}/chromium-kiosk.desktop" -o /home/pi/.config/autostart/chromium-kiosk.desktop
chmod 644 /home/pi/.config/autostart/chromium-kiosk.desktop
chown pi:pi /home/pi/.config/autostart/chromium-kiosk.desktop
# --- 3. Boot splash and wallpaper (splash.png + Plymouth theme from file server) ---
log "--- Boot splash and wallpaper ---"
mkdir -p "$PLYMOUTH_DIR" /usr/share/rpd-wallpaper
if curl -fsSL "${FILE_SERVER}/splash.png" -o "$PLYMOUTH_DIR/splash.png"; then
cp "$PLYMOUTH_DIR/splash.png" "$WALLPAPER_PATH"
chmod 644 "$PLYMOUTH_DIR/splash.png" "$WALLPAPER_PATH"
if curl -fsSL "${FILE_SERVER}/custom.plymouth" -o "$PLYMOUTH_DIR/custom.plymouth" \
&& curl -fsSL "${FILE_SERVER}/custom.script" -o "$PLYMOUTH_DIR/custom.script"; then
chmod 644 "$PLYMOUTH_DIR/custom.plymouth" "$PLYMOUTH_DIR/custom.script"
else
log "WARNING: Could not download custom.plymouth/custom.script; boot splash theme may be incomplete"
fi
grep -q '^Theme=custom' /etc/plymouth/plymouthd.conf 2>/dev/null || printf '%s\n' '[Daemon]' 'Theme=custom' >> /etc/plymouth/plymouthd.conf
update-initramfs -u -k all 2>/dev/null || true
mkdir -p /etc/lightdm/lightdm.conf.d
curl -fsSL "${FILE_SERVER}/99-wallpaper.conf" -o /etc/lightdm/lightdm.conf.d/99-wallpaper.conf 2>/dev/null || log "WARNING: Could not download 99-wallpaper.conf"
log "Splash and wallpaper set from file server"
else
log "WARNING: Could not download splash.png"
fi
# KDE Plasma: default session (X11 for Chromium)
# --- 4. LightDM: KDE Plasma X11 session + configs from file server ---
log "--- LightDM session ---"
mkdir -p /etc/lightdm/lightdm.conf.d
cat > /etc/lightdm/lightdm.conf.d/99-default-session.conf << 'LIGHTDM'
[Seat:*]
user-session=plasmax11
LIGHTDM
curl -fsSL "${FILE_SERVER}/99-default-session.conf" -o /etc/lightdm/lightdm.conf.d/99-default-session.conf 2>/dev/null || log "WARNING: Could not download 99-default-session.conf"
# KDE touch-friendly
cat > /home/pi/.config/kdeglobals << 'KDE'
[General]
ForceFontDPI=120
KDE
chown pi:pi /home/pi/.config/kdeglobals
chmod 644 /home/pi/.config/kdeglobals
cat > /home/pi/.config/kwinrc << 'KWIN'
[Windows]
BorderlessMaximizedWindows=true
[Plugins]
touchpointsEnabled=true
KWIN
chown pi:pi /home/pi/.config/kwinrc
chmod 644 /home/pi/.config/kwinrc
# On-screen keyboard (maliit)
cat > /home/pi/.config/autostart/maliit-keyboard.desktop << 'MALIIT'
[Desktop Entry]
Type=Application
Name=Maliit Keyboard
Exec=maliit-keyboard -r
X-GNOME-Autostart-enabled=true
MALIIT
chown pi:pi /home/pi/.config/autostart/maliit-keyboard.desktop
chmod 644 /home/pi/.config/autostart/maliit-keyboard.desktop
# Ownership for all of pi's config
chown -R pi:pi /home/pi/.config
# Set KDE Plasma (X11) as default session
# --- 5. KDE touch-friendly + Maliit (from file server) ---
log "--- KDE and Maliit ---"
mkdir -p "$AUTOSTART" "$PI_HOME/.config"
curl -fsSL "${FILE_SERVER}/kdeglobals" -o "$PI_HOME/.config/kdeglobals" 2>/dev/null || log "WARNING: Could not download kdeglobals"
curl -fsSL "${FILE_SERVER}/kwinrc" -o "$PI_HOME/.config/kwinrc" 2>/dev/null || log "WARNING: Could not download kwinrc"
curl -fsSL "${FILE_SERVER}/maliit-keyboard.desktop" -o "$AUTOSTART/maliit-keyboard.desktop" 2>/dev/null || log "WARNING: Could not download maliit-keyboard.desktop"
chown -R "$PI_USER:$PI_USER" "$PI_HOME/.config"
update-alternatives --set x-session-manager /usr/bin/startplasma-x11 2>/dev/null || true
# reTerminal DM: install Seeed display/touch drivers (screen will work after reboot)
# --- 6. reTerminal DM drivers (Seeed) ---
log "--- reTerminal DM drivers ---"
REPO_DIR="/tmp/seeed-linux-dtoverlays"
git clone --depth 1 https://github.com/Seeed-Studio/seeed-linux-dtoverlays "$REPO_DIR"
"$REPO_DIR/scripts/reTerminal.sh" --device reTerminal-DM
rm -rf "$REPO_DIR"
# Reboot so display and touch work
# --- 7. One-shots (rotation + wallpaper at first login) ---
install_oneshot set-rotation-once || true
install_oneshot set-wallpaper-once || true
# --- 8. Reboot ---
log "=== first-boot.sh finished, rebooting ==="
reboot

View File

@@ -0,0 +1,40 @@
screen_width = Window.GetWidth();
screen_height = Window.GetHeight();
theme_image = Image("splash.png");
image_width = theme_image.GetWidth();
image_height = theme_image.GetHeight();
scale_x = image_width / screen_width;
scale_y = image_height / screen_height;
if (scale_x > 1 || scale_y > 1)
{
if (scale_x > scale_y)
{
resized_image = theme_image.Scale(screen_width, image_height / scale_x);
image_x = 0;
image_y = (screen_height - ((image_height * screen_width) / image_width)) / 2;
}
else
{
resized_image = theme_image.Scale(image_width / scale_y, screen_height);
image_x = (screen_width - ((image_width * screen_height) / image_height)) / 2;
image_y = 0;
}
}
else
{
resized_image = theme_image.Scale(image_width, image_height);
image_x = (screen_width - image_width) / 2;
image_y = (screen_height - image_height) / 2;
}
if (Plymouth.GetMode() != "shutdown")
{
sprite = Sprite(resized_image);
sprite.SetPosition(image_x, image_y, -100);
}
fun message_callback(text) {
}

View File

@@ -0,0 +1,6 @@
#!/bin/bash
# One-shot: set DSI-1 (reTerminal DM) rotation to Right, then remove self. Runs as user pi at first login.
export DISPLAY=:0
sleep 5
kscreen-doctor output.DSI-1.rotation.right
rm -f /home/pi/.config/autostart/set-rotation-once.desktop /home/pi/set-rotation-once.sh

View File

@@ -0,0 +1,7 @@
#!/bin/bash
# One-shot: set desktop wallpaper to splash image, then remove self. Runs as user pi at first login.
export DISPLAY=:0
sleep 8
WALLPAPER="/usr/share/rpd-wallpaper/splash.png"
[[ -f "$WALLPAPER" ]] && plasma-apply-wallpaperimage "$WALLPAPER" 2>/dev/null || true
rm -f /home/pi/.config/autostart/set-wallpaper-once.desktop /home/pi/set-wallpaper-once.sh