<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.

[![License](https://img.shields.io/badge/license-GPL--2.0--or--later-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,
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, generate example configs and edit them by hand:

```bash
./target/release/trx-server --print-config > trx-server.toml
./target/release/trx-client --print-config > trx-client.toml
```

### 4. Run

```bash
./target/release/trx-server --config trx-server.toml
./target/release/trx-client --config trx-client.toml
```

Open the configured HTTP frontend address in a browser (default `http://localhost:8080`).

## 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).
