[docs](trx-rs): generate the example config and correct the manual

trx-rs.toml.example was maintained by hand and had fallen well behind: no
[[rigs]], no [[remotes]], no [timeouts], no bandplan or decode-history
settings, and a [frontends.http].default_rig_id that had been renamed.

Generate it from the config structs instead, so a new field shows up the moment
it exists, and add a test that fails when the checked-in copy drifts:

    cargo run -p trx-config --example generate_example

Section comments come from a small table; a section without an entry is still
emitted, so forgetting a comment can never drop a setting from the example.

The manual was wrong about the basics.  It listed five config search paths, none
of which the loader has ever looked at (the real order is ./trx-rs.toml → XDG →
/etc), called --print-config output "fully commented" when it carries no
comments at all, and documented a TRX_PLUGIN_DIRS variable no code reads.  It
also still described [frontends.rigctl].port as the bind port years after
rig_ports replaced it.  Fixed, and the new configuration features are written
up alongside.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SyX26FCpMQxiBoC7r5K1A7
Signed-off-by: Stan Grams <sjg@haxx.space>

trx-rs.toml.example

@@ -1,36 +1,60 @@
+# trx-rs example configuration
+#
+# Generated from the config structs; regenerate with:
+#     cargo run -p trx-config --example generate_example
+#
+# Both sections are optional: trx-server reads [trx-server], trx-client reads
+# [trx-client], and either may live in its own file with the section header
+# omitted.  Any string may use ${ENV_VAR}, and credentials may be moved out of
+# this file with the matching *_file keys.
+#
+# Check a config without starting anything:
+#     trx-server --check-config --config trx-rs.toml
+#     trx-client --check-config --config trx-rs.toml
+
+# Server: drives the radio hardware.
 [trx-server]
 rigs = []
 
+# Station identity.  Coordinates feed PSKReporter and the map.
 [trx-server.general]
 callsign = "N0CALL"
 log_level = "info"
 latitude = 52.2297
 longitude = 21.0122
 
+# Single-rig layout.  For several radios, delete this and use [[rigs]].
 [trx-server.rig]
 model = "ft817"
 initial_freq_hz = 144300000
 initial_mode = "USB"
 
+# How to reach the radio: serial, tcp, or sdr.
 [trx-server.rig.access]
 type = "serial"
 port = "/dev/ttyUSB0"
 baud = 9600
 
+# CAT polling and retry behaviour.
 [trx-server.behavior]
 poll_interval_ms = 500
 poll_interval_tx_ms = 100
 max_retries = 3
 retry_base_delay_ms = 100
+vfo_prime = true
 
+# JSON control listener that trx-client connects to.
 [trx-server.listen]
 enabled = true
 listen = "127.0.0.1"
 port = 4530
 
+# Tokens clients must present.  Empty means no authentication.
+# Use tokens_file = "/etc/trx-rs/tokens" to keep them out of this file.
 [trx-server.listen.auth]
 tokens = []
 
+# Opus audio stream for trx-client.
 [trx-server.audio]
 enabled = true
 listen = "127.0.0.1"
@@ -42,25 +66,52 @@ channels = 2
 frame_duration_ms = 20
 bitrate_bps = 256000
 
+# Report FT8/FT4/WSPR spots to pskreporter.info.
 [trx-server.pskreporter]
 enabled = false
 host = "report.pskreporter.info"
 port = 4739
 
+# Forward received APRS frames to APRS-IS.
 [trx-server.aprsfi]
 enabled = false
 host = "rotate.aprs.net"
 port = 14580
 passcode = -1
+beacon = false
+beacon_interval_secs = 1200
+beacon_symbol_table = "/"
+beacon_symbol_code = "-"
 
+# Write decodes to JSON Lines files.
 [trx-server.decode_logs]
 enabled = false
-dir = "/path/to/log/dir"
+dir = "/Users/sjg/Library/Caches/trx-rs/decoders"
 aprs_file = "TRXRS-APRS-%YYYY%-%MM%-%DD%.log"
 cw_file = "TRXRS-CW-%YYYY%-%MM%-%DD%.log"
 ft8_file = "TRXRS-FT8-%YYYY%-%MM%-%DD%.log"
 wspr_file = "TRXRS-WSPR-%YYYY%-%MM%-%DD%.log"
+wefax_file = "TRXRS-WEFAX-%YYYY%-%MM%-%DD%.log"
 
+# Which decoders run.  Trimming this list saves real CPU on small boxes.
+# Valid names: aprs, aprs_hf, ais, cw, ft2, ft4, ft8, lrpt, sstv, vdes, wefax, wspr.
+[trx-server.decoders]
+enabled = [
+    "aprs",
+    "aprs_hf",
+    "ais",
+    "cw",
+    "ft2",
+    "ft4",
+    "ft8",
+    "lrpt",
+    "sstv",
+    "vdes",
+    "wefax",
+    "wspr",
+]
+
+# SoapySDR pipeline; used when [rig.access] type = "sdr".
 [trx-server.sdr]
 sample_rate = 1920000
 bandwidth = 1500000
@@ -69,16 +120,35 @@ center_offset_hz = 100000
 channels = []
 max_virtual_channels = 4
 
+# "auto" for hardware AGC, or "manual".
 [trx-server.sdr.gain]
 mode = "auto"
 value = 30.0
 
+# Software squelch on demodulated audio.
 [trx-server.sdr.squelch]
 enabled = false
 threshold_db = -65.0
 hysteresis_db = 3.0
 tail_ms = 180
 
+# Impulse-noise suppression on the IQ stream.
+[trx-server.sdr.noise_blanker]
+enabled = false
+threshold = 10.0
+
+# Timeout and buffer tuning.  The defaults suit most setups.
+[trx-server.timeouts]
+command_exec_timeout_ms = 10000
+poll_refresh_timeout_ms = 8000
+io_timeout_ms = 10000
+request_timeout_ms = 12000
+rig_task_channel_buffer = 32
+
+# Client: exposes the radio to users.
+[trx-client]
+
+# Labels shown in the web UI.
 [trx-client.general]
 callsign = "N0CALL"
 website_url = "https://haxx.space"
@@ -86,24 +156,49 @@ website_name = "haxx.space"
 ais_vessel_url_base = "https://www.vesselfinder.com/?mmsi="
 log_level = "info"
 
+# Legacy single-remote form; prefer [[remotes]] below.
 [trx-client.remote]
-url = "192.168.1.100:9000"
-rig_id = "hf"
 poll_interval_ms = 750
 
 [trx-client.remote.auth]
+
+[[trx-client.remotes]]
+name = "home-hf"
+url = "192.168.1.100:4530"
+rig_id = "hf"
+poll_interval_ms = 750
+
+[trx-client.remotes.auth]
 token = "my-token"
 
+[[trx-client.remotes]]
+name = "home-vhf"
+url = "192.168.1.100:4530"
+rig_id = "vhf"
+poll_interval_ms = 750
+
+[trx-client.remotes.auth]
+token = "my-token"
+
+# Web UI.  default_rig_name and the per-rig maps are keyed by the
+# [[remotes]] name, not the server-side rig id.
 [trx-client.frontends.http]
 enabled = true
 listen = "127.0.0.1"
 port = 8080
-default_rig_id = "hf"
+default_rig_name = "home-hf"
 initial_map_zoom = 10
 spectrum_coverage_margin_hz = 50000
 spectrum_usable_span_ratio = 0.9200000166893005
 show_sdr_gain_control = true
+bandplan_enabled = true
+bandplan_region = "iaru_r1"
+decode_history_retention_min = 1440
 
+[trx-client.frontends.http.decode_history_retention_min_by_rig]
+
+# Passphrase login for the web UI.  rx_passphrase_file and
+# control_passphrase_file keep the secrets out of this file.
 [trx-client.frontends.http.auth]
 enabled = false
 rx_passphrase = "rx-passphrase-example"
@@ -113,6 +208,7 @@ session_ttl_min = 480
 cookie_secure = false
 cookie_same_site = "Lax"
 
+# Hamlib-compatible TCP interface, one listener per rig.
 [trx-client.frontends.rigctl]
 enabled = false
 listen = "127.0.0.1"
@@ -120,6 +216,7 @@ port = 4532
 
 [trx-client.frontends.rigctl.rig_ports]
 
+# JSON-over-TCP control interface.
 [trx-client.frontends.http_json]
 enabled = true
 listen = "127.0.0.1"
@@ -128,12 +225,16 @@ port = 0
 [trx-client.frontends.http_json.auth]
 tokens = []
 
+# Where to fetch the audio stream from.
 [trx-client.frontends.audio]
 enabled = true
 server_port = 4531
 
+[trx-client.frontends.audio.rig_urls]
+
 [trx-client.frontends.audio.rig_ports]
 
+# Play RX audio on a local sound device and capture TX from one.
 [trx-client.frontends.audio.bridge]
 enabled = false
 bitrate_bps = 192000