MRRC Modern / mrrc_modern SDD — Software Design Description

Web Remote Control for supported radios (Yaesu FT-710, Icom IC-7300 / IC-7300MK2)
IBM Team Solution Design (TeamSD) v2.3.2 aligned documentation set

Purpose

This SDD is the canonical design record for the mrrc_modern codebase — a Python FastAPI server that bridges a browser to one or more supported HF/50MHz transceivers via pluggable radio backends. It captures requirements, architecture, design decisions, component boundaries, operational model, capability inventory, known gaps, and evolution history.

Runtime facts are derived from server.py, backends/*, audio_handler.py, radio_state.py, poll_scheduler.py, scope_handler.py, config.py, opus_rx.py, static/index.html, static/ft710_main.js, static/ft710_ui.js, and static/modules/*.

Document Index

# Chapter ART Code File
1 Executive Summary - 01-executive-summary.md
2 Business Direction BUS 411 02-business-direction.md
3 Project Definition ENG 343 03-project-definition.md
4 System Context APP 011 04-system-context.md
5 Non-Functional Requirements ART 0507 05-non-functional-requirements.md
6 Use Case Model ART 0508 06-use-case-model.md
7 Subject Area Model APP 408 07-subject-area-model.md
8 Architecture Decisions ART 0513 08-architecture-decisions.md
9 Architecture Overview ART 0512 09-architecture-overview.md
10 Service Model ART 0582 10-service-model.md
11 Component Model ART 0515 11-component-model.md
12 Operational Model ART 0522 12-operational-model.md
13 Feasibility Assessment ART 0530 13-feasibility-assessment.md
14 Version History - 14-version-history.md
15 PTT Safety Architecture ART 0535 15-ptt-safety-architecture.md
Record Repo Authority
MRRC Cloud Hub SDD V0.1 mrrc_hub 公网远程接入：实例出站隧道、Access/Tunnel Gateway、Registry、Ticket/Lease、设备证书、Portal、OTA 灰度、审计
Fleet Hub 设计评审（2026-09-30） mrrc_hub 对本仓远程接入现有能力的代码取证评审（含本仓侧需改动的 C1–C6）
docs/legacy/sdd/original-sdd/ mrrc 旧架构（前身项目）设计记录

边界：电台控制与媒体（CAT/CI-V、Opus 音频、频谱/瀑布、PTT 多层安全释放、5 个 WS 端点） 的权威是本 SDD；接入与租约（隧道、子域路由、凭证、Operator 租约、Portal）的权威是 mrrc_hub/SDD/。两者交叉引用，不互相复制。注意 mrrc_hub 的 ID 带 -H 中缀 （AD-H06 / NFR-H006 / R-H1），以免与本章集的裸 ID 撞号。

Quick Facts

Attribute Value
Document ID SDD-MRRC-MODERN-2026-001
SDD Version V3.03
Baseline Date 2026-10-17
Status v1.28.1（2026-10-17）：hub 再也不会钉住一把实例已经换掉的证书（ssl_bootstrap.sign_for() 幂等，已坏实例点一次「连接」自愈）；FT8 深路径不再每个时隙杀掉服务器的 DSP worker（FFTW 线程初始化改为返回状态码，worker 自己的 stdio 落到 logs/ft8-worker.log，诊断包收集）。上一版 v1.28.0（2026-10-16）：电台电源回到 ☰ 菜单且两种意图分开、出站 HTTPS 只信随包的根证书、FT8 级联的深路径第一次真正跑起来，外加三个只在产物里现形的缺陷。四份产物（同一修订 66b6930）：macOS DMG 85,064,796 bytes 1c9ba24e…；Windows Setup 79,386,940 bytes cfbeacc7…（VM certutil == Mac shasum）；W103D 1,170,343,847 bytes 749e442a…；rpi64 530,820,848 bytes a00ab228…。unittest 2327 项（macOS，1 skip）；Windows 门禁 2324 项 OK；release_check.py 离线 32 ok / 0 failing；两条镜像线各跑四步产物验证（代码身份逐字节一致 / 装机内容 / D-11 双指向 / chroot 内载入 libwsjt_core.so 并核对 abi=2 与 decode_paths=0x7）。
Project MRRC Modern / mrrc_modern
Primary Radios Yaesu FT-710 and Icom IC-7300 / IC-7300MK2 (verified); Icom IC-705 / IC-7610 / IC-7760 and Yaesu FTDX10 / FTDX101D / FTDX101MP / FTX-1F / FT-891 (profiles without hardware verification, TX gated, no scope stream for the Yaesu family) — all selectable via backend
Backend Selection MRRC_RADIO_MODEL=ft710\|ic7300\|ic7300mk2\|ic705\|ic7610\|ic7760\|ftdx10\|ftdx101d\|ftdx101mp\|ftx1\|ft891 (default ft710); MRRC_ALLOW_UNVERIFIED_TX=1 unlocks transmit on the eight unverified models
Runtime Python 3.12+, FastAPI, Uvicorn, NumPy, PyAudio
Frontend HTML5, CSS3, vanilla JavaScript, Web Audio API (no client-side MP3 encoder; CQ playback is server-side, AD-020)
Transport HTTP/WS for browser; Serial CAT (Yaesu) or USB CI-V (Icom) for radio; FT4222 SPI for FT-710 scope; recording as server-side 16 kHz MP3 (AD-017); CI-V 0x27 spectrum for the Icom family (475 bins on IC-7300/IC-7300MK2/IC-705, 689 bins on IC-7610/IC-7760)
Default Entry https://localhost:8888 (TLS only; self-signed until a certificate is enrolled)

System at a Glance

Browser (iPhone / Desktop / Tablet)
  | HTTP + WebSocket: /WSradio /WSaudioRX /WSaudioTX /WSspectrum (+optional /WSatr1000)
  v
FastAPI/Uvicorn MRRC Server (server.py)
  | Pluggable backend selected by MRRC_RADIO_MODEL
  |   ft710: Serial CAT (USB Enhanced COM Port, 38400 baud) → Yaesu FT-710
  |          FT4222 SPI (scope_pipe subprocess) → real spectrum data
  |   ic7300/ic7300mk2: USB CI-V serial (115200 8N1, addr 0x94/0xB6) → Icom IC-7300/MK2
  |                     CI-V 0x27 spectrum on the same port (display+data enabled; 44-segment newest-data queue)
  | PyAudio (USB Audio device) → RX/TX audio capture/playback
  | Opus codec (libopus) → compressed audio transport
  v
Yaesu FT-710 or Icom IC-7300 / IC-7300MK2 Radio

Capability Summary

Area Status Notes
Mobile UI Implemented static/index.html, ft710.css, ft710_main.js, ft710_ui.js
Radio control Implemented Backend-specific command set: frequency, mode, filter, PTT, gains, etc.
Spectrum waterfall Implemented FT-710: FT4222 SPI real + S-meter fallback; IC-7300: CI-V 0x27 real + S-meter fallback
RX audio Implemented PyAudio capture → Opus/PCM → /WSaudioRX → browser playback (per-backend sample rate)
TX audio Implemented Browser mic → /WSaudioTX → Opus decode → PyAudio → radio (per-backend sample rate)
S-meter + Multi-meter Implemented Backend-specific meter polling (e.g., FT-710 RM3-RM8)
Radio telemetry (RI) Implemented Hi-SWR, recorder, RX/TX, tuner, scan, squelch-open status from RI0;
Meter display + AMC Implemented MS/AO commands exposed in state and control path
Memory channels Implemented /api/mem_channels GET/POST with JSON persistence
Session authentication Implemented Shared-password login; _auth_tokens + mrrc_auth cookie, persisted in data/auth-tokens.json (0600, 30-day) so a restart keeps sessions; all WS gated. Token transport is header → cookie → deprecated ?token= (AD-024); no frontend builds a token URL
PTT safety Implemented Touch-and-hold, PTT watchdog, dead-man switch, unload beacon, TX-phase liveness gate (opt-in via MRRC_REMOTE_SESSION_TX_HEARTBEAT_S; catches connections that die without a TCP close — §15.6)
Remote-session telemetry Implemented session_metrics.py + GET /api/session_metrics: listener/operator concurrency (sessions + sockets), lifetime/window peaks, spectrum+audio_rx uplink bytes — counts only, no identifiers (AD-023)
Scope visualization Implemented 850-point FFT waterfall, frequency scale, S-meter bar