ham-tools: A Suite of Command-Line Amateur Radio Utilities
Primary Purpose:
ham-tools is a collection of command-line utilities designed for amateur radio enthusiasts, offering tools for callsign lookups, bearing calculations, and real-time DX cluster monitoring.
Key Features:
QRZ.com Callsign Lookup (qrz): Enables one-shot or interactive lookups with a local cache and FIFO functionality.
Address-to-Bearing Conversion (qte): Utilizes OpenStreetMap data to calculate bearings from the user's location, providing grid squares and compass directions.
Live DX Cluster Viewers: Interfaces for DX Summit, DXHeat, and HolyCluster, featuring TUI interfaces for real-time spot monitoring and plain text output options.
Audience & Benefits:
Ideal for amateur radio operators seeking efficient, versatile tools. ham-tools streamlines workflows with quick lookups, precise bearing calculations, and real-time cluster data access. Available via winget on Windows, ensuring cross-platform usability.
README
ham-tools
A small suite of command-line amateur-radio tools written in C.
Tool
What it does
qrz
QRZ.com callsign lookup — one-shot or interactive REPL, with a local SQLite cache and a FIFO for feeding lookups from other programs
qte
Bearing/heading lookup — geocodes an address (OpenStreetMap Nominatim) and prints the grid square, short-path heading, long-path and compass bearing from your QTH
dxsummit
Live DX Summit cluster spots — ncurses TUI (or --dump for plain text)
dxheat
Live DXHeat cluster spots — ncurses TUI (or --dump)
holycluster
Live HolyCluster spots over a WebSocket — ncurses TUI (or --dump)
This builds all five tools and installs them onto your PATH.
> If Homebrew refuses to load the formula from this untrusted third-party
> tap, trust it once and re-run the install:
>
> sh > brew trust Guru-RF/ham-tools >
>
> To build the latest development version straight from master instead:
>
> sh > brew install --HEAD Guru-RF/ham-tools/ham-tools >
Install on Windows (winget)
Native Windows builds are available for both x64 (Intel/AMD) and ARM64:
winget install Guru-RF.ham-tools
winget picks the right architecture automatically and puts qrz, qte,
dxsummit, dxheat and holycluster on your PATH. Open a new terminal
afterwards so the updated PATH takes effect, then create your config file
(see Configuration) before running or .
> Windows differences. The tools are built as native binaries with MSYS2
> MinGW-w64. One-shot lookups, the qrz REPL and the cluster TUIs all work the
> same as on macOS/Linux, with two caveats:
>
> - The qrz lookup FIFO — and the dx* TUIs' "feed the selected callsign
> into a running qrz" channel — is a POSIX named pipe and is disabled on
> Windows. One-shot lookups and the interactive REPL are unaffected.
> - Config lives in %APPDATA%\ham-tools\ instead of ~/.config/ham-tools/.
Build from source
Dependencies
The tools link against a handful of system libraries:
Library
Used by
pkg config
libcurl
all
-lcurl
libyaml
all (config parsing)
yaml-0.1
jansson
qte, dxheat, holycluster
jansson
libxml2
qrz
xml2-config
sqlite3
qrz (cache)
-lsqlite3
readline
qrz (interactive REPL)
-lreadline
ncurses
dxsummit, dxheat, holycluster (TUI)
-lncurses
libwebsockets
holycluster
libwebsockets
Build tools: a C11 compiler (cc/clang/gcc), make, and pkg-config.
curl and xml2-config ship with macOS. On macOS the Makefile automatically
prefers Homebrew's readline (the system libedit lacks the callback API qrz
needs).
Install MSYS2 and build from the UCRT64 shell on
x64, or the CLANGARM64 shell on Windows-on-ARM. Replace the package prefix
below to match (mingw-w64-ucrt-x86_64- for UCRT64,
mingw-w64-clang-aarch64- for CLANGARM64):
The Makefile auto-detects MSYS2 (adds .exe, links ncursesw, builds with
-std=gnu11). On CLANGARM64 build with make -C c CC=clang.
Compile
cd c
make # builds all five binaries in place
The binaries are written next to their sources: qte/qte, qrz/qrz,
dxsummit/dxsummit, dxheat/dxheat, holycluster/holycluster.
Install
make install # installs into $HOME/bin (PREFIX defaults to $HOME)
make install PREFIX=/usr/local # or anywhere you like ($PREFIX/bin)
Other make targets
make clean # remove object files and binaries
The Makefile honours the usual overrides, e.g. make CC=gcc,
make CFLAGS="-O3", or make PREFIX=/opt/ham.
Configuration
All tools read a single YAML file:
Platform
Location
Linux / macOS
~/.config/ham-tools/config.yaml
Windows
%APPDATA%\ham-tools\config.yaml
The first time you run any tool without a config, it writes a starter
config.yaml at that location and tells you where — just edit it and run again.
The same directory also holds the qrz SQLite cache and REPL history (and, on
Linux/macOS, the lookup FIFO). A minimal config looks like:
verbose: false
# Your station location — required by `qte` for bearing calculations.
qth:
latitude: 50.95
longitude: 4.05
# QRZ.com credentials — required by `qrz`.
qrz:
com:
username: "YOURCALL"
password: "your-qrz-password"
# Optional: override the qrz lookup FIFO path
# fifo: /tmp/qrz.fifo
Editing the config on Windows
Run any tool once (e.g. qrz) to have it create the starter config, then open
it in Notepad:
notepad "$env:APPDATA\ham-tools\config.yaml"
That path expands to C:\Users\\AppData\Roaming\ham-tools\config.yaml (the
AppData folder is hidden in Explorer). Set your qth and QRZ.com credentials
and save. A couple of Windows tips:
Save as plain UTF-8 and keep the name config.yaml (don't let Notepad add
a .txt extension).
Use spaces, not tabs, for indentation (YAML rejects tabs).
Usage
qrz W1AW # one-shot lookup of one or more callsigns
qrz # interactive REPL (readline history; also reads the FIFO)
echo "DL1ABC" > ~/.config/ham-tools/qrz.fifo # feed a lookup into a running qrz
qte "Brussels, Belgium" # grid + short/long-path bearing from your QTH
dxsummit # live cluster TUI (q to quit)
dxsummit --dump # one-shot plain-text dump of current spots
dxheat # live cluster TUI
dxheat --dump
holycluster # live WebSocket cluster TUI
holycluster --dump