nearxos/reterminal-dm4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
359645296e220d130452260448384b7f101d4b1f
reterminal-dm4/chromium-setup/emmc-provisioning/cloud-init/first-boot.md

8.7 KiB
Raw Blame History

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.

Structure (sections)

  1. Constants — FILE_SERVER, PI_USER, paths, log file.
  2. Logging — All output tee’d 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 pi’s 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 pi’s .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.
  • DEBIAN_FRONTEND=noninteractive — Prevents apt from asking questions (assumes default or automatic answers).

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:

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

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)

Downloads from FILE_SERVER (no local creation):

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

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

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.

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.

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 KDE’s 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 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 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.