Scan a frequency range with an SDR (RTL-SDR / Airspy / HackRF), identify P25 control channels, and log per-system metadata. Optionally cross-reference findings against RadioReference and auto-tune SDR gain via BER feedback.

For each control channel found, records:

• Identity: WACN, System ID, NAC, RFSS ID, Site ID, LRA (Location Registration Area)
• Channel: control channel frequency, full IDEN_UP band plan (FDMA + TDMA, with VHF/UHF receiver bandwidth). A channel is only flagged TDMA when it carries ≥2 slots/carrier, so an all-FDMA band plan advertised via IDEN_UP_TDMA isn't mislabeled.
• Topology: neighbor sites with frequencies (resolved through the band plan), plus per-neighbor status flags (conventional channel, site in failure, stale/last-known, failsoft). Status broadcasts are decoded from both single-block TSBKs and FDMA multi-block trunking (MBT) PDUs, so neighbors are recovered on VHF/UHF systems that advertise them as MBT.
• Secondary CCs: any alternate control channels advertised via SCCB (TSBK opcode 0x39). Captured opportunistically — most sites never transmit SCCB, so this is usually empty. When present, it lists the site's currently advertised secondary CC(s); it is not a rotation schedule.
• Site status: failsoft flag (no active RFSS network connection), control-channel encryption flag (P_PARM_BCST present, with algid), advertised system services (SYS_SRV_BCST), and the system's signed UTC offset (TIME_DATE_ANN).
• Signal quality: RSSI (mean + peak, dBFS), BER, decode rate
• RR enrichment (with --rr): system name, site description, frequency offset vs database, neighbor diff

Outputs three files per scan: NDJSON survey, plain-text human-readable report, and a Markdown submission report listing data not yet in RadioReference.

The live console table updates per candidate as Phase 2 decodes; the RR Match column shows the matched RadioReference system + site (with frequency offset) or flags new sites / NAC mismatches as it goes.

# Scan 800 MHz P25 with an Airspy
./p25-survey --start 851 --stop 869 --sdr airspy --gain 14 \
    --output /tmp/survey-800.json

# Scan 700 MHz public-safety downlink with RR enrichment
./p25-survey --start 769 --stop 775 --sdr airspy --gain 14 \
    --rr --hide-no-cc --output /tmp/survey-700.json

# Find the best gain for your SDR/location/band
./p25-survey --start 769 --stop 775 --sdr airspy --gain 14 \
    --rr --auto-gain --output /tmp/survey-700.json

Single-file executable via shiv:

make dev-deps     # one-time: install shiv + pytest + numpy/scipy for testing
make              # produces ./p25-survey (~85 KB)
make test         # 135 unit tests, no SDR or GNU Radio needed
./p25-survey --help

The executable bundles the package only — numpy, scipy, rich, GNU Radio, and gr-op25_repeater come from the host's Python (this avoids ABI conflicts with GNU Radio's compiled C extensions).

On the host running the survey:

• Python 3.10+
• GNU Radio 3.10+
• gr-osmosdr with the driver matching your SDR (RTL-SDR / Airspy / HackRF)
• gr-op25_repeater from boatbod/op25 dev branch (or master once dev is merged forward). The two patches this tool previously required — the audio-destructor guard and FEC stats — are now upstream, so a stock build works.

Runtime stack (GNU Radio + osmosdr + SDR drivers):

sudo apt-get update
sudo apt-get install -y \
    gnuradio gnuradio-dev \
    gr-osmosdr libosmosdr-dev \
    librtlsdr-dev libairspy-dev libhackrf-dev \
    python3-pip python3-pybind11

Then build and install op25:

sudo apt-get install -y libcppunit-dev cmake build-essential pkg-config \
    libsndfile1-dev libspdlog-dev
git clone https://github.com/boatbod/op25.git
cd op25 && git checkout dev
mkdir build && cd build && cmake .. && make -j$(nproc) && \
    sudo make install && sudo ldconfig

Pure unit tests (make test) don't need any of the above.

Three phases per scan:

1. Energy scan — sweep the SDR's center frequency in chunks of 0.8 × sample_rate, FFT each capture, find spectral peaks above noise_floor + threshold_db. Snap to the band's tuning grid. Output: a list of candidate frequencies.

2. P25 decode — for each candidate, run op25's P25 demodulator + frame assembler with adaptive dwell. Bail at --confirm-timeout (2 s default) if no P25 broadcasts arrive. Otherwise dwell up to --max-dwell (12 s) while collecting NET_STS_BCST, RFSS_STS_BCST, IDEN_UP*, ADJ_STS_BCST, SCCB (secondary CC), and the additional TIA-102.AABC-B broadcasts (SYS_SRV_BCST, TIME_DATE_ANN, P_PARM_BCST); resolve neighbor and secondary-CC frequencies through the captured band plan. RFSS/NET/ADJ_STS and P_PARM are decoded from FDMA MBT PDUs as well as single-block TSBKs.

3. Optional gain sweep (--auto-gain) — sweep 5 gain values × 4 s dwell on each confirmed CC, measure BER per gain, recommend the gain that minimizes block error rate. Per-band median across CCs becomes the suggested --gain for re-running the scan.

For --output /tmp/survey.json, you get three files:

NDJSON survey schema is documented in docs/schema.md.

--threshold N is the dB margin above the median noise floor that an FFT bin must clear to be considered a candidate. The trade-off:

Phase 2 has its own filter (--confirm-timeout abandons a candidate that produces no P25 broadcasts), so a low threshold mostly costs scan time, not final-report quality. Non-P25 noise gets filtered at the decode step regardless.

Auto-selected from the start frequency. Override with --step <kHz>, or pass a comma-separated list of grids (e.g. --step 6.25,7.5,12.5) to cover a mixed-raster band in one pass.

# Texas 800 MHz statewide PS (TXWARN, regional systems, etc.)
./p25-survey --start 851 --stop 869 --sdr airspy --gain 14 \
    --threshold 14 --rr --hide-no-cc --output /tmp/survey-800.json

# 700 MHz PS narrowband downlink (DART, NCTCOG, etc. for DFW area)
./p25-survey --start 769 --stop 775 --sdr airspy --gain 14 \
    --threshold 14 --rr --hide-no-cc --output /tmp/survey-700.json

# VHF land mobile — be generous with threshold; lots of non-P25 noise
./p25-survey --start 150 --stop 174 --sdr airspy --gain 14 \
    --threshold 8 --rr --hide-no-cc --output /tmp/survey-vhf.json

# UHF land mobile (federal, state, narrowbanded business)
./p25-survey --start 380 --stop 512 --sdr airspy --gain 14 \
    --threshold 12 --rr --hide-no-cc --output /tmp/survey-uhf.json

# Calibrate gain for an unfamiliar SDR/location:
./p25-survey --start 851 --stop 869 --sdr airspy --gain 14 \
    --rr --auto-gain --output /tmp/cal.json
# (At the end, accept the rescan prompt to validate the recommendation.)

Ctrl-C exits gracefully. Records decoded up to that point are already on disk (per-record fsync). Resume with --resume:

# First attempt got Ctrl-C'd partway through:
./p25-survey --start 851 --stop 869 --sdr airspy --rr \
    --output /tmp/survey-800.json
# ... ^C ...
# Pick up where it left off:
./p25-survey --start 851 --stop 869 --sdr airspy --rr \
    --resume --output /tmp/survey-800.json

• DECISIONS.md — every architectural choice with rationale.
• PLAN.md — module layout, algorithms, milestones.
• docs/schema.md — NDJSON survey record schema.
• docs/airspy-gain-tables.md — Airspy linearity/sensitivity preset → LNA/MIX/IF lookup tables, snapshot from libairspy.

GPL-3.0-or-later. Required because gr-op25_repeater is GPLv3.