Stellar Link Tools & Utilities CLI Reference
satlinkctl is the operator CLI. It talks to satlinkd's REST API, except compare, which runs
entirely on the host.
Shell Copy cd ps && cargo build --release -p satlinkctl
./target/release/satlinkctl --helpGlobal options#
Option Environment Default Meaning
--api <URL>SATLINK_APIhttp://localhost:8080Daemon base URL, without a trailing slash --token <TOKEN>SATLINK_TOKEN— Bearer token when the daemon requires authentication --json— off Machine-readable JSON instead of a human summary -V, --version— — Print the CLI version
Pass negative numbers in the attached form (--rx-hz=-2500), or they are read as flags.
Board and daemon#
Command Purpose
satlinkctl statusDaemon version, uptime and service health satlinkctl doctor [--repeat N]Bring-up health check, every verdict by register name. Re-reads the same address N times (default 20), because some AXI faults only show on repetition. Exit code 0 only when nothing failed satlinkctl plSnapshot of the shell, IRQ and sequencer registers satlinkctl events [--n N]The last N runtime events (default 20) satlinkctl runs [--limit N]The last N scenario runs (default 20)
Note
Without --json, status prints a one-line summary that does not include the release id.
Use curl $SATLINK_API/api/v1/version or satlinkctl --json status when a script needs it.
profile# Command Purpose
profile listAvailable profiles profile get <NAME>A profile, as JSON profile apply <NAME>Apply it (validate, stage, commit, tune) profile activeThe active profile
scenario# Command Purpose
scenario listLoaded scenarios scenario get <NAME>One scenario scenario run <NAME>Start a run; prints the run id
Condition the chain first (chain up) so the run starts without waiting for an AD9361 tuning.
campaign# Command Purpose
campaign listLoaded campaigns campaign get <NAME>One campaign campaign run <NAME> [--follow]Start one; --follow polls the saved state until it stops, surviving a reboot campaign activeWhat is running, and which board provider would take a board action campaign runsEvery execution, newest first campaign status <ID>Cursor, attempts and verdict campaign pause <ID>Stop at the next step boundary campaign resume <ID> [--follow]Continue from the cursor campaign rerun <ID> <STEP>Run one step again, appending an attempt
chain# Command Purpose
chain status [--target T]Every prerequisite, read back from the board, and the first missing one. T is air, device-loopback or pl-loopback; default: what the board is wired for chain up [--target T] [--profile P] [--rate R]Run the missing conditioning steps in order. Target default air; profile default: the applied one; rate (default 8 000 000) is only used when no profile dictates it chain recoverPulse the receiver's clear bits (AGC, timing, carrier)
See Chain Conditioning .
The AD9361 front end: rate, digital interface tuning, and the path switch.
Command Purpose
rf statusRate, device loopback, DAC source, tuning readiness rf calibrateRe-run the part's initialisation and calibrations. Resets the part : run it first rf tune [--rate R]Set the rate (default 8 000 000) and tune the LVDS interface at that rate. Run on an idle chain rf rf [--force]Route through the AD9361's internal digital loopback. Emits nothing rf air [--force]On air: the internal loopback stays open, the signal reaches the TX connector rf plBack to the PL loopback
rf rf and rf air refuse when the interface was never tuned or when the profile was applied
before the last tuning; --force overrides.
radio# Command Purpose
radio statusFrequencies, gains, lock flags, NCO offsets, bandwidths, sample rate radio freq <HZ> [--channel CH]Set the LO(s); CH is rx, tx or both (default). The RX and TX LOs are independent radio nco [--rx-hz HZ] [--tx-hz HZ]Digital NCO offsets from the LO, within ±fs/2 radio gain [--rx-db DB] [--tx-db DB] [--domain D]AD9361 gains with D = rf (default; TX is an attenuation, ≤ 0), or the PL's Q8.8/Q15 scalars with D = digital radio loopback [--on]Toggle the PL loopback mux (--on to set, absent to clear) radio arm-rx, radio disarm-rx [--chan N]Arm or disarm RX radio start-tx, radio stop-tx [--chan N]Start or stop TX (opens or closes the egress) radio reset <SCOPE>Reset rx, tx or all
reg# Command Purpose
reg list [FILTER]Catalogued registers, filtered by substring reg get <NAME>Read one reg set <NAME> <VALUE>Write one (decimal or 0x hex), then read it back
See PL Register Map .
datapath and tx# Command Purpose
datapath statusWho holds the modem, and whether the TX egress is open datapath enableClaim the modem, then read back whether the claim took datapath disableRelease it tx send [options]Send one frame, then flush tx flush [--blocks N]Flush what is buffered (default 2 blocks)
tx send options:
Option Default Meaning
--hex <HEX> / --file <FILE>— The payload (mutually exclusive) --protocol <P>rawraw, csp or ccsds (built by the CLI)--src <N>10 CSP source address (ignored for raw) --dst <N>1 CSP destination, or CCSDS APID --framing <F>streamstream (no boundary survives) or slot (one packet per FRAME_LEN slot)--slot-len <N>256 Slot pitch; must divide 4096 --flush-blocks <N>2 Blocks the flush emits. Two, so the receive side returns a full block
Measurements#
Command Purpose
capture -o <FILE> [options]Capture raw RX DMA blocks to a file loopback -p <PAYLOAD> [options]Feed a payload while capturing, then compare compare <CAPTURE> <REFERENCE> [options]Compare a capture with the payload that was sent, on the host
capture and loopback options:
Option Default Meaning
--blocks <N>4 Blocks to collect in a row; a short capture fails instead of being truncated --warmup <N>0 Blocks to obtain and discard first (acquisition transient). Explicit on purpose --timeout-ms <MS>30000 Give up after this long --keepoff Keep the IIO devices claimed afterwards --reference <FILE>— capture only: compare straight away-o, --out <FILE>— loopback only: also write the capture
compare options: --block-bytes (raw DMA block size, default 16 384) and --dense (treat every
byte as payload instead of the le:u8/32 contract).
The payload and the capture are in the raw le:u8/32 encoding: one useful byte in the low lane
of each 32-bit word. See Measurement Tools .
Tool Where Purpose
satlinkdps/satlinkdThe daemon: satlinkd [-c CONFIG] [-l LOG_LEVEL] [--dry-run]. See Daemon Configuration satlink-checkps/satlink-checkCold-deploy self-test from the host: daemon reachable, services, PL registers, profiles and scenarios load. --json for a report satlink-benchps/satlink-benchSustained PS↔PL throughput, on the board: one descriptor, one timestamp per write, PL counters read in the same process; --duplex arms a reader first tools/make-release.sh, tools/deploy-release.shrepo root Build, deploy and verify a release (see Releases and Deployment ) pl/top/bringup/resolve-board.shrepo root Print the board's IP, resolved by IIO context name and serial pl/top/bringup/rf_path_gain.pyrepo root Characterise the RF path with a spectrum analyser dsl/tools/leo_pass_profile.pyrepo root Derive LEO pass curves for scenarios (see Channel Models )