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-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.
## 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
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
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
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
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
- 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
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
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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
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, viasfdisk+mkfs.vfat+mtools(no loopback mount). Onlywrite_image_to_device(guardeddd) touches hardware. Alkane cards reuse the.afwpayloads (VerifiedAfw) anduimage::wrap; the installer injects an/etc/init.d/S99alkane-sd-installhook 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
-D warnings, Windows clippy-D warnings, and the full test suite all pass locally; GUI headless self-test passes.sd_mediatests (card assembly read back viamtools; initramfs injection round-trips the hook; script targets the boot slots, never BOOT.bin).make-media --kind stockfrom 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
`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_01B1W6qKwKxq3oUPDKWicM6iThe 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_01B1W6qKwKxq3oUPDKWicM6iView command line instructions
Checkout
From your project repository, check out a new branch and test the changes.