| name | survey-spectrum |
| description | Use when the user wants to know what signals are present — characterize a capture or a simulated device's spectrum (PSD, signal detection, spectrogram) and summarize what's on the air. |
Survey Spectrum
Characterize what's present in a capture, then summarize it for the user. This is the first step of almost every RF task ("what's here?").
Method
- Get a capture. From a simulated device:
capture(device_id, center_freq, sample_rate, duration). From a file the user brings: load_capture(path). Use the returned path for everything below.
- Read the numbers.
psd(capture_path) → noise floor + strongest peaks. find_signals(capture_path) → candidate signals (center_freq, bandwidth, snr_db).
- Always look, don't just count. Render
spectrogram(capture_path) and read the image. find_signals is a first pass over a 1-D PSD; the spectrogram shows time/frequency structure (bursts, drift, multiple carriers) that the list can miss. If you see on/off activity, run detect_bursts(capture_path) for structured burst timing (start, duration, power).
- Confirm wideband signals with
measure. A wide signal (e.g. an FM carrier) with a low noise floor can fragment into several find_signals detections. For any wide or clustered group, call measure(capture_path, center_freq=...) to get the true 99% occupied bandwidth, and trust the spectrogram over the raw detection count.
- Summarize. Give the user a short table: frequency, bandwidth, SNR, and a guess at type (narrowband tone vs. wideband FM-like vs. bursty), plus the spectrogram path.
Judgment
- Seed a noise floor when simulating. A noiseless tone has phantom sidebands that register as spurious detections. When you build a scene to survey (see simulate-scene), always include a small
noise element (amplitude ≈ 0.005).
- SNR gate. Treat a
measure result as a real signal only above ~8 dB SNR; below that you're likely measuring noise.
- Bandwidth is threshold-crossing extent, not −3 dB or OBW — use
measure when you need a real bandwidth number.
