Provided by: libhamlib-utils_3.3-5_amd64 bug

NAME

       rotctl - control antenna rotators

SYNOPSIS

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

DESCRIPTION

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

              Often a serial port, but could be a USB to serial adapter.   Typically  /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 format prepended with “0x”.  You may pass an
              empty string for no termination char.  The string “-1” tells rotctl  to  switch  to
              binary protocol.  See the send_cmd command for further explanation.

              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 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 terminal 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 READLINE 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 rotator itself may not
       support some commands.  In that case, the operation will fail with a Hamlib error code.

COMMANDS

       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 argument(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 upper case letter will
       often be used for a set method whereas the corresponding 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 information.

       Note: The backend for the rotator to be controlled, or the rotator itself 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 ‘#’ character 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
            10.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 description.  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
              network 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 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 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 conversions.

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

              Floating point values are supplied.   The  precision  of  the  returned  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

              returns:

                 Locator: AA55AA00AA00

       l, loc2lonlat 'Locator'
              Returns 'Longitude' and 'Latitude' in decimal degrees at the approximate 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 longitude 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.

READLINE

       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
       ⟨https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩.  rotctl sets the name “rotctl”
       which can be used in Conditional Init Constructs in the Readline Init File ($HOME/.inputrc
       by default) for custom keybindings unique to rotctl.

       Command  history  is  available with Readline support as described in the Readline History
       manual   ⟨https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩.     Command    and
       argument  strings  are  stored  as single lines even when arguments are prompted for input
       individually.  Commands and arguments are not validated  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 current 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 destination directory
       may be changed by setting the ROTCTL_HIST_DIR environment 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 internal  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 history, however, it is not  saved  to  disk  between
       sessions.

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

       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.

EXAMPLE

       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

BUGS

       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 simplifies radio and
       rotator control functions for developers  of  software  primarily  of  interest  to  radio
       amateurs and those interested in radio communications.

       Copyright © 2001-2011 Stephane Fillod
       Copyright © 2002-2017 the Hamlib Group (various contributors)
       Copyright © 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 PARTICULAR PURPOSE.

SEE ALSO

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

COLOPHON

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

              hamlib.org ⟨http://www.hamlib.org⟩.