Settings
The settings window (⌘,) has fourteen areas, sorted into four groups in a sidebar on the left: General, Radio, Data & Services and Tools. Each area configures a clearly defined part of the app. This page is the hub — several areas (Station, CAT, Rotor, Lookup & Upload, Macros, License) have their own step-by-step guides in Tutorials.
Sidebar instead of a tab bar from 1.40.3
Up to 1.40.2 the areas sat in a tab bar. With fourteen areas it no longer fitted the window — the last two slid into a » menu that could not be clicked, which made the License area unreachable. A sidebar cannot overflow: it scrolls.
| Area | What for |
|---|---|
| Station | Your own callsign, locator, canton, app callsign license |
| Operators | Several operators at one station — profiles with their own call, credentials and logbook |
| Data | Data folder path, POTA/SOTA/WWFF/BOTA/LLOTA/WCA/GMA databases, SCP sources |
| CAT | Connection (USB / IC-705 WLAN / Network), TRX profile, serial port, baud, Hamlib subprocess status |
| Rotor | Antenna rotator via rotctld (USB / network), 22 model profiles, calibration, spot-click tracking |
| QTH locator | Elevation model, units, vegetation allowance, sample count and map cache of the QTH locator module |
| Winlink | Winlink account (password in the keychain), CMS server, radio transports (ARDOP/VARA), signatures |
| Cluster | Manage DXSpider nodes, spotter radius |
| Lookup & Upload | QRZ, HamQTH, eQSL, Club Log, LoTW, Wavelog — 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.
Operators
When several hams share a station (family, club station, contest team), each person can have their own profile. A profile bundles identity, credentials and logbook — everything moves along when you switch.
Multi-operator only
If you operate solo, there's nothing to do here: a default profile is created automatically from your existing settings. The tab and the quick switch only become relevant once you create a second profile — single-user behaviour is unchanged.
A profile contains:
| Area | Content |
|---|---|
| Identity | Callsign, name, locator, QTH |
| Lookup | own QRZ and HamQTH credentials |
| Upload | own accounts for QRZ Logbook, LoTW, eQSL, Club Log, Wavelog, HRDLOG, QRZCQ, HamCall, POTA/SOTA/WWFF/BOTA |
| Logbook | the standard logbook assigned to the operator |
How it works:
- Create/manage: at the top of the tab you pick the active profile and create new ones — "New" starts with empty credentials (so you don't accidentally hand over your accounts), "Duplicate" copies the current ones as a basis.
- Default profile (⭐): exactly one profile is the default and active after every app launch — so you reliably land on yourself, never accidentally in someone else's profile.
- Switching while operating: once two profiles exist, a quick switch (👥) appears in the logbook bar. One click changes the callsign, all credentials and opens the operator's logbook.
- Separate logbooks: switching opens the log assigned to the profile automatically and stamps QSOs with its fixed callsign — so contacts stay separated per person and auto-uploads go to the right account. The default profile inherits your existing log; a new guest profile automatically gets a fresh one.
A licence for multiple callsigns
A licence can contain several callsigns — each profile using one of them runs the full version. So for a multi-operator station, request one licence with all calls. If a profile carries a callsign not covered by the licence, a notice makes it clear (that profile then runs in demo mode).
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.
Rotor
Antenna rotator control via Hamlib (rotctld) — HAM-Tools ships with a bundled rotctld helper binary (SPID, Yaesu GS-232, Hy-Gain, Green Heron, EA4TX, Prosistel, M2 and more, plus satellite az/el).
Connection ("Connection" picker):
| Connection | Fields |
|---|---|
| USB (Serial) | Standard — HAM-Tools starts its own rotctld on the serial port (fields below). Loopback-only (127.0.0.1) |
| Network (rotctld) | Host + Port of an already-running rotctld server (standard port 4533), e.g. a remote rotator on the LAN |
Fields (USB connection):
| Field | Description |
|---|---|
| Rotor profile | Manufacturer + model from 22 curated profiles (rotor-profiles.json) — automatically selects the Hamlib rotor no., default baud, serial parameters and az/el capability |
| USB port | /dev/cu.usbserial-* etc. — auto-detected via dropdown (🔄 refreshes) |
| Baud / data bits / stop bits / parity / handshake | preset by the profile, overridable |
| North offset / rotation range | calibration in degrees; rotation range e.g. 0–450 for overlap |
| Use elevation | only on az/el models |
| Poll interval | how often the live azimuth is read (default 1000 ms) |
| Spot-click tracking | switch "Turn to the bearing automatically on spot click" — turns the antenna to the great-circle bearing to the DX station |
What happens after a successful connection:
- Live azimuth on the compass rose + manual target via slider/"Turn"
- "Stop" halts a running rotation immediately
- With spot-click tracking on, a DX cluster spot click turns the antenna to the bearing (source: your own station locator + the DXCC location of the spot)
Several rotator configurations can be saved (one per rotator), switched via the "Active config" picker.
Rotor tutorial
Step-by-step setup with a USB adapter, driver check, calibration and spot click: Tutorials → Rotor Setup. Full module docs incl. the model table: Rotor / Antenna Control.
QTH Locator from 1.38
Settings for the QTH Locator module — line of sight, terrain profile and map. Four sections:
Units
| Field | Description |
|---|---|
| Distance | km or miles |
| Height | metres or feet |
| Locator | number of digits in the displayed Maidenhead locator (4 / 6 / 8 / 10) |
Own QTH — locator and station name come from Settings → Station and are only displayed here. With no locator set there, the home button in the module has nowhere to jump to.
Defaults for new stations — the antenna height and band a newly placed station starts with. Saves retyping them on every path.
Calculation
| Field | Description |
|---|---|
| Sample points | 64–512 elevation queries per path. More points draw finer terrain but cost queries and time |
| Refraction | Standard (k = 4/3) matches normal radio propagation; purely geometric (k = 1), inversion (k = 2) and flat earth (k = 0) are there for comparison |
| Clutter allowance | Elevation models return bare ground. The allowance adds forest and buildings — it only applies when switched on in the profile |
Elevation data — source of the terrain heights:
| Source | What for |
|---|---|
| swisstopo (Switzerland) | The finest for Switzerland — Säntis measures 2501 m here instead of 2399 m from Copernicus (2502 m in reality). Outside the national survey it falls back to Open-Meteo |
| Open-Meteo (90 m) | Copernicus DEM, fast, pleasant for long paths |
| OpenTopoData (30 m) | SRTM 30 m, finer in terrain, at most one request per second |
Below that: how many elevation points are cached, with a button to clear the cache.
Map — size of the tile cache and a button to clear it. Cached tiles stay visible without a connection — and every cached tile is one request less to a volunteer-run server.
Winlink
Configuration of the Winlink module (email over amateur radio):
- Station: callsign and locator are taken from the Station tab automatically; the fields here normally stay empty. An entry applies to Winlink only (e.g.
HB9HJI/Pfor portable operation). - Winlink account: the password is stored exclusively in the macOS keychain — never in files or preferences.
- Connection (telnet): CMS server and port. “Production” is
server.winlink.org; the “test server” (cms-z.winlink.org) is suitable for connection tests but does not deliver anything. - Radio: VARA / ARDOP / PTT via rigctld from 1.34: modem endpoints and PTT. For the integrated ardopcf: audio devices (the rig’s USB codec), PTT mode (CAT CI-V / RTS / rigctld / VOX), serial port, CI-V address and baud rate. Details and step-by-step setup: Winlink module → Radio operation.
- Drive level + level assistant from 1.40: a slider for the audio sent to the radio, plus an assistant that sets it via a two-tone signal against the rig's ALC — see Winlink module → Drive level.
- Restore frequency after the session from 1.40.2: off (the default) leaves the rig on the gateway's channel after the exchange, so the next call runs without retuning — see Winlink module → Staying put after the session.
- Gateway directory from 1.39: daily refresh on/off, search radius (300–3000 km), list age and an immediate fetch. The list comes from the Winlink web services and is fetched at most once a day. The directory itself opens with ⌥⌘G — see Winlink module → Gateway directory.
- Signatures from 1.34: create signatures and choose a default — it is inserted into every new message.
The Winlink data (messages as .b2f files, session logs) lives in the data folder under HAM-Tools/Winlink/.
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 |
| Wavelog | Real-time upload to self- or DARC-hosted instances; "Test connection" loads the station profiles from the server, API key in the keychain; the only service that also transfers contest/outdoor logs |
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