2008-09-12 22:55:10 +00:00
|
|
|
.\" Hey, EMACS: -*- nroff -*-
|
|
|
|
.\" First parameter, NAME, should be all caps
|
|
|
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
|
|
|
|
.\" other parameters are allowed: see man(7), man(1)
|
2012-01-08 02:36:18 +00:00
|
|
|
.TH ROTCTLD "8" "January 7, 2012" "Hamlib" "Rotator Control Daemon"
|
2008-09-12 22:55:10 +00:00
|
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
|
|
.\"
|
|
|
|
.\" Some roff macros, for reference:
|
|
|
|
.\" .nh disable hyphenation
|
|
|
|
.\" .hy enable hyphenation
|
|
|
|
.\" .ad l left justify
|
|
|
|
.\" .ad b justify to both left and right margins
|
|
|
|
.\" .nf disable filling
|
|
|
|
.\" .fi enable filling
|
|
|
|
.\" .br insert line break
|
|
|
|
.\" .sp <n> insert n+1 empty lines
|
|
|
|
.\" for manpage-specific macros, see man(7)
|
|
|
|
.SH NAME
|
2010-02-14 22:18:00 +00:00
|
|
|
rotctld \- Hamlib TCP rotator control daemon
|
2008-09-12 22:55:10 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B rotctld
|
|
|
|
[\fIOPTION\fR]...
|
|
|
|
.SH DESCRIPTION
|
2011-06-21 18:42:43 +00:00
|
|
|
The \fBrotctld\fP program is an NEW \fBHamlib\fP rotator control daemon ready
|
|
|
|
for testing that handles client requests via TCP sockets. This allows multiple
|
|
|
|
user programs to share one rotator (this needs testing). Multiple rotators can
|
|
|
|
be controlled on different TCP ports by use of multiple \fBrotctld\fP processes.
|
|
|
|
The syntax of the commands are the same as \fBrotctl\fP. It is hoped that
|
|
|
|
\fBrotctld\fP will be especially useful for client authors using languages such
|
|
|
|
as Perl, Python, PHP, and others.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
|
|
|
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
|
2010-02-14 22:18:00 +00:00
|
|
|
.\" \fI<whatever>\fP escape sequences to invoke bold face and italics,
|
2008-09-12 22:55:10 +00:00
|
|
|
.\" respectively.
|
|
|
|
\fBrotctld\fP communicates to a client through a TCP socket using text
|
|
|
|
commands shared with \fBrotctl\fP. The protocol is simple, commands are sent
|
|
|
|
to \fBrotctld\fP on one line and \fBrotctld\fP responds to "get" commands with
|
2008-11-01 22:33:46 +00:00
|
|
|
the requested values, one per line, when successful, otherwise, it responds
|
2011-07-09 03:55:54 +00:00
|
|
|
with one line "RPRT x", where x is a negative number indicating the error code.
|
|
|
|
Commands that do not return values respond with the line "RPRT x", where x
|
2011-06-21 18:42:43 +00:00
|
|
|
is zero when successful, otherwise is a regative number indicating the error
|
|
|
|
code. Each line is terminated with a newline '\\n' character. This protocol
|
|
|
|
is primarily for use by the \fINET rotctl\fP (rot model 2) backend.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
A separate \fBExtended Response\fP protocol extends the above
|
|
|
|
behavior by echoing the received command string as a header, any returned values
|
2011-07-09 03:55:54 +00:00
|
|
|
as a key: value pair, and the "RPRT x" string as the end of response marker
|
2011-06-21 18:42:43 +00:00
|
|
|
which includes the \fBHamlib\fP success or failure value. See the
|
|
|
|
\fIPROTOCOL\fP section for details. Consider using this protocol for clients
|
|
|
|
that will interact with \fBrotctld\fP directly through a TCP socket.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
|
|
|
Keep in mind that \fBHamlib\fP is BETA level software.
|
2011-06-21 18:42:43 +00:00
|
|
|
While a lot of backend libraries lack complete rotator support, the basic
|
|
|
|
functions are usually well supported. The API may change without publicized
|
|
|
|
notice, while an advancement of the minor version (e.g. 1.1.x to 1.2.x)
|
|
|
|
indicates such a change.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
Please report bugs and provide feedback at the e-mail address given in the
|
2008-09-12 22:55:10 +00:00
|
|
|
REPORTING BUGS section. Patches and code enhancements are also welcome.
|
|
|
|
.SH OPTIONS
|
|
|
|
This program follows the usual GNU command line syntax, with long
|
2009-01-15 03:45:08 +00:00
|
|
|
options starting with two dashes ('-').
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
2008-09-12 22:55:10 +00:00
|
|
|
Here is a summary of the supported options:
|
|
|
|
.TP
|
|
|
|
.B \-m, --model=id
|
2009-01-15 03:45:08 +00:00
|
|
|
Select rotator model number. See -l, "list" option below.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
|
|
|
.B \-r, --rot-file=device
|
|
|
|
Use \fIdevice\fP as the file name of the port the rotator is connected.
|
2010-02-14 22:18:00 +00:00
|
|
|
Often a serial port, but could be a USB to serial adapter or USB port device.
|
2011-06-21 18:42:43 +00:00
|
|
|
Typically /dev/ttyS0, /dev/ttyS1, /dev/ttyUSB0, etc. on Linux or COM1, COM2,
|
|
|
|
etc. on Win32.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
|
|
|
.B \-s, --serial-speed=baud
|
2009-01-15 03:45:08 +00:00
|
|
|
Set serial speed to \fIbaud\fP rate. Uses maximum serial speed from rotor
|
|
|
|
backend capabilities (set by -m above) as the default.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B \-T, --listen-addr=IPADDR
|
|
|
|
Use \fIIPADDR\fP as the listening IP address. The default is ANY.
|
|
|
|
.TP
|
|
|
|
.B \-t, --port=number
|
|
|
|
Use \fInumber\fP as the TCP listening port. The default is 4533.
|
2010-02-18 00:18:54 +00:00
|
|
|
.sp
|
|
|
|
\fBN.B.\fP: As \fBrigctld\fP's default port is 4532, it is advisable to use odd
|
|
|
|
numbered ports for \fBrotctld\fP, e.g. 4533, 4535, 4537, etc.
|
2010-02-14 22:18:00 +00:00
|
|
|
.TP
|
2008-09-12 22:55:10 +00:00
|
|
|
.B \-L, --show-conf
|
|
|
|
List all config parameters for the rotator defined with -m above.
|
|
|
|
.TP
|
|
|
|
.B \-C, --set-conf=parm=val[,parm=val]*
|
2009-01-15 03:45:08 +00:00
|
|
|
Set config parameter. e.g. --set-conf=stop_bits=2
|
2010-02-18 00:18:54 +00:00
|
|
|
.sp
|
2008-09-12 22:55:10 +00:00
|
|
|
Use -L option for a list.
|
|
|
|
.TP
|
|
|
|
.B \-l, --list
|
|
|
|
List all model numbers defined in \fBHamlib\fP and exit.
|
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B \-u, --dump-caps
|
|
|
|
Dump capabilities for the radio defined with -m above and exit.
|
|
|
|
.TP
|
|
|
|
.B \-e, --end-marker
|
|
|
|
Use END marker in rotctld protocol.
|
2010-02-18 00:18:54 +00:00
|
|
|
.sp
|
2011-06-21 18:42:43 +00:00
|
|
|
N.B.: This option should be considered obsolete. Please consider using the
|
|
|
|
Extended Response protocol instead (see \fIPROTOCOL\fP below). This option
|
|
|
|
will be removed in a future Hamlib release.
|
2010-02-14 22:18:00 +00:00
|
|
|
.TP
|
2008-09-12 22:55:10 +00:00
|
|
|
.B \-v, --verbose
|
|
|
|
Set verbose mode, cumulative (see DIAGNOSTICS below).
|
|
|
|
.TP
|
|
|
|
.B \-h, --help
|
|
|
|
Show a summary of these options and exit.
|
|
|
|
.TP
|
|
|
|
.B \-V, --version
|
|
|
|
Show the version of \fBrotctld\fP and exit.
|
|
|
|
.PP
|
|
|
|
\fBN.B.\fP Some options may not be implemented by a given backend and will
|
2010-02-14 22:18:00 +00:00
|
|
|
return an error. This is most likely to occur with the \fI\-\-set-conf\fP
|
2008-09-12 22:55:10 +00:00
|
|
|
and \fI\-\-show-conf\fP options.
|
2009-11-03 20:47:15 +00:00
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
Please note that the backend for the rotator to be controlled,
|
|
|
|
or the rotator itself may not support some commands. In that case,
|
2008-09-12 22:55:10 +00:00
|
|
|
the operation will fail with a \fBHamlib\fP error code.
|
|
|
|
.SH COMMANDS
|
2010-02-14 22:18:00 +00:00
|
|
|
Commands can be sent over the TCP socket either as a single char, or as a
|
|
|
|
long command name plus the value(s) space separated on one '\\n' terminated
|
|
|
|
line. See \fIPROTOCOL\fP.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
2011-06-21 18:42:43 +00:00
|
|
|
Since most of the \fBHamlib\fP operations have a \fIset\fP and a \fIget\fP
|
|
|
|
method, an upper case letter will be used for \fIset\fP methods whereas the
|
2008-09-12 22:55:10 +00:00
|
|
|
corresponding lower case letter refers to the \fIget\fP method. Each operation
|
2010-02-14 22:18:00 +00:00
|
|
|
also has a long name; prepend a backslash to send a long command name.
|
|
|
|
.PP
|
|
|
|
Example (Perl): `print $socket "\\\\dump_caps\\n";' to see what the rotor's
|
|
|
|
backend can do (NOTE: In Perl and many other languages a '\\' will need to be
|
|
|
|
escaped with a preceding '\\' so that even though two backslash characters
|
|
|
|
appear in the code, only one will be passed to \fBrotctld\fP. This is a
|
2010-02-18 00:18:54 +00:00
|
|
|
possible bug, beware!).
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
Please note that the backend for the rotator to be controlled, or the rotator
|
|
|
|
itself may not support some commands. In that case, the operation will fail
|
|
|
|
with a \fBHamlib\fP error message.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
Here is a summary of the supported commands (In the case of "set" commands the
|
|
|
|
quoted string is replaced by the value in the description. In the case of "get"
|
|
|
|
commands the quoted string is the key name of the value returned.):
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B P, set_pos 'Azimuth' 'Elevation'
|
|
|
|
Set position: Azimuth and Elevation as double precision floating point values.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
|
|
|
.B p, get_pos
|
2010-02-14 22:18:00 +00:00
|
|
|
Get position: 'Azimuth' and 'Elevation' as double precision floating point
|
|
|
|
values.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B M, move 'Direction' 'Speed'
|
|
|
|
Move the rotator in a specific direction at the given rate.
|
|
|
|
.sp
|
|
|
|
Values are integers where Direction is defined as 2 = Up, 4 = Down, 8 = Left,
|
|
|
|
and 16 = Right. Speed is an integer between 1 and 100. Not all backends that
|
|
|
|
implement the move command use the Speed value. At this time only the gs232a
|
|
|
|
utilizes the Speed parameter.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
|
|
|
.B S, stop
|
|
|
|
Stop the rotator.
|
2010-02-14 23:01:53 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B K, park
|
|
|
|
Park the antenna.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B C, set_conf 'Token' 'Value'
|
|
|
|
Set Token to Value.
|
|
|
|
.sp
|
|
|
|
Backend dependent. Needs testing.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B R, reset 'Reset'
|
|
|
|
Reset the rotator.
|
|
|
|
.sp
|
|
|
|
Integer value of '1' for Reset All.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
|
|
|
.B _, get_info
|
|
|
|
Get misc information about the rotator.
|
2010-02-14 22:18:00 +00:00
|
|
|
.sp
|
|
|
|
At the moment returns 'Model Name'.
|
2008-09-12 22:55:10 +00:00
|
|
|
.TP
|
2010-02-14 22:18:00 +00:00
|
|
|
.B w, send_cmd 'Cmd'
|
|
|
|
Send raw command string to rotator.
|
|
|
|
.sp
|
|
|
|
For binary protocols enter values as \\0xAA\\0xBB. Expect a 'Reply' from the
|
|
|
|
rotator which will likely be a binary block or an ASCII string.
|
|
|
|
.PP
|
|
|
|
\fBLocator Commands\fP
|
|
|
|
.PP
|
|
|
|
These commands offer conversions of Degrees Minutes Seconds to other formats,
|
|
|
|
Maidenhead square locator conversions and distance and azimuth conversions.
|
|
|
|
.TP
|
|
|
|
.B L, lonlat2loc 'Longitude' 'Latitude' 'Loc Len [2-12]'
|
|
|
|
Returns the Maidenhead locator for the given 'Longitude' and 'Latitude'.
|
|
|
|
.sp
|
|
|
|
Both are floating point values. The precision of the returned square is
|
|
|
|
controlled by 'Loc Len' which should be an even numbered integer value between
|
|
|
|
2 and 12.
|
|
|
|
.sp
|
2011-06-21 18:42:43 +00:00
|
|
|
For example, "+L -170.000000 -85.000000 12\\n" returns
|
|
|
|
"Locator: AA55AA00AA00\\n".
|
2010-02-14 22:18:00 +00:00
|
|
|
.TP
|
|
|
|
.B l, loc2lonlat 'Locator'
|
|
|
|
Returns 'Longitude' and 'Latitude' in decimal degrees at the approximate
|
|
|
|
center of the requested grid square (despite the use of double precision
|
|
|
|
variables internally, some rounding error occurs). West longitude is
|
|
|
|
expressed as a negative value. South latitude is expressed as a negative
|
|
|
|
value. Locator can be from 2 to 12 characters in length.
|
|
|
|
.sp
|
|
|
|
For example, "+l AA55AA00AA00\\n" returns "Longitude: -169.999983\\nLatitude:
|
|
|
|
-84.999991\\n".
|
|
|
|
.TP
|
|
|
|
.B D, dms2dec 'Degrees' 'Minutes' 'Seconds' 'S/W'
|
|
|
|
Returns 'Dec Degrees', a signed floating point value.
|
|
|
|
.sp
|
|
|
|
Degrees and Minutes are
|
|
|
|
integer values and Seconds is a floating point value. S/W is a flag with '1'
|
|
|
|
indicating South latitude or West longitude and '0' North or East (the flag is
|
|
|
|
needed as computers don't recognize a signed zero even though only the Degrees
|
|
|
|
value only is typically signed in DMS notation).
|
|
|
|
.TP
|
|
|
|
.B d, dec2dms 'Dec Degrees'
|
|
|
|
Returns 'Degrees' 'Minutes' 'Seconds' 'S/W'.
|
|
|
|
.sp
|
|
|
|
Values are as in dms2dec above.
|
|
|
|
.TP
|
|
|
|
.B E, dmmm2dec 'Degrees' 'Dec Minutes' 'S/W'
|
|
|
|
Returns 'Dec Degrees', a signed floating point value.
|
|
|
|
.sp
|
|
|
|
Degrees is an integer
|
|
|
|
value and Minutes is a floating point value. S/W is a flag with '1'
|
|
|
|
indicating South latitude or West longitude and '0' North or East (the flag is
|
|
|
|
needed as computers don't recognize a signed zero even though only the Degrees
|
|
|
|
value only is typically signed in DMS notation).
|
|
|
|
.TP
|
|
|
|
.B e, dec2dmmm 'Dec Deg'
|
|
|
|
Returns 'Degrees' 'Minutes' 'S/W'.
|
|
|
|
.sp
|
|
|
|
Values are as in dmmm2dec above.
|
|
|
|
.TP
|
|
|
|
.B B, qrb 'Lon 1' 'Lat 1' 'Lon 2' 'Lat 2'
|
|
|
|
Returns 'Distance' 'Azimuth' where Distance is in km and Azimuth is in degrees.
|
|
|
|
.sp
|
|
|
|
All Lon/Lat values are signed floating point numbers.
|
|
|
|
.TP
|
|
|
|
.B A, a_sp2a_lp 'Short Path Deg'
|
|
|
|
Returns 'Long Path Deg' or -RIG_EINVAL upon input error..
|
|
|
|
.sp
|
|
|
|
Both are floating point values within the range 0.00 to 360.00.
|
|
|
|
.TP
|
|
|
|
.B a, d_sp2d_lp 'Short Path km'
|
|
|
|
Returns 'Long Path km'.
|
|
|
|
.sp
|
|
|
|
Both are floating point values.
|
2008-09-12 22:55:10 +00:00
|
|
|
.SH PROTOCOL
|
2010-02-14 22:18:00 +00:00
|
|
|
\fBDefault Protocol\fP
|
|
|
|
.PP
|
2008-09-12 22:55:10 +00:00
|
|
|
The \fBrotctld\fP protocol is intentionally simple. Commands are entered on
|
|
|
|
a single line with any needed values. In Perl, reliable results are obtained
|
|
|
|
by terminating each command string with a newline character, '\\n'.
|
2010-02-14 22:18:00 +00:00
|
|
|
.sp
|
2008-09-12 22:55:10 +00:00
|
|
|
Example \fIset\fP (Perl code):
|
2010-02-14 22:18:00 +00:00
|
|
|
.sp
|
2008-09-12 22:55:10 +00:00
|
|
|
print $socket "P 135 10\\n";
|
2010-02-14 22:18:00 +00:00
|
|
|
.sp
|
2008-09-12 22:55:10 +00:00
|
|
|
print $socket "\\\\set_pos 135 10\\n"; # escape leading '\\'
|
|
|
|
.PP
|
2010-02-18 00:18:54 +00:00
|
|
|
A one line response will be sent as a reply to \fIset\fP commands,
|
2011-07-09 03:55:54 +00:00
|
|
|
"RPRT \fIx\fP\\n" where \fIx\fP is the Hamlib error code with '0'
|
2010-02-18 00:18:54 +00:00
|
|
|
indicating success of the command.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
Responses from \fBrotctld\fP \fIget\fP commands are text values and match the
|
|
|
|
same tokens used in the \fIset\fP commands. Each value is returned on its own
|
2011-07-09 03:55:54 +00:00
|
|
|
line. On error the string "RPRT \fIx\fP\\n" is returned where \fIx\fP is the
|
2010-02-18 00:18:54 +00:00
|
|
|
Hamlib error code.
|
2010-02-14 22:18:00 +00:00
|
|
|
.sp
|
2008-09-12 22:55:10 +00:00
|
|
|
Example \fIget\fP (Perl code):
|
2010-02-14 22:18:00 +00:00
|
|
|
.sp
|
2008-09-12 22:55:10 +00:00
|
|
|
print $socket "p\\n";
|
2010-02-18 00:18:54 +00:00
|
|
|
.br
|
2008-09-12 22:55:10 +00:00
|
|
|
"135"
|
|
|
|
.br
|
|
|
|
"10"
|
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
Most \fIget\fP functions return one to three values. A notable exception is
|
|
|
|
the \fI\\dump_caps\fP function which returns many lines of key:value pairs.
|
|
|
|
.PP
|
|
|
|
This protocol is primarily used by the \fINET rotctl\fP (rotctl model 2) backend
|
2011-06-21 18:42:43 +00:00
|
|
|
which allows applications already written for Hamlib's C API to take advantage
|
|
|
|
of \fBrotctld\fP without the need of rewriting application code. An
|
|
|
|
application's user can select rotor model 2 ("NET rotctl") and then set
|
|
|
|
rot_pathname to "localhost:4533" or other network host:port.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
|
|
|
\fBExtended Response Protocol\fP
|
|
|
|
.PP
|
|
|
|
An \fIEXPERIMENTAL\fP Extended Response protocol has been introduced into
|
|
|
|
\fBrotctld\fP as of February 10, 2010. This protocol adds several rules to the
|
2010-02-18 00:18:54 +00:00
|
|
|
strings returned by \fBrotctld\fP and adds a rule for the command syntax.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
|
|
|
1. The command received by \fBrotctld\fP is echoed with its long command name
|
|
|
|
followed by the value(s) (if any) received from the client terminated by the
|
2010-02-18 00:18:54 +00:00
|
|
|
specified response separator as the first record of the response.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
2011-07-09 03:55:54 +00:00
|
|
|
2. The last record of each block is the string "RPRT \fIx\fP\\n" where \fIx\fP
|
2011-06-21 18:42:43 +00:00
|
|
|
is the numeric return value of the Hamlib backend function that was called by
|
|
|
|
the command.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
|
|
|
3. Any records consisting of data values returned by the rotor backend are
|
|
|
|
prepended by a string immediately followed by a colon then a space and then the
|
2011-06-21 18:42:43 +00:00
|
|
|
value terminated by the response separator. e.g. "Azimuth: 90.000000\\n" when
|
|
|
|
the command was prepended by '+'.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
|
|
|
4. All commands received will be acknowledged by \fBrotctld\fP with records from
|
|
|
|
rules 1 and 2. Records from rule 3 are only returned when data values must be
|
|
|
|
returned to the client.
|
|
|
|
.PP
|
|
|
|
An example response to a \fI+P\fP command (note the prepended '+'):
|
2010-02-18 00:18:54 +00:00
|
|
|
.sp
|
|
|
|
$ echo "+P 90 45" | nc -w 1 localhost 4533
|
2010-02-14 22:18:00 +00:00
|
|
|
.br
|
|
|
|
set_pos: 90 45
|
|
|
|
.br
|
|
|
|
RPRT 0
|
|
|
|
.PP
|
|
|
|
In this case the long command name and values are returned on the first line and
|
|
|
|
the second line contains the end of block marker and the numeric rig backend
|
|
|
|
return value indicating success.
|
|
|
|
.PP
|
|
|
|
An example response to a \fI+\\get_pos\fP query:
|
2010-02-18 00:18:54 +00:00
|
|
|
.sp
|
|
|
|
$ echo "+\\get_pos" | nc -w 1 localhost 4533
|
2010-02-14 22:18:00 +00:00
|
|
|
.br
|
|
|
|
get_pos:
|
|
|
|
.br
|
|
|
|
Azimuth: 90.000000
|
|
|
|
.br
|
|
|
|
Elevation: 45.000000
|
|
|
|
.br
|
|
|
|
RPRT 0
|
|
|
|
.PP
|
|
|
|
In this case, as no value is passed to \fBrotctld\fP, the first line consists
|
|
|
|
only of the long command name. The final line shows that the command was
|
|
|
|
processed successfully by the rotor backend.
|
|
|
|
.PP
|
|
|
|
Invoking the Extended Response protocol requires prepending a command with a
|
|
|
|
punctuation character. As shown in the examples above, prepending a '+'
|
|
|
|
character to the command results in the responses being separated by a newline
|
|
|
|
character ('\\n'). Any other punctuation character recognized by the C
|
|
|
|
\fIispunct()\fP function except '\\', '?', or '_' will cause that character to
|
|
|
|
become the response separator and the entire response will be on one line.
|
|
|
|
.PP
|
2010-02-18 00:18:54 +00:00
|
|
|
Separator character summary:
|
|
|
|
.TP
|
|
|
|
.B '+'
|
|
|
|
.br
|
|
|
|
Each record of the response is appended with a newline ('\\n').
|
|
|
|
.TP
|
|
|
|
.B ';', '|', or ','
|
|
|
|
.br
|
|
|
|
Each record of the response is appended by the given character resulting in
|
|
|
|
entire response on one line.
|
|
|
|
.sp
|
|
|
|
Common record separators for text representations of spreadsheet data, etc.
|
|
|
|
.TP
|
|
|
|
.B '?'
|
|
|
|
.br
|
|
|
|
Reserved for 'help' in rotctl short command
|
|
|
|
.TP
|
|
|
|
.B '_'
|
|
|
|
.br
|
|
|
|
Reserved for \\get_info short command
|
2010-03-01 22:37:06 +00:00
|
|
|
.TP
|
|
|
|
.B '#'
|
|
|
|
.br
|
|
|
|
Reserved for comments when reading a command file script
|
2010-02-18 00:18:54 +00:00
|
|
|
.sp
|
|
|
|
Other punctuation characters have not been tested! Use at your own risk.
|
|
|
|
.PP
|
2010-02-14 22:18:00 +00:00
|
|
|
For example, invoking a \fI;\\get_pos\fP query with a leading ';' returns:
|
|
|
|
.sp
|
|
|
|
get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0
|
|
|
|
.sp
|
|
|
|
Or, using the pipe character '|' returns:
|
|
|
|
.sp
|
|
|
|
get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0
|
|
|
|
.sp
|
|
|
|
And a \\set_pos command prepended with a '|' returns:
|
|
|
|
.sp
|
|
|
|
set_pos: 135 22.5|RPRT 0
|
|
|
|
.PP
|
|
|
|
Such a format will allow reading a response as a single event using a prefered
|
|
|
|
response separator. Other punctuation characters have not been tested!
|
|
|
|
.PP
|
2011-06-21 18:42:43 +00:00
|
|
|
All commands with the exception of \fI\\set_conf\fP have been tested with the
|
2010-02-14 22:18:00 +00:00
|
|
|
Extended Response protocol and the included \fBtestrotctld.pl\fP script.
|
|
|
|
.PP
|
|
|
|
.SH EXAMPLES
|
|
|
|
Start \fBrotctld\fP for a Ham IV rotor with the RotorEZ installed using a
|
|
|
|
USB-to-serial adapter and backgrounding:
|
|
|
|
.sp
|
|
|
|
$ rotctld -m 401 -r /dev/ttyUSB1 &
|
|
|
|
.sp
|
2011-06-21 18:42:43 +00:00
|
|
|
Start \fBrotctld\fP for RotorEZ using COM2 on Win32:
|
|
|
|
.sp
|
|
|
|
$ rotctl -m 401 -r COM2
|
|
|
|
.sp
|
2010-02-14 22:18:00 +00:00
|
|
|
Connect to the already running \fBrotctld\fP, and set position to
|
|
|
|
135.0 degrees azimuth and 30.0 degrees elevation with a 1 second read timeout:
|
|
|
|
.sp
|
|
|
|
$ echo "\\set_pos 135.0 30.0" | nc -w 1 localhost 4533
|
|
|
|
.sp
|
|
|
|
Connect to a running \fBrotctld\fP with \fBrotctl\fP on the local host:
|
|
|
|
.sp
|
|
|
|
$ rotctl -m2
|
2008-09-12 22:55:10 +00:00
|
|
|
.SH DIAGNOSTICS
|
|
|
|
The \fB-v\fP, \fB--version\fP option allows different levels of diagnostics
|
2010-02-14 22:18:00 +00:00
|
|
|
to be output to \fBstderr\fP and correspond to -v for BUG, -vv for ERR,
|
|
|
|
-vvv for WARN, -vvvv for VERBOSE, or -vvvvv for TRACE.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
|
|
|
A given verbose level is useful for providing needed debugging information to
|
|
|
|
the email address below. For example, TRACE output shows all of the values
|
|
|
|
sent to and received from the rotator which is very useful for rotator backend
|
2010-02-14 22:18:00 +00:00
|
|
|
library development and may be requested by the developers. See the
|
|
|
|
\fBREADME.betatester\fP and \fBREADME.developer\fP files for more information.
|
2008-09-12 22:55:10 +00:00
|
|
|
.SH SECURITY
|
2010-02-14 22:18:00 +00:00
|
|
|
No authentication whatsoever; DO NOT leave this TCP port open wide to the
|
|
|
|
Internet. Please ask if stronger security is needed or consider using an
|
|
|
|
SSH tunnel.
|
2010-02-18 00:18:54 +00:00
|
|
|
.PP
|
|
|
|
As \fBrotctld\fP does not need any greater permissions than \fBrotctl\fP, it
|
|
|
|
is advisable to not start \fBrotctld\fP as \fIroot\fP or another system user
|
|
|
|
account in order to limit any vulnerability.
|
2008-09-12 22:55:10 +00:00
|
|
|
.SH BUGS
|
|
|
|
The daemon is not detaching and backgrounding itself.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
2008-09-12 22:55:10 +00:00
|
|
|
Much testing needs to be done.
|
|
|
|
.SH REPORTING BUGS
|
|
|
|
Report bugs to <hamlib-developer@lists.sourceforge.net>.
|
2010-02-14 22:18:00 +00:00
|
|
|
.PP
|
2008-09-12 22:55:10 +00:00
|
|
|
We are already aware of the bugs in the previous section :-)
|
|
|
|
.SH AUTHORS
|
2010-02-14 22:18:00 +00:00
|
|
|
Written by Stephane Fillod, Nate Bargmann, and the Hamlib Group
|
2010-02-18 00:18:54 +00:00
|
|
|
.PP
|
2008-09-12 22:55:10 +00:00
|
|
|
<http://www.hamlib.org>.
|
|
|
|
.SH COPYRIGHT
|
2010-02-14 22:18:00 +00:00
|
|
|
Copyright \(co 2000-2009 Stephane Fillod
|
|
|
|
.br
|
2012-01-08 02:36:18 +00:00
|
|
|
Copyright \(co 2011-2012 Nate Bargmann
|
2010-02-14 22:18:00 +00:00
|
|
|
.br
|
|
|
|
Copyright \(co 2000-2009 the Hamlib Group.
|
2008-09-12 22:55:10 +00:00
|
|
|
.PP
|
|
|
|
This is free software; see the source for copying conditions.
|
|
|
|
There is NO warranty; not even for MERCHANTABILITY
|
|
|
|
or FITNESS FOR A PARTICULAR PURPOSE.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR rotctl (1),
|
|
|
|
.BR hamlib (3)
|