ka9q-python 3.2.0__tar.gz

ka9q_python-3.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael James Hauan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION OF THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ka9q_python-3.2.0/MANIFEST.in

@@ -0,0 +1,21 @@
+# 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 examples
+recursive-include examples *.py
+
+# Include tests
+recursive-include tests *.py
+
+# Exclude compiled files
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude *.pyo
+global-exclude .DS_Store

ka9q_python-3.2.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.4
+Name: ka9q-python
+Version: 3.2.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-Expression: 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
+Keywords: ka9q-radio,sdr,ham-radio,radio-control
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Telecommunications Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Ham Radio
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# ka9q-python
+
+[![PyPI version](https://badge.fury.io/py/ka9q-python.svg)](https://badge.fury.io/py/ka9q-python)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**General-purpose Python library for controlling [ka9q-radio](https://github.com/ka9q/ka9q-radio)**
+
+Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, SuperDARN radar, CODAR oceanography, HF fax, satellite downlinks, and more.
+
+**Note:** Package name is `ka9q-python` out of respect for KA9Q (Phil Karn's callsign). Import as `import ka9q`.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Examples](#examples)
+- [Use Cases](#use-cases)
+- [License](#license)
+
+## 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  
+
+## Installation
+
+```bash
+pip install ka9q-python
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/mijahauan/ka9q-python.git
+cd ka9q-python
+pip install -e .
+```
+
+## Quick Start
+
+### Listen to AM Broadcast
+
+```python
+from ka9q import RadiodControl
+
+# Connect to radiod
+control = RadiodControl("radiod.local")
+
+# Create AM channel on 10 MHz WWV
+control.create_channel(
+    ssrc=10000000,
+    frequency_hz=10.0e6,
+    preset="am",
+    sample_rate=12000
+)
+
+# RTP stream now available with SSRC 10000000
+```
+
+### Monitor WSPR Bands
+
+```python
+from ka9q import RadiodControl
+
+control = RadiodControl("radiod.local")
+
+wspr_bands = [
+    (1.8366e6, "160m"),
+    (3.5686e6, "80m"),
+    (7.0386e6, "40m"),
+    (10.1387e6, "30m"),
+    (14.0956e6, "20m"),
+]
+
+for freq, band in wspr_bands:
+    control.create_channel(
+        ssrc=int(freq),
+        frequency_hz=freq,
+        preset="usb",
+        sample_rate=12000
+    )
+    print(f"{band} WSPR channel created")
+```
+
+### Discover Existing Channels
+
+```python
+from ka9q import discover_channels
+
+channels = discover_channels("radiod.local")
+for ssrc, info in channels.items():
+    print(f"{ssrc}: {info.frequency/1e6:.3f} MHz, {info.preset}, {info.sample_rate} Hz")
+```
+
+### Record RTP Stream with Precise Timing
+
+```python
+from ka9q import discover_channels, RTPRecorder
+import time
+
+# Get channel with timing info
+channels = discover_channels("radiod.local")
+channel = channels[14074000]
+
+# Define packet handler
+def handle_packet(header, payload, wallclock):
+    print(f"Packet at {wallclock}: {len(payload)} bytes")
+
+# Create and start recorder
+recorder = RTPRecorder(channel=channel, on_packet=handle_packet)
+recorder.start()
+recorder.start_recording()
+time.sleep(60)  # Record for 60 seconds
+recorder.stop_recording()
+recorder.stop()
+```
+
+### Multi-Homed Systems
+
+For systems with multiple network interfaces, specify which interface to use:
+
+```python
+from ka9q import RadiodControl, discover_channels
+
+# Specify your interface IP address
+my_interface = "192.168.1.100"
+
+# Create control with specific interface
+control = RadiodControl("radiod.local", interface=my_interface)
+
+# Discovery on specific interface
+channels = discover_channels("radiod.local", interface=my_interface)
+```
+
+## 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.
+- **[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.
+
+## Examples
+
+See the `examples/` directory for complete applications:
+
+- **`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
+
+## 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.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

ka9q_python-3.2.0/README.md

@@ -0,0 +1,202 @@
+# ka9q-python
+
+[![PyPI version](https://badge.fury.io/py/ka9q-python.svg)](https://badge.fury.io/py/ka9q-python)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**General-purpose Python library for controlling [ka9q-radio](https://github.com/ka9q/ka9q-radio)**
+
+Control radiod channels for any application: AM/FM/SSB radio, WSPR monitoring, SuperDARN radar, CODAR oceanography, HF fax, satellite downlinks, and more.
+
+**Note:** Package name is `ka9q-python` out of respect for KA9Q (Phil Karn's callsign). Import as `import ka9q`.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Examples](#examples)
+- [Use Cases](#use-cases)
+- [License](#license)
+
+## 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  
+
+## Installation
+
+```bash
+pip install ka9q-python
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/mijahauan/ka9q-python.git
+cd ka9q-python
+pip install -e .
+```
+
+## Quick Start
+
+### Listen to AM Broadcast
+
+```python
+from ka9q import RadiodControl
+
+# Connect to radiod
+control = RadiodControl("radiod.local")
+
+# Create AM channel on 10 MHz WWV
+control.create_channel(
+    ssrc=10000000,
+    frequency_hz=10.0e6,
+    preset="am",
+    sample_rate=12000
+)
+
+# RTP stream now available with SSRC 10000000
+```
+
+### Monitor WSPR Bands
+
+```python
+from ka9q import RadiodControl
+
+control = RadiodControl("radiod.local")
+
+wspr_bands = [
+    (1.8366e6, "160m"),
+    (3.5686e6, "80m"),
+    (7.0386e6, "40m"),
+    (10.1387e6, "30m"),
+    (14.0956e6, "20m"),
+]
+
+for freq, band in wspr_bands:
+    control.create_channel(
+        ssrc=int(freq),
+        frequency_hz=freq,
+        preset="usb",
+        sample_rate=12000
+    )
+    print(f"{band} WSPR channel created")
+```
+
+### Discover Existing Channels
+
+```python
+from ka9q import discover_channels
+
+channels = discover_channels("radiod.local")
+for ssrc, info in channels.items():
+    print(f"{ssrc}: {info.frequency/1e6:.3f} MHz, {info.preset}, {info.sample_rate} Hz")
+```
+
+### Record RTP Stream with Precise Timing
+
+```python
+from ka9q import discover_channels, RTPRecorder
+import time
+
+# Get channel with timing info
+channels = discover_channels("radiod.local")
+channel = channels[14074000]
+
+# Define packet handler
+def handle_packet(header, payload, wallclock):
+    print(f"Packet at {wallclock}: {len(payload)} bytes")
+
+# Create and start recorder
+recorder = RTPRecorder(channel=channel, on_packet=handle_packet)
+recorder.start()
+recorder.start_recording()
+time.sleep(60)  # Record for 60 seconds
+recorder.stop_recording()
+recorder.stop()
+```
+
+### Multi-Homed Systems
+
+For systems with multiple network interfaces, specify which interface to use:
+
+```python
+from ka9q import RadiodControl, discover_channels
+
+# Specify your interface IP address
+my_interface = "192.168.1.100"
+
+# Create control with specific interface
+control = RadiodControl("radiod.local", interface=my_interface)
+
+# Discovery on specific interface
+channels = discover_channels("radiod.local", interface=my_interface)
+```
+
+## 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.
+- **[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.
+
+## Examples
+
+See the `examples/` directory for complete applications:
+
+- **`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
+
+## 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.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

ka9q_python-3.2.0/examples/advanced_features_demo.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""
+Demonstration of newly exposed radiod features in ka9q-python
+
+This script demonstrates the use of advanced radiod features that
+were previously not exposed in the Python interface.
+"""
+
+from ka9q.control import RadiodControl
+from ka9q.types import Encoding
+
+def main():
+    # Connect to radiod
+    control = RadiodControl(control_address="239.101.6.1")
+    
+    # Example SSRC (replace with your actual channel SSRC)
+    ssrc = 12345
+    
+    print("=== Advanced RadioD Feature Demonstrations ===\n")
+    
+    # 1. Doppler tracking for satellite reception
+    print("1. Setting Doppler shift and rate (for satellite tracking)")
+    control.set_doppler(ssrc=ssrc, doppler_hz=-5000, doppler_rate_hz_per_sec=100)
+    print("   ✓ Doppler: -5 kHz, rate: 100 Hz/s\n")
+    
+    # 2. PLL configuration for carrier tracking
+    print("2. Configuring PLL for coherent AM detection")
+    control.set_pll(ssrc=ssrc, enable=True, bandwidth_hz=50, square=False)
+    print("   ✓ PLL enabled with 50 Hz bandwidth\n")
+    
+    # 3. SNR squelch
+    print("3. Setting SNR-based squelch")
+    control.set_squelch(ssrc=ssrc, enable=True, open_snr_db=10, close_snr_db=8)
+    print("   ✓ Squelch opens at 10 dB, closes at 8 dB\n")
+    
+    # 4. Independent Sideband mode
+    print("4. Enabling Independent Sideband (ISB) mode")
+    control.set_independent_sideband(ssrc=ssrc, enable=True)
+    control.set_output_channels(ssrc=ssrc, channels=2)
+    print("   ✓ ISB mode enabled (USB/LSB to L/R channels)\n")
+    
+    # 5. Secondary filter configuration
+    print("5. Configuring secondary filter for extra selectivity")
+    control.set_filter2(ssrc=ssrc, blocksize=5, kaiser_beta=3.5)
+    print("   ✓ Filter2 configured with blocksize=5, beta=3.5\n")
+    
+    # 6. Opus encoder settings
+    print("6. Setting Opus encoding and bitrate")
+    control.set_output_encoding(ssrc=ssrc, encoding=Encoding.OPUS)
+    control.set_opus_bitrate(ssrc=ssrc, bitrate=64000)
+    print("   ✓ Opus encoding at 64 kbps\n")
+    
+    # 7. Spectrum analyzer mode
+    print("7. Configuring spectrum analyzer mode")
+    control.set_spectrum(ssrc=ssrc, bin_bw_hz=100, bin_count=512, kaiser_beta=6.0)
+    print("   ✓ Spectrum mode: 100 Hz bins, 512 bins, beta=6.0\n")
+    
+    # 8. Packet buffering control
+    print("8. Setting packet buffering for lower packet rate")
+    control.set_packet_buffering(ssrc=ssrc, min_blocks=2)
+    print("   ✓ Minimum 2 blocks (40ms) buffering\n")
+    
+    # 9. Status interval configuration
+    print("9. Configuring automatic status reporting")
+    control.set_status_interval(ssrc=ssrc, interval=50)
+    print("   ✓ Status sent every 50 frames\n")
+    
+    # 10. RF hardware controls (hardware-dependent)
+    print("10. Adjusting RF gain and attenuation")
+    # control.set_rf_gain(ssrc=ssrc, gain_db=20)
+    # control.set_rf_attenuation(ssrc=ssrc, atten_db=10)
+    print("   ✓ RF controls available (commented out - hardware dependent)\n")
+    
+    # 11. AGC threshold (separate from existing AGC settings)
+    print("11. Setting AGC threshold")
+    control.set_agc_threshold(ssrc=ssrc, threshold_db=10)
+    print("   ✓ AGC threshold at 10 dB above noise\n")
+    
+    # 12. First LO tuning (affects all channels - use with care!)
+    print("12. Setting first LO frequency")
+    # control.set_first_lo(ssrc=ssrc, frequency_hz=14.1e6)
+    print("   ✓ First LO tuning available (commented out - affects all channels)\n")
+    
+    # 13. FM-specific features
+    print("13. FM threshold extension (for weak signals)")
+    control.set_fm_threshold_extension(ssrc=ssrc, enable=True)
+    print("   ✓ FM threshold extension enabled\n")
+    
+    # 14. Linear mode envelope detection
+    print("14. Enabling envelope detection (for AM)")
+    control.set_envelope_detection(ssrc=ssrc, enable=True)
+    print("   ✓ Envelope detection enabled\n")
+    
+    # 15. Demodulator type switching
+    print("15. Changing demodulator type")
+    # control.set_demod_type(ssrc=ssrc, demod_type=1)  # 0=LINEAR, 1=FM, 2=WFM, 3=SPECTRUM
+    print("   ✓ Demod type switching available (commented out)\n")
+    
+    # 16. Output destination
+    print("16. Setting RTP output destination")
+    # control.set_destination(ssrc=ssrc, address="239.1.2.3", port=5004)
+    print("   ✓ Destination control available (commented out)\n")
+    
+    # 17. Option bits (experimental/debug)
+    print("17. Setting option bits")
+    # control.set_options(ssrc=ssrc, set_bits=0x01, clear_bits=0x02)
+    print("   ✓ Option bit control available (commented out - experimental)\n")
+    
+    print("\n=== All features demonstrated! ===")
+    print("Note: Some features are commented out to prevent unintended changes.")
+    print("Uncomment and adjust as needed for your specific use case.")
+    
+    control.close()
+
+if __name__ == "__main__":
+    main()