1ROTCTL(1)                      Hamlib Utilities                      ROTCTL(1)
2
3
4

NAME

6       rotctl - control antenna rotators
7

SYNOPSIS

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

DESCRIPTION

13       Control antenna rotators.
14
15       rotctl accepts commands from the command line as well as in interactive
16       mode if none are provided on the command line.
17
18       Keep  in mind that Hamlib is BETA level software.  While a lot of back‐
19       end libraries lack complete rotator support, the  basic  functions  are
20       usually well supported.
21
22       Please  report bugs and provide feedback at the e-mail address given in
23       the BUGS section below.  Patches and code enhancements sent to the same
24       address are welcome.
25

OPTIONS

27       This  program follows the usual GNU command line syntax.  Short options
28       that take an argument may have the value follow immediately or be sepa‐
29       rated  by a space.  Long options starting with two dashes (‘-’) require
30       an ‘=’ between the option and any argument.
31
32       Here is a summary of the supported options:
33
34       -m, --model=id
35              Select rotator model number.
36
37              See model list (use “rotctl -l”).
38
39              Note: rotctl (or third party software using the C API) will  use
40              rotator model 2 for NET rotctl (communicating with rotctld).
41
42       -r, --rot-file=device
43              Use  device  as the file name of the port connected to the rota‐
44              tor.
45
46              Often a serial port, but could be a USB to serial adapter.  Typ‐
47              ically  /dev/ttyS0,  /dev/ttyS1,  /dev/ttyUSB0,  etc.  on Linux,
48              COM1, COM2, etc. on MS Windows.  The BSD flavors  and  Mac  OS/X
49              have their own designations.  See your system's documentation.
50
51       -R, --rot-file2=device
52              Use device as the file name of the port connected to the 2nd ro‐
53              tator.  e.g. 2nd rotator used for elevation.
54
55              Often a serial port, but could be a USB to serial adapter.  Typ‐
56              ically  /dev/ttyS0,  /dev/ttyS1,  /dev/ttyUSB0,  etc.  on Linux,
57              COM1, COM2, etc. on MS Windows.  The BSD flavors  and  Mac  OS/X
58              have their own designations.  See your system's documentation.
59
60       -s, --serial-speed=baud
61              Set serial speed to baud rate.
62
63              Uses  maximum  serial speed from rotator backend capabilities as
64              the default.
65
66       -t, --send-cmd-term=char
67              Change the termination char for text  protocol  when  using  the
68              send_cmd command.
69
70              The  default  value  is  ASCII  CR (‘0x0D’).  ASCII non-printing
71              characters can be given as the ASCII number in hexadecimal  for‐
72              mat  prepended  with  “0x”.  You may pass an empty string for no
73              termination char.  The string “-1” tells rotctl to switch to bi‐
74              nary  protocol.   See  the send_cmd command for further explana‐
75              tion.
76
77              Note: The semicolon (‘;’) is a common  terminator  for  rotators
78              that accept ASCII character strings.
79
80       -L, --show-conf
81              List  all  configuration parameters for the rotator defined with
82              -m above.
83
84       -C, --set-conf=parm=val[,parm=val]
85              Set rotator configuration parameter(s),  e.g.  stop_bits=2.
86
87              Use the -L option above for a list of  configuration  parameters
88              for a given model number.
89
90       -u, --dump-caps
91              Dump  capabilities  for  the  rotator  defined with -m above and
92              exit.
93
94       -l, --list
95              List all rotator model numbers defined in Hamlib and exit.
96
97              The list is sorted by model number.
98
99              Note: In Linux the  list  can  be  scrolled  back  using  Shift-
100              PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
101              minal in X or the cmd window in  Windows.   The  output  can  be
102              piped to more(1) or less(1), e.g. “rotctl -l | more”.
103
104       -i, --read-history
105              Read  previously  saved command and argument history from a file
106              (default $HOME/.rotctl_history) for the current session.
107
108              Available when rotctl is built with Readline support (see  READ‐
109              LINE below).
110
111              Note:  To  read  a history file stored in another directory, set
112              the     ROTCTL_HIST_DIR     environment      variable,      e.g.
113              “ROTCTL_HIST_DIR=$HOME/tmp  rotctl -i”.  When ROTCTL_HIST_DIR is
114              not set, the value of HOME is used.
115
116       -I, --save-history
117              Write current session (and any previous session(s), if -i option
118              is  also  given) command and argument history to a file (default
119              $HOME/.rotctl_history) at the end of the current session.
120
121              Complete commands with arguments are saved as a single  line  to
122              be  recalled and used or edited.  Available when rotctl is built
123              with Readline support (see READLINE below).
124
125              Note: To write a history file  in  another  directory,  set  the
126              ROTCTL_HIST_DIR         environment        variable,        e.g.
127              “ROTCTL_HIST_DIR=$HOME/tmp rotctl -I”.  When ROTCTL_HIST_DIR  is
128              not set, the value of HOME is used.
129
130       -v, --verbose
131              Set verbose mode, cumulative (see DIAGNOSTICS below).
132
133       -Z, --debug-time-stamps
134              Enable time stamps for the debug messages.
135
136              Use  only  in  combination with the -v option as it generates no
137              output on its own.
138
139       -h, --help
140              Show a summary of these options and exit.
141
142       -V, --version
143              Show version of rotctl and exit.
144
145       -      Stop option processing and read commands from standard input.
146
147              See Standard Input below.
148
149       Note: Some options may not be implemented by a given backend  and  will
150       return  an error.  This is most likely to occur with the --set-conf and
151       --show-conf options.
152
153       Be aware that the backend for the rotator to be controlled, or the  ro‐
154       tator  itself  may not support some commands.  In that case, the opera‐
155       tion will fail with a Hamlib error code.
156

COMMANDS

158       Commands can be entered either as a single char, or as a  long  command
159       name.   The  commands  are not prefixed with a dash as the options are.
160       They may be typed in when in interactive  mode  or  provided  as  argu‐
161       ment(s)  in  command line interface mode.  In interactive mode commands
162       and their arguments may be entered on a single line (typed  text  shown
163       in bold):
164
165           P 123 45
166
167       Since most of the Hamlib operations have a set and a get method, an up‐
168       per case letter will often be used for a set method whereas the  corre‐
169       sponding  lower  case  letter refers to the get method.  Each operation
170       also has a long name; in interactive mode, prepend a backslash, ‘\’, to
171       enter a long command name.
172
173       Example:  Use  “\get_info” in interactive mode to see the rotator's in‐
174       formation.
175
176              Note: The backend for the rotator to be controlled, or the rota‐
177              tor  itself may not support some commands. In that case, the op‐
178              eration will fail with a Hamlib error message.
179
180   Standard Input
181       As an alternative to the READLINE interactive command entry or a single
182       command  for  each run, rotctl features a special option where a single
183       dash (‘-’) may be used to read commands from  standard  input  (stdin).
184       Commands  must be separated by whitespace similar to the commands given
185       on the command line.  Comments may be added using  the  ‘#’  character,
186       all text up until the end of the current line including the ‘#’ charac‐
187       ter is ignored.
188
189       A simple example:
190
191           $ cat <<.EOF. >cmds.txt
192           > # File of commands
193           > set_pos 180.0 10.0     # rotate
194           > pause 30  # wait for action to complete
195           > get_pos   # query rotator
196           >.EOF.
197
198           $ rotctl -m 1 - <cmds.txt
199
200           set_pos 180.0 10.0
201           pause 30
202           get_pos 180.000000
203           10.000000
204
205           $
206
207   Rotator Commands
208       A summary of commands is included below (In the case  of  set  commands
209       the  quoted  italicized string is replaced by the value in the descrip‐
210       tion.  In the case of get commands the quoted italicized string is  the
211       key name of the value returned.):
212
213       Q|q, exit rotctl
214              Exit rotctl in interactive mode.
215
216              When  rotctl is controlling the rotator directly, will close the
217              rotator backend and port.  When rotctl is connected  to  rotctld
218              (rotator  model  2),  the TCP/IP connection to rotctld is closed
219              and rotctld remains running, available for another  TCP/IP  net‐
220              work connection.
221
222       P, set_pos 'Azimuth' 'Elevation'
223              Set position.
224
225              'Azimuth' and 'Elevation' are floating point values.
226
227              Azimuth can be -180 to 540 depending on the rotator to allow for
228              rotators facing south and the capabilities of the rotator.
229
230              Elevation can be -20 to 210 depending on the rotator.
231
232              For example:
233
234                  P 163.0 41.0
235
236              Note: If the rotator does not support setting elevation (most do
237              not) supply “0.0” for 'Elevation'.
238
239       p, get_pos
240              Get position.
241
242              'Azimuth'  and  'Elevation'  are  returned  as  double precision
243              floating point values.
244
245       M, move 'Direction' 'Speed'
246              Move the rotator in a specific direction at the given rate.
247
248              'Direction' is an integer or keyword defined as ‘2’ = UP, ‘4’  =
249              DOWN, ‘8’ = LEFT or CCW and ‘16’ = RIGHT or CW
250
251              'Speed' is an integer between 1 and 100. Use -1 for no change to
252              current speed.
253
254              Note: Not all backends that implement the move command  use  the
255              Speed value.
256
257       S, stop
258              Stop the rotator.
259
260       K, park
261              Park the rotator.
262
263       C, set_conf 'Token' 'Value'
264              Set a configuration parameter.
265
266              'Token' is a string; see the -C option and the -L output.
267
268              'Value' is a string of up to 20 characters.
269
270       R, reset 'Reset'
271              Reset the rotator.
272
273              'Reset' accepts an integer value of ‘1’ for “Reset All”.
274
275       _, get_info
276              Get miscellaneous information about the rotator.
277
278              Returns 'Info' “Model Name” at present.
279
280       dump_state
281              Return certain state information about the rotator backend.
282
283       1, dump_caps
284              Not  a real rot remote command, it just dumps capabilities, i.e.
285              what the backend knows about this model, and what it can do.
286
287       w, send_cmd 'Cmd'
288              Send a raw command string to the rotator.
289
290              ASCII CR (or --send-cmd-term value, see -t option)  is  appended
291              automatically at the end of the command for text protocols.  For
292              binary protocols, enter hexadecimal values as “\0xAA\0xBB”.
293
294   Locator Commands
295       These commands offer conversions of Degrees Minutes  Seconds  to  other
296       formats, Maidenhead square locator conversions and distance and azimuth
297       conversions.
298
299       L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
300              Returns the Maidenhead 'Locator' for the given  'Longitude'  and
301              'Latitude'.
302
303              Floating  point  values  are supplied.  The precision of the re‐
304              turned square is controlled by 'Loc Len' which should be an even
305              numbered integer value between 2 and 12.
306
307              For example:
308
309                  L -170.0 -85.0 12
310
311              returns:
312
313                  Locator: AA55AA00AA00
314
315       l, loc2lonlat 'Locator'
316              Returns 'Longitude' and 'Latitude' in decimal degrees at the ap‐
317              proximate center of the requested Maidenhead grid square.
318
319              'Locator' can be from 2 to 12 characters in length.
320
321              West longitude is expressed as a negative value.
322
323              South latitude is expressed as a negative value.
324
325              For example:
326
327                  l AA55AA00AA00
328
329              returns:
330
331                  Longitude: -169.999983 Latitude: -84.999991
332
333              Note: Despite the use of double precision variables  internally,
334              some rounding error occurs.
335
336       D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
337              Returns 'Dec Degrees', a signed floating point value.
338
339              'Degrees' and 'Minutes' are integer values.
340
341              'Seconds' is a floating point value.
342
343              'S/W'  is a flag with ‘1’ indicating South latitude or West lon‐
344              gitude and ‘0’ North or East (the flag is  needed  as  computers
345              don't  recognize  a  signed  zero even though only the 'Degrees'
346              value is typically signed in DMS notation).
347
348       d, dec2dms 'Dec Degrees'
349              Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
350
351              Values are as in dms2dec above.
352
353       E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
354              Returns 'Dec Degrees', a signed floating point value.
355
356              'Degrees' is an integer value.
357
358              'Dec Minutes' is a floating point value.
359
360              'S/W' is a flag as in dms2dec above.
361
362       e, dec2dmmm 'Dec Deg'
363              Returns 'Degrees' 'Minutes' 'S/W'.
364
365              Values are as in dmmm2dec above.
366
367       B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
368              Returns 'Distance' and 'Azimuth'.
369
370              'Distance' is in km.
371
372              'Azimuth' is in degrees.
373
374              Supplied Lon/Lat values are signed floating point numbers.
375
376       A, a_sp2a_lp 'Short Path Deg'
377              Returns 'Long Path Deg'.
378
379              Both the supplied argument and returned value are floating point
380              values within the range of 0.00 to 360.00.
381
382              Note: Supplying a negative value will return an error message.
383
384       a, d_sp2d_lp 'Short Path km'
385              Returns 'Long Path km'.
386
387              Both the supplied argument and returned value are floating point
388              values.
389
390       pause 'Seconds'
391              Pause for the given whole (integer) number of  'Seconds'  before
392              sending the next command to the rotator.
393

READLINE

395       If  Readline  library  development  files  are found at configure time,
396       rotctl will be conditonally built with Readline support for command and
397       argument entry.  Readline command key bindings are at their defaults as
398       described          in           the           Readline           manual
399https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩.      rotctl
400       sets the name “rotctl” which can be used in Conditional Init Constructs
401       in  the  Readline Init File ($HOME/.inputrc by default) for custom key‐
402       bindings unique to rotctl.
403
404       Command history is available with Readline support as described in  the
405       Readline                         History                         manual
406https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩.  Command
407       and argument strings are stored as single lines even when arguments are
408       prompted for input individually.  Commands and arguments are not  vali‐
409       dated and are stored as typed with values separated by a single space.
410
411       Normally  session  history  is not saved, however, use of either of the
412       -i/--read-history or -I/--save-history  options  when  starting  rotctl
413       will  cause  any previously saved history to be read in and/or the cur‐
414       rent and any previous session history (assuming the -i and  -I  options
415       are  given  together)  will be written out when rotctl is closed.  Each
416       option is mutually exclusive, i.e. either may be given separately or in
417       combination.   This  is  useful to save a set of commands and then read
418       them later but not write the modified history for a consistent  set  of
419       test commands in interactive mode, for example.
420
421       History is stored in $HOME/.rotctl_history by default although the des‐
422       tination directory may be changed by setting the ROTCTL_HIST_DIR  envi‐
423       ronment variable.  When ROTCTL_HIST_DIR is unset, the value of the HOME
424       environment variable is used instead.  Only the  destination  directory
425       may be changed at this time.
426
427       If  Readline support is not found at configure time the original inter‐
428       nal command handler is used.  Readline is not used for rotctl  commands
429       entered  on the command line regardless if Readline support is built in
430       or not.
431
432       Note: Readline support is not included in the MS Windows 32 or  64  bit
433       binary builds supplied by the Hamlib Project.  Running rotctl on the MS
434       Windows platform in the ‘cmd’ shell does give session command line his‐
435       tory, however, it is not saved to disk between sessions.
436

DIAGNOSTICS

438       The  -v,  --verbose option allows different levels of diagnostics to be
439       output to stderr and correspond to -v for BUG, -vv for  ERR,  -vvv  for
440       WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
441
442       A given verbose level is useful for providing needed debugging informa‐
443       tion to the email address below.  For example, TRACE output  shows  all
444       of  the values sent to and received from the radio which is very useful
445       for radio backend library development and may be requested by  the  de‐
446       velopers.
447

EXIT STATUS

449       rotctl exits with:
450
451       0      if all operations completed normally;
452
453       1      if there was an invalid command line option or argument;
454
455       2      if an error was returned by Hamlib.
456

EXAMPLES

458       Start rotctl for RotorEZ using the first serial port on Linux:
459
460           $ rotctl -m 401 -r /dev/ttyS0
461
462       Start rotctl for RotorEZ using COM2 on MS Windows:
463
464           > rotctl -m 401 -r COM2
465
466       Connect to a running rotctld with rotator model 2 (“NET rotctl”) on the
467       local host and specifying the TCP port, and querying the position:
468
469           $ rotctl -m 2 -r localhost:4533 t_pos
470

BUGS

472       Report bugs to:
473
474              Hamlib Developer mailing list
475              ⟨hamlib-developer@lists.sourceforge.net⟩
476

COPYING

478       This file is part of Hamlib, a project to develop a library  that  sim‐
479       plifies  radio, rotator, and amplifier control functions for developers
480       of software primarily of interest to radio amateurs  and  those  inter‐
481       ested in radio communications.
482
483       Copyright © 2001-2011 Stephane Fillod
484       Copyright © 2002-2017 the Hamlib Group (various contributors)
485       Copyright © 2003-2020 Nate Bargmann
486
487       This  is  free  software;  see the file COPYING for copying conditions.
488       There is NO warranty; not even for MERCHANTABILITY  or  FITNESS  FOR  A
489       PARTICULAR PURPOSE.
490

SEE ALSO

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

COLOPHON

495       Links  to  the Hamlib Wiki, Git repository, release archives, and daily
496       snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
497
498
499
500Hamlib                            2020-09-09                         ROTCTL(1)
Impressum