Settings

Interface refinements from 1.54.0

Settings cards and English labels have been improved. Collapsible Radio details retain their state. The operator settings explain that the current operator affects new QSOs; operators stored in existing QSOs remain unchanged.

1.53.0

Use Modules to show or hide shared module navigation; navigation adapts to narrow windows. The app language selected in Settings takes effect after restarting the app.

The settings window (⌘,) has fifteen 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
FreeDV	FreeDV Reporter: view or be visible, status message, stations into the DX cluster
Lookup & Upload	QRZ, HamQTH, eQSL, Club Log, LoTW, Wavelog, HRDLOG — everything QSL-related
External Loggers	Take QSOs from WSJT-X, JTDX, JS8Call, MSHV and N1MM into the logbook via UDP
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

---

Window and cluster from 1.52.0

Resize the window using an edge or corner, including after closing and reopening it with ⌘,. The Yaesu FTX-1 is listed without a Beta suffix.

Enable the POTA source under Cluster. Without it, the POTA checkbox in the logbook is disabled. FreeDV connection and spot forwarding can also be controlled using the info icon beside the logbook source filter.

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, 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.

Per-profile credentials in the Keychain from 1.46

Each profile's credentials are stored as separate entries in the macOS Keychain, not in the settings file. Delete a profile and its credentials go with it.

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–F8

Databases 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
LLOTA lakes	CSV import	~6.5k entries
WCA castles	CSV import	~20k entries
GMA summits	CSV import	~34k entries
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.

Transfer settings from 1.46 — for moving to another Mac: "Export …" packs all settings including the passwords and API keys from the macOS keychain into an .htsettings file, encrypted with a passphrase of your choice (AES-256, unrecoverable without the passphrase). On the target Mac: "Import …", restart the app, done. Logbooks (.htlog) are not included — copy them via the data folder above.

---

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/P for 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).

---

FreeDV from 1.47

Connection to FreeDV Reporter (qso.freedv.org) for the FreeDV module.

Setting	Effect
Connect automatically when the FreeDV module opens	connection starts as soon as the module is open
Sign-in: View only / Visible as station	view needs no callsign; visible reports callsign, locator and frequency to the Reporter
Status message	up to 80 characters of free text next to your callsign, only in "visible" mode
Feed online stations as spots into the DX cluster	stations and reception reports appear with source FreeDV in the spot list, bandmap and world map
Audio input from 1.48	device the RADE receiver takes the signal from — the radio's USB codec, as for SSTV and WSPR
Speech output from 1.48	device the decoded speech plays on — Mac speakers or headphones
Modem from 1.48	RADE V1 (default, on air) or RADE V2 (preview, not yet released by the FreeDV team)

Callsign and locator come from Station; "Visible as station" needs both, otherwise it stays in view mode.

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
HRDLOG.net from 1.46	Auto-upload per QSO via upload code (from your HRDLOG profile); backfill via right-click in the QSO table, dedicated status column. Being road-tested

Per service: API key/username/password + auto-upload toggle + "QSL sent via X" auto-mark. Since 1.46, passwords and keys live in the macOS keychain instead of the settings files — existing values migrate there automatically on first launch.

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

Other programs log into HAM-Tools: WSJT-X, JTDX, JS8Call, MSHV and N1MM Logger+ send every logged QSO via UDP, HAM-Tools listens on the configured port and writes it into the active logbook — including the log-type fields (POTA park, contest exchange …). This is how FT8 and FT4 QSOs get into the log without retyping.

Each entry is a listener with a port and a protocol. Several run in parallel as long as the ports differ.

Protocol	Default port	What arrives
WSJT-X / JTDX / JS8Call / MSHV / FreeDV GUI	2237 (JS8Call 2242, MSHV 2333)	Logged QSOs, status, decodes
N1MM Logger+ (contest)	12060	QSOs (ContactInfo) and spots — those go into the DX cluster stream

Setup:

• WSJT-X / JTDX: File → Settings → Reporting → UDP server 127.0.0.1, port as set in HAM-Tools, enable "Accept UDP requests" and the logged-QSO forwarding. JS8Call has the same dialog, MSHV has the option under UDP Broadcast Settings with logged-QSO broadcast.
• FreeDV GUI: Tools → Options → Reporting → Enable QSO Logging, host 127.0.0.1, port 2237 — uses the same bridge as WSJT-X. QSOs arrive as DIGITALVOICE with submode FREEDV.
• N1MM: Config → Configure Ports → Broadcast Data → tick Contacts and Spots, target 127.0.0.1:12060.
• If WSJT-X and MSHV run at the same time they need different ports, otherwise datagrams get lost.

The status pill per listener shows listening / linked (with datagram counter and program version) / error. A badge in the logbook bar mirrors the state.

Convenience for the WSJT-X family (applies app-wide):

Switch	Effect
Take active callsign into the QSO window	Double-clicking a station in WSJT-X immediately shows call, name, QTH and QRZ picture in the entry panel
Confirm logged QSOs in the entry window	After every QSO logged via WSJT-X the partner appears with callbook lookup and a "✓ logged" banner
Highlight FT8/FT4 spots in WSJT-X	Clicking an FT8/FT4 spot in the DX cluster highlights the callsign in the Band Activity window
Spot click starts a call in WSJT-X	If WSJT-X decoded the station recently, the spot click acts like a double-click on the decode line (needs "Accept UDP requests" in WSJT-X)

Receive only

HAM-Tools does not send QSOs via UDP to other loggers itself. For the other direction use the ADIF export.

---

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. All passwords and API keys (QRZ, HamQTH, LoTW, eQSL, Club Log, Wavelog, HRDLOG, QRZ Logbook, POTA/SOTA/WWFF/BOTA, Winlink) have lived in the macOS Keychain since 1.46 — the plist no longer contains any of them.

When you move to a new Mac:

1. Export settings: Settings → Data → Transfer settings → Export … — the .htsettings file contains all settings including the credentials from the Keychain, encrypted with your passphrase
2. Copy the data folder (~/Documents/HAM-Tools/) — contains logbooks, caches, macros
3. Install HAM-Tools on the new Mac, Import … the .htsettings file, restart the app
4. Check CAT profiles if the serial port names differ

Copying the plist is no longer enough

Before 1.46 it was enough to copy the plist and re-enter passwords. Now that the credentials live in the Keychain they only travel via the export — a copied plist gives you an app without any credentials.