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 re‐
14 quests 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 re‐
24 quested 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-state
103 Dump state for the rotator defined with -m above and exit.
104 -u, --dump-caps
106 Dump capabilities for the rotator defined with -m above and
107 exit.
108 -l, --list
110 List all rotator model numbers defined in Hamlib and exit.
111 The list is sorted by model number.
113 Note: In Linux the list can be scrolled back using Shift-
115 PageUp/Shift-PageDown, or using the scrollbars of a virtual ter‐
116 minal in X or the cmd window in Windows. The output can be
117 piped to more(1) or less(1), e.g. “rotctl -l | more”.
118 -v, --verbose
120 Set verbose mode, cumulative (see DIAGNOSTICS below).
121 -Z, --debug-time-stamps
123 Enable time stamps for the debug messages.
124 Use only in combination with the -v option as it generates no
126 output on its own.
127 -h, --help
129 Show a summary of these options and exit.
130 -V, --version
132 Show version of rotctld and exit.
133 Note: Some options may not be implemented by a given backend and will
135 return an error. This is most likely to occur with the --set-conf and
136 --show-conf options.
137 Be aware that the backend for the rotator to be controlled, or the ro‐
139 tator itself may not support some commands. In that case, the operation
140 will fail with a Hamlib error code.
141
143 Commands can be sent over the TCP socket either as a single char, or as
144 a long command name plus the value(s) space separated on one ‘\n’ ter‐
145 minated line. See PROTOCOL.
146 Since most of the Hamlib operations have a set and a get method, an up‐
148 per case letter will be used for set methods whereas the corresponding
149 lower case letter refers to the get method. Each operation also has a
150 long name; prepend a backslash, ‘\’, to send a long command name.
151 Example (Perl): “print $socket "\\dump_caps\n";” to see what the rota‐
153 tor's backend can do (Note: In Perl and many other languages a ‘\’ will
154 need to be escaped with a preceding ‘\’ so that even though two back‐
155 slash characters appear in the code, only one will be passed to
156 rotctld. This is a possible bug, beware!).
157 Note: The backend for the rotator to be controlled, or the rotator it‐
159 self may not support some commands. In that case, the operation will
160 fail with a Hamlib error message.
161 Here is a summary of the supported commands (In the case of set com‐
163 mands the quoted italicized string is replaced by the value in the de‐
164 scription. In the case of get commands the quoted italicized string is
165 the key name of the value returned.):
166 P, set_pos 'Azimuth' 'Elevation'
168 Set position.
169 'Azimuth' and 'Elevation' are floating point values.
171 For example (typed text shown in bold):
173 P 163.0 41.0
175 Note: If the rotator does not support setting elevation (most do
177 not) supply “0.0” for 'Elevation'.
178 p, get_pos
180 Get position.
181 'Azimuth' and 'Elevation' are returned as double precision
183 floating point values.
184 M, move 'Direction' 'Speed'
186 Move the rotator in a specific direction at the given rate.
187 'Direction' is an integer defined as ‘2’ = Up, ‘4’ = Down, ‘8’ =
189 Left, and ‘16’ = Right.
190 'Speed' is an integer between 1 and 100. Use -1 for no change to
192 current speed.
193 Note: Not all backends that implement the move command use the
195 Speed value.
196 S, stop
198 Stop the rotator.
199 K, park
201 Park the rotator.
202 C, set_conf 'Token' 'Value'
204 Set a configuration parameter.
205 'Token' is a string; see the -C option and the -L output.
207 'Value' is a string of up to 20 characters.
209 R, reset 'Reset'
211 Reset the rotator.
212 'Reset' accepts an integer value of ‘1’ for “Reset All”.
214 _, get_info
216 Get misc information about the rotator.
217 Returns 'Info' “Model Name”.
219 dump_state
221 Return certain state information about the rotator backend.
222 1, dump_caps
224 Not a real rot remote command, it just dumps capabilities, i.e.
225 what the backend knows about this model, and what it can do.
226 w, send_cmd 'Cmd'
228 Send a raw command string to the rotator.
229 ASCII CR is appended automatically at the end of the command for
231 text protocols. For binary protocols, enter hexadecimal values
232 as “\0xAA\0xBB”.
233 Locator Commands
235 These commands offer conversions of Degrees Minutes Seconds to other
236 formats, Maidenhead square locator conversions and distance and azimuth
237 conversions.
238 L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
240 Returns the Maidenhead 'Locator' for the given 'Longitude' and
241 'Latitude'.
242 'Longitude' and 'Latitude' are floating point values.
244 'Loc Len' is the precision of the returned square and should be
246 an even numbered integer value between 2 and 12.
247 For example:
249 L -170.0 -85.0 12
251 returns:
253 Locator: AA55AA00AA00
255 l, loc2lonlat 'Locator'
257 Returns 'Longitude' and 'Latitude' in decimal degrees at the ap‐
258 proximate center of the requested Maidenhead grid square.
259 'Locator' can be from 2 to 12 characters in length.
261 West longitude is expressed as a negative value.
263 South latitude is expressed as a negative value.
265 For example:
267 l AA55AA00AA00
269 returns:
271 Longitude: -169.999983 Latitude: -84.999991
273 Note: Despite the use of double precision variables internally,
275 some rounding error occurs.
276 D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
278 Returns 'Dec Degrees', a signed floating point value.
279 'Degrees' and 'Minutes' are integer values.
281 'Seconds' is a floating point value.
283 'S/W' is a flag with ‘1’ indicating South latitude or West lon‐
285 gitude and ‘0’ North or East (the flag is needed as computers
286 don't recognize a signed zero even though only the 'Degrees'
287 value is typically signed in DMS notation).
288 d, dec2dms 'Dec Degrees'
290 Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
291 Values are as in dms2dec above.
293 E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
295 Returns 'Dec Degrees', a signed floating point value.
296 'Degrees' is an integer value.
298 'Dec Minutes' is a floating point value.
300 'S/W' is a flag as in dms2dec above.
302 e, dec2dmmm 'Dec Deg'
304 Returns 'Degrees' 'Minutes' 'S/W'.
305 Values are as in dmmm2dec above.
307 B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
309 Returns 'Distance' and 'Azimuth'.
310 'Distance' is in km.
312 'Azimuth' is in degrees.
314 Supplied Lon/Lat values are signed floating point numbers.
316 A, a_sp2a_lp 'Short Path Deg'
318 Returns 'Long Path Deg'.
319 Both the supplied argument and returned value are floating point
321 values within the range of 0.00 to 360.00.
322 Note: Supplying a negative value will return an error message.
324 a, d_sp2d_lp 'Short Path km'
326 Returns 'Long Path km'.
327 Both the supplied argument and returned value are floating point
329 values.
330 pause 'Seconds'
332 Pause for the given whole (integer) number of 'Seconds' before
333 sending the next command to the rotator.
334
336 There are two protocols in use by rotctld, the Default Protocol and the
337 Extended Response Protocol.
338 The Default Protocol is intended primarily for the communication be‐
340 tween Hamlib library functions and rotctld (“NET rotctl”, available us‐
341 ing rotator model ‘2’).
342 The Extended Response Protocol is intended to be used with scripts or
344 other programs interacting directly with rotctld as consistent feedback
345 is provided.
346 Default Protocol
348 The Default Protocol is intentionally simple. Commands are entered on
349 a single line with any needed values. In practice, reliable results
350 are obtained by terminating each command string with a newline charac‐
351 ter, ‘\n’.
352 Example set position (Perl code):
354 print $socket "P 135 10\n";
356 or:
358 print $socket "\\set_pos 135 10\n"; # escape leading ‘\’
360 A one line response will be sent as a reply to set commands, “RPRT x\n”
362 where x is the Hamlib error code with ‘0’ indicating success of the
363 command.
364 Responses from rotctld get commands are text values and match the same
366 tokens used in the set commands. Each value is returned on its own
367 line. On error the string “RPRT x\n” is returned where x is the Hamlib
368 error code.
369 Example get position (Perl code):
371 print $socket "p\n";
373 "135"
374 "10"
375 Most get functions return one to three values. A notable exception is
377 the dump_caps command which returns many lines of key:value pairs.
378 This protocol is primarily used by the “NET rotctl” (rotctl model 2)
380 backend which allows applications already written for Hamlib's C API to
381 take advantage of rotctld without the need of rewriting application
382 code. An application's user can select rotator model 2 (“NET rotctl”)
383 and then set rot_pathname to “localhost:4533” or other network
384 host:port (set by the -T/-t options, respectively, above).
385 Extended Response Protocol
387 The Extended Response protocol adds several rules to the strings re‐
388 turned by rotctld and adds a rule for the command syntax.
389 1. The command received by rotctld is echoed with its long command name
391 followed by the value(s) (if any) received from the client terminated
392 by the specified response separator as the first record of the re‐
393 sponse.
394 2. The last record of each block is the string “RPRT x\n” where x is
396 the numeric return value of the Hamlib backend function that was called
397 by the command.
398 3. Any records consisting of data values returned by the rotator back‐
400 end are prepended by a string immediately followed by a colon then a
401 space and then the value terminated by the response separator, e.g.
402 “Azimuth: 90.000000\n” when the command was prepended by ‘+’.
403 4. All commands received will be acknowledged by rotctld with records
405 from rules 1 and 2. Records from rule 3 are only returned when data
406 values must be returned to the client.
407 An example response to a P command sent from the shell prompt (note the
409 prepended ‘+’):
410 $ echo "+P 90 45" | nc -w 1 localhost 4533
412 set_pos: 90 45
413 RPRT 0
414 In this case the long command name and values are returned on the first
416 line and the second line contains the end of block marker and the nu‐
417 meric rotor backend return value indicating success.
418 An example response to a get_pos query:
420 $ echo "+\get_pos" | nc -w 1 localhost 4533
422 get_pos:
423 Azimuth: 90.000000
424 Elevation: 45.000000
425 RPRT 0
426 Note: The ‘\’ is still required for the long command name even
428 with the ERP character.
429 In this case, as no value is passed to rotctld, the first line consists
431 only of the long command name. The final line shows that the command
432 was processed successfully by the rotor backend.
433 Invoking the Extended Response Protocol requires prepending a command
435 with a punctuation character. As shown in the examples above, prepend‐
436 ing a ‘+’ character to the command results in the responses being sepa‐
437 rated by a newline character (‘\n’). Any other punctuation character
438 recognized by the C ispunct() function except ‘\’, ‘?’, or ‘_’ will
439 cause that character to become the response separator and the entire
440 response will be on one line.
441 Separator character summary:
443 ‘+’ Each record of the response is appended with a newline (‘\n’).
445 ‘;’, ‘|’, or, ‘,’
447 Each record of the response is appended by the given character
448 resulting in entire response on one line.
449 These are common record separators for text representations of
451 spreadsheet data, etc.
452 ‘?’ Reserved for help in rotctl.
454 ‘_’ Reserved for get_info short command
456 ‘#’ Reserved for comments when reading a command file script.
458 Note: Other punctuation characters have not been tested! Use at
460 your own risk.
461 For example, invoking a get_pos query with a leading ‘;’ returns:
463 get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0
465 Or, using the pipe character ‘|’ returns:
467 get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0
469 And a set_pos command prepended with a ‘|’ returns:
471 set_pos: 135 22.5|RPRT 0
473 Such a format will allow reading a response as a single event using a
475 preferred response separator. Other punctuation characters have not
476 been tested!
477 All commands with the exception of set_conf have been tested with the
479 Extended Response protocol and the included testrotctld.pl Perl script.
480
482 The -v, --verbose option allows different levels of diagnostics to be
483 output to stderr and correspond to -v for BUG, -vv for ERR, -vvv for
484 WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
485 A given verbose level is useful for providing needed debugging informa‐
487 tion to the email address below. For example, TRACE output shows all
488 of the values sent to and received from the radio which is very useful
489 for radio backend library development and may be requested by the de‐
490 velopers.
491
493 Start rotctld for a Hy-Gain Ham IV rotor with the Idiom Press RotorEZ
494 board installed using a USB-to-serial adapter and backgrounding:
495 $ rotctld -m 401 -r /dev/ttyUSB1 &
497 Start rotctld for RotorEZ using COM2 on Win32:
499 > rotctl -m 401 -r COM2
501 Connect to the already running rotctld, and set position to 135.0 de‐
503 grees azimuth and 30.0 degrees elevation with a 1 second read timeout
504 from the shell prompt:
505 $ echo "\set_pos 135.0 30.0" | nc -w 1 localhost 4533
507 Connect to a running rotctld with rotctl on the local host:
509 $ rotctl -m 2
511
513 No authentication whatsoever; DO NOT leave this TCP port open wide to
514 the Internet. Please ask if stronger security is needed or consider
515 using a Secure Shell (ssh(1)) tunnel.
516 As rotctld does not need any greater permissions than rotctl, it is ad‐
518 visable to not start rotctld as “root” or another system user account
519 in order to limit any vulnerability.
520
522 The daemon is not detaching and backgrounding itself.
523 No method to exit the daemon so the kill(1) command must be used to
525 terminate it.
526 Multiple clients using the daemon may experience contention with the
528 connected rotator.
529 Report bugs to:
531 Hamlib Developer mailing list
533 ⟨hamlib-developer@lists.sourceforge.net⟩
534
536 This file is part of Hamlib, a project to develop a library that sim‐
537 plifies radio, rotator, and amplifier control functions for developers
538 of software primarily of interest to radio amateurs and those inter‐
539 ested in radio communications.
540 Copyright © 2000-2009 Stephane Fillod
542 Copyright © 2000-2018 the Hamlib Group (various contributors)
543 Copyright © 2011-2020 Nate Bargmann
544 This is free software; see the file COPYING for copying conditions.
546 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
547 PARTICULAR PURPOSE.
548
550 kill(1), rotctl(1), ssh(1), hamlib(7)
551
553 Links to the Hamlib Wiki, Git repository, release archives, and daily
554 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
555Hamlib 2020-09-09 ROTCTLD(1)