HF Planner

What It Does

Tell it where you are and where you want to talk to. It checks current ionospheric conditions and tells you which bands have the best chance of working right now.

Pulls live data from KC2G’s ionosonde network, WSPR spots, PSK Reporter, and VOACAP. No API keys needed.

Install

You need Docker. On Linux, install with sudo apt install docker.io or your distro’s package manager. On macOS and Windows, install Docker Desktop. Windows requires WSL2.

Option 1: Docker Desktop GUI (Windows/macOS)

1. Open Docker Desktop
2. Click the search bar at the top
3. Search for lfmanifesto/hfplanner
4. Click Pull to download
5. Click Run, expand Optional settings, set Host port to 5001
6. Click Run
7. Open http://localhost:5001

Option 2: Command Line

docker run -d -p 5001:5001 lfmanifesto/hfplanner:latest

Open http://localhost:5001

Windows Notes

Docker Desktop needs WSL2. If it complains about virtualization:

1. Enable WSL: wsl --install in admin PowerShell
2. Restart
3. Run Docker Desktop

Runs On

Linux (Intel/AMD or ARM), macOS (Intel or Apple Silicon), and Windows 10/11 via Docker Desktop.

Bands

All 10 HF bands: 160m, 80m, 60m, 40m, 30m, 20m, 17m, 15m, 12m, 10m

Each band shows the dial frequency for JS8Call, Reticulum, and SSB.

How It Works

1. Gets solar conditions (SFI, K-index) from hamqsl.com
2. Pulls real-time foF2 and MUF from KC2G ionosonde network
3. Checks WSPR and PSK Reporter for recent spots on each band
4. Runs VOACAP model for path loss estimates
5. Compares against mode thresholds (JS8 needs -24dB, Reticulum DATAC4 needs -4dB, etc.)

If the band’s critical frequency is above your operating frequency, NVIS will work. The app flags this.

Data Sources by Mode

Different modes use different data sources for SNR estimation:

WSPR (Weak Signal Propagation Reporter) runs low-power beacons worldwide. If WSPR spots exist between two grids, the ionosphere is supporting that path. This is the universal “is the band open?” check.

PSK Reporter tracks digital mode spots. For JS8Call, we filter for actual JS8 traffic. For Reticulum and SSB, PSK Reporter data isn’t useful since nobody spots FreeDV data modes or voice.

VOACAP is an ionospheric model. It predicts propagation but can be optimistic. We use it as a fallback when no spot data exists, with penalties applied.

Confidence Levels

Each band shows a confidence level based on how much real-world data validates the prediction:

When confidence is LOW or MODEL-ONLY, the app applies conservative SNR penalties to avoid false optimism. Real spots always beat models.

Mode Thresholds

Link Budget

The app calculates link margins for each mode. Positive margin means the link will work, negative means it won’t.

You can enter your actual station parameters: feedline loss (0.5-3 dB estimated coax loss) and noise floor (measured RX noise in dBm). If you don’t enter a noise floor, the app uses the ITU-R P.372 atmospheric noise model. Measured values from your SDR or spectrum analyzer give more accurate results.

Cloud-RF (Optional)

For NVIS paths under 200km, Cloud-RF adds terrain modeling. Get an API key from cloudrf.com and run:

docker run -d -p 5001:5001 -e CLOUDRF_API_KEY=your_key lfmanifesto/hfplanner:latest

Not required. The app works fine without it.

Troubleshooting

“Docker not found” - Install Docker first.

Port 5001 in use - Use a different port: -p 5002:5001

No data loading - Check your internet connection. All data comes from external APIs.

Windows credential errors over SSH - Run docker commands locally, not via SSH. Windows credential manager doesn’t work in SSH sessions.

Changelog

v0.3.0-alpha - Link budget calculations with margin display. User-configurable noise floor and feedline loss. Shows “measured” vs “model” noise indicator. Feedline loss reference guide in Reference tab.

v0.2.x - Mode-specific data sources for accurate predictions. JS8Call now uses actual JS8 spots from PSK Reporter. Reticulum and SSB use WSPR + VOACAP blend. Added confidence indicators.

v0.1.x - Docker install, multi-platform images (amd64 + arm64), KC2G ionosonde data, 60m band, cleaned up UI.

Related

ReticulumHF for running Reticulum over HF radio. Reticulum Field Reference for setup guides and LoRa calculators.

Questions

Discord or Matrix.