From 45546eef465b890a4598834ab6485cb1de33de99 Mon Sep 17 00:00:00 2001 From: Michael Smith Date: Tue, 17 Mar 2026 14:18:27 +0000 Subject: [PATCH] Add requirements document for SDR scanner & recorder Captures all functional and non-functional requirements from the requirements interview: simultaneous CB frequency monitoring, NFM demodulation, squelch-based activity detection, automatic WAV recording with conversation grouping, YAML config, and console logging. Co-Authored-By: Claude Opus 4.6 (1M context) --- REQUIREMENTS.md | 248 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 248 insertions(+) create mode 100644 REQUIREMENTS.md diff --git a/REQUIREMENTS.md b/REQUIREMENTS.md new file mode 100644 index 0000000..6412fd6 --- /dev/null +++ b/REQUIREMENTS.md @@ -0,0 +1,248 @@ +# Requirements: SDR Scanner & Recorder + +> Generated by requirements interview on 2026-03-17 +> Status: Draft — pending architect review + +## 1. Project Overview + +### 1.1 Vision + +A headless SDR scanning and recording system that monitors a fixed list of CB radio frequencies, demodulates narrow FM, and automatically records audio when activity is detected. + +### 1.2 Problem Statement + +The user needs an automated way to monitor multiple CB radio channels simultaneously and capture conversations as audio files for later review, without manual intervention. + +### 1.3 Success Criteria + +- The system runs unattended in a terminal session on a Raspberry Pi 400 +- All configured frequencies are monitored simultaneously +- When activity is detected on any channel, audio is automatically recorded to a WAV file +- Recordings are grouped by conversation (using configurable hang time) and named with frequency and timestamp + +### 1.4 Background & Context + +- **Hardware:** Raspberry Pi 400 (64-bit OS, 4GB RAM, quad-core ARM), dedicated to this task +- **SDR dongle:** High-quality RTL-SDR with TCXO (no drift concerns) +- **Band:** CB radio, 27 MHz (26.965–27.405 MHz) — all frequencies fall within ~440 kHz, well within the RTL-SDR's ~2 MHz tuning window +- **Approach:** Research existing software first (SDRAngel, SDRTrunk, GNU Radio, etc.) before considering a custom build. Simplest viable approach is preferred. + +## 2. Stakeholders & Users + +### 2.1 User Personas + +| Persona | Description | +| :------------------- | :--------------------------------------------------------------------------------------------------- | +| Operator (sole user) | Technically proficient. Runs the system from a terminal/screen session. Reviews recordings manually. | + +### 2.2 Stakeholders + +Single user — no additional stakeholders. + +### 2.3 Usage Expectations + +- Single user, local access only +- No remote access or multi-user requirements + +## 3. Functional Requirements + +### 3.1 Feature Summary + +| ID | Feature | Priority | +| :----- | :---------------------------------- | :------- | +| FR-001 | Simultaneous frequency monitoring | Must | +| FR-002 | NFM demodulation | Must | +| FR-003 | Squelch-based activity detection | Must | +| FR-004 | Automatic WAV recording | Must | +| FR-005 | Conversation grouping via hang time | Must | +| FR-006 | YAML configuration | Must | +| FR-007 | Console activity logging | Must | + +### 3.2 Detailed Requirements + +#### FR-001: Simultaneous Frequency Monitoring + +- **Description:** Monitor all configured frequencies in parallel using a single RTL-SDR IQ capture +- **User Story:** As the operator, I want all my frequencies monitored at once so that I don't miss activity on one channel while another is being recorded +- **Acceptance Criteria:** + - All configured frequencies (up to 10) are monitored simultaneously + - Uses a single RTL-SDR device with one tuning window covering the 27 MHz CB band +- **Priority:** Must + +#### FR-002: NFM Demodulation + +- **Description:** Demodulate narrow FM audio from each monitored frequency +- **User Story:** As the operator, I want each channel demodulated so that I can listen to the captured audio as intelligible speech +- **Acceptance Criteria:** + - Each monitored frequency is independently demodulated using narrow FM + - Audio quality is sufficient for understanding CB radio conversations +- **Priority:** Must + +#### FR-003: Squelch-Based Activity Detection + +- **Description:** Detect activity on each channel using a signal-strength-based squelch threshold +- **User Story:** As the operator, I want the system to only record when someone is transmitting so that I don't get hours of static +- **Acceptance Criteria:** + - Configurable squelch threshold per channel (or global default) + - Activity is detected when signal exceeds the squelch threshold + - No recording occurs during silence/noise-only periods +- **Priority:** Must + +#### FR-004: Automatic WAV Recording + +- **Description:** Record demodulated audio to WAV files when activity is detected +- **User Story:** As the operator, I want recordings saved as WAV files named with frequency and timestamp so I can easily find and review them +- **Acceptance Criteria:** + - Output format: WAV (raw PCM, no encoding overhead) + - Filename format: `{frequency}_{timestamp}.wav` + - Files are written to a configurable output directory +- **Priority:** Must + +#### FR-005: Conversation Grouping via Hang Time + +- **Description:** Keep a recording open for a configurable period after the signal drops, to group back-and-forth conversation into a single file +- **User Story:** As the operator, I want a CB conversation captured in one file rather than split into dozens of fragments +- **Acceptance Criteria:** + - Configurable hang time (default: 5 seconds) + - If signal returns within the hang time, the recording continues in the same file + - If silence exceeds the hang time, the file is closed and a new recording starts on next activity +- **Priority:** Must + +#### FR-006: YAML Configuration + +- **Description:** All user-configurable parameters are specified in a YAML config file +- **User Story:** As the operator, I want to edit a simple config file to set my frequencies and squelch levels +- **Acceptance Criteria:** + - Config file includes: frequency list, squelch threshold(s), hang time, output directory + - System reads config at startup +- **Priority:** Must + +#### FR-007: Console Activity Logging + +- **Description:** Log activity events to stdout +- **User Story:** As the operator, I want to see when activity is detected so I can monitor the system in real time if I choose +- **Acceptance Criteria:** + - Logs include: frequency, timestamp, event type (recording started/stopped), output filename + - Output goes to stdout (visible in terminal/screen session) +- **Priority:** Must + +### 3.3 Key User Journeys + +**Primary journey:** + +1. Operator edits YAML config with desired frequencies and squelch settings +2. Operator starts the system in a terminal/screen session +3. System begins monitoring all configured frequencies simultaneously +4. Activity appears on one or more channels — system begins recording and logs the event +5. Activity stops — after hang time expires, recording is saved and logged +6. Operator reviews WAV files at their convenience + +### 3.4 Data Model (Conceptual) + +- **Configuration:** List of frequencies, squelch threshold(s), hang time, output directory +- **Recording:** WAV file with associated metadata (frequency, start time) encoded in filename +- **Log entry:** Timestamp, frequency, event type, filename + +## 4. Non-Functional Requirements + +### 4.1 Performance + +- **NFR-001:** Must handle simultaneous demodulation and recording of up to 10 channels on a Raspberry Pi 400 (quad-core ARM, 4GB RAM) — **Priority: Must** +- **NFR-002:** WAV output (no encoding overhead) to minimize CPU usage — **Priority: Must** + +### 4.2 Availability & Reliability + +- **NFR-003:** System should run stable in a terminal session for extended periods — **Priority: Should** +- Auto-restart and systemd integration are explicitly out of scope for this phase + +### 4.3 Security & Compliance + +- No specific security requirements (local-only, single user) +- CB radio monitoring is receive-only and legal in most jurisdictions + +### 4.4 Scalability + +- Not applicable — fixed hardware, fixed frequency list, single instance + +### 4.5 Data Management + +- Storage management is handled manually by the operator +- No retention policies, backup, or cleanup requirements + +## 5. Constraints + +### 5.1 Technical Constraints + +- **Hardware:** Raspberry Pi 400, RTL-SDR dongle with TCXO +- **OS:** Raspberry Pi OS 64-bit (Debian-based) +- **SDR bandwidth:** ~2 MHz tuning window (sufficient for 27 MHz CB band) + +### 5.2 Business Constraints + +- Single developer/operator +- No budget constraints mentioned + +### 5.3 Timeline + +- No deadline — "when it's ready" +- Research phase should be thorough to find the best-fit approach + +### 5.4 Scope Boundaries (Explicit Exclusions) + +- No web UI or remote access +- No systemd service or auto-restart +- No storage management or cleanup automation +- No digital mode decoding +- No wide FM or any modulation beyond NFM +- No audio streaming +- No multi-device support + +## 6. Assumptions & Dependencies + +### 6.1 Assumptions + +- The RTL-SDR dongle is functional and recognized by the Pi (drivers installed, `rtl_test` works) +- All target frequencies fall within a single RTL-SDR tuning window +- The Pi 400 has sufficient CPU/RAM for parallel demodulation of up to 10 NFM channels + +### 6.2 External Dependencies + +- RTL-SDR USB drivers (`librtlsdr`) +- Existing SDR software ecosystem (SDRAngel, SDRTrunk, GNU Radio, etc.) — to be evaluated in research phase + +## 7. Open Questions + +| # | Question | Context | +| :-- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | Which existing software best fits this use case? | Research needed: SDRAngel, SDRTrunk, rtl_fm, GNU Radio, others. Evaluate for: multi-channel NFM, squelch, WAV recording, Pi compatibility. | +| 2 | If no existing software fits, what's the simplest custom approach? | Options: GNU Radio + Python, custom C/C++ with librtlsdr, Go with RTL-SDR bindings. User prefers Go or C/C++ over Python. | +| 3 | What sample rate is optimal for covering the CB band? | Need to balance bandwidth coverage with Pi CPU load. | +| 4 | What audio sample rate is appropriate for CB voice? | CB audio bandwidth is ~3 kHz; 8 kHz or 16 kHz sample rate likely sufficient. | + +## 8. Glossary + +| Term | Definition | +| :-------- | :------------------------------------------------------------------------------------------------- | +| SDR | Software-Defined Radio — radio receiver implemented in software using a generic RF frontend | +| RTL-SDR | Low-cost SDR receiver based on the RTL2832U chipset | +| TCXO | Temperature-Compensated Crystal Oscillator — provides stable frequency reference, minimizing drift | +| NFM | Narrow FM — frequency modulation with ~5 kHz deviation, used by CB and many two-way radio services | +| IQ | In-phase/Quadrature — raw complex signal data captured by the SDR | +| Squelch | Signal gate that mutes audio when signal strength falls below a threshold | +| Hang time | Duration the squelch remains open after signal drops, to avoid choppy audio during pauses | +| CB | Citizens Band — 27 MHz radio service for short-range personal/business communication (40 channels) | + +## Appendix: Priority Matrix + +| ID | Requirement | Priority | Rationale | +| :------ | :-------------------------------- | :------- | :------------------------------------------------------------- | +| FR-001 | Simultaneous frequency monitoring | Must | Core capability — monitoring one at a time defeats the purpose | +| FR-002 | NFM demodulation | Must | Required to produce listenable audio | +| FR-003 | Squelch-based activity detection | Must | Without this, recordings would be continuous noise | +| FR-004 | Automatic WAV recording | Must | Primary output of the system | +| FR-005 | Conversation grouping (hang time) | Must | Prevents fragmented recordings, much more usable output | +| FR-006 | YAML configuration | Must | Needed for frequency list and tuning parameters | +| FR-007 | Console activity logging | Must | Operator awareness of system activity | +| NFR-001 | Pi 400 performance | Must | Hardware constraint — must run on target platform | +| NFR-002 | WAV format (no encoding) | Must | Minimizes CPU overhead on Pi | +| NFR-003 | Long-running stability | Should | Nice to have but not blocking initial delivery |