| name | simulate-scene |
| description | Use when the user wants a test signal or a simulated RF environment with no hardware — translate intent into a scene and register it as a persistent simulated device. |
Simulate Scene
Create a simulated device whose "on-air" contents you control. This is the no-hardware on-ramp, and a real workflow in its own right: prototype a receiver against known ground truth before going on-air, or reproduce a colleague's scenario without their antenna.
Method
- Translate intent into elements. Each element is
{kind, freq, amplitude, params}:
tone — an unmodulated carrier at freq.
fm_tone — an NBFM voice carrier; params.mod_freq is the modulating audio tone (e.g. 1000 for 1 kHz). Renders only when the capture sample_rate is a multiple of 100000.
noise — a noise floor (freq ignored).
iq_file — replay a recorded capture (usually created via transmit, not by hand).
- Always add a noise floor. Include a
noise element (amplitude ≈ 0.005). A noiseless scene produces analysis artifacts (phantom sidebands) that confuse survey-spectrum.
- Register it.
simulate_scene(device_id, elements). The scene is saved to scenes/<device_id>.yaml and the device reappears in later sessions — it's a shareable, git-friendly fixture.
- Verify the scene is what you intended.
capture the device and run survey-spectrum; confirm the signals land where you placed them.
Judgment
- Keep amplitudes sane: a strong carrier ≈ 1.0, a weaker one ≈ 0.3–0.5, noise ≈ 0.005. Huge dynamic range makes weak signals invisible.
- Place signals comfortably inside the captured band — elements beyond ±45% of the sample rate from the center are skipped at render time.
- Name devices for what they represent (
fm_band, ism_test), since the name becomes the scene filename.