Skip to content

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

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!

TQSL stores the cert in its own data folder (~/.tqsl, older versions ~/Library/Application Support/TrustedQSL), not in the macOS Keychain.

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 always uploads with the location selected in Settings (Phase 4) — switch it there before uploading from a different site.

from 1.56 A log's own locator does not

apply to LoTW: here the TQSL station location determines the site (and thus MY_GRIDSQUARE).

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 "📁 Search…" 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:

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

Phase 5 — Enable Auto-Upload ​

Three toggles in the LoTW section:

ToggleEffect
"Automatically upload every logged QSO"One TQSL call per QSO — recommended for home loggers. Only applies to standard logs (DX)
"Mark »QSL sent via LoTW« after successful upload"Additionally records the general QSL sent status (date + "LOTW") unless one is already present — recommended. Up to 1.56 the switch had no effect from 1.57
"Real-time upload (master)" at the very topIf 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 → "Upload to LoTW (tqsl)" (for several: "Upload N QSOs to LoTW (tqsl)") — all selected QSOs go out in a single tqsl call
  4. If your certificate has a password (Phase 2), tqsl asks for it in its own window — HAM-Tools doesn't store it
  5. Wait 5–30 seconds — an alert reports the result ("N QSOs uploaded to LoTW" with new / duplicates / errors, or "LoTW upload failed" with the end of the tqsl output). Afterwards the "QSL status" column in the table shows:
DisplayMeaning
LoTW → (row yellow)Successfully handed to LoTW
LoTW ✓ (row green)The other station uploaded their QSO too + it matched

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

from 1.56 The upload status always lands in

the log the QSO comes from — even if you open another log while the upload is running.

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. One-time: Settings → Lookup & Upload → LoTW, section "Confirmation sync (LoTW web login)" — enter the Username and Password of your lotw.arrl.org account (not the cert password from Phase 2)
  2. Logbook → "QSL" tab in the bottom tab bar
  3. Button "Fetch LoTW confirmations" (the same fetch sits behind "Retrieve confirmations now" in Settings)
  4. HAM-Tools fetches the LoTW report (ADIF) from arrl.org and matches it against the QSOs of the open log on call + date/time (to the minute)
    • band + mode; an alert shows how many confirmations were matched and how many are new
  5. Confirmed QSOs change from LoTW → to LoTW ✓ in the "QSL status" column
  6. The Awards tab shows the new confirmed counters

Matching reliable only from 1.56 from 1.56

Up to 1.55 the fetch found no confirmations because of a parser bug. If you fetched in vain before, simply fetch again now. From 1.57 the sync checks all logbooks, not only the open one; unreadable logbooks are named in the result from 1.57.

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 error alert contains the end of the raw tqsl output ([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.

Some QSOs rejected — and none is marked as sent from 1.56
→ If LoTW rejects individual QSOs in a batch upload (or tqsl only processes part of it), HAM-Tools no longer marks any of the QSOs as sent — up to 1.55 they could all count as uploaded. Fix the rejected QSOs using the tqsl output and upload the selection again; LoTW then reports the ones already accepted as duplicates.

"tqsl did not respond within 180 s and was terminated" from 1.56
→ HAM-Tools aborts a hanging tqsl call after 180 seconds. Check your internet connection and the LoTW status, then upload again.

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

HAM-Tools © HB9HJI · Funkwelt