Simplify Toolkit docs and update installer status
build-test-release / release (push) Successful in 15m58s

This commit is contained in:
Noah
2026-10-15 14:36:09 -06:00
parent 8597ae9f9d
commit 5033c9609d
7 changed files with 172 additions and 451 deletions
+38 -96
View File
@@ -1,4 +1,4 @@
# alkane-toolkit
# Alkane Toolkit
[![CI](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/main.svg)](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
![tests](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/tests.svg)
@@ -10,118 +10,60 @@
![dependencies](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/dependencies.svg)
![license](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/license.svg)
The CI badge shows the last completed attempt for this branch while newer
runs are queued. Badge SVGs are stored in a private, machine-maintained branch.
The code-quality letter requires warnings-denied Clippy and measured test plus
UI self-test line coverage: A at 90%, B at 80%, C at 70%, D at 60%, and F
below 60%. A missing coverage measurement displays pending.
The benchmark delta compares an earlier commit only when its CPU class
matches the current dedicated runner; otherwise it establishes a new
baseline. Main CI runs microbenchmarks serially to avoid test contention.
Desktop fleet discovery and monitoring for ASIC miners. The Rust GUI uses
wxWidgets through a patched [wx-rs bridge](thirdparty/wx-rs). Firmware
installation is under development.
A cross-platform desktop toolkit for discovering, monitoring, and re-flashing
ASIC miners. It scans a fleet over the network, shows live health and hashrate
in a sortable table. The install path is under development for **stock** and
**alkaneOS** firmware on boards running stock, VNish/AnthillOS, Braiins OS+,
LuxOS, ePIC, HiveOn, BixBit, WardenOS).
The core and UI are pure Rust; the native window is wxWidgets driven through a
vendored, patched [wx-rs](thirdparty/wx-rs) bridge, so there is no Electron,
no web view, and a single self-contained binary per platform.
## What it does
- **Discover** a fleet by CIDR or IP range and identify each miner's make,
model, control board, and firmware (via a vendored [asic-rs](vendor/asic-rs)).
- **Monitor** hashrate vs. expected, per-board health, chip temperatures, fans,
PSU state, and pool workers, with an Excel-style filter and drag-reorderable
columns.
- **Operate** miners from a right-click menu: flash the locate light, pause /
resume, restart, set a power or hashrate target, select a firmware profile
(LuxOS/VNish presets), configure pools, set the timezone, and change the
password -- each action offered only when every selected miner supports it.
- **Install firmware**: push stock or aftermarket images, or revert an
aftermarket miner to stock, behind a typed confirmation.
Discovery and telemetry are read-only and safe to run against any fleet; every
mutating action is capability-gated and, where destructive, confirmed.
## Build and run (Debian/Ubuntu)
## Run locally
```sh
scripts/build-wx-linux.sh # once: builds the vendored wxWidgets 3.3.3 into ~/.cache
scripts/build-gui-linux.sh # cargo build --release -p alkane-gui
~/.cache/alkane-tk-target/release/alkane-toolkit
scripts/build-wx-linux.sh
scripts/build-gui-linux.sh
ALKANE_FAKE_SCAN=1 ~/.cache/alkane-tk-target/release/alkane-toolkit
```
Runtime needs GTK 3: `sudo apt install libgtk-3-0`. To explore the UI with no
hardware, run the offline demo fleet:
The first command builds wxWidgets 3.3.3 once. Linux runtime needs GTK 3
(`libgtk-3-0` on Debian/Ubuntu). The fake scan uses offline fixtures and
does not contact hardware. Windows and macOS use their respective
`scripts/build-gui-*.sh` scripts and platform toolchains.
```sh
ALKANE_FAKE_SCAN=1 alkane-toolkit
```
## Current scope
Windows and macOS share all GUI code; only the C++ bridge and wx build differ
(`scripts/build-gui-windows.sh` needs an msys2 toolchain, `-macos.sh` needs a
Mac).
- Discover miners by CIDR or IP range with vendored
[asic-rs](vendor/asic-rs), and show model, firmware, health, hashrate,
temperatures, fans, PSU, and pool workers.
- Filter, sort, and reorder columns in the desktop table.
- Probe discovery, telemetry, presets, and write actions with the
`miner_probe` CLI. Run it without arguments for the verb list.
## Command-line probe
`miner_probe` is a headless companion for hardware checks that should not go
through the window event loop -- discovery, telemetry, and each write action:
```sh
miner_probe scan 10.0.0.0/24 # discover + telemetry (TSV)
miner_probe presets 10.0.0.5 # list a firmware's selectable profiles
miner_probe setpreset 10.0.0.5 540MHz
```
Run `miner_probe` with no arguments for the full verb list.
The installer and some operator actions remain roadmap items; see the
[implementation plan](docs/IMPLEMENTATION-PLAN.md) and
[firmware parity matrix](docs/aftermarket-parity-roadmap.md). A listed
firmware or board is not an install claim. Discovery is read-only.
## Development
```sh
export WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config"
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target" # keep the target tree off the source share
cargo test -p alkane-gui # unit tests
cargo test -p alkane-gui --release -- --ignored bench_ # microbenchmarks
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings # lint gate
xvfb-run -a env ALKANE_SELFTEST=1 \
"$CARGO_TARGET_DIR/release/alkane-toolkit" # headless UI self-test
ci/coverage.sh --summary-only # coverage (tests + self-test)
export CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target"
cargo test -p alkane-gui --offline
cargo clippy -p alkane-gui --no-deps --bins -- -D warnings
scripts/ui-selftest.sh
ci/coverage.sh --summary-only
```
CI mirrors these: `verify.yml` runs lint, tests, benchmarks, the self-test, and
a dependency audit on development branches. `release.yml` runs the full gate
on every `main` push and cuts an `X.Y.Z` release when the change warrants it.
`next.yml` builds release candidates with little testing and publishes `-rc`
releases. Dependencies are vendored under `vendor/`, so builds never touch the
network.
Keep build output off the source share. `main` runs the full CI gate and
publishes qualifying releases; `next` builds `-rc` candidates. Badges
report host tests and benchmarks, not installation support. Benchmark
comparisons require the same CPU class.
## Architecture
## Firmware safety
- `crates/alkane-gui` -- the application: scan engine, data model, wxWidgets UI,
and the `miner_probe` CLI (the other `crates/alkane-*` are early scaffolding).
- `vendor/asic-rs` -- the miner-discovery and control library, vendored and
extended through numbered patches under `thirdparty/asic-rs/patches`.
- `thirdparty/wx-rs` -- the patched wxWidgets bridge (see `docs/adr/0002`,
`0003`).
See [`docs/IMPLEMENTATION-PLAN.md`](docs/IMPLEMENTATION-PLAN.md) for the roadmap
and [`docs/aftermarket-parity-roadmap.md`](docs/aftermarket-parity-roadmap.md)
for the firmware config/scan parity work.
## Firmware safety rules
Encoded in code, from alkane-sdk `docs/install-methods.md`:
1. Never write the bootloader or secure region.
2. Verify on a channel the installer does not control.
3. Reboot is root-only; a dropped SSH connection can still be success.
4. A packer is per board; never reuse one across boards.
5. Boot-switch handling is an explicit, verified step.
The [SDK install rules](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/docs/install-methods.md) require
serial and recovery checks for risky writes. Installation must never write
the bootloader or secure region, must verify over an independent channel,
and must use the packer and boot-switch procedure for the exact board.
## License
Licensed under the [MIT license](LICENSE).
[MIT](LICENSE). Vendored dependencies keep their own terms.
+89 -247
View File
@@ -1,275 +1,117 @@
# alkane-toolkit — Implementation Plan
# Toolkit plan
Version 0.1, drafted 2026-09-14. Status: DRAFT for review.
Drafted 2026-09-14. This is an installer design reference. See the
[README](../README.md) for current delivery status.
## 1. Mission
## Scope
A cross-platform desktop application that installs **stock** or **alkaneOS**
onto ASIC miner control boards, whatever they currently run — stock, Vnish/
AnthillOS, Braiins OS+, LuxOS, ePIC UMC, BixBit, WardenOS — with the safety
rules that keep every transition reversible enforced in code, not in prose.
The Toolkit is planned to install stock or Alkane OS from stock,
Vnish/AnthillOS, Braiins OS+, LuxOS, ePIC UMC, BixBit, and WardenOS.
The SDK owns board data, image packers, and build outputs. The Toolkit
owns discovery, access, execution, verification, and the operator UI.
An entry in this plan is a target, not a shipping install path.
**alkane-toolkit is the mechanization of alkane-sdk's `install/from-firmware/`
recipes.** The SDK owns board knowledge, packers, and build outputs; the
toolkit owns discovery, foothold, execution, verification, and the operator
UI. Nothing in the toolkit re-derives board facts; it loads them from the SDK.
The source rules are [SDK install methods](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/docs/install-methods.md),
[firmware recipes](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/install/from-firmware/README.md),
and `boards/*/board.yml`. The bench evidence cited below includes the
S17 NAND restore (2026-09-14), WhatsMiner network updates and `/data`
overlay, Amlogic stock capture, and Braiins CV bootloader analysis.
## 2. Ground truth this is built on
Sources (all CONFIRMED unless tagged):
- `alkane-sdk/main/docs/install-methods.md` — universal invariants, per-board
flows, boot-switch discipline, anti-brick floor.
- `alkane-sdk/main/install/from-firmware/README.md` — universal install
pattern and the root-vector table per source firmware.
- `alkane-sdk/main/boards/` — 7 board families: am335x-bb, zynq-7010,
cv1835, a113d, allwinner-h3/h6/h616 (status: bake).
- Bench-corpus install evidence: stock restores (S17 NAND restore verified
2026-09-14), WhatsMiner network install (0x9a5ba57c package, remote-daemon
cmd 7), WhatsMiner `/data` overlay persistence, BixBit SSH SD images,
aml stock live capture, Braiins cv bootloader.
### The universal pattern (from the SDK, implemented as pipeline stages)
## Install pipeline
```
discover -> classify(board, soc, running-fw, chip) -> foothold(root)
-> pack(board, image) -> backup -> transfer -> write
-> verify-write -> boot-switch -> reboot
-> verify-live(marker, independent channel) -> verify-persist(N>=2 power cycles)
discover -> classify -> root access -> pack -> backup -> transfer -> write
-> verify write -> select boot -> reboot -> verify live
-> verify after at least two unattended power cycles
```
### Root vectors per source firmware (SDK table, toolkit implements)
Each `{board, source OS}` recipe supplies typed parameters to one engine
([ADR 0001](adr/0001-recipes-as-data.md)). Each stage must be resumable
or idempotent and write an audit record. The GUI and CLI use the same
engine; board facts come from the SDK. WhatsMiner package builders must
match captured vendor output byte for byte when ported from Python.
| Source | In-band root | Mechanism |
|---|---|---|
| Braiins OS+ | yes | root SSH, empty password (first boot on aml) |
| ePIC UMC OS | yes | vendor default `root:letmein` |
| LuxOS | yes | unauthenticated OTA-source hijack |
| Vnish / AnthillOS | no | removal API -> land on stock -> stock->ours |
| Bitmain stock | yes (owned hw) | update-daemon loopback RCE via SSH forward |
| WhatsMiner stock | restricted | admin uid-300; root via rooted SD or `/data` overlay |
## Safety requirements
### The five invariants (enforced in Rust types, not docs)
1. Refuse writes to bootloader and secure partitions in the engine.
2. Verify a positive marker and liveness over an independent channel,
then pass at least two unattended power cycles.
3. Treat a dropped SSH session after root-initiated reboot as possible
success; reclassify over the liveness channel.
4. Bind each image packer to its board and verify boot-switch state.
5. Require a live serial console before kernel or boot-adjacent writes.
6. Verify image digest and format before writing, and read back over an
independent channel. Protect live earners from broad auth attempts;
teardown requires explicit operator authorization in the audit log.
1. **Never write the bootloader/secure region** (AM335x/Zynq/A113D NAND
loader partitions, CV1835 `boot0`, H616 eFuse). `PartitionSpec` carries a
`secure: bool`; the write engine refuses `secure` targets unconditionally.
2. **Verify on an independent channel** — positive marker match, then a
liveness probe the installer did not control, then >= 2 unattended power
cycles (persist gate).
3. **Reboot is root-only; dropped SSH can be success.** The reboot stage
treats a connection timeout as a candidate success and re-classifies via
the liveness channel.
4. **Packer is per board.** `PackFormat` is a board-owned enum (legacy uImage
ramdisk, FIT, UBI/UBIFS, raw-partition dd); cross-board use is a compile-
time non-representable state.
5. **Boot-switch is an explicit verified stage** — recorded false positive
(Amlogic UBI volume-name trap) encoded as a regression test.
These requirements encode recorded UBI volume-name and installer-exit
false positives. The SDK documents the per-board recovery path.
## 3. Architecture
## Components
Cargo workspace, core in Rust, GUI per section 6.
| Component | Planned responsibility |
| --- | --- |
| `alkane-core` | Board, OS, artifact, partition, stage, and safety types |
| `alkane-discovery` | Vendored asic-rs 0.8.1 scan, CIDR lists, classification, and a planned ARP/ICMP pre-pass for silent boards |
| `alkane-access` | SSH with legacy algorithms, Bitmain and WhatsMiner port 4028 clients, and serial transport where network receive is broken |
| `alkane-flash` | SSH stream transfer for minimal BusyBox, MTD/eMMC writes, board packers, readback, U-Boot environment updates, LuxOS installer, and IMAGEWTY tooling |
| `alkane-artifacts` | SHA-256 manifest and image magic, size, and integrity checks; seed manifest has 14 bench artifacts |
| `alkane-cli` | Headless bench and scripting commands for the same engine |
| `alkane-gui` | Rust wxWidgets UI through patched wx-rs ([ADR 0002](adr/0002-gui-bindings.md)); primary view in [UI spec](UI-SPEC.md) |
```
crates/
alkane-core/ domain: Board, SocFamily, SourceOs, TargetOs, Artifact,
Pathway, PipelineStage, PartitionSpec, Invariant checks
alkane-discovery/ LAN discovery + classification (port of tools/net-scan.py,
incl. the two pending upgrades: multi-subnet/CIDR and the
ARP/ICMP pre-pass for link-up-but-silent boards)
alkane-access/ foothold: SSH (russh) with legacy algo support
(diffie-hellman-group1-sha1, ssh-rsa, aes128-cbc for old
stock), credential table, Bitmain :4028 API client,
WhatsMiner :4028 update_firmware client (md5crypt token +
SHA256(pwd_md5) AES-ECB, u32-LE chunk framing, live-
verified; the 8889 binary daemon stays out: key unknown),
update-daemon loopback RCE driver, serial-transport mode
(a113d ethernet RX broken on bench units; serial
base64/bzip2 push ~10 KiB/s is proven)
alkane-flash/ transfer + write engines: SSH exec-channel `cat >` pipes
(stock busyboxes have no SFTP server and no wget/tftp/nc;
use SFTP only where the OS provides it), mtd writers,
eMMC raw, per-board packers (FIT/uImage/UBI), env-rewrite
discipline (stage -> size-gate -> single-block dd ->
byte-compare readback), readback verification, LuxOS =
official installer as subprocess + ed25519 inject
watcher port, IMAGEWTY patching = debugfs subprocess
first (Rust ext4 writer later)
alkane-artifacts/ artifact registry: manifest (sha256, board applicability,
source provenance; seed committed at
crates/alkane-artifacts/data/manifest-seed.csv),
verify-image port (magic/min-size/integrity),
stock-package library from the bench corpus
alkane-cli/ headless driver for bench + scripting (`alkane-toolkit-cli`)
gui/ native GUI (decision in section 6)
docs/ this plan, ADRs, safety-model
```
Access details include the WhatsMiner `update_firmware` token and
AES-ECB/u32-LE chunk framing, old stock SSH algorithms, and serial
base64/bzip2 transfer for A113D. Flash recipes must retain the
single-block U-Boot environment readback and per-board format checks.
Key design decisions:
## Bench pathways
- **D1 — Recipes and board knowledge as data, consumed from alkane-sdk.**
Each `{board, source-OS}` recipe is a declarative pipeline (stage list +
parameters) interpreted by the engine. The SDK already publishes the
machine-readable half: `boards/*/board.yml` (SoC, arch, boot.partitions,
install capabilities, firmware-install sources) and
`install/from-firmware/<board>/README.md` (foothold, transfer, write,
verify, revert). The toolkit parses these rather than duplicating them;
`persistence/` MTD tables (empty placeholders today) get materialized
from `board.yml` + `wiki/40-boot-os-and-build/board-os-matrix.md` into
the same machine-readable store.
- **D2 — Every stage is idempotent-or-resumable** and produces an audit log
entry (what, where, checksum before/after) so a failed install can be
resumed or rolled back from the same state the log describes.
- **D3 — Reuse, don't rewrite, WhatMiner package building.** The proven
Python builders (`scratch/wm-install-build/wm_package_builder.py`,
`build_rooted_data.py`, `edit_wm_imagewty_h3.py`) are ported to Rust with
byte-for-byte output equivalence tests against captured vendor packages.
- **D4 — CLI first.** Every GUI action maps 1:1 to a CLI verb; the GUI is a
view. This keeps the bench (headless) and the operator (GUI) on one engine.
## 4. Bench-validated pathway matrix (what the engine must express)
From `bench-wiki/boards/` + `MEMORY-SNAPSHOT/` — each row is proven on our
bench, so the recipe data format must carry all of this without special
cases:
The matrix records physical install observations. It does not prove that
the Toolkit implements them. The recipe schema must represent each row.
| Board (SoC) | Proven installs | Foothold on stock | Transfer | Hard rules |
|---|---|---|---|---|
| am335x-bb (S19j Pro) | 5/5 network-only (stock, LuxOS, ePIC, Braiins, Vnish → OurOS), round-tripped | `miner:miner` + update-daemon loopback RCE | SSH/SFTP | autoboot abort = ESC with 1 s window (catcher first, then power); mtd0-3 never written; bootloader written last; no SD boot proven — NAND is the only net |
| zynq-7010 (S19) | stock→OurOS, Vnish→OurOS network-only | `miner:miner` + loopback RCE | SSH/SFTP | PS RSA eFuse is per-unit — read 0xF800D010 before planning; FIT unverified branch is the entry; autoboot 0 s (keys must pre-flood); stock console echoes but no getty |
| zynq-7010 (S17) | stock NAND restore verified by CRC through U-Boot (2026-09-14) | stock `root` with EMPTY password; legacy SSH algos (dh-group1-sha1, ssh-rsa, aes128-cbc) | ymodem over serial for NAND writes; SSH for userspace | board mtd char/block reads return EIO — verify only via U-Boot `nand read`+`crc32`; ymodem splits at ≤2047 blocks; `reboot -f` no-ops from RAM-boot (sysrq `b`) |
| a113d (BHB42XXX) | 5/5 | `miner:miner` + loopback RCE; `amlenv.py` edits env in-band over SSH (`/dev/nand_env`) | SSH (net), U-Boot env is the boot switch | UBI volume name is order-dependent (`nvdada_log`/`umc_os_rootfs`/`overlay`) — detect live, never hardcode; per-OS DHCP lease differs (false DARK trap — a failed self-report downgrades to WARNING, SSH fingerprint decides) |
| a113d hardened (S21 Pro) | stock restore via env swap; two root paths | `miner:miner`; daemon injection char-whitelisted (dead) — use `eclipse`/`updatem` forged `{type:root}` package → sudoers → root | SSH or serial-only (base64/bzip2, ~10 KiB/s, ~11 min install) | stock busybox has no wget/nc/tftp/curl/gzip/xz; console arg must be `ttyAML0`+`meson` earlycon or the board boots blind and the install looks failed |
| cv1835 (S19k Pro) | 3/3 buildable (LuxOS no asset, ePIC wrong silicon excluded) | `miner:miner` + `/nvdata/rroot` (non-permanent — p7 reformat destroys it; gate on `rroot -c id`) or loopback RCE | SSH pipe (`cat >`, busybox has no wget/tftp/nc) | Vnish/Braiins are RAM overlays on stock kernel — exit while overlay is live; eMMC boot0 eFuse-hook units cannot SD-recover; golden copy at raw LBA 0x300000 is the only net; serial catch needs 3 ms flood |
| allwinner H3/H6/H616 (WhatsMiner) | rooted `/data` overlay survives genuine reinstall (proven on H616); genuine network update executed on H3 + H616 | `admin:admin` uid-300 shell; root via `/data/rootshell` overlay (persists) or rooted SD image | 4028 API `update_firmware` (AES-ECB + md5crypt token, ≤1 MB chunks); IMAGEWTY SD-burn for rooted card | package format 0x9A5BA57C forgeable (MD5+CRC only); 8889 binary daemon AES key unknown — not implementable, use 4028; H616 payload key eFuse/OP-TEE-bound; H3 rootfs.fex LUKS (only /data slices editable); random MAC → DHCP moves |
| am335x-bb (S19j Pro) | 5/5 network-only (stock, LuxOS, ePIC, Braiins, Vnish -> OurOS), round-tripped | `miner:miner` + update-daemon loopback RCE | SSH/SFTP | autoboot abort = ESC with 1 s window (catcher first, then power); mtd0-3 never written; bootloader written last; no SD boot proven; NAND is the only net |
| zynq-7010 (S19) | stock->OurOS, Vnish->OurOS network-only | `miner:miner` + loopback RCE | SSH/SFTP | PS RSA eFuse is per-unit; read 0xF800D010 before planning; FIT unverified branch is the entry; autoboot 0 s (keys must pre-flood); stock console echoes but no getty |
| zynq-7010 (S17) | stock NAND restore verified by CRC through U-Boot (2026-09-14) | stock `root` with EMPTY password; legacy SSH algos (dh-group1-sha1, ssh-rsa, aes128-cbc) | ymodem over serial for NAND writes; SSH for userspace | board mtd char/block reads return EIO; verify only via U-Boot `nand read`+`crc32`; ymodem splits at ≤2047 blocks; `reboot -f` no-ops from RAM-boot (sysrq `b`) |
| a113d (BHB42XXX) | 5/5 | `miner:miner` + loopback RCE; `amlenv.py` edits env in-band over SSH (`/dev/nand_env`) | SSH (net), U-Boot env is the boot switch | UBI volume name is order-dependent (`nvdada_log`/`umc_os_rootfs`/`overlay`); detect live, never hardcode; per-OS DHCP lease differs (false DARK trap; a failed self-report downgrades to WARNING, SSH fingerprint decides) |
| a113d hardened (S21 Pro) | stock restore via env swap; two root paths | `miner:miner`; daemon injection char-whitelisted (dead); use `eclipse`/`updatem` forged `{type:root}` package -> sudoers -> root | SSH or serial-only (base64/bzip2, ~10 KiB/s, ~11 min install) | stock busybox has no wget/nc/tftp/curl/gzip/xz; console arg must be `ttyAML0`+`meson` earlycon or the board boots blind and the install looks failed |
| cv1835 (S19k Pro) | 3/3 buildable (LuxOS no asset, ePIC wrong silicon excluded) | `miner:miner` + `/nvdata/rroot` (non-permanent; p7 reformat destroys it; gate on `rroot -c id`) or loopback RCE | SSH pipe (`cat >`, busybox has no wget/tftp/nc) | Vnish/Braiins are RAM overlays on stock kernel; exit while overlay is live; eMMC boot0 eFuse-hook units cannot SD-recover; golden copy at raw LBA 0x300000 is the only net; serial catch needs 3 ms flood |
| allwinner H3/H6/H616 (WhatsMiner) | rooted `/data` overlay survives genuine reinstall (proven on H616); genuine network update executed on H3 + H616 | `admin:admin` uid-300 shell; root via `/data/rootshell` overlay (persists) or rooted SD image | 4028 API `update_firmware` (AES-ECB + md5crypt token, ≤1 MB chunks); IMAGEWTY SD-burn for rooted card | package format 0x9A5BA57C forgeable (MD5+CRC only); 8889 binary daemon AES key unknown; not implementable, use 4028; H616 payload key eFuse/OP-TEE-bound; H3 rootfs.fex LUKS (only /data slices editable); random MAC -> DHCP moves |
Fleet classification fingerprints: Antminer-family 4028 speaks
`{"command":...}`; WhatsMiner speaks `{"cmd":"get_version"}` and rejects the
other dialect — the cheapest reliable family split. SSH banner + KEX
offering narrows OS generation (old stock = legacy-only algos).
Antminer port 4028 uses `{"command":...}`; WhatsMiner uses
`{"cmd":"get_version"}`. SSH banner and KEX help classify old stock.
## 5. Discovery + classification (M1 scope)
## Milestones
**Scan engine = vendored `asic-rs` 0.8.1** (Apache-2.0, 256foundation; see
ADR-0003): `MinerFactory` with subnet configuration,
`scan_stream()` discovery, per-firmware entries for Antminer (stock,
Braiins, Vnish, LuxOS, ePIC...), WhatsMiner, Marathon, Bitaxe and more,
typed miner data (hashrate, temps, fans, power, pools). Our `net-scan.py`
knowledge is folded in rather than ported line-for-line:
| Phase | Exit condition |
| --- | --- |
| M0 | Workspace, CI, vendored asic-rs/wxWidgets/wx-rs, and Rust GUI decision recorded |
| M1 | Nine-board bench discovery view, scan ranges, filters, columns, and silent-board classification |
| M2 | Artifact registry and image verification, including bulk archives and per-model corpus |
| M3 | Zynq-7010 stock restore, then Alkane OS installation after SDK release qualification; readback, boot switch, liveness, and persistence gates |
| M4 | Guided SD recovery builders and verified image burn |
| M5 | WhatsMiner, A113D, CV1835, and AM335x install pathways |
| M6 | Install wizard, progress and cancel, audit log, and platform packaging |
- Multi-subnet / CIDR-list targeting (scan-ranges editor feeds it, per
`docs/UI-SPEC.md`).
- ARP/ICMP pre-pass so link-up-but-silent boards surface as a distinct row
(a board we can identify but not log into is a restore candidate, not
invisible) — ours to add; asic-rs only reports responders.
- Our classification additions: install-pathway availability, foothold
state, family splits asic-rs does not model (the `command` vs `cmd`
:4028 dialect split, SSH banner/KEX generation fingerprint).
- live-fleet-ops guardrails around the scan loop: rate limiting, no auth
bursts, production ranges excluded unless explicitly enabled.
The SDK now builds rootfs artifacts for all seven boards. No production
image or Toolkit installation pathway is qualified. The first install
milestone remains blocked by release evidence and installer implementation.
Bench validation closes each milestone; do not exercise live earners
without explicit authorization.
## 6. GUI: the wxWidgets decision
## Open questions
Requirement: native cross-platform GUI, wxWidgets **vendored into the repo**
(ADR-0003, wx 3.3.3 pristine + patch queue). Primary view is fixed by the
operator in `docs/UI-SPEC.md` (KPI header, scan-ranges editor, Excel-style
filter panel, columns panel; sortable/drag-reorderable table with row
checkboxes, IP pinned first, default order: hashrate, power, chip temp,
cooling, firmware, pool worker, rest). Rust binding reality (checked
crates.io 2026-09-14):
- Which stock image version is canonical for each board? The bench corpus
has an S17 restore image; other stock packages need selection.
- Which SDK release should the installer pin after board and simulator
gates pass?
- Which of Linux, Windows, and macOS must ship in the first GUI package?
- `wxRust` 0.0.1-alpha, unmaintained since 2022.
- `wx-rs` 0.2.0 (2023, self-contained), ~6k downloads.
## References
Neither is production-grade. Two ways to honor the requirement:
- **Option A (recommended): thin C++ wxWidgets shell + Rust core.**
`gui/` is a small C++17 wx app (~1-2k lines: frames, lists, wizard, event
glue) that calls the Rust core through a small stable C ABI exported by
`alkane-core` (cdylib; header generated with cbindgen). All logic, safety
invariants, and tests live in Rust. The shell holds zero business logic.
wxWidgets is used as intended, on the mature C++ API, on all three OSes.
- **Option B: pure-Rust via `wx-rs`.** Time-boxed spike first (M0): a window
+ tree/list + wizard + worker-thread progress + cancel, built and run on
Linux and Windows. If the spike holds, keep pure Rust; otherwise fall back
to A without having lost the week.
The plan proceeds on A as the default with the B spike as a gate in M0; the
call is reversible until M3 (first GUI milestone).
## 7. Milestones
- **M0 — Scaffold + GUI decision.** Workspace compiles (done), CI on gitea,
ADRs (drafted), wx spike (Option B) executed against the vendored wx
3.3.3 + UI-SPEC table, binding decision recorded. Vendoring done:
asic-rs 0.8.1 (cargo-vendored), wxWidgets 3.3.3 (pristine + patches/).
- **M1 — Discovery + classification.** asic-rs MinerFactory integrated;
KPI header + sortable table render the live bench (9 boards: S17 stock,
S19 xil, S19j Pro bb, S19k Pro cv, S21 Pro aml, H3, H616, M50, WardenOS
dev); scan-ranges editor, filter panel, columns panel per UI-SPEC;
ARP/ICMP pre-pass added for silent boards; the per-OS-DHCP-lease
false-DARK rule respected.
- **M2 — Artifact registry + verify-image.** Seed manifest committed (14
artifacts with sha256: WhatsMiner SD programs, Bitmain stock zip, ePIC
powerplay, BixBit .bmu set, forged WM packages, LuxOS installer);
remaining: bulk archives (3.7 GB / 624 MB), `firmware-analysis/downloads/`
per-model corpus, and the verify-image magic/size/integrity checks.
- **M3 — First full pathway: zynq-7010.** stock -> stock restore (proven on
C49, the S17) and any-supported-source -> alkaneOS once the SDK's zynq
artifacts exist. Foothold, exec-channel transfer, mtd write with readback
verify, boot-switch, liveness + persist gates. This milestone exercises
every invariant for real.
- **M4 — SD recovery builders.** Port `make-sd-*.sh` + guided SD flow
(generate image, verify, burn, boot instructions).
- **M5 — Remaining families.** WhatsMiner (4028 update_firmware client +
package builder port + `/data` overlay), a113d (serial transport + env
discipline + hardened-S21 `updatem` vector), cv1835 (SSH pipe + p1 FIT),
am335x-bb.
- **M6 — GUI completeness.** Fleet view, install wizard with per-stage
progress/abort, audit log viewer, cross-platform packaging.
Each milestone ends with a bench validation run against the 9-board fleet
(none of which are live earners without explicit authorization).
**v0 scope note:** no alkaneOS build exists yet (SDK boards are in `bake`
status; no rootfs/fit/uImage outputs). v0 therefore ships discovery +
classification + stock<->stock installs + SD recovery; the alkaneOS target
activates the same pipeline with different artifact references.
## 8. Safety model (non-negotiables encoded at M0)
- `secure` partition writes are refused by the engine, not gated by the UI.
- Console-attached requirement: any stage that touches kernel/boot-adjacent
regions requires the operator to confirm a live serial console; the stage
is blocked otherwise (standing order: never flash blind; both bricks were
at the untestable U-Boot->kernel handoff).
- Production fleet protection: discovery excludes RFC1918 ranges not
explicitly enabled; no parallel auth attempts against a live earner.
- Teardown of a live earner requires explicit operator authorization in the
audit log (bench rule: always teardown .89/.106-class boards).
- Every artifact is verified (sha256 + format magic) before any byte is
written; verify-write on an independent channel after.
## 9. Open questions (for the operator)
1. GUI binding: proceed with Option A default, or run the Option B spike
first? (Plan assumes A with the spike as a cheap gate.)
2. Target OS matrix for GUI packaging: Linux + Windows + macOS all three?
3. "Install stock" set: which stock versions are canonical per board (the
bench corpus has asicto stock packages for S17; S19/S19j Pro/S19k Pro/S21
stock packages need collection or the vnish cdn mirror)?
4. alkaneOS artifact source: install waits on SDK board builds leaving
`bake` status — v0 ships stock-restore + discovery until then?
## 10. References
- `../alkane-sdk/main/docs/install-methods.md` (invariants)
- `../alkane-sdk/main/install/from-firmware/README.md` (pattern + root vectors)
- `../alkane-sdk/main/boards/` (board.yml: partitions, install capabilities)
- Bench wiki: `bench-wiki/boards/` (per-board install/restore evidence)
- Memory notes: `MEMORY-SNAPSHOT/` (firmware-flows-captured, whatsminer-*,
cb4-sd-boot-bixbit-ssh, aml-stock-live-capture)
- Tooling to port: `tools/net-scan.py`, `scratch/cb6-api-re/wm_package_builder.py`,
`scratch/wm-install-build/wm_install_client.py`, `scratch/wm-install-build/`
IMAGEWTY editors, `tools/luxos-inject-install.sh`
- Artifact seed manifest: `crates/alkane-artifacts/data/manifest-seed.csv`
- [SDK install rules](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/docs/install-methods.md)
- [SDK firmware recipes](https://gitea.bluefla.re/blueflare/alkane-sdk/src/branch/main/install/from-firmware/README.md)
- `bench-wiki/boards/` and `MEMORY-SNAPSHOT/` in the parent workspace
- `crates/alkane-artifacts/data/manifest-seed.csv`
- `scratch/wm-install-build/` package and IMAGEWTY builders in the parent workspace
+6 -6
View File
@@ -1,10 +1,10 @@
# UI Spec — primary view
# Primary view
Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
## Header (above the table)
## Header
- **KPI block, top left — 6 KPIs:**
- **KPI block, top left: 6 KPIs:**
1. Total miners
2. Hashing
3. Slow
@@ -31,7 +31,7 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
4. Cooling (fan)
5. Firmware
6. Pool worker account name
7. …then the remaining statistics in registry order.
7. Remaining statistics in registry order.
## Data sources
@@ -45,10 +45,10 @@ Source: operator description, 2026-09-15. Status: ACCEPTED (v1 scope).
ships with the board registry; missing band = excluded from Slow, counted
in Hashing).
## Implementation notes
## Implementation
- wxWidgets: the view is a `wxDataViewListCtrl`/`wxDataViewCtrl` (virtual
list — thousands of rows without materializing cells), checkbox column +
list for thousands of rows without materializing cells), checkbox column +
IP column fixed via attribute/serializer, drag reorder via `wxReorderable`
column events, sort via column header click events mapped to the model.
- Filter panel: per-column distinct-value checklist with text search,
+1 -1
View File
@@ -1,4 +1,4 @@
# ADR 0001: Recipes as data, interpreted by one engine
# ADR 0001: Recipe engine
Status: ACCEPTED
Date: 2026-09-14
+15 -29
View File
@@ -1,41 +1,27 @@
# ADR 0002: GUI bindings — wxWidgets shell in C++ + Rust core, spike to revisit
# ADR 0002: GUI bindings
Status: RESOLVED 2026-09-15 - the operator chose Option B (pure Rust via
wx-rs) with vendoring (ADR-0003). wx-rs 0.2.0 was extended via the patch
queue: Linux/GTK3 wx-config build path plus the widget bridge (panel,
sizers, static text, button, text ctrl, checkbox, checklistbox, dialog,
data view list ctrl, timer). The app ships this way; no C++ shell.
Date: 2026-09-14
Resolved: 2026-09-15
## Context
The toolkit must present a native cross-platform GUI (wxWidgets chosen).
Rust bindings to wxWidgets checked on crates.io 2026-09-14:
- `wxRust` 0.0.1-alpha — unmaintained since 2022.
- `wx-rs` 0.2.0 (2023, self-contained) — ~6k downloads, no 1.0.
Betting the GUI on alpha bindings risks weeks of binding-gap debugging
(paste-heavy widgets, worker threads + event loops, GTK/WinCocoa quirks).
The toolkit needs a native wxWidgets GUI. At the time of evaluation,
`wxRust` 0.0.1-alpha had seen no maintenance since 2022, and `wx-rs`
0.2.0 lacked widgets needed for the Toolkit.
## Decision
Default: **thin C++17 wxWidgets shell (`gui/`) + Rust core exposed over a
small stable C ABI** (cdylib from `alkane-core`, header generated with
cbindgen). The shell holds frames, lists, the install wizard, and event
glue only — no business logic, no safety logic. All invariants, engines,
and tests live in Rust where they are testable headlessly.
The operator chose a Rust GUI through a vendored, patched `wx-rs` 0.2.0.
The patch queue adds the Linux/GTK3 build path and bindings for panels,
sizers, controls, dialogs, data views, timers, and event dispatch. The
application uses this bridge; it has no separate C++ shell.
Gate: M0 runs a time-boxed `wx-rs` spike (window + list/tree + wizard flow
+ worker-thread progress + cancel on Linux and Windows). If the spike is
solid, flip to pure Rust; either way the decision is recorded before M3.
The original proposal was a small C++17 wxWidgets shell calling a Rust
core through a C ABI. The `wx-rs` spike met the GUI need, so that proposal
was not adopted.
## Consequences
- The repo builds two things: a Rust workspace and a small C++ app linked
against the core cdylib. CMake in `gui/`.
- Core API surface stays small and event-oriented (discover, identify,
plan, execute, cancel, progress events, log tail) — good FFI hygiene and
a natural match for the CLI too (D4).
- If wx-rs wins the spike, the C ABI is kept as an integration boundary for
scripted/HIL use anyway.
- Keep business logic and safety checks in testable Rust code.
- Carry wx-rs changes as numbered patches under `thirdparty/wx-rs/patches`.
- Recheck the bridge on Linux, Windows, and macOS packaging changes.
+2 -2
View File
@@ -1,4 +1,4 @@
# ADR 0003: Vendoring policy — pristine upstream archives + patch queue
# ADR 0003: Vendoring
Status: ACCEPTED
Date: 2026-09-15
@@ -42,7 +42,7 @@ thirdparty/
Rules:
1. Never edit a vendored pristine tree in place — every local change is a
1. Never edit a vendored pristine tree in place. Every local change is a
patch in `patches/`, applied by the build in numeric order. This makes
an upstream update: replace pristine archive, `git apply` surviving
patches, rebase the rest.
+21 -70
View File
@@ -1,76 +1,27 @@
# Aftermarket Toolkit Config + Scan Parity Roadmap
# Firmware parity
Scope: configuration and scanning/telemetry features only. Firmware flashing/installation
flows are out of scope except where a toolkit exposes config as part of them. This is a
plan document only; no repo source was edited and no live miner was mutated in producing it.
This plan covers configuration and telemetry parity. It excludes firmware
installation. The original audit was read-only and made no live miner changes.
Repo: `/home/noah/Ultron/projects/miner-firmware/alkane-toolkit`
It compares the Toolkit with Braiins Toolbox/BOS, LuxOS/luxminer, ePIC
PowerPlay/UMC, WhatsMinerTool/btminer, Vnish, and stock Antminer. Sources
include the Toolkit baseline audit, vendor API/help surfaces, and the
read-only device checks listed under [Verification](#verification).
Sources merged: baseline audit of alkane-toolkit today, plus gap-closed per-toolkit specs for
Braiins toolbox + Braiins OS REST API, LuxOS installer + luxminer :4028 JSON API, ePIC
rig-runner + PowerPlay/UMC OS REST API (:4028), and WhatsMiner (btminer :4028 read + :8889 /
4028-token write path, WhatsMinerTool feature surface).
At the audit point, Antminer support covered 15 of 58 features fully and
15 partially (about 39% weighted parity). WhatsMiner covered 12 of 30
fully and 5 partially (about 48%). Missing work centers on structured
tuning, cooling, fan control, auto-scaling, network settings, and CLI
coverage. The gap list below records each feature and its evidence.
---
## 1. Executive summary
Our toolkit already covers the universal fleet-management basics on every make: discovery and
make/model/firmware identification, core live telemetry (hashrate, expected hashrate, wattage,
efficiency, temps, fans, pools, messages, uptime, locate light), and seven capability-gated
write actions (fault light, pause, resume, restart, set power limit, set tuning percent,
configure pools). Those write actions are wired into the GUI right-click menu but are almost
entirely absent from the committed CLI (`miner_probe` at git HEAD has only `scan`; setpl / led /
setpools / msgs / hashrate are uncommitted local-only additions).
Where we fall short of the aftermarket toolkits is the deep configuration surface each firmware
exposes: structured autotuning (power/hashrate target, named presets, per-board overclock),
cooling/thermal configuration, fan control, DPS / perpetual-tune / ATM auto-scaling, network
config, timezone, change-password, factory reset, advanced keyed settings, and the richer scan
reads that feed those dialogs (constraints/limits tables, PSU info, per-chip health/frequency,
best-share, network config read). A recurring pattern: the asic-rs backend already implements a
setter (change_password, factory_reset, set_timezone_config, set_temperature_config, set
scaling/tuning config on some makes) but the GUI and CLI never surface it, so the gap is pure
UI/CLI wiring rather than new protocol work. The other recurring pattern is a scan read that is
fetched but discarded (BOS fan duty, per-pool extended stats, Lux per-chip health detail).
Headline parity (have = 1.0, partial = 0.5, missing = 0):
- Antminer (union across BOS / LuxOS / VNish / ePIC / stock, 58 distinct features):
have 15, partial 15, missing 28 -> weighted parity approximately 39%.
- WhatsMiner (WhatsMinerTool + btminer API, 30 distinct features):
have 12, partial 5, missing 13 -> weighted parity approximately 48%.
Biggest gaps, both makes: structured tuning (targets/presets/per-board), cooling + fan config,
DPS/ATM/perpetual-tune auto-scaling, and the CLI being effectively read-only today.
Top ~12 highest-priority gaps (detail in section 3):
1. Commit the full write CLI in `miner_probe` (light/pause/resume/restart/pools/power + new config verbs). CLI is read-only today; every UI action lacks a committed command.
2. Structured tuning: power target + hashrate target + tuner-mode + reset (BOS; stock Antminer / WhatsMiner mining-mode; unifies with per-make backends).
3. Named preset / profile select (LuxOS 21 profiles, VNish presets, ePIC tune-presets) via `SupportsPresets` + `SupportsTuningConfig::Preset`.
4. Cooling configuration (BOS cooling modes/temps/fan-pause; LuxOS tempctrl+fanctrl; ePIC fanspeed/shutdowntemp/critical-temp) - largest single missed config family.
5. Manual fan control (LuxOS fanset, ePIC fanspeed, antminer/epic backend `SupportsFanConfig`).
6. Auto-scaling: BOS DPS + LuxOS ATM + ePIC PerpetualTune (needs a dedicated auto-tuning config trait; ScalingConfig cannot carry it).
7. Per-board voltage/frequency override (LuxOS voltageset/frequencyset, ePIC /tune/clock + /tune/voltage) via `TuningTarget::Manual`.
8. Timezone config (BOS/VNish/ePIC backends complete; UI/CLI missing) - pure wiring.
9. Change password (BOS/VNish/antminer/ePIC backends complete; UI/CLI missing) - pure wiring; add for WhatsMiner (backend gap).
10. Factory reset (BOS/VNish/antminer backends complete; UI/CLI missing) + WhatsMiner restore_factory backend gap.
11. Best-share + session-best-share scan (two columns exist, no backend fills them; BOS/LuxOS/WhatsMiner summary all carry the value).
12. Network config read + write (all makes) and PSU-info scan (BOS/ePIC/WhatsMiner) - new core structs/traits.
File written: `/tmp/claude-1000/-home-noah/312805ea-e1aa-4f86-9144-632f3a9c1252/scratchpad/aftermarket-parity-roadmap.md`
---
## 2. Parity matrices
## Parity matrices
Legend: our_support = have / partial / missing. UI = exposed in GUI right-click menu today.
CLI = exposed in committed `miner_probe` today (uncommitted local-only additions are marked
`local`). Toolkit columns: B = Braiins toolbox/BOS, L = LuxOS/luxminer, V = VNish, E = ePIC/
PowerPlay, S = stock Antminer. A dot means that toolkit exposes the feature.
### 2a. Antminer parity matrix
### Antminer
Category C = config, T = telemetry/scan.
@@ -137,7 +88,7 @@ Category C = config, T = telemetry/scan.
Antminer totals: have 15, partial 15, missing 28 (of 58).
### 2b. WhatsMiner parity matrix
### WhatsMiner
Toolkit column W = WhatsMinerTool / btminer API (:4028 read + :8889 or 4028-token write).
btminer notes: :4028 is anonymous read-only; privileged writes go to :8889 (AES-ECB + md5-crypt
@@ -183,7 +134,7 @@ WhatsMiner totals: have 12, partial 5, missing 13 (of 30).
---
## 3. Prioritized gap list (missing + partial)
## Gaps
Each gap gives: asic-rs backend work, ui.rs ConfigAction / action wiring, miner_probe/CLI surface,
clean-integration note, hardware verification plan (IP/model + read-back + restore), and priority.
@@ -201,7 +152,7 @@ or a unit pulled from production during a maintenance window, NEVER on the live
that are read-only (BOS .83/.27, LuxOS .60/.67, ePIC .6/.10, the WhatsMiner fleet). Read paths
verify against those live units.
### PRIORITY: HIGH
### High priority
G1. Commit a full write CLI in miner_probe (all makes).
- Backend: none (reuse existing traits).
@@ -316,7 +267,7 @@ G9. Best share + session best share scan.
- HW verify: read-only vs live units, assert equals the API value. No restore.
- Priority: HIGH (cheap, two dead columns).
### PRIORITY: MEDIUM
### Medium priority
G10. Timezone config (BOS/VNish/ePIC).
- Backend: COMPLETE (SupportsTimezoneConfig; BOS GraphQL setTimezone, ePIC POST /timezone). No
@@ -411,7 +362,7 @@ G18. WhatsMiner power-mode set + set-power-percent + poweroff.
characterized on bench then power-cycle to recover. NEVER on the live fleet.
- Priority: MEDIUM.
### PRIORITY: LOW
### Low priority
G19. BOS advanced keyed settings (read + write, 22 keys with danger-gating).
- Backend: new AdvancedSettings trait (keyed map + static metadata: type/default/status/min_version/
@@ -450,7 +401,7 @@ G22. Diagnostics collect + firmware update-check surfacing + BOS custom-contract
---
## 4. Recommended implementation order (shippable rounds)
## Implementation order
Round A - CLI foundation and cheap wins (unblocks everything else):
- G1 (commit write CLI), G9 (best-share/session-best-share), G8 (constraints/limits/capabilities
@@ -481,7 +432,7 @@ Round F - network + advanced + long tail:
---
## 5. Verification coverage note
## Verification
Confirmed on real hardware, read-only, this run:
- Braiins OS: 10.4.1.83 and 10.4.1.27 (Antminer S19J Pro NoPic, BOS 26.09-plus, API 1.8.0). Verified