Documentation

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:

• ARRL 10-Meter Contest
• ARRL DX Contest
• ARRL VHF Contest
• CWops CWT (CW Mini Test)
• EU DX Contest
• Florida QSO Party (FQP)
• Georgia QSO Party (GAQP)
• Japan International DX Contest (JIDX)
• Louisiana QSO Party (LAQP)
• Michigan QSO Party (MIQP)
• Minnesota QSO Party (MNQP)
• Mississippi QSO Party (MSQP)
• Missouri QSO Party (MOQP)
• New Mexico QSO Party (NMQP)
• North Dakota QSO Party (NDQP)
• North American QSO Party (NAQP) — CW, SSB, RTTY
• OK-OM DX Contest
• Russian DX Contest (RDXC)
• SP DX Contest
• 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.

Rig Control

ContestLogX supports three rig control backends. Choose the one that fits your setup in Rig → Rig Connection.

Option A — flrig (recommended)

flrig provides full rig control including frequency, mode, CW keying, PTT, power, and bandwidth. This is the recommended backend for CW operators.

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 → Rig Connection, select flrig (XML-RPC) as the backend.
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.

Option B — Hamlib (rigctld)

Hamlib supports over 400 radio models via the rigctld network daemon. It provides frequency and mode control; CW keying and some other features depend on individual rig support and are unavailable for most radios.

1. Find your rig model number

rigctl -l | grep -i alinco
# Example output:
# 17001  Alinco     DX-77        0.6     Stable      RS-232

2. Start rigctld

Use the model number, serial port, baud rate, and any rig-specific options:

rigctld -m 17001 \
  -r /dev/serial/by-id/usb-FTDI_FT232R_USB_UART_FTHJCZ32-if00-port0 \
  -s 9600 \
  --set-conf=post_write_delay=200,timeout=800

Common options:

• -m — rig model number (from rigctl -l)
• -r — serial device path
• -s — serial baud rate
• -t — TCP port for ContestLogX to connect to (default: 4532)
• --set-conf — rig-specific tuning (timeouts, write delays, etc.)

3. Connect ContestLogX

1. Go to Rig → Rig Connection, select Hamlib (rigctld) as the backend.
2. Enter localhost and the port rigctld is listening on (default: 4532).
3. Click Connect. The status bar will show the current frequency and mode.

Option C — Mocked (testing)

The mocked backend simulates a radio without any real hardware. Useful for SO2R practice when you only have one physical radio, UI testing, or demo/training scenarios.

1. Go to Rig → Rig Connection, select Mocked (testing) as the backend.
2. Click Connect — the simulated radio connects instantly.
3. Default state: 14.200 MHz USB, 25 WPM, 100W. All commands (frequency, mode, CW, PTT) are accepted and return the last-set values.

QSY Back

Press Alt+B to tune your rig back to the frequency and mode of your previous QSO. Press it again to go further back through your QSO history. This is useful when you leave your run frequency to chase a multiplier and want to return quickly. The history resets when you log a new QSO. The shortcut key is customizable in Settings → Shortcuts.

Troubleshooting

• Connection refused: flrig or rigctld is not running.
• Frequency shows 0 (flrig): 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>'

• Frequency shows 0 (Hamlib): Verify rigctld is responding:
  

  echo "f" | nc localhost 4532

• Debug mode: Run ./clx --debug and enable Rig Debug Logging from the Debug menu to see command/response traffic.

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.

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.

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

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

SO2R (Single Operator, 2 Radio)

SO2R lets you operate two radios simultaneously — typically one in Run mode calling CQ while the other searches for new multipliers in S&P mode. ContestLogX supports SO2R with two independent QSO entry panels, each with its own rig connection, frequency/mode display, and Run/S&P state.

Enabling SO2R

1. Go to Rig → SO2R Mode, or check the SO2R checkbox in the Rig Connection Settings dialog.
2. A second QSO entry panel (Radio R) appears below the existing panel (Radio L).
3. Both panels are always visible — visual continuity is essential for maintaining rate.

Connecting Two Rigs

Each radio can use a different rig backend (flrig, Hamlib, or Mocked) with independent host and port settings. The Mocked backend is ideal for SO2R practice when you only have one physical radio.

1. Go to Rig → Rig Connection. The dialog shows Radio L and Radio R tabs.
2. Configure each radio’s backend, host, and port independently.
3. Click Connect for each radio. Both frequency/mode displays update independently.

Active Radio

One radio is always the active radio. The active radio’s entry panel has a green title bar and border. All actions go to the active radio:

• CW and SSB memory keying (F1–F8)
• DX cluster spot tuning (click a spot)
• The Log QSO button and Enter key log from the active radio’s fields and frequency

Exception: clicking Log QSO or pressing Enter directly in a radio’s entry fields automatically activates that radio first, so the QSO always logs with the correct radio’s frequency and mode.

Switching the Active Radio

Press the configured shortcut key (default: ` backtick) to toggle between Radio L and Radio R. The shortcut can be changed in File → Settings → Shortcuts under Switch Active Radio (SO2R).

Independent Run / S&P

Each radio has its own Run / S&P / Off mode buttons. A typical SO2R workflow is Radio L in RUN (calling CQ) and Radio R in S&P (hunting multipliers), but any combination is supported.

Disabling SO2R

Uncheck Rig → SO2R Mode. The Radio R panel is removed, Radio R’s rig connection is closed, and the entry dock returns to the standard single-radio layout. The setting is remembered across sessions.

WSJT-X Integration

ContestLogX listens for UDP messages from WSJT-X on port 2237 (configurable in settings). When WSJT-X logs a QSO, the callsign, exchange, RST, frequency, and mode are pre-filled in the QSO entry panel for operator review before logging.

Digital modes (FT8, FT4, JT65, etc.) are automatically mapped to the appropriate contest mode. No configuration is needed — the listener starts automatically when ContestLogX launches.

Supported WSJT-X Messages

• QSO Logged — pre-fills entry fields with call, exchange, RST, frequency, and mode
• Status, Heartbeat, Decode — logged when WSJT-X debug is enabled (Debug menu)

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.

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.

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.

CW Decoder

The CW Decoder is a dockable panel that listens to your radio's receive audio and displays decoded Morse text in real time. It's a copy assist — the operator is always the authority on what gets logged. Click a decoded callsign or RST to fill the matching QSO entry field. Open the panel from Window → CW Decoder (Radio L) or (Radio R).

Audio Setup

Audio is configured per radio in Rig Connection Settings. Each radio tab has a CW Decoder — Audio Input section with three controls:

• Audio Input Device — the system audio device your radio's receive audio is routed through. Options include any input the OS exposes: a USB audio endpoint on the radio (Elecraft K4, Icom IC-7300, Yaesu FT-710, etc.), a soundcard line-in, or a virtual audio cable (VB-CABLE on Windows, BlackHole on macOS, pw-loopback / "Monitor of…" source on Linux). Select (none) for a radio with no audio routed to the PC — the decoder simply won't open for that radio. In SO2R, each radio has an independent audio device setting; any combination of "neither / L only / R only / both" is legal.
• Mute decoder on PTT (default ON) — gates the decoder while the owning radio is transmitting so your own keying doesn't echo back through the decoder. Two paths: rig-backend PTT state (from flrig or Hamlib) and ContestLogX's internal CW-send paths (F-key memories, CW console). Both paths respect this checkbox; turn it off only if your audio routing already filters transmit (some radios' USB audio output is receive-only by default).
• PTT grace window (default 250 ms) — small delay added to the internal-send mute duration to absorb your CW console's spool tail and the rig's recovery time. Raise if you see self-decode at the end of a transmission.

Multi-Channel Decoding

The decoder runs N parallel Goertzel tone detectors spread across a passband — every bin decodes independently, with its own WPM lock and Morse state. Each bin is a horizontal row in the panel, labeled with its center frequency. Two stations on different CW tones within the passband decode simultaneously in their respective rows without cross-contamination.

Two controls in the widget's toolbar determine the coverage:

• Center — the passband's center frequency in Hz (default 700 Hz, the common CW sidetone). Set this to the sidetone frequency your radio is configured for.
• Bins — how many parallel detectors to run (default 6). Spacing is a fixed 50 Hz, so N bins span N×50 Hz of passband centered on the chosen frequency.

With the defaults (Center 700, Bins 6), the decoder covers 550–850 Hz with bins at 575 / 625 / 675 / 725 / 775 / 825 Hz. Raising Bins widens the coverage for a general survey of a busy band; lowering it narrows the search around a single signal. Changes take effect within a second.

WPM Tracking

Each bin automatically detects and continuously adapts to the sender's speed — no manual WPM setting. The live WPM readout next to each row's frequency label updates as the decoder tracks changes in sending speed within a few characters. A WPM bounding range control (default 15–40 WPM) constrains the estimator so noise bursts can't drive it to implausible values; widen the range for very slow or very fast content.

Click to Fill

Decoded callsigns appear underlined in blue; RST reports in amber. Click any highlighted token to fill the matching QSO entry field for that radio:

• Callsign click — fills the CALL field. Triggers the same downstream actions as keyboard entry: Super Check Partial lookup, call-history lookup, dupe check, name/QTH auto-fill. Keyboard focus stays wherever you were typing — the click does not steal focus.
• RST click — fills the RSTr field. The regex accepts cut numbers (5NN, 55N, 5N9, etc. where N = 9) and normalizes to digits on fill. Click 5NN, 599 goes into the field.

In SO2R, click-fill always targets the owning radio's entry fields — i.e., a click in Radio L's decoder fills Radio L's CALL regardless of which radio is currently active for keyboard input. Auto-capture (without an operator click) is deliberately not implemented — the decoder reports what it hears; the operator decides what gets logged.

Squelch & Noise Rejection

A global squelch slider gates tone detection across all bins uniformly. The Schmitt trigger also tracks a per-bin rolling noise-floor estimate and lifts the release threshold above it — so bins close to a strong signal release cleanly between characters instead of wedging on. In practice a squelch setting of 10–30% works well on most HF audio; raise it on noisy bands.

Tuning Tips

• For best copy, tune the radio so the received CW sidetone lands within your decoder passband and ideally near a bin center. Bins have 100 Hz resolution; a signal more than ~100 Hz off the nearest bin center will detect with reduced magnitude (still decodes, but less robustly).
• If you know your target signal frequency, set Center to match it and reduce Bins — a narrow 2–4 bin window centered on the signal gives the cleanest decode without noise bleed from off-frequency activity.
• On Linux, for a clean test signal, use pw-loopback or pavucontrol's "Monitor of [output device]" source to route any MP3/audio player output directly into ContestLogX — no speaker or mic involved. The decoder captures at the device's native sample rate; no internal resampling.

Practice Mode — Head-Copy Trainer

The Audio dropdown has two virtual sources at the top of the list — Practice — CW Rag Chew and Practice — Contest Exchange — that synthesize random CW on your default output device and feed the same tones into the decoder pipeline. The workflow is: listen with your eyes off the decoder and copy in your head, then glance at the decoder output to check yourself. No typing, no grading screen, no scoreboard — just audio in, decoded text out, and you in the middle deciding whether you got it right.

• Rag Chew — random CQ calls, DX rag-chew fragments, and short exchanges drawn from a template pool. Names, rigs, antennas, QTHs, and power levels are randomized each fragment.
• Contest Exchange — pulls exchange format and named multipliers (states, sections, zones, etc.) from the currently-loaded contest. RST is always 5NN. The entry is disabled until a contest is loaded.
• Speed — follows the CW console's WPM setting. Bump the console slider to change practice speed; the next transmission picks up the new rate.
• Audio routing — playback uses your system default output device (speakers / headphones). No virtual audio cable needed.
• On startup CLX resets a saved practice source back to (none) so it never starts generating CW at launch — you have to re-select it each session.

Docking & Layout

The CW Decoder dock defaults to the top dock area — above the QSO log, bounded horizontally by the right-side docks (DX Cluster, Band Map, etc.). Like other docks, it's movable, floatable, and closable. When floating, the window can grow horizontally (wider = more decoded text per row before scrolling) but its vertical dimension is locked to the natural height of the configured bin rows. Changing bin count while floating re-pins the height accordingly.

Known Limitations

• The WPM readout is typically ~5–15% below the sender's actual speed due to 10 ms DSP block quantization. Character decoding accuracy is unaffected because the dot:dash ratio is preserved; this is a display-only imprecision.
• Operators who send with compressed word gaps (common in fast contest CW like CWT) will produce fused tokens like TUK4RO — the decoder is reporting what was actually keyed. Click- to-fill in that case puts the literal token into CALL; manual edit fixes it.
• The decoder supports one audio path per radio. Multi-signal separation within a single bin (two stations on the same tone frequency) is not attempted.

Remote Dashboard

The Remote Dashboard is a small HTTP server built into ContestLogX that serves a live, read-only view of your current session (score, rate, recent QSOs, rig state, propagation) on your local network. Point a phone, tablet, or another PC browser at the URL and you get an auto-refreshing dashboard — useful for checking your score from the couch during a coffee break, monitoring a guest operator's session from another room, or just having an ambient display on a second screen while you run.

The server is off by default and binds to your LAN only — it's not exposed to the internet. Every request requires a bearer token, and the bookmarkable URL includes that token so your phone reconnects without prompting.

Enabling the Dashboard

1. Open File → Preferences → Dashboard.
2. Check "Enable Remote Dashboard HTTP server". A token is auto-generated.
3. Leave the port at 8080 (or change if you already have something on that port).
4. Choose a bind mode:
   • LAN (auto-detect) — default; binds to the first non-loopback IPv4 interface
   • Localhost only — dashboard only reachable from the same PC
   • Any interface — useful if auto-detect picks the wrong interface (VPN, etc.)
5. Click Copy URL for Phone and paste the URL into your phone's browser. Add it to the home screen and you have a one-tap bookmark.
6. Click OK. The server starts immediately — no app restart required.

What the Dashboard Shows

• Score — final score, total QSOs, points, multiplier count
• Rate — current hourly rate (last 10 min ×6), actual last hour, session average
• Rig — frequency, mode, band, Run/S&P indicator per radio (both radios shown in SO2R mode)
• Propagation — SFI / A-index / K-index from the most recent NOAA fetch
• Recent QSOs — last ten logged QSOs newest-first with UTC time, call, band, mode, and received exchange

The page auto-refreshes every 5 seconds. Layout is responsive — one column on a phone, three columns on a desktop monitor.

Security Notes

• The auth token is the only gate — anyone on your LAN with the URL can see the dashboard. Keep your home Wi-Fi secured. If you're on an untrusted network (hotel, hamfest), use the Localhost only bind mode or leave the feature disabled.
• Click Rotate next to the token in Preferences to invalidate old bookmarks — e.g. after a guest operator leaves, or if you suspect the URL leaked.
• The dashboard is read-only. It cannot log a QSO, change the rig frequency, or modify any contest state. Rig-control write endpoints are planned for a future version with their own explicit opt-in.

Troubleshooting

• Phone can't reach the URL. Confirm the phone is on the same Wi-Fi as the PC running ContestLogX. Some guest-network SSIDs isolate clients — switch to the main network.
• Firewall prompt on Windows. Allow ContestLogX on private networks when the OS prompts. On Linux, ufw allow 8080 if you've enabled ufw.
• Port already in use. Change the port in Preferences. Common conflicts: 8080 is used by many dev servers; 8000 is a common fallback.

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.

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.

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.

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.