Simplify Toolkit docs and update installer status
build-test-release / release (push) Successful in 15m58s
build-test-release / release (push) Successful in 15m58s
This commit is contained in:
@@ -1,4 +1,4 @@
|
||||
# alkane-toolkit
|
||||
# Alkane Toolkit
|
||||
|
||||
[](https://gitea.bluefla.re/blueflare/alkane-toolkit/actions)
|
||||

|
||||
@@ -10,118 +10,60 @@
|
||||

|
||||

|
||||
|
||||
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
@@ -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
@@ -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,4 +1,4 @@
|
||||
# ADR 0001: Recipes as data, interpreted by one engine
|
||||
# ADR 0001: Recipe engine
|
||||
|
||||
Status: ACCEPTED
|
||||
Date: 2026-09-14
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user