RIGCTLTCP(1)

📦 version 4.7.2, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu stonking

💖 RIGCTLTCP 💖

okay bestie, sit down, hydrate, because we're about to talk about rigctltcp from the Hamlib Utilities and it is lowkey a whole vibe. this is the RIGCTLTCP(1) page, part 1, and we are getting into it. no skimming, no scrolling past the boring bits — every flag, every default, every warning is staying right here. periodt. ✨

🌸 NAME 🌸

rigctltcp — TCP multicast control of radio transceivers and receivers 🎀

like, it talks to your radios. over the network. multicast. iconic behavior honestly.

🦋 SYNOPSIS 🦋

rigctltcp [-hlLuoVR] [-m id] [-r device] [-p device] [-d device]
          [-P type] [-D type] [-s baud] [-c id] [-S char] [-C parm=val]
          [-T ipaddr] [-t num] [-M addr] [-n port] [-W secs] [-w secs]
          [-x option] [-A password] [-v[-Z]]

that's the whole shape of it. keep scrolling for what each little guy actually does 👑

💅 DESCRIPTION 💅

so rigctltcp is a network daemon — and the way it eats is by enabling UDP multicast broadcasts that carry rig snapshot data. it supports bidirectional rig control and status, so it's a two-way conversation, not a one-sided situationship. 💞

and the broadcast data? it can be either rigctld(1) token pairs or JSON. your choice, no judgment. ✨

every single packet gets tagged with a unique id string, which is the whole reason multiple rigs can broadcast and receive on the same port without it becoming total chaos. it's giving organized. it's giving coordinated. 🫶

and it will eventually be able to set frequency, mode, passband width, PTT status, satmode, and split status to start — since those are common to so many apps. more functions plan to be added as time goes on. the roadmap is growing. 🌱

the broadcast packet contents are based on get_rig_info output and may contain multiple VFO lines. peep the EXAMPLES section below for that. 👀

✨ OPTIONS ✨

okay this program follows the usual GNU command line syntax, bestie. here's the tea:

  • short options that take an argument may have the value follow immediately, or be separated by a space.
  • long options starting with two dashes (-) require an = between the option and any argument.

here's the summary of everything supported:

  • -m, --model=ID — pick your radio model number. defaults to Dummy, ID 1. want the model list? run rigctltcp -l. 🎀
note: rigctltcp (or third party software using the C API) will use ID 2 for NET rigctl (that's the one communicating with rigctld).
  • -r, --rig-file=DEVICE — use DEVICE as the file name of the port connected to the radio. typically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux, COM1, COM2, etc. on MS Windows. the BSD flavors and MacOS have their own device names — see your system's documentation. 🐧🪟🍎
    • can also be a network address:port, e.g. 127.0.0.1:12345
    • the special string uh-rig may be given to enable micro-ham device support. (yes really, tiny rig energy 🐜)
  • -p, --ptt-file=DEVICE — use DEVICE as the file name of the Push To Talk device, using a device filename as described in -r above. 🎙️
  • -d, --dcd-file=DEVICE — use DEVICE as the file name of the Data Carrier Detect device, using a device filename as described in -r above.
  • -P, --ptt-type=TYPE — use TYPE of Push To Talk device. supported types are RIG (CAT command), DTR, RTS, PARALLEL, CM108, GPIO, GPION, NONE — this overrides the PTT type defined in the rig's backend. 🌈
some side effects bestie, listen: when type is set to DTR, read PTT state comes from the Hamlib frontend, not read from the radio. when set to NONE, PTT state cannot be read or set even if the rig backend supports reading/setting PTT status from the rig. 💀
  • -D, --dcd-type=TYPE — use TYPE of Data Carrier Detect device. supported types are RIG (CAT command), DSR, CTS, CD, PARALLEL, CM108, GPIO, GPION, NONE. 🎀
  • -s, --serial-speed=BAUD — set serial speed to BAUD rate. it uses the maximum serial speed from the radio backend capabilities (set by -m above) as the default.
  • -c, --civaddr=ID — use ID as the CI–V address to communicate with the rig. only useful for Icom and some Ten–Tec rigs. 🌸
note: the id is in decimal notation, unless prefixed by 0x, in which case it is hexadecimal.
  • -S, --separator=CHAR — use CHAR as separator instead of line feed. the default is \n. recommend using $ or @ as they work on both POSIX and MS Windows. 💫
  • -L, --show-conf — list all config parameters for the radio defined with -m above. will exit if no -r is given. note the dummy device has no serial parameters. 🙈
  • -C, --set-conf=PARM=val[,PARM=val] — set configuration parameter(s). some common ones are:
    • async: True enables asynchronous data transfer for backends that support it. this allows use of transceive and spectrum data. 📡
    • auto_power_on: True enables compatible rigs to be powered up on open. ⚡
    • auto_power_off: True enables compatible rigs to be powered down on close.
    • auto_disable_screensaver: True enables compatible rigs to have their screen saver disabled on open. 😴
    • dcd_type: Data Carrier Detect (or squelch) interface type override.
    • dcd_pathname: Path name to the device file of the Data Carrier Detect (or squelch).
    • disable_yaesu_bandselect: True disables the automatic band select on band change for Yaesu rigs.
    • dtr_state: ON turns on DTR, OFF turns it off, disabled when not set.
    • freq_skip: !=0 skips setting freq on TX_VFO when in RX and on RX_VFO when in TX—for use with gpredict and rigs that do not have TARGETABLE_VFO.
    • lo_freq: Frequency to add to the VFO frequency for use with a transverter.
    • post_write_delay: Delay in ms between each command sent out.
    • ptt_share: True enables ptt port to be shared with other apps.
    • ptt_type: Push–To–Talk interface type override.
    • ptt_pathname: Path name to the device file of the Push–To–Talk.
    • ptt_bitnum: Push–To–Talk GPIO bit number.
    • retry: Max number of retries.
    • rts_state: ON turns on DTR, OFF turns it off, disabled when not set.
    • twiddle_timeout: For satellite ops when VFOB is twiddled will pause VFOB commands until timeout.
    • twiddle_rit: Suppress get_freq on VFOB for RIT tuning satellites.
    • timeout: Timeout in ms.
    • write_delay: Delay in mS between each byte sent out.
    • tuner_control_pathname: Path name to a script/program to control a tuner with 1 argument of 0/1 for Tuner Off/On.
use the -L option above for a list of configuration parameters for a given model number. 👑
  • -l, --list — list all model numbers defined in Hamlib and exit. the list is sorted by model number. 🦋
note: the list can be scrolled back using Shift+PageUp/Shift+PageDown, or using the scrollbars of a terminal emulator in X/Wayland or the cmd window in MS Windows. the output can be piped to more(1) or less(1), e.g. rigctltcp -l | more. 💅
  • -u, --dump-caps — dump capabilities for the radio defined with -m above and exit. 🎀
  • -o, --vfo — enable vfo mode. an extra VFO argument will be required in front of each appropriate command (except set_vfo). otherwise, currVFO is used when this option is not set and an extra VFO argument is not used. see chk_vfo below. 🌈
  • -v, --verbose — set verbose mode, cumulative (see DIAGNOSTICS below). 🔍
  • -T, --listen-addr=IPADDR — use IPADDR as the listening IP address. the default is ANY (0.0.0.0).
  • -t, --port=NUM — use NUM as the TCP listening port. the default is 4531. 🔌
  • -M, --multicast-addr=ADDR — use ADDR as the multicast IP address. the default is OFF (0.0.0.0). recommended IPv4 setting is 224.0.1.1. 📻
  • -n, --multicast-port=PORT — use number as the TCP listening port. the default is 4532.
  • -W, --twiddle_timeout=SECONDS — enables timeout when VFO twiddling is detected. some functions will be ignored. should only be needed when controlling software should be "paused" so you can move the VFO. continuous movement extends the timeout. ⏳
  • -w, --twiddle_rit=SECONDS — suppress VFOB get_freq so RIT can be twiddled.
  • -x, --uplink=OPTION — 1=Sub, 2=Main. for GPredict use this option to ignore get_freq for Sub or Main uplink VFO. should allow downlink VFO movement without confusing GPredict or the uplink. 🛰️
  • -Z, --debug-time-stamps — enable time stamps for the debug messages. use only in combination with the -v option as it generates no output on its own. 🕰️
  • -A, --password=PASSWORD — sets a password on rigctltcp which requires Hamlib to use rig_set_password and clients to use PASSWORD to access rigctltcp. a 32 character shared secret will be displayed to be used on the client side. 🔐
(NOT IMPLEMENTED) 💀
  • -R, --rigctltcp-idle — will make rigctltcp close the rig when no clients are connected. normally remains connected to speed up connects.
  • -h, --help — show a summary of these options and exit. 🫶
  • -V, --version — show version of rigctltcp and exit.
note: some options may not be implemented by a given backend and will return an error. this is most likely to occur with the --set-conf and --show-conf options.
please note that the backend for the radio to be controlled, or the radio itself, may not support some commands. in that case, the operation will fail with a Hamlib error code. 😭

🔍 DIAGNOSTICS 🔍

the -v, --verbose option allows different levels of diagnostics to be output to stderr, and they correspond like this, bestie:

  1. -v → for BUG
  2. -vv → for ERR
  3. -vvv → for WARN
  4. -vvvv → for VERBOSE
  5. -vvvvv → for TRACE

a given verbose level is useful for providing needed debugging information to the email address below. for example, TRACE output shows all of the values sent to and received from the radio, which is very useful for radio backend library development and may be requested by the developers. 🛠️✨

🚪 EXIT STATUS 🚪

rigctltcp exits with:

  1. 0 — if all operations completed normally; ✅
  2. 1 — if there was an invalid command line option or argument; 🙈
  3. 2 — if an error was returned by Hamlib. 💥

okay that's where part 1 wraps — but we are NOT done yet, so don't go anywhere bestie, there's more coming 🫶✨

✨ EXAMPLES ✨

Okay bestie, here's what a multicast packet actually looks like — this one's dated 2023-10-20, so you know exactly what era of vibes we're working with. She's giving real data, real fields, real JSON. Look at her glow 💖

{
  "app": "Hamlib",
  "version": "4.6~git 2023-10-20T16:52:59Z SHA=d87671",
  "seq": 183,
  "time": "2023-10-20T20:13:53.139869-0000",
  "crc": 0,
  "rig": {
    "id": "FLRig:127.0.0.1:12345:30508",
    "status": "OK",
    "errorMsg": "",
    "name": "FLRig",
    "split": false,
    "splitVfo": "VFOA",
    "satMode": false,
    "modelist": "AM CW USB LSB FM CWR PKTLSB PKTUSB "
  },
  "vfos": [
    {
      "name": "VFOA",
      "freq": 14074270,
      "mode": "PKTUSB",
      "width": 3,
      "ptt": false,
      "rx": true,
      "tx": true
    },
    {
      "name": "VFOB",
      "freq": 14074500,
      "mode": "",
      "width": 0,
      "ptt": false,
      "rx": false,
      "tx": false
    }
  ],
  "spectra": [
    {
      "id": 0,
      "name": "?",
      "type": "FIXED",
      "minLevel": 0,
      "maxLevel": 0,
      "minStrength": 0,
      "maxStrength": 0,
      "centerFreq": 0,
      "span": 0,
      "lowFreq": 0,
      "highFreq": 0,
      "length": 0,
      "data": ""
    }
  ]
}

Like… the whole rig, just floating out there in a packet, being all structured and adorable 🌸 seq be counting, crc be checking, and the spectra array is sitting there with "data": "" because she's empty and unbothered, honestly iconic.

💀 BUGS 💀

This woefully incomplete document.

Like, that's it. That's the whole bug report. The docs are not serving, and the page itself is telling on itself. Not me reading a manual that admits it's incomplete 😭 at least she's honest!

🎀 COPYING 🎀

This file is part of Hamlib, a project to develop a library that simplifies radio, rotator, and amplifier control functions for developers of software primarily of interest to radio amateurs and those interested in radio communications.

Copyright © 2000-2011 Stephane Fillod

Copyright © 2000-2026 the Hamlib Group (various contributors)

Copyright © 2010-2026 Nate Bargmann

This is free software; see the file COPYING for copying conditions.

There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. 🫶 So yes bestie, she's free, she's open, and she is absolutely not promising you anything legally. Adjust expectations accordingly. ✨

👑 SEE ALSO 👑

Go read those too, iykyk — the lore runs deep and they're all connected 💜

🌈 COLOPHON 🌈

Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org. The mothership is right there, go explore 💅

And that's the whole page, bestie!! 🎀 This was RIGCTLTCP(1) from the Hamlib source, dated 2026-02-14 — you read all of it, you understood all of it, and honestly? Slay. Go multicast something pretty. 🌸💖✨

📦 where this page comes from