feat: Installation Media -- build bootable SD cards (stock recovery + alkane) from the toolkit #56

Open
noah wants to merge 13 commits from feat/installation-media into main
Owner

Installation Media: build bootable SD cards from the toolkit

A new, sanctioned physical path alongside the network-only install: build a bootable SD/removable-media card for card-bootable boards, to recover a board to stock or to bootstrap/install alkane via a card.

Motivated by the bench need (proven on an S17 2026-11-17) to recover boards with an SD card, and to install alkane via SD on boards where that is preferable.

What it does

  • Stock recovery card - replicate a genuine Bitmain vendor SD-recovery package onto a FAT32 card (operator supplies the vendor package). Codifies the by-hand procedure that recovered the bench S17.
  • Alkane: run from SD - boot alkane from the card each power-on; nothing written to the board.
  • Alkane: installer - boot an installer OS from the card that writes alkane into NAND (BOOT.bin preserved), read-back verifies, and LED-signals done (GPIO 941/942), then the operator pulls the card and boots internal alkane.

Zynq-7010 first (stock U-Boot card-detect side-load, confirmed on hardware). A113D is excluded (eMMC-only, no SD slot).

How it is built

  • crates/alkane-flash/src/sd_media.rs: assembles a partitioned FAT32 card image (MBR, FAT32 type 0x0c @ LBA 2048) as an ordinary file, root-free, via sfdisk + mkfs.vfat + mtools (no loopback mount). Only write_image_to_device (guarded dd) touches hardware. Alkane cards reuse the .afw payloads (VerifiedAfw) and uimage::wrap; the installer injects an /etc/init.d/S99alkane-sd-install hook into the afw rootfs cpio.gz.
  • crates/alkane-cli: afw make-media --kind stock|alkane [--mode simpleboot|installer] ... (writing a device needs --confirm WRITE).
  • crates/alkane-gui: right-click Installation Media (SD card)... -> a window (kind, Browse source, allow-unsigned, target SD device with Rescan, Create). Safe removable-device enumeration (never a system disk). Background worker streams progress on the shared channel.
  • docs/installation-media.md.

Verification

  • fmt, native clippy -D warnings, Windows clippy -D warnings, and the full test suite all pass locally; GUI headless self-test passes.
  • 7 new sd_media tests (card assembly read back via mtools; initramfs injection round-trips the hook; script targets the boot slots, never BOOT.bin).
  • End-to-end: make-media --kind stock from the genuine vendor S17 package produces a card image byte-identical in content/sizes to the hand-built card that recovered the bench S17.

Not yet hardware-validated: the alkane installer card's on-board hook (writing NAND + driving LEDs) running on the real S17 - the next bench step. The stock-recovery card format is already hardware-proven.

Generated with Claude Code

https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i

## Installation Media: build bootable SD cards from the toolkit A new, sanctioned **physical** path alongside the network-only install: build a bootable SD/removable-media card for card-bootable boards, to recover a board to stock or to bootstrap/install alkane via a card. Motivated by the bench need (proven on an S17 2026-11-17) to recover boards with an SD card, and to install alkane via SD on boards where that is preferable. ### What it does - **Stock recovery card** - replicate a genuine Bitmain vendor SD-recovery package onto a FAT32 card (operator supplies the vendor package). Codifies the by-hand procedure that recovered the bench S17. - **Alkane: run from SD** - boot alkane from the card each power-on; nothing written to the board. - **Alkane: installer** - boot an installer OS from the card that writes alkane into NAND (BOOT.bin preserved), read-back verifies, and LED-signals done (GPIO 941/942), then the operator pulls the card and boots internal alkane. Zynq-7010 first (stock U-Boot card-detect side-load, confirmed on hardware). A113D is excluded (eMMC-only, no SD slot). ### How it is built - `crates/alkane-flash/src/sd_media.rs`: assembles a partitioned FAT32 card **image** (MBR, FAT32 type 0x0c @ LBA 2048) as an ordinary file, **root-free**, via `sfdisk` + `mkfs.vfat` + `mtools` (no loopback mount). Only `write_image_to_device` (guarded `dd`) touches hardware. Alkane cards reuse the `.afw` payloads (`VerifiedAfw`) and `uimage::wrap`; the installer injects an `/etc/init.d/S99alkane-sd-install` hook into the afw rootfs cpio.gz. - `crates/alkane-cli`: `afw make-media --kind stock|alkane [--mode simpleboot|installer] ...` (writing a device needs `--confirm WRITE`). - `crates/alkane-gui`: right-click **Installation Media (SD card)...** -> a window (kind, Browse source, allow-unsigned, target SD device with Rescan, Create). Safe removable-device enumeration (never a system disk). Background worker streams progress on the shared channel. - `docs/installation-media.md`. ### Verification - fmt, native clippy `-D warnings`, Windows clippy `-D warnings`, and the full test suite all pass locally; GUI headless self-test passes. - 7 new `sd_media` tests (card assembly read back via `mtools`; initramfs injection round-trips the hook; script targets the boot slots, never BOOT.bin). - End-to-end: `make-media --kind stock` from the genuine vendor S17 package produces a card image byte-identical in content/sizes to the hand-built card that recovered the bench S17. **Not yet hardware-validated:** the alkane **installer** card's on-board hook (writing NAND + driving LEDs) running on the real S17 - the next bench step. The stock-recovery card format is already hardware-proven. Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
noah added 5 commits 2026-11-17 10:06:41 -07:00
New `sd_media` module: build bootable removable-media card *images* for
boards that boot from a card, root-free up to the final device write.

- `CardImage`: assemble a single-partition (MBR, FAT32 type 0x0c @ LBA 2048)
  card image as an ordinary file using sfdisk + mkfs.vfat + mtools
  (mcopy/mmd) -- no loopback mount, no root -- so the `.img` is fully
  inspectable and unit-testable without hardware. This is the exact card
  shape proven on the bench S17 (2026-11-17): stock U-Boot card-detects it
  and side-loads the flasher-OS trio with no boot-mode strap and no uEnv.txt.
- `build_stock_recovery_card`: codify the by-hand bench procedure -- replicate
  a genuine vendor SD-recovery package's layout (flasher-OS trio at the card
  root + `bin/` NAND payload) onto a card image. `locate_vendor_card` finds
  the layout inside an unpacked (possibly nested) vendor package.
- `write_image_to_device`: guarded, separate dd of a finished image to a block
  device (the only part that touches real hardware; caller confirms target).

Tests build a card from a synthetic vendor package and read it back with
mdir/mtype (skip cleanly if the host lacks the image toolchain).

First slice of the SD Installation-Media feature; alkane simple-boot and
installer card builders, the GUI window, and CLI parity follow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
Extends sd_media with the alkane card builders, reusing the afw payloads
(VerifiedAfw kernel/dtb/rootfs) and uimage::wrap:

- build_zynq_simpleboot_card: wrap the afw kernel/rootfs as a legacy-uImage
  side-load trio (uImage + raw dtb + uramdisk) so the stock U-Boot card-detect
  boots alkane from the card (nothing written to NAND).
- build_zynq_installer_card: boot an installer-OS (afw rootfs + an injected
  /etc/init.d/S99alkane-sd-install hook) that writes the alkane boot slots from
  the card bin/ into NAND (BOOT.bin at 0x0..0x1a00000 preserved), read-back
  verifies, and drives the red/green LEDs (GPIO 941/942) with a blink-done cue.
  Offsets mirror zynq_nand.
- build_installer_initramfs injects the hook into the afw rootfs cpio.gz.
- _from_parts variants take raw bytes so the builders unit-test without a
  VerifiedAfw.

7 sd_media tests pass. On-hardware behaviour of the installer hook is
validated on the bench S17 next.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
`alkane-cli afw make-media` wraps the sd_media builders:
  --kind stock  --stock-package <zip|dir> --out card.img
  --kind alkane --mode simpleboot|installer --afw <f.afw> --out card.img
      [--allow-unsigned] [--write /dev/sdX --confirm WRITE]

Zynq-7010 only for now. A .zip stock package is unpacked to a temp dir; a
directory is used as-is. Writing to a real device requires --confirm WRITE.

Verified end-to-end: building a stock card from the genuine vendor S17
package yields a card image byte-identical in content/sizes to the hand-built
card that recovered the bench S17 on 2026-11-17.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
Adds the headline "Installation Media (SD card)..." right-click action for
card-bootable boards (Zynq; gated by alkane_detect::media_supported, which
excludes the eMMC-only A113D).

- media_ops.rs: safe removable-device enumeration (lsblk -J; only removable /
  hotplug USB-or-mmc whole disks, never a system disk) and start_make_media, a
  background worker that builds the card image with alkane_flash::sd_media and
  optionally writes it to the chosen device, streaming StockMsg on the same
  channel the install/restore flows use (reuses stock_op + its drain).
- ui.rs: the dialog (build_install_media_dialog) -- choose kind (stock
  recovery / alkane run-from-SD / alkane installer), Browse an .afw or vendor
  package, allow-unsigned, pick a target SD device (index 0 = build an image
  file only) with Rescan, Create/Cancel -- plus the context item, dispatch,
  and apply_make_media_confirm.
- alkane_detect::media_supported; StockHandle::new so media_ops can build the
  handle.

GUI builds, native clippy -D warnings clean, headless self-test passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
docs: Installation Media (SD cards) -- feature, boards, GUI/CLI usage, safety
source / check (pull_request) Skipped
verify / verify-windows (pull_request) Failing after 19m51s
verify / verify (pull_request) Successful in 30m15s
dabe3ce846
Documents the sanctioned SD-media path alongside the network-only install:
stock-recovery, alkane run-from-SD, and alkane installer cards; Zynq-only
(A113D excluded, eMMC-only); GUI + CLI usage; erase/boot-region safety notes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
noah added 1 commit 2026-11-17 11:03:16 -07:00
test(flash): gate sd_media host-tool tests to unix (fix Windows/Wine verify)
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 32m35s
verify / verify-windows (pull_request) Successful in 27m1s
3742f28e7d
The verify-windows gate runs the unit tests under Wine. The card-building
tests shell out to unix tools (sfdisk/mkfs.vfat/mtools/cpio/gzip); their
find_tool-based runtime skip sees those binaries in the shared container
filesystem and does NOT skip, but a Windows process under Wine cannot exec a
Linux ELF, so injects_install_hook_into_initramfs failed.

Card building is a unix-host operation, so cfg(unix) the four tool-invoking
tests and their helpers. On the Windows target they are not compiled (no Wine
exec, no dead-code warnings); the three pure tests (sanitize labels, script
targets the boot slots, rejects a bad package -- which errors before any tool)
still run everywhere. Native keeps all 7 sd_media tests.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
noah added 3 commits 2026-11-17 12:27:40 -07:00
fix(gui): offer alkane install for the stock A113D (AML C76) board
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 30m58s
verify / verify-windows (pull_request) Successful in 19m55s
d574118314
The right-click "Install alkane OS..." item never appeared for a stock
Amlogic A113D (Antminer BHB42XXX). board_family(), which gates the menu
via install_supported(), recognized only the Xilinx/Zynq S17 control
board, so it returned None for the A113D and the menu offered nothing.

Two things combined to hide it, both visible in a live scan of the bench
board at 10.255.1.18:

    brand=Unknown  model="Unknown: ANTMINER BHB42XXX"  board=AML (C76)

asic-rs has no make for the BHB42XXX, so the brand is "Unknown" and
board_family() bailed at the `!brand.contains("antminer")` guard before
any board-code check; and there was no AML -> a113d mapping anyway. Yet
SUPPORTED_BOARDS, the from-stock install engine (stock::install_from_stock
dispatches a113d -> aml_ubi) and the CLI's SUPPORTED list all already
support a113d -- only this detection gate was stale.

Map the "AML (C76)" control board (the a113d identity; board_labels
already maps a113d -> ("AML","C76")) directly to "a113d", ahead of the
brand guard, since this board legitimately reports no brand. The "AML"
code is only ever derived for an Amlogic Antminer control board, so it is
specific on its own. CBE (140mm S19k/S21-class) is deliberately not
mapped.

Verified against the bench A113D: live scan now reports install=true, and
a headless stock->alkane->stock cycle through the GUI operation layer
(ALKANE_BENCH_SEQUENCE) on the released v0.1.0-a113d-bench1 image passes
(install -> dropbear_2026.93 -> flag-restore -> dropbear_2018.76).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
feat(gui): compact icon toolbar + SD-card media button
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 22m53s
verify / verify-windows (pull_request) Successful in 20m10s
8cb6989000
Reworks the fleet-view toolbar into icon buttons and adds a direct
Installation-Media entry point:

- New wx-rs bridge fn `wxbr_svg_button` (patch 0010): render a recoloured SVG
  into a clickable wxBitmapButton. Rust wrapper `Widget::svg_button`.
- Settings -> gear icon; its dropdown already carries Logs (ID_LOGS_OPEN), so
  the standalone Log toolbar button is removed (the inline log view + toggle
  are kept but no longer surfaced as a button).
- Bug report -> bug icon.
- New unified "Data" icon (database) with a dropdown: Presets, Filter, Columns,
  Export (the four former standalone buttons; items dispatched via on_menu_item).
- New "SD card" icon opens the Installation Media dialog without right-clicking
  a miner (ID_MEDIA_TOOLBAR -> build_install_media_dialog; defaults to the
  zynq-7010 board when nothing is selected).
- Four new Font-Awesome-style icons (gear/bug/database/sd-card), recoloured to
  the theme foreground via svg_recolored; tooltips name each button.

Native + Windows clippy clean, fmt clean, GUI self-test passes; icons verified
to rasterise correctly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
noah added 4 commits 2026-11-17 14:44:05 -07:00
- Install verify no longer false-fails on images that serve only SSH. The
  install worker now polls the target's SSH banner after writing (stock
  Antminers ship dropbear 2018/2019; any newer banner on the board we just
  installed to means alkane booted), independent of the HTTP /api/identity
  scan probe. The GUI's HTTP awaiting message is softened to make clear it is
  only about the row auto-refresh, not an install failure. Fixes the "installed
  but did not answer as alkane" seen on the A113D bench image (SSH-only, no
  HTTP API).
- Toolbar icons 22px -> 16px so they fit the control row.

Note: a minimal image without the HTTP API still will not appear in the scan
(the scan probe is HTTP); the proper fix is an A113D image that serves the
flare-ui/API (separate alkane-os/sdk work).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
#5: the install dialog's release source now accepts a full repo URL (Gitea or
GitHub) or a bare owner/repo. ReleaseSource::from_url parses the host; GitHub
uses api.github.com with the GitHub releases path. Security: the gitea token is
attached ONLY for the trusted self-hosted gitea host -- never sent to GitHub or
any other host (public anonymous access), including the asset download
(ReleaseSource::for_asset_url). curl now sends a generic User-Agent (GitHub
requires one). Field default is the full gitea URL.

#3: a stock Antminer whose miner API (:4028) is down -- e.g. no hashboards --
is now found by its :80 "antMiner Configuration" vendor web UI
(detect_stock_antminer), shown as "Antminer / Stock (model unknown)". The
install context item is offered for such a board, and the install dialog gains a
control-board selector (SUPPORTED_BOARDS) so the operator picks the board when
the scan could not determine it; changing it re-filters the release picker.

Tests: from_url parsing (gitea/github/bare, token safety); the
unidentified-stock-Antminer predicate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
Apply the presentation/documentation-review title directives to the install
and Installation-Media dialogs: short nominal labels (Release, Release repo,
Local .afw, Media type, Source, Target card, Control board), and delete
contextual tidbits and mechanism narration (the "Flash plan" checklist and its
afw_plan_text/install_plan_label, "This reflashes the control board...", "The
card is built as an image first...", the restated intro sentences). Essential
context moved to tooltips (repo URL formats, the unsigned-afw caveat, the
card-erase warning, the local-.afw override).

No behaviour change; the flash tier/overwrite detail still runs in the engine's
preflight, it is just not narrated in the dialog.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
test(gui): ALKANE_BENCH_FLOW -- full user flow incl. the scan step
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 26m13s
verify / verify-windows (pull_request) Successful in 20m39s
5b624c1910
Adds a headless GUI-flow driver that exercises the same code a user's clicks
trigger, including the scan: scan -> (restore to stock if on alkane) -> scan ->
install -> scan -> verify the board serves the HTTP API and shows as alkane.

bench_sequence::scan_report runs the real scan::start_scan and prints how each
board classifies (brand/model/control-board/install/alkane); run_flow chains
the scan + restore + install with liveness verification. Wired as
ALKANE_BENCH_FLOW="<host> <afw> [scan-range]" in main.rs.

Per Noah's rule: test toolkit fixes by automating the real GUI flow including
scanning, not just the engine in isolation.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
All checks were successful
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 26m13s
Required
Details
verify / verify-windows (pull_request) Successful in 20m39s
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/installation-media:feat/installation-media
git checkout feat/installation-media
Sign in to join this conversation.