1ROTCTL(1) Hamlib Utilities ROTCTL(1)
2
6 rotctl - control antenna rotators
7
9 rotctl [-hiIlLuV] [-m id] [-r device] [-s baud] [-t char] [-C parm=val]
10 [-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 -s, --serial-speed=baud
52 Set serial speed to baud rate.
53 Uses maximum serial speed from rotator backend capabilities as
55 the default.
56 -t, --send-cmd-term=char
58 Change the termination char for text protocol when using the
59 send_cmd command.
60 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 Note: The semicolon (‘;’) is a common terminator for rotators
69 that accept ASCII character strings.
70 -L, --show-conf
72 List all configuration parameters for the rotator defined with
73 -m above.
74 -C, --set-conf=parm=val[,parm=val]
76 Set rotator configuration parameter(s), e.g. stop_bits=2.
77 Use the -L option above for a list of configuration parameters
79 for a given model number.
80 -u, --dump-caps
82 Dump capabilities for the rotator defined with -m above and
83 exit.
84 -l, --list
86 List all rotator model numbers defined in Hamlib and exit.
87 The list is sorted by model number.
89 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 -i, --read-history
96 Read previously saved command and argument history from a file
97 (default $HOME/.rotctl_history) for the current session.
98 Available when rotctl is built with Readline support (see READ‐
100 LINE below).
101 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 -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 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 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 -v, --verbose
122 Set verbose mode, cumulative (see DIAGNOSTICS below).
123 -Z, --debug-time-stamps
125 Enable time stamps for the debug messages.
126 Use only in combination with the -v option as it generates no
128 output on its own.
129 -h, --help
131 Show a summary of these options and exit.
132 -V, --version
134 Show version of rotctl and exit.
135 - Stop option processing and read commands from standard input.
137 See Standard Input below.
139 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 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
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 P 123 45
156 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 Example: Use “\get_info” in interactive mode to see the rotator's
164 information.
165 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 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 A simple example:
180 $ 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 $ rotctl -m 1 - <cmds.txt
189 set_pos 180.0 10.0
191 pause 30
192 get_pos 180.000000
193 10.000000
194 $
196 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 Q|q, exit rotctl
204 Exit rotctl in interactive mode.
205 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 P, set_pos 'Azimuth' 'Elevation'
213 Set position.
214 'Azimuth' and 'Elevation' are floating point values.
216 For example:
218 P 163.0 41.0
220 Note: If the rotator does not support setting elevation (most do
222 not) supply “0.0” for 'Elevation'.
223 p, get_pos
225 Get position.
226 'Azimuth' and 'Elevation' are returned as double precision
228 floating point values.
229 M, move 'Direction' 'Speed'
231 Move the rotator in a specific direction at the given rate.
232 'Direction' is an integer defined as ‘2’ = Up, ‘4’ = Down, ‘8’ =
234 Left, and ‘16’ = Right.
235 'Speed' is an integer between 1 and 100.
237 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 S, stop
243 Stop the rotator.
244 K, park
246 Park the rotator.
247 C, set_conf 'Token' 'Value'
249 Set a configuration parameter.
250 'Token' is a string; see the -C option and the -L output.
252 'Value' is a string of up to 20 characters.
254 R, reset 'Reset'
256 Reset the rotator.
257 'Reset' accepts an integer value of ‘1’ for “Reset All”.
259 _, get_info
261 Get miscellaneous information about the rotator.
262 Returns 'Info' “Model Name” at present.
264 dump_state
266 Return certain state information about the rotator backend.
267 1, dump_caps
269 Not a real rot remote command, it just dumps capabilities, i.e.
270 what the backend knows about this model, and what it can do.
271 w, send_cmd 'Cmd'
273 Send a raw command string to the rotator.
274 ASCII CR (or --send-cmd-term value, see -t option) is appended
276 automatically at the end of the command for text protocols. For
277 binary protocols, enter hexadecimal values as “\0xAA\0xBB”.
278 Locator Commands
280 These commands offer conversions of Degrees Minutes Seconds to other
281 formats, Maidenhead square locator conversions and distance and azimuth
282 conversions.
283 L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
285 Returns the Maidenhead 'Locator' for the given 'Longitude' and
286 'Latitude'.
287 Floating point values are supplied. The precision of the
289 returned square is controlled by 'Loc Len' which should be an
290 even numbered integer value between 2 and 12.
291 For example:
293 L -170.0 -85.0 12
295 returns:
297 Locator: AA55AA00AA00
299 l, loc2lonlat 'Locator'
301 Returns 'Longitude' and 'Latitude' in decimal degrees at the
302 approximate center of the requested Maidenhead grid square.
303 'Locator' can be from 2 to 12 characters in length.
305 West longitude is expressed as a negative value.
307 South latitude is expressed as a negative value.
309 For example:
311 l AA55AA00AA00
313 returns:
315 Longitude: -169.999983 Latitude: -84.999991
317 Note: Despite the use of double precision variables internally,
319 some rounding error occurs.
320 D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
322 Returns 'Dec Degrees', a signed floating point value.
323 'Degrees' and 'Minutes' are integer values.
325 'Seconds' is a floating point value.
327 'S/W' is a flag with ‘1’ indicating South latitude or West lon‐
329 gitude and ‘0’ North or East (the flag is needed as computers
330 don't recognize a signed zero even though only the 'Degrees'
331 value is typically signed in DMS notation).
332 d, dec2dms 'Dec Degrees'
334 Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
335 Values are as in dms2dec above.
337 E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
339 Returns 'Dec Degrees', a signed floating point value.
340 'Degrees' is an integer value.
342 'Dec Minutes' is a floating point value.
344 'S/W' is a flag as in dms2dec above.
346 e, dec2dmmm 'Dec Deg'
348 Returns 'Degrees' 'Minutes' 'S/W'.
349 Values are as in dmmm2dec above.
351 B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
353 Returns 'Distance' and 'Azimuth'.
354 'Distance' is in km.
356 'Azimuth' is in degrees.
358 Supplied Lon/Lat values are signed floating point numbers.
360 A, a_sp2a_lp 'Short Path Deg'
362 Returns 'Long Path Deg'.
363 Both the supplied argument and returned value are floating point
365 values within the range of 0.00 to 360.00.
366 Note: Supplying a negative value will return an error message.
368 a, d_sp2d_lp 'Short Path km'
370 Returns 'Long Path km'.
371 Both the supplied argument and returned value are floating point
373 values.
374 pause 'Seconds'
376 Pause for the given whole (integer) number of 'Seconds' before
377 sending the next command to the rotator.
378
380 If Readline library development files are found at configure time,
381 rotctl will be conditonally built with Readline support for command and
382 argument entry. Readline command key bindings are at their defaults as
383 described in the Readline manual
384 ⟨https://tiswww.cwru.edu/php/chet/readline/rluserman.html⟩. rotctl
385 sets the name “rotctl” which can be used in Conditional Init Constructs
386 in the Readline Init File ($HOME/.inputrc by default) for custom key‐
387 bindings unique to rotctl.
388 Command history is available with Readline support as described in the
390 Readline History manual
391 ⟨https://tiswww.case.edu/php/chet/readline/history.html#SEC1⟩. Command
392 and argument strings are stored as single lines even when arguments are
393 prompted for input individually. Commands and arguments are not vali‐
394 dated and are stored as typed with values separated by a single space.
395 Normally session history is not saved, however, use of either of the
397 -i/--read-history or -I/--save-history options when starting rotctl
398 will cause any previously saved history to be read in and/or the cur‐
399 rent and any previous session history (assuming the -i and -I options
400 are given together) will be written out when rotctl is closed. Each
401 option is mutually exclusive, i.e. either may be given separately or in
402 combination. This is useful to save a set of commands and then read
403 them later but not write the modified history for a consistent set of
404 test commands in interactive mode, for example.
405 History is stored in $HOME/.rotctl_history by default although the des‐
407 tination directory may be changed by setting the ROTCTL_HIST_DIR envi‐
408 ronment variable. When ROTCTL_HIST_DIR is unset, the value of the HOME
409 environment variable is used instead. Only the destination directory
410 may be changed at this time.
411 If Readline support is not found at configure time the original inter‐
413 nal command handler is used. Readline is not used for rotctl commands
414 entered on the command line regardless if Readline support is built in
415 or not.
416 Note: Readline support is not included in the MS Windows 32 or 64 bit
418 binary builds supplied by the Hamlib Project. Running rotctl on the MS
419 Windows platform in the ‘cmd’ shell does give session command line his‐
420 tory, however, it is not saved to disk between sessions.
421
423 The -v, --verbose option allows different levels of diagnostics to be
424 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
425 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
426 A given verbose level is useful for providing needed debugging informa‐
428 tion to the email address below. For example, TRACE output shows all
429 of the values sent to and received from the radio which is very useful
430 for radio backend library development and may be requested by the
431 developers.
432
434 rotctl exits with:
435 0 if all operations completed normally;
437 1 if there was an invalid command line option or argument;
439 2 if an error was returned by Hamlib.
441
443 Start rotctl for RotorEZ using the first serial port on Linux:
444 $ rotctl -m 401 -r /dev/ttyS0
446 Start rotctl for RotorEZ using COM2 on MS Windows:
448 $ rotctl -m 401 -r COM2
450 Connect to a running rotctld with rotator model 2 (“NET rotctl”) on the
452 local host and specifying the TCP port, and querying the position:
453 $ rotctl -m 2 -r localhost:4533 \get_pos
455
457 Report bugs to:
458 Hamlib Developer mailing list
460 ⟨hamlib-developer@lists.sourceforge.net⟩
461
463 This file is part of Hamlib, a project to develop a library that sim‐
464 plifies radio, rotator, and amplifier control functions for developers
465 of software primarily of interest to radio amateurs and those inter‐
466 ested in radio communications.
467 Copyright © 2001-2011 Stephane Fillod
469 Copyright © 2002-2017 the Hamlib Group (various contributors)
470 Copyright © 2003-2019 Nate Bargmann
471 This is free software; see the file COPYING for copying conditions.
473 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
474 PARTICULAR PURPOSE.
475
477 less(1), more(1), rotctld(1), hamlib(7)
478
480 Links to the Hamlib Wiki, Git repository, release archives, and daily
481 snapshot archives:
482 hamlib.org ⟨http://www.hamlib.org⟩.
484Hamlib 2019-12-10 ROTCTL(1)