sdr-recorder/REQUIREMENTS.md

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 audio recording	Must
FR-005	Conversation grouping via hang time	Must
FR-006	Configuration file	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 (3-4 channels) 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 files when activity is detected
• User Story: As the operator, I want recordings saved as audio files named with frequency and timestamp so I can easily find and review them
• Acceptance Criteria:
  • Output format: MP3 (preferred) or WAV
  • Filename format: {frequency}_{timestamp}.mp3
  • 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: Configuration File

• Description: All user-configurable parameters are specified in a 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
  • Format: YAML, libconfig, or similar human-readable format
  • 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: MP3 (or 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 3-4 channels on a Raspberry Pi 400 (quad-core ARM, 4GB RAM) — Priority: Must
• NFR-002: MP3 output preferred (smaller files, acceptable CPU overhead for 3-4 channels); WAV acceptable as fallback — 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 (quad-core ARM Cortex-A72, 4GB RAM)
• OS: Raspberry Pi OS 64-bit (Debian-based), OpenSSH 10.0p2
• SDR dongle: Realtek RTL2838UHIDIR with Rafael Micro R820T tuner (TCXO-equipped, no drift concerns)
• Tuner gain range: 0.0–49.6 dB in 29 steps
• SDR bandwidth: ~2 MHz tuning window (sufficient for 27 MHz CB band)
• SDR libraries: librtlsdr built from source (rtl_test, rtl_fm, rtl_sdr at /usr/local/bin/)
• Docker: Installed on Pi; user m is in the docker group (no sudo required). Preferred deployment method.
• Verified: Hardware and driver stack confirmed working on target Pi (2026-03-18)

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 audio recording	Must	Primary output of the system
FR-005	Conversation grouping (hang time)	Must	Prevents fragmented recordings, much more usable output
FR-006	Configuration file	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	MP3 format (preferred)	Must	Smaller files; WAV acceptable as fallback
NFR-003	Long-running stability	Should	Nice to have but not blocking initial delivery