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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 images2026-10-22 11:05:19 -06:00
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.
--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.
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 next2026-10-22 11:34:17 -06:00
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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.mdin the miner-firmware workspace.Included
ChainProbe/DetectionBackend,ProbeOutcomedistinguishing identified / silent / garbled), profile database with strictvalidation, envelope intersection,
plan()with explicit refusals.voltage_for(freq)pairs voltage with frequency; unconfirmed hardware runs theconservative floor and is flagged.
NoChainsLeftinstead of spinning.map_fanswith minimum drop and margin thresholds (ambiguous zones stayunresolved), persistence keyed on fan/sensor counts.
power / hashrate / ambient-margin / max-fan.
MinerRuntimeowns the order (stopped is never tuned, disabled chains are neverdispatched to, missing measurements hold the last command).
hardwareandstatsdocuments, dependency-free on-box UI page.round-robin hashrate splitting.
CAPABILITIES,PROBE_CHAIN,READ_EEPROM,IDENTIFY_PSU,SET_CHAIN_FREQUENCY,READ_POWER, each capability-gated.--sim-halreference server and--self-check.Verification
cargo test --lib: 155 passed;clippy --all-targets -D warningsandcargo fmtclean.--bootagainst the reference server: three BM1362 chains with a dead EEPROM detected, powertarget 2400 W settled at 623 MHz / 1442 mV.
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.
Add hardware detection plan modelto Autodetect, fault tolerance, tuning, API/UI and Stratum V2 for per-family images