nearxos/reterminal-dm4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update eMMC provisioning guide and scripts for reTerminal DM4 to remove auto-flash feature. Users must now manually choose Backup or Deploy in the dashboard after connecting the device. Adjusted documentation and trigger scripts accordingly.

Browse Source
This commit is contained in:
nearxos
2026-02-18 12:29:22 +02:00
parent 21fc0e8fd2
commit 864e082046
4 changed files with 22 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
chromium-setup/emmc-provisioning/docs/EMMC-PROVISIONING-GUIDE.md
View File

@@ -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: