CAT / Radio Control
HAM-Tools controls your radio via Hamlib (rigctld). 38 models come preconfigured: Yaesu, Icom, Kenwood, Elecraft, Xiegu, FlexRadio — these are the curated profiles with verified factory defaults. The bundled Hamlib 4.7.1 knows 301 models in total; you can pick any of them via the manufacturer entry "More Hamlib models …" (see below).
Connection Types 🆕
New in 1.13.0
Besides USB there are two network paths. Pick them in the "Path" picker at the top of Settings → CAT — selectable per configuration:
| Connection | What's behind it |
|---|---|
| USB (serial) | The standard: HAM-Tools starts its own rigctld on the USB serial port |
| IC-705 Wi-Fi | HAM-Tools connects directly to the IC-705 (or a compatible Icom) over WLAN — native Icom RS-BA1 protocol, no extra tool like wfview or kappanhang needed |
| Network (rigctld) | Dock onto an already running rigctld server — e.g. from wfview/kappanhang on the same Mac or a shack PC on the LAN |
IC-705 WLAN — Radio Without Cable
The IC-705 (and network-capable Icom relatives) speaks the RS-BA1 network protocol, which HAM-Tools has implemented natively since 1.13.0 (control stream UDP 50001 + CI-V serial stream 50002):
- Fields: radio IP, user, password — the values come from the radio menu Set → WLAN Set → Remote Settings (create a Network User with administrator rights)
- Password in the keychain from 1.62: the network password is stored in the macOS keychain like the other credentials, no longer in plain text in the settings. It is migrated automatically on the first start after the update; if saving fails, the CAT window warns below the password field. The settings export still includes it.
- Start from 1.56: no serial port is needed. "Start" becomes clickable once radio IP, user and password are filled in.
- What runs: frequency, mode, and S-meter live; PTT and QSY (a spot click turns the radio) over WLAN
- What doesn't work over WLAN: CW keying (contest macros) and the rig-internal voice memories — these need the USB path via rigctld
- What deliberately doesn't: audio does not run through HAM-Tools — use WSJT-X & Co. externally as usual (the radio's audio stream stays free)
- Outdoor tip: the IC-705 can act as a WLAN access point itself — connect the Mac directly to the radio's WLAN, no router needed
- The CI-V address must match the radio setting (IC-705 default:
0xA4)
Connection monitoring: Since 1.29.1 HAM-Tools detects a WLAN loss and reconnects automatically. Since 1.32 a CI-V watchdog additionally guards the connection: if no CI-V response arrives from the radio for ~10 s, the session is considered stalled and is re-established automatically.
→ Step by step: Tutorial: Connect the IC-705 over WLAN
Network (rigctld) — External Hamlib Server
If a bridge tool (wfview, kappanhang) or another computer is already running a rigctld, HAM-Tools simply hooks onto it:
- Host:
127.0.0.1for the same device, otherwise the LAN IP of the shack PC - Port: the standard rigctld port is
4532; wfview/kappanhang often listen on4533so that 4532 stays free for other programs - Validation from 1.56: an empty field means port
4533. If the entry is not a whole number from 1 to 65535, "Port: enter a whole number from 1 to 65535." appears and "Start" stays disabled. This path doesn't need a serial port.
wfview needs 1.45.2 from 1.45.2
wfview answers frequency queries with decimal places. Older HAM-Tools versions rejected that and reported "No rigctld reachable" — since 1.45.2 it is read correctly.
FlexRadio — Radio on the LAN from 1.56
FlexRadio 6000 and 8000 series radios sit on the network, not on USB. HAM-Tools starts its own rigctld that talks directly to the radio's SmartSDR interface — SmartSDR CAT or any other helper program is not needed.
- Manufacturer "FlexRadio", Model "6000/8000 Series – Slice A" (B–D for further slices)
- Choose the Path "LAN (radio IP)" — for Flex profiles it replaces "USB (serial)"
- Enter the Radio IP — it is shown in SmartSDR or in your router's DHCP list. Hamlib sets the port (4992) itself;
127.0.0.1does not work, the radio always has its own LAN IP. An invalid address or127.0.0.1is flagged in orange, and "Start" stays disabled.
Frequency, mode and PTT run over CAT. Audio does not go through CAT but through SmartSDR's DAX devices (or a virtual audio cable such as Loopback): choose them as input and output in SSTV, FreeDV, WSPR or Winlink, just like a regular sound card.
The Flex profiles have not yet been tried with real hardware — nor together with SmartSDR for Mac and DAX. Feedback to bugs@funkwelt.net is very welcome.
First Setup (USB)
This is how you set up the standard path over a USB cable (for WLAN see above):
- Cmd+, → CAT tab
- Pick Manufacturer (Icom / Yaesu / Kenwood / Elecraft / Xiegu / FlexRadio / Hamlib Dummy for testing without hardware) — or "More Hamlib models …" if your radio is not listed (see below)
- Pick Model — factory defaults (baud, data bits, parity, handshake) load automatically
- Pick Port (section "Serial interface") — the dropdown lists all
/dev/cu.*(USB CAT cables are detected automatically) - CI-V Address (ICOM only) — default from the profile, you can override it if your radio is configured differently
- Click "Start" — the badge at the top switches from "CAT off" (gray) via "CAT…" (orange) to "CAT" (green)
Connect automatically at launch from 1.58: The switch below "Start" is on by default. HAM-Tools then connects once to the active configuration when it opens, just like clicking "Start". This is skipped if no port has been chosen yet, the saved USB port is missing (radio not plugged in) or the "Hamlib Dummy" configuration is active. If the radio is off, the badge shows "CAT err" as usual. When the switch is off, connect manually with "Start".
Detect Automatically (Auto-Detect) 🆕
New in 1.15.0
Not sure which baud rate your radio is set to — or want to skip the manual setup entirely? The "Auto-detect…" button next to the model picker finds your radio by itself (works like the CAT search in UCX Log).
- Switch the radio on and connect it via USB/CAT cable
- Settings → CAT → "Auto-detect…" (only clickable while CAT is stopped — press Stop first if a connection is active)
- Pick a manufacturer (e.g. Kenwood) — or "All manufacturers" if you're unsure
- "Start search" — HAM-Tools cycles through every combination of model × USB port × baud rate until the radio gives a valid answer. The progress view shows live what's being tested ("Testing Kenwood TS-590SG — usbserial-1420 @ 115200 Bd… 12/96")
- On a hit: "Apply" writes model, port and baud rate into the active configuration — then press "Start" as usual and "Save" to keep it
Good to know:
- Factory baud rates are tested first — a radio with default settings is usually found within seconds. Only after that does the full baud matrix run; a sweep across all manufacturers can take several minutes (the dialog shows an estimate).
- Some related models share the same CAT protocol (e.g. Kenwood TS-480/590/890) — so a sibling model may trigger first. If the shown model isn't yours: click "Keep searching" and the sweep continues with the next candidate.
- The search is WSJT-X-safe: it runs on its own internal port and leaves a shared rigctld server (see CAT Sharing) untouched.
- Only the USB (serial) path is detected — for IC-705 Wi-Fi and network rigctld see Connection Types.
CI-V Address (ICOM, Xiegu)
Every ICOM model has a default CI-V address; Xiegu (G90, X6100) also speaks CI-V via Hamlib's Icom backend. HAM-Tools knows:
Notation
HAM-Tools shows the address as 0xA4 (C notation), while the radio menu shows the same value as A4h (h suffix). 0xA4 = A4h = 164 decimal — it is exactly the same address, just a different notation.
| Model | CI-V | Model | CI-V |
|---|---|---|---|
| IC-7300 | 0x94 | IC-7100 | 0x88 |
| IC-7610 | 0x98 | IC-9100 | 0x7C |
| IC-705 | 0xA4 | IC-7600 | 0x7A |
| IC-9700 | 0xA2 | IC-7700 | 0x74 |
| IC-7200 | 0x76 | IC-7000 | 0x70 |
| IC-746PRO | 0x66 | Xiegu G90 / X6100 | 0x70 |
TIP
If your radio's CI-V was changed to a different value in the menu, just override the value in the field. With the "Default (0xXX)" button you reset to the factory value.
For Yaesu / Kenwood / Elecraft / FlexRadio this section is hidden — those manufacturers don't use CI-V.
With the free "More Hamlib models …" profile the section appears for every model of the Icom backend (Hamlib numbers 3000–3999, which includes Xiegu). The field is empty there: without input Hamlib uses its own default address, a value you enter overrides it.
Multi-Config
You can save multiple configurations (e.g. one per radio). Workflow:
- Make the settings for Radio A (model + port + CI-V if applicable)
- Click "Save as…" → enter a name (e.g.
IC-705 Mobile) → Save - Configure Radio B (switch model, change port)
- "Save as…" again →
IC-7300 Shack - Switch between configs: in the "Active config" picker at the top. While connected, the new config only applies after "Stop" and "Start"; the status names the config that is actually connected and points out the difference from 1.63
Change, test, save from 1.61
Changes in the CAT window take effect immediately — "Start" connects with the new values, so you can safely try another model or baud rate. They are only stored in the config when you say so:
- "Save" stores the changes in the active config (only enabled while there are unsaved changes; an orange note shows them).
- "Save as…" creates a new config with the changed values — the previous one stays as it was.
- If you switch configs with unsaved changes (picker or menu Transceiver → Load TRX setup), HAM-Tools asks: Save, Discard or Cancel.
- After a restart, the saved state always applies.
Exception: if macOS gives the USB adapter a new path and HAM-Tools finds it by itself, the new port is saved right away.
What the App Does With CAT
- Read frequency: every 500 ms (default, adjustable 200–2000 ms) → shown in the logbook entry panel and the POTA/Contest form
- Set frequency: clicking a DX cluster spot or a QTH memory makes the radio jump to that frequency
- Step frequency from 1.47.1: every digit of the frequency display has an arrow above and below it — one click raises or lowers exactly that digit (1 Hz to 10 MHz) and sends the step to the radio as a QSY right away. Click a digit to open the text field for typing (Return applies, Esc cancels). Without CAT the frequency is set locally.
- Read mode: in sync with frequency, determines the RST default (599 for CW/Digi, 59 for SSB)
- Set mode: the mode picker in the Radio/CAT panel sends
setModeto Hamlib → the radio switches USB/LSB/CW/PKTUSB - VFO A/B + Split: by click in the Radio/CAT panel
- S-meter: read live from the radio (Hamlib
get_strength) - PTT: set by the contest voice macros (F1–F8) for SSB playback; otherwise the app does not interfere with transmit
- Tuner: the ATU pill toggles the antenna tuner on/off; the separate TUNE button (modern Yaesu) starts a real tuner match (see below)
Yaesu: ATU Pill vs. TUNE Button
The Radio panel has two separate controls for the antenna tuner:
- ATU — toggle: switches the built-in tuner into the line (on) or out (off). (Formerly called "TUN" — renamed because it was too easy to confuse with the "TUNE" button.)
- TUNE — starts a real tuner match on the TRX. On modern Yaesu via the CAT command
AC002;; the FTX-1 uses a different syntax and getsAC103;(since 1.45.1).
The TUNE button only appears on rigs with a CAT-controllable tuner. On the older Yaesu with binary CAT (FT-817/857/897) it's hidden, since these have no ATU that can be matched over CAT. The device-specific tune command is overridable per TRX profile.
Robust against tuner/voice hiccups (since 1.24.2 / 1.25.0)
A Yaesu tuning cycle is an unacknowledged CAT command and used to throw the connection off briefly (up to "CAT reconnect needed"). The app now handles this: the ATU toggle and voice memory no longer drop CAT (silent retry), and after a TUNE match the CAT resyncs automatically & budget-free — however often you tune, no manual reset. Meanwhile the status badge briefly shows "Tuning…" instead of an error.
CAT Sharing (WSJT-X & Co.)
By default HAM-Tools holds the serial port exclusively — as long as CAT is connected, no second program can reach the radio. With "Share CAT (WSJT-X & co.)" both run in parallel:
- Cmd+, → CAT tab → enable the switch "Keep rigctld open for other programs".
- In HAM-Tools, "Start" (connect CAT).
- Configure WSJT-X (or fldigi, JS8Call …):
- Rig:
Hamlib NET rigctl - Network Server:
127.0.0.1:4532 - PTT Method:
CAT - Poll Interval: 1 s
- Rig:
HAM-Tools then runs its built-in rigctld as a local server (only 127.0.0.1, no LAN access) that any number of Hamlib programs can hook onto. The server stays open even if you disconnect HAM-Tools' own CAT connection — a running WSJT-X session doesn't drop. You stop it via "End sharing" or when you quit the app.
Band sync for free
When WSJT-X changes band over the shared rigctld, HAM-Tools sees it on the next frequency poll. If you enable "Band follows TRX" in the DX Cluster, the spot list, world map, and logbook filter follow along automatically.
Mode Picker Usable Even Without CAT
New in 1.8.10
Mode selection works even without an active CAT connection — important for remote setups, travel logging with no TRX within reach, or filling in paper logs after the fact.
- With CAT: a mode click sends
setModeto the radio, the radio switches, the poll loop confirms the new value. The selection is limited to Hamlib modes: USB, LSB, CW, CWR, AM, FM, RTTY, RTTYR, PKTUSB, PKTLSB. - Without CAT: a mode click sets the value directly in the internal RadioState (USB/LSB are mapped to
SSB, PKTUSB/PKTLSB toDATA, the rest 1:1). In addition, digital modes appear under a divider: FT8, FT4, JT65, JT9, PSK31, JS8, Q65, MSK144. These run on the TRX over PKTUSB modulation — Hamlib doesn't know them directly, so they're hidden without a CAT connection.
The status under the frequency display shows CAT (green) or manual (gray), so you always know where the current values come from.
More Hamlib Models (Free Profile)
Your radio is missing from the model list? The bundled Hamlib knows around 300 models, of which only the 38 curated ones ship as profiles with factory defaults. You reach all the others like this:
- Pick Manufacturer → "More Hamlib models …". HAM-Tools reads the model list from the bundled
rigctld(rigctld -l). - Type manufacturer, model or Hamlib number into the search field and pick the model from the dropdown — or enter the Hamlib no. directly and click Apply. Models that already have a curated profile are marked as such.
- HAM-Tools queries the model's capabilities (
rigctld --dump-caps) and prefills baud rate, data bits, parity and handshake. The baud rate is Hamlib's maximum for that model; the allowed range is shown — match the value with the setting on your radio. - Pick the port, enter the CI-V address for Icom-backend models if needed, Start.
What differs with the free profile:
- No band plausibility check, no CAT tune button, no low-voltage power correction and no voice keyer row — those extras exist only for the curated profiles.
- Auto-detect only tries the curated profiles.
- Models that Hamlib reaches over the network (FLRig, SDRConsole, further Flex slices …) cannot be selected here: start
rigctldyourself and use the "Network (rigctld)" path. Models with a parallel port or a dedicated driver are rejected. - Hamlib keeps a status for every backend (Stable, Beta, Alpha, Untested). With Beta and below, mode or PTT may not work cleanly — that is a Hamlib limitation, not one of HAM-Tools. If a model works well for you, let us know: it may well become a curated profile.
The free profile is saved with the configuration (multi-config works as usual). If you switch back to a curated manufacturer, its factory defaults apply again.
Hamlib Under the Hood
HAM-Tools ships its own rigctld binary (Universal2, in Contents/Helpers/rigctld inside the app bundle). You don't need to install a separate Hamlib.
rigctld is spawned as a subprocess at CAT start with the matching arguments:
rigctld -m <hamlibRigNumber> -r <port> -s <baud> -C data_bits=8,stop_bits=1,...For ICOM, civaddr=0xXX is added to the -C argument automatically.
Troubleshooting
| Symptom | Possible cause |
|---|---|
| Badge stays gray on "CAT off", "Start" grayed out | No model or port chosen; for IC-705 Wi-Fi the radio IP, user or password is empty; for Network (rigctld) an invalid port |
| Badge turns red "CAT err" | Port busy (another app is running), baud doesn't match, cable unplugged — tip: auto-detect finds model + baud by itself |
| Auto-detect finds nothing | Radio off, cable unplugged, or another program holds the serial port — and on Icom: a changed CI-V address (the search probes the factory address) |
| Connected but freq stays at 0 | Wrong CI-V (on ICOM), radio in the wrong mode |
| Connected but mode stays on "—" | The Hamlib module for this model doesn't support mode read |
| Connection drops | USB adapter driver issue — try another cable, update the FTDI driver |
For reproducible problems → Report a bug… (Cmd+Shift+B) with the diagnostics attachment enabled.
Transceiver Menu
In the menu bar under Transceiver:
- Reset CAT (⌃⇧⌘R) — reconnects the active config
- Connect CAT or Disconnect CAT (⇧⌘T)
- Load TRX setup — switches the active config; if CAT is connected, it reconnects
- Save TRX setup… — saves the active config under a new name
- Settings… — opens the settings
Tips
- Multi-radio shack: one config per radio — switch with the picker, no entry marathon
- Portable: a second config with a different USB adapter port (can vary depending on the USB hub)
- Test without hardware: the
Hamlib Dummy Rig (test without hardware)profile → sets arbitrary values, good for UI tests