Documentation

Everything you need to get up and running with ContestLogX.

1. Getting Started

Install Dependencies (Ubuntu/Debian)

sudo apt install cmake qt6-base-dev libqt6serialport6-dev libqt6xml6-dev

Build & Run

make        # build
./clx       # run

First-Time Setup

  1. On first launch, go to File → Settings and enter your callsign, name, and QTH.
  2. Download the DXCC database via File → Download cty.dat. This is required for DXCC multiplier scoring.
  3. Optionally download the Super Check Partial database via File → Download master.scp for callsign checking.
  4. Select a contest via File → New Log, choose your contest and station class, then fill in any required exchange information.

Supported Contests

ContestLogX ships with built-in modules for the following contests:

  • North American QSO Party (NAQP) — CW, SSB, RTTY
  • ARRL 10-Meter Contest
  • ARRL DX Contest
  • ARRL VHF Contest
  • CWops CWT (CW Mini Test)
  • EU DX Contest
  • Florida QSO Party (FQP)
  • Minnesota QSO Party (MNQP)
  • Virginia QSO Party (VAQP)
  • Winter Field Day
  • YB DX Contest
  • General DXCC (open-ended DXCC tracking)

Additional contests can be added by dropping a JSON definition file into the contests/ directory — no recompilation needed.

2. Rig Control via flrig

ContestLogX integrates with flrig for rig control. When connected, frequency and mode are polled automatically and reflected in the logging entry fields.

Setup Steps

  1. Start flrig and connect it to your radio.
  2. In flrig, go to Config → Server, enable the XML-RPC server, and note the port (default: 12345).
  3. In ContestLogX, go to Rig → flrig Connection.
  4. Enter localhost as the host and 12345 as the port, then click Connect.
  5. The status bar will show the current frequency and mode (e.g., 14025.0 CW), updated every 500 ms.

Troubleshooting

  • Connection refused: flrig is not running, or the XML-RPC server is not enabled.
  • Frequency shows 0: Check the port number and verify flrig is responding. You can test with:
    curl -X POST http://localhost:12345/RPC2 \
  -H "Content-Type: text/xml" \
  -d '<?xml version="1.0"?><methodCall><methodName>rig.get_vfo</methodName></methodCall>'
  • Debug mode: Run ./clx --debug and enable flrig debug messages from the Debug menu to see full XML-RPC traffic.

3. Logging a QSO

The entry row at the top of the log accepts QSO data. Fields vary by contest but always include callsign, frequency/band, mode, and exchange data.

Entry Workflow

  1. Type the callsign in the CALL field.
  2. Press Tab or Space to move to the next field. Call history and dupe checking run automatically.
  3. Fill in received exchange fields (RST, name, state, serial, etc.).
  4. Press Enter to log the QSO. The entry row clears and the QSO is appended to the log.

Sorting the Log

Click any column header to sort the log by that field — click again to reverse the order. The status bar shows the active sort (e.g., Sorted by CALL ▲). The sort resets to chronological order automatically when you start typing a new callsign.

Filtering the Log

Press Ctrl+F (configurable in Preferences → Shortcuts) to open the filter bar. Type any substring to narrow the log to matching QSOs — the search covers callsign, mode, exchange, comment, and frequency. The status bar shows Filter: N of M QSOs while a filter is active. Press Escape, click the clear button, or start typing in the entry fields to dismiss the filter.

Dupe Checking

Duplicate checking is contest-aware. Depending on the contest definition, dupes may be checked per-band, per-mode, per-band-and-mode, or across the whole contest. A visual indicator highlights duplicate callsigns before you log.

Score Display

The score widget updates in real time showing QSO count, multipliers, and total score broken down by band and mode. Multipliers are tracked as named mults (e.g., states/provinces), DXCC entities, grid squares, or ITU regions depending on the contest.

4. Call History & Exchange Autofill

ContestLogX maintains a persistent call history database. When you enter a callsign, exchange fields (name, state, QTH, CWops ID, grid, etc.) are automatically pre-filled from previous QSOs — across contests and sessions.

How It Works

  1. Enter a callsign and press Tab or Space.
  2. If the call is in history, matching exchange fields are auto-populated.
  3. Accept the values or type over them, then log as normal.
  4. On save (with auto-save enabled), operator data from all QSOs is merged back into history.

Managing History

Go to File → Manage Call History to:

  • Browse all stored records in a sortable table
  • Double-click or right-click any record to edit or delete it
  • Toggle call history insertion on/off
  • Toggle auto-save on/off
  • Clear all history

What Gets Stored

Static operator info is stored: name, QTH, state/province, CWops ID, grid square. Per-QSO data (date, band, RST, serial numbers, points) is never stored in history.

5. CW & SSB Memories

ContestLogX supports eight programmable message memories (F1–F8). CW messages are sent via your keyer interface; SSB messages use the system text-to-speech (TTS) engine — no audio recordings to manage.

Token Substitution

Both CW and SSB memories support token substitution. The following tokens are expanded at send time:

  • {CALL} — callsign in the entry field
  • {MYCALL} — your station callsign
  • {SN} / {SNs} / {serial} — next outgoing serial number

For SSB memories, {CALL} and {MYCALL} are automatically converted to NATO phonetics before being sent to TTS (e.g., "Kilo One Alpha Bravo Charlie"). CW memories send the expanded text literally.

Station vs. Contest Memories

Each memory type (CW and SSB) has two independent sets of eight slots:

  • Station Memories — global, shared across all contests
  • Contest-Specific Memories — saved inside the .clx log file, specific to one contest log

The active set is shown in the status bar as a clickable button (Station Memories or Contest Memories). Click it to toggle, or use the Ctrl+T keyboard shortcut (configurable in Preferences → Shortcuts). The choice is saved with the log file and restored when you reopen it.

Edit each set independently from Settings → CW Memories or Settings → SSB Memories using the Station Memories / Contest-Specific Memories radio buttons at the top of the editor.

Halting a Transmission

Press Escape at any time to immediately stop CW sending or cancel a TTS (SSB) voice message in progress. Works whether the QSO entry dock is docked or floating.

CW Serial Number Formatting

The CW Memories editor includes options for the {SN} token:

  • Minimum digits — pad with leading zeros: 1 digit (e.g. 7), 2 digits (e.g. 07), or 3 digits (e.g. 007)
  • Cut numbers — substitute traditional CW abbreviations: 0→T, 9→N, 1→A

Typical Memory Layout

F1  CQ TEST N9OH N9OH
F2  {CALL} 5NN {SN}
F3  TU N9OH
F4  {CALL}
F5  ?
F6  AGN?
F7  QRZ?
F8  N9OH

6. Run & Search and Pounce Modes

ContestLogX supports two operating modes that change how the Enter key sequences through a contact — so you can work a full QSO without touching the mouse or the F-keys.

Selecting a Mode

Use the RUN and S&P buttons in the QSO entry bar, or assign a keyboard shortcut to Toggle Run / S&P Operating Mode in Preferences → Shortcuts.

Memory Roles

For the Enter sequence to work you must assign roles to your memory slots. Open the CW or SSB Memories editor and set the Role column for each relevant memory:

  • CQ — your CQ call (e.g. CQ TEST {MYCALL})
  • My Call — your callsign, sent when answering a running station (e.g. {MYCALL})
  • Run Exch — exchange sent in Run mode; typically starts with the caller's callsign (e.g. {CALL} 5NN {SN})
  • S&P Exch — exchange sent in S&P mode; your part only, no callsign needed (e.g. 5NN {SN})
  • TU — sign-off after logging in Run mode (e.g. TU {MYCALL} TEST)

Memories without a role work exactly as before — press the F-key to send them at any time. At most one memory per role is used; if multiple are tagged with the same role the first match wins.

Run Mode — Enter Sequence

Use Run mode when you are calling CQ and stations answer you.

  1. Call box empty → Enter sends the CQ memory.
  2. Call filled → Enter sends the Run Exch memory and waits for the caller's exchange.
  3. After receiving exchange, Enter again sends the TU memory and logs the QSO.

Search & Pounce Mode — Enter Sequence

Use S&P mode when you are tuning the band and calling a running station.

  1. Call filled → Enter sends the My Call memory so the running station hears you.
  2. After copying their exchange → Enter sends your S&P Exch memory and logs the QSO.

Notes

  • The Enter sequence resets each time a QSO is logged or the entry form is cleared.
  • You can always press F-keys directly — the mode only affects the Enter key behaviour.
  • If no memory is tagged with the required role for the current step, Enter does nothing for that step (a warning is written to the debug log).

7. DX Cluster

ContestLogX includes a built-in DX cluster client. Open it from Window → DX Cluster. Spots appear in real time and expire automatically after 15 minutes.

Connecting

  1. Enter a cluster address in host:port format (e.g. dxc.k0xm.net:7300) or select one from the dropdown.
  2. Click Connect. ContestLogX will auto-login using your configured callsign.
  3. Spots populate automatically; propagation data (SFI, A, K index) is also parsed and displayed in the status bar.

Band Filter

Use the band dropdown (to the right of the Auto-scroll checkbox) to show only spots on a specific band. Selecting ALL removes the filter. The band list is populated from the contest definition currently loaded — it updates automatically when you switch contests.

Clicking a Spot

Click any spot row to tune your rig to that frequency and pre-fill the callsign in the entry field. The spot is removed from the list once you log the QSO.

Spotting Your Last QSO

Click Spot Last QSO to pre-fill the cluster command field with a dx command for the most recently logged contact. Edit if needed, then press Enter to send.

Band Map

When the DX cluster is connected, spots are also fed to the visual Band Map panel. See Section 8 — Band Map for details.

8. Band Map

The Band Map displays DX cluster spots as labeled markers on a horizontal frequency axis, giving you a spatial overview of activity on the current band. Open it from Window → Band Map. The panel is a dockable, floatable window — drag it anywhere or float it on a second monitor.

Color Coding

Each spot marker is color-coded so you can instantly prioritize where to point your antenna without reading the callsign list.

Orange — New Multiplier

This station would add a multiplier you haven't worked yet. ContestLogX checks whether the station's DXCC entity already appears anywhere in your log — if not, the spot is orange. These are your highest-priority targets: working them increases both your QSO count and your multiplier total.

Blue — Unworked, Not a New Multiplier

You haven't worked this station yet, but their DXCC entity is already in your log on this band. Worth working for the QSO point, but won't add to your multiplier count. These are your bread-and-butter contacts — move quickly and keep the rate up.

Gray — Already Worked

This callsign is already in your log. Depending on the contest's dupe rules (per-band, per-mode, or overall), working them again may not count. Gray spots fade into the background so your eye is drawn to orange and blue first.

Colors update automatically the moment you log a QSO or run Contest → Recalculate Score — a freshly worked orange spot turns gray without disappearing from the map.

Click to QSY

Click any spot marker to tune your rig to that frequency and mode — same behavior as clicking a row in the DX Cluster panel. The callsign is also pre-filled in the entry field.

Zoom & Pan

  • Scroll wheel — zoom in/out centered on cursor position
  • Zoom slider — drag the slider at the top of the panel to adjust the visible frequency range
  • Click-drag — pan the view left or right
  • Zoom and pan reset to full-band default whenever you change bands

VFO Line

When rig control is connected, a green vertical line shows your current VFO frequency on the band map, updating in real time as you tune.

Spot Expiry & Limits

  • Spots expire automatically after 30 minutes by default.
  • A maximum of 30 spots are displayed at a time; the oldest spot is evicted when the limit is reached.
  • Both thresholds are configurable via QSettings keys BandMap/ExpiryMinutes and BandMap/MaxSpots.

Band Changes

Changing bands (as detected from the rig frequency) automatically clears all spots and resets the viewport to full-band zoom. The "No cluster" indicator appears in the top-right corner if the DX cluster connection is lost; existing spots remain visible until expiry.

9. Importing & Exporting Logs

ContestLogX supports both import and export for Cabrillo and ADIF formats.

Export

  • Cabrillo — standard format for contest submission to sponsors (ARRL, CQ, etc.)
  • ADIF — standard format for uploading to Logbook of the World (LoTW), QRZ, eQSL, and others

Access via File → Export and choose the desired format.

Import

Existing logs in Cabrillo or ADIF format can be imported into ContestLogX via File → Import. This is useful for migrating logs from other software or re-scoring old contest logs.

Cabrillo import is preferred over ADIF for contest logs. ADIF is a general-purpose format and does not have standard field names for contest-specific exchanges (e.g., state, serial number, power category). ContestLogX can only map a small set of well-known ADIF fields; non-standard fields used by other loggers are not recognized, and contest exchange fields will often be empty after an ADIF import.

Cabrillo files contain the exchange data in a structured, contest-specific format and import cleanly. If your logging software can export both formats, use Cabrillo for importing contest logs into ContestLogX.

10. Creating Custom Contest Modules

Every contest in ContestLogX is defined by a JSON file in the contests/ directory. You can add support for any contest — including regional and club-sponsored events — by creating a new JSON file. No recompilation is needed.

→ Full Contest Module Format Reference — complete field-by-field documentation with examples from all built-in contest modules.

File Structure Overview

{
  "contest": {
    "name": "My Contest",
    "abbreviation": "MYC",
    "modes": ["CW", "SSB"],
    "bands": ["40m", "20m", "15m", "10m"]
  },
  "frequencies": { ... },
  "stationClasses": { ... },
  "exchangeFields": { ... },
  "scoring": {
    "qsoPoints": { ... },
    "multipliers": [ ... ],
    "finalScore": "SUM(points) * namedMults"
  },
  "validation": {
    "namedMults": ["CA", "OR", "WA", ...]
  },
  "dupeChecking": { ... }
}

Multiplier Types

  • namedMults — exchange field values validated against a list (e.g., US states, ARRL sections)
  • dxccMultipliers — DXCC entities, scored once per contest or once per band
  • ituRegions — ITU regions per band
  • namedCallPrefixes — specific callsign prefixes (e.g., YB0–YB9)
  • gridSquareMultipliers — Maidenhead grid squares per band (used in VHF contests)

Multiplier Scope

  • multsOnce — counted once for the whole contest
  • multsPerBand — a new multiplier on each band
  • multsPerMode — a new multiplier on each mode
  • multsPerBandAndMode — a new multiplier per band/mode combination

QSO Scoring Rules

Points are assigned based on the geographic relationship between stations. Rules are evaluated in the order listed in the precedence array — the first match wins.

"qsoPoints": {
  "sameDxccEntity":     { "CW": 1, "SSB": 1 },
  "sameContinent":      { "CW": 2, "SSB": 1 },
  "differentContinent": { "CW": 3, "SSB": 2 }
},
"precedence": [
  "sameDxccEntity",
  "sameContinent",
  "differentContinent"
]

Final Score Formula

A formula string in the scoring.finalScore field controls how the final score is calculated, e.g.:

"finalScore": "SUM(points) * (namedMults + dxccMultipliers)"

Installing a New Module

Drop your .json file into the contests/ directory next to the application, then restart ContestLogX. Your contest will appear in the File → New Log dialog.

11. CLX File Format

ContestLogX saves logs in the .clx format — a human-readable JSON file that is easy to inspect, back up, and version-control. It stores all contest and station metadata alongside the full QSO list.

Top-Level Structure

{
  "metadata": {
    "contestFile": "naqp.json",
    "stationClass": "SO_UNASSISTED_CW",
    "version": "1.0"
  },
  "station": {
    "callsign": "N9OH",
    "name": "Steve",
    "qth": "FL"
  },
  "categories": { ... },
  "qsos": [ ... ]
}

Because .clx is plain JSON, you can inspect it in any text editor, query it with jq, or import it into scripts for post-contest analysis.

12. Data Files & Storage Locations

User Data

Linux:   ~/.local/share/ContestLogX/
macOS:   ~/Library/Application Support/ContestLogX/
Windows: %APPDATA%\ContestLogX\
  • cty.dat — DXCC database (download via File → Download cty.dat)
  • master.scp — Super Check Partial callsign database (optional, download via File → Download master.scp)
  • history.json — call history records (auto-maintained)

Configuration

Linux:   ~/.config/ContestLogX/ContestLogX.json
macOS:   ~/Library/Preferences/ContestLogX/ContestLogX.json
Windows: %APPDATA%\ContestLogX\ContestLogX.json

Application settings including rig connection details, call history preferences, and window layout are saved here automatically.

Debug Logging

Run with ./clx --debug --log <logfile.clx> to enable verbose logging to clx_debug.log in the current directory. Useful for diagnosing rig control and scoring issues.