m/sdr-recorder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add requirements document for SDR scanner & recorder

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Michael Smith
2026-03-17 14:18:27 +00:00
parent da03466c50
commit 45546eef46
1 changed files with 248 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
REQUIREMENTS.md Normal file
View File

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