Claude SDR Control -- AI-Powered Software Defined Radio

28-year dream realized: AI-powered aircraft tracking and radio decoding with PortaPack H2 + HackRF One

Overview

Claude SDR Control is an advanced software-defined radio system that combines PortaPack H2/HackRF One hardware with AI-driven automation. The system provides real-time aircraft tracking, FM radio playback, signal reconnaissance, and a modular architecture supporting 12 radio applications -- all controllable through a web dashboard.

Screenshots

Dashboard	ADS-B Tracking	Gateway

RDS Decoder	Weather Station	Recon Scanner

SubGHz	APRS-RX

Hardware Setup

Two PortaPack H2 devices running ADS-B tracking simultaneously, connected to a MacBook.

Features

Core Capabilities

Live ADS-B Aircraft Tracking -- Real-time aircraft monitoring with position data, flight paths, and animated replay
FM Radio -- Tune and listen to FM broadcast stations (87.5-108 MHz) directly in the browser
HackRF Gateway -- Direct USB IQ streaming from HackRF One with multi-client WebSocket access
Serial Gateway -- Multi-client WebSocket access to PortaPack H2 serial console
7 IQ Decoders -- Real-time signal processing pipelines for ADS-B, RDS, Weather, SubGHz, APRS, Recon, and FM Audio

Advanced Features

AI-Powered Control -- Claude Code integration for intelligent SDR automation
Flight Track Replay -- Animated playback with speed control (1x/5x/10x)
WebSocket Broadcasting -- Real-time data updates every 2 seconds
Web Audio Streaming -- 48 kHz PCM audio over WebSocket for browser playback
Per-App Dashboards -- Dedicated web UIs for each radio application
Three Data Source Modes -- Replay (local cache), Serial (PortaPack), Gateway (HackRF direct)

Hardware Requirements

Primary Hardware

HackRF One -- Software-defined radio transceiver (1 MHz - 6 GHz)
PortaPack H2 (optional) -- Portable SDR platform with touchscreen UI
Antenna Kit -- Appropriate antennas for target frequencies

Optional Hardware

Second HackRF One -- For simultaneous multi-frequency operation
GPS Module -- For location-aware applications
External Amplifier -- For improved reception

Software Requirements

System Requirements

Python 3.10+ -- Core runtime environment
Operating System -- Windows, macOS, or Linux
Web Browser -- Modern browser for dashboard and FM radio audio
libhackrf -- HackRF USB library (for Gateway mode)

Dependencies

FastAPI + Uvicorn -- Web framework and ASGI server
WebSockets -- Real-time communication
NumPy + SciPy -- DSP signal processing for IQ decoders
pyhackrf2 -- HackRF One USB control
pyModeS -- ADS-B Mode-S message decoding
PySerial -- Serial port communication (PortaPack mode)
SQLAlchemy -- Configuration database

Quick Start

1. Clone Repository

git clone https://github.com/hydro13/sdr.git
cd sdr/

2. Set Up Virtual Environment

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate on Windows

3. Install Dependencies

pip install -r requirements.txt

4. Configure Environment (Optional)

cp config.example.env .env
# Edit .env to set your hardware ports (e.g., SDR_PORT=/dev/ttyACM0)

5. Start Web Dashboard

cd claude-sdr-control/
python sdr_web_server.py

Open http://localhost:5051 in your browser.

Note: The system starts in REPLAY mode by default, using cached data. No hardware required for initial testing!

6. Optional: Start HackRF Gateway (for direct IQ streaming)

cd claude-sdr-control/sdr-gateway/src/
python gateway_service.py

The gateway provides WebSocket IQ streaming at ws://localhost:5053.

7. Optional: Start Serial Gateway (for PortaPack serial console)

cd serial-gateway/
python gateway_service.py

The serial gateway runs at ws://localhost:5052/portapack.

Architecture

┌─────────────────────────────────────────────────────────┐
│              Web Browser (Dashboard / FM Radio)          │
│           http://localhost:5051 + WebSocket              │
└──────────────────────┬──────────────────────────────────┘
                       │
              REST API + WebSocket
                       │
┌──────────────────────▼──────────────────────────────────┐
│          FastAPI Server (sdr_web_server.py)              │
│  - Port 5051                                            │
│  - IQ Decoder management (7 decoders)                   │
│  - FM Audio WebSocket streaming (PCM 48kHz)             │
│  - Per-app dashboards and APIs                          │
│  - Three data source modes (replay/serial/gateway)      │
└────────┬───────────────────────────────┬────────────────┘
         │                               │
    WebSocket IQ                    WebSocket Serial
    (port 5053)                     (port 5052)
         │                               │
┌────────▼────────┐          ┌───────────▼───────────┐
│  HackRF Gateway │          │   Serial Gateway      │
│  (Direct USB)   │          │   (PortaPack Console)  │
│  - IQ streaming │          │   - File reading       │
│  - Multi-client │          │   - App management     │
│  - Freq control │          │   - Serial commands    │
└────────┬────────┘          └───────────┬───────────┘
         │                               │
    USB (libhackrf)               Serial (115200 baud)
         │                               │
┌────────▼────────┐          ┌───────────▼───────────┐
│   HackRF One    │          │   PortaPack H2        │
│   (SDR Radio)   │          │   + HackRF One        │
└─────────────────┘          └───────────────────────┘

IQ Decoder Pipeline

HackRF One (USB) → Gateway (ws://5053) → IQ Decoder → Parser → Dashboard
                                            │
                                    ┌───────┴───────┐
                                    │  7 Decoders:  │
                                    │  - ADS-B      │
                                    │  - FM Audio   │
                                    │  - RDS        │
                                    │  - Weather    │
                                    │  - APRS       │
                                    │  - Recon      │
                                    │  - SubGHz     │
                                    └───────────────┘

Application Modules

Module	Frequency	Description	Status
`adsb`	1090 MHz	Aircraft tracking via ADS-B/Mode-S	Production
`fm-radio`	87.5-108 MHz	FM broadcast radio with browser audio	Development
`rds`	87.5-108 MHz	FM RDS data decoding (station names, text)	Active
`recon`	Sweep	Frequency reconnaissance and signal scanning	Active
`weatherstation`	433/868 MHz	OOK/ASK weather sensor reception	Active
`subghz`	300-928 MHz	Sub-GHz protocol decoding	Active
`aprs-rx`	144.800 MHz	APRS packet reception (Bell 202 AFSK)	Active
`looking-glass`	Configurable	Spectrum analysis and visualization	Development
`aprs-tx`	144.800 MHz	APRS packet transmission	Planning
`siggen`	Configurable	Programmable signal generation	Planning
`pocsag-tx`	Various	Pager protocol transmission	Planning
`btle-rx`	2.4 GHz	Bluetooth LE signal analysis	Planning
`sonde`	400-406 MHz	Radiosonde weather balloon tracking	Planning

Configuration

Environment Variables

SDR_PORT=/dev/ttyACM0          # macOS/Linux. Use COM3 on Windows
SDR_WEB_PORT=5051              # Web dashboard port
SDR_GATEWAY_PORT=5052          # Serial gateway port (PortaPack)
SDR_HACKRF_PORT=5053           # HackRF IQ gateway port

Device Configuration

Serial Baudrate: 115200 (default)
HackRF Sample Rate: 2-20 MSPS (configurable per decoder)
HackRF Gain: LNA 0-40 dB, VGA 0-62 dB

Project Structure

sdr/
├── README.md                          # This file
├── CLAUDE.md                          # AI assistant instructions
├── LICENSE                            # MIT License
├── screenshots/                       # Dashboard screenshots
│
├── serial-gateway/                    # PortaPack Serial Gateway (port 5052)
│   └── gateway_service.py
│
└── claude-sdr-control/                # Main project
    ├── sdr_web_server.py              # FastAPI server (port 5051)
    ├── sdr_web_server.db              # SQLAlchemy config database
    │
    ├── sdr-gateway/src/               # HackRF IQ Gateway (port 5053)
    │   ├── gateway_service.py
    │   ├── hackrf_backend.py
    │   ├── spectrum_analyzer.py
    │   └── ...
    │
    ├── src/claude_sdr/
    │   ├── decoders/                  # IQ signal decoders (7 decoders)
    │   │   ├── base.py                # Base decoder (Gateway WebSocket client)
    │   │   ├── adsb_decoder.py        # 1090 MHz Mode-S demodulation
    │   │   ├── fm_audio_decoder.py    # FM broadcast → 48kHz PCM audio
    │   │   ├── rds_decoder.py         # FM RDS subcarrier extraction
    │   │   ├── weather_decoder.py     # 433/868 MHz OOK/ASK
    │   │   ├── aprs_decoder.py        # 144.8 MHz Bell 202 AFSK
    │   │   └── recon_decoder.py       # Frequency sweep + FFT
    │   ├── parsers/                   # Data parsers
    │   │   ├── adsb.py
    │   │   ├── rds.py
    │   │   ├── weatherstation.py
    │   │   ├── subghz.py
    │   │   ├── recon.py
    │   │   └── aprs.py
    │   └── controllers/
    │       ├── portapack.py           # PortaPack serial control
    │       └── unified.py             # Unified controller API
    │
    ├── static/                        # Web dashboards
    │   ├── dashboard.html             # Main dashboard
    │   ├── fm-radio.html              # FM Radio player
    │   ├── adsb-dashboard.html        # ADS-B aircraft tracking
    │   ├── rds-dashboard.html         # RDS decoder display
    │   ├── recon-dashboard.html       # Recon scanner
    │   ├── weatherstation-dashboard.html
    │   ├── subghz-dashboard.html
    │   ├── aprs-rx-dashboard.html
    │   └── ar-view.html               # AR overlay view
    │
    └── apps/                          # Per-app development docs
        ├── adsb/
        ├── rds/
        ├── recon/
        ├── weatherstation/
        └── ...                        # 12 app directories

Current Status

Production Ready

ADS-B Aircraft Tracking — Fully functional with real-time updates and replay capability
Web Dashboard — Complete FastAPI-based web interface with WebSocket support
HackRF Gateway — Stable IQ streaming from HackRF One hardware
Serial Gateway — Reliable PortaPack H2 serial console access

Active Development

FM Radio — Browser-based audio streaming (functional, being refined)
RDS Decoder — FM RDS data extraction (working, needs UI improvements)
Recon Scanner — Frequency reconnaissance and signal detection
Weather Station — OOK/ASK weather sensor decoding
APRS-RX — Amateur radio packet reception
SubGHz — Sub-GHz protocol decoding

Experimental/Planning

APRS-TX — Amateur radio packet transmission
Bluetooth LE — BLE signal analysis
Radiosonde Tracking — Weather balloon monitoring
Signal Generator — Programmable RF signal generation

Platforms Tested

✅ macOS (primary development platform)
✅ Linux (Ubuntu, Debian tested)
🔄 Windows (functional, occasional serial port issues)

Contributing

We welcome contributions! This project represents a 28-year passion for combining AI with software-defined radio.

How to Contribute

🐛 Report bugs using our issue templates
💡 Suggest features for new radio protocols or improvements
🚀 Submit pull requests for bug fixes or enhancements
📚 Improve documentation and user guides
🧪 Test on different hardware configurations

Areas We Need Help

New radio application modules
Mobile-responsive web interface improvements
Signal processing optimizations
Cross-platform testing and compatibility
Documentation and tutorials

See our Contributing Guide for detailed information on:

Development environment setup
Code style guidelines
Hardware requirements (or how to develop without hardware!)
Pull request process

Note: You don't need SDR hardware to contribute! The REPLAY mode allows full development using cached data.

Roadmap

This project is evolving into an AI Radio Intelligence System — transforming from single-SDR signal processing into a comprehensive, AI-powered radio monitoring platform.

Vision: The AI Radio Brain

Claude (the AI assistant) will become the "Radio Brain" that continuously monitors the radio spectrum, automatically identifies and classifies signals, learns patterns, detects anomalies, and provides intelligent insights about radio activity.

4-Phase Evolution Plan

Phase 1: Multi-SDR Gateway (4-6 weeks)
Extend gateway to handle 2+ HackRF devices simultaneously with role-based assignment (Monitor/Scanner). Enable concurrent operations like ADS-B tracking + ATC monitoring.

Phase 2: Spectrum Intelligence (6-8 weeks)
Wideband FFT spectrum sweeping, signal detection, SQLite database logging, waterfall visualization, and baseline pattern learning.

Phase 3: Classification & Recognition (8-10 weeks)
Modulation recognition (AM/FM/OOK/FSK/LoRa), Dutch/Belgian frequency allocation database, protocol fingerprinting, and auto-decoder activation.

Phase 4: AI Radio Brain (8-12 weeks)
Full AI integration where Claude analyzes spectrum data, learns patterns, detects anomalies, provides natural language insights, and makes intelligent SDR control decisions.

End State Capabilities

Dual-HackRF intelligent spectrum surveillance
Automatic signal classification for 50+ protocols
AI-powered anomaly detection and pattern learning
Natural language radio environment summaries
Cross-signal correlation and network discovery
Autonomous SDR tuning and decoder activation

📋 Full Technical Roadmap: RADIO-BRAIN-ROADMAP.md
Comprehensive 4-phase plan with architecture, APIs, implementation strategy, and success metrics.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Hardware

PortaPack H2 -- Portable SDR platform by ShareBrained Technology
HackRF One -- Open-source SDR hardware by Great Scott Gadgets

Software

Claude Code -- AI development assistant by Anthropic
FastAPI -- Modern web framework for Python APIs
pyModeS -- ADS-B Mode-S decoding library
pyhackrf2 -- HackRF One Python bindings
SciPy -- Scientific computing for DSP filters

Community

PortaPack Community -- Firmware development and documentation
SDR Community -- Open-source radio development
Amateur Radio Community -- Protocol documentation and testing

Built for the Software Defined Radio community

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.claude		.claude
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
archive		archive
claude-sdr-control		claude-sdr-control
screenshots		screenshots
serial-gateway		serial-gateway
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
RADIO-BRAIN-ROADMAP.md		RADIO-BRAIN-ROADMAP.md
README.md		README.md
config.example.env		config.example.env
requirements.txt		requirements.txt

License

hydro13/sdr

Folders and files

Latest commit

History

Repository files navigation

Claude SDR Control -- AI-Powered Software Defined Radio

Overview

Screenshots

Hardware Setup

Features

Core Capabilities

Advanced Features

Hardware Requirements

Primary Hardware

Optional Hardware

Software Requirements

System Requirements

Dependencies

Quick Start

1. Clone Repository

2. Set Up Virtual Environment

3. Install Dependencies

4. Configure Environment (Optional)

5. Start Web Dashboard

6. Optional: Start HackRF Gateway (for direct IQ streaming)

7. Optional: Start Serial Gateway (for PortaPack serial console)

Architecture

IQ Decoder Pipeline

Application Modules

Configuration

Environment Variables

Device Configuration

Project Structure

Current Status

Production Ready

Active Development

Experimental/Planning

Platforms Tested

Contributing

How to Contribute

Areas We Need Help

Roadmap

Vision: The AI Radio Brain

4-Phase Evolution Plan

End State Capabilities

License

Credits

Hardware

Software

Community

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages