trx-rs/OVERVIEW.md

trx-rs Project Overview

What is trx-rs?

trx-rs is a modular transceiver (radio) control stack written in Rust. It provides a backend service for controlling amateur radio transceivers via CAT (Computer-Aided Transceiver) protocols, with multiple frontend interfaces for access and monitoring.

Current Capabilities

Feature	Status
Yaesu FT-817 CAT control	Implemented
HTTP/Web UI with SSE	Implemented
rigctl-compatible TCP	Implemented
VFO A/B switching	Implemented
PTT control	Implemented
Signal/TX power metering	Implemented
Front panel lock	Implemented
Multiple rig backends	Extensible (only FT-817)
Backend/frontend registry	Implemented
TCP CAT transport	Partial (config wiring only)
JSON TCP control (line-delimited)	Implemented (configurable frontend)
AppKit GUI frontend	Implemented (macOS only, optional)
Plugin registry loading	Implemented (shared libraries)
Configuration file (TOML)	Implemented
Rig state machine	Implemented
Command handlers	Implemented
Event notifications	Implemented (rig task emits events)
Retry/polling policies	Implemented
Controller-based rig task	Implemented

---

Current Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                              trx-server/trx-client                                      │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │                        Application                                  │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │  │
│  │  │    Config    │  │     CLI      │  │      Rig Task            │  │  │
│  │  │  (TOML file) │  │   (clap)     │  │   (main loop)            │  │  │
│  │  └──────────────┘  └──────────────┘  └──────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                  │                                        │
│              ┌───────────────────┴───────────────────┐                   │
│              ▼                                       ▼                   │
│  ┌─────────────────────┐                 ┌─────────────────────┐        │
│  │   trx-core          │                 │   Frontend Layer    │        │
│  │  ┌───────────────┐  │                 │  ┌───────────────┐  │        │
│  │  │  controller/  │  │                 │  │     HTTP      │  │        │
│  │  │  - machine    │  │                 │  │  (REST+SSE)   │  │        │
│  │  │  - handlers   │  │                 │  └───────────────┘  │        │
│  │  │  - events     │  │                 │  ┌───────────────┐  │        │
│  │  │  - policies   │  │                 │  │  HTTP JSON    │  │        │
│  │  └───────────────┘  │                 │  │  (TCP/JSON)   │  │        │
│  └─────────────────────┘                 │  └───────────────┘  │        │
│              │                           │  ┌───────────────┐  │        │
│              │                           │  │    rigctl     │  │        │
│              │                           │  │  (TCP/hamlib) │  │        │
│              │                           │  └───────────────┘  │        │
│              │                           └─────────────────────┘        │
│              ▼                                                           │
│  ┌─────────────────────┐                                                │
│  │   trx-backend       │                                                │
│  │  ┌───────────────┐  │                                                │
│  │  │ FT-817 Driver │  │                                                │
│  │  └───────────────┘  │                                                │
│  └─────────────────────┘                                                │
└──────────────────────────────────────────────────────────────────────────┘

Key Components

Component	Purpose
trx-core	Core types, traits (Rig, RigCat), state definitions, controller components
trx-core/rig/controller	State machine, command handlers, event system, policies
trx-backend	Backend factory and abstraction layer
trx-backend-ft817	FT-817 CAT protocol implementation
trx-frontend	Frontend trait (FrontendSpawner)
trx-frontend-http	Web UI with REST API and SSE
trx-frontend-http-json	JSON-over-TCP control frontend
trx-frontend-appkit	AppKit GUI frontend (macOS only, optional)
trx-frontend-rigctl	Hamlib rigctl-compatible TCP interface
trx-server	Server binary — connects to rig backend, exposes JSON TCP control
trx-client	Client binary — connects to server, runs frontends (HTTP, rigctl)

---

Configuration

trx-rs supports TOML configuration files with the following search order:

1. --config <path> (explicit CLI argument)
2. ./trx-server.toml or ./trx-client.toml (current directory)
3. ~/.config/trx-rs/config.toml (XDG user config)
4. /etc/trx-rs/config.toml (system-wide)

CLI arguments override config file values.

Plugin discovery:

• Uses shared libraries with a trx_register entrypoint.
• Searches ./plugins, ~/.config/trx-rs/plugins, and any paths in TRX_PLUGIN_DIRS.

Example Configuration

[general]
callsign = "N0CALL"

[rig]
model = "ft817"
initial_freq_hz = 144300000
initial_mode = "USB"

[rig.access]
type = "serial"
port = "/dev/ttyUSB0"
baud = 9600

[frontends.http]
enabled = true
listen = "127.0.0.1"
port = 8080

[frontends.rigctl]
enabled = true
listen = "127.0.0.1"
port = 4532

[frontends.http_json]
enabled = true
listen = "127.0.0.1"
port = 9000
auth.tokens = ["demo-token"]

[behavior]
poll_interval_ms = 500
poll_interval_tx_ms = 100
max_retries = 3
retry_base_delay_ms = 100

Use trx-server --print-config or trx-client --print-config to generate an example configuration.

---

Rig Controller Components

Located in trx-core/src/rig/controller/:

State Machine (machine.rs)

Explicit state machine for rig lifecycle management:

pub enum RigMachineState {
    Disconnected,
    Connecting { started_at: Option<u64> },
    Initializing { rig_info: Option<RigInfo> },
    PoweredOff { rig_info: RigInfo },
    Ready(ReadyStateData),
    Transmitting(TransmittingStateData),
    Error { error: RigStateError, previous_state: Box<RigMachineState> },
}

Events trigger state transitions:

• RigEvent::Connected, Initialized, PoweredOn, PoweredOff
• RigEvent::PttOn, PttOff
• RigEvent::Error(RigStateError), Recovered, Disconnected

Command Handlers (handlers.rs)

Trait-based command system with validation:

pub trait RigCommandHandler: Debug + Send + Sync {
    fn name(&self) -> &'static str;
    fn can_execute(&self, ctx: &dyn CommandContext) -> ValidationResult;
    fn execute<'a>(&'a self, executor: &'a mut dyn CommandExecutor)
        -> Pin<Box<dyn Future<Output = DynResult<CommandResult>> + Send + 'a>>;
}

Implemented commands:

• SetFreqCommand, SetModeCommand, SetPttCommand
• PowerOnCommand, PowerOffCommand
• ToggleVfoCommand, LockCommand, UnlockCommand
• GetTxLimitCommand, SetTxLimitCommand, GetSnapshotCommand

The rig task (trx-server/src/rig_task.rs) now syncs the state machine to the live RigState and emits events whenever rig status changes.

Event Notifications (events.rs)

Typed event system for rig state changes:

pub trait RigListener: Send + Sync {
    fn on_frequency_change(&self, old: Option<Freq>, new: Freq);
    fn on_mode_change(&self, old: Option<&RigMode>, new: &RigMode);
    fn on_ptt_change(&self, transmitting: bool);
    fn on_state_change(&self, old: &RigMachineState, new: &RigMachineState);
    fn on_meter_update(&self, rx: Option<&RigRxStatus>, tx: Option<&RigTxStatus>);
    fn on_lock_change(&self, locked: bool);
    fn on_power_change(&self, powered: bool);
}

pub struct RigEventEmitter {
    // Manages listeners and dispatches events
}

Policies (policies.rs)

Configurable retry and polling behavior:

pub trait RetryPolicy: Send + Sync {
    fn should_retry(&self, attempt: u32, error: &RigError) -> bool;
    fn delay(&self, attempt: u32) -> Duration;
    fn max_attempts(&self) -> u32;
}

pub trait PollingPolicy: Send + Sync {
    fn interval(&self, transmitting: bool) -> Duration;
    fn should_poll(&self, transmitting: bool) -> bool;
}

Implementations:

• ExponentialBackoff - Exponential delay with max cap
• FixedDelay - Constant delay between retries
• NoRetry - Fail immediately
• AdaptivePolling - Faster polling during TX
• FixedPolling - Constant interval
• NoPolling - Disable automatic polling

Error Types

RigError now includes error classification:

pub struct RigError {
    pub message: String,
    pub kind: RigErrorKind,  // Transient or Permanent
}

impl RigError {
    pub fn timeout() -> Self;           // Transient
    pub fn communication(msg) -> Self;  // Transient
    pub fn invalid_state(msg) -> Self;  // Permanent
    pub fn not_supported(op) -> Self;   // Permanent
    pub fn is_transient(&self) -> bool;
}

---

Remaining Improvement Opportunities

Integration Work

1. Plugin UX improvements - Add structured plugin metadata (name, version, capabilities) and surface it in CLI help.

Testing

• Add integration tests with mock backends
• Add more backend/frontend unit tests

Features

• Add more rig backends (IC-7300, TS-590, etc.)
• Add TX limit support for FT-817 (or document per-backend constraints in UI)
• Add WebSocket support for bidirectional communication
• Add metrics/telemetry export (Prometheus)
• Add authentication for HTTP frontend

Code Quality

• Add CI/CD pipeline
• Add pre-commit hooks

---

Implementation Status

Component	Status	Tests
State Machine	Implemented	5 tests
Command Handlers	Implemented	3 tests
Event Notifications	Implemented	2 tests
Retry/Polling Policies	Implemented	5 tests
Config File Support	Implemented	4 tests
rigctl Frontend	Implemented	-
HTTP Frontend	Implemented	-
FT-817 Backend	Implemented	-

Total: 19 unit tests passing

---

Building and Running

# Build
cargo build --release

# Run server with CLI args
./target/release/trx-server -r ft817 "/dev/ttyUSB0 9600"

# Run server with config file
./target/release/trx-server --config /path/to/config.toml

# Run client
./target/release/trx-client --config /path/to/client-config.toml

# Print example config
./target/release/trx-server --print-config > trx-server.toml

# Run tests
cargo test

# Run clippy
cargo clippy