sjg/trx-rs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs](trx-rs): rework README for readability, link to wiki for details

Browse Source 
Streamline README with centered header, feature summary table, collapsible
install commands, compact data-flow diagram, and documentation table linking
to wiki pages instead of duplicating content.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: Stan Grams <sjg@haxx.space>
This commit is contained in:
Stan Grams
2026-03-29 12:24:27 +02:00
parent a8a1cdfd2f
commit a0f7de6af3
1 changed files with 76 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+76 -199
View File
@@ -1,234 +1,111 @@
<div align="center"> <div align="center">
<img src="assets/trx-logo.png" alt="trx-rs logo" width="25%" /> <img src="assets/trx-logo.png" alt="trx-rs logo" width="25%" />
</div>
# trx-rs # trx-rs
`trx-rs` is a modular amateur radio control stack written in Rust. A modular amateur radio control stack written in Rust.
It splits radio hardware access from user-facing interfaces so you can run
[![License](https://img.shields.io/badge/license-BSD--2--Clause-blue.svg)](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, rig control, SDR DSP, decoding, audio streaming, and web access as separate,
composable pieces. composable pieces.
The project is built around two primary binaries: | | |
|---|---|
- `trx-server`: talks to radios and SDR backends | **Backends** | Yaesu FT-817, Yaesu FT-450D, SoapySDR |
- `trx-client`: connects to the server and exposes frontends such as the web UI | **Frontends** | Web UI, rigctl-compatible TCP, JSON-over-TCP |
| **Decoders** | AIS, APRS, CW, FT8, RDS, VDES, WSPR |
## Web UI Demo | **Audio** | Opus streaming between server, client, and browser |
> GIF placeholder: add an animated walkthrough of the website here.
## What It Does
- Controls supported radios over networked client/server boundaries
- Exposes a browser UI, a rigctl-compatible frontend, and JSON-based control
- Supports SDR workflows with live spectrum, waterfall, demodulation, and decode
- Streams Opus audio between server, client, and browser
- Runs multiple decoders including AIS, APRS, CW, FT8, RDS, VDES, and WSPR
- Supports multi-rig deployments and SDR virtual channels
- Loads backends and frontends via plugins
## Architecture
At a high level:
1. `trx-server` owns the radio hardware and DSP pipeline.
2. `trx-client` connects to the server over TCP for control and audio.
3. Frontends hang off `trx-client`, including the HTTP web UI.
This separation is intentional: it keeps hardware access local to one host while
making control and monitoring available elsewhere on the network.
## Workspace Layout
- `src/trx-core`: shared types, rig state, controller logic
- `src/trx-protocol`: client/server protocol types and codecs
- `src/trx-app`: shared app bootstrapping, config, logging, plugins
- `src/trx-server`: server binary and backend integration
- `src/trx-client`: client binary and remote connection handling
- `src/trx-client/trx-frontend`: frontend abstraction
- `src/decoders`: protocol-specific decoder crates
- `examples/trx-plugin-example`: minimal plugin example
## Supported Pieces
### Backends
- Yaesu FT-817
- Yaesu FT-450D
- SoapySDR-based SDR backend
### Frontends
- HTTP web frontend
- rigctl-compatible TCP frontend
- JSON-over-TCP frontend
### Decoders
- AIS
- APRS
- CW
- FT8
- RDS
- VDES
- WSPR
## Build Requirements
You will need a Rust toolchain (stable) plus a few system libraries.
### Common (all builds)
| Library | Purpose |
|---------|---------|
| **libopus** (dev) | Opus audio codec for streaming between server, client, and browser |
| **pkg-config** or **pkgconf** | Locates system libraries at build time |
| **cmake** | Builds the vendored Opus C source (`audiopus_sys`) when a system copy is not found |
### Platform audio
| Platform | Library | Purpose |
|----------|---------|---------|
| **Linux** | **libasound2** (dev) | ALSA backend for `cpal` audio capture/playback |
| **macOS** | Core Audio (ships with Xcode) | No extra packages needed |
### SDR support (optional)
| Library | Purpose |
|---------|---------|
| **libsoapysdr** (dev) | SDR device abstraction used by the `trx-backend-soapysdr` crate |
SoapySDR is enabled by default. Build without it using `--no-default-features`:
```bash
cargo build --release --no-default-features
```
### Install commands
**Debian / Ubuntu:**
```bash
# Required
sudo apt install build-essential pkg-config cmake libopus-dev libasound2-dev
# Optional — SDR support
sudo apt install libsoapysdr-dev
```
**Fedora:**
```bash
# Required
sudo dnf install gcc pkg-config cmake opus-devel alsa-lib-devel
# Optional — SDR support
sudo dnf install SoapySDR-devel
```
**Arch Linux:**
```bash
# Required
sudo pacman -S base-devel pkgconf cmake opus alsa-lib
# Optional — SDR support
sudo pacman -S soapysdr
```
**macOS (Homebrew):**
```bash
# Required
brew install cmake opus
# Optional — SDR support
brew install soapysdr
```
## Configuration
Both `trx-server` and `trx-client` read from a shared `trx-rs.toml`.
- Default lookup order: current directory, `~/.config/trx-rs`, `/etc/trx-rs`
- Use `--config <FILE>` to point at an explicit config file
- Use `--print-config` to print an example combined config
Start from [`trx-rs.toml.example`](trx-rs.toml.example).
## Quick Start ## Quick Start
### 1. Build ### 1. Install dependencies
<details>
<summary><b>Debian / Ubuntu</b></summary>
```bash ```bash
cargo build sudo apt install build-essential pkg-config cmake libopus-dev libasound2-dev
# Optional — SDR support
sudo apt install libsoapysdr-dev
``` ```
</details>
### 2. Create a config file <details>
<summary><b>Fedora</b></summary>
```bash ```bash
cp trx-rs.toml.example trx-rs.toml sudo dnf install gcc pkg-config cmake opus-devel alsa-lib-devel
# Optional — SDR support
sudo dnf install SoapySDR-devel
``` ```
</details>
Adjust backend, frontend, audio, and auth settings for your environment. <details>
<summary><b>Arch Linux</b></summary>
### 3. Run the server
```bash ```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://github.com/sgrams/trx-rs/wiki/User-Manual#build-requirements)
in the wiki for details on each library.
### 2. Build and run
```bash
cargo build --release
cp trx-rs.toml.example trx-rs.toml # edit for your environment
cargo run -p trx-server cargo run -p trx-server
```
### 4. Run the client
```bash
cargo run -p trx-client cargo run -p trx-client
``` ```
### 5. Open the web UI Open the configured HTTP frontend address in a browser (default `http://localhost:8080`).
Open the configured HTTP frontend address in a browser. Build without SDR support: `cargo build --release --no-default-features`
## Web Frontend Highlights ## How It Works
- Real-time spectrum and waterfall ```
- Frequency, mode, and bandwidth control Radio / SDR hardware
- Decoder dashboards and history | serial or USB
- SDR virtual channels trx-server rig control, DSP, decoders, audio capture
- Browser RX/TX audio | JSON-TCP (4530) + Opus-TCP (4531)
- Optional authentication with read-only and control roles trx-client remote connection, audio relay
|
Frontends Web UI (8080), rigctl (4532), JSON-TCP
```
## Authentication `trx-server` owns hardware access and runs the DSP pipeline.
`trx-client` connects over TCP and exposes user-facing frontends.
The HTTP frontend supports optional passphrase-based authentication. This keeps hardware local to one host while making control available over the network.
- `rx`: read-only access
- `control`: full control access
When exposing the web UI beyond a trusted LAN, run it behind HTTPS and enable
secure cookie settings in the config.
## Audio
Audio is transported as Opus between server, client, and browser.
- `trx-server` captures and encodes audio
- `trx-client` relays audio to the HTTP frontend
- Browsers connect over `/audio`
## Documentation ## Documentation
- [User Manual](docs/User-Manual.md): configuration, features, and usage | Resource | Description |
- [Architecture](docs/Architecture.md): system design, crate layout, data flow, and internals |----------|-------------|
- [`CONTRIBUTING.md`](CONTRIBUTING.md): contribution and commit rules | [User Manual](https://github.com/sgrams/trx-rs/wiki/User-Manual) | Configuration, features, and usage |
| [Architecture](https://github.com/sgrams/trx-rs/wiki/Architecture) | System design, crate layout, data flow, and internals |
## Project Status | [Optimization Guidelines](https://github.com/sgrams/trx-rs/wiki/Optimization-Guidelines) | Performance guidelines for the real-time DSP pipeline |
| [Planned Features](https://github.com/sgrams/trx-rs/wiki/Planned-Features) | Roadmap and design notes |
This is an active project with evolving APIs and frontend behavior. Expect some | [Contributing](CONTRIBUTING.md) | Commit conventions, workflow, and code style |
rough edges and ongoing refactors.
## License ## License
Licensed under BSD-2-Clause. BSD-2-Clause. See [`LICENSES`](LICENSES) for bundled third-party license files.
See [`LICENSES`](LICENSES) for bundled third-party license files.