wxShark

NOAA Weather Radio receiver, SAME alert decoder, and web monitoring dashboard.

Quick Start

# Setup
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install -r requirements.txt
cargo install samedec

# Configure in .env (copy .env.example and edit)
cp .env.example .env
nano .env

# Run (headless, for servers/RPi)
python3 wxshark.py --headless

# Or with port overrides
python3 wxshark.py --headless --web-port 8082 --udp-port 2000

# Run as a background daemon (detach from terminal)
python3 wxshark.py --headless --daemon

# Stop a running daemon
python3 wxshark.py --stop

Open http://<host>:<port> in a browser.

Daemon details:

• PID file: /tmp/wxshark.pid
• Log file: /tmp/wxshark.log (rotating, 5 MB max, 3 backups)
• Sending SIGTERM (via --stop or kill) triggers graceful shutdown

Configuration

All settings live in .env (see .env.example for reference). Only a few values can be overridden at runtime via CLI:

CLI Flag	Description
-d, --daemon	Run as background daemon (detach from terminal)
--stop	Stop a running daemon
--headless	Disable Qt GUI
--web-port	Override web port
--udp-port	Override UDP audio port
--web-host	Override web bind address

SAME Filtering

Set SAME_CODES to filter alerts by specific county codes (space-separated). Set SAME_ALL=true to accept all SAME codes regardless of code. If neither is set, all codes are accepted.

SAME_CODES=029095 020091   # filter to specific counties
SAME_ALL=true              # accept all codes

MQTT

Configure MQTT in .env. Authentication and SSL/TLS are supported:

MQTT_ENABLED=true
MQTT_HOST=homeassistant.local
MQTT_PORT=8883
MQTT_USER=mqtt-username
MQTT_PASSWORD=mqtt-password
MQTT_TOPIC=wxshark/alerts
MQTT_TOPIC_TELEM=wxshark/telemetry
MQTT_SSL=true
MQTT_CA_CERT=/home/username/homeassistant.crt

If MQTT_CA_CERT is left empty, the system trust store is used. (this feature is untested)

Telemetry: Every 5 minutes, system telemetry (CPU%, RAM%, temps) is published to the MQTT_TOPIC_TELEM topic. Payload mirrors the web /api/telemetry endpoint.

Dependencies

• GNU Radio with SoapySDR + HackRF support
• samedec (Rust, installed via cargo)
• Python 3.12+ with --system-site-packages venv (GNU Radio is a system package)

See ARCHITECTURE.md for full details, data flow, and component documentation.

Alert Log

Alerts are persisted to alerts.json in the project directory. Each alert includes the ZCZC header, parsed message, and expiration time. Alerts are pruned after 24 hours past their expiration time (or 24 hours from issue time if the expiration is unknown).

You can read the alert log directly:

cat alerts.json | python3 -m json.tool

SDR Support

• HackRF One — fully supported (superhet downconversion avoids DC spike)
• RTLSDR — planned (requires flowgraph adjustment for 1.024 MHz sample rates)