1ROTCTLD(1) Hamlib Utilities ROTCTLD(1)
2
3
4
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
21 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
32 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
39 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
43 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
53 Here is a summary of the supported options:
54
55 -m, --model=id
56 Select rotator model number.
57
58 See model list (use “rotctld -l”).
59
60 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
64 -r, --rot-file=device
65 Use device as the file name of the port connected to the rota‐
66 tor.
67
68 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
73 -s, --serial-speed=baud
74 Set serial speed to baud rate.
75
76 Uses maximum serial speed from rotator backend capabilities as
77 the default.
78
79 -T, --listen-addr=IPADDR
80 Use IPADDR as the listening IP address.
81
82 The default is ANY.
83
84 -t, --port=number
85 Use number as the TCP listening port.
86
87 The default is 4533.
88
89 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
92 -L, --show-conf
93 List all configuration parameters for the rotator defined with
94 -m above.
95
96 -C, --set-conf=parm=val[,parm=val]
97 Set rotator configuration parameter(s), e.g. stop_bits=2.
98
99 Use the -L option above for a list of configuration parameters
100 for a given model number.
101
102 -u, --dump-state
103 Dump state for the rotator defined with -m above and exit.
104
105 -u, --dump-caps
106 Dump capabilities for the rotator defined with -m above and
107 exit.
108
109 -l, --list
110 List all rotator model numbers defined in Hamlib and exit.
111
112 The list is sorted by model number.
113
114 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
119 -v, --verbose
120 Set verbose mode, cumulative (see DIAGNOSTICS below).
121
122 -Z, --debug-time-stamps
123 Enable time stamps for the debug messages.
124
125 Use only in combination with the -v option as it generates no
126 output on its own.
127
128 -h, --help
129 Show a summary of these options and exit.
130
131 -V, --version
132 Show version of rotctld and exit.
133
134 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
138 Be aware that the backend for the rotator to be controlled, or the
139 rotator itself may not support some commands. In that case, the opera‐
140 tion 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
147 Since most of the Hamlib operations have a set and a get method, an
148 upper case letter will be used for set methods whereas the correspond‐
149 ing lower case letter refers to the get method. Each operation also
150 has a long name; prepend a backslash, ‘\’, to send a long command name.
151
152 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
158 Note: The backend for the rotator to be controlled, or the rotator
159 itself may not support some commands. In that case, the operation will
160 fail with a Hamlib error message.
161
162 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
164 description. In the case of get commands the quoted italicized string
165 is the key name of the value returned.):
166
167 P, set_pos 'Azimuth' 'Elevation'
168 Set position.
169
170 'Azimuth' and 'Elevation' are floating point values.
171
172 For example (typed text shown in bold):
173
174 P 163.0 41.0
175
176 Note: If the rotator does not support setting elevation (most do
177 not) supply “0.0” for 'Elevation'.
178
179 p, get_pos
180 Get position.
181
182 'Azimuth' and 'Elevation' are returned as double precision
183 floating point values.
184
185 M, move 'Direction' 'Speed'
186 Move the rotator in a specific direction at the given rate.
187
188 'Direction' is an integer defined as ‘2’ = Up, ‘4’ = Down, ‘8’ =
189 Left, and ‘16’ = Right.
190
191 'Speed' is an integer between 1 and 100. Use -1 for no change to
192 current speed.
193
194 Note: Not all backends that implement the move command use the
195 Speed value.
196
197 S, stop
198 Stop the rotator.
199
200 K, park
201 Park the rotator.
202
203 C, set_conf 'Token' 'Value'
204 Set a configuration parameter.
205
206 'Token' is a string; see the -C option and the -L output.
207
208 'Value' is a string of up to 20 characters.
209
210 R, reset 'Reset'
211 Reset the rotator.
212
213 'Reset' accepts an integer value of ‘1’ for “Reset All”.
214
215 _, get_info
216 Get misc information about the rotator.
217
218 Returns 'Info' “Model Name”.
219
220 dump_state
221 Return certain state information about the rotator backend.
222
223 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
227 w, send_cmd 'Cmd'
228 Send a raw command string to the rotator.
229
230 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
234 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
239 L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len'
240 Returns the Maidenhead 'Locator' for the given 'Longitude' and
241 'Latitude'.
242
243 'Longitude' and 'Latitude' are floating point values.
244
245 'Loc Len' is the precision of the returned square and should be
246 an even numbered integer value between 2 and 12.
247
248 For example:
249
250 L -170.0 -85.0 12
251
252 returns:
253
254 Locator: AA55AA00AA00
255
256 l, loc2lonlat 'Locator'
257 Returns 'Longitude' and 'Latitude' in decimal degrees at the
258 approximate center of the requested Maidenhead grid square.
259
260 'Locator' can be from 2 to 12 characters in length.
261
262 West longitude is expressed as a negative value.
263
264 South latitude is expressed as a negative value.
265
266 For example:
267
268 l AA55AA00AA00
269
270 returns:
271
272 Longitude: -169.999983 Latitude: -84.999991
273
274 Note: Despite the use of double precision variables internally,
275 some rounding error occurs.
276
277 D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
278 Returns 'Dec Degrees', a signed floating point value.
279
280 'Degrees' and 'Minutes' are integer values.
281
282 'Seconds' is a floating point value.
283
284 '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
289 d, dec2dms 'Dec Degrees'
290 Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
291
292 Values are as in dms2dec above.
293
294 E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
295 Returns 'Dec Degrees', a signed floating point value.
296
297 'Degrees' is an integer value.
298
299 'Dec Minutes' is a floating point value.
300
301 'S/W' is a flag as in dms2dec above.
302
303 e, dec2dmmm 'Dec Deg'
304 Returns 'Degrees' 'Minutes' 'S/W'.
305
306 Values are as in dmmm2dec above.
307
308 B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
309 Returns 'Distance' and 'Azimuth'.
310
311 'Distance' is in km.
312
313 'Azimuth' is in degrees.
314
315 Supplied Lon/Lat values are signed floating point numbers.
316
317 A, a_sp2a_lp 'Short Path Deg'
318 Returns 'Long Path Deg'.
319
320 Both the supplied argument and returned value are floating point
321 values within the range of 0.00 to 360.00.
322
323 Note: Supplying a negative value will return an error message.
324
325 a, d_sp2d_lp 'Short Path km'
326 Returns 'Long Path km'.
327
328 Both the supplied argument and returned value are floating point
329 values.
330
331 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
339 The Default Protocol is intended primarily for the communication
340 between Hamlib library functions and rotctld (“NET rotctl”, available
341 using rotator model ‘2’).
342
343 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
347 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
353 Example set position (Perl code):
354
355 print $socket "P 135 10\n";
356
357 or:
358
359 print $socket "\\set_pos 135 10\n"; # escape leading ‘\’
360
361 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
365 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
370 Example get position (Perl code):
371
372 print $socket "p\n";
373 "135"
374 "10"
375
376 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
379 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
386 Extended Response Protocol
387 The Extended Response protocol adds several rules to the strings
388 returned by rotctld and adds a rule for the command syntax.
389
390 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
393 response.
394
395 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
399 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
404 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
408 An example response to a P command sent from the shell prompt (note the
409 prepended ‘+’):
410
411 $ echo "+P 90 45" | nc -w 1 localhost 4533
412 set_pos: 90 45
413 RPRT 0
414
415 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
417 numeric rotor backend return value indicating success.
418
419 An example response to a get_pos query:
420
421 $ echo "+\get_pos" | nc -w 1 localhost 4533
422 get_pos:
423 Azimuth: 90.000000
424 Elevation: 45.000000
425 RPRT 0
426
427 Note: The ‘\’ is still required for the long command name even
428 with the ERP character.
429
430 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
434 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
442 Separator character summary:
443
444 ‘+’ Each record of the response is appended with a newline (‘\n’).
445
446 ‘;’, ‘|’, or, ‘,’
447 Each record of the response is appended by the given character
448 resulting in entire response on one line.
449
450 These are common record separators for text representations of
451 spreadsheet data, etc.
452
453 ‘?’ Reserved for help in rotctl.
454
455 ‘_’ Reserved for get_info short command
456
457 ‘#’ Reserved for comments when reading a command file script.
458
459 Note: Other punctuation characters have not been tested! Use at
460 your own risk.
461
462 For example, invoking a get_pos query with a leading ‘;’ returns:
463
464 get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0
465
466 Or, using the pipe character ‘|’ returns:
467
468 get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0
469
470 And a set_pos command prepended with a ‘|’ returns:
471
472 set_pos: 135 22.5|RPRT 0
473
474 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
478 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
486 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
490 developers.
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
496 $ rotctld -m 401 -r /dev/ttyUSB1 &
497
498 Start rotctld for RotorEZ using COM2 on Win32:
499
500 > rotctl -m 401 -r COM2
501
502 Connect to the already running rotctld, and set position to 135.0
503 degrees azimuth and 30.0 degrees elevation with a 1 second read timeout
504 from the shell prompt:
505
506 $ echo "\set_pos 135.0 30.0" | nc -w 1 localhost 4533
507
508 Connect to a running rotctld with rotctl on the local host:
509
510 $ 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
517 As rotctld does not need any greater permissions than rotctl, it is
518 advisable 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
524 No method to exit the daemon so the kill(1) command must be used to
525 terminate it.
526
527 Multiple clients using the daemon may experience contention with the
528 connected rotator.
529
530 Report bugs to:
531
532 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
541 Copyright © 2000-2009 Stephane Fillod
542 Copyright © 2000-2018 the Hamlib Group (various contributors)
543 Copyright © 2011-2020 Nate Bargmann
544
545 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⟩.
555
556
557
558Hamlib 2020-09-09 ROTCTLD(1)