RIGCTLTCP(1)

NAME
rigctltcp - TCP multicast control of radio transceivers and receivers

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]]

DESCRIPTION
Network daemon enabling UDP multicast broadcasts containing rig snapshot data. Supports bidirectional rig control and status. Broadcast data can be either rigctld(1) token pairs or JSON.

All packets are tagged with a unique id string so multiple rigs can broadcast/rx on the same port. Will eventually be able to set frequency, mode, passband width, PTT status, satmode, and split status to start since those are common to many apps. More functions plan to be added as time goes on.

Broadcast packet contents are based on get_rig_info output and may contain multiple VFO lines. See EXAMPLES below.

OPTIONS
This program follows the usual GNU command line syntax. 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 is a summary of the supported options:

-m, --model=ID
    Select radio model number. Defaults to Dummy, ID 1.

    See model list (use “rigctltcp -l”).

    Note: rigctltcp (or third party software using the C API) will use ID 2 for NET rigctl (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 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.

-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’, overriding PTT type defined in the rig's backend.

    Some side effects of this command are that 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 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.

    Uses maximum serial speed from 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 correspond to -v for BUG, -vv for ERR, -vvv for WARN, -vvvv for VERBOSE, or -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:

0   if all operations completed normally;

1   if there was an invalid command line option or argument;

2   if an error was returned by Hamlib.

EXAMPLES
This is an example of a multicast packet as of 2023-10-20.

    {
      "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": ""
        }
      ]
    }

BUGS
This woefully incomplete document.

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.

SEE ALSO
rigctl(1), hamlib(7)

COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org (http://www.hamlib.org).