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