Autodetect, fault tolerance, tuning, API/UI and Stratum V2 for per-family images #14

Merged
noah merged 31 commits from feature/detect-core into next 2026-10-22 11:34:17 -06:00
Owner

What this is

The software half of the per-family autodetect goal: one image per control-board family that
identifies whatever hashboards, PSU and fans are plugged in (including a dead hashboard EEPROM),
checks the voltage envelope, and mines with fault tolerance and adaptive tuning.

Design and phase status: docs/DETECTION-CORE.md in the miner-firmware workspace.

Included

  • Detection: EEPROM-independent chain identification (ChainProbe/DetectionBackend,
    ProbeOutcome distinguishing identified / silent / garbled), profile database with strict
    validation, envelope intersection, plan() with explicit refusals.
  • Envelope: voltage_for(freq) pairs voltage with frequency; unconfirmed hardware runs the
    conservative floor and is flagged.
  • Faults: escalation ladder (retry -> disable chip -> disable chain -> stop), thermal stop,
    NoChainsLeft instead of spinning.
  • Fans: active sweep, map_fans with minimum drop and margin thresholds (ambiguous zones stay
    unresolved), persistence keyed on fan/sensor counts.
  • Tuning: bounded PID with anti-windup and rate limiting, thermal derate guard, targets
    power / hashrate / ambient-margin / max-fan.
  • Runtime: MinerRuntime owns the order (stopped is never tuned, disabled chains are never
    dispatched to, missing measurements hold the last command).
  • API/UI: hardware and stats documents, dependency-free on-box UI page.
  • Stratum V2: codec, session, TCP link with framing, V1 fallback policy; plus smooth weighted
    round-robin hashrate splitting.
  • HAL additions: CAPABILITIES, PROBE_CHAIN, READ_EEPROM, IDENTIFY_PSU,
    SET_CHAIN_FREQUENCY, READ_POWER, each capability-gated.
  • Runnable without hardware: --sim-hal reference server and --self-check.

Verification

  • cargo test --lib: 155 passed; clippy --all-targets -D warnings and cargo fmt clean.
  • --boot against the reference server: three BM1362 chains with a dead EEPROM detected, power
    target 2400 W settled at 623 MHz / 1442 mV.
  • Two-fan three-zone sweep: learned map fan 0 -> zones 0,2 and fan 1 -> zone 1, persisted.
  • SV2 driven over TCP against a mock pool: handshake, channel, prev-hash, job, submit, ack.

Not included

Per-family SDK backends on real buses, real profile envelopes (the example database is
placeholders), flare-ui assets, and the seven-family bench cycles. The bench rollout gate is
unchanged.

## What this is The software half of the per-family autodetect goal: one image per control-board family that identifies whatever hashboards, PSU and fans are plugged in (including a dead hashboard EEPROM), checks the voltage envelope, and mines with fault tolerance and adaptive tuning. Design and phase status: `docs/DETECTION-CORE.md` in the miner-firmware workspace. ## Included - **Detection**: EEPROM-independent chain identification (`ChainProbe`/`DetectionBackend`, `ProbeOutcome` distinguishing identified / silent / garbled), profile database with strict validation, envelope intersection, `plan()` with explicit refusals. - **Envelope**: `voltage_for(freq)` pairs voltage with frequency; unconfirmed hardware runs the conservative floor and is flagged. - **Faults**: escalation ladder (retry -> disable chip -> disable chain -> stop), thermal stop, `NoChainsLeft` instead of spinning. - **Fans**: active sweep, `map_fans` with minimum drop and margin thresholds (ambiguous zones stay unresolved), persistence keyed on fan/sensor counts. - **Tuning**: bounded PID with anti-windup and rate limiting, thermal derate guard, targets power / hashrate / ambient-margin / max-fan. - **Runtime**: `MinerRuntime` owns the order (stopped is never tuned, disabled chains are never dispatched to, missing measurements hold the last command). - **API/UI**: `hardware` and `stats` documents, dependency-free on-box UI page. - **Stratum V2**: codec, session, TCP link with framing, V1 fallback policy; plus smooth weighted round-robin hashrate splitting. - **HAL additions**: `CAPABILITIES`, `PROBE_CHAIN`, `READ_EEPROM`, `IDENTIFY_PSU`, `SET_CHAIN_FREQUENCY`, `READ_POWER`, each capability-gated. - **Runnable without hardware**: `--sim-hal` reference server and `--self-check`. ## Verification - `cargo test --lib`: 155 passed; `clippy --all-targets -D warnings` and `cargo fmt` clean. - `--boot` against the reference server: three BM1362 chains with a dead EEPROM detected, power target 2400 W settled at 623 MHz / 1442 mV. - Two-fan three-zone sweep: learned map fan 0 -> zones 0,2 and fan 1 -> zone 1, persisted. - SV2 driven over TCP against a mock pool: handshake, channel, prev-hash, job, submit, ack. ## Not included Per-family SDK backends on real buses, real profile envelopes (the example database is placeholders), flare-ui assets, and the seven-family bench cycles. The bench rollout gate is unchanged.
noah added 1 commit 2026-10-22 10:12:06 -06:00
Add hardware detection plan model
source-pr / source (pull_request) Successful in 14s
367f07d956
Introduce the detection core data model: chain observations, board profile
and PSU envelopes, envelope intersection, and a conservative operating point
when the hardware is not confirmed by an EEPROM. Refusal is explicit for
unknown chips, missing PSUs and empty envelopes, and degraded chains are
reported rather than fatal.
noah added 1 commit 2026-10-22 10:13:29 -06:00
Add chain probing policy to the detection core
source-pr / source (pull_request) Successful in 12s
99fb12d725
Define the backend contract for identification (ChainProbe) with a bounded
ProbeBudget and a ProbeOutcome that distinguishes an identified chain from a
silent port and from unframed bytes. probe_chain retries a chain until it
identifies or the budget is spent, and reports an exhausted chain as an
unknown chip instead of dropping it; detect_chains walks every declared port.

Framing and baud switching stay in the per-family SDK backend. Tests cover
retry-until-identified, budget exhaustion, EEPROM state retention and the
refusal path when a chain never identifies.
noah added 1 commit 2026-10-22 10:15:40 -06:00
Carry detection verbs over the HAL wire contract
source-pr / source (pull_request) Successful in 12s
3028ef29fb
Add capability negotiation and three detection verbs to the local HAL
contract: CAPABILITIES, PROBE_CHAIN, READ_EEPROM and IDENTIFY_PSU. A backend
that predates them rejects the capability query, which surfaces as a protocol
error instead of a silent zero. HalClient implements ChainProbe, so the OS
detection driver can run against a real board without knowing the family.

The probe contract is now error-aware: a transport failure propagates as an
error and is never reported as a silent port, and probe_chain/detect_chains
are generic over the backend. A wire round-trip test drives a mock backend
over a socket pair and checks the encoding of all three verbs.
noah added 1 commit 2026-10-22 10:17:45 -06:00
Add the profile database and the end-to-end detection driver
source-pr / source (pull_request) Successful in 12s
9ed94bd01f
Profiles carry the only envelopes detection may use, so a combination absent
from the database is refused rather than guessed. The schema-1 document is
validated on load: unknown chips or sensor wiring, inverted or zero envelopes,
zero chain counts and duplicate names are all rejected.

run_detection now ties the pieces together: probe every declared port, select
a profile by chip, sensor wiring and physical port count, identify the PSU, and
emit a HardwarePlan. A machine with a dead chain still matches its three-chain
profile and runs degraded instead of being reclassified; plan() now tolerates
unidentified chains and refuses only when nothing identified.

The detection backend contract gains identify_psu(), and HalClient answers it
through the new HAL verb.
noah added 1 commit 2026-10-22 10:19:55 -06:00
Map fans to thermal zones by active probing
source-pr / source (pull_request) Successful in 11s
c616429669
Fans are not labeled by the hardware: a fan can cool one hashboard heavily
and another barely, and front/back top/bottom is physical. map_fans learns the
map from a stepped run: for every fan compare zone temperatures at the lowest
and highest duty, then give each zone to the fan with the strongest cooling
response.

A response must clear min_drop_mc and beat the runner-up by
min_margin_per_mille, otherwise the zone is reported unresolved rather than
guessed, so a noisy run cannot invent a map. One fan may own several zones,
and a fan with no duty range contributes no evidence.
noah added 1 commit 2026-10-22 10:21:37 -06:00
Add the fan-mapping measurement sweep
source-pr / source (pull_request) Successful in 11s
4139576155
sweep() drives the probing run that map_fans consumes: it moves one fan at a
time between the low and high duty while the others hold their setting, waits
for the settle interval, and records every zone reading. Repeat readings are
emitted so the mapper averages noise.

Safety is enforced in the loop, not by convention: a probe duty below the
minimum, an empty duty range, an inverted range, zero reads and zero fans are
all refused before any fan is touched, and the run always ends with every fan
restored to the high duty so the machine is not left under-cooled.
noah added 1 commit 2026-10-22 10:23:02 -06:00
Drive fan probing through the HAL client
source-pr / source (pull_request) Successful in 12s
ef399d0ca5
HalClient implements FanProbe, so the measurement sweep runs against a real
board over the same local contract: set_fan maps to SET_FAN_TARGET and
read_zone maps to READ_TEMPERATURE. The wire round-trip test now exercises
both fan verbs through the mock backend.
noah added 1 commit 2026-10-22 10:24:49 -06:00
Add the fault-tolerance escalation ladder
source-pr / source (pull_request) Successful in 12s
724b3da478
The machine should keep hashing with as many dead chips or chains as
possible, so faults escalate in steps instead of stopping at the first one:
a chain error retries up to a policy limit, then the chain is disabled and the
rest keep running; a chip fault disables only that chip; a chain whose nonce
response stays below the policy floor for consecutive windows is disabled; a
temperature fault stops the machine immediately.

Disabling every chain stops with NoChainsLeft rather than leaving the miner
spinning on an empty active set. The supervisor owns no hardware and no
thermal limits; those come from the profile envelope.
noah added 1 commit 2026-10-22 10:26:41 -06:00
Add adaptive PID tuning with a thermal derate guard
source-pr / source (pull_request) Successful in 12s
5aa6349e27
Replace preset tuning with a bounded controller: a PID over chain frequency
that targets a DC power draw or a hashrate, inside the profile envelope. The
controller rate-limits its output, ignores errors inside a deadband, takes the
derivative on the measurement so a setpoint change does not kick it, and uses
conditional integration so a saturated actuator does not wind the integral up.

A thermal guard runs before the target logic: any sensor at or above the
ceiling derates the frequency regardless of what the operator asked for, so a
hashrate target can never cook a board.
noah added 1 commit 2026-10-22 10:29:04 -06:00
Add the ambient-temperature and max-fan tuning targets
source-pr / source (pull_request) Successful in 12s
96f84dc283
Ambient mode holds the hottest sensor a configured margin above the measured
intake temperature, which is the efficiency-at-this-ambient operating point;
missing either sensor is an error rather than a guess. Max-fan mode pins the
fan at its cap, ramps frequency toward the envelope ceiling, and still defers
to the thermal guard.

step() now returns a Command carrying the frequency and, when the target owns
the fan, the duty to apply. The max-fan ramp is explicit rather than a
setpoint loop: a P controller fed its own output settles at half the ceiling,
which the ramp test caught.
noah added 1 commit 2026-10-22 10:31:13 -06:00
Expose detection, envelope and tuning state on the management API
source-pr / source (pull_request) Successful in 12s
fe0c2d43ce
The cgminer-compatible surface only answered summary and version, which hides
everything detection learned. The API now also answers hardware (profile, chip,
PSU, envelope, operating point, per-chain chip count and EEPROM state, fan
zones, active chains, stop reason, target and live frequency) and stats (the
same data in cgminer's flat STATS shape).

MiningStatus carries an optional HardwareSnapshot behind a mutex, so a client
can tell unavailable apart from an empty machine, and unknown commands still
refuse. Chip models gained a stable API name so the wire strings do not drift
from the enum.
noah added 1 commit 2026-10-22 10:32:53 -06:00
Split hashrate across pools with smooth weighted round-robin
source-pr / source (pull_request) Successful in 12s
b62d64adfb
Each dispatched work slot comes from exactly one pool, and the router hands
out slots in proportion to the configured weights. Smooth weighted
round-robin is used instead of a plain repeating pattern because it keeps the
mix correct at every prefix: a miner with three chains still gets the intended
ratio in the first three slots, not only after a hundred.

Weights parse from a simple list, a zero-weight pool never receives work, and
malformed configurations (empty, all zero, non-numeric, too many pools) are
refused rather than silently normalised.
noah added 1 commit 2026-10-22 10:34:54 -06:00
Add the Stratum V2 mining-protocol codec
source-pr / source (pull_request) Successful in 12s
6ab645e731
Implement the client half of SV2 as framed messages: the 6-byte header
(extension_type U16, msg_type U8, msg_length U24), SetupConnection and its
success reply, OpenStandardMiningChannel and its success reply, NewMiningJob
with both the active and future ntime forms, SetNewPrevHash and
SubmitSharesStandard.

Field layouts and message identifiers come from the published specification
(03-Protocol-Overview 3.2/3.6, 08-Message-Types, 05-Mining-Protocol 5.3) and
were checked against it rather than recalled. Decoding is strict: truncated
payloads, bad option markers, bad UTF-8 and a non-finite or negative hashrate
are protocol errors, never defaults.
noah added 1 commit 2026-10-22 10:36:40 -06:00
Add the Stratum V2 session: handshake, jobs and submissions
source-pr / source (pull_request) Successful in 11s
914fb8bef7
Drive the client half of an SV2 mining connection: send SetupConnection,
verify the success reply, open a standard channel and remember its id, target
and extranonce prefix. Afterwards the session interprets NewMiningJob,
SetNewPrevHash, SetTarget and share acknowledgements, and submits standard
shares with a monotonic sequence number.

State is explicit rather than assumed: a job that arrives before any
SetNewPrevHash reports no previous hash instead of a zero one, a setup or
channel rejection carries the server's error code, and an unknown message is
ignored instead of killing the session.
noah added 1 commit 2026-10-22 10:38:19 -06:00
Serve an on-box web UI backed by the JSON API
source-pr / source (pull_request) Successful in 12s
b25d6b2a71
The miner now serves a single page that polls /api/hardware and shows profile,
chip, PSU, operating point, chains and EEPROM state, active chains, target and
whether hashing stopped. The page is a convenience; the API routes it uses are
the interface of record, so a JSON-only client loses nothing.

No framework and no new dependency: the request parser is bounded, only GET is
accepted, responses close the connection and are not cached. MiningStatus now
exposes its hardware and summary documents so the UI and the cgminer-style
server build them once, in one place.
noah added 1 commit 2026-10-22 10:39:55 -06:00
Add the mining runtime state machine
source-pr / source (pull_request) Successful in 13s
97ea7a4f65
Tie the detection plan, the fault ladder and the tuner together, where their
order is decided: a stopped machine is never tuned, a disabled chain is never
dispatched to, and a missing measurement holds the last command instead of
inventing one.

MinerRuntime exposes the active chain set, the stop reason and an operating
point that reflects the last applied command rather than the boot-time
default, which is what the API snapshot reports.
noah added 1 commit 2026-10-22 10:41:38 -06:00
Add the SV2 TCP link and the V1 fallback policy
source-pr / source (pull_request) Successful in 12s
e3e0dab0ec
TcpLink turns a TCP stream into framed SV2 messages: it buffers partial reads
and returns one frame at a time, so a frame split across packets is not a
protocol error and two frames in one read are still delivered separately. A
closed stream is an error, never an empty frame.

The fallback policy permits Stratum V1 only when the operator allowed it and
the failure is not transport-level: a dead route or a dropped stream fails
identically on V1, so falling back there would only delay the real error. V1
failures never loop back to V2.
noah added 1 commit 2026-10-22 10:43:53 -06:00
Wire the API and UI through one start-up path
source-pr / source (pull_request) Successful in 12s
2c6535f948
Add an app layer that binds and starts the management API and the web UI,
publishes the runtime snapshot, and exposes a bound-address result so callers
can discover ephemeral ports. The binary now uses the same function the tests
use, so the wiring CI exercises is the wiring that runs on a board, and it
gained ALKANE_WEB_LISTEN alongside ALKANE_API_LISTEN.

The snapshot is built from the live runtime: active chains, stop reason and
the last applied frequency rather than the boot default.
noah added 1 commit 2026-10-22 10:45:44 -06:00
Add the boot sequence from backend and profiles to runtime
source-pr / source (pull_request) Successful in 12s
5a1a7948b1
app::boot is the sequence a family image runs at start-up: validate the
profile database, detect the hardware through the backend, build the runtime
with the operator target and fault policy, and publish the API snapshot in one
step. It returns the runtime or an explicit BootError, so a refusal is visible
to the caller instead of a half-configured miner.

Target labels are defined once (power:3000, hashrate:200, ambient:20000,
fan:100) so the API, UI and logs cannot drift apart.
noah added 1 commit 2026-10-22 10:47:29 -06:00
Persist the learned fan map and reuse it until the hardware changes
source-pr / source (pull_request) Successful in 12s
5048156b74
Mapping fans perturbs the machine, so it is done once and stored. ensure_map
reuses a stored map only when the fan and sensor counts match the current
machine; a mismatch is ignored rather than trusted, because applying a map
learned on four fans to a two-fan machine would mis-control thermals.

The store is a small schema-1 document; corrupt or foreign files are ignored
and trigger a fresh sweep instead of failing the boot.
noah added 1 commit 2026-10-22 10:49:21 -06:00
Add a runnable self-check for the boot path
source-pr / source (pull_request) Successful in 12s
42509a6383
alkane-os --self-check drives the whole chain without hardware: parse the
example profile database, detect three BM1362 chains with a dead EEPROM,
identify an APW12, boot the runtime, tick toward a power target and print the
published hardware document. It fails loudly if the profile database does not
parse, detection refuses, the tuner does not move, or the chain set is wrong,
which makes it usable as a bench smoke test on a bare control board.

profiles.example.json is a shape example, not validated hardware data: the
envelopes are placeholders until real captures fill the database.
noah added 1 commit 2026-10-22 10:51:11 -06:00
Pair voltage with frequency across the profile envelope
source-pr / source (pull_request) Successful in 12s
2b07d27c67
Boards do not run at a fixed voltage across their frequency range, so the
reported operating point was describing a machine that does not exist: the
voltage stayed at the boot value while the tuner moved the frequency.

Envelope::voltage_for interpolates linearly between the profile floor and
ceiling and clamps outside it, and MinerRuntime now reports the voltage that
pairs with the applied frequency. A single-frequency envelope reports its
floor without dividing by zero.
noah added 1 commit 2026-10-22 10:52:12 -06:00
Report one operating point, not two
source-pr / source (pull_request) Successful in 13s
64e1a9ae2b
The live frequency and the boot-time operating point were both in the
hardware document, so a client could read 563 MHz in one field and 300 MHz in
another. The document and the cgminer stats now both derive the operating point
from the live frequency and the envelope, which is also what makes the reported
voltage correct.
noah added 1 commit 2026-10-22 10:54:53 -06:00
Boot over the real HAL contract
source-pr / source (pull_request) Successful in 14s
894b22277f
boot_from_hal connects the board backend, detects through the actual HAL
verbs, runs the one-time fan sweep through the same socket, publishes the
snapshot and returns the runtime and the learned map.

The tests drive it against a mock backend that speaks the real wire protocol
(ALKH framing, CAPABILITIES, PROBE_CHAIN, READ_EEPROM, IDENTIFY_PSU), so the
detection path is exercised end to end rather than assumed, and a missing
socket surfaces as a backend error instead of a half-booted miner.
noah added 1 commit 2026-10-22 10:56:54 -06:00
Add the HAL frequency actuator and a --boot command
source-pr / source (pull_request) Successful in 14s
dccbefc8b7
The tuner produced a frequency the hardware contract had no way to apply, so
detection and tuning could not affect a real board. SET_CHAIN_FREQUENCY joins
the HAL verbs behind its own capability bit, and HalClient refuses to use it
when the backend does not advertise it.

--boot HAL_SOCKET PROFILES.json TARGET [PIC|NOPIC] [TICKS] now runs the real
path: detect over the socket, serve the API and UI, read the hottest sensor,
tick the runtime, apply the frequency to each active chain and the fan duty
when the target owns the fan, then print the published document. A missing
socket exits 1 with a backend error instead of a half-booted miner.
noah added 1 commit 2026-10-22 11:00:07 -06:00
Add a reference HAL server and power telemetry
source-pr / source (pull_request) Successful in 13s
b0d81b5d0e
The reference server answers the real ALKH contract from a fixed machine
description, so the whole OS path can run on a development host and a backend
author has a concrete example of every opcode. It serves detection, frequency,
fan, temperature and power over one socket.

Power was the missing measurement: a power target could not regulate because
the HAL had no way to report watts, so READ_POWER joins the verbs behind
CAP_POWER. With it, --boot against the reference server settles the loop at
623 MHz for a 2400 W target (4 W per MHz in the model) instead of holding at
the boot frequency.

Fan mapping stays opt-in for --boot (ALKANE_FAN_FANS/ALKANE_FAN_ZONES) because
it perturbs the machine and takes minutes.
noah added 1 commit 2026-10-22 11:02:12 -06:00
Make the reference server thermal model fan-aware
source-pr / source (pull_request) Successful in 13s
79f492e5e8
Zones now respond to the fan that actually cools them (round-robin by zone
index), so the active fan sweep can be demonstrated end to end without
hardware: with two fans and three zones the learned map is fan 0 -> zones 0,2
and fan 1 -> zone 1, persisted to the map file.

The settle interval is configurable (ALKANE_FAN_SETTLE_MS) because the real
twenty-second settle makes an interactive sweep last minutes.
noah added 1 commit 2026-10-22 11:03:52 -06:00
Drive an SV2 session against a socket pool end to end
source-pr / source (pull_request) Successful in 12s
a16a4385f8
The codec and session had only ever been tested in memory. This runs the real
path over TCP: the client handshakes, opens a channel, receives SetNewPrevHash
and an active NewMiningJob, submits a share and consumes the acknowledgement,
against a mock pool that speaks the same frames.

It also pins the ordering the protocol depends on: the job is interpreted only
after the prev hash, and the submit sequence starts at one.
noah changed title from Add hardware detection plan model to Autodetect, fault tolerance, tuning, API/UI and Stratum V2 for per-family images 2026-10-22 11:05:19 -06:00
noah added 1 commit 2026-10-22 11:06:33 -06:00
Add a HAL conformance harness for family backends
source-pr / source (pull_request) Successful in 12s
78baeb8c31
A family backend is only useful if it answers the contract the OS expects, and
until now the only way to know was to boot a board and watch it fail somewhere
downstream. --check-hal walks the contract in order (capabilities, probe,
EEPROM, PSU, frequency and temperature, power, fan) and reports each check
separately, using a fresh connection per check so one desynchronised exchange
cannot invalidate the rest.

It catches the failure modes that matter for autodetect: a backend that does
not advertise chain probing, one that reports an inverted envelope, one that
returns an implausible temperature or power, and one that cannot accept
frequency or fan commands.
noah added 1 commit 2026-10-22 11:08:18 -06:00
Validate profile databases and make the power check meaningful
source-pr / source (pull_request) Successful in 12s
8564ced65d
--check-profiles parses a database and reports schema, count and validation,
so envelope work can be checked before an image ever boots with it. An inverted
envelope is rejected with a non-zero exit.

The conformance power check now sets 500 MHz before reading, because a backend
that always reports 0 W passed a range check while being useless to a
power-target loop. It must now report a plausible non-zero draw at a known
operating point.
noah added 1 commit 2026-10-22 11:10:43 -06:00
Publish the live operating point every control period
source-pr / source (pull_request) Successful in 12s
f6af71138c
A client watching the API during a run saw the boot-time snapshot: status was
published at boot and again when the loop exited, so frequency and voltage were
frozen at their starting values for the whole run. The loop now publishes each
period, which is what makes the UI and the API honest while the machine is
actually mining.
noah merged commit 6e7d10d2cf into next 2026-10-22 11:34:17 -06:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: blueflare/alkane-os#14