# Hardware testing: the flash ladder

CI proves the package is well-formed and that the installer does not brick a
*simulated* printer. It cannot prove anything about your actual machine. This
is the on-hardware procedure, ordered so that each step is recoverable using
what the previous step established.

**Rule: never skip a rung. Each one exists because it makes the next one
recoverable.**

---

## Before the first flash

- [ ] Build the uninstall stick and keep it physically separate:
      `make uninstall-pkg` → put `Creator5*-uninstall.tgz` on a spare USB stick.
- [ ] Note your printer's serial number (Settings → About). The factory image
      restores a placeholder serial and you may need to put yours back.
- [ ] Confirm you can reach the printer's IP.
- [ ] `make test` passes (78 checks).
- [ ] `make rootfs && make test-ash` passes — this parses every script that
      will run on the printer using the printer's own busybox ash.

Two USB sticks, FAT32, both packages at the **root** of the stick (not in a
folder). Ship both filenames (`Creator5-*` and `Creator5Pro-*`): the Pro's
boot script globs `Creator5Pro-*.tgz`, the non-Pro globs `Creator5-*.tgz`.

---

## Stage 0 — probe (`make probe`)

**Changes nothing.** Reinstalls the stock software component byte-for-byte and
writes a diagnostic report to the USB stick.

Flash it, wait for the reboot, pull the stick and read:

| File on the stick | What it tells you |
|---|---|
| `anvil-report.txt` | free space, partitions, installed versions, init layout, whether nginx/moonraker really exist |
| `anvil-stock-etc.tar` | the whole `/etc`, so the init chain can be studied offline |
| `anvil-stock-nginx.conf` | the stock nginx config (not shipped in any update package) |
| `anvil-stock-bootscripts.tar` | `app_startup.sh`, `start.sh`, `passwd`, `shadow` as they exist on YOUR unit |

**Go/no-go:** the report exists and the printer boots normally.
If the stick comes back empty, the package never installed — nothing was
changed, and you have learned that before risking anything.

**Check in the report:**
- free space on `/usr/data` is comfortably above the size of your full package
- `moonrakerDmn: yes` and `nginx binary: yes`
- the `INIT SYSTEM` block matches expectations (busybox init, `/etc/init.d/rcS`,
  `S50dropbear` present)

---

## Stage 1 — ssh (`make ssh`)

Sets a root password you know. **Nothing else changes.**

This works because the stock rootfs already ships `/usr/sbin/dropbear` and an
enabled `/etc/init.d/S50dropbear` — port 22 is already open on a stock
printer, there is simply no published password.

Set one first:
```sh
openssl passwd -6 'your-password'      # paste into ROOT_PW_HASH in config.env
```

**Go/no-go:**
```sh
ssh root@PRINTER
```
- [ ] you get a shell
- [ ] the printer still prints normally

From here on you have a real recovery channel, which is what makes every
later stage safe.

---

## Stage 2 — web (`make web`)

Starts nginx (Mainsail on :80) and moonraker (:7125). Klipper and the
touchscreen stay stock, so printing behaviour is unchanged.

**Go/no-go:**
- [ ] `http://PRINTER/` loads Mainsail
- [ ] Mainsail shows the printer as **ready** (not "Klipper reports: ERROR")
- [ ] the touchscreen still works
- [ ] a small test print completes from the touchscreen

If Mainsail loads but Klipper errors, stop here and read
`/usr/data/logs/printer.log` over ssh. Do not continue.

---

## Stage 3 — full (`make full`)

Replaces the Klipper tree with the fork and installs the toolchanger extras.
**This is the first stage that changes how the machine moves.**

Before flashing, re-read the warnings in `creator5-toolchange/README.md`
about Z offsets. A wrong offset drives the nozzle into the plate.

**Go/no-go — with the emergency stop within reach:**
- [ ] Klipper starts (`ssh root@PRINTER 'grep -i error /usr/data/logs/printer.log | tail'`)
- [ ] `TOOLCHANGE_STATUS` responds in the Mainsail console
- [ ] home all axes — watch the first Z move
- [ ] one tool change, by hand, at temperature
- [ ] a single-tool test print
- [ ] a multi-tool test print

The `.cfg` includes are **not** wired up automatically — a tuned `printer.cfg`
is never modified. New files arrive as `*.mod-new`. Add the includes by hand
in the order given in the toolchanger README, then run
`FF_IMPORT_FIRMWARE_CONFIG` once.

---

## Stage 4 — helix (`make helix`)

HelixScreen replaces FlashForge's `firmwareExe` as the touchscreen UI.

This is the stage where the stock UI stops driving the screen, so understand
the safety net before flashing:

- The genuine binary is kept on disk as `firmwareExe.stock` and is the
  fallback. Nothing is deleted.
- `init.d/S70klipper` owns Klipper startup, because on stock firmware it was
  `firmwareExe` — not any init script — that ran `/usr/prog/klipper/start.sh`.
  Without this the printer would boot to a working screen and be unable to
  move.
- If the UI dies repeatedly, `SAFE-MODE` latches after 3 boots and the printer
  falls back to the stock UI on its own.

**Go/no-go:**
- [ ] HelixScreen appears on the touchscreen
- [ ] Klipper is running (Mainsail says ready) — this is the one people miss
- [ ] heaters and motion respond from the touchscreen
- [ ] a test print from the touchscreen

**Recovering from a bad UI, in increasing severity:**
```sh
ssh root@PRINTER
/usr/data/mod/init.d/S80ui status        # what did it choose, and why
touch /usr/data/mod/SAFE-MODE            # force the stock UI on next boot
reboot
```
If ssh is gone too, flash the uninstall stick.

---

## If something goes wrong

| Symptom | Do this |
|---|---|
| Printer boots, screen blank | ssh in; `touch /usr/data/mod/SAFE-MODE`; reboot |
| No ssh, no screen | flash the uninstall stick |
| Uninstall stick does not help | flash a stock FlashForge package |
| Still broken | factory package (`Creator5Pro-factory-*.tgz` **plus** the separate `Creator5Pro-factory.tar.xz` on the same stick; needs 800 MB free) |

The mod never creates a mount point named like a mod, specifically so that
FlashForge's factory-restore package — which greps the mount table for a
known community mod's name and refuses to run when it matches — remains
usable as a last resort.

**Logs worth reading, all on the data partition and all surviving a reboot:**
```
/usr/data/mod-install.log      what the installer did
/usr/data/logs/mod-boot.log    services + UI choice at each boot
/usr/data/logs/printer.log     klipper
/usr/data/logs/helixscreen.log helixscreen
```