ka9q-python 3.15.1__tar.gz → 3.17.0__tar.gz

{ka9q_python-3.15.1 → ka9q_python-3.17.0}/CHANGELOG.md

@@ -1,5 +1,180 @@
 # Changelog
 
+## [3.17.0] - 2026-06-28
+
+First release marked **Production/Stable** (trove classifier 4 → 5). Folds in
+23 commits of feature and resilience work that had accumulated on `main` past
+the `v3.16.1` tag with no version bump.
+
+### Added
+
+- **`RadiodControl.poll_channel(ssrc)`** (`control.py`) — a targeted, O(1)
+  status probe for a single channel. Replaces the previous reliance on a full
+  channel discovery sweep when only one channel's state is needed.
+- **`MultiStream.prune_frequency(...)`** (`multi_stream.py`) — releases a
+  superseded channel slot *and its ring buffer*, fixing a ring leak when a
+  frequency is retuned/replaced within a live `MultiStream`.
+- **mDNS hostname + port surfaced by discovery** (`discovery.py`) — additive
+  fields on the discovery result; existing consumers are unaffected.
+- **RTP↔GPS offset-step detection (`anchor_epoch`)** (`stream.py`) — a
+  `RadiodStream` now detects a step in radiod's RTP↔GPS offset and re-anchors
+  its timing reference instead of carrying a stale anchor.
+
+### Changed
+
+- **`ensure_channel` now verifies via `poll_channel` (O(1))** instead of a dead
+  discovery sweep (`control.py`). Faster, more reliable channel confirmation.
+  Note a deliberate relaxation on the *create* path: the channel is now accepted
+  on **frequency match alone** — a rate/preset divergence is logged as a warning
+  (not raised) and the destination is no longer re-verified. Callers should treat
+  the returned `ChannelInfo` as authoritative for the granted encoding/rate
+  (the sigmond recorders already do). The reuse path still verifies strictly.
+- **`RadiodStream` binds the channel's multicast group**, not `0.0.0.0`
+  (`stream.py`) — avoids cross-talk on hosts carrying multiple multicast groups.
+- **`rtp_to_wallclock` renamed to `rtp_to_utc`** (`rtp_recorder.py`). The name
+  "wallclock" wrongly implied a system-clock dependency; the function is purely
+  RTP/GPS-referenced. `rtp_to_wallclock` remains as a deprecated alias — no
+  caller needs to change.
+- **`anchor_step_threshold_sec` raised 0.25 → 0.75** (`stream.py`) to tolerate
+  output-timing jitter on a busy radiod without spuriously re-anchoring.
+- **8 MB receive buffer on `poll_channel`'s status listener** (`control.py`) to
+  avoid drops while probing on a busy status multicast group.
+- **ka9q-radio compatibility pin advanced to `9b742e6`** (no protocol drift;
+  validated by `check_upstream_drift.py`).
+- **Repository moved to the HamSCI org**; project/doc/URL references updated
+  from `mijahauan/` to `HamSCI/`.
+
+### Fixed
+
+- **Gap storm now treated as a stream-health failure → re-subscribe**
+  (`multi_stream.py`, 228a041). A stale `MultiStream` subscription after a
+  radiod restart manifests as a sustained packet-gap storm (not silence); the
+  health monitor now detects it and re-subscribes, restoring delivery without
+  an external restart. See the sigmond `stale-subscription-gap-storm-protection`
+  note.
+
+### Packaging
+
+- **Removed the redundant `setup.py`.** All project metadata lives in
+  `pyproject.toml`'s PEP 621 `[project]` table (`setuptools.build_meta`
+  backend). `setup.py` had drifted to a stale `3.10.0` / `4 - Beta` duplicate
+  and was an unused second source of truth.
+
+### Docs / Tests
+
+- Added a **requirements baseline** (`docs/REQUIREMENTS.md`, `KQP-*` spec).
+- `CLAUDE.md` documents `MultiStream` as the fourth abstraction layer.
+- The **live channel-verification suite is now gated behind explicit opt-in**
+  (`--radiod-host`), so the default `pytest` run no longer hangs waiting on a
+  live radiod. Unit suite: 363 passed, 27 skipped.
+
+## [3.16.1] - 2026-05-24
+
+### Fixed
+
+- **`ChannelInfo` anchor pair is now atomic** (`channel-info`).  Adds
+  `ChannelInfo.get_anchor()` / `update_anchor()` — a tuple-based
+  atomic snapshot of `(gps_time, rtp_timesnap)`.  `rtp_to_wallclock`
+  now reads the pair via `get_anchor` (single GIL-atomic attribute
+  access) instead of two separate reads; `StatusListener` writes via
+  `update_anchor` (single tuple assignment).
+
+  Why: the `StatusListener` introduced in 3.16.0 refreshes the anchor
+  in place at sub-second cadence (~450 ms on a busy host).  Direct
+  sequential reads of `channel.gps_time` followed by
+  `channel.rtp_timesnap` could land between the listener's two writes
+  and yield a torn pair off by one listener-cadence interval.
+  `rtp_to_wallclock` then returned a wall-time off by that much —
+  usually harmless, but consumers comparing against an external time
+  reference with a tight gate (e.g. hf-timestd's T5 LB-1421 NMEA
+  disambig at ±0.5 s) could be pushed across the threshold and fall
+  back to a chrony walk that itself fails during a post-restart
+  cascade.
+
+  Backward compatible: constructor kwargs (`gps_time=`,
+  `rtp_timesnap=`) and direct field reads are unchanged; consumers
+  that need the pair transactionally must call `get_anchor`.  Adds
+  5 new tests (atomic update, construction-time seed, mixed-None
+  handling, listener path, 50-iteration consistency smoke test).
+
+### Performance
+
+- **`RadiodStream`: `SO_RCVBUF` raised 0 → 64 MB** (`stream.py`).
+  Mirrors the 3.16.0-cycle `multi_stream.py` change on the
+  single-channel path.  Previously `RadiodStream` sockets fell back
+  to the kernel default (`rmem_default`, typically 16 MB on hosts
+  with sigmond's `rule_kernel_rcvbuf_adequate` provisioning) and were
+  vulnerable to GIL-stall packet loss with no other consumer competing
+  to drain the buffer.  64 MB matches the `MultiStream` cap; sigmond
+  provisions `net.core.rmem_max=128 MB` (after kernel doubling), so
+  the request is honored.  Observed on bee1 2026-05-23 closing a
+  140 ms-stall-induced `gap=13440` resequencer event on hf-timestd's
+  T6 dedicated stream.
+
+- **`MultiStream`: `SO_RCVBUF` raised 8 MB → 64 MB** (`multi_stream.py`).
+  Observed 412 M UDP `RcvbufErrors` on B4-100 since boot, driven by
+  GIL contention preventing Python receiver threads from draining the
+  kernel-doubled 16 MB sockets.  Bigger absorber → more headroom
+  across GIL stalls before packets are dropped.  After applying:
+  socket `rb` shows 134217728 (128 MB visible after kernel doubling)
+  and recv-Q sits at ~50 KB in steady state (was hitting 14 MB / 16
+  MB before).  Requires `net.core.rmem_max >= 64 MB` to be honored —
+  provisioned by sigmond in
+  `/etc/sysctl.d/99-wspr-recorder.conf` alongside this change.
+
+## [3.16.0] - 2026-05-23
+
+### Added
+
+- **`StatusListener` — continuous STATUS multicast listener.**  New
+  `ka9q.status_listener.StatusListener` class subscribes to radiod's
+  STATUS multicast (port 5006) in a background thread and refreshes
+  `ChannelInfo.gps_time` / `.rtp_timesnap` on every broadcast.  Replaces
+  the previous one-shot `discover_channels` anchor capture, which
+  froze the timing anchor at SSRC discovery — leaving `rtp_to_wallclock`
+  to project forward from a host-clock value that drifts at the
+  chrony slew rate (~3.8 µs/s on a typical disciplined host).
+
+  Mutates the registered `ChannelInfo` in place so callers holding a
+  reference (e.g. hf-timestd's cached `_t6_channel_info`) see fresh
+  values immediately.  Supports per-SSRC and wildcard callbacks for
+  explicit notification.  Uses `SO_REUSEPORT` so it can coexist with
+  `RadiodControl`'s own status socket without stealing tune/discover
+  responses — multicast packets are delivered to every joined socket.
+
+  Opt-in via `RadiodControl.start_status_listener()`; closing the
+  control object stops the listener.  See class docstring for usage.
+
+- **`RadiodControl.start_status_listener(...)` / `.stop_status_listener(...)`
+  / `.status_listener` property** — convenience wiring to attach a
+  `StatusListener` to an existing control session.  Listener is
+  stopped automatically by `RadiodControl.close()`.
+
+### Why this exists
+
+Before this release, every ka9q-python consumer (hf-timestd, codar,
+psk, hfdl, wspr, wsprdaemon-client, gpsdo-monitor) labeled data via
+`rtp_to_wallclock(rtp, channel)` with a ChannelInfo whose
+`gps_time`/`rtp_timesnap` were captured once at SSRC discovery.
+For long-running services this meant labels drifted from GPSDO truth
+at the host-clock slew rate — on bee1 (`chrony` slewing at
+~3.8 µs/s), labels accumulated ~330 ms of drift per day.
+
+The chrony SHM-push side of hf-timestd's BPSK PPS path (HPPS / HFPS)
+manifested this most visibly: TS-1 source reported tracking with
+1 ns standard deviation but drifted at the host slew rate, blocking
+DASI2 grant deployment.  Faster anchor refresh closes the drift.
+
+### Backwards compatibility
+
+- All existing tests pass unchanged.  The listener is **opt-in** —
+  consumers that don't call `start_status_listener()` see no behavior
+  change.
+- `ChannelInfo` is unchanged structurally; only its mutability
+  contract is clarified (the timing fields were always documented as
+  "the latest snapshot", which is now true continuously rather than
+  once).
+
 ## [3.15.1] - 2026-05-21
 
 ### Fixed

{ka9q_python-3.15.1/ka9q_python.egg-info → ka9q_python-3.17.0}/PKG-INFO

@@ -1,17 +1,15 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.15.1
+Version: 3.17.0
 Summary: Python interface for ka9q-radio control and monitoring
-Home-page: https://github.com/mijahauan/ka9q-python
-Author: Michael Hauan AC0G
 Author-email: Michael Hauan AC0G <ac0g@hauan.org>
 License: MIT
-Project-URL: Homepage, https://github.com/mijahauan/ka9q-python
-Project-URL: Documentation, https://github.com/mijahauan/ka9q-python/blob/main/README.md
-Project-URL: Repository, https://github.com/mijahauan/ka9q-python
-Project-URL: Issues, https://github.com/mijahauan/ka9q-python/issues
+Project-URL: Homepage, https://github.com/HamSCI/ka9q-python
+Project-URL: Documentation, https://github.com/HamSCI/ka9q-python/blob/main/README.md
+Project-URL: Repository, https://github.com/HamSCI/ka9q-python
+Project-URL: Issues, https://github.com/HamSCI/ka9q-python/issues
 Keywords: ka9q-radio,sdr,ham-radio,radio-control
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Intended Audience :: Telecommunications Industry
 Classifier: Programming Language :: Python :: 3
@@ -32,10 +30,7 @@ Provides-Extra: tui
 Requires-Dist: textual>=0.50; extra == "tui"
 Provides-Extra: opus
 Requires-Dist: opuslib>=3.0; extra == "opus"
-Dynamic: author
-Dynamic: home-page
 Dynamic: license-file
-Dynamic: requires-python
 
 # ka9q-python
 
@@ -95,7 +90,7 @@ pip install "ka9q-python[tui,opus]"      # multiple
 Or install from source:
 
 ```bash
-git clone https://github.com/mijahauan/ka9q-python.git
+git clone https://github.com/HamSCI/ka9q-python.git
 cd ka9q-python
 pip install -e .
 ```

{ka9q_python-3.15.1 → ka9q_python-3.17.0}/README.md

@@ -56,7 +56,7 @@ pip install "ka9q-python[tui,opus]"      # multiple
 Or install from source:
 
 ```bash
-git clone https://github.com/mijahauan/ka9q-python.git
+git clone https://github.com/HamSCI/ka9q-python.git
 cd ka9q-python
 pip install -e .
 ```

{ka9q_python-3.15.1 → ka9q_python-3.17.0}/docs/GETTING_STARTED.md

@@ -25,7 +25,7 @@ pip install ka9q-python
 Or, if you want to install from source:
 
 ```bash
-git clone https://github.com/mijahauan/ka9q-python.git
+git clone https://github.com/HamSCI/ka9q-python.git
 cd ka9q-python
 pip install -e .
 ```
@@ -235,7 +235,7 @@ Congratulations! You've created your first `ka9q-python` application and learned
 
 3. **Learn About Advanced Features**: Check out `examples/advanced_features_demo.py` to see how to use Doppler tracking, PLL configuration, squelch, and more.
 
-4. **Join the Community**: If you have questions or want to contribute, visit the [GitHub repository](https://github.com/mijahauan/ka9q-python).
+4. **Join the Community**: If you have questions or want to contribute, visit the [GitHub repository](https://github.com/HamSCI/ka9q-python).
 
 ---
 

{ka9q_python-3.15.1 → ka9q_python-3.17.0}/docs/INSTALLATION.md

@@ -13,12 +13,12 @@ The distribution name is `ka9q-python`; the import name is `ka9q`.
 
 ### From GitHub (development version)
 ```bash
-pip install git+https://github.com/mijahauan/ka9q-python.git
+pip install git+https://github.com/HamSCI/ka9q-python.git
 ```
 
 ### From Local Clone
 ```bash
-git clone https://github.com/mijahauan/ka9q-python.git
+git clone https://github.com/HamSCI/ka9q-python.git
 cd ka9q-python
 pip install .
 ```
@@ -27,7 +27,7 @@ pip install .
 
 ### Editable Install
 ```bash
-git clone https://github.com/mijahauan/ka9q-python.git
+git clone https://github.com/HamSCI/ka9q-python.git
 cd ka9q-python
 pip install -e .
 ```
@@ -218,7 +218,7 @@ twine upload dist/*
 
 ```bash
 # Clone and install in editable mode
-git clone https://github.com/mijahauan/ka9q-python.git
+git clone https://github.com/HamSCI/ka9q-python.git
 cd ka9q-python
 pip install -e ".[dev]"
 
@@ -285,5 +285,5 @@ if __name__ == '__main__':
 ## Support
 
 - Documentation: See README.md and other docs in the repository
-- Issues: https://github.com/mijahauan/ka9q-python/issues
+- Issues: https://github.com/HamSCI/ka9q-python/issues
 - Examples: See `examples/` directory

{ka9q_python-3.15.1 → ka9q_python-3.17.0}/docs/MULTI_STREAM.md

@@ -38,10 +38,10 @@ Keep `ManagedStream` when:
 - You specifically want each channel's receive path isolated.
 
 Production users:
-[psk-recorder](https://github.com/mijahauan/psk-recorder) runs 20
+[psk-recorder](https://github.com/HamSCI/psk-recorder) runs 20
 channels (10 FT4 + 10 FT8) on bee3 through a single `MultiStream`.
-[wspr-recorder](https://github.com/mijahauan/wspr-recorder) and
-[hf-timestd](https://github.com/mijahauan/hf-timestd) use the same
+[wspr-recorder](https://github.com/HamSCI/wspr-recorder) and
+[hf-timestd](https://github.com/HamSCI/hf-timestd) use the same
 pattern.
 
 ---

{ka9q_python-3.15.1 → ka9q_python-3.17.0}/docs/RECIPES.md

@@ -130,9 +130,9 @@ matters.
 ## Recipe 2 — Fixed sets of same-type channels (WSPR, PSK, FT8, timing)
 
 This is the pattern used by
-[wspr-recorder](https://github.com/mijahauan/wspr-recorder),
-[psk-recorder](https://github.com/mijahauan/psk-recorder), and
-[hf-timestd](https://github.com/mijahauan/hf-timestd):
+[wspr-recorder](https://github.com/HamSCI/wspr-recorder),
+[psk-recorder](https://github.com/HamSCI/psk-recorder), and
+[hf-timestd](https://github.com/HamSCI/hf-timestd):
 
 1. Read a band plan (list of frequencies + preset + sample rate).
 2. For each entry, call `ensure_channel()` — deterministic SSRC