Daemon Configuration · Stellar Link

satlinkd is configured by one TOML file. On the board it is /etc/satlinkd/satlinkd.toml, installed by the firmware build from stellar-fw/overlay/etc/satlinkd/satlinkd.toml.

Command line#

text

satlinkd [-c|--config <FILE>] [-l|--log-level <FILTER>] [--dry-run]

Option	Environment	Meaning
`-c`, `--config`	`SATLINKD_CONFIG`	The configuration file. Without it, `./satlinkd.toml` then `/etc/satlinkd/satlinkd.toml` are searched
`-l`, `--log-level`	`SATLINKD_LOG_LEVEL`	A log filter (`info`, `debug`, `satlink_api=debug,info`, …). When given, it overrides `[observability] log_filter`
`--dry-run`	—	Load and validate the configuration, then exit without starting any service

If the configured filter would silence the daemon's own info messages, the daemon says so on standard error: a filter string that parses but matches nothing is otherwise indistinguishable from a quiet daemon.

On the board the daemon is started at boot by /etc/init.d/S99satlinkd {start|stop|restart} and logs to /var/log/satlinkd.log.

Changing the configuration on a board#

/etc is on the RAM disk. An edit there works until the next reboot:

Shell

ssh root@192.168.2.1
vi /etc/satlinkd/satlinkd.toml
satlinkd --config /etc/satlinkd/satlinkd.toml --dry-run    # check it
/etc/init.d/S99satlinkd restart

A permanent change goes into stellar-fw/overlay/etc/satlinkd/satlinkd.toml and a new release.

`[daemon]`#

Key	Board	Default	Meaning
`profiles_dir`	`/opt/satlink/dsl/profiles`	`dsl/profiles`	Profiles, `*.yaml` directly in the directory
`scenarios_dir`	`/opt/satlink/dsl/scenarios`	`dsl/scenarios`	Scenarios, loaded recursively; `POST /api/v1/scenarios` writes here
`campaigns_dir`	`/opt/satlink/dsl/campaigns`	`dsl/campaigns`	Campaigns
`campaign_state_dir`	`/mnt/jffs2/satlink-campaigns`	the same	Campaign cursors. Must survive a reboot: keep it on `/mnt/jffs2`

`[api]`#

Key	Board	Default	Meaning
`bind`	`0.0.0.0:8080`	`0.0.0.0:8080`	REST and WebSocket listener
`cors_origins`	`["*"]`	`["http://localhost:5173"]`	Allowed browser origins; `"*"` allows any
`auth_required`	—	`false`	Require a JWT on mutating requests (needs the `auth` build feature)
`auth_secret`	—	empty	HS256 secret for those tokens
`max_body_bytes`	—	20 MiB	Largest request body. Hex payloads double in size, and a transmit request costs about 11× its useful bytes in memory while it is processed. Use `/ws/tx` for large transfers

`[pl_driver]`#

Key	Board	Meaning
`uio_device`	`/dev/uio0`	The UIO node mapping the PL's 1 MiB window
`map_index`	`0`	UIO map index
`mock`	`false`	Required, no default. `true` uses an in-memory stub instead of the hardware. It is mandatory on purpose: a board whose configuration lost this key refuses to start rather than serving invented register values
`trace_writes`	`true`	Log every PL register write by name
`trace_to_kmsg`	`true`	Send those lines to `/dev/kmsg`, so they reach `dmesg` and the serial console, and survive in the kernel log when the RAM-disk log file is lost to a freeze

`[telemetry]`#

Key	Board	Meaning
`poll_interval_ms`	`200`	Telemetry cadence (5 Hz on the board)
`watch_registers`	about 30 names	PL registers sampled on every tick by catalogued name; assertable as `reg.<name>`. Unknown names are reported at startup and dropped. Default: none. See Telemetry and Metrics

`[store]`#

Key	Board	Meaning
`sqlite_path`	`/var/lib/satlink/satlink.db`	The run store (reports, run history, profile revisions). On the RAM disk: lost at reboot
`disabled`	—	`true` opens no store

`[observability]`#

Key	Board	Default	Meaning
`metrics_bind`	`0.0.0.0:9090`	`0.0.0.0:9090`	Prometheus exporter
`log_filter`	`info`	`info`	Log filter (overridden by `--log-level`)
`json_logs`	—	`false`	JSON log lines
`journald`	—	`false`	Log to journald

`[datapath]`#

Key	Board	Default	Meaning
`autostart`	`false`	`false`	Claim the modem's IIO devices at startup. Leave it off on a bench: holding them makes every other tool fail with `EBUSY`, which looks like a dead modem. The daemon claims them on demand
`buffer_length`	`4096`	`4096`	IIO buffer length in samples; a block is `buffer_length × 4` bytes and carries `buffer_length` useful bytes

`[radio]`#

Key	Default	Meaning
`condition_at_start`	`false`	Run the AD9361 calibration and interface tuning once at startup. Off because a conditioning from a power-cycled part has taken a board off the network; turn it on only after measuring it on your board
`boot_profile`	none	The profile whose rate the startup tuning targets
`condition_timeout_s`	`180`	Give up on the startup conditioning after this long (the API comes up regardless)
`settle_after_calibrate_ms`	`2000`	Wait between calibration and tuning

`[monitor]` and `[iq]`#

Key	Default	Meaning
`[monitor] synthetic_fft`	`false`	Manufacture a spectrum when no samples are available (UI work without a board). Responses are then marked `synthetic: true`
`[iq] allow_synthetic`	`false`	Allow IQ captures to fall back to a synthesised tone, marked `synthetic: true`

`[link]`#

Key	Board	Default	Meaning
`enabled`	`true`	`false`	Run the ZeroMQ bridge
`kind`	`zmq`	`zmq`	Transport; only `zmq` is implemented, anything else is refused
`bind_address`	`0.0.0.0`	`0.0.0.0`	Listen address
`tx_port`	`5555`	`5555`	PULL: frames in
`rx_port`	`5556`	`5556`	PUB: frames received
`telemetry_port`	`5557`	`5557`	PUB: telemetry; `0` disables it
`frame_slot_bytes`	`0`	`0`	`0` publishes whole blocks; `N` parses `N`-byte slots. Must match the profile's `mtu_bytes` and divide 4096

See ZeroMQ Link Service.

A minimal host configuration#

For UI or API work on a host without a board (ps/config/satlinkd.default.toml):

TOML

[daemon]
profiles_dir  = "dsl/profiles"
scenarios_dir = "dsl/scenarios"

[api]
bind         = "0.0.0.0:8080"
cors_origins = ["http://localhost:5173"]

[pl_driver]
uio_device = "/dev/uio0"
map_index  = 0
mock       = true

[telemetry]
poll_interval_ms = 200

Command line#

Changing the configuration on a board#

[daemon]#

[api]#

[pl_driver]#

[telemetry]#

[store]#

[observability]#

[datapath]#

[radio]#

[monitor] and [iq]#

[link]#

A minimal host configuration#

`[daemon]`#

`[api]`#

`[pl_driver]`#

`[telemetry]`#

`[store]`#

`[observability]`#

`[datapath]`#

`[radio]`#

`[monitor]` and `[iq]`#

`[link]`#