CAT Setup
In 15 minutes from "rig and Mac are sitting next to each other" to "frequency and mode appear automatically in the logger".
IC-705 without a cable?
Since 1.13.0 the IC-705 can also be controlled directly over WLAN — no USB cable needed: Tutorial: Connect the IC-705 over WLAN.
Requirements
- A rig with a CI-V or serial interface (38 curated profiles plus around 300 more Hamlib models)
- A USB cable (rig-specific, e.g. CT-17 for Icom, OPC-478 for older Icom, USB audio cable for Yaesu)
- Possibly a driver for the USB-serial chip (FTDI, Silicon Labs, Prolific) — usually not needed on macOS Sonoma+
Step 1 — Connect the Cable + Driver Check
- Turn the rig on, connect it to the Mac with the USB cable
- Open Terminal, test:bash
ls /dev/cu.* | grep -iE "usbserial|slab|usbmodem" - You should see at least one entry, e.g.:
/dev/cu.usbserial-AB0OJWMD(FTDI chip)/dev/cu.SLAB_USBtoUART(Silicon Labs)/dev/cu.usbmodem14201(USB CDC, many modern Icoms)
No entry? Then the driver is missing:
- FTDI: macOS has shipped it since ~10.9, nothing should be needed
- Silicon Labs (CP210x): download at silabs.com
- Prolific PL2303: problematic on modern macOS versions, better to replace the adapter
Step 2 — Choose a Rig Profile
- Open HAM-Tools → Settings → CAT (
⌘,→ "CAT" tab) - In the "Radio" section, pick the Manufacturer — 38 curated profiles with factory defaults
- Next to it, pick your Model, e.g.:
| Manufacturer | Examples |
|---|---|
| Icom | IC-7300, IC-7610, IC-705, IC-9700, IC-7100, IC-7000 |
| Yaesu | FT-991 / FT-991A, FTDX-10, FTDX-101D, FT-891, FT-857, FT-817 |
| Kenwood | TS-590S, TS-2000, TS-480 |
| Elecraft | K3, KX2, KX3 |
| Xiegu | G90, X6100 |
| FlexRadio | 6000/8000 Series (Slice A–D, over LAN) |
If your model isn't there from 1.56: pick the manufacturer "More Hamlib models …". HAM-Tools reads the roughly 300 models from the bundled rigctld; type manufacturer, model or Hamlib number into the search field and pick the model (or enter the Hamlib no. and click "Apply"). Baud rate and serial parameters come from Hamlib — the preset baud rate is Hamlib's maximum, so match it with the setting on your radio. Band check, CAT tune and the voice keyer row are only available with the curated profiles. Details: CAT → More Hamlib models.
Step 3 — Set Serial Port + Baud
After selecting the model, in the "Serial interface" section:
- Open the Port dropdown — it lists the
/dev/cu.*ports ("Refresh" rescans them) - Choose the port you identified in Step 1
- The Baud rate is preset by the profile (e.g. IC-7300 = 19200, IC-7610 = 115200)
- The CI-V address ("CI-V (ICOM)" section) is only relevant for Icom — the default is 0x94 for the IC-7300, check the rig menu.from 1.56 The field also appears for the Xiegu G90/X6100 (
0x70) and, with thefree profile "More Hamlib models …", for models of the Icom backend — there it is empty: without an entry, Hamlib uses its own default address
Check the baud in the rig
Icoms default to "Auto" for baud — usually works, but is slower and less reliable than a fixed value. In the rig menu (e.g. IC-7300: Menu → SET → Connectors → CI-V → CI-V Baud Rate) set the same value as in HAM-Tools.
Step 4 — Start the Connection
- In CAT settings, "Status" section: click "Start" (grayed out while model or port is missing)
- The status badge next to it — and at the bottom of the main window's sidebar, where a click connects and disconnects — shows:
- ⚪ CAT off → not connected
- 🟠 CAT… → the rigctld subprocess starts, healthcheck runs
- 🟢 CAT → all good, the frequency updates live in the main window
- 🔴 CAT err → connection failed, the error text appears below
When 🟢: turn the rig's VFO and watch whether HAM-Tools follows the frequency.
Once everything works, click "Save" from 1.61. Only then are model, port and baud rate stored in the configuration; an orange note shows while something is unsaved. Without saving, HAM-Tools starts with the old settings after a restart (see the CAT module).
From 1.58 on, HAM-Tools connects to this configuration by itself at the next app launch ("Connect automatically at launch" below "Start", on by default — see the CAT module).
What Runs in the Background?
HAM-Tools ships with a bundled rigctld (Hamlib) as a helper binary at HAM-Tools.app/Contents/Helpers/rigctld. When you activate the CAT connection, a subprocess is started:
rigctld -m <rig-id> -r /dev/cu.usbserial-X -s <baud> -C <serial parameters> -T 127.0.0.1 -t 4532HAM-Tools then talks to rigctld over TCP on port 4532. If you want more diagnostics:
# In a second Terminal:
nc 127.0.0.1 4532
f # query frequency
m # query mode
\get_freq # alternative commandWhat Happens After a Successful Connection?
| Effect | Where it's visible |
|---|---|
| Frequency live | Main window radio panel, in the logger QSO form, in the spot bridge |
| Mode live | RST default follows (CW → 599, SSB → 59, RTTY → 599) |
| Band auto | Calculated from frequency, preset in the QSO form |
| Cabrillo mismatch warning | When the contest category doesn't match the mode |
| Macros F1–F8 | Send CW directly via send_morse, or trigger SSB audio with PTT — in the contest form, from 1.56 also in the DX form and all outdoor forms (profile "General (DX & Outdoor)") |
| Icom Voice Keyer V1–V4 | 4-button row in all entry forms (Yaesu V1–V5); from 1.56 hidden with the free profile "More Hamlib models …" |
Common Problems
"Failed to open serial port"
→ Another program is holding the port (often: an old rigctld instance, fldigi, WSJT-X). Close the other app, or kill rigctld manually: pkill rigctld
crash or force quit — a leftover instance then belongs to another program.
Frequency is read but not written
→ Check "CI-V Transceive" (Icom) or "CAT Rate" (Yaesu) in the rig menu. Some models explicitly need "Send Freq on Change" = ON.
PTT doesn't work / no transmit
→ Some setups need a separate PTT cable, others can do PTT via CAT. In HAM-Tools: the rig profile has supportsPTT: true/false. If false, you have to handle PTT externally (VOX, footswitch, separate interface).
Connection drops after a few seconds
→ Baud mismatch between rig and HAM-Tools. Set both to a fixed value (e.g. 19200 for the IC-7300, 38400 for the FT-991A).
How do I link FLDigi / WSJT-X at the same time?
→ First, in Settings → CAT, section "Share CAT (WSJT-X & co.)", enable the "Keep rigctld open for other programs" switch — without it, HAM-Tools holds the port exclusively and WSJT-X can't reach the radio. Then click "Start" in HAM-Tools. In WSJT-X / fldigi, set: Rig = "Hamlib NET rigctl", network server = 127.0.0.1:4532, PTT = CAT, poll interval 1 s. That way both programs share the rig through HAM-Tools' rigctld — the server stays open even when you disconnect HAM-Tools' CAT connection. Details: CAT → CAT Sharing.
Next Steps
- Contest with Macros — F1–F8 CW + SSB
- LoTW Pipeline — QSL sync after logging
- CAT Module Docs — the full CI-V table