diff --git a/README.md b/README.md index 4a7f9a6..4cfe1da 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,40 @@ -# DJ7NTs QO100 Webconsole +# DJ7NTs QO-100 Web SDR Transceiver Console -> **Disclaimer:** This is a proof-of-concept project. Use at your own risk — no guarantees or warranties of any kind. The source code is not fully open-source at this time. +> **Disclaimer:** This is a proof-of-concept project. Use at your own risk — no guarantees or warranties of any kind. The source code is not fully open-source at this time. FT8/FT4 digital modes are **experimental**. + +## Features + +- **Voice SSB** — USB with full DSP chain (NR, AGC, 5-band EQ, notch filter) +- **CW** *(experimental)*— TX with 10 ms envelope ramp +- **FT8 / FT4** *(experimental)* — server-side encode/decode, WSJT-X-style autosequencer, dual-mode decode +- **Multi-user** — admin, user, and guest roles; concurrent users with independent VFO +- **Wavelog integration** — automatic logging +- **Web-based** — no desktop app needed; all DSP runs server-side, browser handles audio I/O + +## Supported Operating Modes + +| Mode | Description | +|------|-------------| +| **QO-100** | Satellite operation with LNB conversion, beacon tracking (AFC), transponder frequency offset, and bandpass clamping | +| **Simple** | General-purpose SDR — direct frequency tuning, no LNB, no beacon tracking | + +## Supported Hardware + +| Device | Profile | Notes | +|--------|---------|-------| +| **Analog Devices PlutoSDR** (rev B/C, 2-channel) | `pluto` | GPIO + ADM1177 power monitor, native 576 kHz sample rate. GPS-DO recommended for TX stability; XIT compensates drift. Global TX offset configurable. | +| **AD9363-based clone** (e.g. LibreSDR) | `ad9363-clone` | No GPIO/ADM1177; requires linear-interpolation resampling to 576 kHz; auto-probes multiple sample rates. | ## Prerequisites - Docker (any recent version) and Docker Compose -- **Analog Devices PlutoSDR** (original rev.B/C - 2(!) Channel-Version (one TX, one RX)) or **AD9363-based clone** (e.g. LibreSDR) — device type is selected during setup -- **USB-to-Ethernet adapter** (100 Mbit) connected to the Pluto's USB OTG port — Gigabit adapters are not supported and may cause issues +- **Analog Devices PlutoSDR** (original rev.B/C — 2-channel version, one TX, one RX) or **AD9363-based clone** (e.g. LibreSDR) — selected during setup +- **USB-to-Ethernet adapter** (100 Mbit) connected to the Pluto's USB OTG port, if using a Board without Ethernet — Gigabit adapters are not supported and may cause issues - LNB connected to the PlutoSDR -- Original(!) 2channel-Pluto should be GPS-DO stabilized. Currently there's only a XIT to compensate it. As an additional Feature there's a global TX-Offset-Setting. +- Pluto should be GPS-DO stabilized. Currently there's only XIT to compensate drift. A global TX offset is available as an additional setting. - The Pluto and the host running Docker must be on the same network -The prebuilt image is available for **x86_64** (PCs/servers) and **arm64** (Raspberry Pi 4+, Rock 5 ITX). Docker automatically pulls the correct variant for your hardware. +The prebuilt image is available for **x86_64** (PCs/servers) and **arm64** (Raspberry Pi 4+, Rock 5 ITX). Docker automatically pulls the correct variant. ## Quick Start with Docker Compose @@ -50,6 +73,69 @@ Start: docker compose up -d ``` +## Sidecar Architecture + +The **sidecar** is a Go binary that bridges the server and the Pluto SDR hardware via [libiio](https://github.com/analogdevicesinc/libiio). It handles all I/Q streaming, TX/RX control, and hardware-specific configuration. + +### Deployment Modes + +| Mode | Description | Usage | +|------|-------------|-------| +| **Local** (default) | Sidecar runs on the host machine, communicates with Pluto over the network | `./pluto-sidecar --socket --profile pluto` | +| **On-Pluto** | Cross-compiled ARM binary runs directly on the Pluto device. Lower latency, uses local IIO context. Auto-reconnects on errors. | `./pluto-sidecar-arm --local --profile pluto --listen :4242` | + +The Docker image includes the sidecar and runs it in **local mode** automatically. + +### On-Pluto Deployment + +For lowest latency, the sidecar can run directly on the Pluto's ARM Cortex-A9. The ARM binary (`pluto-sidecar-arm`) is cross-compiled with a Docker buildx step and deployed to the Pluto via SSH/SCP. In this mode, the sidecar opens a local IIO context (no network I/O for IQ data) and listens on a TCP port for the server to connect. + +### Binary Protocol + +Control and data flow over separate channels using a binary frame protocol: `[type:u8][length:u32le][payload]`. The on-Pluto mode additionally supports async transport for low-latency TX. + +## FT8 / FT4 Digital Modes *(Experimental)* + +Server-side weak-signal digital modes using the `@e04/ft8ts` library (pure TypeScript port of WSJT-X). Both FT8 (15 s slots) and FT4 (7.5 s slots) are decoded simultaneously under a single "FT8/FT4" RX mode. + +### Capabilities + +- **Dual decode** — FT4 decoded every 7.5 s, FT8 every 15 s; messages tagged with mode +- **Autosequencer** — WSJT-X-style automatic QSO flow (CQ → reply → signal report → 73) +- **Auto mode** — when replying, automatically matches the decoded station's mode (FT8 or FT4) +- **Slot-aligned TX** — transmissions start at slot boundaries; early-TX window (≤2 s FT8 / ≤1.2 s FT4) allows quick autosequence replies +- **Dedicated UI** — waterfall display (2.93 Hz/bin), decode list with color coding, TX panel with message templates + +### Signal Path + +**RX:** SSB demod (3.2 kHz bandwidth) → HPF → LPF → decimate to 12 kHz → ring buffer → slot-boundary decode jobs (separate workers per mode, depth-3 OSD). + +**TX:** `@e04/ft8ts` encode → 12 kHz audio → interpolate to 48 kHz → slot-scheduled → TX worker. + +AGC, NR, EQ, and notch are bypassed for FTx — constant-amplitude GFSK signals must not be squashed. + +## DSP Pipeline + +All signal processing runs server-side (TypeScript/Bun). The browser only handles audio I/O and UI. + +### RX + +``` +576 kHz I/Q + → frequency shift → ×12 decimation → Hilbert transform → sideband select + → DC blocker → notch filter → Ephraim-Malah noise reduction + → AGC → 5-band EQ → low-pass filter → ×6 decimation → 8 kHz PCM → browser +``` + +### TX + +``` +48 kHz mic (browser) + → jitter buffer → TX worker thread + → mic gain → pre-filter → EQ → pre-emphasis → compressor → limiter → post-filter + → SSB modulator → ×12 interpolation → 576 kHz I/Q → sidecar → Pluto +``` + ## First-Time Setup 1. Open `http://:3004` in a browser @@ -92,7 +178,7 @@ Changes trigger a reconnect to the SDR bridge. ### TX Lock -A global transmit lock that, when enabled, blocks all users from transmitting (PTT, two-tone, etc.) and stops any active transmissions. +A global transmit lock that, when enabled, blocks all users from transmitting (PTT, two-tone, FTx, etc.) and stops any active transmissions. ### Activity Log