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

FreeBSD Manual Pages

  
 
  

home | help
RIGCTLD(1)		       Hamlib Utilities			    RIGCTLD(1)

NAME
       rigctld - TCP radio control daemon

SYNOPSIS
       rigctld [-hlLouV] [-m id] [-r device] [-p device] [-d device] [-P type]
	       [-D type] [-s baud] [-c id] [-T IPADDR] [-t number]
	       [-C parm=val] [-v[-Z]]

DESCRIPTION
       The  rigctld  program is	a radio	control	daemon that handles client re-
       quests via TCP sockets.	This allows multiple user  programs  to	 share
       one  radio  (this needs more development).  Multiple radios can be con-
       trolled on different TCP	ports by use of	 multiple  rigctld  processes.
       Note  that  multiple processes/ports are	also necessary if some clients
       use extended responses and/or vfo mode.	So up to 4 processes/ports may
       be needed for each combination of extended response/vfo mode.  The syn-
       tax of the commands are the  same  as  rigctl(1).   It  is  hoped  that
       rigctld	will  be  especially useful for	client authors using languages
       such as Perl, Python, PHP, and others.

       rigctld communicates to a client	through	a TCP socket using  text  com-
       mands shared with rigctl.  The protocol is simple, commands are sent to
       rigctld on one line and rigctld responds	to "get" commands with the re-
       quested	values,	 one per line, when successful,	otherwise, it responds
       with one	line "RPRT x", where `x' is a negative number  indicating  the
       error  code.   Commands that do not return values respond with the line
       "RPRT x", where `x' is `0' when successful,  otherwise  is  a  regative
       number  indicating the error code.  Each	line is	terminated with	a new-
       line `\n' character.  This protocol is primarily	for  use  by  the  NET
       rigctl (radio model 2) backend.

       A  separate  Extended  Response	Protocol extends the above behavior by
       echoing the received command string as a	header,	any returned values as
       a  key:	value  pair,  and  the	"RPRT x" string	as the end of response
       marker which includes the Hamlib	success	or  failure  value.   See  the
       PROTOCOL	section	for details.  Consider using this protocol for clients
       that will interact with rigctld directly	through	a TCP socket.

       Keep in mind that Hamlib	is BETA	level software.	 While a lot of	 back-
       end  libraries  lack  complete rotator support, the basic functions are
       usually well supported.

       Please report bugs and provide feedback at the e-mail address given  in
       the BUGS	section	below.	Patches	and code enhancements sent to the same
       address are welcome.

OPTIONS
       This program follows the	usual GNU command line syntax.	Short  options
       that take an argument may have the value	follow immediately or be sepa-
       rated 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.

	      See model	list (use "rigctl -l").

	      Note:  rigctl (or	third party software using the C API) will use
	      radio model 2 for	NET rigctl (this model number is not used  for
	      rigctld even though it shows in the model	list).

       -r, --rig-file=device
	      Use device as the	file name of the port connected	to the radio.

	      Often a serial port, but could be	a USB to serial	adapter.  Typ-
	      ically /dev/ttyS0,  /dev/ttyS1,  /dev/ttyUSB0,  etc.  on	Linux,
	      COM1,  COM2,  etc.  on MS	Windows.  The BSD flavors and Mac OS/X
	      have their own designations.  See	your system's documentation.

	      The special string "uh-rig" may be given to enable micro-ham de-
	      vice support.

       -p, --ptt-file=device
	      Use  device  as the file name of the Push-To-Talk	device using a
	      device file as described above.

       -d, --dcd-file=device
	      Use device as the	file name of the Data  Carrier	Detect	device
	      using a device file as described above.

       -P, --ptt-type=type
	      Use type of Push-To-Talk device.

	      Supported	 types	are `RIG' (CAT command), `DTR',	`RTS', `PARAL-
	      LEL', `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', `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.

       -T, --listen-addr=IPADDR
	      Use IPADDR as the	listening IP address.

	      The default is ANY.

       -t, --port=number
	      Use number as the	TCP listening port.

	      The default is 4532.

	      Note:  As	rotctld's default port is 4533,	it is advisable	to use
	      even numbered ports for rigctld, e.g. 4532, 4534,	4536, etc.

       -L, --show-conf
	      List all config parameters for the radio defined with -m above.

       -C, --set-conf=parm=val[,parm=val]
	      Set radio	configuration parameter(s), e.g.  stop_bits=2.

	      Use the -L option	above for a list of  configuration  parameters
	      for a given model	number.

       -u, --dump-caps
	      Dump capabilities	for the	radio defined with -m above and	exit.

       -l, --list
	      List all model numbers defined in	Hamlib and exit.

	      The list is sorted by model number.

	      Note:  In	 Linux	the  list  can	be  scrolled back using	Shift-
	      PageUp/Shift-PageDown, or	using the scrollbars of	a virtual ter-
	      minal  in	 X  or	the  cmd window	in Windows.  The output	can be
	      piped to more(1) or less(1), e.g.	"rigctl	-l | more".

       -o, --vfo
	      Enable vfo mode.

	      An extra VFO argument will be required in	front of  each	appro-
	      priate  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).

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

       -h, --help
	      Show a summary of	these options and exit.

       -V, --version
	      Show version of rigctl 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 ra-
       dio  itself may not support some	commands.  In that case, the operation
       will fail with a	Hamlib error code.

COMMANDS
       Commands	can be sent over the TCP socket	either as a single char, or as
       a  long command name plus the value(s) space separated on one `\n' ter-
       minated line. See PROTOCOL.

       Since most of the Hamlib	operations have	a set and a get	method,	an up-
       per  case letter	will be	used for set methods whereas the corresponding
       lower case letter refers	to the get method.  Each operation also	has  a
       long name; prepend a backslash, `\', to send a long command name.

       Example	(Perl):	 "print	 $socket "\\dump_caps\n";" to see what the ra-
       dio's backend can do (Note: In Perl and many other languages a `\' will
       need  to	 be escaped with a preceding `\' so that even though two back-
       slash characters	appear in  the	code,  only  one  will	be  passed  to
       rigctld.	 This is a possible bug, beware!).

       Note:  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 message.

       Here  is	 a  summary of the supported commands (In the case of set com-
       mands the quoted	italicized string is replaced by the value in the  de-
       scription.  In the case of get commands the quoted italicized string is
       the key name of the value returned.):

       F, set_freq 'Frequency'
	      Set 'Frequency', in Hz.

	      Frequency	may be a floating point	or integer value.

       f, get_freq
	      Get 'Frequency', in Hz.

	      Returns an integer value.

       M, set_mode 'Mode' 'Passband'
	      Set 'Mode' and 'Passband'.

	      Mode is a	token: `USB', `LSB',  `CW',  `CWR',  `RTTY',  `RTTYR',
	      `AM',  `FM',  `WFM',  `AMS',  `PKTLSB',  `PKTUSB', `PKTFM', `EC-
	      SSUSB', `ECSSLSB', `FA', `SAM', `SAL', `SAH', `DSB'.

	      Passband is in Hz	as an integer, or `0' for  the	radio  backend
	      default.

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      Mode token will return a space separated list of	radio  backend
	      supported	Modes.	Use this to determine the supported Modes of a
	      given radio backend.

       m, get_mode
	      Get 'Mode' and 'Passband'.

	      Returns Mode as a	token and Passband in Hz as in set_mode	above.

       V, set_vfo 'VFO'
	      Set 'VFO'.

	      VFO is a token: `VFOA', `VFOB', `VFOC', `currVFO', `VFO',	`MEM',
	      `Main', `Sub', `TX', `RX'.

	      In VFO mode (see --vfo option above) only	a single VFO parameter
	      is required:

		 $ rigctl -m 229 -r /dev/rig -o

		 Rig command: V
		 VFO: VFOB

		 Rig command:

       v, get_vfo
	      Get current 'VFO'.

	      Returns VFO as a token as	in set_vfo above.

       J, set_rit 'RIT'
	      Set 'RIT'.

	      RIT is in	Hz and can be +	or -.  A value of `0' resets RIT  (Re-
	      ceiver Incremental Tuning) to match the VFO frequency.

	      Note:  RIT  needs	to be explicitly activated or deactivated with
	      the set_func command.  This allows setting the RIT offset	 inde-
	      pendently	 of  its  activation  and  allows RIT to remain	active
	      while setting the	offset to `0'.

       j, get_rit
	      Get 'RIT'	in Hz.

	      Returned value is	an integer.

       Z, set_xit 'XIT'
	      Set 'XIT'.

	      XIT is in	Hz and can be +	or -.	A  value  of  `0'  resets  XIT
	      (Transmitter Incremental Tuning) to match	the VFO	frequency.

	      Note:  XIT  needs	to be explicitly activated or deactivated with
	      the set_func command.  This allows setting the XIT offset	 inde-
	      pendently	 of  its  activation  and  allows XIT to remain	active
	      while setting the	offset to `0'.

       z, get_xit
	      Get 'XIT'	in Hz.

	      Returned value is	an integer.

       T, set_ptt 'PTT'
	      Set 'PTT'.

	      PTT is a value: `0' (RX),	`1' (TX), `2' (TX  mic),  or  `3'  (TX
	      data).

       t, get_ptt
	      Get 'PTT'	status.

	      Returns PTT as a value in	set_ptt	above.

       S, set_split_vfo	'Split'	'TX VFO'
	      Set 'Split' mode.

	      Split is either `0' = Normal or `1' = Split.

	      Set 'TX VFO'.

	      TX  VFO  is  a  token: `VFOA', `VFOB', `VFOC', `currVFO',	`VFO',
	      `MEM', `Main', `Sub', `TX', `RX'.

       s, get_split_vfo
	      Get 'Split' mode.

	      Split is either `0' = Normal or `1' = Split.

	      Get 'TX VFO'.

	      TX VFO is	a token	as in set_split_vfo above.

       I, set_split_freq 'Tx Frequency'
	      Set 'TX Frequency', in Hz.

	      Frequency	may be a floating point	or integer value.

       i, get_split_freq
	      Get 'TX Frequency', in Hz.

	      Returns an integer value.

       X, set_split_mode 'TX Mode' 'TX Passband'
	      Set 'TX Mode' and	'TX Passband'.

	      TX Mode is a token: `USB', `LSB',	`CW', `CWR', `RTTY',  `RTTYR',
	      `AM',  `FM',  `WFM',  `AMS',  `PKTLSB',  `PKTUSB', `PKTFM', `EC-
	      SSUSB', `ECSSLSB', `FA', `SAM', `SAL', `SAH', `DSB'.

	      TX Passband is in	Hz as an integer, or `0' for the radio backend
	      default.

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      TX Mode token will return	a space	separated list of radio	 back-
	      end  supported TX	Modes.	Use this to determine the supported TX
	      Modes of a given radio backend.

       x, get_split_mode
	      Get 'TX Mode' and	'TX Passband'.

	      Returns TX Mode  as  a  token  and  TX  Passband	in  Hz	as  in
	      set_split_mode above.

       Y, set_ant 'Antenna'
	      Set 'Antenna' number (`0', `1', `2', ...).

       y, get_ant
	      Get 'Antenna' number (`0', `1', `2', ...).

       b, send_morse 'Morse'
	      Send 'Morse' symbols.

       0x8b, get_dcd
	      Get 'DCD'	(squelch) status: `0' (Closed) or `1' (Open).

       R, set_rptr_shift 'Rptr Shift'
	      Set 'Rptr	Shift'.

	      Rptr Shift is one	of: `+', `-', or something else	for `None'.

       r, get_rptr_shift
	      Get 'Rptr	Shift'.

	      Returns `+', `-',	or `None'.

       O, set_rptr_offs	'Rptr Offset'
	      Set 'Rptr	Offset', in Hz.

       o, get_rptr_offs
	      Get 'Rptr	Offset', in Hz.

       C, set_ctcss_tone 'CTCSS	Tone'
	      Set 'CTCSS Tone',	in tenths of Hz.

       c, get_ctcss_tone
	      Get 'CTCSS Tone',	in tenths of Hz.

       D, set_dcs_code 'DCS Code'
	      Set 'DCS Code'.

       d, get_dcs_code
	      Get 'DCS Code'.

       0x90, set_ctcss_sql 'CTCSS Sql'
	      Set 'CTCSS Sql' tone, in tenths of Hz.

       0x91, get_ctcss_sql
	      Get 'CTCSS Sql' tone, in tenths of Hz.

       0x92, set_dcs_sql 'DCS Sql'
	      Set 'DCS Sql' code.

       0x93, get_dcs_sql
	      Get 'DCS Sql'
	       code.

       N, set_ts 'Tuning Step'
	      Set 'Tuning Step', in Hz.

       n, get_ts
	      Get 'Tuning Step', in Hz.

       U, set_func 'Func' 'Func	Status'
	      Set 'Func' and 'Func Status'.

	      Func  is	a  token: `FAGC', `NB',	`COMP',	`VOX', `TONE', `TSQL',
	      `SBKIN', `FBKIN',	`ANF', `NR', `AIP', `APF', `MON', `MN',	 `RF',
	      `ARO',  `LOCK', `MUTE', `VSC', `REV', `SQL', `ABM', `BC',	`MBC',
	      `RIT', `AFC', `SATMODE', `SCOPE',	`RESUME',  `TBURST',  `TUNER',
	      `XIT'.

	      Func  Status is a	non null value for "activate" or "de-activate"
	      otherwise, much as TRUE/FALSE  definitions  in  the  C  language
	      (true is non-zero	and false is zero, `0').

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      Func token will return a space separated list of	radio  backend
	      supported	 set  function tokens.	Use this to determine the sup-
	      ported functions of a given radio	backend.

       u, get_func 'Func'
	      Get 'Func	Status'.

	      Returns Func Status as a non null	value for the Func token given
	      as in set_func above.

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      Func token will return a space separated list of	radio  backend
	      supported	 get  function tokens.	Use this to determine the sup-
	      ported functions of a given radio	backend.

       L, set_level 'Level' 'Level Value'
	      Set 'Level' and 'Level Value'.

	      Level is a token:	`PREAMP', `ATT',  `VOX',  `AF',	 `RF',	`SQL',
	      `IF',  `APF',  `NR',  `PBT_IN', `PBT_OUT', `CWPITCH', `RFPOWER',
	      `MICGAIN', `KEYSPD', `NOTCHF', `COMP', `AGC',  `BKINDL',	`BAL',
	      `METER',	`VOXGAIN', `ANTIVOX', `SLOPE_LOW', `SLOPE_HIGH', `RAW-
	      STR', `SWR', `ALC', `STRENGTH'.

	      The Level	Value can be a float or	an integer value.  For the AGC
	      token  the  value	 is  one  of `0' = OFF,	`1' = SUPERFAST, `2' =
	      FAST, `3'	= SLOW,	`4' = USER, `5'	= MEDIUM, `6' =	AUTO.

	      Note: Passing a `?' (query) as the first argument	instead	 of  a
	      Level  token will	return a space separated list of radio backend
	      supported	set level tokens.  Use this to determine the supported
	      levels of	a given	radio backend.

       l, get_level 'Level'
	      Get 'Level Value'.

	      Returns  Level  Value  as	a float	or integer for the Level token
	      given as in set_level above.

	      Note: Passing a `?' (query) as the first argument	instead	 of  a
	      Level  token will	return a space separated list of radio backend
	      supported	get level tokens.  Use this to determine the supported
	      levels of	a given	radio backend.

       P, set_parm 'Parm' 'Parm	Value'
	      Set 'Parm' and 'Parm Value'.

	      Parm  is	a  token:  `ANN',  `APO', `BACKLIGHT', `BEEP', `TIME',
	      `BAT', `KEYLIGHT'.

	      Note: Passing a `?' (query) as the first argument	instead	 of  a
	      Parm  token  will	return a space separated list of radio backend
	      supported	set parameter tokens.  Use this	to determine the  sup-
	      ported parameters	of a given radio backend.

       p, get_parm 'Parm'
	      Get 'Parm	Value'.

	      Returns  Parm  Value  as	a  float or integer for	the Parm token
	      given as in set_parm above.

	      Note: Passing a `?' (query) as the first argument	instead	 of  a
	      Parm  token  will	return a space separated list of radio backend
	      supported	get parameter tokens.  Use this	to determine the  sup-
	      ported parameters	of a given radio backend.

       B, set_bank 'Bank'
	      Set 'Bank'.

	      Sets the current memory bank number.

       E, set_mem 'Memory#'
	      Set 'Memory#' channel number.

       e, get_mem
	      Get 'Memory#' channel number.

       G, vfo_op 'Mem/VFO Op'
	      Perform a	'Mem/VFO Op'.

	      Mem/VFO	Operation  is  a  token:  `CPY',  `XCHG',  `FROM_VFO',
	      `TO_VFO',	`MCL', `UP', `DOWN', `BAND_UP',	 `BAND_DOWN',  `LEFT',
	      `RIGHT', `TUNE', `TOGGLE'.

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      Mem/VFO Op token will return a space  separated  list  of	 radio
	      backend  supported Set Mem/VFO Op	tokens.	 Use this to determine
	      the supported Mem/VFO Ops	of a given radio backend.

       g, scan 'Scan Fct' 'Scan	Channel'
	      Perform a	'Scan Fct' on a	'Scan Channel'.

	      Scan Function is a token:	`STOP',	`MEM', `SLCT', `PRIO', `PROG',
	      `DELTA', `VFO', `PLT'.

	      Scan Channel is an integer (maybe?).

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      Scan Fct token will return a space separated list	of radio back-
	      end  supported  Scan Function tokens.  Use this to determine the
	      supported	Scan Functions of a given radio	backend.

       H, set_channel 'Channel'
	      Set memory 'Channel' data.

	      Not implemented yet.

       h, get_channel
	      Get memory 'Channel' data.

	      Not implemented yet.

       A, set_trn 'Transceive'
	      Set 'Transceive' mode.

	      Transcieve is a token: `OFF', `RIG', `POLL'.

	      Transceive is a mechanism	for radios to report events without  a
	      specific call for	information.

	      Note:  Passing  a	`?' (query) as the first argument instead of a
	      Transceive token will return a space  separated  list  of	 radio
	      backend supported	Transceive mode	tokens.	 Use this to determine
	      the supported Transceive modes of	a given	radio backend.

       a, get_trn
	      Get 'Transceive' mode.

	      Transceive mode (reporting event)	as in set_trn above.

       *, reset	'Reset'
	      Perform rig 'Reset'.

	      Reset is a value:	`0' = None, `1'	= Software reset,  `2'	=  VFO
	      reset, `4' = Memory Clear	reset, `8' = Master reset.

	      Since  these  values  are	 defined  as a bitmask in include/ham-
	      lib/rig.h, it should be possible to AND these values together to
	      do  multiple  resets at once, if the backend supports it or sup-
	      ports a reset action via rig control at all.

       0x87, set_powerstat 'Power Status'
	      Set 'Power Status'.

	      Power Status is a	value: `0' = Power Off,	`1' = Power On,	`2'  =
	      Power Standby.

       0x88, get_powerstat
	      Get 'Power Status' as in set_powerstat above.

       0x89, send_dtmf 'Digits'
	      Set DTMF 'Digits'.

       0x8a, recv_dtmf
	      Get DTMF 'Digits'.

       _, get_info
	      Get  misc	 information  about  the  rig (no VFO in 'VFO mode' or
	      value is passed).

       1, dump_caps
	      Not a real rig remote command, it	just dumps capabilities,  i.e.
	      what the backend knows about this	model, and what	it can do.

	      TODO:  Ensure  this  is in a consistent format so	it can be read
	      into a hash, dictionary, etc.  Bug reports requested.

	      Note: This command will produce many lines of output so be  very
	      careful  if  using  a  fixed length array!  For example, running
	      this command against the Dummy backend results in	 over  5kB  of
	      text output.

	      VFO parameter not	used in	'VFO mode'.

       2, power2mW 'Power [0.0..1.0]' 'Frequency' 'Mode'
	      Returns 'Power mW'.

	      Converts	a  Power  value	 in  a	range of 0.0...1.0 to the real
	      transmit power in	milli-Watts (integer).

	      'Frequency' and 'Mode' also need to be provided as output	 power
	      may vary according to these values.

	      VFO parameter is not used	in VFO mode.

       4, mW2power 'Power mW' 'Frequency' 'Mode'
	      Returns 'Power [0.0..1.0]'.

	      Converts	the  real transmit power in milli-Watts	(integer) to a
	      Power value in a range of	0.0 ...	1.0.

	      'Frequency' and 'Mode' also need to be provided as output	 power
	      may vary according to these values.

	      VFO parameter is not used	in VFO mode.

       chk_vfo
	      Returns  "CHKVFO	1\n" (single line only)	if rigctld was invoked
	      with the -o/--vfo	option and "CHKVFO 0\n"	if not.

	      When in VFO mode the client will need to pass 'VFO' as the first
	      parameter	to set or get commands.	 VFO is	one of the strings de-
	      fined in set_vfo above.

PROTOCOL
       There are two protocols in use by rigctld, the Default Protocol and the
       Extended	Response Protocol.

       The  Default  Protocol  is intended primarily for the communication be-
       tween Hamlib library functions and rigctld ("NET	rigctl", available us-
       ing radio model `2').

       The  Extended  Response Protocol	is intended to be used with scripts or
       other programs interacting directly with	rigctld	as consistent feedback
       is provided.

   Default Protocol
       The  Default Protocol is	intentionally simple.  Commands	are entered on
       a single	line with any needed values.  In  practice,  reliable  results
       are  obtained by	terminating each command string	with a newline charac-
       ter, `\n'.

       Example set frequency and mode commands (Perl code):

	    print $socket "F 14250000\n";
	    print $socket "\\set_mode LSB 2400\n";   # escape leading '\'

       A one line response will	be sent	as a reply to set commands, "RPRT x\n"
       where  x	 is  the  Hamlib error code with `0' indicating	success	of the
       command.

       Responses from rigctld get commands are text values and match the  same
       tokens  used  in	 the  set  commands. Each value	is returned on its own
       line.  On error the string "RPRT	x\n" is	returned where x is the	Hamlib
       error code.

       Example get frequency (Perl code):

	    print $socket "f\n";
	    "14250000\n"

       Most  get  functions return one to three	values.	A notable exception is
       the dump_caps command which returns many	lines of key:value pairs.

       This protocol is	primarily used by the "NET rigctl"  (rigctl  model  2)
       backend which allows applications already written for Hamlib's C	API to
       take advantage of rigctld without the  need  of	rewriting  application
       code.   An application's	user can select	rotator	model 2	("NET rigctl")
       and  then  set  rig_pathname  to	 "localhost:4532"  or  other   network
       host:port (set by the -T/-t options, respectively, above).

   Extended Response Protocol
       The  Extended  Response	protocol adds several rules to the strings re-
       turned by rigctld and adds a rule for the command syntax.

       1. The command received by rigctld is echoed with its long command name
       followed	 by  the value(s) (if any) received from the client terminated
       by the specified	response separator as the  first  record  of  the  re-
       sponse.

       2.  The	last  record of	each block is the string "RPRT x\n" where x is
       the numeric return value	of the Hamlib backend function that was	called
       by the command.

       3.  Any records consisting of data values returned by the radio backend
       are prepended by	a string immediately followed by a colon then a	 space
       and  then  the  value  terminated by the	response separator. e.g. "Fre-
       quency: 14250000\n" when	the command was	prepended by `+'.

       4. All commands received	will be	acknowledged by	rigctld
	with records from rules	1 and 2.  Records from rule  3	are  only  re-
       turned when data	values must be returned	to the client.

       An  example  response  to a set_mode command sent from the shell	prompt
       (note the prepended `+'):

	    $ echo "+M USB 2400" | nc -w 1 localhost 4532
	    set_mode: USB 2400
	    RPRT 0

       In this case the	long command name and values are returned on the first
       line  and  the second line contains the end of block marker and the nu-
       meric radio backend return value	indicating success.

       An example response to a	get_mode query:

	    $ echo "+\get_mode"	| nc -w	1 localhost 4532
	    get_mode:
	    Mode: USB
	    Passband: 2400
	    RPRT 0

	      Note: The	`\' is still required for the long command  name  even
	      with the ERP character.

       In this case, as	no value is passed to rigctld, the first line consists
       only of the long	command	name.  The final line shows that  the  command
       was processed successfully by the radio backend.

       Invoking	 the  Extended Response	Protocol requires prepending a command
       with a punctuation character.  As shown in the examples above, prepend-
       ing a `+' character to the command results in the responses being sepa-
       rated by	a newline character (`\n').  Any other	punctuation  character
       recognized  by  the  C  ispunct() function except `\', `?', or `_' will
       cause that character to become the response separator  and  the	entire
       response	will be	on one line.

       Separator character summary:

       `+'    Each record of the response is appended with a newline (`\n').

       `;', `|', or, `,'
	      Each  record  of the response is appended	by the given character
	      resulting	in entire response on one line.

	      These are	common record separators for text  representations  of
	      spreadsheet data,	etc.

       `?'    Reserved for help	in rigctl.

       `_'    Reserved for get_info short command

       `#'    Reserved for comments when reading a command file	script.

	      Note: Other punctuation characters have not been tested!	Use at
	      your own risk.

       For example, invoking a get_mode	query with a leading `;' returns:

	    get_mode:;Mode: USB;Passband: 2400;RPRT 0

       Or, using the pipe character `|'	returns:

	    get_mode:|Mode: USB|Passband: 2400|RPRT 0

       And a set_mode command prepended	with a `|' returns:

	    set_mode: USB 2400|RPRT 0

       Such a format will allow	reading	a response as a	single event  using  a
       preferred  response  separator.	 Other punctuation characters have not
       been tested!

       The following commands have been	tested with the	Extended Response pro-
       tocol and the included testctld.pl Perl script:

	      set_freq,	 get_freq,  set_split_freq,  get_split_freq, set_mode,
	      get_mode,	 set_split_mode,  get_split_mode,  set_vfo,   get_vfo,
	      set_split_vfo,   get_split_vfo,	set_rit,   get_rit,   set_xit,
	      get_xit, set_ptt,	get_ptt, power2mW, mW2power, dump_caps.

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 informa-
       tion  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 de-
       velopers.

EXAMPLE
       Start rigctld for a Yaesu FT-920	 using	a  USB-to-serial  adapter  and
       backgrounding:

	    $ rigctld -m 114 -r	/dev/ttyUSB1 &

       Start  rigctld  for  a Yaesu FT-920 using a USB-to-serial adapter while
       setting baud rate and stop bits,	and backgrounding:

	    $ rigctld -m 114 -r	/dev/ttyUSB1 -s	4800 -C	stop_bits=2 &

       Start rigctld for an Elecraft K3	using COM2 on MS Windows:

	    $ rigctld -m 229 -r	COM2

       Connect to the already running rigctld and set the frequency to	14.266
       MHz  with  a  1 second read timeout using the default protocol from the
       shell prompt:

	    $ echo "\set_freq 14266000"	| nc -w	1 localhost 4532

       Connect to a running rigctld with rigctl	on the local host:

	    $ rigctl -m2

SECURITY
       No authentication whatsoever; DO	NOT leave this TCP port	open  wide  to
       the  Internet.	Please	ask if stronger	security is needed or consider
       using a Secure Shell (ssh(1)) tunnel.

       As rigctld does not need	any greater permissions	than rigctl, it	is ad-
       visable	to  not	start rigctld as "root"	or another system user account
       in order	to limit any vulnerability.

BUGS
       The daemon is not detaching and backgrounding itself.

       No method to exit the daemon so the kill(1) command  must  be  used  to
       terminate it.

       Multiple	 clients  using	 the daemon may	experience contention with the
       connected rotator.

       Report bugs to:

	      Hamlib Developer mailing list
	      <hamlib-developer@lists.sourceforge.net>

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

       Copyright (C) 2000-2010 Stephane	Fillod
       Copyright (C) 2000-2018 the Hamlib Group	(various contributors)
       Copyright (C) 2011-2018 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
       kill(1),	rigctl(1), ssh(1), hamlib(7)

COLOPHON
       Links  to  the Hamlib Wiki, Git repository, release archives, and daily
       snapshot	archives:

	      hamlib.org <http://www.hamlib.org>.

Hamlib				  2018-04-29			    RIGCTLD(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | PROTOCOL | DIAGNOSTICS | EXAMPLE | SECURITY | BUGS | COPYING | SEE ALSO | COLOPHON

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rigctld&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help