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

FreeBSD Manual Pages

  
 
  

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

NAME
       rotctld - TCP rotator control daemon

SYNOPSIS
       rotctld [-hlLuV]	[-m id]	[-r device] [-s	baud] [-T IPADDR] [-t number]
	       [-C parm=val] [-v[-Z]]

DESCRIPTION
       The rotctld program is a	rotator	control	daemon that handles client re-
       quests  via  TCP	 sockets.  This	allows multiple	user programs to share
       one rotator (this needs more development).  Multiple  rotators  can  be
       controlled on different TCP ports by use	of multiple rotctld processes.
       The syntax of the commands are the same as rotctl(1).  It is hoped that
       rotctld	will  be  especially useful for	client authors using languages
       such as Perl, Python, PHP, and others.

       rotctld communicates to a client	through	a TCP socket using  text  com-
       mands shared with rotctl.  The protocol is simple, commands are sent to
       rotctld on one line and rotctld 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
       rotctl (rotator 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 rotctld 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 rotator model number.

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

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

       -r, --rot-file=device
	      Use  device  as the file name of the port	connected to the rota-
	      tor.

	      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.

       -s, --serial-speed=baud
	      Set serial speed to baud rate.

	      Uses  maximum  serial speed from rotator backend capabilities as
	      the default.

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

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

       -L, --show-conf
	      List  all	 configuration parameters for the rotator defined with
	      -m above.

       -C, --set-conf=parm=val[,parm=val]
	      Set rotator 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  rotator  defined with -m above and
	      exit.

       -l, --list
	      List all rotator 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.	"rotctl	-l | more".

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

       Be aware	that the backend for the rotator to be controlled, or the  ro-
       tator 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 rota-
       tor'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
       rotctld.	 This is a possible bug, beware!).

       Note:  The backend for the rotator to be	controlled, or the rotator it-
       self 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.):

       P, set_pos 'Azimuth' 'Elevation'
	      Set position.

	      'Azimuth'	and 'Elevation'	are floating point values.

	      For example:

		 P 163.0 41.0

	      Note: If the rotator does	not support setting elevation (most do
	      not) supply "0.0"	for 'Elevation'.

       p, get_pos
	      Get position.

	      'Azimuth'	 and  'Elevation'  are	returned  as  double precision
	      floating point values.

       M, move 'Direction' 'Speed'
	      Move the rotator in a specific direction at the given rate.

	      'Direction' is an	integer	defined	as `2' = Up, `4' = Down, `8' =
	      Left, and	`16' = Right.

	      'Speed' is an integer between 1 and 100.

	      Note:  Not  all backends that implement the move command use the
	      Speed value.  At this time only the gs232a  utilizes  the	 Speed
	      parameter.

       S, stop
	      Stop the rotator.

       K, park
	      Park the rotator.

       C, set_conf 'Token' 'Value'
	      Set a configuration parameter.

	      'Token' is a string; see the -C option and the -L	output.

	      'Value' is a string of up	to 20 characters.

       R, reset	'Reset'
	      Reset the	rotator.

	      'Reset' accepts an integer value of `1' for "Reset All".

       _, get_info
	      Get misc information about the rotator.

	      Returns 'Info' "Model Name".

       w, send_cmd 'Cmd'
	      Send a raw command string	to the rotator.

	      ASCII CR is appended automatically at the	end of the command for
	      text protocols.  For binary protocols, enter hexadecimal	values
	      as "\0xAA\0xBB".

   Locator Commands
       These  commands	offer  conversions of Degrees Minutes Seconds to other
       formats,	Maidenhead square locator conversions and distance and azimuth
       conversions.

       L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
	      Returns  the  Maidenhead 'Locator' for the given 'Longitude' and
	      'Latitude'.

	      'Longitude' and 'Latitude' are floating point values.

	      'Loc Len'	is the precision of the	returned square	and should  be
	      an even numbered integer value between 2 and 12.

	      For example:

		 L -170.0 -85.0	12

	      returns:

		 Locator: AA55AA00AA00

       l, loc2lonlat 'Locator'
	      Returns 'Longitude' and 'Latitude' in decimal degrees at the ap-
	      proximate	center of the requested	Maidenhead grid	square.

	      'Locator'	can be from 2 to 12 characters in length.

	      West longitude is	expressed as a negative	value.

	      South latitude is	expressed as a negative	value.

	      For example:

		 l AA55AA00AA00

	      returns:

		 Longitude: -169.999983	Latitude: -84.999991

	      Note: Despite the	use of double precision	variables  internally,
	      some rounding error occurs.

       D, dms2dec 'Degrees' 'Minutes' 'Seconds'	'S/W'
	      Returns 'Dec Degrees', a signed floating point value.

	      'Degrees'	and 'Minutes' are integer values.

	      'Seconds'	is a floating point value.

	      'S/W'  is	a flag with `1'	indicating South latitude or West lon-
	      gitude and `0' North or East (the	flag is	 needed	 as  computers
	      don't  recognize	a  signed  zero	even though only the 'Degrees'
	      value is typically signed	in DMS notation).

       d, dec2dms 'Dec Degrees'
	      Returns 'Degrees'	'Minutes' 'Seconds' 'S/W'.

	      Values are as in dms2dec above.

       E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
	      Returns 'Dec Degrees', a signed floating point value.

	      'Degrees'	is an integer value.

	      'Dec Minutes' is a floating point	value.

	      'S/W' is a flag as in dms2dec above.

       e, dec2dmmm 'Dec	Deg'
	      Returns 'Degrees'	'Minutes' 'S/W'.

	      Values are as in dmmm2dec	above.

       B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
	      Returns 'Distance' and 'Azimuth'.

	      'Distance' is in km.

	      'Azimuth'	is in degrees.

	      Supplied Lon/Lat values are signed floating point	numbers.

       A, a_sp2a_lp 'Short Path	Deg'
	      Returns 'Long Path Deg'.

	      Both the supplied	argument and returned value are	floating point
	      values within the	range of 0.00 to 360.00.

	      Note: Supplying a	negative value will return an error message.

       a, d_sp2d_lp 'Short Path	km'
	      Returns 'Long Path km'.

	      Both the supplied	argument and returned value are	floating point
	      values.

       pause 'Seconds'
	      Pause for	the given whole	(integer) number of  'Seconds'	before
	      sending the next command to the rotator.

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

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

       The Extended Response Protocol is intended to be	used with  scripts  or
       other programs interacting directly with	rotctld	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 position (Perl code):

	    print $socket "P 135 10\n";

       or:

	    print $socket "\\set_pos 135 10\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 rotctld 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 position (Perl code):

	    print $socket "p\n";
	    "135"
	    "10"

       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 rotctl" (rotctl model 2)
       backend which allows applications already written for Hamlib's C	API to
       take  advantage	of  rotctld  without the need of rewriting application
       code.  An application's user can	select rotator model 2 ("NET  rotctl")
       and   then  set	rot_pathname  to  "localhost:4533"  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 rotctld and adds a rule for the command syntax.

       1. The command received by rotctld 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	rotator	 back-
       end  are	 prepended  by a string	immediately followed by	a colon	then a
       space and then the value	terminated by  the  response  separator,  e.g.
       "Azimuth: 90.000000\n" when the command was prepended by	`+'.

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

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

	    $ echo "+P 90 45" |	nc -w 1	localhost 4533
	    set_pos: 90	45
	    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 rotor backend return value	indicating success.

       An example response to a	get_pos	query:

	    $ echo "+\get_pos" | nc -w 1 localhost 4533
	    get_pos:
	    Azimuth: 90.000000
	    Elevation: 45.000000
	    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 rotctld, the first line consists
       only of the long	command	name.  The final line shows that  the  command
       was processed successfully by the rotor 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 rotctl.

       `_'    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_pos query with a leading `;'	returns:

	    get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0

       Or, using the pipe character `|'	returns:

	    get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0

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

	    set_pos: 135 22.5|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!

       All commands with the exception of set_conf have	been tested  with  the
       Extended	Response protocol and the included testrotctld.pl Perl script.

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  rotctld  for a Hy-Gain Ham IV rotor with the Idiom Press RotorEZ
       board installed using a USB-to-serial adapter and backgrounding:

	    $ rotctld -m 401 -r	/dev/ttyUSB1 &

       Start rotctld for RotorEZ using COM2 on Win32:

       $ rotctl	-m 401 -r COM2

       Connect to the already running rotctld, and set position	to  135.0  de-
       grees  azimuth  and 30.0	degrees	elevation with a 1 second read timeout
       from the	shell prompt:

	    $ echo "\set_pos 135.0 30.0" | nc -w 1 localhost 4533

       Connect to a running rotctld with rotctl	on the local host:

	    $ rotctl -m	2

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 rotctld does not need	any greater permissions	than rotctl, it	is ad-
       visable	to  not	start rotctld 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-2009 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),	rotctl(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			    ROTCTLD(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=rotctld&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help