1ROTCTLD(1) Hamlib Utilities ROTCTLD(1)
2
6 rotctld - TCP rotator control daemon
7
9 rotctld [-hlLuV] [-m id] [-r device] [-s baud] [-T IPADDR] [-t number]
10 [-C parm=val] [-v[-Z]]
11
13 The rotctld program is a rotator control daemon that handles client
14 requests via TCP sockets. This allows multiple user programs to share
15 one rotator (this needs more development). Multiple rotators can be
16 controlled on different TCP ports by use of multiple rotctld processes.
17 The syntax of the commands are the same as rotctl(1). It is hoped that
18 rotctld will be especially useful for client authors using languages
19 such as Perl, Python, PHP, and others.
20 rotctld communicates to a client through a TCP socket using text com‐
22 mands shared with rotctl. The protocol is simple, commands are sent to
23 rotctld on one line and rotctld responds to “get” commands with the
24 requested values, one per line, when successful, otherwise, it responds
25 with one line “RPRT x”, where ‘x’ is a negative number indicating the
26 error code. Commands that do not return values respond with the line
27 “RPRT x”, where ‘x’ is ‘0’ when successful, otherwise is a regative
28 number indicating the error code. Each line is terminated with a new‐
29 line ‘\n’ character. This protocol is primarily for use by the NET
30 rotctl (rotator model 2) backend.
31 A separate Extended Response Protocol extends the above behavior by
33 echoing the received command string as a header, any returned values as
34 a key: value pair, and the “RPRT x” string as the end of response
35 marker which includes the Hamlib success or failure value. See the
36 PROTOCOL section for details. Consider using this protocol for clients
37 that will interact with rotctld directly through a TCP socket.
38 Keep in mind that Hamlib is BETA level software. While a lot of back‐
40 end libraries lack complete rotator support, the basic functions are
41 usually well supported.
42 Please report bugs and provide feedback at the e-mail address given in
44 the BUGS section below. Patches and code enhancements sent to the same
45 address are welcome.
46
48 This program follows the usual GNU command line syntax. Short options
49 that take an argument may have the value follow immediately or be sepa‐
50 rated by a space. Long options starting with two dashes (‘-’) require
51 an ‘=’ between the option and any argument.
52 Here is a summary of the supported options:
54 -m, --model=id
56 Select rotator model number.
57 See model list (use “rotctld -l”).
59 Note: rotctl (or third party software using the C API) will use
61 rotator model 2 for NET rotctl (this model number is not used
62 for rotctld even though it shows in the model list).
63 -r, --rot-file=device
65 Use device as the file name of the port connected to the rota‐
66 tor.
67 Often a serial port, but could be a USB to serial adapter. Typ‐
69 ically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux,
70 COM1, COM2, etc. on MS Windows. The BSD flavors and Mac OS/X
71 have their own designations. See your system's documentation.
72 -s, --serial-speed=baud
74 Set serial speed to baud rate.
75 Uses maximum serial speed from rotator backend capabilities as
77 the default.
78 -T, --listen-addr=IPADDR
80 Use IPADDR as the listening IP address.
81 The default is ANY.
83 -t, --port=number
85 Use number as the TCP listening port.
86 The default is 4533.
88 Note: As rigctld's default port is 4532, it is advisable to use
90 odd numbered ports for rotctld, e.g. 4533, 4535, 4537, etc.
91 -L, --show-conf
93 List all configuration parameters for the rotator defined with
94 -m above.
95 -C, --set-conf=parm=val[,parm=val]
97 Set rotator configuration parameter(s), e.g. stop_bits=2.
98 Use the -L option above for a list of configuration parameters
100 for a given model number.
101 -u, --dump-caps
103 Dump capabilities for the rotator defined with -m above and
104 exit.
105 -l, --list
107 List all rotator model numbers defined in Hamlib and exit.
108 The list is sorted by model number.
110 Note: In Linux the list can be scrolled back using Shift-
112 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
113 minal in X or the cmd window in Windows. The output can be
114 piped to more(1) or less(1), e.g. “rotctl -l | more”.
115 -v, --verbose
117 Set verbose mode, cumulative (see DIAGNOSTICS below).
118 -Z, --debug-time-stamps
120 Enable time stamps for the debug messages.
121 Use only in combination with the -v option as it generates no
123 output on its own.
124 -h, --help
126 Show a summary of these options and exit.
127 -V, --version
129 Show version of rotctld and exit.
130 Note: Some options may not be implemented by a given backend and will
132 return an error. This is most likely to occur with the --set-conf and
133 --show-conf options.
134 Be aware that the backend for the rotator to be controlled, or the
136 rotator itself may not support some commands. In that case, the opera‐
137 tion will fail with a Hamlib error code.
138
140 Commands can be sent over the TCP socket either as a single char, or as
141 a long command name plus the value(s) space separated on one ‘\n’ ter‐
142 minated line. See PROTOCOL.
143 Since most of the Hamlib operations have a set and a get method, an
145 upper case letter will be used for set methods whereas the correspond‐
146 ing lower case letter refers to the get method. Each operation also
147 has a long name; prepend a backslash, ‘\’, to send a long command name.
148 Example (Perl): “print $socket "\\dump_caps\n";” to see what the rota‐
150 tor's backend can do (Note: In Perl and many other languages a ‘\’ will
151 need to be escaped with a preceding ‘\’ so that even though two back‐
152 slash characters appear in the code, only one will be passed to
153 rotctld. This is a possible bug, beware!).
154 Note: The backend for the rotator to be controlled, or the rotator
156 itself may not support some commands. In that case, the operation will
157 fail with a Hamlib error message.
158 Here is a summary of the supported commands (In the case of set com‐
160 mands the quoted italicized string is replaced by the value in the
161 description. In the case of get commands the quoted italicized string
162 is the key name of the value returned.):
163 P, set_pos 'Azimuth' 'Elevation'
165 Set position.
166 'Azimuth' and 'Elevation' are floating point values.
168 For example:
170 P 163.0 41.0
172 Note: If the rotator does not support setting elevation (most do
174 not) supply “0.0” for 'Elevation'.
175 p, get_pos
177 Get position.
178 'Azimuth' and 'Elevation' are returned as double precision
180 floating point values.
181 M, move 'Direction' 'Speed'
183 Move the rotator in a specific direction at the given rate.
184 'Direction' is an integer defined as ‘2’ = Up, ‘4’ = Down, ‘8’ =
186 Left, and ‘16’ = Right.
187 'Speed' is an integer between 1 and 100.
189 Note: Not all backends that implement the move command use the
191 Speed value. At this time only the gs232a utilizes the Speed
192 parameter.
193 S, stop
195 Stop the rotator.
196 K, park
198 Park the rotator.
199 C, set_conf 'Token' 'Value'
201 Set a configuration parameter.
202 'Token' is a string; see the -C option and the -L output.
204 'Value' is a string of up to 20 characters.
206 R, reset 'Reset'
208 Reset the rotator.
209 'Reset' accepts an integer value of ‘1’ for “Reset All”.
211 _, get_info
213 Get misc information about the rotator.
214 Returns 'Info' “Model Name”.
216 w, send_cmd 'Cmd'
218 Send a raw command string to the rotator.
219 ASCII CR is appended automatically at the end of the command for
221 text protocols. For binary protocols, enter hexadecimal values
222 as “\0xAA\0xBB”.
223 Locator Commands
225 These commands offer conversions of Degrees Minutes Seconds to other
226 formats, Maidenhead square locator conversions and distance and azimuth
227 conversions.
228 L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
230 Returns the Maidenhead 'Locator' for the given 'Longitude' and
231 'Latitude'.
232 'Longitude' and 'Latitude' are floating point values.
234 'Loc Len' is the precision of the returned square and should be
236 an even numbered integer value between 2 and 12.
237 For example:
239 L -170.0 -85.0 12
241 returns:
243 Locator: AA55AA00AA00
245 l, loc2lonlat 'Locator'
247 Returns 'Longitude' and 'Latitude' in decimal degrees at the
248 approximate center of the requested Maidenhead grid square.
249 'Locator' can be from 2 to 12 characters in length.
251 West longitude is expressed as a negative value.
253 South latitude is expressed as a negative value.
255 For example:
257 l AA55AA00AA00
259 returns:
261 Longitude: -169.999983 Latitude: -84.999991
263 Note: Despite the use of double precision variables internally,
265 some rounding error occurs.
266 D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
268 Returns 'Dec Degrees', a signed floating point value.
269 'Degrees' and 'Minutes' are integer values.
271 'Seconds' is a floating point value.
273 'S/W' is a flag with ‘1’ indicating South latitude or West lon‐
275 gitude and ‘0’ North or East (the flag is needed as computers
276 don't recognize a signed zero even though only the 'Degrees'
277 value is typically signed in DMS notation).
278 d, dec2dms 'Dec Degrees'
280 Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
281 Values are as in dms2dec above.
283 E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
285 Returns 'Dec Degrees', a signed floating point value.
286 'Degrees' is an integer value.
288 'Dec Minutes' is a floating point value.
290 'S/W' is a flag as in dms2dec above.
292 e, dec2dmmm 'Dec Deg'
294 Returns 'Degrees' 'Minutes' 'S/W'.
295 Values are as in dmmm2dec above.
297 B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
299 Returns 'Distance' and 'Azimuth'.
300 'Distance' is in km.
302 'Azimuth' is in degrees.
304 Supplied Lon/Lat values are signed floating point numbers.
306 A, a_sp2a_lp 'Short Path Deg'
308 Returns 'Long Path Deg'.
309 Both the supplied argument and returned value are floating point
311 values within the range of 0.00 to 360.00.
312 Note: Supplying a negative value will return an error message.
314 a, d_sp2d_lp 'Short Path km'
316 Returns 'Long Path km'.
317 Both the supplied argument and returned value are floating point
319 values.
320 pause 'Seconds'
322 Pause for the given whole (integer) number of 'Seconds' before
323 sending the next command to the rotator.
324
326 There are two protocols in use by rotctld, the Default Protocol and the
327 Extended Response Protocol.
328 The Default Protocol is intended primarily for the communication
330 between Hamlib library functions and rotctld (“NET rotctl”, available
331 using rotator model ‘2’).
332 The Extended Response Protocol is intended to be used with scripts or
334 other programs interacting directly with rotctld as consistent feedback
335 is provided.
336 Default Protocol
338 The Default Protocol is intentionally simple. Commands are entered on
339 a single line with any needed values. In practice, reliable results
340 are obtained by terminating each command string with a newline charac‐
341 ter, ‘\n’.
342 Example set position (Perl code):
344 print $socket "P 135 10\n";
346 or:
348 print $socket "\\set_pos 135 10\n"; # escape leading ‘\’
350 A one line response will be sent as a reply to set commands, “RPRT x\n”
352 where x is the Hamlib error code with ‘0’ indicating success of the
353 command.
354 Responses from rotctld get commands are text values and match the same
356 tokens used in the set commands. Each value is returned on its own
357 line. On error the string “RPRT x\n” is returned where x is the Hamlib
358 error code.
359 Example get position (Perl code):
361 print $socket "p\n";
363 "135"
364 "10"
365 Most get functions return one to three values. A notable exception is
367 the dump_caps command which returns many lines of key:value pairs.
368 This protocol is primarily used by the “NET rotctl” (rotctl model 2)
370 backend which allows applications already written for Hamlib's C API to
371 take advantage of rotctld without the need of rewriting application
372 code. An application's user can select rotator model 2 (“NET rotctl”)
373 and then set rot_pathname to “localhost:4533” or other network
374 host:port (set by the -T/-t options, respectively, above).
375 Extended Response Protocol
377 The Extended Response protocol adds several rules to the strings
378 returned by rotctld and adds a rule for the command syntax.
379 1. The command received by rotctld is echoed with its long command name
381 followed by the value(s) (if any) received from the client terminated
382 by the specified response separator as the first record of the
383 response.
384 2. The last record of each block is the string “RPRT x\n” where x is
386 the numeric return value of the Hamlib backend function that was called
387 by the command.
388 3. Any records consisting of data values returned by the rotator back‐
390 end are prepended by a string immediately followed by a colon then a
391 space and then the value terminated by the response separator, e.g.
392 “Azimuth: 90.000000\n” when the command was prepended by ‘+’.
393 4. All commands received will be acknowledged by rotctld with records
395 from rules 1 and 2. Records from rule 3 are only returned when data
396 values must be returned to the client.
397 An example response to a P command sent from the shell prompt (note the
399 prepended ‘+’):
400 $ echo "+P 90 45" | nc -w 1 localhost 4533
402 set_pos: 90 45
403 RPRT 0
404 In this case the long command name and values are returned on the first
406 line and the second line contains the end of block marker and the
407 numeric rotor backend return value indicating success.
408 An example response to a get_pos query:
410 $ echo "+\get_pos" | nc -w 1 localhost 4533
412 get_pos:
413 Azimuth: 90.000000
414 Elevation: 45.000000
415 RPRT 0
416 Note: The ‘\’ is still required for the long command name even
418 with the ERP character.
419 In this case, as no value is passed to rotctld, the first line consists
421 only of the long command name. The final line shows that the command
422 was processed successfully by the rotor backend.
423 Invoking the Extended Response Protocol requires prepending a command
425 with a punctuation character. As shown in the examples above, prepend‐
426 ing a ‘+’ character to the command results in the responses being sepa‐
427 rated by a newline character (‘\n’). Any other punctuation character
428 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
429 cause that character to become the response separator and the entire
430 response will be on one line.
431 Separator character summary:
433 ‘+’ Each record of the response is appended with a newline (‘\n’).
435 ‘;’, ‘|’, or, ‘,’
437 Each record of the response is appended by the given character
438 resulting in entire response on one line.
439 These are common record separators for text representations of
441 spreadsheet data, etc.
442 ‘?’ Reserved for help in rotctl.
444 ‘_’ Reserved for get_info short command
446 ‘#’ Reserved for comments when reading a command file script.
448 Note: Other punctuation characters have not been tested! Use at
450 your own risk.
451 For example, invoking a get_pos query with a leading ‘;’ returns:
453 get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0
455 Or, using the pipe character ‘|’ returns:
457 get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0
459 And a set_pos command prepended with a ‘|’ returns:
461 set_pos: 135 22.5|RPRT 0
463 Such a format will allow reading a response as a single event using a
465 preferred response separator. Other punctuation characters have not
466 been tested!
467 All commands with the exception of set_conf have been tested with the
469 Extended Response protocol and the included testrotctld.pl Perl script.
470
472 The -v, --verbose option allows different levels of diagnostics to be
473 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
474 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
475 A given verbose level is useful for providing needed debugging informa‐
477 tion to the email address below. For example, TRACE output shows all
478 of the values sent to and received from the radio which is very useful
479 for radio backend library development and may be requested by the
480 developers.
481
483 Start rotctld for a Hy-Gain Ham IV rotor with the Idiom Press RotorEZ
484 board installed using a USB-to-serial adapter and backgrounding:
485 $ rotctld -m 401 -r /dev/ttyUSB1 &
487 Start rotctld for RotorEZ using COM2 on Win32:
489 $ rotctl -m 401 -r COM2
491 Connect to the already running rotctld, and set position to 135.0
493 degrees azimuth and 30.0 degrees elevation with a 1 second read timeout
494 from the shell prompt:
495 $ echo "\set_pos 135.0 30.0" | nc -w 1 localhost 4533
497 Connect to a running rotctld with rotctl on the local host:
499 $ rotctl -m 2
501
503 No authentication whatsoever; DO NOT leave this TCP port open wide to
504 the Internet. Please ask if stronger security is needed or consider
505 using a Secure Shell (ssh(1)) tunnel.
506 As rotctld does not need any greater permissions than rotctl, it is
508 advisable to not start rotctld as “root” or another system user account
509 in order to limit any vulnerability.
510
512 The daemon is not detaching and backgrounding itself.
513 No method to exit the daemon so the kill(1) command must be used to
515 terminate it.
516 Multiple clients using the daemon may experience contention with the
518 connected rotator.
519 Report bugs to:
521 Hamlib Developer mailing list
523 ⟨hamlib-developer@lists.sourceforge.net⟩
524
526 This file is part of Hamlib, a project to develop a library that sim‐
527 plifies radio and rotator control functions for developers of software
528 primarily of interest to radio amateurs and those interested in radio
529 communications.
530 Copyright © 2000-2009 Stephane Fillod
532 Copyright © 2000-2018 the Hamlib Group (various contributors)
533 Copyright © 2011-2018 Nate Bargmann
534 This is free software; see the file COPYING for copying conditions.
536 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
537 PARTICULAR PURPOSE.
538
540 kill(1), rotctl(1), ssh(1), hamlib(7)
541
543 Links to the Hamlib Wiki, Git repository, release archives, and daily
544 snapshot archives:
545 hamlib.org ⟨http://www.hamlib.org⟩.
547Hamlib 2018-04-29 ROTCTLD(1)