Merge pull request 'Own Pages site (manual, quality dashboard, benchmarks); remove internal notes' (#20) from repo-cleanup into main
build-test-release / windows (push) Successful in 7m8s
build-test-release / release (push) Successful in 15m41s

This commit is contained in:
2026-11-03 10:10:21 -07:00
28 changed files with 1095 additions and 205 deletions
-35
View File
@@ -1,35 +0,0 @@
name: public-benchmark-pages
on:
workflow_run:
workflows: [build-test-release]
types: [completed]
workflow_dispatch:
concurrency:
group: alkane-toolkit-public-benchmark-pages
cancel-in-progress: false
jobs:
publish:
runs-on: alkane-verify
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- name: Install SSH client
run: bash ci/ensure-build-deps.sh ssh
- name: Render measured benchmark history
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py render
- name: Publish public benchmark page
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
BENCH_PAGES_DEPLOY_KEY: ${{ secrets.BENCH_PAGES_DEPLOY_KEY }}
run: python3 ci/publish-bench-pages.py toolkit
- name: Clean generated page
if: always()
run: python3 ci/cleanup-generated.py
+47
View File
@@ -0,0 +1,47 @@
name: pages
# The project site, https://blueflare.gitea.bluefla.re/alkane-toolkit/ :
# overview, user manual (docs/manual), code-quality dashboard (from the
# quality record main CI publishes with the badges) and benchmark history.
# Rebuilt after every main build-test-release run and published to this
# repository's gh-pages branch.
on:
workflow_run:
workflows: [build-test-release]
types: [completed]
workflow_dispatch:
concurrency:
group: alkane-toolkit-pages
cancel-in-progress: false
jobs:
publish:
runs-on: alkane-verify
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
permissions:
contents: write
steps:
- uses: actions/checkout@v4
- name: Install page tools
run: bash ci/ensure-build-deps.sh pages
- name: Render measured benchmark history
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py render
- name: Fetch measured quality record
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/fetch-quality.py quality.json
- name: Build site
run: |
python3 ci/build-pages.py --out site --quality quality.json \
--bench bench-site/index.html --sha "$GITHUB_SHA"
- name: Publish site
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/publish-pages.py site
- name: Clean generated site
if: always()
run: python3 ci/cleanup-generated.py
+6 -3
View File
@@ -271,8 +271,10 @@ jobs:
set -euo pipefail
rustup component add llvm-tools-preview >/dev/null 2>&1 || true
[ "$(cargo llvm-cov --version)" = 'cargo-llvm-cov 0.8.7' ]
PCT=$(bash ci/coverage.sh --summary-only \
| awk '/^TOTAL/{gsub(/%/,"",$10); print $10}')
# Keep the whole table: gen-badges turns it into the per-crate and
# per-file breakdown on the Pages quality dashboard.
bash ci/coverage.sh --summary-only | tee coverage-summary.txt
PCT=$(awk '/^TOTAL/{gsub(/%/,"",$10); print $10}' coverage-summary.txt)
[ -n "$PCT" ] || { echo "coverage report produced no TOTAL line" >&2; exit 1; }
echo "pct=${PCT}" >> "$GITHUB_OUTPUT"
echo "line coverage (tests + self-test): ${PCT}%"
@@ -300,7 +302,8 @@ jobs:
python3 ci/gen-badges.py --tests "$PASS" \
--coverage "${{ steps.cov.outputs.pct }}" \
--bench-coverage "${{ steps.benchcov.outputs.pct }}" \
--bench-delta "$BENCH_DELTA" --clippy clean
--bench-delta "$BENCH_DELTA" --clippy clean \
--coverage-summary coverage-summary.txt
- name: Publish measured badges
env:
+5
View File
@@ -2,3 +2,8 @@
**/target
.claude/
__pycache__/
# Internal working notes live outside this public repository.
/AGENTS.md
/HANDOFF.md
/CLAUDE.md
code-review-report*.md
+14 -14
View File
@@ -1,17 +1,18 @@
# 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)
![coverage](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/coverage.svg)
![bench](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/bench.svg)
![bench coverage](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/bench-coverage.svg)
![lines of code](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/loc.svg)
![code quality](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/quality.svg)
![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)
[![tests](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/tests.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
[![coverage](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/coverage.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/#coverage)
[![bench](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/bench.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/bench/)
[![bench coverage](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/bench-coverage.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
[![lines of code](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/loc.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/#coverage)
[![code quality](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/quality.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
[![dependencies](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/dependencies.svg)](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/)
[![license](https://gitea.bluefla.re/blueflare/alkane-toolkit/raw/branch/ci-badges/badges/license.svg)](LICENSE)
The code quality grade reports GUI Clippy and first-party Rust formatting checks
from the last successful main build. Test coverage has a separate badge.
The badges link to the [project site](https://blueflare.gitea.bluefla.re/alkane-toolkit/): the [manual](https://blueflare.gitea.bluefla.re/alkane-toolkit/manual/),
the [code-quality dashboard](https://blueflare.gitea.bluefla.re/alkane-toolkit/quality/) (how the grade is set, coverage by
crate and file) and the [benchmark history](https://blueflare.gitea.bluefla.re/alkane-toolkit/bench/).
Desktop miner discovery and monitoring. The Rust GUI uses wxWidgets through
a patched [wx-rs bridge](thirdparty/wx-rs). In-app image flashing is disabled
@@ -42,8 +43,7 @@ macOS is not built.
aftermarket firmware to stock.
Discovery is read-only. Control and restore actions change miners. Check the
selected devices before applying them. See the [implementation plan](docs/IMPLEMENTATION-PLAN.md)
and [firmware matrix](docs/aftermarket-parity-roadmap.md) for planned coverage.
selected devices before applying them.
## Development
@@ -55,8 +55,8 @@ WX_RS_WXCONFIG="$HOME/.cache/wx-3.3.3-linux/bin/wx-config" \
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 public
[benchmark history](https://blueflare.gitea.bluefla.re/alkane-benchmarks/toolkit/).
code, not installation support. See the
[benchmark history](https://blueflare.gitea.bluefla.re/alkane-toolkit/bench/).
## Firmware safety
+293
View File
@@ -0,0 +1,293 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Build the Alkane Toolkit Pages site (served from this repo's gh-pages).
build-pages.py --out site [--manual docs/manual] [--quality quality.json]
[--bench bench-site/index.html] [--sha SHA]
Pages:
/ overview and downloads
/manual/ the user manual, one page per docs/manual/NN-name.md chapter
/quality/ code-quality dashboard from the measured quality.json that main
CI publishes next to the badges (ci/gen-badges.py)
/bench/ the measured benchmark history (ci/bench_history.py render)
Every value taken from CI data is HTML-escaped; the manual is Markdown written
in this repository.
"""
import argparse
import html
import json
import re
import shutil
from pathlib import Path
import markdown
REPO = "https://gitea.bluefla.re/blueflare/alkane-toolkit"
RELEASES = REPO + "/releases"
SECTIONS = (("", "Overview"), ("manual/", "Manual"), ("quality/", "Code quality"),
("bench/", "Benchmarks"))
CSS = """
:root { --bg:#ffffff; --fg:#1f2328; --muted:#59636e; --line:#d1d9e0; --card:#f6f8fa;
--accent:#d9822b; --link:#0969da; --good:#1a7f37; --warn:#9a6700; --bad:#cf222e; }
@media (prefers-color-scheme: dark) { :root { --bg:#0d1117; --fg:#e6edf3; --muted:#9198a1;
--line:#30363d; --card:#151b23; --link:#4493f8; --good:#3fb950; --warn:#d29922; --bad:#f85149; } }
* { box-sizing: border-box; }
body { margin:0; background:var(--bg); color:var(--fg);
font:16px/1.55 system-ui,-apple-system,"Segoe UI",Roboto,Ubuntu,sans-serif; }
a { color:var(--link); text-decoration:none; } a:hover { text-decoration:underline; }
header { border-bottom:1px solid var(--line); }
header .bar, main { max-width:1040px; margin:0 auto; padding:0 16px; }
header .bar { display:flex; align-items:center; gap:24px; height:56px; flex-wrap:wrap; }
header .brand { font-weight:700; color:var(--fg); display:flex; gap:8px; align-items:center; }
header .brand i { width:20px; height:20px; border-radius:5px; background:var(--accent); display:inline-block; }
header nav { display:flex; gap:18px; flex-wrap:wrap; }
header nav a { color:var(--muted); } header nav a.on { color:var(--fg); font-weight:600; }
main { padding:28px 16px 64px; }
h1 { font-size:1.9rem; margin:.2em 0 .4em; } h2 { margin-top:1.8em; border-bottom:1px solid var(--line); padding-bottom:.25em; }
code { background:var(--card); border:1px solid var(--line); border-radius:5px; padding:.1em .35em; font-size:.92em; }
pre { background:var(--card); border:1px solid var(--line); border-radius:8px; padding:12px; overflow:auto; }
pre code { border:0; padding:0; }
table { border-collapse:collapse; width:100%; margin:1em 0; display:block; overflow-x:auto; }
th, td { border:1px solid var(--line); padding:6px 10px; text-align:left; vertical-align:top; }
th { background:var(--card); }
td.num, th.num { text-align:right; font-variant-numeric:tabular-nums; white-space:nowrap; }
.cards { display:grid; grid-template-columns:repeat(auto-fill,minmax(180px,1fr)); gap:12px; margin:1.2em 0; }
.card { background:var(--card); border:1px solid var(--line); border-radius:10px; padding:14px; }
.card b { display:block; font-size:1.6rem; } .card span { color:var(--muted); font-size:.9rem; }
.good { color:var(--good); } .warn { color:var(--warn); } .bad { color:var(--bad); }
.bar-cell { min-width:120px; } .meter { height:8px; background:var(--line); border-radius:4px; overflow:hidden; }
.meter i { display:block; height:100%; }
.layout { display:grid; grid-template-columns:220px 1fr; gap:32px; }
.layout aside ol { padding-left:1.2em; margin:0; } .layout aside li { margin:.3em 0; }
.layout aside a.on { font-weight:600; color:var(--fg); }
@media (max-width:760px) { .layout { grid-template-columns:1fr; } }
.buttons a { display:inline-block; margin:4px 8px 4px 0; padding:8px 14px; border-radius:8px;
border:1px solid var(--line); background:var(--card); color:var(--fg); }
.buttons a.primary { background:var(--accent); border-color:var(--accent); color:#fff; }
footer { color:var(--muted); font-size:.85rem; margin-top:48px; }
"""
def page(title: str, body: str, depth: int, current: str, sha: str) -> str:
up = "../" * depth
nav = "".join(
f'<a href="{up}{path}"{" class=on" if path == current else ""}>{label}</a>'
for path, label in SECTIONS)
built = f"Built from {html.escape(sha[:10])}. " if sha else ""
return f"""<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>{html.escape(title)} - Alkane Toolkit</title>
<link rel="stylesheet" href="{up}style.css"></head>
<body><header><div class="bar"><a class="brand" href="{up}"><i></i>Alkane Toolkit</a>
<nav>{nav}<a href="{RELEASES}">Downloads</a><a href="{REPO}">Source</a></nav></div></header>
<main>{body}
<footer>{built}Alkane Toolkit is MIT licensed.</footer></main></body></html>
"""
def write(out: Path, rel: str, text: str) -> None:
path = out / rel
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(text, encoding="utf-8")
# ---- manual -----------------------------------------------------------------
def chapters(manual: Path) -> list[tuple[str, str, str]]:
"""(slug, title, markdown) for docs/manual/NN-slug.md, in file-name order."""
out = []
for path in sorted(manual.glob("[0-9][0-9]-*.md")):
text = path.read_text(encoding="utf-8")
m = re.search(r"^# (.+)$", text, re.M)
title = m.group(1).strip() if m else path.stem
out.append((path.stem[3:], title, text))
return out
def build_manual(out: Path, manual: Path, sha: str) -> None:
items = chapters(manual)
if not items:
raise SystemExit(f"no manual chapters in {manual}")
def toc(current: str) -> str:
links = "".join(
f'<li><a href="{slug}.html"{" class=on" if slug == current else ""}>'
f"{html.escape(title)}</a></li>" for slug, title, _ in items)
return f"<aside><ol>{links}</ol></aside>"
for slug, title, text in items:
# Chapters link to each other as NN-name.md in the repo; on the site
# they are name.html.
text = re.sub(r"\]\((?:\./)?[0-9][0-9]-([a-z0-9-]+)\.md(#[^)]*)?\)", r"](\1.html\2)", text)
body_html = markdown.markdown(text, extensions=["tables", "fenced_code", "toc"])
write(out, f"manual/{slug}.html",
page(title, f'<div class="layout">{toc(slug)}<article>{body_html}</article></div>',
1, "manual/", sha))
first = items[0][0]
listing = "".join(f'<li><a href="{s}.html">{html.escape(t)}</a></li>' for s, t, _ in items)
write(out, "manual/index.html",
page("Manual", f"<h1>Manual</h1><p>Start with "
f'<a href="{first}.html">{html.escape(items[0][1])}</a>.</p><ol>{listing}</ol>',
1, "manual/", sha))
# ---- quality dashboard ---------------------------------------------------------
def pct_class(pct: float | None) -> str:
if pct is None:
return ""
return "good" if pct >= 80 else "warn" if pct >= 40 else "bad"
def meter(pct: float) -> str:
colour = {"good": "var(--good)", "warn": "var(--warn)", "bad": "var(--bad)"}[pct_class(pct)]
return f'<div class="meter"><i style="width:{max(0.0, min(pct, 100.0)):.1f}%;background:{colour}"></i></div>'
def build_quality(out: Path, quality: dict | None, sha: str) -> None:
e = html.escape
if not quality:
write(out, "quality/index.html", page(
"Code quality", "<h1>Code quality</h1><p>No measurement has been published yet; "
"the next main build will fill this page.</p>", 1, "quality/", sha))
return
grade = str(quality.get("grade", "pending"))
cov = quality.get("coverage_pct")
bench_cov = quality.get("bench_coverage_pct")
delta = quality.get("bench_delta_pct")
def card(value: str, label: str, cls: str = "") -> str:
return f'<div class="card"><b class="{cls}">{value}</b><span>{label}</span></div>'
cards = "".join([
card(e(grade), "Quality grade", {"A": "good", "B": "good", "C": "warn"}.get(grade, "bad")),
card(e(str(quality.get("tests_passed", "-"))), "Tests passing", "good"),
card(f"{cov:.1f}%" if cov is not None else "-", "Line coverage", pct_class(cov)),
card(f"{bench_cov:.1f}%" if bench_cov is not None else "-", "Benchmark coverage", pct_class(bench_cov)),
card(e(str(quality.get("clippy") or "-")), "Clippy (warnings are errors)",
"good" if quality.get("clippy") == "clean" else "bad"),
card(e(str(quality.get("rustfmt") or "-")), "rustfmt", "good" if quality.get("rustfmt") == "clean" else ""),
card(f"{quality.get('loc', 0):,}", "Lines of Rust"),
card(e(str(quality.get("dependencies", "-"))), "Crates in Cargo.lock"),
card((f"{'+' if delta > 0 else ''}{delta:.1f}%" if delta is not None else "-"),
"Benchmarks vs previous" + (" (same inputs)" if quality.get("bench_same_inputs") else ""),
"" if delta is None else "good" if delta >= 2 else "" if delta > -2 else "warn"),
])
bands = ", ".join(f"{e(str(letter))} at {floor:.0f}% or more"
for floor, letter in quality.get("grade_bands", []))
grade_rule = (f"<p>The grade is F if Clippy or rustfmt fails on main. Otherwise it is the "
f"line-coverage band: {bands}, and F below that. The coverage badge uses the "
f"same bands for its colour, so the two never disagree.</p>")
crates = quality.get("coverage_by_crate", {})
loc = quality.get("loc_by_crate", {})
rows = []
for name in sorted(set(crates) | set(loc)):
c = crates.get(name)
if c and c["lines"]:
pct = 100.0 * (c["lines"] - c["missed"]) / c["lines"]
cov_cells = (f'<td class="num {pct_class(pct)}">{pct:.1f}%</td>'
f'<td class="bar-cell">{meter(pct)}</td>'
f'<td class="num">{c["lines"] - c["missed"]:,} / {c["lines"]:,}</td>')
else:
cov_cells = '<td class="num">-</td><td></td><td class="num">-</td>'
rows.append(f"<tr><td>{e(name)}</td>{cov_cells}<td class='num'>{loc.get(name, 0):,}</td></tr>")
crate_table = ("<table><tr><th>Crate</th><th class=num>Line coverage</th><th></th>"
"<th class=num>Covered lines</th><th class=num>Lines of Rust</th></tr>"
+ "".join(rows) + "</table>")
files = sorted(quality.get("coverage_by_file", []),
key=lambda r: (r["lines"] - r["missed"]) / r["lines"] if r["lines"] else 1)
file_rows = "".join(
f"<tr><td><code>{e(r['file'])}</code></td>"
f"<td class='num {pct_class(100.0 * (r['lines'] - r['missed']) / r['lines'])}'>"
f"{100.0 * (r['lines'] - r['missed']) / r['lines']:.1f}%</td>"
f"<td class='num'>{r['missed']:,}</td><td class='num'>{r['lines']:,}</td></tr>"
for r in files if r["lines"])
file_table = ("<table><tr><th>File (least covered first)</th><th class=num>Coverage</th>"
"<th class=num>Uncovered lines</th><th class=num>Lines</th></tr>"
+ file_rows + "</table>") if file_rows else ""
measured = str(quality.get("sha", ""))[:10]
of_build = f" (this page: <code>{e(measured)}</code>)" if measured else ""
body = f"""<h1>Code quality</h1>
<p>Measured by main CI on every build{of_build}:
unit tests, line coverage (unit tests plus the headless UI self-test), Clippy with
warnings as errors, and rustfmt. Windows builds run the same tests under Wine and
on real Windows 11.</p>
<div class="cards">{cards}</div>
<h2 id="grade">How the grade is set</h2>{grade_rule}
<h2 id="coverage">Coverage by crate</h2>{crate_table}
<h2 id="files">Coverage by file</h2>{file_table}
<p>The dependency count is every package in <code>Cargo.lock</code>, direct and
transitive. Lines of Rust count every <code>.rs</code> line under <code>crates/</code>,
tests included.</p>"""
write(out, "quality/index.html", page("Code quality", body, 1, "quality/", sha))
# ---- benchmarks + overview -------------------------------------------------------
def build_bench(out: Path, bench: Path | None, sha: str) -> None:
if bench is None or not bench.is_file():
write(out, "bench/index.html", page(
"Benchmarks", "<h1>Benchmarks</h1><p>No benchmark history yet.</p>", 1, "bench/", sha))
return
rendered = bench.read_text(encoding="utf-8")
# The history renderer emits a complete document; keep its body (and its
# own styles) under the site's header.
styles = "".join(re.findall(r"<style[^>]*>.*?</style>", rendered, re.S | re.I))
m = re.search(r"<body[^>]*>(.*)</body>", rendered, re.S | re.I)
inner = m.group(1) if m else rendered
text = page("Benchmarks", inner, 1, "bench/", sha)
write(out, "bench/index.html", text.replace("</head>", styles + "</head>", 1))
def build_index(out: Path, quality: dict | None, sha: str) -> None:
grade = html.escape(str((quality or {}).get("grade", "pending")))
body = f"""<h1>Alkane Toolkit</h1>
<p>Desktop discovery and monitoring for ASIC miners on your network: find every
miner in your IP ranges, see hashrate, power, temperatures, fans and hashboard
health at a glance, and run the controls each firmware supports.</p>
<div class="buttons"><a class="primary" href="{RELEASES}">Download for Windows or Linux</a>
<a href="manual/">Read the manual</a><a href="quality/">Code quality: {grade}</a>
<a href="bench/">Benchmarks</a></div>
<h2>Platforms</h2>
<ul><li><b>Windows 10 and 11</b> (x86_64): one signed, self-contained <code>alkane-toolkit.exe</code>.</li>
<li><b>Linux</b> (x86_64, GTK 3): one binary.</li></ul>
<p>Every release is built, tested and signed by CI from the public source.</p>"""
write(out, "index.html", page("Overview", body, 0, "", sha))
def main() -> None:
ap = argparse.ArgumentParser(description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--out", required=True)
ap.add_argument("--manual", default="docs/manual")
ap.add_argument("--quality", default=None)
ap.add_argument("--bench", default=None)
ap.add_argument("--sha", default="")
args = ap.parse_args()
out = Path(args.out)
if out.exists():
shutil.rmtree(out)
out.mkdir(parents=True)
quality = None
if args.quality and Path(args.quality).is_file():
quality = json.loads(Path(args.quality).read_text())
if not isinstance(quality, dict) or quality.get("schema") != 1:
raise SystemExit("unsupported quality.json")
(out / "style.css").write_text(CSS.strip() + "\n", encoding="utf-8")
build_index(out, quality, args.sha)
build_manual(out, Path(args.manual), args.sha)
build_quality(out, quality, args.sha)
build_bench(out, Path(args.bench) if args.bench else None, args.sha)
print(f"built {sum(1 for _ in out.rglob('*.html'))} pages in {out}")
if __name__ == "__main__":
main()
+3 -3
View File
@@ -32,12 +32,12 @@ def main() -> int:
print(f"{path.name}: {name} has a different runner image", file=sys.stderr)
return 1
pages = yaml.load(
(ROOT / ".gitea/workflows/bench-pages.yml").read_text(),
(ROOT / ".gitea/workflows/pages.yml").read_text(),
Loader=yaml.BaseLoader,
)
if (pages["on"]["workflow_run"]["workflows"] != ["build-test-release"]
or pages["jobs"]["publish"].get("runs-on") != "alkane-verify"):
print("Benchmark Pages must follow main CI on the trusted verifier", file=sys.stderr)
print("Pages must follow main CI on the trusted verifier", file=sys.stderr)
return 1
release = yaml.load(
(ROOT / ".gitea/workflows/release.yml").read_text(),
@@ -46,7 +46,7 @@ def main() -> int:
if release["jobs"]["release"].get("runs-on") != "alkane-ci":
print("Main release must use the dedicated Alkane build pool", file=sys.stderr)
return 1
if any("ci/publish-bench-pages.py" in step.get("run", "")
if any("ci/publish-pages.py" in step.get("run", "")
for step in release["jobs"]["release"]["steps"]):
print("Main release must not publish Pages from GARM", file=sys.stderr)
return 1
+3 -3
View File
@@ -9,9 +9,9 @@ import sys
ROOT = Path(__file__).resolve().parents[1]
DIRECTORIES = ("target", "dist", "coverage", "bench-site")
FILES = ("bench-current.txt",)
BADGE_FILES = ("bench-baseline.json", "bench-context.json")
DIRECTORIES = ("target", "dist", "coverage", "bench-site", "site")
FILES = ("bench-current.txt", "coverage-summary.txt", "quality.json")
BADGE_FILES = ("bench-baseline.json", "bench-context.json", "quality.json")
def cleanup() -> None:
+1 -1
View File
@@ -46,7 +46,7 @@ vendor/*|thirdparty/asic-rs/*)
# resources, embedded assets). ui.rs/fixtures.rs/bin
# match the UI arm above first, so they still bump Z, not Y.
backend=true ;;
*) : ;; # docs, HANDOFF, README, thirdparty/wxwidgets tree: no bump
*) : ;; # docs, README, thirdparty/wxwidgets tree: no bump
esac
done <<< "$changed"
+2 -1
View File
@@ -3,11 +3,12 @@
# Use the preinstalled CI image or install missing packages on older runners.
set -euo pipefail
mode="${1:?usage: ensure-build-deps.sh base|ui|all|ssh|windows}"
mode="${1:?usage: ensure-build-deps.sh base|ui|all|ssh|windows|pages}"
case "$mode" in
base) packages=(libssl-dev pkg-config ca-certificates) ;;
ui) packages=(xvfb xauth dbus-x11 fonts-dejavu-core) ;;
ssh) packages=(openssh-client) ;;
pages) packages=(python3-markdown) ;;
all) packages=(libssl-dev pkg-config ca-certificates openssh-client
xvfb xauth dbus-x11 fonts-dejavu-core) ;;
# Windows cross build (mingw-w64, posix threads) + Wine for its tests.
+41
View File
@@ -0,0 +1,41 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Download the measured quality record (badges/quality.json on ci-badges).
fetch-quality.py OUT.json
Writes nothing (and exits 0) when main CI has not published one yet, so the
Pages build shows a "not measured yet" dashboard instead of failing.
"""
import base64
import json
import os
from pathlib import Path
import sys
from urllib.error import HTTPError
from urllib.request import Request, urlopen
def main() -> None:
out = Path(sys.argv[1])
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
url = f"{api}/repos/{repo}/contents/badges/quality.json?ref=ci-badges"
request = Request(url, headers={"Authorization": f"token {os.environ['GITEA_TOKEN']}"})
try:
with urlopen(request, timeout=20) as response:
content = base64.b64decode(json.load(response)["content"])
except HTTPError as error:
if error.code == 404:
print("No quality record published yet")
return
raise
if not isinstance(json.loads(content), dict):
sys.exit("invalid quality record")
out.write_bytes(content)
print(f"Fetched quality record ({len(content)} bytes)")
if __name__ == "__main__":
main()
+97 -8
View File
@@ -135,10 +135,66 @@ def cov_color(pct: float) -> str:
return "red"
def quality_grade(clippy: str | None) -> str:
if clippy is None:
# Code-quality grade (shown on the badge and explained on the Pages quality
# dashboard). Lint failures fail the grade outright; otherwise the grade is the
# measured line-coverage band, using the same bands as the coverage badge
# colour, so the two badges can never disagree.
GRADE_BANDS = ((80.0, "A"), (60.0, "B"), (40.0, "C"), (20.0, "D"))
GRADE_COLORS = {"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
"D": "orange", "F": "red", "pending": "lightgrey"}
def quality_grade(clippy: str | None, coverage: float | None = None) -> str:
if clippy is None or (clippy == "clean" and coverage is None):
return "pending"
return "A" if clippy == "clean" else "F"
if clippy != "clean":
return "F"
for floor, grade in GRADE_BANDS:
if coverage >= floor:
return grade
return "F"
def coverage_by_file(summary_path: str | None, root: str) -> list[dict]:
"""Per-file line coverage from a `cargo llvm-cov --summary-only` table.
Columns: Filename, Regions, Missed Regions, Cover, Functions, Missed
Functions, Executed, Lines, Missed Lines, Cover, ...
"""
if not summary_path:
return []
rows = []
root_abs = os.path.abspath(root).rstrip("/") + "/"
for line in Path(summary_path).read_text(errors="replace").splitlines():
cols = line.split()
if len(cols) < 10 or cols[0] in ("Filename", "TOTAL") or not cols[0].endswith(".rs"):
continue
try:
lines, missed = int(cols[7]), int(cols[8])
except ValueError:
continue
name = cols[0][len(root_abs):] if cols[0].startswith(root_abs) else cols[0]
rows.append({"file": name, "lines": lines, "missed": missed})
return rows
def crate_of(path: str) -> str:
parts = Path(path).parts
if "crates" in parts and parts.index("crates") + 1 < len(parts):
return parts[parts.index("crates") + 1]
if "wx-rs-0.2.0-patched" in parts:
return "wx-rs (bridge)"
return "other"
def loc_by_crate(root: str) -> dict[str, int]:
out: dict[str, int] = {}
crates = Path(root) / "crates"
for path in sorted(crates.glob("*/**/*.rs")):
crate = path.relative_to(crates).parts[0]
with open(path, encoding="utf-8", errors="ignore") as fh:
out[crate] = out.get(crate, 0) + sum(1 for _ in fh)
return out
def human(n: int) -> str:
@@ -169,6 +225,9 @@ def main() -> int:
# percentage string, or "NEW" when there is no baseline.
ap.add_argument("--bench-delta", default=None)
ap.add_argument("--clippy", choices=("clean", "failed"))
# The full `cargo llvm-cov --summary-only` table, for the per-crate and
# per-file breakdown in quality.json (the Pages quality dashboard).
ap.add_argument("--coverage-summary", default=None)
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):
@@ -189,11 +248,9 @@ 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)
write("quality", "code quality", grade,
{"A": "brightgreen", "B": "yellowgreen", "C": "yellow",
"D": "orange", "F": "red", "pending": "lightgrey"}[grade],
f"code quality: {grade} (GUI Clippy and first-party rustfmt)")
grade = quality_grade(args.clippy, args.coverage)
write("quality", "code quality", grade, GRADE_COLORS[grade],
f"code quality: {grade} (Clippy, rustfmt and line coverage)")
if args.tests is not None:
write("tests", "tests", f"{args.tests} passing", "brightgreen")
if args.coverage is not None:
@@ -228,6 +285,38 @@ def main() -> int:
write("bench", "bench", "baseline set", "blue")
elif args.bench is not None:
write("bench", "bench", args.bench, "blue")
# Everything above, plus the per-crate breakdowns, for the Pages quality
# dashboard (ci/build-pages.py).
files = coverage_by_file(args.coverage_summary, args.root)
crates: dict[str, dict] = {}
for row in files:
c = crates.setdefault(crate_of(row["file"]), {"lines": 0, "missed": 0})
c["lines"] += row["lines"]
c["missed"] += row["missed"]
quality = {
"schema": 1,
"sha": os.environ.get("GITHUB_SHA", ""),
"grade": grade,
"grade_bands": [[floor, letter] for floor, letter in GRADE_BANDS],
"clippy": args.clippy,
"rustfmt": "clean" if args.clippy is not None else None,
"tests_passed": args.tests,
"coverage_pct": args.coverage,
"bench_coverage_pct": args.bench_coverage,
"bench_delta_pct": delta,
"bench_same_inputs": same_inputs,
"loc": loc,
"loc_by_crate": loc_by_crate(args.root),
"dependencies": deps,
"license": lic,
"coverage_by_crate": crates,
"coverage_by_file": files,
}
path = os.path.join(args.root, args.out, "quality.json")
with open(path, "w", encoding="utf-8") as fh:
json.dump(quality, fh, indent=1, sort_keys=True)
print(f"wrote {path}")
return 0
-121
View File
@@ -1,121 +0,0 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish a measured benchmark page to the public, data-only Pages repo."""
import argparse
import json
import os
from pathlib import Path
import shlex
import subprocess
import tempfile
from urllib.request import Request, urlopen
PAGES_REPO = "ssh://git@gitea.bluefla.re:2222/blueflare/alkane-benchmarks.git"
GUARD_REPO = "https://gitea.bluefla.re/blueflare/alkane-benchmarks.git"
GUARD_COMMIT = "ea160545c49bc419a245692deda8dd7db7a611eb"
PAGES_HOST = "gitea.bluefla.re"
PAGES_HOST_FINGERPRINT = "SHA256:lqB5cmC9E5HNeg/lkzdOwQ++I8A70Wx7lnNs6liN24g"
PAGES_HOST_KEY = "[gitea.bluefla.re]:2222 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO1II6NkmRW+QAd+Wj+7qbNrA8Oo+/N/WRog4hELskn/"
def run(*args: str, env: dict[str, str] | None = None,
cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
return subprocess.run(args, env=env, cwd=cwd, text=True,
capture_output=True, check=True)
def current_main_sha() -> str:
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
request = Request(f"{api}/repos/{repo}/branches/main",
headers={"Authorization": f"token {token}"})
with urlopen(request, timeout=20) as response:
branch = json.load(response)
return branch["commit"]["id"]
def publish(site: str) -> None:
if os.environ.get("GITHUB_REF") != "refs/heads/main":
raise ValueError("benchmark Pages publication requires main")
sha = os.environ["GITHUB_SHA"]
if current_main_sha() != sha:
print("Skipping benchmark page from a superseded main commit")
return
page = Path("bench-site/index.html").read_bytes()
if not page.startswith(b"<!doctype html>") or len(page) > 1_048_576:
raise ValueError("invalid benchmark page")
with tempfile.TemporaryDirectory(prefix="alkane-pages-") as directory:
temporary = Path(directory)
guard_checkout = temporary / "guard"
run("git", "clone", "--quiet", "--single-branch", "--branch", "next",
GUARD_REPO, str(guard_checkout))
guard_source = run("git", "show", f"{GUARD_COMMIT}:ci/validate_site.py",
cwd=guard_checkout).stdout
guard_script = temporary / "validate_site.py"
guard_script.write_text(guard_source)
run("python3", str(guard_script), "--page", site,
str(Path("bench-site/index.html").resolve()))
key = os.environ["BENCH_PAGES_DEPLOY_KEY"]
if not key.startswith("-----BEGIN OPENSSH PRIVATE KEY-----"):
raise ValueError("missing benchmark Pages deploy key")
key_path = temporary / "deploy_key"
key_path.write_text(key.rstrip("\n") + "\n")
key_path.chmod(0o600)
known_hosts = temporary / "known_hosts"
known_hosts.write_text(PAGES_HOST_KEY + "\n")
fingerprint = run("ssh-keygen", "-lf", str(known_hosts)).stdout.split()[1]
if fingerprint != PAGES_HOST_FINGERPRINT:
raise ValueError("benchmark Pages SSH host key changed")
git_env = os.environ.copy()
ssh_command = (f"ssh -i {shlex.quote(str(key_path))} -o IdentitiesOnly=yes "
f"-o UserKnownHostsFile={shlex.quote(str(known_hosts))} "
"-o StrictHostKeyChecking=yes -o ConnectTimeout=10")
git_env["GIT_SSH_COMMAND"] = ssh_command
git_env["GIT_TERMINAL_PROMPT"] = "0"
checkout = temporary / "site"
run("git", "clone", "--quiet", "--single-branch", "--branch", "gh-pages",
PAGES_REPO, str(checkout), env=git_env)
run("git", "config", "user.name", "Alkane CI", cwd=checkout)
run("git", "config", "user.email", "ci@bluefla.re", cwd=checkout)
for attempt in range(3):
if current_main_sha() != sha:
print("Skipping benchmark page from a superseded main commit")
return
run("git", "fetch", "--quiet", "origin", "gh-pages", env=git_env,
cwd=checkout)
run("git", "checkout", "-q", "-B", "bench-publish", "origin/gh-pages",
cwd=checkout)
destination = checkout / site / "index.html"
destination.parent.mkdir(exist_ok=True)
destination.write_bytes(page)
run("git", "add", f"{site}/index.html", cwd=checkout)
changed = subprocess.run(("git", "diff", "--cached", "--quiet"),
cwd=checkout, check=False)
if changed.returncode == 0:
print(f"{site} benchmark page is already current")
return
if changed.returncode != 1:
raise RuntimeError("cannot compare benchmark page")
run("git", "commit", "-q", "-m",
f"Update {site} benchmarks for {sha[:10]} [skip ci]", cwd=checkout)
pushed = subprocess.run(("git", "push", "--quiet", "origin",
"HEAD:gh-pages"), env=git_env, cwd=checkout,
text=True, capture_output=True, check=False)
if pushed.returncode == 0:
print(f"Published {site} benchmark page for {sha[:10]}")
return
if attempt == 2:
raise RuntimeError(f"benchmark Pages push failed: {pushed.stderr.strip()}")
raise RuntimeError("benchmark Pages publication did not complete")
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("site", choices=("sdk", "os", "toolkit"))
publish(parser.parse_args().site)
if __name__ == "__main__":
main()
+9 -1
View File
@@ -2,6 +2,7 @@
# SPDX-License-Identifier: MIT
"""Publish measured toolkit badges to the private Gitea badge branch."""
import json
import os
from pathlib import Path
@@ -22,7 +23,14 @@ def main() -> None:
raise ValueError(f"invalid {name} SVG")
publish_file(api, repo, f"badges/{name}.svg", data, token,
f"Update measured {name} badge")
print(f"Published {len(NAMES)} measured badge SVGs")
# The full measurement record behind the badges, read by the Pages
# quality dashboard (ci/build-pages.py).
data = (ROOT / "badges" / "quality.json").read_bytes()
if not isinstance(json.loads(data), dict):
raise ValueError("invalid quality.json")
publish_file(api, repo, "badges/quality.json", data, token,
"Update measured quality record", max_bytes=262_144)
print(f"Published {len(NAMES)} measured badge SVGs and quality.json")
if __name__ == "__main__":
+79
View File
@@ -0,0 +1,79 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish the built Pages site to this repository's gh-pages branch.
publish-pages.py SITE_DIR
Served at https://blueflare.gitea.bluefla.re/alkane-toolkit/ by the Pages
server, which serves the gh-pages branch of public repositories. Each publish
is one orphan commit (force-pushed), so the branch never accumulates history.
Only main may publish, and a run for a superseded main commit skips.
"""
import json
import os
from pathlib import Path
import shutil
import subprocess
import sys
import tempfile
from urllib.request import Request, urlopen
BRANCH = "gh-pages"
MAX_BYTES = 20 * 1024 * 1024
def current_main_sha(api: str, repo: str, token: str) -> str:
request = Request(f"{api}/repos/{repo}/branches/main",
headers={"Authorization": f"token {token}"})
with urlopen(request, timeout=20) as response:
return json.load(response)["commit"]["id"]
def git(*args: str, cwd: Path, env: dict | None = None) -> None:
subprocess.run(("git", *args), cwd=cwd, env=env, check=True)
def main() -> None:
if len(sys.argv) != 2:
sys.exit(__doc__)
site = Path(sys.argv[1])
if not (site / "index.html").is_file():
sys.exit(f"{site} has no index.html")
size = sum(p.stat().st_size for p in site.rglob("*") if p.is_file())
if size > MAX_BYTES:
sys.exit(f"site is {size} bytes, over the {MAX_BYTES} byte limit")
for path in site.rglob("*"):
if path.is_file() and path.suffix not in {".html", ".css", ".svg", ".png", ".json"}:
sys.exit(f"unexpected file type on the site: {path}")
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
sha = os.environ["GITHUB_SHA"]
token = os.environ["GITEA_TOKEN"]
if os.environ.get("GITHUB_REF") != "refs/heads/main":
sys.exit("Pages publication requires main")
if current_main_sha(api, repo, token) != sha:
print("Skipping Pages for a superseded main commit")
return
server = api.removesuffix("/api/v1")
with tempfile.TemporaryDirectory(prefix="alkane-pages-") as directory:
work = Path(directory)
shutil.copytree(site, work, dirs_exist_ok=True)
env = dict(os.environ, GIT_TERMINAL_PROMPT="0")
git("init", "-q", "-b", BRANCH, cwd=work)
git("-c", "user.name=Alkane CI", "-c", "user.email=ci@noreply.gitea.bluefla.re",
"add", "-A", cwd=work)
git("-c", "user.name=Alkane CI", "-c", "user.email=ci@noreply.gitea.bluefla.re",
"commit", "-q", "-m", f"Publish site for {sha[:10]} [skip ci]", cwd=work)
# The token is read from the environment by the credential helper at
# push time; it never appears on a command line or in the remote URL.
helper = '!f() { echo username=alkane-ci; echo "password=$GITEA_TOKEN"; }; f'
git("-c", f"credential.helper={helper}", "push", "-q", "--force",
f"{server}/{repo}.git", f"HEAD:refs/heads/{BRANCH}", cwd=work, env=env)
print(f"Published Pages for {sha[:10]} to {BRANCH}")
if __name__ == "__main__":
main()
+30 -10
View File
@@ -5,6 +5,7 @@
import importlib.util
import re
from pathlib import Path
import tempfile
import unittest
@@ -50,16 +51,35 @@ class BenchBadgeTests(unittest.TestCase):
self.assertEqual(gen_badges.bench_color(30.0), "brightgreen")
self.assertEqual(gen_badges.bench_color(-55.5555556), "orange")
def test_quality_grade_is_only_the_clippy_result(self):
self.assertEqual(gen_badges.quality_grade("clean"), "A")
self.assertEqual(gen_badges.quality_grade("failed"), "F")
self.assertEqual(gen_badges.quality_grade(None), "pending")
svg = gen_badges.badge_svg(
"code quality", "A", "brightgreen",
"code quality: A (GUI Clippy and first-party rustfmt)",
)
self.assertIn('aria-label="code quality: A (GUI Clippy and first-party rustfmt)"', svg)
self.assertIn('>A</text>', svg)
def test_quality_grade_follows_lint_and_coverage(self):
# A lint failure fails the grade; otherwise it is the coverage band,
# with the same floors as the coverage badge colour.
self.assertEqual(gen_badges.quality_grade("failed", 95.0), "F")
self.assertEqual(gen_badges.quality_grade("clean", 85.0), "A")
self.assertEqual(gen_badges.quality_grade("clean", 65.6), "B")
self.assertEqual(gen_badges.quality_grade("clean", 48.0), "C")
self.assertEqual(gen_badges.quality_grade("clean", 25.0), "D")
self.assertEqual(gen_badges.quality_grade("clean", 5.0), "F")
self.assertEqual(gen_badges.quality_grade("clean"), "pending")
self.assertEqual(gen_badges.quality_grade(None, 90.0), "pending")
for pct in (85.0, 65.6, 48.0, 25.0):
grade = gen_badges.quality_grade("clean", pct)
self.assertEqual(gen_badges.GRADE_COLORS[grade], gen_badges.cov_color(pct))
def test_coverage_table_is_split_by_crate(self):
with tempfile.TemporaryDirectory(prefix="alkane-cov-") as directory:
summary = Path(directory) / "summary.txt"
summary.write_text(
"Filename Regions Missed Regions Cover Functions Missed Functions "
"Executed Lines Missed Lines Cover\n"
"crates/alkane-gui/src/ui.rs 10 5 50.00% 4 2 50.00% 100 60 40.00%\n"
"crates/alkane-core/src/platform.rs 4 0 100.00% 2 0 100.00% 50 5 90.00%\n"
"TOTAL 14 5 64.29% 6 2 66.67% 150 65 56.67%\n")
rows = gen_badges.coverage_by_file(str(summary), directory)
self.assertEqual([r["file"] for r in rows],
["crates/alkane-gui/src/ui.rs", "crates/alkane-core/src/platform.rs"])
self.assertEqual(rows[0]["missed"], 60)
self.assertEqual(gen_badges.crate_of(rows[1]["file"]), "alkane-core")
if __name__ == "__main__":
+3 -3
View File
@@ -1,6 +1,6 @@
//! Bench-fleet fixtures: the expected hardware output of the 9 boards on
//! 10.255.1.0/24 (see ../../../HANDOFF.md section 7 and the parent project's
//! [removed]). These are the reference values the workflow tests compare
//! Fixture fleet: the expected hardware output of nine representative miners
//! (one per control-board family / firmware). These are the reference values
//! the workflow tests compare
//! the application's actual output against, and the rows the offline
//! `ALKANE_FAKE_SCAN` demo mode renders. Only miners that respond become rows,
//! so there is no synthetic "offline" fixture.
+55
View File
@@ -0,0 +1,55 @@
# Getting started
Alkane Toolkit finds the ASIC miners on your network and shows them in one
table: model, firmware, hashrate, power, temperatures, fans and the health of
every hashboard. From the same table you can run the controls each miner's
firmware supports, such as pausing, restarting or changing pools.
## Download
Get the latest release from the
[downloads page](https://gitea.bluefla.re/blueflare/alkane-toolkit/releases).
| Platform | File | Notes |
|---|---|---|
| Windows 10 and 11 (x86_64) | `alkane-toolkit-vX.Y.Z-windows-x86_64.zip` | One signed `alkane-toolkit.exe`; nothing to install |
| Linux (x86_64) | `alkane-toolkit-vX.Y.Z-linux-x86_64.tar.gz` | One binary; needs GTK 3 (`sudo apt install libgtk-3-0`) |
### Windows
1. Download the zip, right-click it, choose **Properties**, tick **Unblock** if
it is shown, then extract it.
2. Run `alkane-toolkit.exe`. Windows shows *BlueFlare Energy Solutions Inc.* as
the verified publisher. To check the signature yourself, right-click the exe,
choose **Properties** and open **Digital Signatures**.
### Linux
```sh
tar xzf alkane-toolkit-vX.Y.Z-linux-x86_64.tar.gz
./alkane-toolkit-vX.Y.Z-linux-x86_64/alkane-toolkit
```
## First run
The toolkit starts a scan as soon as it opens. Set your own ranges first with
**Scan ranges** (see [Scanning](02-scanning.md)); until you do, it scans a
built-in default range.
To look around without touching any miner, start it in demo mode. It shows a
built-in sample fleet and simulates every action:
| Platform | Command |
|---|---|
| Windows (Command Prompt) | `set ALKANE_FAKE_SCAN=1 && alkane-toolkit.exe` |
| Linux | `ALKANE_FAKE_SCAN=1 ./alkane-toolkit` |
## Where settings are kept
| Platform | Folder |
|---|---|
| Windows | `%APPDATA%\alkane-toolkit` |
| Linux | `~/.config/alkane-toolkit` |
See [Settings and credentials](06-settings.md) for the files in that folder.
Deleting the folder resets the toolkit to its defaults.
+51
View File
@@ -0,0 +1,51 @@
# Scanning
Discovery is read-only: a scan asks each address what it is and records what
it reports. It never changes a miner.
## Scan ranges
Click **Scan ranges** to edit the addresses to scan. Put one entry per line;
blank lines and lines starting with `#` are ignored.
| Form | Example | Scans |
|---|---|---|
| Single address | `192.168.1.50` | that address |
| CIDR block | `192.168.1.0/24` | the whole block |
| Full range | `192.168.1.10-192.168.2.40` | every address between the two, inclusive |
| Short range | `192.168.1.10-90` | `.10` to `.90` within the same /24 |
| Per-octet ranges | `10.1-4.0-1.1-255` | every combination (10.1.0.1 ... 10.4.1.255) |
Commas or spaces between several entries on one line are not accepted; use one
line each. Duplicates are removed automatically. One line, and all lines
together, may cover at most 1,000,000 addresses.
**Apply** saves the ranges and starts a scan. A mistake keeps the dialog open
and the status bar explains it, for example `invalid range: bad octet range`.
The same dialog has three numbers:
| Field | Meaning | Default |
|---|---|---|
| Rescan (s) | seconds between automatic rescans; `0` turns auto-rescan off | 300 |
| Timeout (s) | how long to wait for one miner (scans, refreshes, actions and log fetches) | 10 |
| Concurrency | how many addresses are probed at once (8 to 256); higher is faster but slow miners may report fewer values | 128 |
When the ranges change, miners outside the new ranges leave the table at the
next scan.
## Running, pausing and stopping
The three buttons next to **Scan ranges** control scanning:
- **Play** (green) turns auto-rescan on and starts a scan now if none is running.
- **Pause** (amber) turns auto-rescan off and lets the current scan finish.
- **Stop** (red) turns auto-rescan off and cancels the current scan.
While a scan runs, a progress bar spans the top of the table and the status bar
shows progress such as `1935/4590 - scanning 192.168.1.86 (92 found)`. Afterwards
it shows the count and the time to the next scan, for example
`245 miners - next scan in 4m 12s`.
Actions that change miners wait for the scan to finish; see
[Actions](05-actions.md).
+80
View File
@@ -0,0 +1,80 @@
# The table and header
## Summary cards
The cards at the top count the miners **currently shown** (after any filter).
Each miner is in exactly one status: slow, paused, hashing or not hashing.
| Card | Counts | Click |
|---|---|---|
| Total | rows in the view | - |
| Hashing (green rabbit) | mining at 80% of expected hashrate or more | show only these; click again to clear |
| Slow (amber turtle) | mining below 80% of expected hashrate | show only these |
| Not hashing (red glass) | answering but not mining | show only these |
| Paused (blue otter) | stopped on purpose (paused, stopped, suspended) | show only these |
| SHA-256 Hashrate | total hashrate, per algorithm | switch algorithm when the fleet runs more than one |
| Est. power | total reported power draw | - |
On a narrow window the hashrate and power cards are hidden.
## Columns
IP is always the first column. The default view shows Model, Health,
Hashrate, Power, Chip temp, Firmware, CPU, Access and Light. More than seventy
other columns are available, grouped as Identity, Firmware and board, Health
and status, Performance, Temperature, Cooling, Hardware and Pools.
- **Columns** opens a checklist: tick to show, drag to reorder, or sort the list
alphabetically or by category. *Hide columns with no scanned values* hides
columns that are empty for every miner (it resets when the app restarts).
- Drag a column header to move it.
- Right-click a header to sort by it, auto-size one or all columns, hide it, or
open the column chooser.
Some values worth knowing:
| Column | Shows |
|---|---|
| Hashrate | actual/expected, for example `95.0T/96.0T`; the actual part is red at 50% of expected or less, amber around 75%, green at 100% |
| Chip temp | hottest chip on each hashboard, for example `77 / 64 / 74`; blue when cool, red at 90 C and above |
| Firmware | the firmware family, coloured (Braiins purple, LuxOS gold, VNish green, ePIC light blue, Hiveon orange, Bixbit pink); stock firmware uses the normal text colour |
| Pool account / Worker | the pool user split at the first dot |
| Board HR / V / freq | per-hashboard hashrate, voltage and frequency |
A blank cell means the miner did not report that value.
## Sorting
Click a header to sort ascending, again for descending, again to clear.
- **Hashrate** also sorts by *relative* hashrate (actual as a share of
expected), shown as `%^` and `%v` in the header.
- **Health** sorts by overall health, then by power (`Pwr`), fans (`Fan`) and
hashboards (`Brd`). Ascending puts the most broken miners first.
## Selecting miners
Click a row to select it; Ctrl-click and Shift-click add to the selection, and
you can drag across rows to select a block. The selection follows miners by IP,
so it survives rescans. Double-click a row (or press Enter) to open the miner's
web page in your browser. Right-click the selection for [actions](05-actions.md).
## Filters and presets
**Filter** keeps only the rows that match. Pick a column, then:
- for numbers: between, =, !=, >, >=, < or <= (blank cells never match);
- for text: *is any of* (tick values; `(blank)` matches empty cells), contains,
does not contain, begins with, ends with or equals (case does not matter).
Filters on different columns must all match. **Reset** clears them. Clicking a
status card is a quick filter of its own.
**Presets** saves and loads whole views: column order and visibility, sort and
filters. *Default* is built in and cannot be deleted; saving under an existing
name replaces it.
## Zoom and theme
The slider in the bottom-right corner zooms the table: text, icons and column
widths scale together. The window follows the system light or dark theme.
+54
View File
@@ -0,0 +1,54 @@
# Health, access and light
## The Health column
Each miner gets a row of icons, always in the same order, so problems line up
across the table:
1. **Bolt**: the power supply
2. **Brain**: the control board
3. **Fan**: one icon per fan
4. **Chip**: one icon per hashboard
Hover over any icon to see its details: PSU voltage and current, the fan speed,
or a hashboard's actual and expected hashrate, frequency and voltage, and any
fault message with its code.
| Colour | Meaning |
|---|---|
| Green | healthy |
| Amber | working but below par (a slow board, a fan well below the others, a PSU fault while still mining) |
| Red | detected but down (a faulted board, a stopped fan, a PSU that is not delivering) |
| Grey | expected but not detected or not reachable |
| Blue | the miner is paused, so its boards and stopped fans are idle on purpose |
How each part is judged:
- **Power** is green when the miner draws power, its PSU fan turns or it is
mining; a reported PSU fault makes it amber (still mining) or red.
- **Control board** is red for a control-board fault and amber for a
miner-wide warning such as a high ambient temperature.
- **Fans** are red at 0 rpm and amber below half the speed of the fastest fan.
- **Hashboards** follow the status the miner reports for each board. When the
firmware names the failing boards, only those turn red. A board the miner
cannot see is grey.
While an action runs on a miner, its Health cell shows progress such as
`restarting...` or `refreshing...`.
## Access
The padlock shows whether the toolkit can change the miner:
- **green, open**: changes are possible with the saved credentials;
- **red, closed**: view only;
- **blank**: not known yet.
After a scan the padlock is an estimate from what the firmware offers. Use
**Check access (auth)** in the right-click menu for a real, read-only login
test.
## Light
A flashing green-over-red dot means the miner's locate light is on. Turn it on
or off with **Flash lights** / **Stop flashing lights**.
+60
View File
@@ -0,0 +1,60 @@
# Actions
Right-click one or more selected miners for the actions menu. With several
miners selected, labels show the count, for example *Restart (12)*. An action
appears only when **every** selected miner's firmware supports it, so the menu
changes with the selection.
| Action | What it does | Changes the miner |
|---|---|---|
| Open in browser | opens each miner's web page | no |
| Refresh | re-reads just these miners | no |
| Check access (auth) | tests whether the saved login is accepted | no |
| View log (API)... | shows the first selected miner's log (WhatsMiner: its active fault codes) | no |
| Restore to stock firmware... | removes aftermarket firmware; see [Restore to stock](07-restore.md) | yes, reboots |
| Flash lights / Stop flashing lights | locate light on or off | yes, harmless |
| Pause mining / Resume mining | stop or start hashing | yes |
| Set tuning %... | tuning level, 0 to 100 | yes |
| Set power target... | power target in watts; the prompt shows the current value and the allowed range | yes |
| Set hashrate target... | hashrate target in TH/s, for firmware that tunes by hashrate | yes |
| Set profile... | pick a firmware profile or preset (only profiles every selected miner has are listed) | yes |
| Restart | reboot | yes |
| Configure pools... | set up to three pools | yes |
| Set timezone... | IANA time zone, for example `America/Edmonton` | yes |
| Change password... | new web/API password | yes |
| Factory reset... | wipes pools, tuning and network settings and reboots; the miner may come back on a new DHCP address | yes, destructive |
## Safety
- Pause, Resume, Restart and Factory reset ask for confirmation. Value prompts
(tuning, targets, timezone, password) apply when you confirm the value.
- Actions that change miners do not start while a scan is running, including an
automatic rescan. Wait for it to finish or press **Pause**. Scans in turn wait
for running actions.
- Each changed miner is re-read automatically when the action finishes. Results
and failures appear in the bottom-right corner of the status bar and in
**Settings > Logs**.
- If **Change password** succeeds on every selected miner, the saved global
login is updated to the new password. If only some succeed, the saved login
is left alone and the log says so.
## Configuring pools
The pool dialog has three rows: Address, Account, Worker and Password. A row is
used only when it has an address and an account. A blank password becomes `x`.
The miner's username becomes `account.worker`.
Each field has a **+** menu with common pool addresses and the values you saved
before (**Add new...** edits that list). Worker names can use placeholders that
are filled in per miner:
| Placeholder | Becomes |
|---|---|
| `{ip1}` to `{ip4}` | one octet of the miner's IP |
| `{serial}`, `{mac}` | serial number; MAC without colons |
| `{hostname}` | the miner's hostname |
| `{brand}`, `{model}`, `{submodel}` | make and model |
| `{firmware}`, `{cpu}`, `{cb}` | firmware family, control-board CPU and board |
| `{nameplate-hr}` | the model's rated hashrate |
For example, `rack3-{ip3}-{ip4}` gives `rack3-1-50` for `10.0.1.50`.
+69
View File
@@ -0,0 +1,69 @@
# Settings and credentials
**Settings** opens a menu with Credentials, Language and Logs.
## Credentials
Miners need a login for anything beyond basic discovery: for some details, and
for every action. The Credentials dialog has two parts:
- **All firmwares** at the top: one username and password tried on every miner.
The saved password is never shown; leave the field blank to keep it. Blank
username and password clear it.
- **One row per firmware**, pre-filled with that firmware's factory default.
Change a row to override the login for that firmware only.
The toolkit tries, in order, the firmware's own row, then the global login,
then the firmware's built-in default.
| Firmware | Factory default (user / password) |
|---|---|
| AntMiner Stock | root / root |
| WhatsMiner Stock | admin / admin |
| Braiins | root / root |
| VNish | (none) / admin |
| LuxOS | root / root |
| UMC OS | (none) / letmein |
| Marathon | root / root |
| VolcMiner Stock | root / ltc@dog |
| Elphapex Stock | root / root |
| FutureBit Stock | futurebit / futurebit123 |
| SealMiner Stock | seal / seal |
| Auradine Stock | admin / admin |
**Reset to defaults** clears every override and the global login at once.
Logins are stored as plain text in the settings folder, readable only by your
user account (Linux file mode 0600; on Windows, your profile folder's
permissions).
### SSH login
Restoring Braiins to stock runs a command over SSH, using the system `ssh`
client (built into Windows 10/11). There is no dialog for this login yet:
create `ssh-credentials.txt` in the settings folder with the username on the
first line and the password on the second.
## Language
English, Chinese, Russian, French, Spanish and Portuguese. The toolbar, cards
and column headers switch immediately; menus and dialogs not yet translated
stay in English.
## Logs
An activity log of scans, actions, errors and exports, newest last, kept for
the current session (the last 2000 lines). Times are shown in UTC.
## Files in the settings folder
| File | Holds |
|---|---|
| `scan-ranges.txt` | scan ranges, one per line |
| `auto-rescan-secs.txt`, `scan-timeout-secs.txt`, `scan-concurrency.txt` | the three scan numbers |
| `scan-credentials.txt` | global login |
| `firmware-credentials.txt` | per-firmware logins |
| `ssh-credentials.txt` | SSH login (created by hand) |
| `presets.json` | saved views |
| `language.txt` | UI language |
| `pool-addresses.txt`, `pool-accounts.txt`, `pool-workers.txt`, `pool-passwords.txt` | saved pool values |
+18
View File
@@ -0,0 +1,18 @@
# Restore to stock firmware
**Restore to stock firmware...** removes aftermarket firmware and returns the
miner to the manufacturer's firmware it keeps on board. Nothing is uploaded.
The miner reboots, and some firmwares come back on a new address.
It is offered when the selection includes a supported firmware, and asks for
confirmation with the list of miners first.
| Firmware | How it is removed | Login used |
|---|---|---|
| VNish (and builds based on it) | web API: unlock, then remove firmware; reboots in seconds | the VNish row in Credentials, else `admin` |
| LuxOS | miner API: log on, then uninstall | none |
| Braiins OS | SSH: runs the firmware's own `uninstall.sh` | `ssh-credentials.txt` (see [Settings](06-settings.md)) |
Miners are restored one at a time. A dropped connection after the command is
sent counts as success, because that is the reboot. A refused login counts as
a failure and leaves the miner unchanged.
+14
View File
@@ -0,0 +1,14 @@
# Export
**Export** saves the scan as a CSV file for spreadsheets or other tools.
1. Choose the fields to include (all are ticked by default; **All** and
**None** help).
2. Pick where to save. The suggested name is `alkane-export-YYYYMMDD-HHMMSS.csv`.
The export contains **every scanned miner**, not just the rows the current
filter shows. Per-board temperatures, fan speeds, board status and pools
become numbered columns (`board_temp_1_c`, `fan_2_rpm`, `pool_1_url`, ...).
Values that start with `=`, `+`, `-` or `@` are prefixed with `'` so a
spreadsheet treats them as text, not formulas.
+32
View File
@@ -0,0 +1,32 @@
# Command line and environment
## Environment variables
| Variable | Effect |
|---|---|
| `ALKANE_FAKE_SCAN=1` | demo mode: a built-in sample fleet, no network traffic, simulated actions |
| `ALKANE_APPEARANCE=light` or `dark` | force the light or dark theme |
| `ALKANE_SELFTEST=1` | run the built-in UI self-test on the sample fleet and exit (prints `SELFTEST PASS` or `FAIL`) |
| `ALKANE_ACCESS_PROBE="<ip> <make>"` | print whether the saved login can change that miner, then exit |
| `ALKANE_LOG_SCAN="<ip> <brand>"` | fetch that miner's log through its API, print the size, then exit |
On Windows these one-shot modes print to the Command Prompt they are started
from.
## miner_probe
`miner_probe` is a command-line companion for scripting and diagnosis. These
commands only read:
| Command | Prints |
|---|---|
| `miner_probe scan <cidr> [<cidr>...]` | discovered miners and their telemetry, as tab-separated values |
| `miner_probe hashrate <cidr>...` | raw hashrate and algorithm |
| `miner_probe msgs <ip>` | fault messages and per-board data |
| `miner_probe tune <ip>` | tuning support and limits |
| `miner_probe presets <ip>` | available firmware profiles |
| `miner_probe timezone <ip>` | the current time zone |
Its other commands change miners. It uses the global login from the settings
folder, or `ALKANE_PROBE_USER` and `ALKANE_PROBE_PASS`, and
`ALKANE_PROBE_CONCURRENCY` (default 128).
+28
View File
@@ -0,0 +1,28 @@
# Troubleshooting
**Windows says "Windows protected your PC".** SmartScreen warns about new
downloads until a certificate has built up reputation. The publisher shown
should be *BlueFlare Energy Solutions Inc.*; click **More info**, then **Run
anyway**. If no publisher is shown, do not run the file and download it again
from the releases page.
**A miner is missing.** Check that its address is inside the scan ranges and
that it answers on its web page from this computer. On busy or slow networks,
raise **Timeout** or lower **Concurrency** in the Scan ranges dialog.
**An action is missing from the right-click menu.** Actions appear only when
every selected miner supports them. Select fewer miners, or only miners with
the same firmware.
**An action does nothing and the status says a scan is in progress.** Changes
wait for scans. Press **Pause**, let the scan finish, then try again.
**Check access says locked.** The saved login is not accepted. Set the right
password in **Settings > Credentials**, either for all firmwares or for that
firmware's row.
**Values are blank.** The firmware did not report them, or it needs a login to
report them. Try **Check access** and the Credentials dialog.
**The window is too small or too large.** It opens at most as large as your
screen's work area. Use the zoom slider in the status bar to scale the table.
+1 -2
View File
@@ -99,8 +99,7 @@ AZURE_SIGNING_TOKEN=$(az account get-access-token --resource https://codesigning
## Native Windows runner
`windows-native.yml` runs on the self-hosted runner `win11-test-vm`
(label `alkane-windows`, host mode) inside the Windows 11 test VM
(a local test VM). It downloads the
(label `alkane-windows`, host mode) inside a Windows 11 test VM. It downloads the
`alkane-toolkit-windows-tests` artifact of the triggering main run, runs every
test executable and the UI self-test natively, and never blocks a release:
while the VM is off, the job waits for the runner.