ka9q-python 3.9.0__tar.gz → 3.12.0__tar.gz

{ka9q_python-3.9.0 → ka9q_python-3.12.0}/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## [3.12.0] - 2026-05-07
+
+### Added
+
+- **Spectrum bin vector decoding**: `decode_status_packet()` now decodes `BIN_DATA` (float32, `SPECT_DEMOD`) and `BIN_BYTE_DATA` (uint8, `SPECT2_DEMOD`) TLV vectors from radiod status packets. New fields on `SpectrumStatus`:
+  - `bin_data: Optional[np.ndarray]` — float32 power values per FFT bin.
+  - `bin_byte_data: Optional[np.ndarray]` — uint8 quantised log-power values.
+  - `bin_power_db` property — returns dB values regardless of source format (10*log10 for float data, `base + byte * step` for byte data).
+
+- **`SpectrumStream`**: new class for receiving real-time FFT spectrum data from radiod. Spectrum data flows over the status multicast channel (port 5006) as TLV vectors, not over RTP. `SpectrumStream` handles channel creation, periodic polling, SSRC filtering, and delivers decoded `ChannelStatus` objects (with populated `spectrum.bin_power_db`) to an `on_spectrum` callback. Supports retuning via `set_frequency()` and context manager usage.
+
+### Documentation
+
+- API_REFERENCE.md: SpectrumStream section, SpectrumStatus bin vector fields, quickstart table updated.
+- ARCHITECTURE.md: module listing, abstraction layer description, threading model updated.
+- RECIPES.md: Recipe 5 covering spectrum display, spectrogram accumulation, frequency axis reconstruction, FFT parameter tuning, and combined audio+spectrum patterns.
+- New `examples/spectrum_example.py`: runnable CLI example for real-time spectrum reception.
+
+### Tests
+
+- 13 new unit tests in `tests/test_spectrum.py` covering float32 and uint8 bin decoding, multi-byte TLV lengths, `bin_power_db` property, combined metadata+bins, edge cases, and import verification.
+
+---
+
+
+## [3.11.0] - 2026-05-06
+
+### Added
+
+- **Channel filter overrides on create / ensure / add_channel**: optional `low_edge`, `high_edge`, and `kaiser_beta` kwargs on `RadiodControl.create_channel()`, `RadiodControl.ensure_channel()`, and `MultiStream.add_channel()` — when specified, the requested filter passband is applied inline with the channel-create command (no transient at preset BW), and on the reuse path of `ensure_channel`, `set_filter` is called so the requested edges are authoritative regardless of the channel's prior state. Previously, callers were stuck with the preset's `low`/`high` values and had to either author a custom radiod preset or call `set_filter` manually after channel creation. Filter edges are not part of the SSRC hash — multiple callers requesting the same channel with different filters reconfigure last-writer-wins, matching the existing model for `gain` / `agc_enable`.
+  - Motivating clients: hf-timestd's BPSK PPS calibrator needs ~±500 Hz to match the TS1 injector's effectively-CW spectrum (the iq preset's ±5 kHz is wrong by an order of magnitude); planned SuperDARN and CODAR-sounder receivers need wider passbands than any single preset provides.
+
+### Backward Compatibility
+
+- Default behavior unchanged: omitting all three kwargs produces a wire packet with no LOW_EDGE / HIGH_EDGE / KAISER_BETA tags, so radiod uses the preset's defaults exactly as before. Reuse path also skips `set_filter` when no filter args are supplied.
+
+### Tests
+
+- 8 new unit tests in `tests/test_filter_edges.py` cover encode-presence on each entry point, encode-absence when omitted, ensure_channel forwarding on the create path, and ensure_channel reuse-path calling set_filter (only when filter args are supplied).
+
+---
+
+## [3.10.0] - 2026-04-30
+
+### Added
+
+- **Channel-lifetime keep-alive** (radiod 0f8b622+): support for ka9q-radio's new self-destruct timer, which lets a channel declare a lifetime in radiod main-loop frames (~50 Hz at the default 20 ms blocktime); 0 means infinite, >0 decrements every frame and destroys the channel at zero. This gives crash-resilient cleanup — if a client dies, its channels expire on their own instead of lingering on radiod.
+  - `RadiodControl.set_channel_lifetime(ssrc, lifetime)` — explicit poll that sends the LIFETIME tag, suitable as a periodic keep-alive.
+  - `RadiodControl.create_channel(..., lifetime=None)` — optional kwarg; sends LIFETIME on the creation packet when provided.
+  - `RadiodControl.ensure_channel(..., lifetime=None)` — passes through to `create_channel`; on the reuse path, calls `set_channel_lifetime` so the value is enforced regardless of the channel's prior state.
+  - `RadiodControl.tune(..., lifetime=None)` — optional kwarg; LIFETIME is included in the multi-parameter command buffer.
+  - `_decode_status_response()` exposes received LIFETIME as `status['lifetime']`; `ChannelStatus.lifetime` field.
+- **`StatusType.LIFETIME = 117`** in `ka9q/types.py` (synced from ka9q-radio commit `5498aef`).
+- **`StatusType.DESCRIPTION` decode** in `_decode_status_response()`: incoming front-end / channel description strings are now surfaced as `status['description']` (the encode side already existed via `set_description`).
+
+### Backward Compatibility
+
+- Default behavior unchanged: omitting `lifetime` produces a wire packet with no LIFETIME tag, so pre-`0f8b622` radiod stays compatible and existing clients see no change. Channels created without LIFETIME inherit radiod's template default (0 = infinite) and live until destroyed.
+
+### Tests
+
+- 10 new unit tests in `tests/test_lifetime.py` cover encode-presence on each entry point, encode-absence when omitted, and validation of negative / non-int inputs.
+- Refreshed stale `tests/test_encode_socket.py` to match the current 6-byte wire format that radiod's `decode_socket()` actually expects.
+- Hardened `tests/test_native_discovery.py::test_native_discovery_with_valid_packet` to mock `RadiodControl._connect`, removing the DNS dependency on `test.local`.
+
+---
+
+## [3.9.0] - 2026-04-15
+
+### Added
+
+- **`ka9q` CLI** (`ka9q/cli.py`): new console entry point `ka9q` (declared via `[project.scripts]`), exposing channel discovery, tune, create, destroy, and status commands against a running radiod.
+- **Textual TUI** (`ka9q/tui.py`): an interactive Textual app for browsing channels and tuning interactively, with radiod and SSRC pickers. Optional install via `pip install ka9q-python[tui]`.
+- **Typed `ChannelStatus` decoder** (`ka9q/status.py`): a typed dataclass view over the dict returned by `_decode_status_response`, so callers can use attribute access and IDE-completable fields instead of dict keys.
+
+---
+
 ## [3.8.0] - 2026-04-12
 
 ### Added

{ka9q_python-3.9.0/ka9q_python.egg-info → ka9q_python-3.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ka9q-python
-Version: 3.9.0
+Version: 3.12.0
 Summary: Python interface for ka9q-radio control and monitoring
 Home-page: https://github.com/mijahauan/ka9q-python
 Author: Michael Hauan AC0G
@@ -60,15 +60,15 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 
 ## Features
 
-✅ **Zero assumptions** - Works for any SDR application  
-✅ **Complete API** - All 85+ radiod parameters exposed  
-✅ **Channel control** - Create, configure, discover channels  
-✅ **RTP recording** - Generic recorder with timing support and state machine  
-✅ **Precise timing** - GPS_TIME/RTP_TIMESNAP for accurate timestamps  
-✅ **Multi-homed support** - Works on systems with multiple network interfaces  
-✅ **Pure Python** - No compiled dependencies  
-✅ **Well tested** - Comprehensive test coverage  
-✅ **Documented** - Comprehensive examples and API reference included  
+- **Complete radiod API** — all 110+ TLV status/command parameters exposed, generated from ka9q-radio's C headers
+- **Four stream abstractions** — `RTPRecorder` (raw packets), `RadiodStream` (samples + gap handling), `ManagedStream` (self-healing single channel), `MultiStream` (shared socket, many SSRCs)
+- **Typed status decoder** — `ChannelStatus`, `FrontendStatus`, `PllStatus`, etc. with dotted-path field access
+- **Precise RTP timing** — GPS_TIME / RTP_TIMESNAP for sample-accurate wallclock timestamps
+- **LAN discovery** — enumerate radiod instances and their active channels via mDNS
+- **CLI + TUI** — `ka9q list / query / set / tui` for interactive and scripted control
+- **Multi-homed** — explicit interface selection for hosts with multiple NICs
+- **Protocol drift detection** — pinned to a specific ka9q-radio commit, with a sync script
+- **Pure Python** — NumPy is the only runtime dependency
 
 ## Installation
 
@@ -215,6 +215,7 @@ monitor.monitor_channel(
     preset="usb",
     sample_rate=12000
 )
+```
 
 ### Channel Cleanup (frequency = 0)
 
@@ -293,63 +294,39 @@ It auto-skips if `../ka9q-radio` is not present, so CI environments without the
 
 ## Documentation
 
-For detailed information, please refer to the documentation in the `docs/` directory:
-
-- **[API Reference](docs/API_REFERENCE.md)**: Full details on all classes, methods, and functions.
-- **[TUI Guide](docs/TUI_GUIDE.md)**: Launching and using the `ka9q tui` Textual terminal UI.
-- **[RTP Timing Support](docs/RTP_TIMING_SUPPORT.md)**: Guide to RTP timing and synchronization.
-- **[Architecture](docs/ARCHITECTURE.md)**: Overview of the library's design and structure.
-- **[Installation Guide](docs/INSTALLATION.md)**: Detailed installation instructions.
-- **[Testing Guide](docs/TESTING_GUIDE.md)**: Information on how to run the test suite.
-- **[Security Considerations](docs/SECURITY.md)**: Important security information regarding the ka9q-radio protocol.
-- **[Changelog](docs/CHANGELOG.md)**: A log of all changes for each version.
-- **[Release Notes](docs/releases/)**: Release-specific notes and instructions.
+- **[Getting Started](docs/GETTING_STARTED.md)** — first-run walkthrough
+- **[Recipes](docs/RECIPES.md)** — task-oriented cookbook: LAN probing, fixed-channel pipelines (WSPR/PSK/FT8/timing), nimble SWL-style retuning, and using ka9q-python across different SDRs
+- **[API Reference](docs/API_REFERENCE.md)** — every public class, method, and function
+- **[Architecture](docs/ARCHITECTURE.md)** — module layout, threading, protocol
+- **[CLI Guide](docs/CLI_GUIDE.md)** — `ka9q list / query / set / tui` command reference
+- **[TUI Guide](docs/TUI_GUIDE.md)** — the Textual terminal UI
+- **[MultiStream Guide](docs/MULTI_STREAM.md)** — shared-socket multi-channel receiver
+- **[RTP Timing](docs/RTP_TIMING_SUPPORT.md)** — GPS_TIME / RTP_TIMESNAP for sample-accurate timestamps
+- **[Installation](docs/INSTALLATION.md)** · **[Testing](docs/TESTING_GUIDE.md)** · **[Security](docs/SECURITY.md)**
+- **[Changelog](CHANGELOG.md)**
 
 ## Examples
 
-See the `examples/` directory for complete applications:
-
-- **High-Level API**: `ensure_channel()` handles the complexity of checking existing channels, creating new ones only when necessary, and verifying configurations.
-- **Destination-Aware Channels**: Support for unique per-application multicast destinations and deterministic IP generation.
-- **Stream Sharing**: Deterministic SSRC allocation allows multiple independent applications to share `radiod` streams efficiently.
-- **`discover_example.py`** - Channel discovery methods (native Python and control utility)
-- **`tune.py`** - Interactive channel tuning utility (Python implementation of ka9q-radio's tune)
-- **`tune_example.py`** - Programmatic examples of using the tune() method
-- **`rtp_recorder_example.py`** - Complete RTP recorder with timing and state machine
-- **`test_timing_fields.py`** - Verify GPS_TIME/RTP_TIMESNAP timing fields
-- **`simple_am_radio.py`** - Minimal AM broadcast listener
-- **`superdarn_recorder.py`** - Ionospheric radar monitoring
-- **`codar_oceanography.py`** - Ocean current radar
-- **`hf_band_scanner.py`** - Dynamic frequency scanner
-- **`wspr_monitor.py`** - Weak signal propagation reporter
+See [`examples/`](examples/) for runnable scripts:
+
+- [`simple_am_radio.py`](examples/simple_am_radio.py) — minimal AM listener
+- [`discover_example.py`](examples/discover_example.py) — channel discovery on the LAN
+- [`stream_example.py`](examples/stream_example.py) — `RadiodStream` sample callback
+- [`rtp_recorder_example.py`](examples/rtp_recorder_example.py) — precise-timing RTP recorder
+- [`multi_stream_smoke.py`](examples/multi_stream_smoke.py) — `MultiStream` multi-SSRC receiver
+- [`hf_band_scanner.py`](examples/hf_band_scanner.py) — dynamic band scanner
+- [`channel_cleanup_example.py`](examples/channel_cleanup_example.py) — teardown via frequency=0
+- [`tune.py`](examples/tune.py) — interactive tuning utility
+- [`superdarn_recorder.py`](examples/superdarn_recorder.py), [`codar_oceanography.py`](examples/codar_oceanography.py), [`grape_integration_example.py`](examples/grape_integration_example.py) — domain-specific recorders
 
 ## Use Cases
 
-### AM/FM/SSB Radio
-- Broadcast monitoring
-- Ham radio operation  
-- Shortwave listening
-
-### Scientific Research
-- WSPR propagation studies
-- SuperDARN ionospheric radar
-- CODAR ocean current mapping
-- Meteor scatter
-- EME (moonbounce)
-
-### Digital Modes
-- FT8/FT4 monitoring
-- RTTY/PSK decoding
-- DRM digital radio
-- HF fax reception
-
-### Satellite Operations
-- Downlink reception
-- Doppler tracking
-- Multi-frequency monitoring
-
-### Custom Applications
-**No assumptions!** Use for anything SDR-related.
+See [docs/RECIPES.md](docs/RECIPES.md) for worked examples of:
+
+- **LAN probing** — enumerate radiod instances and their active channels
+- **Fixed-channel pipelines** — WSPR, PSK/FT8, HF timing (bundled band plans, `MultiStream`); see companion projects `wspr-recorder`, `psk-recorder`, `hf-timestd`
+- **Nimble channel switching** — single-channel SWL-style retuning driven from the CLI or an app
+- **SDR portability** — ka9q-python talks to `radiod`, which talks to the SDR; reporting frontend capabilities via `FrontendStatus`. Primary tested frontend is the RX888; AirspyR2 and Airspy HF+ support is in development.
 
 ## License
 

{ka9q_python-3.9.0 → ka9q_python-3.12.0}/README.md

@@ -23,15 +23,15 @@ Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, S
 
 ## Features
 
-✅ **Zero assumptions** - Works for any SDR application  
-✅ **Complete API** - All 85+ radiod parameters exposed  
-✅ **Channel control** - Create, configure, discover channels  
-✅ **RTP recording** - Generic recorder with timing support and state machine  
-✅ **Precise timing** - GPS_TIME/RTP_TIMESNAP for accurate timestamps  
-✅ **Multi-homed support** - Works on systems with multiple network interfaces  
-✅ **Pure Python** - No compiled dependencies  
-✅ **Well tested** - Comprehensive test coverage  
-✅ **Documented** - Comprehensive examples and API reference included  
+- **Complete radiod API** — all 110+ TLV status/command parameters exposed, generated from ka9q-radio's C headers
+- **Four stream abstractions** — `RTPRecorder` (raw packets), `RadiodStream` (samples + gap handling), `ManagedStream` (self-healing single channel), `MultiStream` (shared socket, many SSRCs)
+- **Typed status decoder** — `ChannelStatus`, `FrontendStatus`, `PllStatus`, etc. with dotted-path field access
+- **Precise RTP timing** — GPS_TIME / RTP_TIMESNAP for sample-accurate wallclock timestamps
+- **LAN discovery** — enumerate radiod instances and their active channels via mDNS
+- **CLI + TUI** — `ka9q list / query / set / tui` for interactive and scripted control
+- **Multi-homed** — explicit interface selection for hosts with multiple NICs
+- **Protocol drift detection** — pinned to a specific ka9q-radio commit, with a sync script
+- **Pure Python** — NumPy is the only runtime dependency
 
 ## Installation
 
@@ -178,6 +178,7 @@ monitor.monitor_channel(
     preset="usb",
     sample_rate=12000
 )
+```
 
 ### Channel Cleanup (frequency = 0)
 
@@ -256,63 +257,39 @@ It auto-skips if `../ka9q-radio` is not present, so CI environments without the
 
 ## Documentation
 
-For detailed information, please refer to the documentation in the `docs/` directory:
-
-- **[API Reference](docs/API_REFERENCE.md)**: Full details on all classes, methods, and functions.
-- **[TUI Guide](docs/TUI_GUIDE.md)**: Launching and using the `ka9q tui` Textual terminal UI.
-- **[RTP Timing Support](docs/RTP_TIMING_SUPPORT.md)**: Guide to RTP timing and synchronization.
-- **[Architecture](docs/ARCHITECTURE.md)**: Overview of the library's design and structure.
-- **[Installation Guide](docs/INSTALLATION.md)**: Detailed installation instructions.
-- **[Testing Guide](docs/TESTING_GUIDE.md)**: Information on how to run the test suite.
-- **[Security Considerations](docs/SECURITY.md)**: Important security information regarding the ka9q-radio protocol.
-- **[Changelog](docs/CHANGELOG.md)**: A log of all changes for each version.
-- **[Release Notes](docs/releases/)**: Release-specific notes and instructions.
+- **[Getting Started](docs/GETTING_STARTED.md)** — first-run walkthrough
+- **[Recipes](docs/RECIPES.md)** — task-oriented cookbook: LAN probing, fixed-channel pipelines (WSPR/PSK/FT8/timing), nimble SWL-style retuning, and using ka9q-python across different SDRs
+- **[API Reference](docs/API_REFERENCE.md)** — every public class, method, and function
+- **[Architecture](docs/ARCHITECTURE.md)** — module layout, threading, protocol
+- **[CLI Guide](docs/CLI_GUIDE.md)** — `ka9q list / query / set / tui` command reference
+- **[TUI Guide](docs/TUI_GUIDE.md)** — the Textual terminal UI
+- **[MultiStream Guide](docs/MULTI_STREAM.md)** — shared-socket multi-channel receiver
+- **[RTP Timing](docs/RTP_TIMING_SUPPORT.md)** — GPS_TIME / RTP_TIMESNAP for sample-accurate timestamps
+- **[Installation](docs/INSTALLATION.md)** · **[Testing](docs/TESTING_GUIDE.md)** · **[Security](docs/SECURITY.md)**
+- **[Changelog](CHANGELOG.md)**
 
 ## Examples
 
-See the `examples/` directory for complete applications:
-
-- **High-Level API**: `ensure_channel()` handles the complexity of checking existing channels, creating new ones only when necessary, and verifying configurations.
-- **Destination-Aware Channels**: Support for unique per-application multicast destinations and deterministic IP generation.
-- **Stream Sharing**: Deterministic SSRC allocation allows multiple independent applications to share `radiod` streams efficiently.
-- **`discover_example.py`** - Channel discovery methods (native Python and control utility)
-- **`tune.py`** - Interactive channel tuning utility (Python implementation of ka9q-radio's tune)
-- **`tune_example.py`** - Programmatic examples of using the tune() method
-- **`rtp_recorder_example.py`** - Complete RTP recorder with timing and state machine
-- **`test_timing_fields.py`** - Verify GPS_TIME/RTP_TIMESNAP timing fields
-- **`simple_am_radio.py`** - Minimal AM broadcast listener
-- **`superdarn_recorder.py`** - Ionospheric radar monitoring
-- **`codar_oceanography.py`** - Ocean current radar
-- **`hf_band_scanner.py`** - Dynamic frequency scanner
-- **`wspr_monitor.py`** - Weak signal propagation reporter
+See [`examples/`](examples/) for runnable scripts:
+
+- [`simple_am_radio.py`](examples/simple_am_radio.py) — minimal AM listener
+- [`discover_example.py`](examples/discover_example.py) — channel discovery on the LAN
+- [`stream_example.py`](examples/stream_example.py) — `RadiodStream` sample callback
+- [`rtp_recorder_example.py`](examples/rtp_recorder_example.py) — precise-timing RTP recorder
+- [`multi_stream_smoke.py`](examples/multi_stream_smoke.py) — `MultiStream` multi-SSRC receiver
+- [`hf_band_scanner.py`](examples/hf_band_scanner.py) — dynamic band scanner
+- [`channel_cleanup_example.py`](examples/channel_cleanup_example.py) — teardown via frequency=0
+- [`tune.py`](examples/tune.py) — interactive tuning utility
+- [`superdarn_recorder.py`](examples/superdarn_recorder.py), [`codar_oceanography.py`](examples/codar_oceanography.py), [`grape_integration_example.py`](examples/grape_integration_example.py) — domain-specific recorders
 
 ## Use Cases
 
-### AM/FM/SSB Radio
-- Broadcast monitoring
-- Ham radio operation  
-- Shortwave listening
-
-### Scientific Research
-- WSPR propagation studies
-- SuperDARN ionospheric radar
-- CODAR ocean current mapping
-- Meteor scatter
-- EME (moonbounce)
-
-### Digital Modes
-- FT8/FT4 monitoring
-- RTTY/PSK decoding
-- DRM digital radio
-- HF fax reception
-
-### Satellite Operations
-- Downlink reception
-- Doppler tracking
-- Multi-frequency monitoring
-
-### Custom Applications
-**No assumptions!** Use for anything SDR-related.
+See [docs/RECIPES.md](docs/RECIPES.md) for worked examples of:
+
+- **LAN probing** — enumerate radiod instances and their active channels
+- **Fixed-channel pipelines** — WSPR, PSK/FT8, HF timing (bundled band plans, `MultiStream`); see companion projects `wspr-recorder`, `psk-recorder`, `hf-timestd`
+- **Nimble channel switching** — single-channel SWL-style retuning driven from the CLI or an app
+- **SDR portability** — ka9q-python talks to `radiod`, which talks to the SDR; reporting frontend capabilities via `FrontendStatus`. Primary tested frontend is the RX888; AirspyR2 and Airspy HF+ support is in development.
 
 ## License