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

Update boot order configuration for eMMC first, then network

Browse Source 
Modify the first-boot script and documentation to set the EEPROM boot order to 0xf21, prioritizing eMMC boot followed by network boot. Adjust network boot settings for faster failure on DHCP timeouts and update related scripts and documentation to reflect these changes. Enhance the rescue script to directly modify EEPROM settings without requiring a chroot into eMMC, streamlining the recovery process for devices stuck in network-only boot. Update relevant documentation to ensure clarity on the new boot order and its implications.
This commit is contained in:
nearxos
2026-02-21 15:05:17 +02:00
parent ff6258c2af
commit 5238d457e8
13 changed files with 348 additions and 247 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
emmc-provisioning/cloud-init/first-boot.md
View File

@@ -18,7 +18,7 @@ This script runs once on first boot via cloud-init (see `user-data-remote-gnss.e
10. **Re-apply splash** — Set `disable_splash=0`, Plymouth theme to `custom` only, `update-initramfs`.
11. **Dark theme** — Set GTK dark theme for user `pi`: `~/.config/gtk-3.0/settings.ini` with `gtk-application-prefer-dark-theme=1` and `gtk-theme-name=PiXnoir` (Raspberry Pi OS dark theme).
12. **CM4 EEPROM enable** — On CM4, `rpi-eeprom-update` is disabled by default. First-boot enables it by adding `RPI_EEPROM_USE_FLASHROM=1` and `CM4_ENABLE_RPI_EEPROM_UPDATE=1` to `/etc/default/rpi-eeprom-update`. **No config.txt changes are needed** — `dtoverlay=audremap`/`dtoverlay=spi-gpio40-45` are for the flashrom method only and **must not be added** as they conflict with the reTerminal DM display backlight (GPIO13 PWM). The bootloader method (`pieeprom.upd`) is used instead.
13. **Boot order** — If `rpi-eeprom-config` is available, set `BOOT_ORDER=0x21` (network first, then eMMC/SD). On CM4 first boot this may be skipped (EEPROM not yet enabled); a one-shot systemd service runs after reboot to set boot order once.
13. **Boot order** — If `rpi-eeprom-config` is available, set `BOOT_ORDER=0xf21` (eMMC first, then network, then restart). Also sets `NET_BOOT_MAX_RETRIES=3`, `DHCP_TIMEOUT=1500`, `DHCP_REQ_TIMEOUT=500`, `NET_INSTALL_AT_POWER_ON=0` so network boot fails fast when no TFTP server is available. On CM4 first boot this may be skipped (EEPROM not yet enabled); a one-shot systemd service runs after reboot to set boot order once.
14. **One-shots** — Download `set-rotation-once.sh` + `.desktop` from file server (wlr-randr for labwc). Wallpaper is set once via pcmanfm config during first-boot.
15. **Reboot.**
@@ -137,9 +137,9 @@ First-boot sets a dark GTK theme for user **pi** via **`~/.config/gtk-3.0/settin
On **CM4**, first-boot enables `rpi-eeprom-update` by setting **`RPI_EEPROM_USE_FLASHROM=1`** and **`CM4_ENABLE_RPI_EEPROM_UPDATE=1`** in **`/etc/default/rpi-eeprom-update`**. **No dtparams are added to config.txt.** `dtoverlay=audremap` and `dtoverlay=spi-gpio40-45` are only needed for the *flashrom* (direct SPI) update method — they **must not** be added because `audremap` remaps audio to GPIO12/13, which conflicts with the reTerminal DM display backlight PWM on GPIO13, causing a blank screen. The bootloader file method (`pieeprom.upd`) works without these overlays. See: [usbboot](https://github.com/raspberrypi/usbboot/blob/master/Readme.md).
## Boot order (network first, then eMMC/SD)
## Boot order (eMMC first, then network)
If **`rpi-eeprom-config`** and **`rpi-eeprom-update`** are present (Pi 4/CM4), the script sets the EEPROM **`BOOT_ORDER=0x21`**: try **network** first (0x2), then **SD/eMMC** (0x1). **Pi 4:** applied on first-boot; EEPROM update scheduled for next reboot. **CM4:** a one-shot service (**`set-cm4-boot-order-once.service`**) runs after the next boot and sets BOOT_ORDER=0x21, then removes itself (two reboots for network-first). If “Could not read current EEPROM config” appears, run `sudo rpi-eeprom-update -l` on the device to see if a firmware file is listed; you can set boot order manually with `rpi-eeprom-config` if needed. If the tools are not available, the step is skipped.
If **`rpi-eeprom-config`** and **`rpi-eeprom-update`** are present (Pi 4/CM4), the script sets the EEPROM **`BOOT_ORDER=0xf21`**: try **SD/eMMC** first (0x1), then **network** (0x2), then **restart** (0xf). Network boot settings are tuned for fast fallback: `NET_BOOT_MAX_RETRIES=3`, `DHCP_TIMEOUT=1500` (1.5s), `DHCP_REQ_TIMEOUT=500` (0.5s), `NET_INSTALL_AT_POWER_ON=0`. The device boots from eMMC normally; if eMMC is blank it tries network boot for re-provisioning but gives up quickly when no TFTP server is available. **Pi 4:** applied on first-boot; EEPROM update scheduled for next reboot. **CM4:** a one-shot service (**`set-cm4-boot-order-once.service`**) runs after the next boot and sets the boot order, then removes itself. If “Could not read current EEPROM config” appears, run `sudo rpi-eeprom-update -l` on the device to see if a firmware file is listed; you can set boot order manually with `rpi-eeprom-config` if needed. If the tools are not available, the step is skipped.
## Reboot

35
emmc-provisioning/cloud-init/first-boot.sh
View File

@@ -214,10 +214,10 @@ grep -q '^RPI_EEPROM_USE_FLASHROM=' "$EEPROM_DEFAULT" && sed -i 's/^RPI_EEPROM_U
grep -q '^CM4_ENABLE_RPI_EEPROM_UPDATE=' "$EEPROM_DEFAULT" && sed -i 's/^CM4_ENABLE_RPI_EEPROM_UPDATE=.*/CM4_ENABLE_RPI_EEPROM_UPDATE=1/' "$EEPROM_DEFAULT" || echo 'CM4_ENABLE_RPI_EEPROM_UPDATE=1' >> "$EEPROM_DEFAULT"
log "Set RPI_EEPROM_USE_FLASHROM=1 and CM4_ENABLE_RPI_EEPROM_UPDATE=1 in $EEPROM_DEFAULT"
# --- 6d. Boot order: network first, then eMMC/SD (for future network boot / re-provisioning) ---
# BOOT_ORDER: 0x2 = network, 0x1 = SD/eMMC. 0x21 = try network first, then local storage.
# --- 6d. Boot order: eMMC/SD first, then network, then restart (0xf21) ---
# BOOT_ORDER nibbles (right-to-left): 1=SD/eMMC, 2=network (TFTP), f=restart loop.
# On CM4, rpi-eeprom-update -l only works after reboot (once 6c is applied). So we try now; if it fails, a one-shot runs after next boot.
log "--- Boot order (network first, then eMMC/SD) ---"
log "--- Boot order (0xf21: eMMC/SD first, then network, restart) ---"
BOOTCONF="/tmp/first-boot-eeprom-conf.txt"
BOOT_ORDER_SET=0
if command -v rpi-eeprom-config >/dev/null 2>&1 && command -v rpi-eeprom-update >/dev/null 2>&1; then
@@ -225,11 +225,17 @@ if command -v rpi-eeprom-config >/dev/null 2>&1 && command -v rpi-eeprom-update
rpi-eeprom-config "$PEE" > "$BOOTCONF" 2>/dev/null || true
fi
if [[ -s "$BOOTCONF" ]]; then
sed -i 's/^BOOT_ORDER=.*/BOOT_ORDER=0x21/' "$BOOTCONF"
grep -q '^BOOT_ORDER=' "$BOOTCONF" || echo 'BOOT_ORDER=0x21' >> "$BOOTCONF"
sed -i 's/^BOOT_ORDER=.*/BOOT_ORDER=0xf21/' "$BOOTCONF"
grep -q '^BOOT_ORDER=' "$BOOTCONF" || echo 'BOOT_ORDER=0xf21' >> "$BOOTCONF"
# Limit network boot: 3 retries, 1500ms DHCP timeout (fail fast to eMMC)
sed -i '/^NET_BOOT_MAX_RETRIES=/d; /^DHCP_TIMEOUT=/d; /^DHCP_REQ_TIMEOUT=/d; /^TFTP_IP=/d; /^NET_INSTALL_AT_POWER_ON=/d' "$BOOTCONF"
echo 'NET_BOOT_MAX_RETRIES=3' >> "$BOOTCONF"
echo 'DHCP_TIMEOUT=1500' >> "$BOOTCONF"
echo 'DHCP_REQ_TIMEOUT=500' >> "$BOOTCONF"
echo 'NET_INSTALL_AT_POWER_ON=0' >> "$BOOTCONF"
if rpi-eeprom-config --apply "$BOOTCONF" 2>/dev/null; then
log "Boot order set to 0x21 (network first, then eMMC/SD); EEPROM update scheduled for next reboot"
BOOT_ORDER_SET=1
log "Boot order set to 0xf21 (eMMC first, then network, restart); EEPROM update scheduled for next reboot"
@ BOOT_ORDER_SET=1
else
log "WARNING: rpi-eeprom-config --apply failed; boot order unchanged"
fi
@@ -247,15 +253,20 @@ if [[ "$BOOT_ORDER_SET" -eq 0 ]] && command -v rpi-eeprom-config >/dev/null 2>&1
ONCE_SVC="/etc/systemd/system/set-cm4-boot-order-once.service"
cat > "$ONCE_SCRIPT" << 'SETBOOTEOF'
#!/bin/bash
# One-shot: set BOOT_ORDER=0x21 (network first) when rpi-eeprom-update becomes available (e.g. after CM4 enable and reboot).
# One-shot: set BOOT_ORDER=0xf21 (eMMC first, then network) when rpi-eeprom-update becomes available (e.g. after CM4 enable and reboot).
BOOTCONF="/tmp/eeprom-boot-order-once.txt"
if PEE="$(rpi-eeprom-update -l 2>/dev/null)" && [[ -n "$PEE" ]] && [[ -f "$PEE" ]]; then
rpi-eeprom-config "$PEE" > "$BOOTCONF" 2>/dev/null
if [[ -s "$BOOTCONF" ]]; then
sed -i 's/^BOOT_ORDER=.*/BOOT_ORDER=0x21/' "$BOOTCONF"
grep -q '^BOOT_ORDER=' "$BOOTCONF" || echo 'BOOT_ORDER=0x21' >> "$BOOTCONF"
sed -i 's/^BOOT_ORDER=.*/BOOT_ORDER=0xf21/' "$BOOTCONF"
grep -q '^BOOT_ORDER=' "$BOOTCONF" || echo 'BOOT_ORDER=0xf21' >> "$BOOTCONF"
sed -i '/^NET_BOOT_MAX_RETRIES=/d; /^DHCP_TIMEOUT=/d; /^DHCP_REQ_TIMEOUT=/d; /^TFTP_IP=/d; /^NET_INSTALL_AT_POWER_ON=/d' "$BOOTCONF"
echo 'NET_BOOT_MAX_RETRIES=3' >> "$BOOTCONF"
echo 'DHCP_TIMEOUT=1500' >> "$BOOTCONF"
echo 'DHCP_REQ_TIMEOUT=500' >> "$BOOTCONF"
echo 'NET_INSTALL_AT_POWER_ON=0' >> "$BOOTCONF"
if rpi-eeprom-config --apply "$BOOTCONF" 2>/dev/null; then
echo "Boot order set to 0x21 (network first, then eMMC/SD)"
echo "Boot order set to 0xf21 (eMMC first, then network)"
fi
fi
rm -f "$BOOTCONF"
@@ -267,7 +278,7 @@ SETBOOTEOF
chmod 755 "$ONCE_SCRIPT"
cat > "$ONCE_SVC" << 'SVCEOF'
[Unit]
Description=Set CM4 boot order once (network first)
Description=Set CM4 boot order once (eMMC first, then network)
After=multi-user.target
[Service]