1ROTCTLD(1)                     Hamlib Utilities                     ROTCTLD(1)
2
3
4

NAME

6       rotctld - TCP rotator control daemon
7

SYNOPSIS

9       rotctld [-hlLuV] [-m id] [-r device] [-s baud] [-T IPADDR] [-t number]
10               [-C parm=val] [-v[-Z]]
11

DESCRIPTION

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
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 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
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

OPTIONS

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  ro‐
139       tator itself may not support some commands. In that case, the operation
140       will fail with a Hamlib error code.
141

COMMANDS

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 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
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 it‐
159       self 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  de‐
164       scription.  In the case of get commands the quoted italicized string is
165       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 ap‐
258              proximate 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

PROTOCOL

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 be‐
340       tween Hamlib library functions and rotctld (“NET rotctl”, available us‐
341       ing 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 re‐
388       turned 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  re‐
393       sponse.
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  nu‐
417       meric 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

DIAGNOSTICS

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 de‐
490       velopers.
491

EXAMPLES

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 de‐
503       grees 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

SECURITY

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 ad‐
518       visable to not start rotctld as “root” or another system  user  account
519       in order to limit any vulnerability.
520

BUGS

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

COPYING

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

SEE ALSO

550       kill(1), rotctl(1), ssh(1), hamlib(7)
551

COLOPHON

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)
Impressum