1ROTCTL(1) Hamlib Utilities ROTCTL(1)
2
6 rotctl - control antenna rotators
7
9 rotctl [-hiIlLuV] [-m id] [-r device] [-R device2] [-s baud] [-t char]
10 [-C parm=val] [-o azoffset] [-O eloffset] [-v[-Z]] [command|-]
11
13 Control antenna rotators.
14 rotctl accepts commands from the command line as well as in interactive
16 mode if none are provided on the command line.
17 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 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
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 Here is a summary of the supported options:
33 -m, --model=id
35 Select rotator model number.
36 See model list (use “rotctl -l”).
38 Note: rotctl (or third party software using the C API) will use
40 rotator model 2 for NET rotctl (communicating with rotctld).
41 -r, --rot-file=device
43 Use device as the file name of the port connected to the rota‐
44 tor.
45 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 -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 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 -s, --serial-speed=baud
61 Set serial speed to baud rate.
62 Uses maximum serial speed from rotator backend capabilities as
64 the default.
65 -t, --send-cmd-term=char
67 Change the termination char for text protocol when using the
68 send_cmd command.
69 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 Note: The semicolon (‘;’) is a common terminator for rotators
78 that accept ASCII character strings.
79 -o, --set-azoffset
81 Azimuth correction floating point -- during set value is added,
82 during get value is subtracted.
83 -O, --set-eloffset
85 Elevation correction floating point -- during set value is
86 added, during get value is subtracted.
87 -L, --show-conf
89 List all configuration parameters for the rotator defined with
90 -m above.
91 -C, --set-conf=parm=val[,parm=val]
93 Set rotator configuration parameter(s), e.g. stop_bits=2.
94 Use the -L option above for a list of configuration parameters
96 for a given model number.
97 -u, --dump-caps
99 Dump capabilities for the rotator defined with -m above and
100 exit.
101 -l, --list
103 List all rotator model numbers defined in Hamlib and exit.
104 The list is sorted by model number.
106 Note: In Linux the list can be scrolled back using Shift-
108 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
109 minal in X or the cmd window in Windows. The output can be
110 piped to more(1) or less(1), e.g. “rotctl -l | more”.
111 -i, --read-history
113 Read previously saved command and argument history from a file
114 (default $HOME/.rotctl_history) for the current session.
115 Available when rotctl is built with Readline support (see READ‐
117 LINE below).
118 Note: To read a history file stored in another directory, set
120 the ROTCTL_HIST_DIR environment variable, e.g.
121 “ROTCTL_HIST_DIR=$HOME/tmp rotctl -i”. When ROTCTL_HIST_DIR is
122 not set, the value of HOME is used.
123 -I, --save-history
125 Write current session (and any previous session(s), if -i option
126 is also given) command and argument history to a file (default
127 $HOME/.rotctl_history) at the end of the current session.
128 Complete commands with arguments are saved as a single line to
130 be recalled and used or edited. Available when rotctl is built
131 with Readline support (see READLINE below).
132 Note: To write a history file in another directory, set the
134 ROTCTL_HIST_DIR environment variable, e.g.
135 “ROTCTL_HIST_DIR=$HOME/tmp rotctl -I”. When ROTCTL_HIST_DIR is
136 not set, the value of HOME is used.
137 -v, --verbose
139 Set verbose mode, cumulative (see DIAGNOSTICS below).
140 -Z, --debug-time-stamps
142 Enable time stamps for the debug messages.
143 Use only in combination with the -v option as it generates no
145 output on its own.
146 -h, --help
148 Show a summary of these options and exit.
149 -V, --version
151 Show version of rotctl and exit.
152 - Stop option processing and read commands from standard input.
154 See Standard Input below.
156 Note: Some options may not be implemented by a given backend and will
158 return an error. This is most likely to occur with the --set-conf and
159 --show-conf options.
160 Be aware that the backend for the rotator to be controlled, or the ro‐
162 tator itself may not support some commands. In that case, the opera‐
163 tion will fail with a Hamlib error code.
164
166 Commands can be entered either as a single char, or as a long command
167 name. The commands are not prefixed with a dash as the options are.
168 They may be typed in when in interactive mode or provided as argu‐
169 ment(s) in command line interface mode. In interactive mode commands
170 and their arguments may be entered on a single line (typed text shown
171 in bold):
172 P 123 45
174 Since most of the Hamlib operations have a set and a get method, an up‐
176 per case letter will often be used for a set method whereas the corre‐
177 sponding lower case letter refers to the get method. Each operation
178 also has a long name; in interactive mode, prepend a backslash, ‘\’, to
179 enter a long command name.
180 Example: Use “\get_info” in interactive mode to see the rotator's in‐
182 formation.
183 Note: The backend for the rotator to be controlled, or the rota‐
185 tor itself may not support some commands. In that case, the op‐
186 eration will fail with a Hamlib error message.
187 Standard Input
189 As an alternative to the READLINE interactive command entry or a single
190 command for each run, rotctl features a special option where a single
191 dash (‘-’) may be used to read commands from standard input (stdin).
192 Commands must be separated by whitespace similar to the commands given
193 on the command line. Comments may be added using the ‘#’ character,
194 all text up until the end of the current line including the ‘#’ charac‐
195 ter is ignored.
196 A simple example:
198 $ cat <<.EOF. >cmds.txt
200 > # File of commands
201 > set_pos 180.0 10.0 # rotate
202 > pause 30 # wait for action to complete
203 > get_pos # query rotator
204 >.EOF.
205 $ rotctl -m 1 - <cmds.txt
207 set_pos 180.0 10.0
209 pause 30
210 get_pos 180.000000
211 10.000000
212 $
214 Rotator Commands
216 A summary of commands is included below (In the case of set commands
217 the quoted italicized string is replaced by the value in the descrip‐
218 tion. In the case of get commands the quoted italicized string is the
219 key name of the value returned.):
220 Q|q, exit rotctl
222 Exit rotctl in interactive mode.
223 When rotctl is controlling the rotator directly, will close the
225 rotator backend and port. When rotctl is connected to rotctld
226 (rotator model 2), the TCP/IP connection to rotctld is closed
227 and rotctld remains running, available for another TCP/IP net‐
228 work connection.
229 P, set_pos 'Azimuth' 'Elevation'
231 Set position.
232 'Azimuth' and 'Elevation' are floating point values.
234 Azimuth can be -180 to 540 depending on the rotator to allow for
236 rotators facing south and the capabilities of the rotator.
237 Elevation can be -20 to 210 depending on the rotator.
239 For example:
241 P 163.0 41.0
243 Note: If the rotator does not support setting elevation (most do
245 not) supply “0.0” for 'Elevation'.
246 p, get_pos
248 Get position.
249 'Azimuth' and 'Elevation' are returned as double precision
251 floating point values.
252 M, move 'Direction' 'Speed'
254 Move the rotator in a specific direction at the given rate.
255 'Direction' is an integer or keyword defined as ‘2’ = UP, ‘4’ =
257 DOWN, ‘8’ = LEFT or CCW and ‘16’ = RIGHT or CW
258 'Speed' is an integer between 1 and 100. Use -1 for no change to
260 current speed.
261 Note: Not all backends that implement the move command use the
263 Speed value.
264 S, stop
266 Stop the rotator.
267 K, park
269 Park the rotator.
270 C, set_conf 'Token' 'Value'
272 Set a configuration parameter.
273 'Token' is a string; see the -C option and the -L output.
275 'Value' is a string of up to 20 characters.
277 R, reset 'Reset'
279 Reset the rotator.
280 'Reset' accepts an integer value of ‘1’ for “Reset All”.
282 _, get_info
284 Get miscellaneous information about the rotator.
285 Returns 'Info' “Model Name” at present.
287 dump_state
289 Return certain state information about the rotator backend.
290 1, dump_caps
292 Not a real rot remote command, it just dumps capabilities, i.e.
293 what the backend knows about this model, and what it can do.
294 w, send_cmd 'Cmd'
296 Send a raw command string to the rotator.
297 ASCII CR (or --send-cmd-term value, see -t option) is appended
299 automatically at the end of the command for text protocols. For
300 binary protocols, enter hexadecimal values as “\0xAA\0xBB”.
301 Locator Commands
303 These commands offer conversions of Degrees Minutes Seconds to other
304 formats, Maidenhead square locator conversions and distance and azimuth
305 conversions.
306 L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
308 Returns the Maidenhead 'Locator' for the given 'Longitude' and
309 'Latitude'.
310 Floating point values are supplied. The precision of the re‐
312 turned square is controlled by 'Loc Len' which should be an even
313 numbered integer value between 2 and 12.
314 For example:
316 L -170.0 -85.0 12
318 returns:
320 Locator: AA55AA00AA00
322 l, loc2lonlat 'Locator'
324 Returns 'Longitude' and 'Latitude' in decimal degrees at the ap‐
325 proximate center of the requested Maidenhead grid square.
326 'Locator' can be from 2 to 12 characters in length.
328 West longitude is expressed as a negative value.
330 South latitude is expressed as a negative value.
332 For example:
334 l AA55AA00AA00
336 returns:
338 Longitude: -169.999983 Latitude: -84.999991
340 Note: Despite the use of double precision variables internally,
342 some rounding error occurs.
343 D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
345 Returns 'Dec Degrees', a signed floating point value.
346 'Degrees' and 'Minutes' are integer values.
348 'Seconds' is a floating point value.
350 'S/W' is a flag with ‘1’ indicating South latitude or West lon‐
352 gitude and ‘0’ North or East (the flag is needed as computers
353 don't recognize a signed zero even though only the 'Degrees'
354 value is typically signed in DMS notation).
355 d, dec2dms 'Dec Degrees'
357 Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
358 Values are as in dms2dec above.
360 E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
362 Returns 'Dec Degrees', a signed floating point value.
363 'Degrees' is an integer value.
365 'Dec Minutes' is a floating point value.
367 'S/W' is a flag as in dms2dec above.
369 e, dec2dmmm 'Dec Deg'
371 Returns 'Degrees' 'Minutes' 'S/W'.
372 Values are as in dmmm2dec above.
374 B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
376 Returns 'Distance' and 'Azimuth'.
377 'Distance' is in km.
379 'Azimuth' is in degrees.
381 Supplied Lon/Lat values are signed floating point numbers.
383 A, a_sp2a_lp 'Short Path Deg'
385 Returns 'Long Path Deg'.
386 Both the supplied argument and returned value are floating point
388 values within the range of 0.00 to 360.00.
389 Note: Supplying a negative value will return an error message.
391 a, d_sp2d_lp 'Short Path km'
393 Returns 'Long Path km'.
394 Both the supplied argument and returned value are floating point
396 values.
397 pause 'Seconds'
399 Pause for the given whole (integer) number of 'Seconds' before
400 sending the next command to the rotator.
401
403 If Readline library development files are found at configure time,
404 rotctl will be conditonally built with Readline support for command and
405 argument entry. Readline command key bindings are at their defaults as
406 described in the Readline manual
407 ⟨https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩. rotctl
408 sets the name “rotctl” which can be used in Conditional Init Constructs
409 in the Readline Init File ($HOME/.inputrc by default) for custom key‐
410 bindings unique to rotctl.
411 Command history is available with Readline support as described in the
413 Readline History manual
414 ⟨https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩. Command
415 and argument strings are stored as single lines even when arguments are
416 prompted for input individually. Commands and arguments are not vali‐
417 dated and are stored as typed with values separated by a single space.
418 Normally session history is not saved, however, use of either of the
420 -i/--read-history or -I/--save-history options when starting rotctl
421 will cause any previously saved history to be read in and/or the cur‐
422 rent and any previous session history (assuming the -i and -I options
423 are given together) will be written out when rotctl is closed. Each
424 option is mutually exclusive, i.e. either may be given separately or in
425 combination. This is useful to save a set of commands and then read
426 them later but not write the modified history for a consistent set of
427 test commands in interactive mode, for example.
428 History is stored in $HOME/.rotctl_history by default although the des‐
430 tination directory may be changed by setting the ROTCTL_HIST_DIR envi‐
431 ronment variable. When ROTCTL_HIST_DIR is unset, the value of the HOME
432 environment variable is used instead. Only the destination directory
433 may be changed at this time.
434 If Readline support is not found at configure time the original inter‐
436 nal command handler is used. Readline is not used for rotctl commands
437 entered on the command line regardless if Readline support is built in
438 or not.
439 Note: Readline support is not included in the MS Windows 32 or 64 bit
441 binary builds supplied by the Hamlib Project. Running rotctl on the MS
442 Windows platform in the ‘cmd’ shell does give session command line his‐
443 tory, however, it is not saved to disk between sessions.
444
446 The -v, --verbose option allows different levels of diagnostics to be
447 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
448 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
449 A given verbose level is useful for providing needed debugging informa‐
451 tion to the email address below. For example, TRACE output shows all
452 of the values sent to and received from the radio which is very useful
453 for radio backend library development and may be requested by the de‐
454 velopers.
455
457 rotctl exits with:
458 0 if all operations completed normally;
460 1 if there was an invalid command line option or argument;
462 2 if an error was returned by Hamlib.
464
466 Start rotctl for RotorEZ using the first serial port on Linux:
467 $ rotctl -m 401 -r /dev/ttyS0
469 Start rotctl for RotorEZ using COM2 on MS Windows:
471 > rotctl -m 401 -r COM2
473 Connect to a running rotctld with rotator model 2 (“NET rotctl”) on the
475 local host and specifying the TCP port, and querying the position:
476 $ rotctl -m 2 -r localhost:4533 t_pos
478
480 Report bugs to:
481 Hamlib Developer mailing list
483 ⟨hamlib-developer@lists.sourceforge.net⟩
484
486 This file is part of Hamlib, a project to develop a library that sim‐
487 plifies radio, rotator, and amplifier control functions for developers
488 of software primarily of interest to radio amateurs and those inter‐
489 ested in radio communications.
490 Copyright © 2001-2011 Stephane Fillod
492 Copyright © 2002-2017 the Hamlib Group (various contributors)
493 Copyright © 2003-2020 Nate Bargmann
494 This is free software; see the file COPYING for copying conditions.
496 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
497 PARTICULAR PURPOSE.
498
500 less(1), more(1), rotctld(1), hamlib(7)
501
503 Links to the Hamlib Wiki, Git repository, release archives, and daily
504 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
505Hamlib 2020-09-09 ROTCTL(1)