HF Propagation Prediction - la5nta/pat GitHub Wiki

HF Propagation Prediction

Pat includes support for HF propagation prediction using VOACAP (Voice of America Coverage Analysis Program), which automatically analyzes propagation conditions to help you identify the most reliable stations for making connections.

This feature was added in v0.19.0.

Overview

VOACAP (Voice of America Coverage Analysis Program) is automatically detected and used if installed in a standard location on your system - no additional configuration required.

When VOACAP is available, Pat will:

  • Display Link Quality Indicator (LQI) values from 0-100 for each RMS station (higher values indicate better conditions)
    • Takes into account factors like signal-to-noise ratio, path reliability and propagation mode
    • Helps you identify which stations are most likely to provide reliable connections
  • Sort RMS stations by connection quality based on current propagation conditions

Setup

Pat supports VOACAP on all major platforms. In most cases, you only need to install VOACAP and Pat will automatically detect and use it—no manual setup required.

Installing VOACAP

Debian-based Systems (Debian Trixie, Ubuntu, etc.)

For Debian Trixie (released August 9, 2025) and derivatives based on it, install from the repositories:

sudo apt install voacapl

Note: This method will only work on recently updated systems running Debian Trixie or newer derivatives.

Other Linux Distributions

For other Linux distributions, follow the installation instructions in the VOACAPL GitHub repository: https://github.com/jawatson/voacapl?tab=readme-ov-file#installation

macOS

Install VOACAPL using Homebrew:

brew install la5nta/tap/voacapl

Windows

To install VOACAP on Windows:

  • Download the original VOACAP implementation (ITSHFBC): itshfbc_180417a.exe
  • See installation instructions: Greg Hand’s HFWin32 page
  • Install VOACAP to c:\itshfbc (this is the default and is required for Pat’s automatic detection)

Configuring Pat

After installing VOACAP, Pat will automatically detect and use it for propagation predictions. No additional configuration is required in most cases.

Advanced Configuration

By default, Pat looks for the VOACAP executable in your system’s $PATH. On Windows, the expected location is c:\itshfbc\bin_win\voacapw.exe.

Pat will automatically search for VOACAP data files in the following locations:

  • ~/itshfbc (Unix/macOS, voacapl's makeitshfbc installs data files here)
  • /usr/share/voacapl/itshfbc (Unix/macOS)
  • /usr/local/share/voacapl/itshfbc (Unix/macOS)
  • $(brew --prefix)/share/voacapl/itshfbc (macOS with Homebrew)
  • c:\itshfbc (Windows)

If you wish to explicitly enable, disable, or configure the prediction engine, or specify custom paths, you can do so in your Pat configuration. Run the configuration tool:

pat configure

Then add or modify the prediction section as needed:

To explicitly disable prediction:

"prediction": {
  "engine": "disabled"
}

To explicitly enable VOACAP (not usually needed as autodetection is the default):

"prediction": {
  "engine": "voacap"
}

To specify custom executable and data directory paths:

"prediction": {
  "engine": "voacap",
  "voacap": {
    "executable": "/path/to/voacapl",
    "data_dir": "/path/to/itshfbc"
  }
}

Troubleshooting

  • "Failed to find executable": Ensure the VOACAP executable is in your PATH or specify the full path in your Pat configuration
  • "Failed to find datadir": If Pat cannot find the VOACAP data files, see the Advanced Configuration section for the list of search paths and instructions for manual setup.
  • Empty or zero predictions: Check that your station's Maidenhead grid square is correctly set in Pat's configuration
  • No prediction values shown with automatic detection: If using automatic detection and no prediction values appear, check that VOACAP is properly installed and accessible

Additional Resources