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

[docs](trx-rs): replace all ASCII diagrams with Mermaid

Browse Source 
Convert ASCII art and box-drawing diagrams to Mermaid fenced code blocks
across README.md, CLAUDE.md, Architecture.md, Wxsat-Map-Overlay.md, and
trx-wxsat/README.md. Add Mermaid-only policy to CLAUDE.md.

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:29:12 +02:00
parent a0f7de6af3
commit 83c23401fc
5 changed files with 63 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+12 -8
View File
@@ -71,14 +71,14 @@ The project is split into a **server** (connects to the radio hardware) and a **
### Data flow
```
Radio hardware
↕ serial/TCP
trx-server (rig_task.rs)
↕ trx-protocol JSON-TCP (port 4530)
trx-client (remote_client.rs)
↕ internal channels
Frontends: HTTP (8080), rigctl (4532), http-json (ephemeral)
```mermaid
graph TD
Radio["Radio Hardware"] <-->|serial / TCP| Server["trx-server (rig_task.rs)"]
Server <-->|"JSON-TCP :4530"| Client["trx-client (remote_client.rs)"]
Server -->|"Opus-TCP :4531"| Client
Client <-->|internal channels| F1["HTTP Frontend :8080"]
Client <-->|internal channels| F2["rigctl Frontend :4532"]
Client <-->|internal channels| F3["JSON-TCP Frontend"]
```
### trx-core controller
@@ -94,6 +94,10 @@ The rig controller (`src/trx-core/src/rig/controller/`) is the central state man
Signal decoders run as background tasks in `trx-server`, consuming decoded audio. `trx-ftx` provides the FT8/FT4/FT2 decoder in pure Rust. Decoded frames can be forwarded to PSKReporter and APRS-IS (IGate) uplinks, or logged via `trx-decode-log`.
## Diagrams
Always use [Mermaid](https://mermaid.js.org/) for diagrams in Markdown files. Never use ASCII art, box-drawing characters, or plain-text diagrams. GitHub renders Mermaid natively in ```mermaid fenced code blocks.
## Commit Format
```
README.md
+8 -8
View File
@@ -82,14 +82,14 @@ Build without SDR support: `cargo build --release --no-default-features`
## How It Works
```
Radio / SDR hardware
| serial or USB
trx-server rig control, DSP, decoders, audio capture
| JSON-TCP (4530) + Opus-TCP (4531)
trx-client remote connection, audio relay
|
Frontends Web UI (8080), rigctl (4532), JSON-TCP
```mermaid
graph TD
Radio["Radio / SDR Hardware"] <-->|"serial or USB"| Server["trx-server<br/>rig control, DSP, decoders, audio capture"]
Server <-->|"JSON-TCP :4530"| Client["trx-client<br/>remote connection, audio relay"]
Server -->|"Opus-TCP :4531"| Client
Client <-->|internal channels| F1["Web UI :8080"]
Client <-->|internal channels| F2["rigctl :4532"]
Client <-->|internal channels| F3["JSON-TCP"]
```
`trx-server` owns hardware access and runs the DSP pipeline.
docs/Architecture.md
+22 -30
View File
@@ -58,36 +58,28 @@ Target users are amateur radio operators who want networked, automated, or multi
## High-Level Architecture
```
┌──────────────────────────────────────────────────────────┐
│ trx-server │
│ │
│ Radio Hardware (serial/TCP) │
│ ↕ CAT protocol │
│ Rig Backend ──────── rig_task.rs ─── listener.rs │
│ (ft817/ft450d/sdr) (state machine) (JSON TCP :4530) │
│ │ │
│ audio.rs │
│ (Opus :4531) │
│ │ │
│ Decoders │
│ (APRS, CW, FT8, WSPR, RDS) │
│ PSKReporter / APRS-IS │
└──────────────────────────────────────────────────────────┘
↕ JSON TCP (port 4530)
↕ Opus audio TCP (port 4531)
┌──────────────────────────────────────────────────────────┐
│ trx-client │
│ │
│ remote_client.rs (polls state, routes commands) │
│ ↕ internal mpsc/watch channels │
│ Frontends: │
│ trx-frontend-http (Web UI :8080) │
│ trx-frontend-rigctl (rigctl :4532) │
│ trx-frontend-http-json (JSON/TCP ephemeral) │
└──────────────────────────────────────────────────────────┘
↕ Browser / Hamlib / Custom tools
End Users
```mermaid
graph TD
subgraph server["trx-server"]
HW["Radio Hardware"] <-->|"CAT protocol<br/>serial / TCP"| Backend["Rig Backend<br/>(ft817 / ft450d / sdr)"]
Backend --> RigTask["rig_task.rs<br/>(state machine)"]
RigTask --> Listener["listener.rs<br/>(JSON TCP :4530)"]
RigTask --> Audio["audio.rs<br/>(Opus :4531)"]
Audio --> Decoders["Decoders<br/>(APRS, CW, FT8, WSPR, RDS)"]
Decoders --> Uplinks["PSKReporter / APRS-IS"]
end
subgraph client["trx-client"]
Remote["remote_client.rs<br/>(polls state, routes commands)"]
Remote <-->|"mpsc / watch channels"| HTTP["trx-frontend-http<br/>(Web UI :8080)"]
Remote <-->|"mpsc / watch channels"| Rigctl["trx-frontend-rigctl<br/>(rigctl :4532)"]
Remote <-->|"mpsc / watch channels"| JSON["trx-frontend-http-json<br/>(JSON/TCP)"]
end
Listener <-->|"JSON TCP :4530"| Remote
Audio -->|"Opus TCP :4531"| Remote
HTTP & Rigctl & JSON <--> Users["End Users<br/>(Browser / Hamlib / Custom tools)"]
```
The server and client are separate binaries. They communicate over **JSON-over-TCP** (control) and **Opus-encoded TCP** (audio). Both binaries can load shared-library plugins at startup.
docs/Wxsat-Map-Overlay.md
+10 -10
View File
@@ -27,16 +27,16 @@ can be projected as semi-transparent overlays on the same Leaflet map.
### Data flow
```
Pass decoded (APT / LRPT)
↓ finalize_wxsat_pass / finalize_lrpt_pass (trx-server/audio.rs)
↓ SGP4 propagation using satellite TLE + pass timestamps
↓ Compute geo_bounds [[south, west], [north, east]]
↓ Compute ground_track [[lat, lon], ...]
↓ Attach to WxsatImage / LrptImage
↓ Broadcast via DecodedMessage
↓ SSE → browser
↓ wxsat.js: L.imageOverlay() + L.polyline() on aprsMap
```mermaid
graph TD
A["Pass decoded (APT / LRPT)"] --> B["finalize_wxsat_pass / finalize_lrpt_pass<br/>(trx-server/audio.rs)"]
B --> C["SGP4 propagation using satellite TLE + pass timestamps"]
C --> D["Compute geo_bounds<br/>[[south, west], [north, east]]"]
D --> E["Compute ground_track<br/>[[lat, lon], ...]"]
E --> F["Attach to WxsatImage / LrptImage"]
F --> G["Broadcast via DecodedMessage"]
G --> H["SSE → browser"]
H --> I["wxsat.js: L.imageOverlay() + L.polyline() on aprsMap"]
```
### Geo-referencing strategy
src/decoders/trx-wxsat/README.md
+11 -25
View File
@@ -34,17 +34,11 @@ trx-wxsat/src/
### NOAA APT
```
FM-demodulated audio (any sample rate)
│ AptDemod: FFT Hilbert transform, bandpass @ 2400 Hz ±1040 Hz
▼
AM envelope resampled to 4160 Hz
│ SyncTracker: 1040 Hz sync-A marker correlation
▼
Aligned 2080-sample lines → [SyncA 39][SpaceA 47][ImageA 909][TelA 45][SyncB 39][SpaceB 47][ImageB 909][TelB 45]
│ Telemetry extraction, wedge-based radiometric calibration, histogram EQ
▼
PNG image (1818 × N pixels, dual-channel side-by-side)
```mermaid
graph TD
A["FM-demodulated audio<br/>(any sample rate)"] -->|"AptDemod: FFT Hilbert transform,<br/>bandpass @ 2400 Hz ±1040 Hz"| B["AM envelope<br/>resampled to 4160 Hz"]
B -->|"SyncTracker: 1040 Hz<br/>sync-A marker correlation"| C["Aligned 2080-sample lines<br/>[SyncA 39][SpaceA 47][ImageA 909][TelA 45]<br/>[SyncB 39][SpaceB 47][ImageB 909][TelB 45]"]
C -->|"Telemetry extraction,<br/>wedge-based radiometric calibration,<br/>histogram EQ"| D["PNG image<br/>(1818 x N pixels, dual-channel side-by-side)"]
```
**Key DSP details:**
@@ -62,20 +56,12 @@ PNG image (1818 × N pixels, dual-channel side-by-side)
### Meteor-M LRPT
```
Baseband samples (any sample rate)
│ QpskDemod: Costas loop carrier recovery + Gardner TED symbol timing
▼
Soft symbols (±1.0, I/Q interleaved) @ 72 ksym/s
│ CaduFramer: hard-decision, ASM (0x1ACFFC1D) search, frame lock
▼
1024-byte CADUs (CCSDS transfer frames)
│ ChannelAssembler: VCID → APID routing, MCU extraction
▼
Per-APID pixel rows (1568 px wide)
│ RGB composite (APIDs 64/65/66) or grayscale fallback
▼
PNG image (1568 × N pixels)
```mermaid
graph TD
A["Baseband samples<br/>(any sample rate)"] -->|"QpskDemod: Costas loop carrier recovery<br/>+ Gardner TED symbol timing"| B["Soft symbols (±1.0, I/Q interleaved)<br/>@ 72 ksym/s"]
B -->|"CaduFramer: hard-decision,<br/>ASM (0x1ACFFC1D) search, frame lock"| C["1024-byte CADUs<br/>(CCSDS transfer frames)"]
C -->|"ChannelAssembler:<br/>VCID → APID routing, MCU extraction"| D["Per-APID pixel rows<br/>(1568 px wide)"]
D -->|"RGB composite (APIDs 64/65/66)<br/>or grayscale fallback"| E["PNG image<br/>(1568 x N pixels)"]
```
**LRPT channel mapping:**