Skip to content

Latest commit

 

History

History
210 lines (158 loc) · 8.2 KB

README.md

File metadata and controls

210 lines (158 loc) · 8.2 KB

WSPR HA Bridge

HACS Custom GitHub Release License Buy Me a Coffee

Data sourced from WSPRnet via WSPR.live. Both services are volunteer-maintained and free for the amateur radio community.

Disclaimer: This project is independently developed and is not affiliated with, endorsed by, or connected to WSPRnet or WSPR.live.

Bridge WSPR (Weak Signal Propagation Reporter) spot data from WSPR.live to Home Assistant for monitoring amateur radio propagation conditions.

Features

  • Real-time WSPR monitoring - Track your WSPR transmissions and receptions
  • Dual deployment - Install via HACS (native integration) or Docker (external bridge)
  • Rich statistics - Per-band metrics, distance stats, propagation scores
  • Global network stats - Network-wide activity and max distances
  • Mode tracking - WSPR-2, WSPR-15, and FST4W mode detection
  • Flexible filtering - Filter by callsign, band, country, or distance
  • WSPR-specific data - Includes power levels (dBm/Watts) and frequency drift (Hz/min)
  • Dashboard generator - Create custom Lovelace dashboards for your callsign

Installation

Option A: HACS Integration (Recommended)

Native Home Assistant integration with UI-based configuration.

  1. Open HACS in Home Assistant
  2. Click the menu (⋮) → Custom repositories
  3. Add https://github.com/pentafive/wspr-ha-bridge as Integration
  4. Click Install
  5. Restart Home Assistant
  6. Go to Settings → Devices & Services → Add Integration → WSPR

Option B: Docker Container

External bridge that publishes to Home Assistant via MQTT.

git clone https://github.com/pentafive/wspr-ha-bridge.git
cd wspr-ha-bridge
cp .env.example .env
# Edit .env with your callsign and MQTT broker
docker compose up -d

Documentation

Architecture

                ┌──────────────────┐
                │   WSPR.live      │
                │ (ClickHouse DB)  │
                │  2.7B+ spots     │
                └────────┬─────────┘
                         │ HTTP Poll (150s)
                         ▼
        ┌────────────────────────────────┐
        │         wspr-ha-bridge         │
        │  ┌─────────────┬─────────────┐ │
        │  │ HACS        │ Docker      │ │
        │  │ Integration │ Container   │ │
        │  │ (native)    │ (MQTT)      │ │
        │  └─────────────┴─────────────┘ │
        └────────────────┬───────────────┘
                         │
                         ▼
                ┌──────────────────┐
                │  Home Assistant  │
                │  • Sensors       │
                │  • Dashboards    │
                │  • Automations   │
                └──────────────────┘

Deployment Comparison

Feature HACS Integration Docker Container
Installation HACS UI docker compose
Configuration Home Assistant UI Environment variables
Updates HACS automatic Manual pull
Resource usage Inside HA Separate container
MQTT required No Yes
Best for Most users Separate hardware, advanced users

Direction Modes

  • RX Mode (rx): Monitor who received your signal (you're transmitting)
  • TX Mode (tx): Monitor who you received (you're receiving)
  • Dual Mode (dual): Monitor both directions

Sensors Created

Statistics Sensors

  • Total spots, Unique stations
  • Most active band, Most active mode
  • Distance (min/avg/max)
  • SNR (min/avg/max)
  • Average TX power (dBm and Watts)
  • Spots per hour
  • DX ratio, Propagation score
  • Feed status (health monitoring)

Global Network Sensors

  • Global spots (last 15 min)
  • Global max/avg distance
  • Network-wide unique transmitters/receivers

Per-Band Sensors

  • Spot count for each HF band (160m through 6m)
  • Includes per-band SNR, distance, and power averages

Data Source

This bridge uses the WSPR.live public ClickHouse database:

  • Database: http://db1.wspr.live/
  • Data latency: ~2-3 minutes from real-time
  • Rate limit: 20 requests/minute (this bridge uses ~0.4 req/min)
  • Historical data: 2.7+ billion spots

Test Mode (Docker)

Verify WSPR.live connectivity without requiring MQTT:

export MY_CALLSIGN=W1ABC
export SCRIPT_DIRECTION=tx
python wspr-ha-bridge.py --test

Dashboard Generator

Generate custom Lovelace dashboards for your callsign:

cd examples/dashboards
python generate_dashboard.py W1ABC -o my-dashboard.yaml

Options:

  • --no-global - Exclude global network statistics
  • --no-bands - Exclude per-band breakdown
  • -o FILE - Save to file instead of stdout

Requires: mushroom cards, mini-graph-card, apexcharts-card (HACS Frontend)

Comparison with pskr-ha-bridge

Feature pskr-ha-bridge wspr-ha-bridge
Data Source mqtt.pskreporter.info db1.wspr.live
Data Model Push (MQTT subscription) Pull (HTTP polling)
Latency Sub-second 2-3 minutes
Modes FT8, FT4, CW, etc. WSPR, FST4W
Extra Data — Power (dBm/W), drift
Global Stats Yes Yes
Deployment HACS + Docker HACS + Docker

WSPR Ecosystem

Data Sources

Analysis Tools

Software

Related Bridges

Support

If you find this integration useful:

  • Buy Me a Coffee — Support development of this and other HA integrations

Data Sources

This integration uses data from the WSPRnet network, accessed through the WSPR.live community database. Both are volunteer-run services that are free for amateur radio operators.

License

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

Disclaimer

This project is independently developed and is not affiliated with, endorsed by, or connected to WSPRnet or WSPR.live. WSPR spot data is sourced from the WSPR.live public database and originates from the WSPRnet network.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.