FAQ — Frequently Asked Questions

General

Which Macs does HAM-Tools run on?

macOS 14 (Sonoma) or newer — tested up to macOS 26 (Tahoe), so macOS 15 (Sequoia) and 26 too. Both Apple Silicon (M1+) and Intel. The app is built as a Universal Binary.

macOS 12 / 13 are not supported

On older systems you'll see "You can't use this version of the application with this version of macOS". Reason: the app uses SwiftUI APIs from macOS 14 (MapKit DSL, the new onChange signature). macOS 14 is a free Apple update for every Mac from model year 2018 onward.

Do I need internet?

No. For DX Cluster and POTA/SOTA spots, yes — for everything else (logbook, calculators, Cabrillo export, CAT), no. License validation runs offline (signed).

Where is my data stored?

~/Documents/HAM-Tools/:

• Logs/ — all .htlog files (SQLite)
• Exports/ — ADIF + Cabrillo + license backups
• Cache/ — callbook cache + spot history

Is the app available in English?

Yes — since 1.12.0 the entire interface is translated into English. Switch under Settings → Appearance → Language (System / Deutsch / English) — applied live, no restart needed.

License

How do I get a license?

Email hb9hji@funkwelt.net with your callsign + name. You'll receive a license string to activate in the app.

What happens after 12 months?

Your current app version keeps running indefinitely. Only app versions released after your update deadline date need an update extension (request it like the initial license).

Can I use the license on two Macs?

Yes, as long as both Macs use the same callsign from the licensed callsigns. Just enter the license string on both Macs.

Logbook

Where are my log files?

~/Documents/HAM-Tools/Logs/*.htlog. They're regular SQLite databases — you can open them with any SQLite tool if you want to dig in forensically.

How do I back up my logs?

A standard Time Machine backup is enough. Plus an ADIF export per log as a secondary backup.

Can I import old logs?

Yes — ADIF import creates a new log with all QSOs from the file.

Accidentally deleted a QSO — can I undo it?

Currently not directly in the app. Use the Time Machine backup or an ADIF re-import.

Contest

Which contests are prepared?

39 templates — HF DX (CQ-WW & CQ-WPX CW/SSB/RTTY, ARRL-DX CW/SSB, ARRL RTTY Roundup, IARU-HF, WAE-DX, DARC-WAG, RUS-DX, All Asian DX, JIDX, REF, SAC, EU-HF-Champ, EUCW/UFT …), national HB contests (Helvetia, Field Day, 50 MHz, NMD, Christmas Contest, SEC) and the complete VHF/UHF block (IARU R1 VHF/UHF, DARC-UKW, Helvetia-VHF, Marconi, AGCW, Alpe-Adria).

Are all contests scored?

Yes — all 39 templates have their own, rules-compliant scoring (points + multipliers, or km distance for VHF/UHF), shared with MacADIF through the ADIFCore library. The engine is still being tested and hasn't been cross-checked against official result lists for every contest — verify your final score before submitting. For IARU-HF scoring, your own CQ/ITU zone must be set in the station settings.

Can I define my own contests?

Not yet. Stage 3 brings a user overlay folder for your own contests.json entries.

Where does the Cabrillo output go?

~/Documents/HAM-Tools/Exports/<Contest-ID>-<Date>.cbr. When you click "Export" it's also opened directly in Finder.

CAT

My radio isn't detected — help?

Most common causes:

1. Wrong CI-V address (on ICOM) — check the default in Settings and the radio menu
2. Port is taken by another app (WSJT-X, fldigi, etc.) — close the other app, or better yet use "Share CAT" (see the next question) so both run in parallel
3. Missing USB cable driver — install the FTDI driver for no-name cables

Test with the "Hamlib Dummy Rig" profile — if that connects, Hamlib is fine and the issue is your hardware config.

PTT control?

Yes — it's used by the contest macros F1–F8 for SSB playback: HAM-Tools calls setPTT(true) before audio starts and setPTT(false) in the onFinish callback. Works with all TRX profiles that have supportsPTT: true in trx-profiles.json (all modern ICOMs, Yaesus, Kenwoods, Elecrafts).

If that's not enough (e.g. exotic TRX models): use an external PTT interface via VOX or a footswitch.

Can I run HAM-Tools alongside WSJT-X (or fldigi)?

Yes — since 1.10.8 via "Share CAT": in Settings → CAT, enable the switch "Keep rigctld open for other programs". HAM-Tools then keeps its built-in Hamlib server open locally, and WSJT-X & Co. attach to it in parallel. In WSJT-X set: Rig = Hamlib NET rigctl, Network Server = 127.0.0.1:4532, PTT = CAT. Order: first "Start" in HAM-Tools, then connect WSJT-X. The server stays open even if you disconnect HAM-Tools' own CAT connection — a running WSJT-X session won't drop. If you also turn on "Band follows TRX" in the DX Cluster, the spot list, map and filters follow along automatically on a WSJT-X band change.

Yaesu: Why does the TUN button turn the tuner off instead of tuning?

The TUN pill only toggles the tuner on/off. For a real tuner match, since 1.10.8 there's a separate TUNE button (modern Yaesu via AC002;). On rigs without a CAT-controllable tuner (FT-817/857/897) it's hidden.

IC-705 over WLAN — do I need wfview or kappanhang?

No. Since 1.13.0 HAM-Tools speaks the Icom network protocol (RS-BA1) natively: in Settings → CAT, choose "IC-705 WLAN" in the "Connection" picker, enter the radio IP + network user + password, done. Frequency, mode, S-meter, PTT and QSY work wirelessly; HAM-Tools deliberately does not stream audio (WSJT-X & Co. remain usable externally). Guide: Tutorial: Connect the IC-705 over WLAN.

Can I attach HAM-Tools to an existing rigctld?

Yes — since 1.13.0 via the "Network (rigctld)" connection: enter the host + port of an already-running rigctld server (e.g. from wfview/kappanhang, often port 4533) — HAM-Tools then starts no subprocess of its own but docks onto it. Handy when another tool holds the radio connection or the radio is on a shack PC on the LAN.

My radio isn't detected — detailed guide?

→ Tutorial: CAT Setup — from USB driver check through the TRX profile to rigctld diagnostics.

DX Cluster

Can the app notify me when a DXpedition goes QRV?

Yes — since 1.12.1: the DX Cluster has a DXpeditions tab with the NG3K ADXO list (~40 active and planned expeditions). Each entry can be enabled — when a watched DXpedition is spotted within its QRV window, you get a macOS notification and the spot gets a cyan ✈ symbol in the spot list and the logbook DX tab. Details: DX Cluster → DXpedition Alerts.

QSL Services (QRZ / eQSL / Club Log / LoTW)

Which QSL services does HAM-Tools support?

Four in parallel: QRZ.com live upload, eQSL.cc auto-upload, Club Log live upload and LoTW via tqsl subprocess. Each with its own auto-upload toggle + "QSL sent" auto-mark. Configuration under Settings → Lookup & Upload.

Do I need anything extra for LoTW?

Yes — TQSL.app from the ARRL must be installed (for license reasons HAM-Tools can't bundle TQSL). Full guide: Tutorial: Set up the LoTW pipeline.

Travel mode — pause all uploads?

In Settings → Lookup & Upload there's a master toggle "Real-Time Upload" right at the top. When off, ALL auto-uploads (QRZ, eQSL, ClubLog, LoTW) are paused. After your trip, turn it back on → bulk-upload all pending QSOs via right-click on the table.

Pull QSO confirmations?

QSL tab in the logbook → buttons "Fetch QRZ confirmations" and "Fetch LoTW confirmations". Confirmations are matched against your QSOs on call+band+mode+date and marked as Confirmed.

Contest — Macros, Multi-Op & Audio

Set up F1–F8 macros?

→ Tutorial: Contest with F1–F8 macros — CW templates, SSB voice recordings, ICOM voice keyer (V1–V4) and Yaesu (V1–V5).

Multiple operators on the same log?

→ Tutorial: Multi-Op Contest.

Microphone permission denied

On your first SSB recording attempt macOS asks for permission. If denied: System Settings → Privacy & Security → Microphone → tick HAM-Tools, restart the app.

Update System

How do I know an update is available?

At app launch (max once per 24h) the app automatically checks a signed JSON manifest at toolbox.funkwelt.net/app/updates.json. Plus ⌘⌥U for a manual check.

Since 1.14.0 the update dialog can install directly: "Install now" downloads the DMG with a progress bar, verifies the SHA-256 from the signed manifest, swaps the app and relaunches — "Download in browser" remains available as an alternative.

How is it guaranteed that the update really comes from HB9HJI?

The update manifest is Ed25519-signed. The public key is baked into the shipped app — if someone injects a foreign manifest or DMG URL, signature verification fails and the update is discarded.

"Critical updates"?

The manifest field critical: true blocks the "Skip" button in the update dialog. It's only used for genuine security/crash hotfixes, not for every feature version.

Roll back updates?

Since the privacy cleanup in V1.9.7, older DMGs are no longer kept publicly available — they contained hardcoded author defaults (HB9HJI as cluster login, JN47PN as QTH locator) that would have become active on first install. If you need a rollback (e.g. a new version crashes), send a quick email to bugs@funkwelt.net — the older version then comes ad hoc.

macOS Security & Notarization

On first open: "HAM-Tools is damaged"?

This no longer happens since V1.9.0 — the app has been Apple- notarized since then (Developer ID + Hardened Runtime + notary ticket). A double-click opens the app directly.

If you have an older DMG and the message appears: right-click → "Open" → "Open anyway", or Terminal:

sudo xattr -dr com.apple.quarantine /Applications/HAM-Tools.app

Recommendation: update to the latest version.

Does Gatekeeper / XProtect cause trouble?

It shouldn't — notarization takes care of that. If it does (e.g. an enterprise Mac with a strict MDM policy): logs under Console.app → "amfid" and email bugs@funkwelt.net.

More questions?

Report a bug or email bugs@funkwelt.net with your question.