trx-rs/autogendoc/CONFIGURATION.md

# Configuration

This document lists all currently supported configuration options for `trx-server` and `trx-client`.

## File Locations

### `trx-server`
Configuration lookup order:
1. `--config <FILE>`
2. `./trx-server.toml`
3. `~/.trx-server.toml`
4. `~/.config/trx-rs/server.toml`
5. `/etc/trx-rs/server.toml`

### `trx-client`
Configuration lookup order:
1. `--config <FILE>`
2. `./trx-client.toml`
3. `~/.config/trx-rs/client.toml`
4. `/etc/trx-rs/client.toml`

CLI options override file values.

## Environment Variables

- `TRX_PLUGIN_DIRS`: additional plugin directories (path-separated), used by both server and client.

## `trx-server` Options

### `[general]`
- `callsign` (`string`, default: `"N0CALL"`)
- `log_level` (`string`, optional): one of `trace|debug|info|warn|error`
- `latitude` (`float`, optional): `-90..=90`
- `longitude` (`float`, optional): `-180..=180`

Notes:
- `latitude` and `longitude` must be set together or both omitted.

### `[rig]`
- `model` (`string`, required effectively unless provided by CLI `--rig`)
- `initial_freq_hz` (`u64`, default: `144300000`, must be `> 0`)
- `initial_mode` (`string`, default: `"USB"`): one of `LSB|USB|CW|CWR|AM|WFM|FM|DIG|PKT`

### `[rig.access]`
- `type` (`string`, default behavior: `serial` if omitted): `serial|tcp|sdr`
- Serial mode:
  - `port` (`string`)
  - `baud` (`u32`)
- TCP mode:
  - `host` (`string`)
  - `tcp_port` (`u16`)
- SDR mode:
  - `args` (`string`, required when `type = "sdr"`): SoapySDR device args string (e.g. `"driver=rtlsdr"` or `"driver=airspy,serial=00000001"`). Passed verbatim to `SoapySDR::Device::new()`.

Notes:
- For `serial`, both `port` and `baud` are required.
- For `tcp`, both `host` and `tcp_port` are required.
- For `sdr`, `args` must be non-empty. The `port`, `baud`, `host`, and `tcp_port` fields are ignored.

### `[behavior]`
- `poll_interval_ms` (`u64`, default: `500`, must be `> 0`)
- `poll_interval_tx_ms` (`u64`, default: `100`, must be `> 0`)
- `max_retries` (`u32`, default: `3`, must be `> 0`)
- `retry_base_delay_ms` (`u64`, default: `100`, must be `> 0`)

### `[listen]`
- `enabled` (`bool`, default: `true`)
- `listen` (`ip`, default: `127.0.0.1`)
- `port` (`u16`, default: `4530`, must be `> 0` when enabled)

### `[listen.auth]`
- `tokens` (`string[]`, default: `[]`)

Notes:
- Empty token strings are invalid.
- Empty list means no auth required.

### `[audio]`
- `enabled` (`bool`, default: `true`)
- `listen` (`ip`, default: `127.0.0.1`)
- `port` (`u16`, default: `4531`, must be `> 0` when enabled)
- `rx_enabled` (`bool`, default: `true`)
- `tx_enabled` (`bool`, default: `true`)
- `device` (`string`, optional)
- `sample_rate` (`u32`, default: `48000`, valid: `8000..=192000`)
- `channels` (`u8`, default: `1`, valid: `1|2`)
- `frame_duration_ms` (`u16`, default: `20`, valid: `3|5|10|20|40|60`)
- `bitrate_bps` (`u32`, default: `24000`, must be `> 0`)

Notes:
- When `[audio].enabled = true`, at least one of `rx_enabled` or `tx_enabled` must be true.

### `[pskreporter]`
- `enabled` (`bool`, default: `false`)
- `host` (`string`, default: `"report.pskreporter.info"`, must not be empty when enabled)
- `port` (`u16`, default: `4739`, must be `> 0` when enabled)
- `receiver_locator` (`string`, optional)

Notes:
- If `receiver_locator` is omitted, server tries deriving it from `[general].latitude`/`longitude`.
- PSK Reporter software ID is hardcoded to: `trx-server v<version> by SP2SJG`.

### `[aprsfi]`
- `enabled` (`bool`, default: `false`)
- `host` (`string`, default: `"rotate.aprs.net"`, must not be empty when enabled)
- `port` (`u16`, default: `14580`, must be `> 0` when enabled)
- `passcode` (`i32`, default: `-1`)

Notes:
- When `passcode = -1` (the default), the passcode is auto-computed from `[general].callsign` using the standard APRS-IS hash algorithm.
- `[general].callsign` must be non-empty when `[aprsfi].enabled = true`; otherwise the IGate is silently disabled at startup.
- Only APRS packets with valid CRC are forwarded; packets from other decoders (FT8, WSPR, CW) are ignored.
- The IGate reconnects automatically with exponential backoff (1 s → 2 s → … → 60 s) on TCP errors.
- Requires `[audio].enabled = true` (APRS packets are decoded from audio).

### `[sdr]`
- `sample_rate` (`u32`, default: `1920000`, must be `> 0`): IQ capture rate in Hz. Must be supported by the device.
- `bandwidth` (`u32`, default: `1500000`): Hardware IF filter bandwidth in Hz.
- `center_offset_hz` (`i64`, default: `100000`): The SDR tunes this many Hz below the dial frequency to keep the signal off the DC spur. Negative values tune above.

### `[sdr.gain]`
- `mode` (`string`, default: `"auto"`): `"auto"` enables hardware AGC (falls back to `"manual"` with a warning if the device does not support it); `"manual"` uses the fixed `value`.
- `value` (`f64`, default: `30.0`): Gain in dB. Used only when `mode = "manual"`.

### `[[sdr.channels]]`

Defines one virtual receiver channel within the wideband IQ stream. At least one channel is required when using the `soapysdr` backend. The **first** channel in the list is the *primary* channel: `set_freq` and `set_mode` from rig control apply to it, and `get_status` reads from it.

- `id` (`string`, default: `""`): Human-readable label used in logs.
- `offset_hz` (`i64`, default: `0`): Frequency offset from the dial frequency in Hz. Primary channel should be `0`.
- `mode` (`string`, default: `"auto"`): Demodulation mode. `"auto"` follows the RigCat `set_mode` command; or a fixed mode string: `LSB`, `USB`, `CW`, `CWR`, `AM`, `WFM`, `FM`, `DIG`, `PKT`.
- `audio_bandwidth_hz` (`u32`, default: `3000`): One-sided bandwidth of the post-demodulation audio BPF in Hz.
- `fir_taps` (`usize`, default: `64`): FIR filter tap count. Higher values give sharper roll-off at the cost of latency.
- `cw_center_hz` (`u32`, default: `700`): CW tone centre frequency in the audio domain (Hz).
- `wfm_bandwidth_hz` (`u32`, default: `75000`): Pre-demodulation filter bandwidth for WFM only (Hz).
- `decoders` (`string[]`, default: `[]`): Decoder IDs that receive this channel's PCM audio. Valid values: `"ft8"`, `"wspr"`, `"aprs"`, `"cw"`. Each decoder ID may appear in at most one channel.
- `stream_opus` (`bool`, default: `false`): Encode this channel's audio as Opus and stream to clients over the TCP audio port. At most one channel may set this to `true`.

Notes:
- Requires `libSoapySDR` installed (`brew install soapysdr` on macOS; `libsoapysdr-dev` on Debian/Ubuntu).
- The SDR backend is RX-only. `[audio] tx_enabled` must be `false`.
- Channel IF constraint: `|center_offset_hz + offset_hz| < sample_rate / 2` for every channel; violated channels cause a startup error.
- `[audio] sample_rate` must match the output audio rate of the SDR pipeline (48000 Hz recommended).
- Use `trx-server --print-config` to see all defaults. SDR fields appear only if the binary was built with `--features soapysdr`.

### `[decode_logs]`
- `enabled` (`bool`, default: `false`)
- `dir` (`string`, default: `"$XDG_DATA_HOME/trx-rs/decoders"`; fallback: `"logs/decoders"`, must not be empty when enabled)
- `aprs_file` (`string`, default: `"TRXRS-APRS-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
- `cw_file` (`string`, default: `"TRXRS-CW-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
- `ft8_file` (`string`, default: `"TRXRS-FT8-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)
- `wspr_file` (`string`, default: `"TRXRS-WSPR-%YYYY%-%MM%-%DD%.log"`, must not be empty when enabled)

Notes:
- Decoder logs are server-side and split by decoder name (APRS/CW/FT8/WSPR).
- Files are appended in JSON Lines format (one JSON object per line).
- Supported filename date tokens: `%YYYY%`, `%MM%`, `%DD%` (UTC date).

## `trx-client` Options

### `[general]`
- `callsign` (`string`, default: `"N0CALL"`)
- `log_level` (`string`, optional): one of `trace|debug|info|warn|error`

### `[remote]`
- `url` (`string`, optional in file but required at runtime unless provided by CLI `--url`)
- `poll_interval_ms` (`u64`, default: `750`, must be `> 0`)

### `[remote.auth]`
- `token` (`string`, optional)

Notes:
- If provided, token must not be empty/whitespace.

### `[frontends.http]`
- `enabled` (`bool`, default: `true`)
- `listen` (`ip`, default: `127.0.0.1`)
- `port` (`u16`, default: `8080`, must be `> 0` when enabled)

### `[frontends.rigctl]`
- `enabled` (`bool`, default: `false`)
- `listen` (`ip`, default: `127.0.0.1`)
- `port` (`u16`, default: `4532`, must be `> 0` when enabled)

### `[frontends.http_json]`
- `enabled` (`bool`, default: `true`)
- `listen` (`ip`, default: `127.0.0.1`)
- `port` (`u16`, default: `0`)
- `auth.tokens` (`string[]`, default: `[]`)

Notes:
- `port = 0` means ephemeral bind (allowed).
- Empty token strings are invalid.

### `[frontends.audio]`
- `enabled` (`bool`, default: `true`)
- `server_port` (`u16`, default: `4531`, must be `> 0` when enabled)
- `bridge.enabled` (`bool`, default: `false`): enables local `cpal` audio bridge
- `bridge.rx_output_device` (`string`, optional): exact local playback device name
- `bridge.tx_input_device` (`string`, optional): exact local capture device name
- `bridge.rx_gain` (`float`, default: `1.0`, must be finite and `>= 0`)
- `bridge.tx_gain` (`float`, default: `1.0`, must be finite and `>= 0`)

Notes:
- The bridge is intended for local WSJT-X integration via virtual audio devices.
- Linux: typically use ALSA loopback (`snd-aloop`).
- macOS: install a virtual CoreAudio device (e.g. BlackHole), then set device names above.

## CLI Override Summary

### `trx-server`
- `--config`, `--print-config`
- `--rig`, `--access`, positional `RIG_ADDR`
- `--callsign`
- `--listen`, `--port` (JSON listener)
- SDR backend: all SDR options are file-only (`[sdr]` and `[[sdr.channels]]`).

### `trx-client`
- `--config`, `--print-config`
- `--url`, `--token`, `--poll-interval`
- `--frontend` (comma-separated)
- `--http-listen`, `--http-port`
- `--rigctl-listen`, `--rigctl-port`
- `--http-json-listen`, `--http-json-port`
- `--callsign`