Refactor first-boot documentation and scripts to enhance Chromium startup behavior. Update start-chromium.sh to prefer Wayland for better touch support and adjust fullscreen handling for both Wayland and X11 environments. Clarify CM4 EEPROM configuration in documentation to prevent conflicts with reTerminal DM display backlight. Improve user guidance on touch interactions in Chromium.
This commit is contained in:
nearxos
97
emmc-provisioning/docs/NETWORK-BOOT-DEPLOYMENT-FLOW.md
Normal file
97
emmc-provisioning/docs/NETWORK-BOOT-DEPLOYMENT-FLOW.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# How network boot deployment works
|
||||
|
||||
This describes the full flow from power-on to eMMC deploy/backup when using **network boot** with the provisioning LXC.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
1. **reTerminal** is set to try **network boot first** (EEPROM `BOOT_ORDER=0x21`).
|
||||
2. It is connected to the **same LAN as the LXC’s eth1** (e.g. 10.20.50.0/24).
|
||||
3. On power-on it gets an IP via **DHCP** and loads **boot files via TFTP** from the LXC.
|
||||
4. The **netboot environment** (kernel + rootfs) runs **provisioning-client.sh**, which registers with the **dashboard** and polls for an action.
|
||||
5. In the **dashboard** you see the device under “Device detected (Network)” and choose **Deploy** or **Backup**.
|
||||
6. The device performs the action (download image → write eMMC, or read eMMC → upload), then you can reboot to run from eMMC.
|
||||
|
||||
---
|
||||
|
||||
## Step-by-step
|
||||
|
||||
### 1. LXC (provisioning server)
|
||||
|
||||
- **eth0** = WAN (e.g. 10.130.60.141), internet for the LXC.
|
||||
- **eth1** = LAN (e.g. 10.20.50.1/24):
|
||||
- **dnsmasq**: DHCP on eth1 (e.g. 10.20.50.100–200) and **TFTP** with next-server = 10.20.50.1, boot file = `start4cd.elf`.
|
||||
- **TFTP root** `/srv/tftpboot`: Raspberry Pi 4/CM4 boot files (from GitHub: start4cd.elf, fixup4cd.dat, kernel8.img, etc.).
|
||||
- **NAT**: traffic from 10.20.50.0/24 is masqueraded out eth0 so netbooted devices have internet if needed.
|
||||
|
||||
The **dashboard** (Flask) runs in the LXC and is reachable at e.g. `http://10.20.50.1:5000` from the LAN. The **golden image** for Deploy lives at `/var/lib/cm4-provisioning/golden.img` (same LXC or bind-mounted from host).
|
||||
|
||||
### 2. reTerminal (device)
|
||||
|
||||
- **EEPROM**: `BOOT_ORDER=0x21` (network first, then SD/eMMC). Can be set by cloud-init first-boot on an already-flashed device.
|
||||
- **Network**: Ethernet connected to the same segment as the LXC’s **eth1** (e.g. same switch/VLAN as 10.20.50.0/24).
|
||||
- On **power-on**:
|
||||
1. Pi 4/CM4 firmware does **DHCP** on the wired interface.
|
||||
2. DHCP reply gives: IP (e.g. 10.20.50.100), **next-server (TFTP)** = 10.20.50.1, **boot filename** = start4cd.elf.
|
||||
3. Device **TFTP**s boot files from the LXC (start4cd.elf, fixup4cd.dat, kernel, DTB, etc.).
|
||||
4. It boots the **kernel** (and optionally an initramfs or NFS root). That environment must have **network**, **curl**, and **provisioning-client.sh**.
|
||||
|
||||
### 3. Netboot root / environment
|
||||
|
||||
The **TFTP**-loaded kernel (and optional initramfs/NFS root) must end up in an environment where:
|
||||
|
||||
- The device has an IP on the same LAN as the LXC (already from DHCP).
|
||||
- **provisioning-client.sh** is present and run (e.g. from init, a login script, or a systemd service).
|
||||
- **PROVISIONING_SERVER** is set to the dashboard URL on the LXC’s LAN IP, e.g.
|
||||
`PROVISIONING_SERVER=http://10.20.50.1:5000`
|
||||
|
||||
So the “netboot environment” is either:
|
||||
|
||||
- A **custom initramfs** (recommended): build with **network-boot-initramfs/build.sh**, copy **initrd.img** to the TFTP root, and add `initramfs initrd.img followkernel` to **config.txt**. The initramfs brings up the network and runs the provisioning client. See **network-boot-initramfs/README.md**.
|
||||
- A **minimal rootfs** (e.g. NFS) that runs the client script at boot, or
|
||||
- Any other setup that gets the client running with network and the right `PROVISIONING_SERVER`.
|
||||
|
||||
### 4. Provisioning client (on the device)
|
||||
|
||||
- **provisioning-client.sh**:
|
||||
1. **Registers**: `POST /api/register-device` with MAC and IP.
|
||||
2. **Polls**: `GET /api/device-action-poll?mac=...` every few seconds.
|
||||
3. When the dashboard returns **action = deploy** (with **url**):
|
||||
downloads the image from **url** and runs `dd of=/dev/mmcblk0`.
|
||||
4. When the dashboard returns **action = backup** (with **upload_url**):
|
||||
runs `dd if=/dev/mmcblk0` and POSTs the stream to **upload_url**.
|
||||
5. Then exits (and you can reboot to eMMC after deploy).
|
||||
|
||||
### 5. Dashboard (your actions)
|
||||
|
||||
- You open the dashboard at `http://10.20.50.1:5000` (or the LXC’s WAN IP if you’re not on the provisioning LAN).
|
||||
- Under **“Device detected (Network)”** you see the device (identified by MAC).
|
||||
- You click **Deploy** or **Backup**.
|
||||
- The dashboard sets the **action** (and URL/upload_url) for that MAC; the next **device-action-poll** returns it, and the client runs the corresponding dd + curl.
|
||||
|
||||
---
|
||||
|
||||
## Data flow summary
|
||||
|
||||
| Stage | Where | What happens |
|
||||
|-------------|--------------|--------------|
|
||||
| Boot | reTerminal | DHCP (get IP + next-server + boot file), then TFTP (load start4cd.elf, kernel, etc.). |
|
||||
| Boot | reTerminal | Kernel (and netboot root) start; run **provisioning-client.sh** with `PROVISIONING_SERVER=http://10.20.50.1:5000`. |
|
||||
| Register | Device → LXC | POST /api/register-device (MAC, IP). |
|
||||
| Poll | Device → LXC | GET /api/device-action-poll?mac=... every 5 s. |
|
||||
| Your choice | You → LXC | In dashboard: click Deploy or Backup for that device. |
|
||||
| Deploy | LXC → device | Client GETs image URL, streams to `dd of=/dev/mmcblk0`. |
|
||||
| Backup | Device → LXC | Client `dd if=/dev/mmcblk0` and POSTs to upload_url. |
|
||||
| After | reTerminal | Reboot; if you deployed, it can now boot from eMMC. |
|
||||
|
||||
---
|
||||
|
||||
## What you need in place
|
||||
|
||||
- **LXC**: eth1 = 10.20.50.1/24, dnsmasq (DHCP + TFTP on eth1), `/srv/tftpboot` with RPi 4 boot files, NAT for 10.20.50.0/24 via eth0. Dashboard running, `golden.img` present for Deploy.
|
||||
See **NETWORK-BOOT-LXC.md** and **setup-network-boot-on-lxc.sh**.
|
||||
- **reTerminal**: EEPROM boot order = network first; Ethernet on 10.20.50.0/24; netboot environment that runs **provisioning-client.sh** with `PROVISIONING_SERVER=http://10.20.50.1:5000`.
|
||||
- **Netboot root**: Must provide network, curl, and the client script (NFS, initramfs, or custom root).
|
||||
|
||||
The **TFTP** setup only gets the Pi to boot a kernel (and optional root). The **provisioning** (Deploy/Backup) is done by that kernel’s environment running the **network-client** against the dashboard on the LXC.
|
||||
Reference in New Issue
Block a user