ShackBook

Standalone ham radio logbook for Windows / Linux / macOS.

ShackBook is a Qt 6 desktop application that keeps a SQLite-backed QSO log and pulls live frequency / mode information from any radio that speaks the TCI (Transceiver Control Interface) protocol over WebSocket — AetherSDR, ExpertSDR2, SunSDR, and others. It fills in callsign details automatically, tracks awards, watches the DX cluster, and exports to ADIF 3.x and Cabrillo 3.0.

It also ships an optional headless server for multi-station operating — mirroring an N3FJP network, ingesting WSJT-X spots, and serving a live Field Day score over HTTP.

Download

Pre-built binaries — including a Windows installer — are on the Releases page:

• Windows installer — ShackBook-Setup-<version>-windows-x64.exe (double-click)
• Windows portable zip — ShackBook-<version>-windows-x64.zip (unzip, run ShackBook.exe)
• Linux AppImage — ShackBook-<version>-linux-x86_64.AppImage (chmod +x and run)
• macOS DMG (Apple Silicon) — ShackBook-<version>-macos-arm64.dmg (macOS 12 or later)
• macOS DMG (Intel) — ShackBook-<version>-macos-x86_64.dmg (macOS 12 or later)

Or build from source — see Build.

Features

Logging

• Live freq / band / mode auto-fill from a TCI server (default ws://127.0.0.1:40001), with auto-reconnect
• Find radios (Tools → Find radios…) — scans for TCI servers and offers what it finds. Only servers that answer a real handshake are listed; a port that merely accepts a connection is not a radio.
• Radios without TCI — Icom, Yaesu, Kenwood and anything else Hamlib drives, followed through its rigctld (Settings → TCI → Follow radio via). Hamlib reports the radio's own model, so contacts are attributed correctly with no nickname needed. Pick the rig, serial port and baud from lists, and press Test connection to see what the radio actually reports. ⚠ Hamlib is not included — see Following a non-TCI radio.
• Quick QSO entry: callsign + RST sent/received + comment, then SAVE
• Real-time duplicate-check warning as you type a callsign
• Full-fidelity QSO editor (Core / Other Station / My Station / Contest / Notes & QSL)
• Filterable QSO table — text search across call/name/QTH/grid/comment, plus band / mode / contest selectors
• Multi-operator logs — one database per callsign, live Switch Operator/Log
• Which radio made each QSO — the radio's name is taken from the TCI connection, shown in the status bar while you work, and stored on every QSO (exported as ADIF MY_RIG). Because TCI reports the application rather than the rig — AetherSDR answers "AetherSDR" for any radio behind it — you can set a nickname per TCI host/port to tell two rigs apart. A QSO logged with no radio connected records none, rather than guessing.
• Logs the power you actually ran — with TCI, a new QSO takes the forward power the radio measured on your last transmission, not a fixed default (Settings → Operator).

Contesting

• CW keyer (Settings → CW keyer, off by default) — F1–F8 send CW messages through the radio over TCI, N1MM-style: CQ {MYCALL} {MYCALL} TEST, {RST} {EXCH}, TU {MYCALL} and so on. Tokens fill from the entry form ({CALL}, {MYCALL}, {RST}, {NR}, {EXCH}, {NAME}), with cut numbers (599 → 5NN, 001 → TT1). The radio's speed shows on the panel with −/+, and Esc (or the STOP button) stops it at once. Because this is the one part of ShackBook that can transmit, it is careful about it:

  • it only ever sends when you press an F-key or click a message — never when a QSO is saved, a spot is clicked, or on a timer;
  • only when the radio is in a CW mode;
  • a new message replaces one still going out, and turning the keyer off, closing ShackBook or losing the link stops the radio first;
  • if the radio doesn't key (a TCI server without a CW keyer), the panel says so.

  Works with any TCI server that implements the CW macro commands — tested on a FLEX-6500 through AetherSDR. AetherSDR's demo radio can't transmit, so it (correctly) won't key. Contributed by Tony KX3H.

• QSO party layout (Tools → QSO Party Layout) — puts a party's exchange first in the entry form, in tab order (CALL → ←RST → ←COUNTY …), with the exchange boxes labelled for it. Fields the party doesn't use are dimmed and skipped by Tab, never hidden. A banner shows it is on, and Exit layout puts the form and your contest settings back exactly as they were. It survives a restart; while a party is running ShackBook offers its layout, but never switches by itself. Saving with a needed exchange field empty warns once — press Enter again to log it anyway.

• County worked/needed table and contest calendar (Tools → QSO Party…)

• Contest mode with sent/received serials and exchange, and Cabrillo 3.0 export

Callsign lookup

Three-tier autofill of an empty QSO's name / QTH / grid / state / country:

1. Worked-before — reuses details from your previous QSO with that station
2. cty.dat — bundled offline AD1C prefix resolver (country / continent / CQ / ITU zones)
3. Online — QRZ.com (XML, paid), HamQTH (free), and callook.info (US, no account)

Awards & spotting

• Awards panel (Tools → Awards): DXCC / WAS / WAC / WAZ / grids, worked vs confirmed, chase lists
• DX cluster client with configurable login suffix and duplicate-login handling
• POTA spot integration
• N1MM+ / DXLog bandmap spots over UDP (Settings → DX Cluster, port 12060) — spots carry the logger's contest state, shown in the Spot Index's Status column: dupes greyed, needed multipliers bold. Spots the logger removes are removed here too. Receive-only. If another program (often SmartSDR CAT) already holds the port, ShackBook says so — pick another port and add it to N1MM's broadcast list.
• Double-click a spot to tune the radio to it (Tools → Show Spot Index; off by default, Settings → TCI). It moves the frequency and, optionally, the mode — never transmits.
• "How far?" button — opens a PSK Reporter map of who's hearing you, filtered to your band
• Section map (Maps menu) — native ARRL/RAC section map, N3FJP-style

Looking after the log

Your log is the one file in the shack that cannot be remade, so ShackBook treats it that way — all of this happens on its own, with nothing to configure:

• Verified backups — a compacted snapshot taken at most weekly, and always before a database upgrade. Each one is reopened and checked before it counts as a backup. They live in a backups/ folder beside the log.
• Checked on open — a fast integrity check every launch, the thorough one only if that finds something.
• Quarantine and restore — a log that fails its check has the damaged files moved aside (never deleted) and the newest verified backup put in their place, with a dialog explaining what happened. If there is no backup to restore, ShackBook keeps logging on the damaged file rather than locking you out mid-contest — but tells you clearly.

Import / export

• ADIF import (File → Import ADIF) — whole-file, deduplicated, fast (proven on 16k+ record logs)
• ADIF 3.1.4 export with the full standard field set
• Cabrillo 3.0 export with operator-defined header categories

Home Assistant (MQTT)

Settings → MQTT publishes shack status to a broker on your LAN, with Home Assistant discovery: online/offline, radio connected, frequency, mode and band, transmitting (an on-air light), and today's QSO count. Details of the last QSO are published only if you switch that on.

Server (optional, for multi-station / Field Day)

A headless companion (shackbook-server) that:

• Mirrors a remote N3FJP network so its QSOs land in your log
• Ingests WSJT-X "Secondary UDP" spots (udp/1100) straight into the log
• Serves a live ARRL Field Day score breakdown over HTTP (/api/score)
• Exposes a REST API (/api/qsos) with schema versioning, audit trail, and soft-delete

All operator settings (MY_CALL, grid, power, TCI host/port, Cabrillo headers, lookup credentials, cluster login) live inside the database — no external config files.

Build

Requirements:

• Qt 6.2 or newer with the Sql and WebSockets modules
• CMake 3.20+
• A C++17 compiler (MSVC, GCC, or Clang)

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

The resulting binaries are build/ShackBook (the logbook) and build/shackbook-server (the optional server), plus .exe on Windows. On Windows, build.bat also handles the MSVC environment setup.

The unit tests are opt-in locally (CI runs them on Linux and Windows for every push and pull request):

cmake -B build-tests -G Ninja -DSHACKBOOK_TESTS=ON
cmake --build build-tests
ctest --test-dir build-tests --output-on-failure

On Windows, build-tests.bat does the same. A build is marked -dev in the window title unless configured with -DSHACKBOOK_RELEASE=ON, so it is always obvious whether you are running an installed release or something you built.

Following a non-TCI radio

TCI is built into AetherSDR, ExpertSDR and SunSDR — if you use one of those, there is nothing extra to install and you can skip this section.

Every other radio is reached through Hamlib, which drives around 200 rigs and exposes them on a single network port via its rigctld program. ShackBook does not include Hamlib — it is a separate project under a different licence, and if you already run WSJT-X or fldigi you almost certainly have it already.

1. Install Hamlib (apt install libhamlib-utils on Debian/Ubuntu, brew install hamlib on macOS, or the Windows build from the Hamlib site).
2. Start it, pointed at your radio — for example an IC-9700 on COM4:

   rigctld -m 3081 -r COM4 -s 19200

   rigctl --list shows the model number for your rig.
3. In ShackBook, Settings → TCI → Follow radio via → Hamlib rigctld. The default host and port (127.0.0.1:4532) suit a local radio. Pick your radio model, serial port and baud from the lists and ShackBook shows the exact command to run.
4. Press Test connection. It asks the radio for its frequency and mode and shows what came back — e.g. "IC-9700 reports 435.645935 MHz, FM". If something is wrong it says which link: nothing listening, a serial-port error, or (the case that otherwise looks like success) rigctld running but the radio not answering, which almost always means the baud rate or model is wrong.

ShackBook tells you if it cannot find Hamlib, and lets you point at it if you installed it somewhere unusual. If nothing is serving the port when you connect, it offers to start rigctld for you with the model, port and baud you picked — it asks first, since that program takes the serial port — and stops it again when ShackBook exits. A rigctld that is already running (your own, or one shared with WSJT-X or fldigi) is never touched.

Database location

The QSO database is auto-created on first run (one file per operator callsign):

OS	Path
Windows	%LOCALAPPDATA%\G0JKN\ShackBook\shackbook-<CALL>.sqlite
Linux	~/.local/share/G0JKN/ShackBook/shackbook-<CALL>.sqlite
macOS	~/Library/Application Support/G0JKN/ShackBook/shackbook-<CALL>.sqlite

<CALL> is the operator you chose at startup. The G0JKN folder is the application's publisher, not your callsign — it is the same for everyone.

That one file is the entire log — copy it and you have copied everything. ShackBook keeps its own verified backups in a backups/ folder beside it (see Looking after the log), but those live on the same disk, so keep a copy somewhere else as well.

Documentation

• CHANGELOG.md — what changed in each release
• ROADMAP.md — what's planned next

License

MIT. See LICENSE.

73 de G0JKN / W3.