Models

A manual change landed AFTER the profile was applied.

What made it dirty — the route or register. "dirty" alone sends the reader looking through everything.

Machine-readable error code (not_found, validation_failed, …).

Human-readable message.

What the apply did to the RADIO, in one sentence — tuned, or why not.

Applying a profile used to leave the AD9361 exactly where it was while the reply said nothing about it (STE-994), so a UHF profile could be "applied" onto a part listening in S-band and every field in this struct stayed green. A tuning that did not happen has to be visible where the apply is.

Whether this assertion read the LINK or only the scenario's own timeline.

It was missing from this DTO while scenario_passed required passed && verified on every assertion — so the field that decides the verdict was the one field a caller could not see, and a green run was indistinguishable from a run that had checked the script against itself. That distinction is the entire reason the flag exists.

MILLISECONDS SINCE THE DAEMON STARTED, not since the epoch. The board has no RTC; a client subtracting this from its own wall clock would be out by decades, which has already cost this project a UI feature.

Set when nothing could be mapped — typically satlinkd not running as root, or /dev/mem absent.

What the value means; present even when the read failed, so a client can show the contract without the number.

Why value is absent. Never left implicit: a missing number that does not say why is indistinguishable from a zero.

Who would take a board action, in words. "the orchestrator power-cycled it" and "nobody did, the step was refused" must not read the same afterwards.

true / false / null — and null is the common case.

A CAMPAIGN THAT DID NOT FINISH HAS NO VERDICT. One paused at step 3 of 15 must not report a pass on twelve steps nobody ran, and a client that rendered false there would be accusing the board of failures it was never asked to produce.

A pause is asked for and has not yet taken effect.

The cron expression, when this campaign schedules itself.

Supported modulations (strings matching the profile enum).

Number of RX channels exposed by the platform.

Number of TX channels exposed by the platform.

true when the PL driver is a mock (no real HW attached).

THE SYMBOL RATES THIS MODEM CAN PRODUCE, and the two it cannot.

Not a menu someone chose: the rate is ad9361_rate / (sps * interp) with sps fixed at 4 and interp decoded only over 1..32, so the set is fixed by the hardware. Clients build their forms from this rather than offering a free number — phy.symbol_rate_baud accepted anything and reached no register at all, so a profile declaring 9600 baud transmitted at about 2 MBaud (measured 2026-09-13).

The unreachable entries are PRESENT, with the bound they hit, rather than silently absent: a list that quietly drops what it cannot do reads as a complete list of what exists.

Number of RAW DMA blocks to collect. Obtaining them in a row is the proof of a sustained regime; a short capture is refused, not truncated.

Blocks to obtain and DISCARD before the measured window starts.

Every capture re-arms the chain, so the leading blocks carry the acquisition transient. Skipping them is legitimate; skipping them SILENTLY, or guessing which ones look like transient, would throw away real head-of-capture errors and call the result clean. Hence explicit, and zero by default.

Give up after this many milliseconds.

Release the IIO devices afterwards so bring-up tools can open them.

The target these conditions were computed for.

What the board is wired for right now; null when the two loopback switches could not be read.

Does anything leave the board in this target? False for both loopbacks — the AD9361's internal one returns TX to RX BEFORE the mixers, so no LO, gain or attenuation setting can explain an empty analyser.

The first unmet condition and the command to run. null when ready.

Every condition, in the order the bring-up needs them.

Authoritative: non-zero means the clock is enabled.

Authoritative: non-zero means it is prepared.

NOT authoritative. Computed by the clock framework from the parent and the dividers, and printed unchanged with the MMCM off (STE-943). Present for display; never judge on it.

None when debugfs is not mounted — distinct from "no clocks", which would read as a healthy empty set.

Stable key — dac-source, tx-egress, …

The stage this must be satisfied to leave.

board when the value was re-read from a register or an IIO attribute, session when it is this daemon's memory and a restart forgets it.

What it is, or could not be read.

met / unmet / unknown. An unknown BLOCKS: a register we failed to read is not a register holding the right value.

What goes wrong when it is unmet, as the symptom the operator will see.

The command that clears it.

Where the samples should go. Defaults to air — the only target of the three that puts anything on a connector, and the one an operator at a spectrum analyser is asking for.

Which profile to apply. Defaults to the one currently applied; with none applied the request is refused rather than guessing, because the profile decides the frame length, the coding and the frequency.

AD9361 rate for the tuning step, when one is needed.

The steps actually run, in order.

What each step reported, keyed in the same order as steps.

True while the daemon holds the modem's IIO devices.

monitor.fft.SRC_SEL — which tap the core is pointed at.

Frequency-domain magnitude samples.

TRUE while these bins are MANUFACTURED HERE and do not come from the PL.

The field exists because nothing in the response distinguished a measurement from an invention: a spectrum served by /api/v1/... reads as signal, and the UI displayed it as such. The client now labels itself from this value rather than from a hard-coded string, which would have gone stale the day the real path landed — and a stale note is this project's dominant failure mode.

Set it to false IN THE SAME COMMIT as the real sample read, not before: a premature false is worse than today's true, because it makes the invention undetectable.

Which end of the link this spectrum describes ("rx" / "tx").

Whether analysis is switched on for that channel. Off by default: a frame costs a DMA block plus a transform, and nothing should pay that because a dashboard tab happens to be open.

Sample rate the block was taken at, 0 when there is no block.

Useful bytes HANDED TO THE DMA, padding included. Zero means nothing was pending — a block of pure padding would put silence on the air.

Handed to the DMA is not "on the air". This field used to say it was, and it was wrong: with the TX egress closed the modem discards the block and this number is exactly the same. tx_chain_running is the only field here that tells the two apart.

Whether the modem's TX egress is open. null when there is no PL driver to ask, which is not the same as false.

How many blocks to emit. Use 2 whenever you intend to see the result come back. An RX block is returned only when ENTIRELY full, and the receive side is always short of what was sent — the first frame of a freshly-armed chain is lost to acquisition, so 4096 useful bytes out come back as 4080. One block therefore stops just before the line and waits for traffic a one-shot sender never sends.

Measured on hardware 2026-09-12: one flushed block never surfaced in 60 s (with tx.framer.frame_cnt confirming all 256 frames had crossed); two came back in 2 s.

What ONE entry is. "dma_block" today: the producer pushes one entry per DMA block, so an entry is 4096 useful bytes cut at a boundary that has no relation to any protocol frame. Calling that a frame is the defect STE-989 is about; naming it is the honest half of the fix. For packet granularity use /ws/frames?framing=slot&slot_len=N.

How to read timestamp. "boot_relative": the board has no RTC and no NTP, so times start at the epoch on every boot. A control centre would otherwise take them for wall-clock.

null when the page is non-empty. Otherwise WHY it is empty.

TRUE when the samples were MANUFACTURED rather than captured. Without it a fabricated capture is indistinguishable from a measurement: it carries the true centre frequency and the active profile, and opens in any viewer showing a clean carrier.

BytePerfect | Degraded | NoCorrelation.

A byte was lost or inserted at a block boundary. NOT a demodulation error — reporting it separately is what stops it being read as one.

Read this before overall_ratio: an aggregate is exactly what hid the 2026-09-08 defect, where the whole capture scored 49.99 % while every block taken separately scored 99.98 %.

Blocks obtained and discarded before the measured window. Never hidden: a window that was moved must say so, or the number stops meaning what the reader thinks it means.

Purge events older than this many hours.

The DDC's digital offset from the RX LO, signed, in Hz.

The DUC's digital offset from the TX LO, signed, in Hz.

What the applied PROFILE declares as its centre, read from the inert chan_cfg shadow. It describes the configuration, not the radio, and the two diverge the moment anyone tunes by hand.

The part's own gain, in dB at the connector. TX is an ATTENUATION.

The part's ANALOG filter width, per direction, read from IIO.

NOT a PL register — the AD9361 has none in this address space, which is exactly why the datapath diagram could not show it. None means the attribute could not be read, never a default: this is the value that sat at 18 MHz for a 53 kHz signal (STE-998), and a plausible-looking number here would be worse than an absence.

The part QUANTISES what is written, so this read-back legitimately differs from any requested width. It is the truth; the request is not.

SERIALISED EVEN WHEN NULL, unlike its neighbours above, and the difference is deliberate. An ABSENT field cannot be told apart from an older daemon that never had it; an explicit null says "this daemon knows about the bandwidth and could not read it". For a field whose whole point is that nobody could see it before, that distinction is the feature.

The part's sample rate. Also on /radio/rf-state; carried here so that one call answers "how is the front end configured" instead of two that have to be reconciled.

True when a profile of this name already existed and was replaced.

Always false today, and present so a client never has to assume.

Profile referenced by the scenario at the time the run finished, if still known to the daemon's in-memory scenarios map.

true if the run had a persisted report (completed/failed/cancelled).

Whether ANY assertion in this run read the link rather than the scenario's own script. A report that observed nothing is not a pass, and the reader has to be able to tell the two apart.

The run did not reach the end of its timeline. Its assertions were written for a whole one, so neither verdict applies.

The board's own trace across the run. EMPTY IS NOT "NOTHING HAPPENED": it means no sampler was attached, which sample_interval_ms == None is how you tell apart.

The sampler's nominal tick, beside the samples — a series without its cadence cannot distinguish a slow poll from a stalled board.

Where this run's numbers came from: "pl", "stub", "mixed", "none".

SERVED, not kept internal. The point of the field is that a report declares its own provenance to whoever reads it — and the reader of a qualification document is usually not the person who ran it.

Profile referenced by the scenario at the time the run finished, if still known to the daemon's in-memory scenarios map.

What the part's ENSM reports AFTER the stop. alert is RF off.

Steps that took effect, in the order they were applied.

Steps that did NOT. Present even when RF is off, because a stop that half-worked and says nothing is the failure mode this exists against.

Is RF actually off at the connector?

How to come back.

pending, running, passed, failed, cancelled.

Which side to tune: "rx", "tx" or "both" (default).

RX AND TX ARE INDEPENDENT LOs. Measured on this bench 2026-09-12: the RX LO sat at 2.400 GHz while the TX LO was still at its 2.450 GHz default, so an analyser on TX1A at 2.4 GHz saw nothing and the API reported one "center_frequency_hz" that described neither.

true (default) also drives the AD9361's analogue LO. false writes only the PL's digital NCO (chan_cfg::FREQ_HZ).

The distinction is not pedantry: until today this route wrote ONLY the NCO, so /radio/status reported a centre frequency the transmitter had never been told about.

The exact rate in baud. Fractional at the bottom of the ladder: the hardware produces 39 062.5, and rounding it would publish a rate nobody can select.

As an operator writes it, e.g. "39.063 ksym/s".

False when this rate cannot be produced at all.

What the AD9361 must be clocked at to realise it. null when unavailable.

The DUC interpolation that realises it. null when unavailable.

Which bound it hits. Present exactly when available is false.

mock or uio.

Useful bytes queued (before the le:u8/32 lane expansion).

Bytes actually written to the DMA block.

True when packet boundaries survive the crossing. False in stream mode — stated rather than left for the caller to discover from a receiver that returns bytes at the wrong offsets.

Whether the modem's TX egress is open.

false means these bytes reach the DMA and the modem DISCARDS them — nothing goes on the air, and no other number in this reply changes. null when there is no PL driver to ask.

Useful bytes that fill one DMA block.

Not a measurement of what is buffered — the assembler's fill level lives in the service and is not queried here, and reporting a guessed one would be the snr_db mistake of STE-977. It is the quantum that matters to a caller: a packet does NOT go on the air until its block is complete, so this is the latency granularity.

Packets to transmit, tagged by protocol: {"protocol":"raw","payload_hex":".."} for bytes forged elsewhere, {"protocol":"csp","header":{..},"payload_hex":".."} to have SatLink build the packet, likewise "ccsds".

How packets are laid out in the byte stream.

{"mode":"stream"} packs them end to end: maximum throughput, and NO packet boundary survives — the receiver gets a byte stream cut at the PL's FRAME_LEN, which has no relation to what was pushed.

{"mode":"slot","slot_len":256,"pad":0} gives one packet per slot, so the framer's cut lands on the boundary. slot_len must equal the PL's FRAME_LEN and divide the block's useful bytes, or the request is refused.

Transmit even though the chain cannot carry it (STE-995).

The refusal is a guard, not a wall: probing a closed-egress branch or an unconditioned front-end is legitimate bench work, and dsl/scenarios/bringup/tx_egress_probe.yaml exists to do exactly that. It is deliberately not the default, and the reply carries the chain state either way so no report can claim the chain was healthy.

satlinkd crate version.

API contract version (v1).

PL bitstream identifier read from the shell — None in mock mode.

This is the shell's BUILD_ID register, read live over /dev/uio0. It says which bitstream is LOADED, which no host-side manifest can.

Release bundle this daemon was built for, or "unreleased".

Compare it with the manifest of the bundle you deployed: they must be equal. On a ramdisk rootfs, deploying and running are two different things, and this field is what separates them (STE-985).