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

NAME

6       rotctl - control antenna rotators
7

SYNOPSIS

9       rotctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
10              [-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       -s, --serial-speed=baud
52              Set serial speed to baud rate.
53
54              Uses  maximum  serial speed from rotator backend capabilities as
55              the default.
56
57       -t, --send-cmd-term=char
58              Change the termination char for text  protocol  when  using  the
59              send_cmd command.
60
61              The  default  value  is  ASCII  CR (‘0x0D’).  ASCII non-printing
62              characters can be given as the ASCII number in hexadecimal  for‐
63              mat  prepended  with  “0x”.  You may pass an empty string for no
64              termination char.  The string “-1” tells  rotctl  to  switch  to
65              binary  protocol.  See the send_cmd command for further explana‐
66              tion.
67
68              Note: The semicolon (‘;’) is a common  terminator  for  rotators
69              that accept ASCII character strings.
70
71       -L, --show-conf
72              List  all  configuration parameters for the rotator defined with
73              -m above.
74
75       -C, --set-conf=parm=val[,parm=val]
76              Set rotator configuration parameter(s),  e.g.  stop_bits=2.
77
78              Use the -L option above for a list of  configuration  parameters
79              for a given model number.
80
81       -u, --dump-caps
82              Dump  capabilities  for  the  rotator  defined with -m above and
83              exit.
84
85       -l, --list
86              List all rotator model numbers defined in Hamlib and exit.
87
88              The list is sorted by model number.
89
90              Note: In Linux the  list  can  be  scrolled  back  using  Shift-
91              PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
92              minal in X or the cmd window in  Windows.   The  output  can  be
93              piped to more(1) or less(1), e.g. “rotctl -l | more”.
94
95       -i, --read-history
96              Read  previously  saved command and argument history from a file
97              (default $HOME/.rotctl_history) for the current session.
98
99              Available when rotctl is built with Readline support (see  READ‐
100              LINE below).
101
102              Note:  To  read  a history file stored in another directory, set
103              the     ROTCTL_HIST_DIR     environment      variable,      e.g.
104              “ROTCTL_HIST_DIR=$HOME/tmp  rotctl -i”.  When ROTCTL_HIST_DIR is
105              not set, the value of HOME is used.
106
107       -I, --save-history
108              Write current session (and any previous session(s), if -i option
109              is  also  given) command and argument history to a file (default
110              $HOME/.rotctl_history) at the end of the current session.
111
112              Complete commands with arguments are saved as a single  line  to
113              be  recalled and used or edited.  Available when rotctl is built
114              with Readline support (see READLINE below).
115
116              Note: To write a history file  in  another  directory,  set  the
117              ROTCTL_HIST_DIR         environment        variable,        e.g.
118              “ROTCTL_HIST_DIR=$HOME/tmp rotctl -I”.  When ROTCTL_HIST_DIR  is
119              not set, the value of HOME is used.
120
121       -v, --verbose
122              Set verbose mode, cumulative (see DIAGNOSTICS below).
123
124       -Z, --debug-time-stamps
125              Enable time stamps for the debug messages.
126
127              Use  only  in  combination with the -v option as it generates no
128              output on its own.
129
130       -h, --help
131              Show a summary of these options and exit.
132
133       -V, --version
134              Show version of rotctl and exit.
135
136       -      Stop option processing and read commands from standard input.
137
138              See Standard Input below.
139
140       Note: Some options may not be implemented by a given backend  and  will
141       return  an error.  This is most likely to occur with the --set-conf and
142       --show-conf options.
143
144       Be aware that the backend for the rotator  to  be  controlled,  or  the
145       rotator itself may not support some commands.  In that case, the opera‐
146       tion will fail with a Hamlib error code.
147

COMMANDS

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

READLINE

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

DIAGNOSTICS

416       The -v, --verbose option allows different levels of diagnostics  to  be
417       output  to  stderr  and correspond to -v for BUG, -vv for ERR, -vvv for
418       WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
419
420       A given verbose level is useful for providing needed debugging informa‐
421       tion  to  the email address below.  For example, TRACE output shows all
422       of the values sent to and received from the radio which is very  useful
423       for  radio  backend  library  development  and  may be requested by the
424       developers.
425

EXIT STATUS

427       rotctl exits with:
428
429       0      if all operations completed normally;
430
431       1      if there was an invalid command line option or argument;
432
433       2      if an error was returned by Hamlib.
434

EXAMPLE

436       Start rotctl for RotorEZ using the first serial port on Linux:
437
438            $ rotctl -m 401 -r /dev/ttyS0
439
440       Start rotctl for RotorEZ using COM2 on MS Windows:
441
442            $ rotctl -m 401 -r COM2
443
444       Connect to a running rotctld with rotator model 2 (“NET rotctl”) on the
445       local host and specifying the TCP port, and querying the position:
446
447            $ rotctl -m 2 -r localhost:4533 \get_pos
448

BUGS

450       Report bugs to:
451
452              Hamlib Developer mailing list
453              ⟨hamlib-developer@lists.sourceforge.net⟩
454

COPYING

456       This  file  is part of Hamlib, a project to develop a library that sim‐
457       plifies radio and rotator control functions for developers of  software
458       primarily  of  interest to radio amateurs and those interested in radio
459       communications.
460
461       Copyright © 2001-2011 Stephane Fillod
462       Copyright © 2002-2017 the Hamlib Group (various contributors)
463       Copyright © 2003-2018 Nate Bargmann
464
465       This is free software; see the file  COPYING  for  copying  conditions.
466       There  is  NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A
467       PARTICULAR PURPOSE.
468

SEE ALSO

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

COLOPHON

473       Links to the Hamlib Wiki, Git repository, release archives,  and  daily
474       snapshot archives:
475
476              hamlib.org ⟨http://www.hamlib.org⟩.
477
478
479
480Hamlib                            2018-04-29                         ROTCTL(1)
Impressum