Skip to content

WSJT-X / JTDX / JS8Call Setup Guide

This guide covers configuring WSJT-X (and compatible apps like JTDX, JS8Call) to work with RigPlane's client-facing rigctld-compatible endpoint. This is separate from the provider layer underneath RigPlane, which may be native or Hamlib-backed depending on the radio path. If RigPlane itself is using Hamlib, see the Hamlib / external rigctld provider guide for the provider-facing setup.

Quick Start

1. Start the server

Recommended: all-in-one (Web UI + audio bridge + rigctld):

# Install rigplane (audio-bridge deps ship with the core install since v0.19)
pip install rigplane

# Install the RigPlane Virtual Audio Driver (macOS, ships with RigPlane Pro)

# Start all-in-one server; the bridge auto-detects the RigPlane cable ends
rigplane --model IC-7610 --host <RADIO_IP> --user <USER> --pass-file <PASSWORD_FILE> web \
  --bridge "RigPlane Virtual Cable Output" --bridge-tx-device "RigPlane Virtual Cable Input"

This starts: - Web UI on :8080 - Audio bridge routing radio RX → RigPlane Virtual Cable Output, RigPlane Virtual Cable Input → radio TX - Rigctld on :4532 (enabled by default)

Serial USB-audio radios use the same bridge direction: RX audio is played to the WSJT-X input loopback, and WSJT-X output is captured and transmitted through the radio's USB-audio TX path. Current serial Icom backends arm PCM TX before bridge transmit; if TX startup fails, the bridge keeps RX running and reports the TX failure instead of logging a per-frame "PCM TX not started" error. On Windows callback capture, native callback blocks are re-chunked into fixed 20 ms PCM frames before transmit.

Alternative: rigctld only (no Web UI or audio bridge):

rigplane --model IC-7610 --host <RADIO_IP> --user <USER> --pass-file <PASSWORD_FILE> serve --wsjtx-compat

2. Configure WSJT-X

In Settings → Radio:

Setting Value
Rig Hamlib NET rigctl
Network Server 127.0.0.1:4532
PTT Method CAT
Mode Data/Pkt
Split Operation Fake It

Press Test CAT — the button should turn green. Press Test PTT — the radio should key up briefly.

Which port?

Point WSJT-X at RigPlane's client-facing rigctld endpoint. If RigPlane is also consuming an external Hamlib rigctld provider underneath, keep the two TCP ports distinct so WSJT-X talks to RigPlane, not around it.

3. Configure WSJT-X Audio (with the RigPlane Virtual Cable)

On macOS the bridge plays RX into RigPlane Virtual Cable Output and captures TX from RigPlane Virtual Cable Input; the cable is a single loopback, so audio played into Output appears on Input. Set WSJT-X to the same two ends:

In Settings → Audio:

Setting Value Why
Input RigPlane Virtual Cable Input Receives RX audio played into the cable Output end
Output RigPlane Virtual Cable Output Sends TX audio captured from the cable Input end

The audio bridge routes: - Radio RX → rigplane → RigPlane Virtual Cable Output → WSJT-X Input (decode FT8/FT4) - WSJT-X Output → RigPlane Virtual Cable Input → rigplane → Radio TX (transmit FT8/FT4)

In the web server, the bridge sends captured audio to the radio only while a managed transmit authority is keyed, or while observed PTT is not OFF. The standalone rigplane audio bridge CLI has no gate: it keeps sending all non-silent captured audio.

--bridge only describes the local audio loopback between WSJT-X and rigplane. Radio DATA policy is derived from the resolved audio route: direct Icom LAN audio uses the LAN audio route, while USB/serial audio remains a USB route even when a local loopback bridge is enabled.

Radio Settings (for TX audio)

On the IC-7610 front panel, set: - Menu → Connectors → MOD Input → LAN (select Data or USB) - This tells the radio to accept modulation input from the LAN connection

Verifying Audio

After starting, check the bridge status: 

curl http://localhost:8080/api/v1/bridge
# Should show: {"active": true, "rx_frames": ..., "rx_drops": 0, ...}

Zero rx_drops = healthy bridge. If you see drops, check CPU load.

The --wsjtx-compat Flag

What it does

When a CAT client connects for the first time:

  • If the radio is in USB, LSB, or RTTY with DATA mode OFF, the server automatically enables DATA mode.
  • This eliminates a known first-TX latency when WSJT-X switches from plain SSB to packet mode (PKTUSB).

When --wsjtx-compat is used with a direct Icom LAN radio connection on a radio profile with multiple DATA sub-modes such as the IC-7610, rigplane treats WSJT-X packet-mode requests as LAN audio operation:

  • PKTUSB, PKTLSB, and PKTRTTY are mapped to DATA2 instead of DATA1.
  • DATA2 modulation input is set to LAN.
  • DATA1 modulation input is not changed.

For USB/serial radio connections, including cases where rigplane bridges local USB audio devices for remote use, the compatibility mapping remains the legacy DATA1 behavior.

When to use it

  • Use --wsjtx-compat if you run WSJT-X, JTDX, or JS8Call and want instant TX on the first transmission.
  • Don't use if you need the radio to stay in the exact mode you set manually (e.g., SSB voice operation alongside CAT control).

What it changes on the radio

In USB/serial CAT operation, only the DATA mode flag (CI-V 0x1A 0x06) is changed. In direct Icom LAN operation on multi-DATA radios, rigplane may also set the selected LAN DATA sub-mode's modulation input to LAN. DATA1 is treated as user-owned and is not rewritten by prewarm, profile apply, or state restore.

Known Behavior

USB → PKTUSB first-TX delay

When WSJT-X connects to a radio in plain USB (DATA off), it sends M PKTUSB -1 to switch to packet mode. This involves two radio changes:

  1. Verify/set USB mode
  2. Enable DATA mode

Some CAT client stacks (including WSJT-X and wfview's rigctld) introduce a ~15–20 second delay before the first PTT after this transition. This is not an rigplane bug — the same behavior occurs with wfview's built-in rigctld emulation.

Workarounds:

  • Use --wsjtx-compat (recommended) — pre-warms DATA on connect.
  • Manually set the radio to USB-D1 before starting WSJT-X.
  • Once DATA mode is active, subsequent TX cycles work without delay.

After closing WSJT-X

The server gracefully handles client disconnect:

  • Abandoned commands are cancelled (no background CI-V spam).
  • The poller stops when the last client disconnects.
  • Reconnecting a new WSJT-X session works immediately.

Troubleshooting

Test CAT fails (button stays red)

  1. Verify the server is running: rigctl -m 2 -r localhost:4532 f
  2. Check the server log for connection/auth errors.
  3. Ensure no other application is using port 4532.

Test PTT fails or has long delay

  1. Confirm PTT Method is set to CAT (not VOX or hardware).
  2. If starting from plain USB, use --wsjtx-compat or pre-set DATA mode.
  3. Check server logs for CI-V timeout patterns.

Radio becomes unresponsive after disconnect

  1. Restart the server if needed: Ctrl-C and re-launch.
  2. Check if another application (wfview, flrig) is also controlling the radio.

Mode shows USB instead of PKTUSB

  • Ensure WSJT-X Mode is set to Data/Pkt (not None or USB).
  • With --wsjtx-compat, DATA mode should already be active on connect.

Compatible Applications

Tested with:

  • WSJT-X 2.7+ (FT8, FT4, JT65, etc.)
  • JTDX (FT8/FT4 variant)
  • JS8Call (JS8 mode)
  • fldigi (various digital modes)
  • Log4OM 2 (logging + CAT)
  • MacLoggerDX (macOS logging)

Any application that supports Hamlib NET rigctl should work.

Get the Packaged Desktop App

Prefer a packaged desktop app?

This guide covers the open-source rigplane Python library. If you want a polished desktop application with a GUI that handles WSJT-X / JTDX / JS8Call integration on macOS and Linux, check out RigPlane Pro.

Download RigPlane Pro for Mac and Linux →