ka9q-python 3.4.2__tar.gz → 3.7.0__tar.gz

ka9q_python-3.7.0/CHANGELOG.md

@@ -0,0 +1,628 @@
+# Changelog
+
+## [3.7.0] - 2026-04-12
+
+### Changed
+
+- **Radiod-aware multicast addressing**: `generate_multicast_ip()` now accepts a `radiod_host` keyword argument. When provided, the hash is computed over both the client identifier and the radiod host, producing a distinct multicast IP for each (client, radiod) pair. This prevents address collisions when the same client application (e.g., `hf-timestd`) connects to multiple radiod instances simultaneously.
+- **Radiod-aware SSRC allocation**: `allocate_ssrc()` now accepts a `radiod_host` parameter, included in the deterministic hash. The same channel parameters on different radiod instances produce distinct SSRCs.
+- **Automatic radiod identity propagation**: `RadiodControl.create_channel()` and `RadiodControl.ensure_channel()` automatically pass `self.status_address` as `radiod_host` when computing SSRCs. No API changes needed for callers using the `RadiodControl` methods — radiod-aware uniqueness is automatic.
+
+### Backward Compatibility
+
+- `generate_multicast_ip(unique_id)` without `radiod_host` produces identical results to v3.6.0.
+- `allocate_ssrc()` without `radiod_host` changes the hash format (trailing separator added), so SSRC values will differ from v3.6.0 for existing deployments. This is intentional — channels will be re-created with new SSRCs on upgrade. The old SSRCs were not radiod-aware and could collide when a client talked to multiple radiod instances.
+- `ManagedStream`, `RadiodStream`, and `RTPRecorder` require no changes — they receive the already-computed SSRC/address via `ChannelInfo`.
+
+---
+
+## [3.6.0] - 2026-04-09
+
+### Added
+
+- **L6 BPSK PPS chain-delay calibration** (`ka9q/pps_calibrator.py`): New utility module for measuring end-to-end RF-to-RTP chain delay using a local GPS-disciplined BPSK PPS injector (WB6CXC design). Three new public classes:
+  - `BpskPpsCalibrator` — detects PPS edges in BPSK IQ streams via phase-transition detection, validates timing consistency, and reports the measured chain delay once locked. Algorithm ported from Scott Newell's wd-record.c `bpsk_state_machine()`.
+  - `PpsCalibrationResult` — dataclass returned by the calibrator with `chain_delay_ns`, `chain_delay_samples`, edge counters, and lock status.
+  - `NotchFilter500Hz` — biquad IIR notch filter at 500 Hz for interference rejection on the BPSK channel.
+- **`ChannelInfo.chain_delay_correction_ns`** (`ka9q/discovery.py`): New optional field. When set, `rtp_to_wallclock()` automatically subtracts this correction from the computed wall time, compensating for the measured RF/ADC/DSP/RTP chain latency. Defaults to `None` (no correction; backward compatible).
+- All three new classes exported from `ka9q/__init__.py`.
+
+### Changed
+
+- **`rtp_to_wallclock()`** (`ka9q/rtp_recorder.py`): Now applies `channel.chain_delay_correction_ns` when present. Existing callers are unaffected (the field defaults to `None`).
+
+---
+
+## [3.5.1] - 2026-04-09
+
+### Added
+
+- **`DemodType` enum** (`ka9q/types.py`): New auto-generated class mirroring `enum demod_type` from ka9q-radio `radio.h`. Exposes `LINEAR_DEMOD`, `FM_DEMOD`, `WFM_DEMOD`, `SPECT_DEMOD`, `SPECT2_DEMOD`, and `N_DEMOD`.
+- **`WindowType` enum** (`ka9q/types.py`): New auto-generated class mirroring `enum window_type` from ka9q-radio `window.h`. Exposes all 9 FFT window types (`KAISER_WINDOW` through `HP5FT_WINDOW`) plus `N_WINDOW` sentinel.
+- Both new types are exported from `ka9q/__init__.py` and tracked by the drift detection system.
+
+### Fixed
+
+- **`set_demod_type()` validation**: Was rejecting demod_type=4 (`SPECT2_DEMOD`), the spectrum v2 mode added in ka9q-radio. Validation range corrected from 0-3 to 0-4.
+
+### Changed
+
+- **`sync_types.py` expanded**: Now parses 4 C headers (`status.h`, `rtp.h`, `radio.h`, `window.h`) instead of 2. Drift detection covers `DemodType` and `WindowType` in addition to `StatusType` and `Encoding`. The `_check_enum()` helper replaces duplicated per-enum comparison logic.
+- **Compatibility pin bumped** to ka9q-radio `d39fea8` (no protocol-level changes from previous pin `6b0fec7`; intervening commits were wd-record and bug fixes).
+
+---
+
+## [3.5.0] - 2026-03-31
+
+### Added
+
+- **Protocol Drift Detection** (`scripts/sync_types.py`): New tool that code-generates `ka9q/types.py` from the ka9q-radio C headers (`status.h`, `rtp.h`). Three modes:
+  - `--check`: exits non-zero if `types.py` is out of sync (for CI and tests)
+  - `--apply`: regenerates `types.py` and updates compatibility pins
+  - `--diff`: dry-run showing what would change
+- **Compatibility Pin** (`ka9q_radio_compat`): Tracked plain-text file recording the ka9q-radio commit hash that `types.py` was last validated against.
+- **Importable Pin** (`ka9q/compat.py`): `KA9Q_RADIO_COMMIT` constant for use by deployment tooling (e.g. `ka9q-update`).
+- **Drift Test** (`tests/test_protocol_compat.py`): Pytest test that runs `sync_types.py --check` and verifies the pin matches ka9q-radio HEAD. Auto-skips when ka9q-radio source is not present.
+- **New StatusType**: `SPECTRUM_OVERLAP` (116) for FFT window overlap control.
+- **New Encodings**: `MULAW` (10), `ALAW` (11) for telephony-grade audio.
+- **`set_max_delay()`**: New control method replacing `set_packet_buffering()`. Sets maximum aggregation delay in blocks (0-5).
+
+### Changed
+
+- **StatusType renames** (matching ka9q-radio HEAD):
+  - `MINPACKET` → `MAXDELAY`
+  - `GAINSTEP` → `UNUSED4`
+  - `CONVERTER_OFFSET` → `UNUSED3`
+  - `COHERENT_BIN_SPACING` → `UNUSED2`
+  - `BLOCKS_SINCE_POLL` → `UNUSED`
+- **Encoding**: `UNUSED_ENCODING` sentinel shifted from 10 to 12.
+- `types.py` is now auto-generated with C header comments preserved.
+
+### Removed
+
+- `compare_encodings.py` and `compare_status_types.py` (replaced by `scripts/sync_types.py`).
+
+### Backward Compatibility
+
+- `set_packet_buffering()` retained as a deprecated alias for `set_max_delay()`.
+- `Encoding.F32` and `Encoding.F16` aliases retained for `F32LE` and `F16LE`.
+
+---
+
+## [3.4.2] - 2026-02-05
+
+### Added
+
+- **Comprehensive Getting Started Guide**: Added a new `docs/GETTING_STARTED.md` file. This guide provides a step-by-step tutorial for new users, covering installation, a simple first program, core concepts, and troubleshooting tips. It is now the recommended entry point for new users.
+- **Examples README**: Added a new `examples/README.md` file to organize the examples directory. It categorizes examples by complexity (basic, intermediate, advanced) and provides a recommended learning path, making it easier for users to find relevant examples.
+
+### Fixed
+
+- **`stream_example.py` Bug**: Fixed a critical bug in `examples/stream_example.py` where the code incorrectly iterated over the dictionary returned by `discover_channels`. The example now correctly accesses `ChannelInfo` objects, preventing an `AttributeError` and allowing the example to run as intended.
+
+### Changed
+
+- **Updated API Documentation**: The documentation for `create_channel` in `docs/API_REFERENCE.md` has been updated to match the actual implementation. This includes adding the `destination` and `encoding` parameters, correcting the parameter order, and documenting the return type (`int` SSRC).
+- **Updated README**: The main `README.md` has been updated to link to the new Getting Started guide.
+
+---
+
+## [3.4.1] - 2026-01-27
+
+### Fixed
+
+- **Stable SSRC Allocation**: Replaced unstable Python `hash()` with `hashlib.sha256` in `allocate_ssrc()`. This ensure SSRCs remain consistent across process restarts, allowing `radiod` to reuse existing receivers and preventing resource exhaustion.
+
+## [3.4.0] - 2026-01-13
+
+### Added
+
+- **TTL Reporting**: Implemented decoding of `OUTPUT_TTL` (status type 19) from `radiod`.
+- **TTL Warning**: Added a warning log when `radiod` reports a TTL of 0, indicating multicast restrictions.
+- **Web API**: Exposed the `ttl` value in the `/api/channel/<address>/<ssrc>` endpoint.
+- **Tests**: Added unit and integration tests for TTL decoding and warning logic.
+
+### Fixed
+
+- **Web UI Start Script**: Fixed `webui/start.sh` to correctly locate `app.py` when running from outside the `webui` directory.
+
+## [3.2.7] - 2025-12-17
+
+### Added
+
+- **ChannelMonitor**: New service that provides automatic recovery from `radiod` restarts. It monitors registered channels and automatically invokes `ensure_channel` to restore them if they disappear.
+  - Usage: `monitor = ChannelMonitor(control); monitor.start(); monitor.monitor_channel(...)`
+
+## [3.2.6] - 2025-12-17
+
+### Added
+
+- **Output Encoding Support**: Added complete support for specifying output encoding (e.g., F32, S16LE, OPUS) in `ensure_channel` and `create_channel`.
+  - `create_channel` now automatically sends the required follow-up `OUTPUT_ENCODING` command to `radiod`.
+  - `ensure_channel` verifies the encoding of existing channels and reconfigures them if different from the requested encoding.
+  - `ChannelInfo` now includes the `encoding` field for discovered channels.
+
+## [3.2.5] - 2025-12-17
+
+### Added
+
+- **Destination-Aware Channels**: `ka9q-python` now supports unique destination IP addresses per client application. The `ensure_channel` and `create_channel` methods now accept a `destination` parameter.
+- **Unique IP Generation**: Added `generate_multicast_ip(unique_id)` helper function to deterministically map application IDs to the `239.0.0.0/8` multicast range.
+- **Improved SSRC Allocation**: `allocate_ssrc` now includes the destination address in its hash calculation, ensuring that streams with different destinations get unique SSRCs.
+
+## [3.2.4] - 2025-12-16
+
+### Fixed
+
+- **Resequencer Fragmented IQ Support** - Fixed resequencer to correctly handle fragmented IQ packets from radiod. The resequencer now uses actual packet sample count for timestamp tracking instead of the fixed `samples_per_packet` value. This prevents false gap detection when radiod fragments large IQ payloads (e.g., IQ 20kHz F32 fragments into 1440+1440+320 byte packets). Affects `_try_output()`, `_handle_lost_packet()`, and `flush()` methods.
+
+### Added
+
+- **Channel Verification Test Suite** - Comprehensive test suite (`tests/test_channel_verification.py`) that verifies radiod channel creation, encoding, sample rate, and destination configuration. Demonstrates ka9q-python usage patterns and serves as integration test.
+
+## [3.2.3] - 2025-12-16
+
+### Fixed
+
+- **Socket Reconnection Vulnerability** - Fixed vulnerability where socket errors would terminate the receive loop permanently. Both `RadiodStream` and `RTPRecorder` now implement automatic reconnection with exponential backoff (1s to 60s max). This provides robustness against network interface restarts, multicast group membership drops, and transient network errors.
+
+## [3.2.2] - 2025-12-13
+
+### Fixed
+
+- **Time Calculation** - Fixed 18-second error in UTC timestamp calculation caused by leap seconds. `rtp_to_wallclock()` now correctly subtracts the current 18-second GPS-UTC offset.
+
+## [3.2.1] - 2025-12-11
+
+### Fixed
+
+- **Time Calculation** - Fixed GPS-to-Unix time conversion in `rtp_to_wallclock()`. Previous formula incorrectly applied NTP epoch offset, resulting in future timestamps.
+- **Documentation** - Updated `RTP_TIMING_SUPPORT.md` with the correct formula.
+
+## [3.2.0] - 2025-12-01
+
+### 🌊 RadiodStream API - Continuous Sample Delivery with Quality Tracking
+
+This release adds a high-level streaming API that delivers continuous sample streams with comprehensive quality metadata. Designed for applications like GRAPE, WSPR, CODAR, and SuperDARN that need reliable data capture with gap detection and quality metrics.
+
+### Added
+
+**Stream Module (`ka9q.stream`):**
+
+- `RadiodStream` - High-level sample stream with automatic resequencing and gap filling
+  - Callback-based delivery: `on_samples(samples: np.ndarray, quality: StreamQuality)`
+  - Handles IQ and audio modes automatically
+  - Cross-platform multicast support (Linux, macOS, Windows)
+
+**Quality Tracking (`ka9q.stream_quality`):**
+
+- `StreamQuality` - Comprehensive quality metrics per batch and cumulative
+  - `completeness_pct` - Percentage of expected samples received
+  - `total_gap_events` / `total_gaps_filled` - Gap statistics
+  - RTP packet metrics: received, lost, duplicate, resequenced
+  - RTP timestamps: `first_rtp_timestamp`, `last_rtp_timestamp` for precise timing
+- `GapEvent` - Individual gap details (position, duration, source)
+- `GapSource` - Gap type classification (NETWORK_LOSS, RESEQUENCE_TIMEOUT, EMPTY_PAYLOAD, etc.)
+
+**Resequencer (`ka9q.resequencer`):**
+
+- `PacketResequencer` - Circular buffer resequencing with gap detection
+  - Handles out-of-order packet delivery
+  - KA9Q-style signed 32-bit timestamp arithmetic for wrap handling
+  - Zero-fills gaps for continuous stream integrity
+- `RTPPacket` - Packet data structure with samples
+- `ResequencerStats` - Resequencing statistics
+
+**Examples:**
+
+- `examples/stream_example.py` - Basic streaming demonstration
+- `examples/grape_integration_example.py` - Two-phase recording pattern (startup buffer → recording)
+
+### Example Usage
+
+```python
+from ka9q import RadiodStream, StreamQuality, discover_channels
+
+def on_samples(samples, quality: StreamQuality):
+    print(f"Got {len(samples)} samples, {quality.completeness_pct:.1f}% complete")
+    for gap in quality.batch_gaps:
+        print(f"  Gap: {gap.source.value}, {gap.duration_samples} samples")
+
+channels = discover_channels('radiod.local')
+stream = RadiodStream(
+    channel=channels[10000000],
+    on_samples=on_samples,
+    samples_per_packet=320,  # RTP timestamp increment at 16kHz
+)
+stream.start()
+# ... run until done ...
+final_quality = stream.stop()
+```
+
+### Architecture
+
+```
+radiod → Multicast → RadiodStream → PacketResequencer → App Callback
+                          ↓
+                    StreamQuality (per batch + cumulative)
+```
+
+**Core delivers:**
+
+- Continuous sample stream (gaps zero-filled)
+- Quality metadata with every callback
+
+**Applications handle:**
+
+- Segmentation (1-minute NPZ, 2-minute WAV, etc.)
+- Format conversion
+- App-specific gap classification (cadence_fill, late_start, etc.)
+
+---
+
+## [3.1.0] - 2025-12-01
+
+### 🎯 SSRC Abstraction - SSRC-Free Channel Creation
+
+This release removes SSRC from the application concern. Applications now specify **what they want** (frequency, mode, sample rate) and the system handles SSRC allocation internally.
+
+### Added
+
+**SSRC Allocation:**
+
+- `allocate_ssrc(frequency_hz, preset, sample_rate, agc, gain)` - Deterministic SSRC allocation from channel parameters. Same parameters always produce the same SSRC, enabling stream sharing across applications.
+
+**SSRC-Free `create_channel()`:**
+
+- `ssrc` parameter is now **optional** (moved to end of parameters)
+- When omitted, SSRC is auto-allocated using `allocate_ssrc()`
+- Method now **returns the SSRC** (useful when auto-allocated)
+
+### Changed
+
+- `create_channel()` signature: `frequency_hz` is now the first (required) parameter
+- `create_channel()` now returns `int` (the SSRC) instead of `None`
+
+### Cross-Library Compatibility
+
+The SSRC allocation algorithm matches signal-recorder's `StreamSpec.ssrc_hash()`:
+
+```python
+key = (round(frequency_hz), preset.lower(), sample_rate, agc, round(gain, 1))
+return hash(key) & 0x7FFFFFFF
+```
+
+This ensures:
+
+- Same parameters → same SSRC in both ka9q-python and signal-recorder
+- Stream sharing works across applications using either library
+- Deterministic allocation for coordination
+
+### Example
+
+```python
+from ka9q import RadiodControl, allocate_ssrc
+
+# SSRC-free API (recommended)
+with RadiodControl("radiod.local") as control:
+    ssrc = control.create_channel(
+        frequency_hz=14.074e6,
+        preset="usb",
+        sample_rate=12000
+    )
+    print(f"Created channel with SSRC: {ssrc}")
+
+# Or use allocate_ssrc() directly for coordination
+ssrc = allocate_ssrc(10.0e6, "iq", 16000)
+```
+
+---
+
+## [3.0.0] - 2025-12-01
+
+### 🎉 Major Release: Complete RadioD Feature Exposure
+
+This major release exposes **all remaining radiod features** through the Python interface, providing comprehensive control over every aspect of ka9q-radio operation.
+
+### Added - 20 New Control Methods
+
+**Tracking & Tuning:**
+
+- `set_doppler(ssrc, doppler_hz, doppler_rate_hz_per_sec)` - Doppler frequency shift and rate for satellite tracking
+- `set_first_lo(ssrc, frequency_hz)` - Direct hardware tuner frequency control
+
+**Signal Processing:**
+
+- `set_pll(ssrc, enable, bandwidth_hz, square)` - Phase-locked loop configuration for carrier tracking
+- `set_squelch(ssrc, enable, open_snr_db, close_snr_db)` - SNR-based squelch with hysteresis
+- `set_envelope_detection(ssrc, enable)` - Toggle between envelope (AM) and synchronous detection
+- `set_independent_sideband(ssrc, enable)` - ISB mode (USB/LSB to separate L/R channels)
+- `set_fm_threshold_extension(ssrc, enable)` - Improve FM reception at weak signal levels
+
+**AGC & Levels:**
+
+- `set_agc_threshold(ssrc, threshold_db)` - Set AGC activation threshold above noise floor
+
+**Output Control:**
+
+- `set_output_channels(ssrc, channels)` - Configure mono (1) or stereo (2) output
+- `set_output_encoding(ssrc, encoding)` - Select output format (S16BE, S16LE, F32, F16, OPUS)
+- `set_opus_bitrate(ssrc, bitrate)` - Configure Opus encoder bitrate (0=auto, typical 32000-128000)
+- `set_packet_buffering(ssrc, min_blocks)` - Control RTP packet buffering (0-4 blocks)
+- `set_destination(ssrc, address, port)` - Change RTP output multicast destination
+
+**Filtering:**
+
+- `set_filter2(ssrc, blocksize, kaiser_beta)` - Configure secondary filter for additional selectivity
+
+**Spectrum Analysis:**
+
+- `set_spectrum(ssrc, bin_bw_hz, bin_count, crossover_hz, kaiser_beta)` - Configure spectrum analyzer parameters
+
+**System Control:**
+
+- `set_status_interval(ssrc, interval)` - Set automatic status reporting rate
+- `set_demod_type(ssrc, demod_type)` - Switch demodulator type (LINEAR/FM/WFM/SPECTRUM)
+- `set_rf_gain(ssrc, gain_db)` - Control RF front-end gain (hardware-dependent)
+- `set_rf_attenuation(ssrc, atten_db)` - Control RF front-end attenuation (hardware-dependent)
+- `set_options(ssrc, set_bits, clear_bits)` - Set/clear experimental option bits
+
+### Updated - Type Definitions
+
+Fixed `StatusType` constants in `ka9q/types.py`:
+
+- `SPECTRUM_FFT_N = 76` (was UNUSED16)
+- `SPECTRUM_KAISER_BETA = 91` (was UNUSED20)
+- `CROSSOVER = 95` (was UNUSED21)
+
+### Documentation
+
+**New Documentation Files:**
+
+- `NEW_FEATURES.md` - Comprehensive documentation of all 20 new features with examples
+- `QUICK_REFERENCE.md` - Quick reference guide with practical code examples
+- `RADIOD_FEATURES_SUMMARY.md` - Complete implementation summary and verification
+- `examples/advanced_features_demo.py` - Working demonstration script
+
+### Feature Coverage
+
+This release provides complete coverage of radiod's TLV command set:
+
+- ✅ All 35+ radiod TLV commands now supported
+- ✅ Doppler tracking for satellite reception
+- ✅ PLL carrier tracking for coherent detection
+- ✅ SNR squelch with hysteresis
+- ✅ Independent sideband (ISB) mode
+- ✅ FM threshold extension
+- ✅ Secondary filtering
+- ✅ Spectrum analyzer configuration
+- ✅ Output encoding selection
+- ✅ RF hardware controls
+- ✅ Experimental option bits
+
+### Use Cases Enabled
+
+**Satellite Communications:**
+
+```python
+control.set_doppler(ssrc=12345, doppler_hz=-5000, doppler_rate_hz_per_sec=100)
+```
+
+**Coherent AM Reception:**
+
+```python
+control.set_pll(ssrc=12345, enable=True, bandwidth_hz=50)
+control.set_envelope_detection(ssrc=12345, enable=False)
+```
+
+**Independent Sideband:**
+
+```python
+control.set_independent_sideband(ssrc=12345, enable=True)
+control.set_output_channels(ssrc=12345, channels=2)
+```
+
+**Opus Audio Streaming:**
+
+```python
+control.set_output_encoding(ssrc=12345, encoding=Encoding.OPUS)
+control.set_opus_bitrate(ssrc=12345, bitrate=64000)
+```
+
+**Spectrum Analysis:**
+
+```python
+control.set_spectrum(ssrc=12345, bin_bw_hz=100, bin_count=512)
+```
+
+### Breaking Changes
+
+⚠️ **None** - This release is 100% backward compatible. All existing code will continue to work without modification.
+
+### Implementation Details
+
+- All new methods follow existing design patterns
+- Comprehensive input validation with clear error messages
+- Full logging support for debugging
+- Proper docstrings with examples for all methods
+- Thread-safe operation via existing infrastructure
+- ~400 lines of new, tested code
+
+### Verification
+
+✅ All code compiles successfully  
+✅ All imports validated  
+✅ 20 new methods confirmed available  
+✅ Pattern consistency verified  
+✅ Documentation complete
+
+### Migration Guide
+
+No migration needed - all changes are additive. Simply update to v3.0.0 and start using the new features as needed.
+
+For examples, see:
+
+- `NEW_FEATURES.md` for detailed feature documentation
+- `QUICK_REFERENCE.md` for quick code examples
+- `examples/advanced_features_demo.py` for working demonstrations
+
+---
+
+## [2.5.0] - 2025-11-30
+
+### Added - RTP Recorder Enhancement
+
+- **`pass_all_packets` parameter** in `RTPRecorder.__init__()`
+  - Allows bypassing internal packet resequencing logic
+  - When `True`, passes ALL packets to callback regardless of sequence gaps
+  - Metrics still track sequence errors, dropped packets, and timestamp jumps
+  - Designed for applications with external resequencers (e.g., signal-recorder's PacketResequencer)
+  - `max_packet_gap` parameter ignored when `pass_all_packets=True`
+  - No resync state transitions - stays in RECORDING mode continuously
+
+- **Updated `_validate_packet()` method** in `RTPRecorder`
+  - Conditional resync triggering based on `pass_all_packets` flag
+  - Metrics tracking independent of pass-through mode
+  - Early return for pass-all mode to bypass resync state handling
+  - Preserves original behavior when `pass_all_packets=False` (default)
+
+### Documentation
+
+- **API Reference** - Added `pass_all_packets` parameter documentation
+  - Added example showing external resequencer usage
+  - Updated parameter descriptions
+
+- **Implementation Guide** - Usage patterns for external resequencing
+
+### Backward Compatibility
+
+100% backward compatible - `pass_all_packets` defaults to `False`, preserving existing behavior.
+
+---
+
+## [2.4.0] - 2025-11-29
+
+### Added - RTP Destination Control
+
+- **`encode_socket()` function** in `ka9q/control.py`
+  - Encodes IPv4 socket addresses in radiod's TLV format (6-byte format)
+  - Validates IP addresses and port numbers
+  - Matches radiod's `decode_socket()` expectations exactly
+
+- **`_validate_multicast_address()` function** in `ka9q/control.py`
+  - Validates multicast address format (IP or hostname)
+  - Allows both IP addresses and DNS names
+
+- **`destination` parameter** to `create_channel()` method
+  - Accepts format: "address" or "address:port"
+  - Examples: "239.1.2.3", "wspr.local", "239.1.2.3:5004"
+  - Enables per-channel RTP destination control
+
+- **Full `destination` support** in `tune()` method
+  - Removed "not implemented" warning
+  - Properly encodes destination socket addresses
+  - Supports port specification (defaults to 5004)
+
+- **Comprehensive documentation**:
+  - `RTP_DESTINATION_FEATURE.md` - Feature documentation with examples
+  - `CONTROL_COMPARISON.md` - Command-by-command comparison with control.c
+  - `IMPLEMENTATION_STATUS.md` - Complete status of ka9q-python vs control/tune
+  - `WEBUI_SUMMARY.md` - Web UI implementation details
+
+- **Test suite** for socket encoding
+  - `tests/test_encode_socket.py` - Comprehensive tests for encode_socket()
+  - Tests roundtrip encoding/decoding
+  - Tests error handling and validation
+
+### Added - Web UI
+
+- **Complete web-based control interface** (`webui/` directory)
+  - `webui/app.py` - Flask backend with REST API
+  - `webui/templates/index.html` - Modern responsive UI
+  - `webui/static/style.css` - Dark theme styling
+  - `webui/static/app.js` - Frontend logic with auto-refresh
+  - `webui/start.sh` - Quick start script
+  - `webui/requirements.txt` - Python dependencies
+  - `webui/README.md` - Complete usage documentation
+
+- **Web UI Features**:
+  - Auto-discovery of radiod instances on LAN
+  - Pull-down selector for radiod instances
+  - Channel list with frequency, mode, sample rate, destination
+  - Real-time channel monitoring (1-second auto-refresh)
+  - 4-column layout: Tuning, Filter, Output, Signal
+  - Full-width Gain & AGC section
+  - Live SNR, baseband power, noise density
+  - Error handling with auto-stop after 3 consecutive failures
+  - Responsive design (desktop, tablet, mobile)
+  - No framework dependencies (vanilla JavaScript)
+
+- **Web UI API Endpoints**:
+  - `GET /api/discover` - Discover radiod instances
+  - `GET /api/channels/<address>` - List channels
+  - `GET /api/channel/<address>/<ssrc>` - Get channel status
+  - `POST /api/tune/<address>/<ssrc>` - Tune channel
+
+### Fixed
+
+- **Deduplication** in `discover_radiod_services()`
+  - Uses dict with address as key to remove duplicates
+  - Sorts results by name for consistency
+  - Fixes multiple entries from avahi-browse (IPv4/IPv6, multiple interfaces)
+
+- **Timeout handling** in web UI
+  - Increased backend timeout from 2s to 10s
+  - Added consecutive error tracking (stops after 3 failures)
+  - Better error messages for inactive channels
+  - Prevents refresh interval overlap
+
+- **Channel selection** in web UI
+  - Fixed bouncing between multiple channels
+  - Only one channel refreshes at a time
+  - Proper cleanup when switching channels
+  - Added `isRefreshing` flag to prevent race conditions
+
+### Changed
+
+- **Control comparison** - Documented 52.5% coverage of control.c commands
+  - 21 commands fully implemented (all core functionality)
+  - 19 advanced commands not yet implemented (PLL, squelch, etc.)
+  - 100% coverage of tune.c commands
+
+- **Implementation status** - Confirmed ka9q-python is production-ready
+  - Complete frequency control
+  - Complete mode/preset control
+  - Complete filter control (including Kaiser beta)
+  - Complete AGC control (all 5 parameters)
+  - Complete gain control (manual, RF gain, RF atten)
+  - Complete output control (sample rate, encoding, destination)
+  - Complete status interrogation
+
+## Summary of Changes
+
+This release adds:
+
+1. **Per-channel RTP destination control** - Clients can now specify unique RTP destinations for each channel
+2. **Web UI** - Modern browser-based interface for monitoring and controlling radiod
+3. **Better discovery** - Deduplicated radiod instance discovery
+4. **Comprehensive documentation** - Full comparison with control.c and implementation status
+
+### Files Modified
+
+- `ka9q/control.py` - Added encode_socket(), updated tune() and create_channel()
+- `ka9q/discovery.py` - Fixed deduplication in discover_radiod_services()
+- `tests/test_encode_socket.py` - New test suite
+
+### Files Added
+
+- `webui/` - Complete web UI implementation (7 files)
+- `RTP_DESTINATION_FEATURE.md` - Feature documentation
+- `CONTROL_COMPARISON.md` - Command comparison
+- `IMPLEMENTATION_STATUS.md` - Implementation status
+- `WEBUI_SUMMARY.md` - Web UI documentation
+- `CHANGELOG.md` - This file
+
+### Backward Compatibility
+
+All changes are backward compatible. Existing code continues to work without modification.
+The `destination` parameter is optional in both `create_channel()` and `tune()`.

{ka9q_python-3.4.2 → ka9q_python-3.7.0}/MANIFEST.in

@@ -1,12 +1,14 @@
 # Include documentation
 include README.md
 include LICENSE
-include SUMMARY.md
-include TUNE_IMPLEMENTATION.md
-include NATIVE_DISCOVERY.md
-include CROSS_PLATFORM_SUPPORT.md
-include TEST_RESULTS.md
-include TESTING_SUMMARY.md
+include CHANGELOG.md
+include RELEASE_NOTES_v3.5.0.md
+
+# Include protocol compatibility pin
+include ka9q_radio_compat
+
+# Include sync tooling
+recursive-include scripts *.py
 
 # Include examples
 recursive-include examples *.py
@@ -14,6 +16,9 @@ recursive-include examples *.py
 # Include tests
 recursive-include tests *.py
 
+# Include docs
+recursive-include docs *.md
+
 # Exclude compiled files
 global-exclude *.pyc
 global-exclude __pycache__