build-receiver - Claude MCP Skill

# Build Receiver

Turn a target signal into a working receiver. The method below is general; FM voice and an unmodulated carrier are shown as two worked examples so the *shape* transfers to modulations the demo doesn't cover.

## General method (any modulation)

1. **Know the target.** Get its center frequency and occupied bandwidth from survey-spectrum / `measure`. Compute the offset from the capture's center: `center_offset = target_freq − capture_center_freq`.
2. **Discover the blocks.** Call `list_blocks`. Compose only from these types; check each block's input/output dtype ('c' complex, 'f' float) so connections match.
3. **Channelize.** Use `freq_xlating_lowpass` to shift the target to baseband and decimate. Choose `decimation` so the post-decimation rate is ~2–3× the signal bandwidth; set `cutoff ≈ signal_bandwidth` and `transition ≈ cutoff/2`.
4. **Demodulate to match the modulation** (see examples below).
5. **Validate.** `validate_pipeline(pipeline)` and fix *every* issue (each names the block and field) before running.
6. **Run.** `run_pipeline(pipeline)`; check `status == "ok"`.
7. **Verify before you claim success** (see Verify). Never report a working receiver without evidence.
8. **Persist.** `save_pipeline(pipeline)` and `export_grc(pipeline)` so the user keeps a reusable receiver they can open in GNU Radio Companion.

## Worked example A — NBFM voice

Channelize so the post-decimation rate equals the FM quad rate (a multiple of the audio rate), then demodulate to a WAV:

- `freq_xlating_lowpass` (decimation chosen so e.g. 2 MHz / 20 = 100 kHz = quad_rate; cutoff ≈ 8 kHz, transition ≈ 4 kHz)
- `nbfm_rx` with `audio_rate=25000`, `quad_rate=100000` (**quad_rate must be an integer multiple of audio_rate**)
- `wav_sink` (`sample_rate=25000`)

Connections: src → chan → demod → audio.

## Worked example B — unmodulated carrier / CW (non-FM)

There is *no* demodulator here — receiving a carrier means channelizing it to baseband and confirming it:

- `freq_xlating_lowpass` (narrow `cutoff`, e.g. a few kHz) → `file_sink` (give the sink a path ending in `.cf32`).
- `run_pipeline`, then bridge the raw output into an analyzable capture: take the sink path from the run's `artifacts[0]` and call `load_capture(path, sample_rate=<post-decimation rate>, center_freq=<target_freq>)` (raw `.cf32` needs the sample rate supplied).
- Then `measure(capture_path, center_freq=<target_freq>)` (or render a `spectrogram`) to confirm the carrier sits where expected with the predicted SNR.

This proves the channelizer/offset logic independently of any demodulator — the same skeleton as example A with the demod stage removed. The run → `load_capture` → analyze bridge is general: that's how you inspect *any* pipeline's file output.

## Other modulations

AM, SSB, and digital (OOK/PPM/FSK) demodulators are **not in the v1.0 vocabulary**. If the target needs one, report the gap and switch to the escape-hatch skill — do not force an FM demodulator onto a non-FM signal.

## Verify (mandatory)

- FM voice: read the recovered WAV and confirm energy in the audio band (e.g. a 1 kHz modulating tone shows up at 1 kHz).
- CW/other: `measure` or `spectrogram` the channelized output and confirm the carrier/structure is where you expect.
- If verification fails → switch to the debug-no-signal skill. Do not retry blindly.