ka9q-python 3.22.0__tar.gz → 3.26.0__tar.gz

{ka9q_python-3.22.0 → ka9q_python-3.26.0}/CHANGELOG.md

@@ -1,5 +1,133 @@
 # Changelog
 
+## 3.25.2 (2026-08-22)
+
+### Fixed
+
+- **`poll_channel()` can now see a channel radiod holds at 0 Hz** (#6).
+  radiod answers a poll for a channel it is still reaping after
+  `remove_channel()` — or one parked at 0 Hz, or one a dynamic-create build
+  minted for the poll itself — with the same `frequency = 0` reply it gives
+  for an unknown SSRC. `poll_channel()` discarded those as "no such
+  channel", so a purging SSRC was indistinguishable from a free one and any
+  "is this SSRC free?" logic re-created the dying channel (answers status,
+  never emits RTP). New `allow_idle=True` returns that reply as a
+  `ChannelInfo` with `frequency == 0.0`, meaning "radiod currently answers
+  for this SSRC at 0 Hz — not free to reuse". Default behaviour is
+  unchanged; `expected_freq` still rejects 0 Hz. `remove_channel()`'s
+  docstring now states the purge window.
+
+## 3.25.1 (2026-08-18)
+
+### Fixed
+
+- **`DEMOD_TYPE` no longer contradicts the preset it is sent with.**
+  `create_channel()` derived the demodulator from a five-name allowlist —
+  `demod_type = 0 if preset in ['iq','usb','lsb','cw','am'] else 1` — and sent
+  it immediately after `PRESET` in the same packet, so the later value won.
+  Every preset outside that list got `FM_DEMOD`, including `wfm`: radiod ran
+  the *narrowband* FM demodulator behind the wfm preset's ±110 kHz filter,
+  which emits nothing and reports `snr=-inf` indefinitely. Broadcast FM was
+  unusable through this library and the failure was silent — the channel
+  existed, verified, and simply never produced RTP.
+
+  `sam`, `ame`, `dsb`, `cwu`, `cwl`, `wspr`, `nam` and `amsq` were mislabelled
+  the same way (all are `demod = linear` in `presets.conf`), and `spectrum`
+  got FM rather than `SPECT_DEMOD`. Only the five allowlisted names were right.
+
+  `demod_type_for_preset()` now mirrors the `demod =` line of each stock
+  preset, and defaults to `LINEAR_DEMOD` — which `radio.h` defines as
+  "everything else" — rather than to FM.
+
+  Verified against radiod: a `wfm` channel now reports `demod_type=2` and,
+  with a squelch threshold below the signal, streams continuously (301
+  packets in 6 s where it previously produced none).
+
+  Note for callers: radiod's `wfm.c` sets `chan->squelch.snr_enable = true`
+  unconditionally when the demod thread starts, so `set_squelch(enable=False)`
+  is reverted on a wfm channel. Hold it open with a low `open_snr_db` instead.
+
+## 3.25.0 (2026-08-18)
+
+### Added
+
+- **`raw_payloads=True` on `RadiodStream` and `ManagedStream`: deliver
+  undecoded RTP payloads for the framed encodings.** `parse_rtp_samples()`
+  deliberately returns `None` for OPUS/OPUS_VOIP/AX25 — they have no
+  raw-sample representation — and `_process_packet` drops a `None`, so a
+  stream on any of those encodings ran healthy and silent: packets arrived,
+  the callback never fired, and nothing logged. The only way to consume an
+  Opus channel was `OpusDecoder`, i.e. decoding to PCM.
+
+  That is the wrong shape for a consumer that wants the codec frames
+  themselves — forwarding Opus to a browser's WebCodecs decoder, or writing
+  an Ogg/AX25 file — where decoding to PCM and re-encoding is pure loss.
+  With `raw_payloads=True`, `on_samples` receives a `List[bytes]`, one
+  entry per RTP packet in arrival order, and with
+  `deliver_interval_packets=1` that is exactly one frame per call.
+
+  Two properties callers must respect:
+
+  - The resequencer is **bypassed**. A codec frame is opaque: it can be
+    neither concatenated nor zero-filled, and gap concealment belongs to
+    the decoder (Opus has built-in PLC). Loss and reorder therefore surface
+    to the caller, which for a sequenced transport like TCP/WebSocket is
+    exactly right, and for a lossy one means the caller owns concealment.
+  - Quality accounting switches to **frames, not samples**:
+    `batch_samples_delivered` and `total_samples_expected` count RTP
+    packets, and the resequencer statistics stay zero because it never ran.
+
+  `stop()` no longer flushes the resequencer in this mode — its ndarray
+  output would otherwise be appended to a buffer of `bytes` and blow up in
+  `np.concatenate` on the final delivery.
+
+  The parameter is additive and defaults to `False`; the sample path is
+  unchanged. `tests/client_usage_manifest.json` is updated for the new
+  signature.
+
+- **`FILTER_DROPS` (tag 77) now decodes in `decode_status_dict()`, and is
+  carried on `ChannelInfo.filter_drops`.** radiod's per-channel count of
+  output blocks its demod thread lapped was decodable only in
+  `decode_status_packet()` → `ChannelStatus.filter_drops` — the typed
+  decoder nothing polls continuously. The lightweight decoder that
+  `StatusListener` runs on *every* broadcast silently skipped the tag, and
+  since listener callbacks receive a `ChannelInfo` rather than the status
+  dict, the counter never reached a long-running client at all. Measuring
+  radiod's own loss therefore meant either `metadump` (which follows one
+  stream, not the fleet) or hand-rolling a TLV walk.
+
+  This matters more since ka9q-radio `55d9048d`: a lapped block is now
+  counted *and* emitted as a block of zeros, so `PacketResequencer`'s
+  zero-block detection and this counter are two independent views of the
+  same event. Cross-checking them is what makes either trustworthy — the
+  same test that showed the pre-`55d9048d` counter accounted for only
+  6–15% of real timeline loss.
+
+  Two properties callers must respect, both covered by tests:
+
+  - The counter is **cumulative since radiod started**. Difference it
+    across two reads; a level on its own says nothing about current loss.
+  - **Absent ≠ zero.** A status packet without the tag leaves
+    `filter_drops` as `None` and does not clear a previously known count
+    — clearing it would read as a counter reset and produce a spurious
+    negative delta.
+
+  `ChannelInfo.filter_drops` is appended as the last field, so the change
+  is purely additive for positional construction. `client_usage_manifest.json`
+  is updated accordingly; the two signature entries were edited by hand
+  because `scripts/gen_client_manifest.py` scans `/opt/git/sigmond`, which
+  is not present on a dev box — re-run it on an appliance to confirm.
+
+### Deprecated
+
+- **`rtp_to_wallclock()` now emits `DeprecationWarning` on every call**
+  (audit F16, completing the 2026-06-27 rename). Signature and behavior
+  are unchanged — it delegates to `rtp_to_utc()`. The in-tree clients
+  (hf-timestd, wspr-recorder) migrated to `rtp_to_utc` before this
+  landed; internal callers (`RadiodStream`, `MultiStream`, `RTPRecorder`)
+  were migrated in the same commit so the library never warns about
+  itself on the per-packet path.
+
 ## 3.22.0 (2026-08-13)
 
 Audit remediation follow-up (findings F1, F3-F8, F10-F14 from the

{ka9q_python-3.22.0/ka9q_python.egg-info → ka9q_python-3.26.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.22.0
+Version: 3.26.0
 Summary: Python interface for ka9q-radio control and monitoring
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT

ka9q_python-3.26.0/docs/POLL-SUPPRESSION-DESIGN.md

@@ -0,0 +1,136 @@
+# Keeping channels alive on a shared control plane
+
+**Status:** design, not built. 2026-09-21.
+**Supersedes in practice:** the 30-second `set_channel_lifetime` keepalive.
+
+## What Phil asks of a controller
+
+Four rules, from ka9q's author on 2026-09-21:
+
+1. The control/status protocol stays **multicast, idempotent and shared**, so
+   several controllers can drive one radiod and all hold a coherent view.
+2. A controller sends configuration parameters autonomously **only** when
+   retransmitting a command whose tag has not yet been echoed. Otherwise it
+   sends an empty poll.
+3. Because every poll response dumps the whole channel state, a controller
+   should **share other controllers' responses** rather than ask again, and
+   should **randomize its poll timing**.
+4. A controller resets its poll timer when a status arrives that another
+   controller's poll triggered.
+
+And one prohibition that shapes everything below: no controller should
+automatically *correct* what it believes to be a wrong channel state. That
+starts a tuning war. State changes follow the user.
+
+## What we do today, and why it has to change
+
+`set_channel_lifetime(ssrc, 6000)` every 30 seconds per channel, carrying a
+re-asserted output encoding alongside. On AC0G-B4 that is 120 autonomous
+configuration broadcasts an hour, which every other controller on the plane
+must receive and parse.
+
+Rule 2 rules it out. Two measurements say we can drop it outright:
+
+- **An empty poll refreshes the self-destruct timer.** `decode_radio_commands`
+  begins `chan->lifetime = chan->lifestart`, for any command of length ≥ 2,
+  and `poll_channel` sends `COMMAND_TAG + OUTPUT_SSRC + EOL` and nothing
+  else. Measured on B4 2026-09-21: an unpolled control channel died at
+  37.7 s; a channel polled every 5 s outlived it and then died 43.7 s after
+  the polls stopped — one fresh lifetime from its last poll.
+- **The re-asserted encoding defends against nothing.** `loadpreset` sits
+  inside `case PRESET:` at both our pin and `ka9q/main`, so a LIFETIME-only
+  command never reaches it. Our own issue (HamSCI/ka9q-python#3) records that
+  we never reproduced the downgrade it guards against.
+
+## The design
+
+### The fact that makes it simple
+
+Every status packet carries the channel's **current remaining lifetime**
+(`radio_status.c`: `encode_int32(&bp,LIFETIME,chan->lifetime)`), and
+`status.py` already decodes it into `ChannelStatus.lifetime`.
+
+So a controller never has to *infer* whether someone else's command refreshed
+a timer. It reads the answer. When another controller polls a channel we own,
+the next status we see carries a lifetime that has jumped back up, and our
+own poll becomes unnecessary — rules 3 and 4 satisfied by observation rather
+than by bookkeeping about tags.
+
+That turns the keepalive from open loop (fire every 30 s regardless) into
+closed loop (act when the channel actually needs it).
+
+### Shape
+
+A `ChannelKeepalive` holding, per owned SSRC:
+
+- `lifetime_frames` — the last value seen in a status
+- `observed_at` — the monotonic time of that reading
+- `block_time_s` — measured, not assumed (see below)
+
+On each tick it projects the remaining lifetime forward from the last
+reading, and polls a channel only when that projection falls under a
+threshold, with jitter applied so two controllers do not synchronise.
+
+```
+remaining_s ≈ (lifetime_frames × block_time_s) − (now − observed_at)
+poll when    remaining_s < threshold_s × uniform(0.85, 1.15)
+```
+
+### Three things that must not go wrong
+
+**⛔ Absence of status must never read as health.** If no status has arrived
+for a channel within some bound, the controller knows nothing about its
+lifetime and must poll unconditionally. A suppression rule whose quiet state
+is "do nothing" turns a dropped multicast group into a fleet of channels
+quietly self-destructing. The fail-safe direction is to poll.
+
+**⛔ Suppression is per-SSRC, never global.** `chan->lifetime` is refreshed by
+a command addressed to *that channel*. Another controller polling a different
+SSRC refreshes nothing of ours. Seeing traffic on the plane is not evidence
+our channel was touched; seeing a status *for our SSRC* is.
+
+**⚠ Block time is a measurement, not a constant.** `lifetime` counts radiod
+main-loop blocks, and the conversion to seconds depends on the configured
+block time. B4 measured ~18.9 ms on 2026-09-21 (2000 frames ≈ 37.7 s) with no
+`blocktime` in its radiod config, so that is a default rather than a fleet
+constant. Derive it per station by watching the lifetime count down between
+two statuses, and fall back to polling on a fixed short period when it cannot
+be derived.
+
+### Threshold
+
+Margin has to cover the status cadence (`STATUS_INTERVAL`), the poll round
+trip, and lost packets on a multicast group with no retransmission. A
+threshold near a third of the configured lifetime leaves room for two missed
+statuses before the channel is at risk. With our 6000 frames ≈ 113 s, that
+puts a poll roughly every 35–40 s in the worst case — no worse than today —
+while a plane with several active controllers should see us poll rarely.
+
+### What it needs from the library
+
+`ChannelInfo` does not carry `lifetime`, though `ChannelStatus` does. Same
+plumbing gap that `demod_type` and `output_channels` had, and the same fix:
+decode it in `decode_status_dict` and pass it through in `discovery.py`.
+
+## What this design refuses to do
+
+It does not reconcile channel state. If a status shows a frequency or a
+filter we did not ask for, the keepalive records it and says nothing. Putting
+it back is the tuning war Phil warns against, and a controller that "knows
+better" than the operator is exactly the thing a shared plane cannot carry.
+
+`ChannelManager.ensure_channels_exist(update_existing=...)` already defaults
+to `False` and is reached only from operator-invoked CLI verbs. That default
+is load-bearing on a shared plane and should be commented as such, rather
+than left looking like an ordinary convenience.
+
+## Testing it
+
+The arrangement that settled the empty-poll question generalises: run two
+channels, drive one and leave the other, and let the untouched arm reveal the
+timescale. Then stop driving the first and confirm it dies — without that
+third arm, survival proves nothing about cause.
+
+For suppression specifically, the case worth building is two controllers on
+one SSRC: confirm the second suppresses while the first polls, and — the one
+that matters — confirm it resumes promptly when the first goes away.