mirror of
https://github.com/openglow-org/forgefirm.git
synced 2026-09-27 08:41:13 -07:00
ScottW514
9c1d0c5073
Documents the new installer: A/B slot install with no repartitioning, factory archives to /data, signature-verified forgefirm.fw, ffboot switching, offline install, and the automatic legacy-layout migration.
92 lines
3.8 KiB
Markdown
92 lines
3.8 KiB
Markdown
# Installing OpenGlow/ForgeFIRM
|
|
|
|
ForgeFIRM installs **alongside** the factory firmware on the stock eMMC,
|
|
using the factory's own A/B rootfs slot scheme: the installer writes
|
|
ForgeFIRM to the slot the factory firmware is *not* running from, and
|
|
switches the bootloader to it. Nothing is repartitioned, the factory
|
|
`/data` partition (settings, calibration, logs) is untouched, and the
|
|
booted factory firmware stays installed in the other slot.
|
|
|
|
Before anything is overwritten, the installer archives **every** factory
|
|
firmware version on the machine — both rootfs slots and the recovery
|
|
boot partitions — to `/data/forgefirm/archive/`, so a full offline
|
|
factory restore is always possible, no Glowforge cloud required.
|
|
|
|
> **Requires a ForgeFIRM release that ships the `forgefirm.fw` asset
|
|
> (v0.1.0 or later).**
|
|
|
|
## Prerequisites
|
|
|
|
- [Serial console](SERIAL.md) access. Current factory firmware does not
|
|
offer SSH, so the install is run at the console (login `root`, no
|
|
password).
|
|
- ~300 MB free on `/data` (a factory machine has far more).
|
|
- Internet access on the machine for the standard flow. For an offline
|
|
install, place a `forgefirm.fw` on `/data` beforehand and pass its
|
|
path to the installer.
|
|
|
|
**A very important warning: this is experimental software. Use of this
|
|
software could seriously maim or kill you or others, and voids your
|
|
warranty. It is not affiliated with or endorsed by Glowforge. Use it at
|
|
your own risk.**
|
|
|
|
## Install
|
|
|
|
Log in at the factory console and run:
|
|
|
|
```sh
|
|
curl -fL https://raw.githubusercontent.com/ScottW514/forgefirm/master/scripts/install-forgefirm.sh --output /tmp/install-forgefirm.sh
|
|
sh /tmp/install-forgefirm.sh
|
|
```
|
|
|
|
(For an offline install: `sh /tmp/install-forgefirm.sh /data/forgefirm.fw`)
|
|
|
|
One stage, no intermediate reboots. The installer:
|
|
|
|
1. Confirms it is running on factory firmware, from a factory eMMC
|
|
slot, with the factory partition layout.
|
|
2. Stops the Glowforge services (including the updater).
|
|
3. Archives every factory slot version and the recovery boot
|
|
partitions to `/data/forgefirm/archive/` (manifest with checksums;
|
|
a few minutes each, with progress).
|
|
4. Downloads the latest `forgefirm.fw` release (or uses the local file
|
|
you passed) and **verifies its signature** before touching anything.
|
|
5. Writes ForgeFIRM to the inactive slot with the factory's own `fwup`,
|
|
then verifies the written filesystem.
|
|
6. Installs `/data/ffboot` (the boot-slot tool) and switches the saved
|
|
U-Boot environment to the new slot — the switch is read-back
|
|
verified; on any failure the machine keeps booting factory firmware.
|
|
7. Reboots into ForgeFIRM.
|
|
|
|
Login is `root`, no password (also via SSH). Change it.
|
|
|
|
## Switching firmware
|
|
|
|
Both systems stay installed; `ffboot` switches between them (as
|
|
`/data/ffboot` on factory firmware, on the PATH in ForgeFIRM):
|
|
|
|
```sh
|
|
ffboot -l # inventory: what is in each slot, what boots next
|
|
ffboot -e # switch to the factory firmware (newest factory slot)
|
|
ffboot -e2 # switch to ForgeFIRM (slot 2 on a standard install)
|
|
```
|
|
|
|
Switch targets are probed first — `ffboot` refuses to select a slot
|
|
that does not look bootable (`-f` overrides). Reverting to factory
|
|
firmware and back requires no reinstall.
|
|
|
|
To reinstall or update ForgeFIRM before the built-in updater ships:
|
|
switch to factory firmware and run the installer again — it skips
|
|
archives it already has and simply rewrites the ForgeFIRM slot.
|
|
|
|
## Upgrading from a legacy dual-partition install
|
|
|
|
Machines installed with the previous (partition-carving) installer
|
|
migrate automatically: run this installer from the factory firmware;
|
|
on ForgeFIRM's first boot from its new slot, the legacy partition is
|
|
reclaimed and `/data` grows back to the full factory size. `/data`
|
|
contents are preserved throughout.
|
|
|
|
**NOTE:** This firmware is in beta. It mostly works. It is for
|
|
experimentation purposes — not for production. Expect problems.
|