diff --git a/chromium-setup/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md b/chromium-setup/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md index af91669..c5c0ede 100644 --- a/chromium-setup/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md +++ b/chromium-setup/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md @@ -1,25 +1,25 @@ -# Automatic eMMC provisioning for reTerminal DM4 (CM4) +# eMMC provisioning for reTerminal DM4 (CM4) This guide covers: -1. **Auto-flash**: When the reTerminal is switched to boot mode (eMMC disable jumper) and connected via USB to a provisioning host, the host automatically deploys a golden image to the CM4 eMMC. -2. **Backup**: When a device is detected (USB or network), the dashboard asks you to choose **Backup** or **Deploy**. Backup saves the device eMMC to a timestamped file in `backups/`. -3. **Network**: If the device boots over the network and runs the **provisioning client** (see `network-client/`), it registers with the dashboard and appears as "Device (Network)"; you then choose Backup or Deploy. Deploy streams the golden image to the device; Backup uploads the device eMMC to the server. -4. **Cloud-init**: The golden image includes cloud-init so each device configures itself on first boot (hostname, network, packages, kiosk setup). +1. **USB boot mode**: When the reTerminal is in boot mode (eMMC disable jumper) and connected via USB, the host runs **rpiboot** to expose the eMMC, then the **dashboard** shows "Device connected (USB)". You choose **Backup** or **Deploy** in the portal — there is no auto-flash; the action runs only after your choice. +2. **Network boot**: If the device boots over the network and runs the **provisioning client** (see `network-client/`), it registers with the dashboard and appears as "Device (Network)"; you then choose Backup or Deploy. Deploy streams the golden image to the device; Backup uploads the device eMMC to the server. +3. **Cloud-init**: The golden image can include cloud-init so each device configures itself on first boot (hostname, network, packages, kiosk setup). --- -## Part 1: Auto-flash when reTerminal is in boot mode +## Part 1: USB boot mode — detect device, choose Backup or Deploy in portal ### How it works - reTerminal has an **eMMC disable** jumper (see reTerminal docs; often “J2” or “nRPIBOOT”). When the jumper is fitted, the CM4 boots in **USB device mode** and waits for `rpiboot` from the host. - You connect the reTerminal’s **USB slave** port to a **provisioning PC** (Linux). - **udev** detects the Raspberry Pi Foundation USB device (vendor `2b8e`) and runs a trigger script. -- The trigger starts a **flash job** that: +- The trigger starts the **provisioning script** that: 1. Runs **rpiboot** (from the `usbboot` project). The CM4 then exposes its eMMC as a USB mass-storage device. - 2. After `rpiboot` exits, finds the new block device (eMMC) and writes your **golden image** to it with `dd`. -- You remove the jumper and power cycle; the reTerminal boots from eMMC and runs **cloud-init** on first boot. + 2. Finds the new block device (eMMC) and writes status so the **dashboard** shows "Device connected (USB boot mode). Choose Backup or Deploy in the dashboard." + 3. **Waits for your choice in the portal** — no automatic flash. When you click **Backup** or **Deploy** in the dashboard, the script runs that action (dd backup or dd deploy). +- You remove the jumper and power cycle; the reTerminal boots from eMMC and can run **cloud-init** on first boot. ### Provisioning host setup (Linux) @@ -45,7 +45,7 @@ sudo cp rpiboot /opt/usbboot/ - Or use a different path and set `GOLDEN_IMAGE` when installing the script (see below). -#### 3. Install the auto-flash script and trigger +#### 3. Install the provisioning script and trigger ```bash # From this repo (chromium-setup/emmc-provisioning/host/) @@ -84,9 +84,9 @@ sudo mkdir -p /etc/cm4-provisioning sudo touch /etc/cm4-provisioning/enabled ``` -To disable auto-flash, remove that file: `sudo rm /etc/cm4-provisioning/enabled`. +To disable provisioning (no device detection), remove that file: `sudo rm /etc/cm4-provisioning/enabled`. -#### 6. Optional: pass environment into the flash job +#### 6. Optional: pass environment into the provisioning job If you use `/opt/cm4-provisioning/env`, update the trigger so the flash script sees those variables. For example change `/usr/local/bin/cm4-flash-trigger.sh` to: diff --git a/chromium-setup/emmc-provisioning/host/90-cm4-boot-mode.rules b/chromium-setup/emmc-provisioning/host/90-cm4-boot-mode.rules index eb417fd..b0ffa11 100644 --- a/chromium-setup/emmc-provisioning/host/90-cm4-boot-mode.rules +++ b/chromium-setup/emmc-provisioning/host/90-cm4-boot-mode.rules @@ -1,8 +1,10 @@ # When reTerminal (CM4) is connected in USB boot mode (eMMC disable jumper), -# Raspberry Pi Foundation USB device appears (vendor 2b8e). Trigger auto-flash. +# Raspberry Pi Foundation USB device appears (vendor 2b8e). Trigger provisioning: +# run rpiboot to expose eMMC, then wait for user to choose Backup or Deploy in the portal. +# No auto-flash — action runs only after portal choice. # Install: sudo cp 90-cm4-boot-mode.rules /etc/udev/rules.d/ # sudo udevadm control --reload-rules -# The trigger script starts the actual flash via systemd so udev does not block. +# The trigger script starts the provisioning script via systemd so udev does not block. SUBSYSTEM=="usb", ATTR{idVendor}=="2b8e", ACTION=="add", \ RUN+="/usr/local/bin/cm4-flash-trigger.sh" diff --git a/chromium-setup/emmc-provisioning/host/cm4-flash-trigger.sh b/chromium-setup/emmc-provisioning/host/cm4-flash-trigger.sh index 23ab3dc..583ea06 100644 --- a/chromium-setup/emmc-provisioning/host/cm4-flash-trigger.sh +++ b/chromium-setup/emmc-provisioning/host/cm4-flash-trigger.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash -# Called by udev when CM4 in boot mode is connected. Starts the flash job in the background -# so udev can return immediately. Install to /usr/local/bin/cm4-flash-trigger.sh +# Called by udev when CM4 in boot mode is connected. Starts the provisioning script in the +# background (rpiboot + wait for portal Backup/Deploy choice). Install to /usr/local/bin/cm4-flash-trigger.sh FLASH_SCRIPT="${CM4_FLASH_SCRIPT:-/opt/cm4-provisioning/flash-emmc-on-connect.sh}" exec systemd-run --no-block --unit=cm4-flash-once "$FLASH_SCRIPT" diff --git a/chromium-setup/emmc-provisioning/host/flash-emmc-on-connect.sh b/chromium-setup/emmc-provisioning/host/flash-emmc-on-connect.sh index 5eae5d5..d0feadf 100644 --- a/chromium-setup/emmc-provisioning/host/flash-emmc-on-connect.sh +++ b/chromium-setup/emmc-provisioning/host/flash-emmc-on-connect.sh @@ -1,7 +1,8 @@ #!/usr/bin/env bash -# Auto-flash CM4 eMMC when reTerminal is connected in boot mode (eMMC disable jumper). -# Run this from udev or a systemd service when Raspberry Pi USB boot device (2b8e) is detected. -# Requires: usbboot (rpiboot) built, golden image at GOLDEN_IMAGE path. +# Provision CM4 eMMC when reTerminal is connected in boot mode (eMMC disable jumper). +# On USB boot device (2b8e) detection: run rpiboot to expose eMMC, then wait for the user +# to choose Backup or Deploy in the portal — no auto-flash; action runs only after portal choice. +# Run this from udev or a systemd service. Requires: usbboot (rpiboot) built, golden image for deploy. set -e