Compare commits

...
3 Commits
11 changed files with 139 additions and 164 deletions
+1 -1
View File
@@ -167,7 +167,7 @@ jobs:
python3 ci/gen-badges.py --tests "$PASS" \
--coverage "${{ steps.cov.outputs.pct }}" \
--bench-coverage "${{ steps.benchcov.outputs.pct }}" \
--bench-delta "$BENCH_DELTA"
--bench-delta "$BENCH_DELTA" --clippy clean
- name: Publish measured badges
env:
Generated
+1
View File
@@ -75,6 +75,7 @@ dependencies = [
"alkane-artifacts",
"alkane-core",
"sha2",
"tempfile",
"thiserror",
]
+39 -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,61 @@
![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. The code quality letter reports the
Clippy gate; the separate coverage badge reports exercised lines.
## 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.
+13 -12
View File
@@ -2,10 +2,11 @@
# Measure line coverage from BOTH the unit tests AND the headless UI self-test.
#
# The self-test (ALKANE_SELFTEST=1) builds the real wxWidgets table, renders every
# fixture through the real widgets, and checks each cell against the model -- it
# exercises most of ui.rs. Because it runs as a separate binary invocation, a plain
# `cargo llvm-cov` (which only runs the #[test]s) never counts it, so ui.rs shows
# ~4% even though it is integration-tested. This combines both runs' coverage.
# fixture through the real widgets, and checks each cell against the model.
# It covers the fixture-rendering path, while interactive event handlers need
# separate tests. Because it runs as a separate binary invocation, a plain
# `cargo llvm-cov` (which only runs the #[test]s) never counts it. This
# combines both runs' coverage.
#
# Usage: ci/coverage.sh [extra `cargo llvm-cov report` args, e.g. --summary-only]
set -euo pipefail
@@ -16,8 +17,12 @@ export WX_RS_WXCONFIG="${WX_RS_WXCONFIG:-$HOME/.cache/wx-3.3.3-linux/bin/wx-conf
# default; override with CARGO_LLVM_COV_FLAGS if you need something else.
read -ra CARGO_FLAGS <<<"${CARGO_LLVM_COV_FLAGS:---offline}"
# A display for the self-test's real widgets.
need_xvfb() { command -v xvfb-run >/dev/null 2>&1; }
# A display is required for the self-test; skipping it would publish an
# incomplete coverage number as if the measured test set had run.
if ! command -v xvfb-run >/dev/null 2>&1; then
echo "coverage.sh: xvfb-run is required for the UI self-test" >&2
exit 1
fi
cargo llvm-cov clean --workspace
@@ -27,12 +32,8 @@ cargo llvm-cov --no-report "${CARGO_FLAGS[@]}" \
-p alkane-artifacts -p alkane-flash -p alkane-cli
# 2. Headless UI self-test, under the same instrumentation, its coverage appended.
if need_xvfb; then
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
else
echo "coverage.sh: xvfb-run not found; skipping the self-test run (unit tests only)" >&2
fi
xvfb-run -a env GDK_BACKEND=x11 ALKANE_SELFTEST=1 \
cargo llvm-cov run --no-report "${CARGO_FLAGS[@]}" --bin alkane-toolkit
# 3. Merged report, our source only (vendored asic-rs + the patched wx-rs bridge
# are out of scope).
+5 -10
View File
@@ -131,15 +131,10 @@ def cov_color(pct: float) -> str:
return "red"
def quality_grade(clippy: str, coverage: float | None) -> str:
if clippy != "clean":
return "F"
if coverage is None:
def quality_grade(clippy: str | None) -> str:
if clippy is None:
return "pending"
for minimum, grade in ((90, "A"), (80, "B"), (70, "C"), (60, "D")):
if coverage >= minimum:
return grade
return "F"
return "A" if clippy == "clean" else "F"
def human(n: int) -> str:
@@ -170,7 +165,7 @@ def main() -> int:
# percentage string (e.g. "-3.2"), or "NEW"/"" when there is no baseline yet
# (round 19 #1). Takes precedence over --bench for the bench badge.
ap.add_argument("--bench-delta", default=None)
ap.add_argument("--clippy", default="clean")
ap.add_argument("--clippy", choices=("clean", "failed"))
args = ap.parse_args()
for value in (args.coverage, args.bench_coverage):
if value is not None and (not math.isfinite(value) or not 0 <= value <= 100):
@@ -191,7 +186,7 @@ def main() -> int:
write("loc", "lines of code", human(loc), loc_color(loc))
write("license", "license", lic, "blue")
write("dependencies", "dependencies", str(deps), "blue")
grade = quality_grade(args.clippy, args.coverage)
grade = quality_grade(args.clippy)
write("quality", "code quality", grade,
{"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
"D": "orange", "F": "red", "pending": "lightgrey"}[grade])
+1
View File
@@ -9,3 +9,4 @@ alkane-core = { path = "../alkane-core" }
alkane-artifacts = { path = "../alkane-artifacts" }
sha2.workspace = true
thiserror.workspace = true
tempfile = "3"
+55 -7
View File
@@ -4,7 +4,7 @@
use alkane_artifacts::VerifiedArtifact;
use sha2::{Digest, Sha256};
use std::io::{Read, Seek, SeekFrom};
use std::io::{Read, Seek, SeekFrom, Write};
use thiserror::Error;
pub struct PartitionSpec {
@@ -90,6 +90,34 @@ fn digest_bytes(hex: &str) -> Result<[u8; 32], FlashError> {
Ok(result)
}
fn stage_verified_artifact(
artifact: &mut VerifiedArtifact,
size: u64,
expected: [u8; 32],
) -> Result<std::fs::File, FlashError> {
let mut staged = tempfile::tempfile().map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
artifact
.reader()
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
let mut source = DigestReader {
inner: artifact.reader(),
remaining: size,
digest: Sha256::new(),
};
std::io::copy(&mut source, &mut staged).map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
if source.remaining != 0 || <[u8; 32]>::from(source.digest.finalize()) != expected {
return Err(FlashError::ArtifactChanged);
}
staged
.flush()
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
staged
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
Ok(staged)
}
struct DigestReader<'a> {
inner: &'a mut dyn Read,
remaining: u64,
@@ -145,6 +173,10 @@ pub fn write_verified<W: Writer, R: IndependentReadback>(
artifact
.revalidate()
.map_err(|_| FlashError::ArtifactChanged)?;
let expected = digest_bytes(&artifact.record().sha256)?;
// The source path may change while backup or transport I/O runs. Copy and
// verify it before any device write; the anonymous file is removed on drop.
let mut staged = stage_verified_artifact(artifact, size, expected)?;
let backup = writer
.backup(partition)
.map_err(|e| FlashError::Write(e.to_string()))?;
@@ -154,13 +186,8 @@ pub fn write_verified<W: Writer, R: IndependentReadback>(
{
return Err(FlashError::BackupIncomplete);
}
let expected = digest_bytes(&artifact.record().sha256)?;
artifact
.reader()
.seek(SeekFrom::Start(0))
.map_err(|e| FlashError::ArtifactIo(e.to_string()))?;
let mut stream = DigestReader {
inner: artifact.reader(),
inner: &mut staged,
remaining: size,
digest: Sha256::new(),
};
@@ -203,6 +230,7 @@ mod tests {
max_read: Option<u64>,
writes: usize,
contents: Vec<u8>,
mutate_source_on_write: Option<PathBuf>,
}
impl Writer for MockWriter {
@@ -231,6 +259,9 @@ mod tests {
_: u64,
) -> Result<(), Self::Error> {
self.writes += 1;
if let Some(path) = &self.mutate_source_on_write {
std::fs::write(path, b"PK\x03\x04changed").map_err(|_| "mutation failed")?;
}
if let Some(limit) = self.max_read {
image
.take(limit)
@@ -285,6 +316,7 @@ mod tests {
max_read: None,
writes: 0,
contents: Vec::new(),
mutate_source_on_write: None,
}
}
@@ -395,4 +427,20 @@ mod tests {
assert_eq!(writer.writes, 1);
std::fs::remove_file(path).unwrap();
}
#[test]
fn writes_verified_snapshot_when_source_changes_during_transport() {
let (path, mut image) = artifact("mutated-during-write");
let mut writer = writer();
writer.mutate_source_on_write = Some(path.clone());
let mut readback = MockReadback {
channel: "serial",
digest: digest_bytes(SHA).unwrap(),
};
let receipt = write_verified(&partition(), &mut image, &mut writer, &mut readback).unwrap();
assert_eq!(receipt.image_sha256, digest_bytes(SHA).unwrap());
assert_eq!(writer.contents, IMAGE);
assert_eq!(std::fs::read(&path).unwrap(), b"PK\x03\x04changed");
std::fs::remove_file(path).unwrap();
}
}
+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.