Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
RIGCTLTCP(1)			Hamlib Utilities		    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 broad-
     cast/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 de-
	    vice 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 ra-
	    dio.   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', `PARAL-
	    LEL', `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  over-
		ride.
		dcd_pathname:  Path  name to the device file of the Data Carrier
		Detect (or squelch).
		disable_yaesu_bandselect: True disables the automatic  band  se-
		lect 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 satel-
		lites.
		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-Page-
	    Down, 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  up-
	    link 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  re-
     turn  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  out-
     put  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  com-
     munications.

     Copyright (C) 2000-2011 Stephane Fillod
     Copyright (C) 2000-2026 the Hamlib Group (various contributors)
     Copyright (C) 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 snap-
     shot archives are available via hamlib.org.

Hamlib				   2026-02-14			    RIGCTLTCP(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=rigctltcp&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>

home | help