# first-boot.sh — Documentation

This script runs once on first boot via cloud-init (see `user-data-remote-gnss.example`). It installs packages, configures a Chromium kiosk with KDE Plasma and touch support, and installs the reTerminal DM display/touch drivers. It must run as **root**.

---

## Script header and environment

- **`set -e`** — Exit immediately if any command fails.
- **`DEBIAN_FRONTEND=noninteractive`** — Prevents apt from asking questions (assumes default or automatic answers).

---

## Packages

Installs the software needed for the rest of the script and for the kiosk:

| Package | Purpose |
|--------|---------|
| **git** | Clone the Seeed Linux DTOverlays repo for reTerminal DM drivers. |
| **chromium-browser** | Full-screen kiosk browser. |
| **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). |
| **maliit-keyboard** | On-screen keyboard for touch input. |
| **xinput-calibrator** | Touchscreen calibration (optional; run manually if needed). |

---

## Autostart directory

Creates `/home/pi/.config/autostart` so that `.desktop` files placed there are started when user `pi` logs into the graphical session.

---

## Chromium kiosk files (from file server)

Does **not** create the kiosk files locally; it downloads them from your file server:

- **`FILE_SERVER`** — Base URL (default: `http://10.130.60.141:5000/files`). Change this if your server is elsewhere.
- **`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.

Ensure the `.desktop` file on the server has `Exec=/home/pi/start-chromium.sh` (or the path you use on the device).

---

## 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.

---

## KDE touch-friendly settings

Two config files for user `pi` to improve touch and window behaviour:

- **`/home/pi/.config/kdeglobals`** — `ForceFontDPI=120` for larger, more readable UI on the small screen.
- **`/home/pi/.config/kwinrc`** — `BorderlessMaximizedWindows=true` and `touchpointsEnabled=true` for better touch and fullscreen behaviour.

Both are owned by `pi:pi` with mode 644.

---

## On-screen keyboard (Maliit)

Creates `/home/pi/.config/autostart/maliit-keyboard.desktop` so that **Maliit** (`maliit-keyboard -r`) starts when `pi` logs in. This gives an on-screen keyboard for touch-only use.

---

## Ownership for pi’s config

Runs `chown -R pi:pi /home/pi/.config` so all files under `pi`’s config directory are owned by `pi`. Ensures the desktop session runs as `pi` without permission issues.

---

## Default X session manager

Runs `update-alternatives --set x-session-manager /usr/bin/startplasma-x11` so the default graphical session is KDE Plasma on X11. Matches the LightDM setting above and ensures the kiosk and Maliit run in the same X11 session.

---

## reTerminal DM: Seeed display/touch drivers

Installs the official Seeed drivers for the reTerminal DM so the display and touch work:

1. Clones **https://github.com/Seeed-Studio/seeed-linux-dtoverlays** into `/tmp/seeed-linux-dtoverlays` (`--depth 1` for a shallow clone).
2. Runs **`scripts/reTerminal.sh --device reTerminal-DM`** to install device-tree overlays and any required firmware/config for the reTerminal DM.
3. Removes the clone from `/tmp`.

These changes take effect after a reboot.

---

## 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.

---

## Customisation

- **File server** — Edit `FILE_SERVER` if your `start-chromium.sh` and `chromium-kiosk.desktop` are served from another host/port.
- **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).