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

FreeBSD Manual Pages


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

       rotctl -	control	antenna	rotators

       rotctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
	      [-v[-Z]] [command|-]

       Control antenna rotators.

       rotctl accepts commands from the	command	line as	well as	in interactive
       mode if none are	provided on the	command	line.

       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.

       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 "rotctl -l").

	      Note: rotctl (or third party software using the C	API) will  use
	      rotator model 2 for NET rotctl (communicating with rotctld).

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

	      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, --send-cmd-term=char
	      Change the termination char for text  protocol  when  using  the
	      send_cmd command.

	      The  default  value  is  ASCII  CR (`0x0D').  ASCII non-printing
	      characters can be	given as the ASCII number in hexadecimal  for-
	      mat  prepended  with  "0x".  You may pass	an empty string	for no
	      termination char.	 The string "-1" tells rotctl to switch	to bi-
	      nary  protocol.	See  the send_cmd command for further explana-

	      Note: The	semicolon (`;')	is a common  terminator	 for  rotators
	      that accept ASCII	character strings.

       -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

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

       -i, --read-history
	      Read  previously	saved command and argument history from	a file
	      (default $HOME/.rotctl_history) for the current session.

	      Available	when rotctl is built with Readline support (see	 READ-
	      LINE below).

	      Note:  To	 read  a history file stored in	another	directory, set
	      the     ROTCTL_HIST_DIR	  environment	   variable,	  e.g.
	      "ROTCTL_HIST_DIR=$HOME/tmp  rotctl -i".  When ROTCTL_HIST_DIR is
	      not set, the value of HOME is used.

       -I, --save-history
	      Write current session (and any previous session(s), if -i	option
	      is  also	given) command and argument history to a file (default
	      $HOME/.rotctl_history) at	the end	of the current session.

	      Complete commands	with arguments are saved as a single  line  to
	      be  recalled and used or edited.	Available when rotctl is built
	      with Readline support (see READLINE below).

	      Note: To write a history file  in	 another  directory,  set  the
	      ROTCTL_HIST_DIR	      environment	 variable,	  e.g.
	      "ROTCTL_HIST_DIR=$HOME/tmp rotctl	-I".  When ROTCTL_HIST_DIR  is
	      not set, the value of HOME is used.

       -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 rotctl and exit.

       -      Stop option processing and read commands from standard input.

	      See Standard Input below.

       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	opera-
       tion will fail with a Hamlib error code.

       Commands	can be entered either as a single char,	or as a	 long  command
       name.   The  commands  are not prefixed with a dash as the options are.
       They may	be typed in when in interactive	 mode  or  provided  as	 argu-
       ment(s)	in  command line interface mode.  In interactive mode commands
       and their arguments may be entered on a single line:

	    P 123 45

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

       Example:	Use "\get_info"	in interactive mode to see the	rotator's  in-

       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.

   Standard Input
       As an alternative to the	READLINE interactive command entry or a	single
       command for each	run, rotctl features a special option where  a	single
       dash  (`-')  may	 be used to read commands from standard	input (stdin).
       Commands	must be	separated by whitespace	similar	to the commands	 given
       on  the	command	 line.	Comments may be	added using the	`#' character,
       all text	up until the end of the	current	line including the `#' charac-
       ter is ignored.

       A simple	example:

	    $ cat <<.EOF. >cmds.txt
	    > #	File of	commands
	    > set_pos 180.0 10.0     # rotate
	    > pause 30	# wait for action to complete
	    > get_pos	# query	rotator
	    > .EOF.

	    $ rotctl -m	1 - <cmds.txt

	    set_pos 180.0 10.0
	    pause 30
	    get_pos 180.000000


   Rotator Commands
       A  summary  of  commands	is included below (In the case of set commands
       the quoted italicized string is replaced	by the value in	 the  descrip-
       tion.   In the case of get commands the quoted italicized string	is the
       key name	of the value returned.):

       Q|q, exit rotctl
	      Exit rotctl in interactive mode.

	      When rotctl is controlling the rotator directly, will close  the
	      rotator  backend	and port.  When	rotctl is connected to rotctld
	      (rotator model 2), the TCP/IP connection to  rotctld  is	closed
	      and  rotctld  remains running, available for another TCP/IP net-
	      work connection.

       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

       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 miscellaneous	information about the rotator.

	      Returns 'Info' "Model Name" at present.

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

	      ASCII  CR	 (or --send-cmd-term value, see	-t option) 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

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

	      Floating point values are	supplied.  The precision  of  the  re-
	      turned square is controlled by 'Loc Len' which should be an even
	      numbered integer value between 2 and 12.

	      For example:

		 L -170.0 -85.0	12


		 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


		 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

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

       If Readline library development files  are  found  at  configure	 time,
       rotctl will be conditonally built with Readline support for command and
       argument	entry.	Readline command key bindings are at their defaults as
       described	   in		the	      Readline		manual
       <>.	rotctl
       sets the	name "rotctl" which can	be used	in Conditional Init Constructs
       in the Readline Init File ($HOME/.inputrc by default) for  custom  key-
       bindings	unique to rotctl.

       Command	history	is available with Readline support as described	in the
       Readline				History				manual
       <>.  Command
       and argument strings are	stored as single lines even when arguments are
       prompted	 for input individually.  Commands and arguments are not vali-
       dated and are stored as typed with values separated by a	single space.

       Normally	session	history	is not saved, however, use of  either  of  the
       -i/--read-history  or  -I/--save-history	 options  when starting	rotctl
       will cause any previously saved history to be read in and/or  the  cur-
       rent  and  any previous session history (assuming the -i	and -I options
       are given together) will	be written out when rotctl  is	closed.	  Each
       option is mutually exclusive, i.e. either may be	given separately or in
       combination.  This is useful to save a set of commands  and  then  read
       them  later  but	not write the modified history for a consistent	set of
       test commands in	interactive mode, for example.

       History is stored in $HOME/.rotctl_history by default although the des-
       tination	 directory may be changed by setting the ROTCTL_HIST_DIR envi-
       ronment variable.  When ROTCTL_HIST_DIR is unset, the value of the HOME
       environment  variable  is used instead.	Only the destination directory
       may be changed at this time.

       If Readline support is not found	at configure time the original	inter-
       nal  command handler is used.  Readline is not used for rotctl commands
       entered on the command line regardless if Readline support is built  in
       or not.

       Note:  Readline	support	is not included	in the MS Windows 32 or	64 bit
       binary builds supplied by the Hamlib Project.  Running rotctl on	the MS
       Windows platform	in the `cmd' shell does	give session command line his-
       tory, however, it is not	saved to disk between sessions.

       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-

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

       Start rotctl for	RotorEZ	using the first	serial port on Linux:

	    $ rotctl -m	401 -r /dev/ttyS0

       Start rotctl for	RotorEZ	using COM2 on MS Windows:

	    $ rotctl -m	401 -r COM2

       Connect to a running rotctld with rotator model 2 ("NET rotctl")	on the
       local host and specifying the TCP port, and querying the	position:

	    $ rotctl -m	2 -r localhost:4533 \get_pos

       Report bugs to:

	      Hamlib Developer mailing list

       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

       Copyright (C) 2001-2011 Stephane	Fillod
       Copyright (C) 2002-2017 the Hamlib Group	(various contributors)
       Copyright (C) 2003-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

       less(1),	more(1), rotctld(1), hamlib(7)

       Links to	the Hamlib Wiki, Git repository, release archives,  and	 daily
       snapshot	archives: <>.

Hamlib				  2018-04-29			     ROTCTL(1)


Want to link to this manual page? Use this URL:

home | help