trx-rs logo # trx-rs A modular amateur radio control stack written in Rust. [![License](https://img.shields.io/badge/license-GPL--2.0--or--later-blue.svg)](LICENSES)
`trx-rs` splits radio hardware access from user-facing interfaces so you can run rig control, SDR DSP, decoding, audio streaming, and web access as separate, composable pieces. | | | |---|---| | **Backends** | Yaesu FT-817, Yaesu FT-450D, SoapySDR | | **Frontends** | Web UI, rigctl-compatible TCP, JSON-over-TCP | | **Decoders** | AIS, APRS, CW, FT8, RDS, VDES, WSPR | | **Audio** | Opus streaming between server, client, and browser | ## Quick Start ### 1. Install dependencies
Debian / Ubuntu ```bash sudo apt install build-essential pkg-config cmake libopus-dev libasound2-dev # Optional — SDR support sudo apt install libsoapysdr-dev ```
Fedora ```bash sudo dnf install gcc pkg-config cmake opus-devel alsa-lib-devel # Optional — SDR support sudo dnf install SoapySDR-devel ```
Arch Linux ```bash sudo pacman -S base-devel pkgconf cmake opus alsa-lib # Optional — SDR support sudo pacman -S soapysdr ```
macOS (Homebrew) ```bash brew install cmake opus # Optional — SDR support brew install soapysdr ```
See [Build Requirements](https://git.haxx.space/sjg/trx-rs/wiki/User-Manual#build-requirements) in the wiki for details on each library. > **Note:** `cmake` is required even when a system Opus library is installed. > The `audiopus_sys` crate probes for Opus via `pkg-config`; if it is not found > (or `pkg-config` is unavailable), it falls back to compiling a vendored copy > of Opus with CMake. A missing `cmake` therefore fails the build with > `is cmake not installed?` rather than a missing-Opus error. ### 2. Build ```bash cargo build --release ``` Build without SDR support: `cargo build --release --no-default-features` ### 3. Configure Run the interactive setup wizard to generate config files for your station: ```bash ./target/release/trx-configurator ``` The wizard walks you through rig selection, serial port detection, audio settings, and frontend options, then writes `trx-server.toml` and `trx-client.toml`. Alternatively, copy `trx-rs.toml.example` — a commented example covering every setting — and edit it by hand: ```bash cp trx-rs.toml.example trx-rs.toml ./target/release/trx-server --check-config --config trx-rs.toml ``` `--check-config` reports everything wrong with a config without starting anything. `--print-config` prints the same settings without comments. ### 4. Run ```bash ./target/release/trx-server --config trx-server.toml ./target/release/trx-client --config trx-client.toml ``` A single `trx-rs.toml` can configure both: the server reads its `[trx-server]` section and the client reads `[trx-client]`. Open the configured HTTP frontend address in a browser (default `http://localhost:8080`). ### 5. Install (optional, Linux + systemd) To build, install the binaries system-wide, and set up systemd **user** services that run the server and client in the background: ```bash script/install.sh ``` This builds in release mode, installs `trx-server`, `trx-client`, and `trx-configurator` to `/usr/local/bin` (using `sudo` only if needed), seeds `~/.config/trx-rs/trx-rs.toml` from the example (existing config is never overwritten), and installs `~/.config/systemd/user/{trx-server,trx-client}.service`. ```bash script/install.sh --prefix ~/.local # install to ~/.local/bin instead script/install.sh --no-sdr # build without SoapySDR support script/install.sh --enable-now # also enable + start the services now script/install.sh --help # all options ``` After editing your config, manage the services with: ```bash systemctl --user enable --now trx-server trx-client # start now + on login journalctl --user -u trx-server -u trx-client -f # follow logs loginctl enable-linger "$USER" # keep running after logout ``` Serial (`/dev/ttyUSB*`) and audio access require your user to be in the `dialout` and `audio` groups. Remove everything with `script/uninstall.sh` (add `--purge` to also delete the config). For an unattended or remotely accessible installation, follow the [safe deployment guide](docs/Deployment.md). It covers a dedicated service account, device permissions, authentication, firewall and reverse-proxy boundaries, verification, upgrades, and rollback. ## How It Works ```mermaid graph TD SDR1["SDR #1"] & SDR2["SDR #2"] <-->|USB| S1["trx-server A"] SDR3["SDR #3"] & FT817["FT-817"] <-->|USB / serial| S2["trx-server B"] S1 <-->|"JSON-TCP :4530"| C1["trx-client"] S1 -->|"Opus-TCP per rig"| C1 S2 <-->|"JSON-TCP :4530"| C1 S2 -->|"Opus-TCP per rig"| C1 C1 <-->|internal channels| F1["Web UI :8080"] C1 <-->|internal channels| F2["rigctl :4532"] ``` Each `trx-server` owns one or more rigs and runs DSP, decoding, and audio capture locally. A `trx-client` connects to any number of servers over TCP and exposes them through a unified set of frontends. ## Documentation | Resource | Description | |----------|-------------| | [User Manual](https://git.haxx.space/sjg/trx-rs/wiki/User-Manual) | Configuration, features, and usage | | [Architecture](https://git.haxx.space/sjg/trx-rs/wiki/Architecture) | System design, crate layout, data flow, and internals | | [Optimization Guidelines](https://git.haxx.space/sjg/trx-rs/wiki/Optimization-Guidelines) | Performance guidelines for the real-time DSP pipeline | | [Planned Features](https://git.haxx.space/sjg/trx-rs/wiki/Planned-Features) | Roadmap and design notes | | [Contributing](CONTRIBUTING.md) | Commit conventions, workflow, and code style | ## License GPL-2.0-or-later. See [`LICENSES`](LICENSES) for the full license text and bundled third-party license files. Bundled third-party components retain their original licenses: Leaflet is BSD-2-Clause, DSEG is OFL-1.1, and opus-decoder is MIT. The APRS symbol sprites come from [hessu/aprs-symbols](https://github.com/hessu/aprs-symbols); their per-symbol copyright status is catalogued in [`LICENSES/LicenseRef-APRS-Symbols.txt`](LICENSES/LicenseRef-APRS-Symbols.txt).