noahandClaude Opus 4.8 f63127d633 flash: restore uses the correct per-board device tree, not the package's
The kernel device tree is never in Bitmain's distributable firmware: all OTA
packages ship none, and the SD recovery image preserves the factory dtb rather
than writing one. The device tree I was taking from the SD recovery package was
its SD-boot dtb (a different partition layout), which does not match the genuine
rootfs and reboot-loops the board.

Fix: restore now takes only the genuine kernel + rootfs from the vendor package
(RestoreImages drops the dtb field), and the method supplies the correct
per-board device tree itself (fetched + verified from the public assets repo, the
same way the NAND-exposing helper is fetched). This pairs genuine kernel/rootfs
with the factory dtb that matches their partition layout. Any genuine package now
works (an OTA .tar.gz as well as an SD .zip), since the package's own dtb is no
longer needed.

cli/gui: --stock-firmware / the uninstall dialog no longer require a package with
a device tree. docs updated.

NOTE: not yet hardware-verified - the bench S17 is mid-recovery (serial-link
hardware issue) and must be brought back before this can be proven on the board.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-11 21:07:44 -06:00
2026-09-23 08:05:11 -06:00

Alkane Toolkit

CI tests coverage bench bench coverage lines of code code quality dependencies license

The badges link to the project site: the manual, the code-quality dashboard (how the grade is set, coverage by crate and file) and the benchmark history.

Desktop miner discovery and monitoring. The Rust GUI uses wxWidgets through a patched wx-rs bridge. In-app image flashing is disabled while that path is reworked.

Run locally

scripts/build-wx-linux.sh
scripts/build-gui-linux.sh
ALKANE_FAKE_SCAN=1 ~/.cache/alkane-tk-target/release/alkane-toolkit

The first command builds wxWidgets 3.3.3 once. Linux needs GTK 3. Fake scan uses offline fixtures and does not contact hardware.

Windows 10/11 builds are cross-compiled on Linux (scripts/build-wx-windows.sh, then scripts/build-gui-windows.sh) and attached to every release as a self-contained alkane-toolkit.exe; see docs/windows.md. macOS builds run on a Mac (scripts/build-wx-macos.sh, then scripts/build-gui-macos.sh) and produce one universal app for Apple Silicon and Intel, macOS 11 or later; see docs/macos.md.

Current scope

  • Discover miners by CIDR or IP range with vendored asic-rs.
  • Show model, firmware, health, hashrate, temperatures, fans, PSU, and workers.
  • Filter and sort the desktop table; inspect probes with miner_probe.
  • Use controls supported by the selected firmware and restore supported aftermarket firmware to stock.

Discovery is read-only. Control and restore actions change miners. Check the selected devices before applying them.

Headless .afw install (CV1835 and AM335x)

alkane-cli is the headless engine; the GUI uses the same engine. A verified .afw is a full OS bundle for exactly one board. The CV1835 installer writes only /dev/mmcblk0p1 over SSH, holds the current p1 first, reads the whole partition back, and reboots only after the read-back matches.

The AM335x installer writes mtd8 (type-3 ramdisk), mtd6 (dtb) and mtd7 (legacy kernel uImage) with flash_erase + nandwrite. It never touches mtd0-5 (SPL/U-Boot/bootenv), holds a backup of each target before writing it, and reads every target back before reboot. Its verify-live checks SSH (kernel string), the HTTP marker on port 80, the API on port 4028, and the eth0 DHCP lease.

alkane-cli afw verify BUNDLE.afw --allow-unsigned
alkane-cli afw plan BUNDLE.afw --host 10.255.1.167
alkane-cli afw preflight BUNDLE.afw --host 10.255.1.167
alkane-cli afw install BUNDLE.afw --host 10.255.1.167 --dry-run
alkane-cli afw install BUNDLE.afw --host 10.255.1.167 --confirm FLASH
alkane-cli afw verify-live BUNDLE.afw --host 10.255.1.167
alkane-cli afw restore --host 10.255.1.167 --held-backup p1.img --confirm FLASH

For AM335x the same subcommands infer the board from the bundle; restore names the three held copies explicitly:

alkane-cli afw plan BUNDLE.afw --host 10.255.1.64
alkane-cli afw preflight BUNDLE.afw --host 10.255.1.64
alkane-cli afw install BUNDLE.afw --host 10.255.1.64 --dry-run
alkane-cli afw install BUNDLE.afw --host 10.255.1.64 --confirm FLASH
alkane-cli afw verify-live BUNDLE.afw --host 10.255.1.64 --timeout 300
alkane-cli afw restore --board am335x --host 10.255.1.64 \
  --held-backup mtd8.img --held-kernel mtd7.img --held-dtb mtd6.img --confirm FLASH

On stock Bitmain CV1835 the SSH login is the unprivileged miner account; the toolkit obtains root through the stock update-daemon loopback channel, not a serial console. Credentials come only from ALKANE_BOARD_PASSWORD or ALKANE_BOARD_PASSWORD_FILE, or from --password-file / --identity-file. No credential value is printed. --allow-unsigned is bench-only; site use needs an Ed25519-signed bundle.

Development

WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config" \
  CARGO_TARGET_DIR="$HOME/.cache/alkane-tk-target" \
  cargo test -p alkane-gui --offline

Keep build output off the source share. main runs full CI and publishes qualifying releases; next builds -rc candidates. Badges measure host code, not installation support. See the benchmark history.

Firmware safety

Installation must follow the SDK install rules: use the exact board's packer and boot-switch procedure, verify through an independent channel, and never write bootloader or secure regions.

License

MIT. Vendored dependencies keep their own terms.

S
Description
Rust + wxWidgets cross-platform toolkit: install stock or alkaneOS on any ASIC miner
Readme MIT
92 MiB
v0.115.0
Latest
2026-11-17 00:03:11 -07:00
Languages
Rust 87.8%
Python 8.5%
Shell 3.5%
Dockerfile 0.2%