Chain Conditioning

Before the modem can put a sample where you want it, a dozen independent things must be right: the AD9361 calibrated and tuned at the right rate, a profile applied after that tuning, the DAC fed from the modem, the transceiver in an emitting state, the loopback switches on the right side, the TX egress open and the datapath claimed. Getting any of them wrong produces a chain that looks healthy and transmits nothing.

The chain layer enumerates these prerequisites, reads them back from the board on every request, and establishes the missing ones in the only order that works.

Checking the chain#

satlinkctl chain status                    # judged against the target the board is wired for
satlinkctl chain status --target air       # "what would it take to go on air?"

GET /api/v1/chain returns the same, with one entry per condition:

An unreadable fact is unknown, and unknown counts as not met: the chain refuses to build a plan on a register it could not read.

The conditions#

The overall stage is the stage of the first unmet condition: unconditioned, unprofiled, misrouted, not-armed, or ready.

Bringing the chain up#

satlinkctl chain up --target air --profile rf_loopback
satlinkctl chain up --target pl  --profile pl_loopback

POST /api/v1/chain/condition with {"target": "air", "profile": "rf_loopback"} does the same. With no profile named, the currently applied one is used; with none applied, the request is refused rather than guessing, because the profile decides the frame length, the coding and the frequency.

Only the missing steps run, always in this order:

The result lists the steps run and the chain state re-read afterwards. For the air target the verdict states all three doors explicitly: pl-mux 0, device-loopback open, dac-source 2 (DMA), reaches_the_connector: true.

Manual steps#

The individual steps are available when you need them, but taking them out of order undoes the earlier ones:

satlinkctl rf calibrate          # resets the part: FIRST, before anything else
satlinkctl rf tune --rate 2500000
satlinkctl profile apply rf_loopback
satlinkctl rf air                # or: rf rf (device loopback), rf pl (PL loopback)
satlinkctl radio start-tx
satlinkctl datapath enable

rf air and rf rf refuse when the interface was never tuned or when the profile was applied before the last tuning; --force overrides the refusal.

Chain targets#

rf is accepted by the CLI as an alias of the device loopback, but scenarios deliberately refuse it: an "RF" mode that emits nothing is exactly the confusion that makes an analyser on the connector show nothing.

Recovering the receiver without a reboot#

The receiver's loops can get stuck: symbols flow, the lock flags read true, and the deframer never finds its marker. A clear flushes the AGC, the timing loop and the carrier loop in signal-flow order, preserving every other bit of their control registers:

satlinkctl chain recover         # POST /api/v1/chain/recover

It says what it pulsed; it does not say the link is healed. Check that with a byte-exact loopback or with frame counters that move, never with the lock flags.

Scenario runs on the air path do this automatically: after the profile apply, the engine pulses the clear 500 ms after its traffic feed starts, so the loops re-acquire on a live signal. A clear issued before traffic flows does not help. A profile apply also clears the loops.

Scenarios and the chain#

Every scenario run conditions the chain first, for a target derived from its profile (radio.loopback: true → pl, otherwise air) unless the scenario declares one, and refuses to start when the target cannot be reached: no run record, no report. See Scenarios.