Set Up the LoTW Pipeline

LoTW (Logbook of The World) is the official ARRL system for QSO confirmations and is accepted for most DXCC, WAS, and WAZ awards. HAM-Tools uses the official CLI tool TQSL as a subprocess — you keep full control over certificates and station locations.

Time: 30 minutes the first time, after that uploads run in seconds.

Prerequisites

• LoTW account at arrl.org/logbook-of-the-world (free, postal verification can take 1–2 weeks)
• HAM-Tools installed and license activated
• Internet connection

Phase 1 — Install TQSL.app (one-time)

HAM-Tools does not ship TQSL (ARRL licensing reasons). You install it yourself.

1. Download: lotw.arrl.org/lotw-help/installation/ → "TQSL for macOS" (currently 2.8.x)
2. Open the DMG, drag TQSL.app into the Applications folder
3. First launch: Gatekeeper complains ("unverified developer"). Right-click → "Open" → "Open anyway".

tqsl 2.5+

HAM-Tools supports both tqsl ≥ 2.5 (configs in ~/.tqsl/) and older versions (configs in ~/Library/Application Support/TrustedQSL/). You don't have to decide — the picker finds both.

Phase 2 — Request and Import the ARRL Certificate

1. In TQSL.app: Callsign Certificate → Request New Callsign Certificate
2. Enter your callsign, country/DXCC, license period
3. "Save Request" → creates a .tq5 file
4. Submit it to ARRL by email (linked at the end of the wizard)
5. ARRL mails a postcard to your license address with a verify code (that's why it can take 1–2 weeks)
6. After their reply: TQSL.app → Callsign Certificate → Load Certificate → load the .tq6 file ARRL emails you
7. When loading, you set a cert password — remember it!

The cert now lives in the macOS Keychain under TrustedQSL.

Phase 3 — Create a Station Location in TQSL

A station location describes where you operated (for LoTW's mapping of DXCC multipliers, US states, ITU/CQ zones).

1. TQSL.app → Station → Station Locations
2. Click "Add"
3. Click through the wizard:
   • Callsign: HB9HJI (your licensed call)
   • DXCC Entity: Switzerland / your country
   • CQ Zone: 14 (CH), ITU Zone: 28
   • Grid Square: your locator (e.g. JN47PN)
   • State / County: only relevant for W/VE
4. Assign a name: e.g. HB9HJI/HOME (shown in HAM-Tools)
5. "OK", the station is saved in ~/.tqsl/station_data.xml

Multiple stations

If you operate portable or abroad, create a separate location per site: HB9HJI/JN36, HB9HJI/M-Tuscany, HB9HJI/AM. HAM-Tools asks which location to use on upload.

Phase 4 — Link It in HAM-Tools

Now HAM-Tools comes into play.

1. Settings → Lookup & Upload (⌘, → "Lookup & Upload" tab)
2. Sub-picker at the top: choose "LoTW"
3. tqsl binary: default is /Applications/Tqsl.app/Contents/MacOS/tqsl — auto-detection should have found the path. If it's empty or the app is elsewhere: click the "📁 Browse…" button next to the field → in Finder just click Tqsl.app, and HAM-Tools fills in the binary path automatically. This also works with a Homebrew install (select /opt/homebrew/bin/tqsl directly).
4. Station location: open the dropdown → you'll see the locations from Phase 3. Pick your default location (e.g. HB9HJI/HOME)

Picker empty?

If the dropdown stays empty: the station location wasn't created in TQSL yet. Did you really finish Phase 3? Does ~/.tqsl/station_data.xml (or ~/Library/Application Support/TrustedQSL/station_data.xml) exist? Check in Terminal:

cat ~/.tqsl/station_data.xml
ls -la ~/Library/Application\ Support/TrustedQSL/

Phase 5 — Enable Auto-Upload

Three toggles in the LoTW section:

Toggle	Effect
"Automatically upload every logged QSO"	One TQSL call per QSO — recommended for home loggers
"After a successful upload, mark › QSL sent via LoTW ‹"	QSL status is set automatically — recommended
(Master) Real-time upload at the very top	If off, EVERYTHING is paused (for travel/portable without internet)

Phase 6 — Test the First Upload

1. Logbook → select a log, with at least 1 QSO in it
2. Select a QSO in the table (or several via ⌘-click)
3. Right-click → "LoTW: upload N QSOs"
4. Enter the cert password (from Phase 2)
5. Wait 5–30 seconds — the "LoTW" status column in the table shows a pill:

Pill	Meaning
🟡 Pending	Upload in progress
🟢 Sent	Successfully handed to LoTW
🔴 Failed	tqsl returned an error — diagnostic snippet in the alert
⚪ Confirmed	The other station uploaded their QSO too + it matched

Initially you'll only see 🟢 Sent — confirmation comes once the other station uploads on their end.

Phase 7 — Confirmation Sync

After a few days / weeks, some of the other stations have submitted their QSOs to LoTW too. Pull the confirmations:

1. Logbook → "QSL" tab at the top
2. Button "Fetch LoTW confirmations"
3. HAM-Tools fetches the LoTW report XML from arrl.org and matches it against your QSOs on call + band + mode + date
4. Confirmed QSOs go 🟢 → ⚪ Confirmed
5. The Awards tab shows the new confirmed counters

Frequency: once a week is enough

LoTW doesn't push confirmations in real time. A weekly sync covers 95%. If a DXpedition QSO matters (the DX operators often don't sync to LoTW until 6 months later), just wait.

Common Problems

"Station Location X could not be found"
→ Typo in the picker. Go to TQSL.app → Station Locations and check the exact name (case matters). Or reopen the picker in HAM-Tools — the dropdown shows the real names.

Cert password is asked for every time
→ That's intentional (security). Saving it would require Keychain item reuse, which we don't do — otherwise you couldn't separate personal/club/contest certs.

"tqsl: error: command-line option 'x' not recognized"
→ You have a very old TQSL version (< 2.5). Update to 2.7+.

Upload ends up in the "rejected" branch even though everything looks OK
→ The diagnostic snippet in the error alert opens the raw tqsl output. Common cause: the cert has expired (LoTW certs are valid for 3 years), or the mode label (e.g. FT8 vs. MFSK) isn't accepted by tqsl. Running tqsl manually in Terminal reproduces it.

Use eQSL/QRZ instead of LoTW
→ see Settings → Lookup & Upload. Each service has its own toggles, all can run in parallel.

What's Next

• Log Your First POTA QSO — if you haven't yet
• The POTA module and SOTA module read LoTW confirmations automatically for award tracking
• ARRL DXCC + WAS + WAZ awards can be applied for directly at ARRL once you have enough confirmations