1ROTCTL(1) Hamlib Utilities ROTCTL(1)
2
3
4
6 rotctl - control antenna rotators
7
9 rotctl [-hiIlLuV] [-m id] [-r device] [-R device2] [-s baud] [-t char]
10 [-C parm=val] [-v[-Z]] [command|-]
11
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
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
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
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
399 ⟨https://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
406 ⟨https://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
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
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
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
472 Report bugs to:
473
474 Hamlib Developer mailing list
475 ⟨hamlib-developer@lists.sourceforge.net⟩
476
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
492 less(1), more(1), rotctld(1), hamlib(7)
493
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)