signal-generator
Skill235 starsChanged 3 months agoMITView on GitHub
Drive the Embedded AI Harness testbench's RF signal generator over `/api/siggen/*` — continuous carrier, Morse/CW beacon, retune, PE4302 attenuation, and frequency listing. Use this skill whenever the user wants to emit, key, retune, or attenuate an RF signal from the testbench, even if they only say "CW beacon", "carrier", "Morse", "Si5351", "GPCLK", "PE4302 attenuator", "DF test", "direction finder", or "80m beacon" — those are all this one API. Always check `/api/siggen/status` first to see which backend (Si5351 vs GPCLK fallback) and attenuator are physically present before choosing a backend.
In this repository17 other files it gives its agents.
- buildSkill
- commissionSkill
- defineSkill
- esp-idf-handlingSkill
- esp-pio-handlingSkill
- grill-meSkill
- harnessSkill
- sdr-receiverSkill
- setup-actionSkill
- testbench-bleSkill
- testbench-debugSkill
- testbench-installSkill
- testbench-integrationSkill
- testbench-loggingSkill
- testbench-mqttSkill
- testbench-test-handlingSkill
- testbench-wifiSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Before starting a carrier or recommending a backend, GET /api/siggen/status.
- Very specific: line 28
If hardware.si5351 is true, you can hit any frequency exactly (333 kHz – 112.5 MHz, fractional synthesis).
- Very specific: line 29
If hardware.si5351 is false, you fall back to GPCLK, which only produces PLLD/N integer dividers — ~25–30 kHz frequency steps in the 80m …
- Very specific: line 30
If hardware.pe4302 is false, calls to /api/siggen/atten will 4xx.
- Very specific: line 31
If active is already true, starting a new carrier replaces the old one.
- Distinctive: line 39
Every endpoint, with its request and response shape: FSD Appendix D.11.
- Distinctive: line 82
No body. Stops the carrier and disables the output.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Signal Generator (/api/siggen/*)
The testbench Pi has one signal-generator service. Two RF sources sit behind it (Si5351 on I²C, BCM2835 GPCLK on GPIO 5/6) and an optional PE4302 step attenuator can sit in the RF path. The endpoint is the same regardless of which backend is active — /api/siggen/* is the only entry point you should reach for.
This skill replaces the legacy cw-beacon skill, which only knew about GPCLK and led to wrong frequencies on testbenches that have an Si5351.
Always check status first
Before starting a carrier or recommending a backend, GET /api/siggen/status. The response tells you which hardware is detected:
{
"ok": true, "active": false, "backend": null,
"freq_hz": 0.0, "channel": null, "pin": null,
"atten_db": null, "morse": null,
"hardware": {"si5351": true, "gpclk": true, "pe4302": true}
}Why this matters:
- If
hardware.si5351istrue, you can hit any frequency exactly (333 kHz – 112.5 MHz, fractional synthesis). Don't reach for GPCLK. - If
hardware.si5351isfalse, you fall back to GPCLK, which only produces PLLD/N integer dividers — ~25–30 kHz frequency steps in the 80m band. Tell the user the actualfreq_hzreturned, not the requested one. - If
hardware.pe4302isfalse, calls to/api/siggen/attenwill 4xx. Don't promise attenuation control. - If
activeis alreadytrue, starting a new carrier replaces the old one. If the user just wants to retune, use/api/siggen/freqinstead so the Morse keyer (if any) keeps running.
Skipping the status check is the most common failure mode of this skill — pick the wrong backend and the carrier ends up tens of kHz off frequency, or you offer attenuation that doesn't exist.
API summary
Every endpoint, with its request and response shape: FSD Appendix D.11.
freq retunes an active carrier without restarting the Morse keyer — use it
rather than stop/start when a test must not lose keying state.
POST /api/siggen/start
{
"freq_hz": 3500000,
"backend": "auto",
"channel": 0,
"pin": 5,
"atten_db": 0,
"morse": {"message": "VVV DE TEST", "wpm": 15, "repeat": true}
}| Field | Type | Default | Notes |
freq_hz | number | required | Si5351 hits exactly; GPCLK snaps to nearest integer divider — read it back from the response |
backend | string | "auto" | auto / si5351 / gpclk. Prefer auto unless you have a reason. |
channel | int | 0 | Si5351 output (0/1/2). Ignored by GPCLK. |
pin | int | 5 | GPCLK pin (5 or 6). Ignored by Si5351. |
atten_db | float | — | Initial PE4302 setting (0–31.5). Optional. |
morse | object | — | Omit → continuous carrier. Include → keyed beacon. |
morse shape: {"message": str, "wpm": int|float = 15, "repeat": bool = true}. WPM is PARIS-standard, 1–60.
The response echoes the actual state — always trust freq_hz from the response, not the request. Example:
{
"ok": true, "active": true, "backend": "si5351",
"freq_hz": 3500000.0000000005, "channel": 0, "pin": null,
"atten_db": 0.0,
"morse": {"message": "VVV DE TEST", "wpm": 15, "repeat": true}
}POST /api/siggen/stop
No body. Stops the carrier and disables the output. Idempotent.
POST /api/siggen/freq
{"freq_hz": 7100000, "channel": 0}Retunes the active carrier without tearing down the Morse keyer. Use this when sweeping or stepping through frequencies during a beacon transmission.
POST /api/siggen/atten
{"db": 12.5}Returns 4xx if PE4302 is not present. Range 0–31.5 dB in 0.5 dB steps. Pin sharing note: PE4302's LE line is GPIO 6, which is also GPCLK2 — when GPCLK is active on pin 6, attenuation control is unavailable. Si5351 + PE4302 and GPCLK on pin 5 + PE4302 are both safe.
GET /api/siggen/frequencies?low=&high=&backend=
Defaults: low=3_500_000, high=4_000_000, backend=auto. GPCLK returns discrete {divider, freq_hz} entries; Si5351 returns a single entry reporting the range as continuously tunable.
Driver methods (pytest/testbench_driver.py)
The Python driver mirrors the API one-for-one. Prefer these over raw curl when writing test scripts:
from testbench_driver import TestbenchDriver
wt = TestbenchDriver("$TESTBENCH_URL")
status = wt.siggen_status() # always first
print(status["hardware"])
wt.siggen_start(freq_hz=3_500_000) # continuous, auto backend
wt.siggen_freq(freq_hz=7_100_000) # retune in place
wt.siggen_atten(db=12.0) # PE4302
wt.siggen_start(freq_hz=3_571_000, # keyed beacon
morse={"message": "VVV DE TEST",
"wpm": 15, "repeat": True})
wt.siggen_stop()Recipes
Carrier at a specific frequency
status = wt.siggen_status()
backend = "si5351" if status["hardware"]["si5351"] else "gpclk"
result = wt.siggen_start(freq_hz=3_500_000, backend=backend)
# On GPCLK, result["freq_hz"] may differ from 3_500_000 by ~25 kHz —
# tell the user the actual frequency.
print(f"Actual: {result['freq_hz']/1e6:.6f} MHz")Morse beacon for a DF test (80m band)
wt.siggen_start(
freq_hz=3_571_000,
morse={"message": "VVV VVV DE TEST", "wpm": 12, "repeat": True})
# ... run direction-finder measurements ...
wt.siggen_stop()A 1–2 m wire on the Si5351 CLK0 output (or GPIO 5/6 for GPCLK) gives a few metres of range. The square wave has strong odd harmonics (3×, 5×, 7×) which are also usable for DF testing.
Calibrated level sweep (requires PE4302)
status = wt.siggen_status()
if not status["hardware"]["pe4302"]:
raise RuntimeError("PE4302 not present — cannot run level sweep")
wt.siggen_start(freq_hz=14_100_000)
for db in [0, 6, 12, 18, 24, 30]:
wt.siggen_atten(db=db)
# measure DUT response here — don't sleep blindly, poll the DUT
wt.siggen_stop()Don't sleep blindly between siggen calls
The siggen service responds when the change is in effect. If a downstream measurement needs settling time (PLL relock on Si5351, attenuator strobe), poll the DUT for the expected reading rather than time.sleep(...) — blind delays are a testbench-wide anti-pattern.
Behavior to be aware of
- Single instance. Starting a new carrier replaces the previous one. There is no multi-channel scheduler; if you need a second tone, you've outgrown this skill.
- Si5351 is preferred when present.
backend: "auto"picks Si5351 if the chip ACKs on I²C, GPCLK otherwise. Don't override unless you specifically want the GPCLK substrate (e.g., to verify both backends work). - Pin sharing. GPCLK pins 5/6 are shared with the gpiod GPIO control (FR-018). Don't drive
/api/gpio/seton pin 5 or 6 while a GPCLK carrier is active there. - Root-only. The portal runs as root via systemd because
/dev/memaccess is needed for GPCLK and PE4302. The skill assumes that's already the case (it is, for the reference build). - Config file.
/etc/rfc2217/signalgen.json(installed frompi/config/signalgen.json) holds I²C bus/address, GPCLK default pin, and PE4302 pin assignments. Defaults are sensible — don't recommend changing them unless the user has an unusual wiring.
Reference
- Functional spec:
docs/Harness-FSD.md§FR-027 (Signal Generator). - Backend logic:
pi/signal_generator.py(orchestrator),pi/si5351.py,pi/gpclk.py,pi/pe4302.py,pi/morse.py. - HTTP handlers:
pi/portal.py(_handle_siggen_*). - Driver:
pytest/testbench_driver.py(siggen_*methods).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

