RF Profiles

A profile is a YAML file describing a complete radio configuration: frequency, gains, modulation, symbol rate, framing and coding. Applying it reconfigures the modem and the AD9361 without touching the bitstream.

A complete example#

This is dsl/profiles/rf_loopback.yaml without its comments: QPSK, uncoded, over the real RF path with an external cable loopback.

version: "satlink.profile/v1"

metadata:
  name: "rf_loopback"
  display_name: "RF loopback (bench, external cable)"
  description: "QPSK uncoded over the real RF path — TX1 -> pad -> splitter -> RX1"
  vendor: "Stellar Systems"
  family: "bring-up"
  revision: "1.0"
  author: "F. du Cray"
  tags: ["bring-up", "loopback", "rf", "test"]

radio:
  rf_port: "RF1"
  duplex: "full"
  center_frequency_hz: 437325000
  tx_enabled: true
  rx_enabled: true
  loopback: false
  tx_power_dbm: -20
  rx_gain_db: 20

phy:
  modulation: "QPSK"
  symbol_rate_baud: 39062.5
  samples_per_symbol: 4
  encoding: "nrz"

framing:
  preamble:
    type: "fill"
    pre_symbols: 512
    post_symbols: 2048
  sync_word:
    value_hex: "1ACFFC1D"
  mtu_bytes: 16
  scrambler:
    enabled: false
  fec:
    type: "none"
  interleaver:
    enabled: false

packet:
  protocol: "raw"
  mtu_bytes: 16

Field reference#

The Effect column says what each field actually does. Fields marked descriptive are parsed, validated for type, stored and displayed, and reach no register: changing them changes nothing on the air.

Top level#

metadata#

radio#

phy#

framing#

What an apply does#

POST /api/v1/profiles/{name}/apply (satlinkctl profile apply <name>):

1. Validate the profile (rules below). A refusal names the field and the reason.
2. Translate it into a list of PL register writes (about 55): loopback mux, channel reset to pass-through, DDC, AGC, matched filter, timing and carrier recovery, slicer, demodulators, deframer, FEC, framer, scrambler, marker inserter, fill, modulators, DUC, TX egress, RSSI.
3. Stage and commit them through the profile sequencer, which waits for a safe point.
4. Tune the AD9361: analog filter bandwidths, LOs and NCO offsets, RX gain and TX attenuation. Failures here do not fail the apply (the modem is configured); they are reported in the result's tuning sentence.
5. Record a profile revision in the store.

An illustrative result:

{
  "profile_name": "rf_loopback",
  "cfg_epoch": 12,
  "tuning": "RX gain 20 dB (AGC → manual), TX attenuation -20 dB; analog BW 200 kHz; LOs tuned to 437292041 Hz with a +32959 Hz NCO offset — centre 437325000 Hz (+0 Hz from the profile's 437325000), leakage 32959 Hz off the band"
}

Some consequences worth knowing:

• An apply resets the channel emulator to pass-through and re-opens the TX egress when tx_enabled is true, including after the RF kill switch.
• An apply performed while traffic flows can time out in WAIT_SAFE. After a successful loopback measurement the datapath may stay busy and later applies time out until a reboot: apply before you measure, never after.
• A later manual change (frequency, gain, register) marks the profile dirty: GET /api/v1/profiles/active returns {"name": "...", "dirty": true, "dirty_reason": "..."}.
• A scenario applies its own profile at the start of every run (see Scenarios).

Validation rules#

Managing profiles#

satlinkctl profile list
satlinkctl profile get rf_loopback       # the profile as JSON
satlinkctl profile apply rf_loopback
satlinkctl profile active

The daemon loads every *.yaml directly inside [daemon] profiles_dir (/opt/satlink/dsl/profiles on the board) at startup; files in subdirectories are not loaded, and a file that fails to parse is skipped with a warning in the log.

Pushing a profile without a firmware release#

PUT /api/v1/profiles/{name} registers a profile sent as YAML (or JSON) in the request body:

curl -X PUT --data-binary @my_profile.yaml \
     -H 'content-type: text/plain' \
     http://192.168.2.1:8080/api/v1/profiles/my_profile

{"name": "my_profile", "replaced": false, "persisted": false,
 "note": "registered in memory only — it is gone at the next daemon restart, and nothing was written to profiles_dir"}

The profile is held in memory only and disappears at the next daemon restart. Keep your file as the source of truth. To ship a profile permanently, add it to dsl/profiles/ and build a release.

GET /api/v1/profiles/{name}/revisions lists when a profile was applied (newest first), from the run store.

Shipped profiles#

Mission profiles cannot match their spacecraft's real 9600-baud links: the modem's lowest rate is 19 531.25 baud. The profile files say so in their comments.

Writing your own profile#

1. Start from pl_loopback.yaml (PL loopback) or rf_loopback.yaml (air), which have a measured baseline behind them.
2. Change one thing at a time and prove it with the PL loopback before going on air.
3. For air profiles: enable the scrambler, set radio.loopback: false, set rx_gain_db for your cabling (see RF Fundamentals) and tx_power_dbm as a negative attenuation.
4. Keep mtu_bytes a divisor of 4096 unless you use Reed-Solomon (which forces 223).
5. Push it with PUT /api/v1/profiles/{name}, apply it, and read the tuning sentence and satlinkctl chain status.