Settings
The settings window (⌘,) has ten tabs. Each tab configures a clearly defined area of the app. This page is the hub — five tabs (Station, CAT, Lookup & Upload, Macros, License) have their own step-by-step guides in Tutorials.
| Tab | What for |
|---|---|
| Station | Your own callsign, locator, canton, app callsign license |
| Data | Data folder path, POTA/SOTA/WWFF/BOTA databases, SCP sources |
| CAT | Connection (USB / IC-705 WLAN / Network), TRX profile, serial port, baud, Hamlib subprocess status |
| Cluster | Manage DXSpider nodes, spotter radius |
| Lookup & Upload | QRZ, HamQTH, eQSL, Club Log, LoTW — everything QSL-related |
| External Loggers | UDP broadcasting to N1MM, Win-Test, Cluster-Master |
| Macros | F1–F8 contest macros (CW + SSB) |
| Alerts | Watch list for cluster spots, macOS notifications |
| Appearance | Theme selection, app language |
| License | Enter + activate license key |
Station
Here you define who you are — every other module draws on this.
Fields:
| Field | Description |
|---|---|
| Callsign | Your primary license callsign (e.g. HB9HJI). Used as OPERATOR in ADIF/Cabrillo exports, serves as the substring master for per-log callsign validation |
| Locator | 6-character Maidenhead locator (e.g. JN47PN). Source for distance calculations, the home point on the history map, the cluster radius filter |
| Canton | Optional — only for CH calls. Exported as HQ info in Swiss contests |
Per-Log Callsign
In the logbook each log can hold its own station call (portable, abroad, club call). The master call entered here is just the default and the validation basis. See Logbook — Per-Log Callsign.
Data
Where HAM-Tools stores its files — and which databases it loads.
Data folder: Default is ~/Documents/HAM-Tools/. Changeable via file picker. Auto-migration from the legacy path on first launch. Contains:
HAM-Tools/
├── Logs/ — .htlog SQLite files, one per logbook
├── Cache/ — spots, callbook cache, memories
├── Exports/ — ADIF (.adi) + Cabrillo (.cbr)
├── Backups/ — auto-backups before risky actions
└── Macros/ — SSB voice recordings F1–F8Databases each with their own load/status indicator:
| DB | Source | Size |
|---|---|---|
| POTA parks | pota.app | ~91k entries |
| SOTA summits | sotadata.org.uk | ~181k entries |
| WWFF references | wwff.co + CSV import | ~68k entries |
| BOTA references | CSV import | varies |
| SCP master calls | supercheckpartial.com + cdn.clublog.org | ~230k calls |
Each DB has a status pill (loading / ready / error), an update button and an auto-stale reminder after 14 days.
CAT
Connect to your transceiver via Hamlib — HAM-Tools ships with a bundled rigctld helper binary (Yaesu, Icom, Kenwood, Elecraft + ~200 more models).
Connection ("Connection" picker, new in 1.13.0):
| Connection | Fields |
|---|---|
| USB (Serial) | Standard — HAM-Tools starts its own rigctld on the serial port (fields below) |
| IC-705 WLAN | Radio IP, User, Password — values from the radio menu Set → WLAN Set → Remote Control (network user with administrator rights). Direct connection without any extra tool; audio does not run through HAM-Tools. The CI-V address must match the radio setting (IC-705: 0xA4) |
| Network (rigctld) | Host + Port of an already-running rigctld server (e.g. wfview/kappanhang, often port 4533; standard rigctld: 4532) |
Details + tutorial: CAT → Connection Types and Connect the IC-705 over WLAN.
Fields (USB connection):
| Field | Description |
|---|---|
| TRX profile | Dropdown with 31 curated profiles (trx-profiles.json) — automatically selects the rig model ID, default baud and PTT mode. Beyond that, the Hamlib backend knows ~200 more models |
| Serial port | /dev/cu.usbserial-* or /dev/cu.SLAB_USBtoUART — auto-detected via dropdown |
| Baud rate | preset by the profile, overridable |
| CI-V address | only for ICOM (e.g. 0x94 for IC-7300) |
| Share CAT | switch "Keep rigctld open for other programs" — keeps the built-in Hamlib server open locally (127.0.0.1:4532) so WSJT-X & Co. can use the same radio in parallel. With WSJT-X config display + copy button and "End sharing" |
| Hamlib status | Live display of whether rigctld is running + a connection health check |
What happens after a successful connection:
- Frequency is automatically shown in the logger + persisted
- Mode is used as the single source of truth (RST defaults follow, Cabrillo mismatch warning)
- Macros F1–F8 send CW directly via
send_morse - The ICOM voice keyer (V1–V4) or Yaesu (V1–V5) is triggered
- On modern Yaesu, the TUNE button starts a real tuner match (separate from the TUN on/off pill)
Sharing CAT with WSJT-X
Details on parallel operation with WSJT-X/fldigi (Rig = Hamlib NET rigctl, 127.0.0.1:4532, PTT = CAT) are in the CAT → CAT Sharing module.
CAT tutorials
Step-by-step setup with a USB cable, driver check and test flow: Tutorials → CAT Setup. For the IC-705 without a cable: Connect the IC-705 over WLAN.
Cluster
Manage DX cluster nodes. Multiple nodes can be active in parallel.
Per node:
| Field | Example |
|---|---|
| Name | DXSpider Funkwelt |
| Host | dxspider.funkwelt.net |
| Port | 7300 |
| Active | Toggle (multiple nodes at once possible) |
Preset nodes: Funkwelt, HB9W, DB0ERF, DX.OE5TXF, ON0ANT, VE7CC.
Spotter radius filter: Spots are filtered by distance from your own QTH (Haversine formula, based on the station locator).
Lookup & Upload
By far the densest tab: all QSL and callbook services in one place. A sub-picker for service selection, a master switch for real-time upload.
Callbook Lookup
| Field | Description |
|---|---|
| Primary Service | QRZ.com or HamQTH.com — queried first |
| Secondary (fallback) | Optional second service if the primary has no hit |
| Auto-lookup on TAB | After entering the call + TAB, name/QTH/locator etc. are fetched automatically |
| Fields to fill | 10 toggles: Name, QTH, Locator, Country, DXCC, CQ Zone, ITU Zone, IOTA, State, County — you choose what gets applied |
Cache: 30 days, local in Cache/callbook-cache.json.
Upload Services
Master switch "Real-Time Upload" at the top — when off, ALL auto-uploads are paused (travel mode).
| Service | What it does |
|---|---|
| QRZ.com | Auto-upload per QSO + confirmation sync ("Fetch QRZ confirmations" in the QSL tab) |
| eQSL.cc | Form POST with per-log nickname override, status pill in the table |
| Club Log | realtime.php with firewall protection (auto-pause after a burst) |
| LoTW (tqsl) | Subprocess upload via the local tqsl binary, confirmation sync via LoTW report download |
Per service: API key/username/password + auto-upload toggle + "QSL sent via X" auto-mark.
LoTW Specifics
| Field | Explanation |
|---|---|
| tqsl binary | Default /Applications/Tqsl.app/Contents/MacOS/tqsl. Auto-detected on first launch. The "📁 Browse…" button next to it opens a Finder picker — you just click Tqsl.app and HAM-Tools extracts the binary path automatically (even if the app lives somewhere other than /Applications or was installed via Homebrew) |
| Station Location | Dropdown from ~/.tqsl/station_data.xml (tqsl 2.5+) and ~/Library/Application Support/TrustedQSL/station_data.xml (older tqsl). The picker shows the locations you created in the tqsl GUI |
LoTW tutorial
The complete pipeline (install TQSL.app, create a station location in the tqsl GUI, set up a certificate, first upload in HAM-Tools): Tutorials → LoTW Pipeline.
External Loggers
UDP broadcasting of logged QSOs to external tools. Multiple targets can be configured in parallel, each with its own format (N1MM, Win-Test, Cluster-Master, generic ADIF-UDP).
Per target:
| Field | Example |
|---|---|
| Name | N1MM Logger |
| Host | 192.168.1.50 |
| Port | 12060 |
| Format | N1MM XML / Win-Test / ADIF-UDP / Custom |
| Active | Toggle |
Useful for example when you use HAM-Tools as the master logger and feed a second tool in parallel for an SDR bandscope or skimmer.
Macros
F1–F8 contest macros (see Contest Macros & Voice Keyer). Eight slots, each with a label + CW text + optional SSB recording.
Per slot:
| Field | Description |
|---|---|
| Label | Short display name on the button (e.g. CQ, 5NN, TU) |
| CW text | Template with variables {MyCall}, {TheirCall}, {Snt}, {Rcv}, {Cnt}, {Exch} |
| SSB recording | Live recording via microphone, AAC/m4a file in Macros/Contest/. Preview without PTT, delete button |
Factory assignment (N1MM style): CQ · Exch · TU · MyCall · HisCall · ? · 5NN · AGN.
Mode auto-detection: When you press a macro button, HAM-Tools looks at radio.hamlibMode — CW → Hamlib send_morse, SSB → AVAudioPlayer with PTT toggling.
Macros tutorial
Setup walkthrough with your own microphone recording + TRX voice keyer: Tutorials → Contest with Macros.
Alerts
Watch list for cluster spots. When a spot matches a prefix or callsign from the list, you get a macOS notification plus a ★ mark in the spot list.
| Field | Description |
|---|---|
| Watch entries | List of prefixes (DL, K1) or full calls (K1AA) |
| DXCC filter | Optional additional DXCC selection (e.g. only most-wanted DXCC) |
| macOS notifications | Toggle — enable system notifications, permission is requested on first enable |
Appearance
The app's look + language.
Theme (V1.9.1):
| Theme | Character |
|---|---|
| HAM Style | Default, ham green on charcoal |
| Dark | classic macOS dark |
| Ham Classic | beige/gold, retro radio look |
| Matrix | black with Matrix green (#00FF41) and cyan accents |
Language: System / Deutsch / English. The effect is applied live, no restart needed.
License
License key management. HAM-Tools uses Ed25519-signed licenses — the public key is baked into the app, the private key lives only with the author (see Activate License).
| Action | What for |
|---|---|
| Paste key | Copy from the email, paste here, click Activate |
| Activation status | Shows the license holder + expiry date (if time-limited) |
| Reset | Deletes the current key, the app goes into demo mode |
| Skipped update | Under App Info (since 1.14.1): shows a version dismissed with "Skip this version" plus a "Reset" button — afterwards it is offered again at the next check |
Demo mode
Without an activated key, some Pro features (auto-upload to QSL services, bulk operations, voice keyer recording) run limited or not at all. Details see Activate License.
Where are the settings stored?
All settings live in UserDefaults under ~/Library/Preferences/com.hb9hji.hamrechner.plist. Passwords (QRZ, HamQTH, eQSL, Club Log) are stored encrypted in the macOS Keychain.
When you move to a new Mac:
- Copy the data folder (
~/Documents/HAM-Tools/) — contains logs, caches, macros - Copy the plist (
~/Library/Preferences/com.hb9hji.hamrechner.plist) — contains settings without passwords - Re-enter passwords — the Keychain isn't copied automatically (unless via iCloud Keychain sync)
- Reassign CAT profiles if the serial port names differ