sjg
be9d5c301b
Document deployment with a dedicated service account, restricted device access, authenticated network listeners, systemd user services, reverse proxying, verification, upgrades, and rollback. Assisted-By: OpenAI Codex (GPT-5) Signed-off-by: Stan Grams <sjg@haxx.space>
196 lines
6.3 KiB
Markdown
196 lines
6.3 KiB
Markdown
<div align="center">
|
|
<img src="assets/trx-logo.png" alt="trx-rs logo" width="25%" />
|
|
|
|
# trx-rs
|
|
|
|
A modular amateur radio control stack written in Rust.
|
|
|
|
[](LICENSES)
|
|
|
|
</div>
|
|
|
|
`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
|
|
|
|
<details>
|
|
<summary><b>Debian / Ubuntu</b></summary>
|
|
|
|
```bash
|
|
sudo apt install build-essential pkg-config cmake libopus-dev libasound2-dev
|
|
# Optional — SDR support
|
|
sudo apt install libsoapysdr-dev
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Fedora</b></summary>
|
|
|
|
```bash
|
|
sudo dnf install gcc pkg-config cmake opus-devel alsa-lib-devel
|
|
# Optional — SDR support
|
|
sudo dnf install SoapySDR-devel
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>Arch Linux</b></summary>
|
|
|
|
```bash
|
|
sudo pacman -S base-devel pkgconf cmake opus alsa-lib
|
|
# Optional — SDR support
|
|
sudo pacman -S soapysdr
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary><b>macOS (Homebrew)</b></summary>
|
|
|
|
```bash
|
|
brew install cmake opus
|
|
# Optional — SDR support
|
|
brew install soapysdr
|
|
```
|
|
</details>
|
|
|
|
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).
|