gui: right-click install/uninstall of alkane-os via the self-contained engine

Wire the GUI to the toolkit's own compiled-in, network-only stock<->alkane engine
(alkane-flash::stock) and the .afw fetch/verify (alkane-artifacts), so a scanned
control board can be right-clicked to:

  - Install alkane OS (from stock): scans alkane-os releases on Gitea, picks one
    (newest first; pre-releases marked), downloads+verifies the .afw, and installs
    it onto each selected board over the network. Optional board password and an
    allow-unsigned (bench) toggle; typed FLASH confirmation.
  - Uninstall alkane OS (restore to stock): restores each selected board to
    genuine stock over the network, with the board's alkane root credential and a
    typed FLASH confirmation.

Both run on a background thread (stock_ops.rs), streaming progress/results to the
status bar, and share the exclusivity guards so they never race a scan/flash/
restore. These use the same engine the CLI drives; the GUI's older asic-rs
firmware-upload path stays disabled.

alkane-artifacts: add list_releases + fetch_afw_url for the release picker, and an
optional build-time embedded read-only token (option_env!("ALKANE_EMBEDDED_TOKEN"))
so a distributed GUI can scan the private alkane-os releases with no setup; the
env token still wins, and no secret is in the source tree.

wx-rs (vendored, patched): build on system wxWidgets 3.2 - guard the 3.3-only
wxApp::SetAppearance/Appearance behind wxCHECK_VERSION(3,3,0), and emit GTK's own
shared libs (pkg-config --libs gtk+-3.0) at link time since the widget bridge
calls GTK directly. Enables the Linux GUI release build.

docs/install.md: document the GUI actions and that the stock-assets repo is now
public (no token for install/restore; only release scanning needs one).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
This commit is contained in:
2026-11-11 14:18:24 -06:00
co-authored by Claude Opus 4.8
parent 27e1dc15e8
commit 82492231bc
9 changed files with 932 additions and 22 deletions
Generated
+2
View File
@@ -89,8 +89,10 @@ name = "alkane-gui"
version = "0.1.0"
dependencies = [
"aes",
"alkane-artifacts",
"alkane-core",
"alkane-discovery",
"alkane-flash",
"asic-rs",
"base64 0.21.7",
"ecb",
+146 -2
View File
@@ -10,7 +10,15 @@
//!
//! A private repo needs a token; it is read from the environment at run time
//! (`ALKANE_RELEASE_TOKEN`, else `GITEA_TOKEN`) and passed to curl through a
//! 0600 config file, never on the command line. No token is embedded or stored.
//! 0600 config file, never on the command line.
//!
//! As a convenience for the GUI, a read-only token can be baked into the binary
//! at build time by compiling with `ALKANE_EMBEDDED_TOKEN=<token>` set (see
//! `EMBEDDED_TOKEN`). The source tree carries no secret - the value lives only in
//! a binary built with that variable set - and the environment variables above
//! always take precedence, so a user can override it. When no such token is baked
//! in and none is in the environment, the token is simply absent (fine for public
//! repos; a private repo then returns 401/404).
use std::fs;
use std::path::{Path, PathBuf};
@@ -19,6 +27,14 @@ use std::process::Command;
use serde_json::Value;
use thiserror::Error;
/// A read-only Gitea token baked in at build time when the crate is compiled
/// with `ALKANE_EMBEDDED_TOKEN` set. `None` in an ordinary build (no secret in
/// the source tree). The environment variables win over this, so it is only a
/// fallback for a distributed binary (the GUI) that ships without asking the user
/// to configure a token. Scope it read-only on the server side; anyone with the
/// binary can extract it.
const EMBEDDED_TOKEN: Option<&str> = option_env!("ALKANE_EMBEDDED_TOKEN");
#[derive(Debug, Error)]
pub enum FetchError {
#[error("curl failed: {0}")]
@@ -51,7 +67,8 @@ impl ReleaseSource {
let token = std::env::var("ALKANE_RELEASE_TOKEN")
.ok()
.or_else(|| std::env::var("GITEA_TOKEN").ok())
.filter(|t| !t.is_empty());
.filter(|t| !t.is_empty())
.or_else(|| EMBEDDED_TOKEN.map(str::to_string).filter(|t| !t.is_empty()));
Self {
base_url,
owner: "blueflare".to_string(),
@@ -193,6 +210,101 @@ pub fn fetch_latest_afw(src: &ReleaseSource, board: &str, dest_dir: &Path) -> Re
Ok(dest)
}
/// One `.afw` asset in a release.
#[derive(Debug, Clone)]
pub struct AfwAsset {
pub name: String,
pub url: String,
}
/// A release as listed for the GUI's release picker: its tag/name, whether it is
/// a pre-release or draft, when it was published, and the `.afw` assets it holds.
#[derive(Debug, Clone)]
pub struct ReleaseInfo {
pub tag: String,
pub name: String,
pub prerelease: bool,
pub draft: bool,
pub published_at: String,
pub afw_assets: Vec<AfwAsset>,
}
impl ReleaseInfo {
/// The `.afw` asset for `board` in this release, if any (matched by the
/// `-<board>-` segment of the filename, as `pick_asset` does).
pub fn asset_for_board(&self, board: &str) -> Option<&AfwAsset> {
let needle = format!("-{board}-");
self.afw_assets.iter().find(|a| a.name.contains(&needle))
}
}
/// Parse a Gitea releases array (newest first) into `ReleaseInfo`s, keeping only
/// the `.afw` assets of each. Drafts are included so the caller can decide.
fn parse_releases(releases: &Value) -> Vec<ReleaseInfo> {
let mut out = Vec::new();
let Some(arr) = releases.as_array() else {
return out;
};
for release in arr {
let tag = release.get("tag_name").and_then(Value::as_str).unwrap_or("").to_string();
let name = release.get("name").and_then(Value::as_str).unwrap_or("").to_string();
let prerelease = release.get("prerelease").and_then(Value::as_bool).unwrap_or(false);
let draft = release.get("draft").and_then(Value::as_bool).unwrap_or(false);
let published_at = release
.get("published_at")
.or_else(|| release.get("created_at"))
.and_then(Value::as_str)
.unwrap_or("")
.to_string();
let mut afw_assets = Vec::new();
if let Some(assets) = release.get("assets").and_then(Value::as_array) {
for asset in assets {
let aname = asset.get("name").and_then(Value::as_str).unwrap_or("");
if aname.ends_with(".afw") {
if let Some(url) = asset.get("browser_download_url").and_then(Value::as_str) {
afw_assets.push(AfwAsset {
name: aname.to_string(),
url: url.to_string(),
});
}
}
}
}
out.push(ReleaseInfo {
tag,
name,
prerelease,
draft,
published_at,
afw_assets,
});
}
out
}
/// List the releases (newest first) of the source repo, each with its `.afw`
/// assets. Used by the GUI to scan alkane-os releases and pick one to install.
pub fn list_releases(src: &ReleaseSource) -> Result<Vec<ReleaseInfo>, FetchError> {
let body = curl_bytes(src, &src.api_list())?;
let releases: Value =
serde_json::from_slice(&body).map_err(|e| FetchError::Parse(e.to_string()))?;
Ok(parse_releases(&releases))
}
/// Download a specific release asset (by its `browser_download_url`) into
/// `dest_dir`, saving it under `name`; returns the written path.
pub fn fetch_afw_url(
src: &ReleaseSource,
name: &str,
url: &str,
dest_dir: &Path,
) -> Result<PathBuf, FetchError> {
fs::create_dir_all(dest_dir).map_err(|e| FetchError::Io(e.to_string()))?;
let dest = dest_dir.join(name);
curl_download(src, url, &dest)?;
Ok(dest)
}
#[cfg(test)]
mod tests {
use super::*;
@@ -223,4 +335,36 @@ mod tests {
assert_eq!(pick_asset(&releases, "zynq-7010"), Some(("alkane-os-0.1.0-zynq-7010-armv7.afw".into(), "u2".into())));
assert_eq!(pick_asset(&releases, "cv1835"), None);
}
#[test]
fn list_parses_releases_and_filters_afw_assets() {
let releases = serde_json::json!([
{"tag_name": "v0.2.0-bench1", "name": "bench", "prerelease": true, "draft": false,
"published_at": "2026-11-11T10:00:00Z", "assets": [
{"name": "SHA256SUMS", "browser_download_url": "s"},
{"name": "alkane-os-0.2.0-zynq-7010-armv7.afw", "browser_download_url": "z"},
]},
{"tag_name": "v0.1.0", "name": "", "prerelease": false, "draft": false,
"published_at": "2026-10-01T00:00:00Z", "assets": [
{"name": "alkane-os-0.1.0-am335x-arm.afw", "browser_download_url": "a"},
]},
]);
let parsed = parse_releases(&releases);
assert_eq!(parsed.len(), 2);
// Newest first; only .afw assets kept; SHA256SUMS dropped.
assert_eq!(parsed[0].tag, "v0.2.0-bench1");
assert!(parsed[0].prerelease);
assert_eq!(parsed[0].afw_assets.len(), 1);
// The board filter matches the -<board>- segment.
assert_eq!(
parsed[0].asset_for_board("zynq-7010").map(|a| a.url.as_str()),
Some("z")
);
assert!(parsed[0].asset_for_board("am335x").is_none());
assert_eq!(
parsed[1].asset_for_board("am335x").map(|a| a.name.as_str()),
Some("alkane-os-0.1.0-am335x-arm.afw")
);
assert!(parsed[1].asset_for_board("zynq-7010").is_none());
}
}
+5
View File
@@ -11,6 +11,11 @@ path = "src/main.rs"
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-discovery = { path = "../alkane-discovery" }
# The self-contained stock <-> alkane engine (compiled-in method) and the .afw
# verify/fetch, so the GUI can install-from-stock and restore-to-stock and scan
# alkane-os releases through the same code paths the CLI uses.
alkane-flash = { path = "../alkane-flash" }
alkane-artifacts = { path = "../alkane-artifacts" }
# vendored + patched wx-rs (see vendor/wx-rs/patches/)
wx-rs = { path = "../../thirdparty/wx-rs/wx-rs-0.2.0-patched" }
asic-rs = "0.8.1"
+1
View File
@@ -20,6 +20,7 @@ mod pool_prefs;
mod presets;
mod restore;
mod scan;
mod stock_ops;
mod ui;
fn main() {
+264
View File
@@ -0,0 +1,264 @@
//! Install alkane-os onto a board on stock, and restore an alkane board to
//! stock, from the GUI - using the toolkit's own self-contained, network-only
//! engine (`alkane_flash::stock`), the same code the CLI drives. There is NO
//! external helper and NO runtime AI dependency: the stock-crossing method is
//! compiled into this binary. The method body itself is authored and sealed
//! elsewhere; this module only calls its public interface and reports progress.
//!
//! Both operations are DESTRUCTIVE (they reflash the control board) and run on a
//! background thread so the reboot/flash latency never blocks the wx event loop.
//! Results stream back over a channel, drained by the UI timer tick exactly like
//! restore.rs. The UI gates each behind a typed-FLASH confirmation.
use std::path::PathBuf;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{channel, Receiver};
use std::sync::Arc;
use alkane_artifacts::afw::{verify_afw, VerifyOptions};
use alkane_artifacts::fetch::{self, ReleaseSource};
use alkane_flash::stock;
use crate::scan::fake_scan_enabled;
/// Control boards alkane-os can be installed onto from stock (mirrors the CLI's
/// `SUPPORTED`). Only these are offered as install targets.
pub const SUPPORTED_BOARDS: &[(&str, &str)] =
&[("zynq-7010", "Antminer S17 (Xilinx Zynq-7010 control board)")];
/// The default install board when the user has not chosen another.
pub const DEFAULT_BOARD: &str = "zynq-7010";
pub fn is_supported_board(board: &str) -> bool {
SUPPORTED_BOARDS.iter().any(|(b, _)| *b == board)
}
/// Where the `.afw` to install comes from: a local file the user picked, or a
/// release asset to download from Gitea (resolved on the worker thread so the
/// download never blocks the UI).
pub enum AfwChoice {
Local(PathBuf),
Release { name: String, url: String },
}
/// Progress + results streamed from the background worker to the UI.
pub enum StockMsg {
Started,
/// A human-readable status line for the status bar (acquiring, verifying...).
Progress(String),
/// One board's outcome.
Result { ip: String, ok: bool, detail: String },
Done,
}
pub struct StockHandle {
pub rx: Receiver<StockMsg>,
// Cancellation is honoured between boards; a UI stop control is not wired yet.
#[allow(dead_code)]
cancel: Arc<AtomicBool>,
}
impl StockHandle {
#[allow(dead_code)]
pub fn stop(&self) {
self.cancel.store(true, Ordering::Relaxed);
}
}
fn download_dir() -> PathBuf {
alkane_core::platform::config_path("downloads")
}
/// Install alkane-os onto the given boards (currently on stock), over the
/// network, via the compiled-in from-stock method. `board` is the target board
/// family (gates the `.afw`); `password`, if set, is passed in-process to the
/// method (never to the environment or an argument).
pub fn start_install(
ips: Vec<String>,
board: String,
source: AfwChoice,
allow_unsigned: bool,
password: Option<String>,
) -> StockHandle {
let (tx, rx) = channel();
let cancel = Arc::new(AtomicBool::new(false));
if fake_scan_enabled() {
let _ = tx.send(StockMsg::Started);
let _ = tx.send(StockMsg::Progress("install (demo): no hardware touched".into()));
for ip in ips {
let _ = tx.send(StockMsg::Result {
ip,
ok: true,
detail: "installed alkane-os (demo)".into(),
});
}
let _ = tx.send(StockMsg::Done);
return StockHandle { rx, cancel };
}
let tc = cancel.clone();
let err_tx = tx.clone();
let spawned = std::thread::Builder::new()
.name("install-from-stock".into())
.spawn(move || {
let _ = tx.send(StockMsg::Started);
// 1. Acquire the .afw (download the release asset if needed).
let _ = tx.send(StockMsg::Progress("acquiring .afw...".into()));
let afw_path = match source {
AfwChoice::Local(p) => p,
AfwChoice::Release { name, url } => {
match fetch::fetch_afw_url(&ReleaseSource::alkane_os(), &name, &url, &download_dir())
{
Ok(p) => p,
Err(e) => {
// One failure line per target so the UI clears its op-status.
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!("could not fetch .afw: {e}"),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
}
}
};
// 2. Verify + gate the bundle once (board/arch/bootloader + integrity).
let _ = tx.send(StockMsg::Progress("verifying .afw...".into()));
let verified = match verify_afw(
&afw_path,
&VerifyOptions {
allow_unsigned,
expect_board: Some(board.clone()),
},
) {
Ok(v) => v,
Err(e) => {
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!(".afw rejected: {e}"),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
};
if !is_supported_board(&verified.manifest.board) {
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!(
"{} is not a supported install target",
verified.manifest.board
),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
// 3. Install onto each board via the network-only from-stock method.
for ip in ips {
if tc.load(Ordering::Relaxed) {
break;
}
let _ = tx.send(StockMsg::Progress(format!(
"installing {} onto {ip} (from stock)...",
verified.manifest.board
)));
let (ok, detail) = match stock::install_from_stock(
&ip,
&afw_path,
&verified,
password.as_deref(),
) {
Ok(()) => (
true,
"installed alkane-os (verify liveness over the network)".to_string(),
),
Err(e) => (false, format!("install failed: {e}")),
};
if tx.send(StockMsg::Result { ip, ok, detail }).is_err() {
return;
}
}
let _ = tx.send(StockMsg::Done);
});
if spawned.is_err() {
let _ = err_tx.send(StockMsg::Result {
ip: String::new(),
ok: false,
detail: "could not start the install worker thread".into(),
});
let _ = err_tx.send(StockMsg::Done);
}
StockHandle { rx, cancel }
}
/// Restore the given alkane boards to genuine stock, over the network, via the
/// compiled-in restore-to-stock method. `password`, if set, is the board's
/// alkane root credential, passed in-process to the method.
pub fn start_restore(ips: Vec<String>, password: Option<String>) -> StockHandle {
let (tx, rx) = channel();
let cancel = Arc::new(AtomicBool::new(false));
if fake_scan_enabled() {
let _ = tx.send(StockMsg::Started);
for ip in ips {
let _ = tx.send(StockMsg::Result {
ip,
ok: true,
detail: "restored to stock (demo)".into(),
});
}
let _ = tx.send(StockMsg::Done);
return StockHandle { rx, cancel };
}
let tc = cancel.clone();
let err_tx = tx.clone();
let spawned = std::thread::Builder::new()
.name("restore-to-stock".into())
.spawn(move || {
let _ = tx.send(StockMsg::Started);
for ip in ips {
if tc.load(Ordering::Relaxed) {
break;
}
let _ = tx.send(StockMsg::Progress(format!(
"restoring {ip} to stock (network-only)..."
)));
let (ok, detail) = match stock::restore_to_stock(&ip, password.as_deref()) {
Ok(()) => (
true,
"restored to stock (verify independently it no longer answers as alkane)"
.to_string(),
),
Err(e) => (false, format!("restore failed: {e}")),
};
if tx.send(StockMsg::Result { ip, ok, detail }).is_err() {
return;
}
}
let _ = tx.send(StockMsg::Done);
});
if spawned.is_err() {
let _ = err_tx.send(StockMsg::Result {
ip: String::new(),
ok: false,
detail: "could not start the restore worker thread".into(),
});
let _ = err_tx.send(StockMsg::Done);
}
StockHandle { rx, cancel }
}
+444 -9
View File
@@ -5,6 +5,8 @@ use crate::credentials;
use crate::model::*;
use crate::restore;
use crate::scan::{self, ScanMsg};
use crate::stock_ops::{self, AfwChoice, StockMsg};
use alkane_artifacts::fetch::{self, ReleaseInfo, ReleaseSource};
use asic_rs::core::data::firmware::FirmwareImage;
use std::cell::RefCell;
use std::collections::{HashMap, HashSet};
@@ -96,6 +98,16 @@ const ID_RESTORE_CANCEL: i32 = 787;
const ID_CTX_POOLS: i32 = 736;
const ID_POOLS_OK: i32 = 788;
const ID_POOLS_CANCEL: i32 = 789;
// Alkane-OS self-contained install/uninstall (stock_ops.rs): put our first image
// onto a board on stock, and return an alkane board to stock, both via the
// toolkit's own compiled-in network-only engine. Typed-FLASH confirmation.
const ID_CTX_INSTALL_ALKANE: i32 = 770;
const ID_CTX_UNINSTALL_ALKANE: i32 = 771;
const ID_INSTALL_OK: i32 = 1006;
const ID_INSTALL_CANCEL: i32 = 1007;
const ID_INSTALL_RELEASE_CHOICE: i32 = 1008;
const ID_UNINSTALL_OK: i32 = 1009;
const ID_UNINSTALL_CANCEL: i32 = 1010;
// Pool-preset manager dialog (round 18 #8b): edit the whole saved list at once.
// NB: 790-795 belong to the language menu (ID_LANG_BASE + Lang index), so these
// live in a separate high block to avoid an id collision (round 18 #12).
@@ -810,6 +822,22 @@ pub struct App {
restore: Option<restore::RestoreHandle>,
restore_dialog: Widget,
pending_restore: Vec<restore::RestoreTarget>,
// Alkane-OS self-contained install/uninstall (stock_ops.rs): one background job
// (either direction) + the two typed-confirm dialogs and the state captured
// when a dialog opens (the scanned release list, target IPs, target board).
stock_op: Option<stock_ops::StockHandle>,
install_dialog: Widget,
install_release_choice: Widget,
install_pass_input: Widget,
install_unsigned_check: Widget,
install_confirm_input: Widget,
install_releases: Vec<ReleaseInfo>,
install_ips: Vec<String>,
install_board: String,
uninstall_dialog: Widget,
uninstall_pass_input: Widget,
uninstall_confirm_input: Widget,
uninstall_ips: Vec<String>,
// Configure-pools dialog (round 14 #7, expanded round 15 #1): 3 pool rows x 4
// fields (address, account, worker, password) = 12 text controls, indexed
// row*4 + field. Plus the "+" dropdown menu state.
@@ -1175,6 +1203,19 @@ pub fn build(frame: Widget) -> App {
restore: None,
restore_dialog: frame,
pending_restore: Vec::new(),
stock_op: None,
install_dialog: frame,
install_release_choice: frame,
install_pass_input: frame,
install_unsigned_check: frame,
install_confirm_input: frame,
install_releases: Vec::new(),
install_ips: Vec::new(),
install_board: stock_ops::DEFAULT_BOARD.to_string(),
uninstall_dialog: frame,
uninstall_pass_input: frame,
uninstall_confirm_input: frame,
uninstall_ips: Vec::new(),
pools_dialog: frame,
pool_fields: Vec::new(),
pool_menu_target: 0,
@@ -1664,10 +1705,10 @@ impl App {
format!("Open {n} miners in browser")
};
menu.menu_append(ID_CTX_OPEN, &open);
// While a firmware flash holds the exclusive lock, offer only the
// read-only "Open in browser" action; every network action is refused
// anyway, so don't dangle them in the menu.
if self.flashing {
// While a firmware flash or a stock install/restore holds the exclusive
// lock, offer only the read-only "Open in browser" action; every network
// action is refused anyway, so don't dangle them in the menu.
if self.flashing || self.stock_op.is_some() {
self.pending_popup = Some((t, menu));
return;
}
@@ -1758,6 +1799,17 @@ impl App {
// the vendor installers cover the current workflow. (ID_CTX_FLASH and the
// flash dialog remain in the code, just not surfaced here.)
let _ = ID_CTX_FLASH;
// Alkane OS install/uninstall via the toolkit's own self-contained,
// network-only engine (stock <-> alkane). Offered for any selection: the
// engine gates on board compatibility and a typed FLASH confirmation, so
// this is safe to surface without relying on asic-rs firmware detection
// (a board on genuine stock often does not identify cleanly).
menu.menu_append_separator();
menu.menu_append(ID_CTX_INSTALL_ALKANE, "Install alkane OS (from stock)...");
menu.menu_append(
ID_CTX_UNINSTALL_ALKANE,
"Uninstall alkane OS (restore to stock)...",
);
self.pending_popup = Some((t, menu));
}
@@ -2025,8 +2077,8 @@ impl App {
// This path sets self.action directly, so it needs start_action's full
// exclusivity guard: don't write pools during a restore or a live scan
// (round 18 #12).
if self.restore.is_some() {
wx_rs::set_status_text("restore-to-stock in progress -- wait for it to finish");
if self.restore.is_some() || self.stock_op.is_some() {
wx_rs::set_status_text("a stock install/restore is in progress -- wait for it to finish");
return;
}
if self.scanning {
@@ -2122,8 +2174,8 @@ impl App {
}
// A restore-to-stock is reverting + rebooting miners; a config action mid-
// revert could hit a unit in an undefined state (round 18 #12).
if self.restore.is_some() {
wx_rs::set_status_text("restore-to-stock in progress -- wait for it to finish");
if self.restore.is_some() || self.stock_op.is_some() {
wx_rs::set_status_text("a stock install/restore is in progress -- wait for it to finish");
return;
}
// A scan is opening its own connections to these same miners; a mutating
@@ -2358,6 +2410,7 @@ impl App {
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
{
wx_rs::set_status_text(
"busy (scan/action/restore in progress) -- try again once it finishes",
@@ -2441,6 +2494,373 @@ impl App {
let _ = oks;
}
/// True when any hardware-touching job is in flight. A new install/uninstall
/// must not start while a scan, config action, refresh, flash, restore, or
/// another stock op is running (they would race on the same boards).
fn hardware_busy(&self) -> bool {
self.flashing
|| self.scanning
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
}
/// Build the "Install alkane OS (from stock)" dialog: a scanned list of
/// alkane-os releases to pick from, an optional board credential, the
/// allow-unsigned (bench) toggle, and a typed FLASH confirmation. The install
/// runs over the network via the toolkit's own compiled-in from-stock engine.
fn build_install_dialog(&mut self) -> Option<Widget> {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
return None;
}
let ips = self.selected_ip_list();
if ips.is_empty() {
wx_rs::set_status_text("select a board to install onto");
return None;
}
let board = self.install_board.clone();
// Scan alkane-os releases from Gitea (newest first), keeping those that
// carry an .afw for this board. One quick API call, done synchronously so
// the picker is populated when the dialog opens.
wx_rs::set_status_text("scanning alkane-os releases...");
let releases: Vec<ReleaseInfo> = match fetch::list_releases(&ReleaseSource::alkane_os()) {
Ok(list) => list
.into_iter()
.filter(|r| !r.draft && r.asset_for_board(&board).is_some())
.collect(),
Err(e) => {
wx_rs::set_status_text(&format!("could not list releases: {e}"));
Vec::new()
}
};
self.install_releases = releases;
self.install_ips = ips.clone();
let frame = Widget::main_frame();
let dlg = Widget::dialog(frame, "Install alkane OS (from stock)");
let root = Widget::box_sizer(true);
let n = ips.len();
root.add(
Widget::static_text(
dlg,
&format!(
"Install alkane OS onto {n} board(s) currently on stock:\n{}",
ips.join(", ")
),
),
0,
sf::BORDER_ALL,
12,
);
root.add(
Widget::static_text(dlg, &format!("Target board: {board}")),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT,
12,
);
root.add(
Widget::static_text(dlg, "Release to install (newest first):"),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let choice = Widget::choice(dlg, ID_INSTALL_RELEASE_CHOICE);
if self.install_releases.is_empty() {
choice.choice_append("(no release with an .afw for this board was found)");
} else {
for (i, r) in self.install_releases.iter().enumerate() {
let tag = if r.tag.is_empty() {
r.name.as_str()
} else {
r.tag.as_str()
};
let kind = if r.prerelease { " [pre-release]" } else { "" };
let latest = if i == 0 { " (latest)" } else { "" };
let date = r.published_at.split('T').next().unwrap_or("");
choice.choice_append(&format!("{tag}{kind} {date}{latest}"));
}
choice.choice_set_selection(0);
}
root.add(choice, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.install_release_choice = choice;
root.add(
Widget::static_text(dlg, "Board password (optional):"),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let pass = Widget::text_ctrl(dlg, false);
root.add(pass, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.install_pass_input = pass;
// Current bench .afw files are unsigned (SHA-256 integrity, no Ed25519).
let unsigned = Widget::check_box(dlg, "Allow unsigned .afw (bench only)");
unsigned.set_checked(true);
root.add(unsigned, 0, sf::BORDER_ALL, 12);
self.install_unsigned_check = unsigned;
root.add(
Widget::static_text(
dlg,
"This reflashes the control board. Type FLASH to confirm:",
),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let confirm = Widget::text_ctrl(dlg, false);
root.add(confirm, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.install_confirm_input = confirm;
let btns = Widget::box_sizer(false);
btns.add_stretch(1);
btns.add(
Widget::button(dlg, "Install", ID_INSTALL_OK),
0,
sf::BORDER_ALL,
6,
);
btns.add(
Widget::button(dlg, "Cancel", ID_INSTALL_CANCEL),
0,
sf::BORDER_ALL,
6,
);
root.add_sizer(btns, 0, sf::EXPAND | sf::BORDER_ALL, 6);
root.set_sizer_on(dlg);
dlg.set_min_size(540, 440);
dlg.fit(dlg);
self.install_dialog = dlg;
wx_rs::set_status_text(&format!(
"{} release(s) available for {board}",
self.install_releases.len()
));
Some(dlg)
}
/// Apply the install confirmation: validate the typed keyword, resolve the
/// chosen release asset, and start the network-only from-stock install.
fn apply_install_confirm(&mut self) {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
self.install_dialog.close(0);
return;
}
if !flash_confirmed(&self.install_confirm_input.get_value()) {
wx_rs::set_status_text("type FLASH to confirm the install");
return;
}
let idx = self.install_release_choice.choice_get_selection();
if idx < 0 || self.install_releases.is_empty() {
wx_rs::set_status_text("no release selected");
return;
}
let board = self.install_board.clone();
let Some(release) = self.install_releases.get(idx as usize) else {
wx_rs::set_status_text("no release selected");
return;
};
let Some(asset) = release.asset_for_board(&board) else {
wx_rs::set_status_text("the selected release has no .afw for this board");
return;
};
let source = AfwChoice::Release {
name: asset.name.clone(),
url: asset.url.clone(),
};
let asset_name = asset.name.clone();
let allow_unsigned = self.install_unsigned_check.is_checked();
let password = {
let p = self.install_pass_input.get_value();
if p.is_empty() {
None
} else {
Some(p)
}
};
let ips = std::mem::take(&mut self.install_ips);
if ips.is_empty() {
self.install_dialog.close(0);
return;
}
self.install_dialog.close(1);
crate::logs::log(format!(
"install alkane OS onto {} board(s) from {}",
ips.len(),
asset_name
));
self.set_op_status(&ips, "installing...");
self.stock_op = Some(stock_ops::start_install(
ips,
board,
source,
allow_unsigned,
password,
));
}
/// Build the "Uninstall alkane OS (restore to stock)" dialog: the board's
/// alkane root credential and a typed FLASH confirmation.
fn build_uninstall_dialog(&mut self) -> Option<Widget> {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
return None;
}
let ips = self.selected_ip_list();
if ips.is_empty() {
wx_rs::set_status_text("select an alkane board to restore to stock");
return None;
}
self.uninstall_ips = ips.clone();
let frame = Widget::main_frame();
let dlg = Widget::dialog(frame, "Uninstall alkane OS (restore to stock)");
let root = Widget::box_sizer(true);
let n = ips.len();
root.add(
Widget::static_text(
dlg,
&format!(
"Restore {n} alkane board(s) to genuine stock:\n{}",
ips.join(", ")
),
),
0,
sf::BORDER_ALL,
12,
);
root.add(
Widget::static_text(dlg, "Board (alkane root) password (optional):"),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let pass = Widget::text_ctrl(dlg, false);
root.add(pass, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.uninstall_pass_input = pass;
root.add(
Widget::static_text(
dlg,
"This reflashes the board back to stock. Type FLASH to confirm:",
),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let confirm = Widget::text_ctrl(dlg, false);
root.add(confirm, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.uninstall_confirm_input = confirm;
let btns = Widget::box_sizer(false);
btns.add_stretch(1);
btns.add(
Widget::button(dlg, "Restore to stock", ID_UNINSTALL_OK),
0,
sf::BORDER_ALL,
6,
);
btns.add(
Widget::button(dlg, "Cancel", ID_UNINSTALL_CANCEL),
0,
sf::BORDER_ALL,
6,
);
root.add_sizer(btns, 0, sf::EXPAND | sf::BORDER_ALL, 6);
root.set_sizer_on(dlg);
dlg.set_min_size(480, 300);
dlg.fit(dlg);
self.uninstall_dialog = dlg;
Some(dlg)
}
fn apply_uninstall_confirm(&mut self) {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
self.uninstall_dialog.close(0);
return;
}
if !flash_confirmed(&self.uninstall_confirm_input.get_value()) {
wx_rs::set_status_text("type FLASH to confirm the restore");
return;
}
let password = {
let p = self.uninstall_pass_input.get_value();
if p.is_empty() {
None
} else {
Some(p)
}
};
let ips = std::mem::take(&mut self.uninstall_ips);
if ips.is_empty() {
self.uninstall_dialog.close(0);
return;
}
self.uninstall_dialog.close(1);
crate::logs::log(format!("restore {} alkane board(s) to stock", ips.len()));
self.set_op_status(&ips, "restoring...");
self.stock_op = Some(stock_ops::start_restore(ips, password));
}
/// Drain the alkane install/uninstall job: progress onto the status bar,
/// per-board results into the op-status, and finalisation on Done.
fn drain_stock_op(&mut self) {
let Some(h) = &self.stock_op else { return };
let mut done = false;
let mut oks = 0usize;
let mut fails: Vec<String> = Vec::new();
let mut op_clear: Vec<String> = Vec::new();
let mut progress: Option<String> = None;
loop {
match h.rx.try_recv() {
Ok(StockMsg::Started) => {}
Ok(StockMsg::Progress(s)) => progress = Some(s),
Ok(StockMsg::Result { ip, ok, detail }) => {
if !ip.is_empty() {
op_clear.push(ip.clone());
}
if ok {
oks += 1;
} else {
fails.push(format!("{ip}: {detail}"));
}
}
Ok(StockMsg::Done) => {
done = true;
break;
}
Err(std::sync::mpsc::TryRecvError::Empty) => break,
Err(std::sync::mpsc::TryRecvError::Disconnected) => {
done = true;
break;
}
}
}
for ip in &op_clear {
self.op_status.remove(ip);
}
if let Some(p) = progress {
wx_rs::set_status_text(&p);
}
if done {
self.stock_op = None;
self.op_status
.retain(|_, v| v != "installing..." && v != "restoring...");
}
if !op_clear.is_empty() || done {
self.fill_rows();
}
if done {
if !fails.is_empty() {
self.set_error_indicator(&format!("stock op: {} failed", fails.len()));
} else if oks > 0 {
wx_rs::set_status_text(&format!("stock op complete: {oks} ok"));
}
}
}
/// Start the access (lock-state) probe on the selected miners, using the
/// saved scan (web) credentials (defaulting to root/root if none are set).
fn start_access_probe(&mut self) {
@@ -2574,6 +2994,8 @@ impl App {
ID_CTX_ACCESS_PROBE => self.start_access_probe(),
ID_CTX_VIEW_LOG => self.start_log_fetch(),
ID_CTX_RESTORE_STOCK => return self.build_restore_confirm_dialog(),
ID_CTX_INSTALL_ALKANE => return self.build_install_dialog(),
ID_CTX_UNINSTALL_ALKANE => return self.build_uninstall_dialog(),
ID_CTX_POOLS => return self.build_pools_dialog(),
ID_CTX_FLASH => {
// A flash needs exclusive hardware access; don't even prompt if
@@ -2583,6 +3005,7 @@ impl App {
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
{
wx_rs::set_status_text(
"busy (scan/action in progress) -- try again once it finishes",
@@ -3071,6 +3494,7 @@ impl App {
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
{
wx_rs::set_status_text("busy (scan/action started) -- flash cancelled, try again");
return;
@@ -3651,6 +4075,7 @@ impl App {
self.drain_refresh();
self.drain_access_probe();
self.drain_restore();
self.drain_stock_op();
self.drain_report();
// A completed background log fetch yields a viewer dialog to show; return
// it so `dispatch` presents it modally after the App borrow is released
@@ -3722,7 +4147,7 @@ impl App {
// Symmetric to start_action's scan guard: don't start a scan (including an
// auto-rescan) while a config action or restore is writing to miners, so
// the two never race on the same unit (round 18 #12).
if self.action.is_some() || self.restore.is_some() {
if self.action.is_some() || self.restore.is_some() || self.stock_op.is_some() {
wx_rs::set_status_text("operation in progress -- scan deferred");
return false;
}
@@ -5177,6 +5602,16 @@ impl App {
self.pending_restore.clear();
self.restore_dialog.close(0);
}
ID_INSTALL_OK => self.apply_install_confirm(),
ID_INSTALL_CANCEL => {
self.install_ips.clear();
self.install_dialog.close(0);
}
ID_UNINSTALL_OK => self.apply_uninstall_confirm(),
ID_UNINSTALL_CANCEL => {
self.uninstall_ips.clear();
self.uninstall_dialog.close(0);
}
ID_POOLS_OK => self.apply_pools(),
ID_POOLS_CANCEL => self.pools_dialog.close(0),
// Pool-preset manager buttons (round 18 #8b).
+46 -11
View File
@@ -1,7 +1,13 @@
# Installing and removing alkane-os
The CLI (`alkane-cli afw ...`) is the supported flashing path. In-app (GUI)
flashing is disabled while that path is reworked; it will call the same engine.
Two front-ends drive the same self-contained engine:
- The CLI (`alkane-cli afw ...`), documented below, is the scriptable path.
- The GUI (`alkane-toolkit`) can scan the fleet, then right-click a board to
install alkane-os onto it from stock or restore it to stock. See
"GUI (right-click install / uninstall)" at the end. (The GUI's older asic-rs
firmware-upload path stays disabled; these two actions use the compiled-in
network-only engine, the same one the CLI uses.)
## Compatible miners
@@ -41,13 +47,12 @@ stock gates and getting root) is done by the toolkit itself, over the network.
The method is part of this binary; nothing else needs to be installed on your
machine. On first use it fetches a small set of per-board assets from our Gitea
(repo `blueflare/alkane-stock-assets`, release `zynq-7010-v1`) and caches them
locally, verifying each against a known SHA-256. That repo is private, so set a
Gitea token in the environment first (`ALKANE_RELEASE_TOKEN`, else
`GITEA_TOKEN`); it is passed to curl through a private 0600 config, never on the
command line. The asset base URL can be overridden with
locally, verifying each against a known SHA-256. That repo is public, so no token
is needed for the stock assets. The asset base URL can be overridden with
`ALKANE_STOCK_ASSETS_BASE`.
Add `--from-stock`:
Add `--from-stock` (the token below is only to resolve `--latest` from the
private alkane-os release repo; a local `.afw` needs no token):
```
export ALKANE_RELEASE_TOKEN=<your-gitea-token>
@@ -81,7 +86,37 @@ alkane-cli afw restore-stock --host <miner-ip> \
Returning an aftermarket board to genuine stock is also done by the toolkit
itself, over the network. It uses the same per-board assets (fetched/cached as
above, so the Gitea token is needed) and the board's alkane root credential
(`--password-file`, or `ALKANE_BOARD_PASSWORD`/`ALKANE_BOARD_PASSWORD_FILE`). You
then verify independently that the board no longer answers as alkane and
presents its stock OS.
above from the now-public assets repo, so no token is needed) and the board's
alkane root credential (`--password-file`, or
`ALKANE_BOARD_PASSWORD`/`ALKANE_BOARD_PASSWORD_FILE`). You then verify
independently that the board no longer answers as alkane and presents its stock
OS.
## GUI (right-click install / uninstall)
The GUI binary is `alkane-toolkit`. Launch it, let the scan list the fleet, then
right-click one or more boards and choose:
- "Install alkane OS (from stock)..." - scans the alkane-os releases on Gitea,
lets you pick one (newest first; pre-releases are marked), optionally takes a
board password and an "allow unsigned .afw (bench)" toggle, and - after you
type FLASH to confirm - downloads/verifies the `.afw` and installs it onto each
selected board over the network, via the same compiled-in from-stock engine the
CLI uses.
- "Uninstall alkane OS (restore to stock)..." - takes the board's alkane root
password and a typed FLASH confirmation, then restores each selected board to
genuine stock over the network.
Progress and per-board results appear on the status bar; verify board state
independently afterwards (the GUI does not claim liveness on its own).
Release scanning reads the private `alkane-os` repo, so it needs a Gitea token.
A read-only token can be baked into the GUI at build time
(`ALKANE_EMBEDDED_TOKEN=<token>` when building), so the shipped binary scans
releases with no setup; otherwise set `ALKANE_RELEASE_TOKEN` (or `GITEA_TOKEN`)
in the environment before launching. The stock-asset fetch needs no token (that
repo is public), so install-from-stock and restore-to-stock work without one -
only the release picker needs it.
Runtime dependencies (Linux): the GUI links wxWidgets 3.2 (wxGTK) and GTK 3, so
the target machine needs `libwxgtk3.2-1` and `libgtk-3-0` installed.
+19
View File
@@ -309,6 +309,25 @@ fn build_with_wx_config() -> Result<(), Box<dyn Error>> {
for f in gtk_cflags.split_whitespace() {
build.flag(f);
}
// ...and GTK's own shared libraries at link time. `wx-config --libs`
// lists only the wx libraries, not the GTK libraries the widget bridge
// calls directly (gtk_*, g_*), so without this the final link fails with
// undefined GTK symbols. Best-effort: empty if pkg-config/gtk3-dev is
// missing, in which case the GTK-only bridge code was also compiled out.
let gtk_libs = Command::new("pkg-config")
.args(["--libs", "gtk+-3.0"])
.output()
.ok()
.filter(|o| o.status.success())
.and_then(|o| String::from_utf8(o.stdout).ok())
.unwrap_or_default();
for f in gtk_libs.split_whitespace() {
if let Some(lib) = f.strip_prefix("-l") {
println!("cargo:rustc-link-lib={}", lib);
} else if let Some(path) = f.strip_prefix("-L") {
println!("cargo:rustc-link-search=native={}", path);
}
}
}
if is_windows() {
// Ship one self-contained .exe: link the C++ runtime statically rather
@@ -375,6 +375,10 @@ extern "C" {
// then returns CannotChange). System follows the desktop: the GTK theme's
// colour scheme, or the Windows 10/11 "app mode" setting, which wxMSW
// otherwise ignores and stays light. ALKANE_APPEARANCE=light|dark forces one.
// The explicit appearance API (wxApp::Appearance / SetAppearance /
// MSWEnableDarkMode) only exists in wxWidgets >= 3.3. On 3.2.x the GTK/Win
// system theme is still followed; we just cannot force it via ALKANE_APPEARANCE.
#if wxCHECK_VERSION(3, 3, 0)
{
wxString pref;
wxGetEnv("ALKANE_APPEARANCE", &pref);
@@ -394,6 +398,7 @@ extern "C" {
wxTheApp->SetAppearance(appearance);
#endif
}
#endif
wxTheApp->OnInit();
#ifdef __WINDOWS__