External API v1 — proposed spec (feedback wanted)

[mm5agm]

This proposes a dedicated, stable /api/external/v1/* HTTP surface so other applications can control the radio through YWC directly — without going through rigctld, and without depending on YWC's internal /api/cat/* (which is UI glue and changes shape as the web UI evolves).

It came out of Discussion #78 with Giovanni (iu1teu), who's looking to retire his own Python CAT bridge and drive the radio through YWC instead. I'm posting it as its own thread so anyone building on top of YWC can weigh in before I implement it.

Ground rules (the stability promise)

• Hand-written, documented response objects — not the anonymous shapes /api/cat/* uses, so this won't shift under you when I rework the web UI.
• Additive-only within v1. Anything breaking becomes v2 alongside, never an in-place change.
• Scoped to exactly what's needed for radio control.

Endpoints

GET /api/external/v1/status — one snapshot of everything:

{
  "connected": true,
  "model": "FTDX3000",
  "vfoA": { "frequencyHz": 14074000, "mode": "USB" },
  "vfoB": { "frequencyHz": 14079000, "mode": "USB" },
  "rxVfo": "A",
  "txVfo": "B",
  "split": true,
  "ptt": false,
  "atu": { "enabled": true, "tuning": false },
  "meters": {
    "sMeter": 42,
    "powerWatts": 0,
    "swr": 1.2,
    "alc": 0,
    "compression": 0,
    "temperatureC": 35
  }
}

POST /api/external/v1/frequency → { "vfo": "A", "frequencyHz": 14074000 }
POST /api/external/v1/mode → { "vfo": "A", "mode": "USB" }
POST /api/external/v1/split → { "rxVfo": "A", "txVfo": "B" } (split is derived: on when rxVfo ≠ txVfo — an independent RX/TX model, not a single on/off toggle)
POST /api/external/v1/atu → { "enabled": true } or { "action": "tune" }
POST /api/external/v1/power → { "on": true } (uses YWC's double-PS1;)

Questions (Giovanni especially, but anyone's input is welcome)

1. Does that status shape line up with what your app consumes, or is it missing / carrying fields you don't want?
2. Units: power in watts or percent? And the S-meter as raw 0–255, dBm, or S-units? I'll match whatever the consuming side expects.
3. PTT: do you want a POST /api/external/v1/ptt here, or keep keying through rigctld and use this API only for state/control?
4. SWR: as a ratio (1.2 = 1.2:1) — does that work?

Once the shape settles I'll build it — it shares the RX/TX VFO plumbing with the web-UI split work, so the two land together.

73, Colin

[iu1teu]

Hi Colin,

This looks like a solid shape overall — closely matches what my bridge already needs. Feedback on the four questions, grounded in what my own CAT polling loop actually does today (not guesses):

1. Status shape. Mostly lines up well — vfoA/vfoB frequency+mode, rxVfo/txVfo, split, atu, the meters block, all map cleanly onto what I poll today. One thing worth raising because it bit me building my own bridge: reading VFO B's mode reliably is genuinely awkward on the FTDX3000 when B isn't the currently-active VFO. My bridge doesn't have a direct "give me VFO B's mode regardless of which is active" command — I infer it indirectly (comparing MD0;, the mode of whichever VFO is currently active, against the VFO-A mode embedded in IF;'s response; if they differ, VFO B must be active and MD0 is its mode — but that only works while VFO B actually is the active one). If VFO B is idle in the background, I don't have a reliable read on its mode at all right now. Curious how you're planning to populate vfoB.mode in the idle case — if you've found a real command for it, I'd genuinely like to know, since it'd let me simplify my own polling too.

2. Units — power/S-meter: watts and raw 0–255 respectively, please, matching what the radio actually returns over CAT (PC; → watts directly, SM0; → raw 0–255) — that's exactly what I already parse with zero conversion, so no mismatch risk either side. I'd actually lean against pre-converting the S-meter to dBm or S-units at the API level: the raw→S-unit mapping isn't perfectly linear near S9 (see below), so baking in one conversion assumption removes the option for a consumer to do their own.

SWR, though, I'd ask for the opposite of raw: please expose it as the computed ratio you've proposed (1.2 = 1.2:1), not raw RM6; 0–255. My bridge currently has to do exactly that conversion itself, and it's genuinely non-linear — I reverse-engineered a piecewise calibration curve from the CAT manual: 0→1.0, 48→1.5, 80→2.0, 120→3.0, 160→5.0, 200→10.0, 255→∞ (linear interpolation between points). If you get this from the same manual you'll probably land on the same curve, but happy to hand over my table directly if it saves you re-deriving it — either way, having YWC do this conversion once means I can delete that code from my side.

3. PTT: I don't actually need this one — my setup keys PTT through WSJT-X's own CAT connection to the radio, entirely separate from my bridge, so a POST /ptt here wouldn't replace anything I currently do. That said, I don't run everyone's setup, so I wouldn't take my "don't need it" as a vote to leave it out if another integrator asks for it — just flagging that it's not blocking for me either way.

4. SWR as a ratio: yes, see above — strongly prefer this over raw, precisely because of the non-linear conversion I already have to do myself.

Nice to see this land as its own spec thread — makes sense for other integrators to weigh in before it's built. Happy to keep testing against pre-releases the same way as the ATU/split work.

73, Giovanni

[mm5agm]

Hi Giovanni,

Perfect — grounding it in what your bridge actually parses is exactly the input I wanted. Locking these in:

• Power: watts. S-meter: raw 0–255, no pre-conversion — agreed, and for the same reason you gave (the raw→S-unit curve isn't linear near S9, so I shouldn't bake one interpretation in).
• SWR: I'll expose the computed ratio, YWC-side. Good news — YWC already does this conversion for its own meters, so it's no extra burden; I'll cross-check my curve against your table (thanks for offering it) and flag if they diverge.
• PTT: I'll leave /ptt out of v1 since it's not blocking for you. Easy to add later if another integrator asks.

On reading VFO B's mode when B is idle — you've put your finger on a real limitation, and it turns out YWC hits the same wall: there's no command that gives an idle VFO's mode on these single-receiver radios. What YWC does is take the mode from MD0; (which is always the active VFO's mode) and route it to whichever VFO is currently active, caching the other. So vfoB.mode is a "last known good" — accurate as of the last time B was the active VFO (and persisted across restarts) — not a live read while B is idle. I don't have a magic command for it either; if I ever find one I'll shout, because it'd let both of us stop inferring. Your IF;-byte-20 approach and my cache-on-active approach are really two ways around the same missing command.

I'll build to this shape. Thanks again — this is the kind of feedback that makes it right the first time.

73, Colin