kopia lustrzana https://github.com/Hamlib/Hamlib
3389 wiersze
104 KiB
Plaintext
3389 wiersze
104 KiB
Plaintext
Included with the Hamlib distribution are several utility programs.
|
|
Besides providing a way for developers to test new code and bug fixes,
|
|
the programs also offer a reference implementation for interfacing to
|
|
the Hamlib library functions both through the C API and offering a
|
|
network accessible API.
|
|
|
|
This chapter focuses on the two test programs, @command{rigctl} for
|
|
testing radio back ends and @command{rotctl} for testing rotor back
|
|
ends and the two network daemons, @command{rigctld} and
|
|
@command{rotcltd} for radio and rotor access via network sockets.
|
|
|
|
|
|
@menu
|
|
* rigctl::
|
|
* rotctl::
|
|
* rigctld::
|
|
* rotctld::
|
|
@end menu
|
|
|
|
@node rigctl
|
|
@section @command{rigctl}
|
|
@cindex rigctl
|
|
|
|
@command{rigctl} is the most frequently used Hamlib utility. As the
|
|
other utilities share many of the same characteristics, much of the
|
|
introductory information presented in this section is applicable to
|
|
the other utility programs.
|
|
|
|
@menu
|
|
* Introduction to rigctl::
|
|
* rigctl invocation::
|
|
* rigctl command line options::
|
|
* rigctl commands::
|
|
* rigctl readline support::
|
|
@end menu
|
|
|
|
@node Introduction to rigctl
|
|
@subsection Introduction to @command{rigctl}
|
|
@cindex Introduction to @command{rigctl}
|
|
@cindex @command{rigctl}, introduction to
|
|
|
|
Most likely the first of the Hamlib utility programs that is used is
|
|
@command{rigctl}. @command{rigctl} is a character based interactive
|
|
program and a command line program able to set or query a radio's
|
|
value with a single command. @command{rigctl} is invoked from a shell
|
|
command prompt with various options and additional commands.
|
|
|
|
In its most simple use as a @dfn{command line} program,
|
|
@command{rigctl} is used to set frequency and mode by typing commands
|
|
after any @command{rigctl} options:
|
|
|
|
@example
|
|
@kbd{rigctl F 14205000}
|
|
@kbd{rigctl M USB 2400}
|
|
@end example
|
|
|
|
@noindent
|
|
and then query those values:
|
|
|
|
@example
|
|
@kbd{rigctl f}
|
|
@kbd{rigctl m}
|
|
@end example
|
|
|
|
Entering interactive mode is a simple matter of not placing any
|
|
commands after any @command{rigctl} options:
|
|
|
|
@example
|
|
@kbd{rigctl}
|
|
@end example
|
|
|
|
@noindent
|
|
Entering @dfn{interactive mode} allows successive commands to be
|
|
entered without exiting @command{rigctl}. Recent additions to
|
|
@command{rigctl} allow command editing and history recall through use
|
|
of the @url{ http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html,
|
|
Readline} library.
|
|
|
|
Interactive mode is indicated by the spartan prompt:
|
|
|
|
@example
|
|
Rig command:
|
|
@end example
|
|
|
|
@noindent
|
|
Commands are given at the prompt and follow the general rule that
|
|
upper case letters set a value and lower case letters query a value:
|
|
|
|
@example
|
|
Rig command: @kbd{M}
|
|
Mode: @kbd{USB}
|
|
Passband: @kbd{2500}
|
|
|
|
Rig command: @kbd{m}
|
|
Mode: USB
|
|
Passband: 2500
|
|
|
|
Rig command:
|
|
@end example
|
|
|
|
An additional prompt is printed when more information is required by
|
|
the command. For @kbd{M} above, @command{rigctl} prompted for the
|
|
``Mode'' and ``Passband'' values. For @kbd{m} above, @command{rigctl}
|
|
returned the ``Mode'' and ``Passband'' values without further prompts.
|
|
The command prompt is returned after each command invocation.
|
|
|
|
The above examples invoked @command{rigctl} without specifying a radio
|
|
model. This is a feature where the Hamlib internal radio @dfn{dummy} is
|
|
used instead. The dummy radio provides a way to test Hamlib functions
|
|
with out the need for actual radio hardware. However, to develop back
|
|
end capability for a given radio, having the actual radio connected to
|
|
the computer is necessary for debugging.
|
|
|
|
For example, to quickly set frequency on an Elecraft K3:
|
|
|
|
@example
|
|
@kbd{rigctl -m 229 -r /dev/rig F 3900000}
|
|
@end example
|
|
|
|
@noindent
|
|
and to query the frequency and then mode:
|
|
|
|
@example
|
|
@kbd{rigctl -m 229 -r /dev/rig f}
|
|
3900000
|
|
|
|
@kbd{rigctl -m 229 -r /dev/rig m}
|
|
LSB
|
|
2000
|
|
@end example
|
|
|
|
@noindent
|
|
The returned values do not have the prompt strings associated with
|
|
interactive mode as shown above.
|
|
|
|
The @option{-m} option takes a numeric value that corresponds to a
|
|
given radio back end model. The @option{-r} option takes the path to
|
|
the port device on @acronym{POSIX} and the device name on MS Windows.
|
|
|
|
@quotation Note
|
|
A complete list of supported radio models may be seen by use of the
|
|
@option{-l} option:
|
|
|
|
@example
|
|
@kbd{rigctl -l}
|
|
Rig # Mfg Model Version Status
|
|
1 Hamlib Dummy 0.5 Beta
|
|
2 Hamlib NET rigctl 0.3 Beta
|
|
101 Yaesu FT-847 0.5 Beta
|
|
103 Yaesu FT-1000D 0.0.6 Alpha
|
|
.
|
|
.
|
|
.
|
|
2702 Rohde&Schwarz EB200 0.1 Untested
|
|
2801 Philips/Simoco PRM8060 0.1 Alpha
|
|
2901 ADAT www.adat.ch ADT-200A 1.36 Beta
|
|
@end example
|
|
|
|
@noindent
|
|
The list is long so use @kbd{@key{SHIFT}-PageUp}/
|
|
@kbd{@key{SHIFT}-PageDown} on Linux, @kbd{@key{ScrollLock}} then
|
|
@kbd{@key{PageUp}}/@kbd{@key{PageDown}} on Free BSD, or use the
|
|
scrollbar to the virtual terminal window (@command{cmd} window on MS
|
|
Windows) or the output can be piped to '@command{more}' or
|
|
'@command{less}', e.g.@: '@kbd{rigctl -l | more}' to scroll back up
|
|
the list. The list is sorted numerically by model number since Hamlib
|
|
1.2.15.1. Model numbers of a manufacturer/ protocol family are
|
|
grouped together.
|
|
@end quotation
|
|
|
|
@node rigctl invocation
|
|
@subsection @command{rigctl} invocation
|
|
@cindex @command{rigctl} invocation
|
|
@cindex invocation, @command{rigctl}
|
|
|
|
Here are some additional examples for invoking @command{rigctl} for
|
|
various situations.
|
|
|
|
@noindent
|
|
Start @command{rigctl} for a Yaesu FT-920 using a @acronym{USB} to serial
|
|
adapter on Linux in interactive mode:
|
|
|
|
@example
|
|
rigctl -m 114 -r /dev/ttyUSB1
|
|
@end example
|
|
|
|
@noindent
|
|
Start @command{rigctl} for a Yaesu FT-920 using @file{COM1} on MS
|
|
Windows while generating TRACE output to @file{stderr}:
|
|
|
|
@example
|
|
rigctl -m 114 -r COM1 -vvvvv
|
|
@end example
|
|
|
|
@noindent
|
|
Start @command{rigctl} for a Yaesu FT-920 using a @acronym{USB} to
|
|
serial adapter on Linux while setting baud rate and stop bits:
|
|
|
|
@example
|
|
rigctl -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2
|
|
@end example
|
|
|
|
@noindent
|
|
Start @command{rigctl} for an Elecraft K3 using a @acronym{USB} to
|
|
serial adapter on Linux while specifying a command terminator for the
|
|
@command{w} command:
|
|
|
|
@example
|
|
rigctl -m 229 -r /dev/ttyUSB0 -t';'
|
|
@end example
|
|
|
|
@noindent
|
|
Connect to a running @command{rigctld} with radio model 2 (@code{NET
|
|
rigctl}) on the local host and specifying the @acronym{TCP} port,
|
|
setting frequency and mode:
|
|
|
|
@example
|
|
rigctl -m 2 -r localhost:4532 F 7253500 M LSB 0
|
|
@end example
|
|
|
|
@strong{N.B.} On MS Windows @kbd{localhost} may need to be replaced
|
|
with the actual loopback @acronym{IP} address--@kbd{127.0.0.1}--or the
|
|
address passed to @command{rigctld} with the @option{-T} option.
|
|
|
|
@node rigctl command line options
|
|
@subsection @command{rigctl} command line options
|
|
@cindex @command{rigctl} command line options
|
|
@cindex Command line options, @command{rigctl}
|
|
|
|
The @command{rigctl} command line options (not to be confused with
|
|
@command{rigctl} commands) control the action of various features.
|
|
Options consist of both ``short options''--a single hyphen '@kbd{-}'
|
|
followed by a single letter and ``long options''--two hyphens
|
|
'@kbd{--}' followed by several letters often comprising one or more
|
|
words separated by a hyphen.
|
|
|
|
@command{rigctl} accepts the following options:
|
|
|
|
@table @option
|
|
@item -m
|
|
@itemx --model=@var{id}
|
|
Select radio model number. See model list (use @kbd{rigctl -l}).
|
|
|
|
@strong{N.B.} @command{rigctl} (or third party software) will use rig
|
|
model 2 for NET rigctl (@command{rigctld}).
|
|
|
|
@item -r
|
|
@itemx --rig-file=@var{device}
|
|
Use @var{device} as the file name of the port the radio is connected.
|
|
Often a serial port, but could be a USB to serial adapter. Typically
|
|
@file{/dev/ttyS0} , @file{/dev/ttyS1} , @file{/dev/ttyUSB0} , etc.@:
|
|
on Linux or @file{COM1} , @file{COM2} , etc.@: on MS Windows. The
|
|
special string @kbd{uh-rig} may be given to enable micro-ham device
|
|
support.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -p
|
|
@itemx --ptt-file=@var{device}
|
|
Use @var{device} as the file name of the Push-To-Talk device using a
|
|
device file as described above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -d
|
|
@itemx --dcd-file=@var{device}
|
|
Use @var{device} as the file name of the Data Carrier Detect device
|
|
using a device file as described above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -P
|
|
@itemx --ptt-type=@var{type}
|
|
Use @var{type} of Push-To-Talk device. Supported types are
|
|
@code{RIG}, @code{DTR}, @code{RTS}, @code{PARALLEL}, @code{NONE},
|
|
overriding @acronym{PTT} type defined in the rig's backend.
|
|
|
|
Some side effects of this command are that when type is set to
|
|
@code{DTR}, read @acronym{PTT} state comes from Hamlib frontend, not
|
|
read from the radio. When set to @code{NONE}, @acronym{PTT} state
|
|
cannot be read or set even if rig backend supports reading/setting
|
|
@acronym{PTT} status from the rig.
|
|
|
|
@item -D
|
|
@itemx --dcd-type=@var{type}
|
|
Use @var{type} of Data Carrier Detect device. Supported types are
|
|
@code{RIG} (@acronym{CAT} command), @code{DSR}, @code{CTS}, @code{CD},
|
|
@code{PARALLEL}, @code{NONE}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -s
|
|
@itemx --serial-speed=@var{baud}
|
|
Set serial speed to @var{baud} rate. Uses @strong{maximum} serial
|
|
speed from rig backend capabilities (set by @option{-m} above) as the
|
|
default.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -c
|
|
@itemx --civaddr=@var{id}
|
|
Use @var{id} as the @acronym{CI-V} address to communicate with the
|
|
rig. Only useful for Icom radios and those using the Icom protocol.
|
|
|
|
@strong{N.B.} The @var{id} is in decimal notation, unless prefixed by
|
|
@code{0x}, in which case it is a hexadecimal value.
|
|
|
|
@item -t
|
|
@itemx --send-cmd-term=@var{char}
|
|
Change the termination @var{char} for text protocol when using the
|
|
@code{send_cmd} command. The default value is @code{<CR>}
|
|
(@code{0x0d}). Non @acronym{ASCII} printable characters can be
|
|
specified as an @acronym{ASCII} number, in hexadecimal format,
|
|
prepended with @code{0x}. You may pass an empty string for no
|
|
termination char. The string '@code{-1}' tells @command{rigctl} to
|
|
switch to binary protocol. See the @code{send_cmd} command for further
|
|
explanation.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -L
|
|
@itemx --show-conf
|
|
List all config parameters for the radio defined with @option{-m}
|
|
above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -C
|
|
@itemx --set-conf=@var{parm}=@var{val}[,@var{parm}=@var{val},@dots{}]
|
|
Set config parameter. e.g.@: @code{stop_bits=2}
|
|
|
|
Use @option{-L} option for a list.
|
|
|
|
@item -l
|
|
@itemx --list
|
|
List all model numbers defined in Hamlib and exit. As of 1.2.15.1 the
|
|
list is sorted by model number.
|
|
|
|
@strong{N.B.} In Linux the list can be scrolled back using
|
|
@kbd{@key{SHIFT}-PageUp}/ @kbd{@key{SHIFT}-PageDown}, or using the
|
|
scrollbars of a virtual terminal in X or the @command{cmd} window in
|
|
MS Windows. The output can be piped to '@command{more}' or
|
|
'@command{less}', e.g.@: '@kbd{rigctl -l | more}'.
|
|
|
|
@item -u
|
|
@itemx --dump-caps
|
|
Dump capabilities for the radio defined with @option{-m} above and
|
|
exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -o
|
|
@itemx --vfo
|
|
Set vfo mode, requiring an extra @acronym{VFO} argument in front of
|
|
each appropriate command (except @command{set_vfo}!). Otherwise,
|
|
@code{currVFO} is assumed when this option is not set and an extra VFO
|
|
argument is not used. See @command{chk_vfo} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -n
|
|
@itemx --no-restore-ai
|
|
On exit @command{rigctl} restores the state of auto information (AI)
|
|
on the controlled rig. If this is not desired, for example if you are
|
|
using @command{rigctl} to turn AI mode on or off, pass this option.
|
|
|
|
@item -i
|
|
@itemx --read-history
|
|
Read previously saved command and argument history from a file
|
|
(default '@file{$HOME/.rigctl_history}') for the current session.
|
|
Available when @command{rigctl} is built with Readline support.
|
|
|
|
@strong{N.B.} To read a history file stored in another directory, set
|
|
the @env{RIGCTL_HIST_DIR} environment variable, e.g.@:
|
|
'@kbd{RIGCTL_HIST_DIR=$HOME/tmp rigctl -i}'. When
|
|
@env{RIGCTL_HIST_DIR} is not set, the value of @env{HOME} is used.
|
|
|
|
@item -I
|
|
@itemx --save-history
|
|
Write current session (and previously saved session(s) if @option{-i}
|
|
option is also given) command and argument history to a file (default
|
|
'@file{$HOME/.rigctl_history}') at the end of the current session.
|
|
Complete commands with arguments are saved as a single line to be
|
|
recalled and used or edited. Available when @command{rigctl} is built
|
|
with Readline support.
|
|
|
|
To write a history file in another directory, set the
|
|
@env{RIGCTL_HIST_DIR} environment variable, e.g.@:
|
|
'@kbd{RIGCTL_HIST_DIR=$HOME/tmp rigctl -I}'. When
|
|
@env{RIGCTL_HIST_DIR} is not set, the value of @env{HOME} is used.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set verbose mode level, cumulative i.e.@: @option{-vvvvv} sets maximum
|
|
debugging output to @file{stderr}.
|
|
|
|
Five different levels of diagnostics can be output to @file{stderr}
|
|
and correspond to @option{-v} for @code{BUG}, @option{-vv} for
|
|
@code{ERR}, @option{-vvv} for @code{WARN}, @option{-vvvv} for
|
|
@code{VERBOSE}, or @option{-vvvvv} for @code{TRACE}. Back end authors
|
|
will use the verbose facility to print critical values useful for
|
|
testing and will often ask for this output in response to a request
|
|
for help.
|
|
|
|
@item -Z
|
|
@itemx --debug-time-stamps
|
|
Enable time stamps on debug output.
|
|
|
|
@item -h
|
|
@itemx --help
|
|
Show summary of these options and exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show version of @command{rigctl} and exit.
|
|
|
|
@end table
|
|
|
|
@quotation Note
|
|
Some options may not be implemented by a given backend and will return
|
|
an error. This is most likely to occur with the @option{--set-conf}
|
|
and @option{--show-conf} options.
|
|
@end quotation
|
|
|
|
@node rigctl commands
|
|
@subsection @command{rigctl} commands
|
|
@cindex @command{rigctl} commands
|
|
@cindex commands, @command{rigctl}
|
|
|
|
Commands can be entered either as a single char, or as a long command
|
|
name. Basically, the commands do not take a dash in front of them on
|
|
the command line, as the options do. They may be typed in when in
|
|
interactive mode or provided as argument(s) in command line interface
|
|
mode. In interactive mode commands and their arguments may be entered
|
|
on a single line:
|
|
|
|
@example
|
|
Rig command: M LSB 2400
|
|
@end example
|
|
|
|
@noindent
|
|
or singly and @command{rigctl} will prompt for any needed values.
|
|
|
|
Since most of the Hamlib operations have a ``set'' and a ``get''
|
|
method, in general an upper case letter will be used for set methods
|
|
whereas the corresponding lower case letter refers to the get method.
|
|
Each operation also has a long name; prepend a backslash @kbd{\} to
|
|
enter a long command name.
|
|
|
|
@quotation
|
|
Example: Use @kbd{\dump_caps} to see what this radio can do.
|
|
@end quotation
|
|
|
|
@noindent
|
|
Be aware that the backend for the radio to be controlled, or the radio
|
|
itself may not support some commands. In that case, the operation will
|
|
fail with a Hamlib error message.
|
|
|
|
Here is a summary of the supported commands:
|
|
|
|
@itemize
|
|
@item
|
|
Command short name is followed by the long name which is followed by
|
|
any variable names.
|
|
|
|
@item
|
|
Some short commands are noted as hexadecimal digits due to the
|
|
limitation of upper and lower case letters available. Use the
|
|
associated long command name instead.
|
|
|
|
@item
|
|
While a comma is used to separate variable names in this document,
|
|
they are not part of the command syntax used by @command{rigctl}. Use
|
|
a space to separate values.
|
|
|
|
@item
|
|
In the case of ``set'' commands the variable @var{name} is replaced by
|
|
the value in the description.
|
|
|
|
@item
|
|
In the case of ``get'' commands the variable @var{name} is the key
|
|
name of the value returned.
|
|
|
|
@end itemize
|
|
|
|
@table @command
|
|
@item q
|
|
Exit @command{rigctl} in interactive mode (@kbd{q} is not case
|
|
sensitive).
|
|
|
|
When @command{rigctl} is controlling the rig directly, will close the
|
|
rig back end and port. When @command{rigctl} is connected to
|
|
@command{rigctld} (rig model 2), the @acronym{TCP/IP} connection to
|
|
@command{rigctld} is closed and @command{rigctld} remains running,
|
|
available for another @acronym{TCP/IP} network connection.
|
|
|
|
@item F, set_freq @var{Frequency}
|
|
Set @var{Frequency}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item f, get_freq
|
|
Get @var{Frequency}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item M, set_mode @var{Mode}, @var{Passband}
|
|
Set @var{Mode} to one of: @code{USB}, @code{LSB}, @code{CW},
|
|
@code{CWR}, @code{RTTY}, @code{RTTYR}, @code{AM}, @code{FM},
|
|
@code{WFM}, @code{AMS}, @code{PKTLSB}, @code{PKTUSB}, @code{PKTFM},
|
|
@code{ECSSUSB}, @code{ECSSLSB}, @code{FAX}, @code{SAM}, @code{SAL},
|
|
@code{SAH}, @code{DSB}.
|
|
|
|
Set @var{Passband} frequency in Hertz, or @code{0} for the Hamlib
|
|
backend default. A value of @code{-1} may be passed which leaves the
|
|
rig passband unchanged from the current or default value for the mode
|
|
as defined by the rig.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument
|
|
instead of @var{Mode} will return a space separated list of radio
|
|
backend supported Modes. Use this to determine the supported Modes of
|
|
a given radio backend.
|
|
|
|
@item m, get_mode
|
|
Get @var{Mode}, @var{Passband}.
|
|
|
|
Returns Mode as a string from @command{set_mode} above and Passband
|
|
frequency in Hertz.
|
|
|
|
@item V, set_vfo @var{VFO}
|
|
Set @var{VFO} to one of: @code{VFOA}, @code{VFOB}, @code{VFOC},
|
|
@code{currVFO}, @code{VFO}, @code{MEM}, @code{Main}, @code{Sub},
|
|
@code{TX}, @code{RX}.
|
|
|
|
In @acronym{VFO} mode only a single @acronym{VFO} parameter is
|
|
required.
|
|
|
|
@item v, get_vfo
|
|
Get current @var{VFO}.
|
|
|
|
Returns @acronym{VFO} as a string from @command{set_vfo} above.
|
|
|
|
@item J, set_rit @var{RIT}
|
|
Set @var{RIT}, in Hertz, can be a positive or negative value.
|
|
|
|
A value of @code{0} resets @acronym{RIT} and @emph{should} turn
|
|
@acronym{RIT} off. If not, file a bug report against the Hamlib
|
|
backend.
|
|
|
|
@strong{N.B.} This functionality is under transition and in the future
|
|
will need to be activated with the @command{set_func} command.
|
|
|
|
@item j, get_rit
|
|
Get @var{RIT}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item Z, set_xit @var{XIT}
|
|
Set @var{XIT}, in Hertz, can be a positive or negative value.
|
|
|
|
A value of @code{0} resets @acronym{XIT} and @emph{should} turn
|
|
@acronym{XIT} off. If not, file a bug report against the Hamlib
|
|
backend.
|
|
|
|
@strong{N.B.} This functionality is under transition and in the future
|
|
will need to be activated with the @command{set_func} command.
|
|
|
|
@item z, get_xit
|
|
Get @var{XIT}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item T, set_ptt @var{PTT}
|
|
Set @var{PTT} to one of: @code{0} (RX), @code{1} (TX), @code{2} (TX
|
|
mic), @code{3} (TX data).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item t, get_ptt
|
|
Get @var{PTT} status.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x8b, get_dcd
|
|
Get @var{DCD} (squelch) status, @code{0} (Closed) or @code{1} (Open)
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item R, set_rptr_shift @var{Rptr Shift}
|
|
Set @var{Rptr Shift}: @code{+}, @code{-} or something else for none.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item r, get_rptr_shift
|
|
Get @var{Rptr Shift}. Returns @code{+}, @code{-} or @code{None}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item O, set_rptr_offs @var{Rptr Offset}
|
|
Set @var{Rptr Offset}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item o, get_rptr_offs
|
|
Get @var{Rptr Offset}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item C, set_ctcss_tone @var{CTCSS Tone}
|
|
Set @var{CTCSS Tone}, in tenths of Hertz.
|
|
|
|
@acronym{CTCSS},
|
|
@url{http://en.wikipedia.org/wiki/Continuous_Tone-Coded_Squelch_System,
|
|
@dfn{Continuous Tone Coded Squelch System}}, is a method used to
|
|
reduce the annoyance of listening to other users on a shared two-way
|
|
communications radio channel by imposing a tone on the transmitted
|
|
signal. Also known as @dfn{subaudible tone} and @acronym{PL},
|
|
@dfn{Private Line}.
|
|
|
|
@item c, get_ctcss_tone
|
|
Get @var{CTCSS Tone}, in tenths of Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item D, set_dcs_code @var{DCS Code}
|
|
Set @var{DCS Code}.
|
|
|
|
@acronym{DCS},
|
|
@url{http://en.wikipedia.org/wiki/Digital-Coded_Squelch#DCS,
|
|
@dfn{Digital-Coded Squelch}} is a digital version of @acronym{CTCSS}
|
|
which imposes a digital code on the transmitted signal.
|
|
|
|
@item d, get_dcs_code
|
|
Get @var{DCS Code}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x90, set_ctcss_sql @var{CTCSS Sql}
|
|
Set @var{CTCSS Sql} tone, in tenths of Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x91, get_ctcss_sql
|
|
Get @var{CTCSS Sql} tone, in tenths of Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x92, set_dcs_sql @var{DCS Sql}
|
|
Set @var{DCS Sql} code.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x93, get_dcs_sql
|
|
Get @var{DCS Sql} code.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item I, set_split_freq @var{Tx Frequency}
|
|
Set @var{TX Frequency}, in Hertz for ``split'' frequency operation.
|
|
|
|
See also @command{set_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item i, get_split_freq
|
|
Get @var{TX Frequency}, in Hertz for ``split'' frequency operation.
|
|
|
|
See also @command{get_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item X, set_split_mode @var{TX Mode}, @var{TX Passband}
|
|
Set @var{TX Mode} to one of: @code{AM}, @code{FM}, @code{CW},
|
|
@code{CWR}, @code{USB}, @code{LSB}, @code{RTTY}, @code{RTTYR},
|
|
@code{WFM}, @code{AMS}, @code{PKTLSB}, @code{PKTUSB}, @code{PKTFM},
|
|
@code{ECSSUSB}, @code{ECSSLSB}, @code{FAX}, @code{SAM}, @code{SAL},
|
|
@code{SAH}, @code{DSB}.
|
|
|
|
The @var{TX Passband} is the exact passband frequency in Hertz, or
|
|
@code{0} for the Hamlib backend default. A value of @code{-1} may be
|
|
passed which leaves the rig passband unchanged from the current or
|
|
default value for the mode as defined by the rig.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{TX Mode} will return a space separated list of radio backend
|
|
supported TX Modes. Use this to determine the supported TX Modes of a
|
|
given radio backend.
|
|
|
|
See also @command{set_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item x, get_split_mode
|
|
Get @var{TX Mode}, @var{TX Passband}.
|
|
|
|
Returns TX mode as a string from @command{set_split_mode} above and TX
|
|
passband in Hz.
|
|
|
|
See also @command{get_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item K, set_split_freq_mode @var{Tx Frequency}, @var{TX Mode}, @var{TX Passband}
|
|
Set @var{TX Frequency}, in Hertz for ``split'' frequency operation.
|
|
Set @var{TX Mode} to one of: @code{AM}, @code{FM}, @code{CW},
|
|
@code{CWR}, @code{USB}, @code{LSB}, @code{RTTY}, @code{RTTYR},
|
|
@code{WFM}, @code{AMS}, @code{PKTLSB}, @code{PKTUSB}, @code{PKTFM},
|
|
@code{ECSSUSB}, @code{ECSSLSB}, @code{FAX}, @code{SAM}, @code{SAL},
|
|
@code{SAH}, @code{DSB}.
|
|
|
|
The @var{TX Passband} is the exact passband frequency in Hertz, or
|
|
@code{0} for the Hamlib backend default. A value of @code{-1} may be
|
|
passed which leaves the rig passband unchanged from the current or
|
|
default value for the mode as defined by the rig.
|
|
|
|
This is a convenience function that combines the effect of
|
|
@command{set_split_freq} and @command{set_split_mode}. It should be
|
|
used when both are required since it allows the back end to optimize
|
|
the operations. For example on many Icom rigs the current VFO must be
|
|
changed temporarily while executing these commands and that can
|
|
disrupt receive or transmit, using this function may minimize that
|
|
disruption.
|
|
|
|
See also @command{set_split_freq} and @command{set_split_mode} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item k, get_split_freq_mode
|
|
Get @var{TX Frequency}, in Hertz for ``split'' frequency operation
|
|
along with The @var{TX Mode} as a string from @command{set_split_mode}
|
|
above and @var{TX Passband} in Hz.
|
|
|
|
This is a convenience function that combines the effect of
|
|
@command{get_split_freq} and @command{get_split_mode}. It should be
|
|
used when both are required since it allows the back end to optimize
|
|
the operations. For example on many Icom rigs the current VFO must be
|
|
changed temporarily while executing these commands and that can
|
|
disrupt receive or transmit, using this function may minimize that
|
|
disruption.
|
|
|
|
See also @command{get_split_freq} and @command{get_split_mode} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item S, set_split_vfo @var{Split}, @var{TX VFO}
|
|
Set @var{Split} mode, @code{0} (off) or @code{1} (on), and @var{TX VFO}
|
|
from @command{set_vfo} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item s, get_split_vfo
|
|
Get @var{Split} mode, @code{0} (off) or @code{1} (on), and @var{TX VFO}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item N, set_ts @var{Tuning Step}
|
|
Set @var{Tuning Step}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item n, get_ts
|
|
Get @var{Tuning Step}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item U, set_func @var{Func}, @var{Func Status}
|
|
Set @var{Func}, @var{Func Status}.
|
|
|
|
@var{Func} is one of: @code{FAGC}, @code{NB}, @code{COMP}, @code{VOX},
|
|
@code{TONE}, @code{TSQL}, @code{SBKIN}, @code{FBKIN}, @code{ANF},
|
|
@code{NR}, @code{AIP}, @code{APF}, @code{MON}, @code{MN}, @code{RF},
|
|
@code{ARO}, @code{LOCK}, @code{MUTE}, @code{VSC}, @code{REV},
|
|
@code{SQL}, @code{ABM}, @code{BC}, @code{MBC}, @code{RIT}, @code{AFC},
|
|
@code{SATMODE}, @code{SCOPE}, @code{RESUME}, @code{TBURST},
|
|
@code{TUNER}, @code{XIT}.
|
|
|
|
Func Status argument is @code{1} for ``activate'', @code{0} for
|
|
``de-activate'', much as TRUE/FALSE definitions in the C/C++ languages
|
|
(true is non-zero and false is zero).
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Func} will return a space separated list of radio backend
|
|
supported ``set'' functions. Use this to determine the supported
|
|
functions of a given radio backend.
|
|
|
|
@item u, get_func @var{Func}
|
|
Get @var{Func Status}.
|
|
|
|
Returns @var{Func Status} as a non null value for the @var{Func} passed.
|
|
@var{Func} is a token from the list in @command{set_func} above.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Func} will return a space separated list of radio backend
|
|
supported ``get'' functions. Use this to determine the supported
|
|
functions of a given radio backend.
|
|
|
|
@item L, set_level @var{Level}, @var{Level Value}
|
|
Set @var{Level}, @var{Level Value}.
|
|
|
|
@var{Level} is one of: @code{PREAMP}, @code{ATT}, @code{VOX}, @code{AF},
|
|
@code{RF}, @code{SQL}, @code{IF}, @code{APF}, @code{NR}, @code{PBT_IN},
|
|
@code{PBT_OUT}, @code{CWPITCH}, @code{RFPOWER}, @code{MICGAIN},
|
|
@code{KEYSPD}, @code{NOTCHF}, @code{COMP}, @code{AGC}(@code{0}:OFF,
|
|
@code{1}:SUPERFAST, @code{2}:FAST, @code{3}:SLOW, @code{4}:USER,
|
|
@code{5}:MEDIUM, @code{6}:AUTO), @code{BKINDL}, @code{BAL},
|
|
@code{METER}, @code{VOXGAIN}, @code{ANTIVOX}, @code{SLOPE_LOW},
|
|
@code{SLOPE_HIGH}, @code{RAWSTR}, @code{SWR}, @code{ALC},
|
|
@code{STRENGTH}.
|
|
|
|
The @var{Level Value} can be a float or an integer.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Level} will return a space separated list of radio backend
|
|
supported ``set'' levels. Use this to determine the supported levels of a
|
|
given radio backend.
|
|
|
|
@item l, get_level @var{Level}
|
|
Get @var{Level Value}.
|
|
|
|
Returns @var{Level Value} as a float or integer for the @var{Level}
|
|
passed. @var{Level} is a token from the list in @command{set_level}
|
|
above.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Level} will return a space separated list of radio backend
|
|
supported ``get'' levels. Use this to determine the supported levels of a
|
|
given radio backend.
|
|
|
|
@item P, set_parm @var{Parm}, @var{Parm Value}
|
|
Set @var{Parm}, @var{Parm Value}
|
|
|
|
@var{Parm} is one of: @code{ANN}, @code{APO}, @code{BACKLIGHT},
|
|
@code{BEEP}, @code{TIME}, @code{BAT}, @code{KEYLIGHT}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Parm} will return a space separated list of radio backend
|
|
supported ``set'' parameters. Use this to determine the supported
|
|
parameters of a given radio backend.
|
|
|
|
@item p, get_parm @var{Parm}
|
|
Get @var{Parm Value}.
|
|
|
|
Returns @var{Parm Value} as a float or integer for the @var{Parm}
|
|
passed. @var{Parm} is a token from the list in @command{set_parm}
|
|
above.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Parm} will return a space separated list of radio backend
|
|
supported ``get'' parameters. Use this to determine the supported
|
|
parameters of a given radio backend.
|
|
|
|
@item B, set_bank @var{Bank}
|
|
Set @var{Bank}. Sets the current memory bank number.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item E, set_mem @var{Memory#}
|
|
Set @var{Memory#} channel number.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item e, get_mem
|
|
Get @var{Memory#} channel number.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item G, vfo_op @var{Mem/VFO Op}
|
|
Perform @var{Mem/VFO Op}.
|
|
|
|
@var{Mem/VFO Op}eration is one of: @code{CPY}, @code{XCHG},
|
|
@code{FROM_VFO}, @code{TO_VFO}, @code{MCL}, @code{UP}, @code{DOWN},
|
|
@code{BAND_UP}, @code{BAND_DOWN}, @code{LEFT}, @code{RIGHT},
|
|
@code{TUNE}, @code{TOGGLE}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Mem/VFO Op} will return a space separated list of radio backend
|
|
supported ``set'' Mem/VFO Ops. Use this to determine the supported Mem/VFO
|
|
Ops of a given radio backend.
|
|
|
|
@item g, scan @var{Scan Fct}, @var{Scan Channel}
|
|
Perform @var{Scan Fct} @var{Scan Channel}.
|
|
|
|
Scan function/channel is one of: @code{STOP}, @code{MEM}, @code{SLCT},
|
|
@code{PRIO}, @code{PROG}, @code{DELTA}, @code{VFO}, @code{PLT}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Scan Fct} will return a space separated list of radio backend
|
|
supported Scan Functions. Use this to determine the supported Scan
|
|
Functions of a given radio backend.
|
|
|
|
@item H, set_channel @var{Channel}
|
|
Set memory @var{Channel} data. Not implemented yet.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item h, get_channel
|
|
Get memory @var{Channel} data. Not implemented yet.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item A, set_trn @var{Transceive}
|
|
Set @var{Transceive} mode (reporting event): @code{OFF}, @code{RIG},
|
|
@code{POLL}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Transceive} will return a space separated list of radio backend
|
|
supported Scan Transceive modes. Use this to determine the supported
|
|
Transceive modes of a given radio backend.
|
|
|
|
@item a, get_trn
|
|
Get @var{Transceive} mode (reporting event) as in @command{set_trn}
|
|
above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item Y, set_ant @var{Antenna}
|
|
Set @var{Antenna} number (@code{0}, @code{1}, @code{2}, @dots{}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item y, get_ant
|
|
Get @var{Antenna} number (@code{0}, @code{1}, @code{2}, @dots{}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item *, reset @var{Reset}
|
|
Perform rig @var{Reset}.
|
|
|
|
@code{0} = None, @code{1} = Software reset, @code{2} = @acronym{VFO}
|
|
reset, @code{4} = Memory Clear reset, @code{8} = Master reset. Since
|
|
these values are defined as a bitmask in @file{rig.h}, it should be
|
|
possible to @code{AND} these values together to do multiple resets at
|
|
once, if the backend supports it or supports a reset action via rig
|
|
control at all.
|
|
|
|
@item b, send_morse @var{Morse}
|
|
Send @var{Morse} symbols.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x87, set_powerstat @var{Power Status}
|
|
Set power On/Off/Standby @var{Power Status}.
|
|
|
|
@code{0} = Power Off, @code{1} = Power On, @code{2} = Power Standby.
|
|
Defined as a bitmask in @file{rig.h}.
|
|
|
|
@item 0x88, get_powerstat
|
|
Get power On/Off/Standby @var{Power Status} as in
|
|
@command{set_powerstat} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x89, send_dtmf @var{Digits}
|
|
Set DTMF @var{Digits}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x8a, recv_dtmf
|
|
Get DTMF @var{Digits}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item _, get_info
|
|
Get misc information about the rig
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item 1, dump_caps
|
|
Not a real rig remote command, it just dumps capabilities, i.e. what
|
|
the backend knows about this model, and what it can do.
|
|
|
|
TODO: Ensure this is in a consistent format so it can be read into a
|
|
hash, dictionary, etc. Bug reports requested.
|
|
|
|
@strong{N.B.} This command will produce many lines of output so be
|
|
very careful if using a fixed length array! For example, running this
|
|
command against the Dummy backend results in over 5kB of text output.
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item 2, power2mW @var{Power 0.0..1.0}, @var{Frequency}, @var{Mode}
|
|
Returns @var{Power mW}
|
|
|
|
Converts a @var{Power} value in a range of @code{0.0..1.0} to
|
|
the real transmit power in milli-Watts (integer). The @var{Frequency}
|
|
and @var{Mode} also need to be provided as output power may vary
|
|
according to these values.
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item 4, mW2power @var{Power mW}, @var{Frequency}, @var{Mode}
|
|
Returns @var{Power 0.0..1.0}
|
|
|
|
Converts the real transmit power in milli-Watts (integer) to a
|
|
@var{Power} value in a range of @code{[0.0..1.0]}. The
|
|
@var{Frequency} and @var{Mode} also need to be provided as output
|
|
power may vary according to these values.
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item w, send_cmd @var{Cmd}
|
|
Send raw command string to rig. This is useful for testing and
|
|
troubleshooting rig commands and responses when developing a backend.
|
|
|
|
For binary protocols enter values as @code{\0xAA\0xBB}. Expect a
|
|
@var{Reply} from the rig which will likely be a binary block or an
|
|
@acronym{ASCII} string depending on the rig's protocol (see your
|
|
radio's computer control documentation).
|
|
|
|
The command terminator, set by the @option{--send-cmd-term} option
|
|
above, will terminate each command string sent to the radio. This
|
|
character should not be a part of the input string.
|
|
@end table
|
|
|
|
@node rigctl readline support
|
|
@subsection @command{rigctl} Readline support
|
|
@cindex @command{rigctl} Readline support
|
|
@cindex Readline support, @command{rigctl}
|
|
|
|
If Readline library development files are found at configure time,
|
|
@command{rigctl} will be conditonally built with Readline support for
|
|
command and argument entry. Readline command key bindings are at
|
|
their defaults as described in the
|
|
@url{http://cnswww.cns.cwru.edu/php/chet/readline/rluserman.html,
|
|
Readline manual} although @command{rigctl} sets the name @code{rigctl}
|
|
which can be used in @code{Conditional Init Constructs} in the
|
|
Readline Init File (@file{$HOME/.inputrc} by default) for custom
|
|
keybindings unique to @command{rigctl}.
|
|
|
|
Command history is available with Readline support as described in the
|
|
@url{http://cnswww.cns.cwru.edu/php/chet/readline/history.html#SEC1,
|
|
Readline History manual}. Command and argument strings are stored as
|
|
single lines even when arguments are prompted for input individually.
|
|
Commands and arguments are not validated and are stored as typed with
|
|
values separated by a single space.
|
|
|
|
Normally session history is not saved, however, use of either of the
|
|
@option{-i}/@option{--read-history} or
|
|
@option{-I}/@option{--save-history} options when starting
|
|
@command{rigctl} will cause any previously saved history to be read in
|
|
and/or the current and any previous session history (assuming the
|
|
@option{-i} and @option{-I} options are given together) will be
|
|
written out when @command{rigctl} is closed. Each option is mutually
|
|
exclusive, i.e. either may be given separately or in combination.
|
|
This is useful to save a set of commands and then read them later but
|
|
not write the modified history for a consistent set of test commands
|
|
in interactive mode, for example.
|
|
|
|
History is stored in @file{$HOME/.rigctl_history} by default although
|
|
the destination directory may be changed by setting the
|
|
@env{RIGCTL_HIST_DIR} environment variable. When
|
|
@env{RIGCTL_HIST_DIR} is unset, the value of the @env{HOME}
|
|
environment variable is used instead. Only the destination directory
|
|
may be changed at this time.
|
|
|
|
If Readline support is not found at configure time the original
|
|
internal command handler is used. Readline is not used for
|
|
@command{rigctl} commands entered on the command line regardless if
|
|
Readline support is built in or not.
|
|
|
|
@quotation Note
|
|
Readline support is not included in the MS Windows 32 binary builds
|
|
supplied by the Hamlib Project. Running @command{rigctl} on the MS
|
|
Windows 32 platform in the @command{cmd} shell does give session
|
|
command line history, however, it is not saved to disk between
|
|
sessions.
|
|
@end quotation
|
|
|
|
@node rotctl
|
|
@section @command{rotctl}
|
|
@cindex rotctl
|
|
|
|
Identical in function to @command{rigctl}, @command{rotctl} provides a
|
|
means for testing Hamlib functions useful for rotor control and
|
|
@acronym{QRA} locator computations. As rotors have a much narrower
|
|
scope than radios, there are fewer command line options and commands
|
|
for @command{rotctl}.
|
|
|
|
@menu
|
|
* Introduction to rotctl::
|
|
* rotctl invocation::
|
|
* rotctl command line options::
|
|
* rotctl commands::
|
|
* rotctl readline support::
|
|
@end menu
|
|
|
|
@node Introduction to rotctl
|
|
@subsection Introduction to @command{rotctl}
|
|
@cindex Introduction to @command{rotctl}
|
|
@cindex @command{rotctl}, introduction to
|
|
|
|
@command{rotctl} is a character based interactive program and a
|
|
command line program able to set or query a rotor's value with a
|
|
single command. @command{rotctl} is invoked from a shell command
|
|
prompt with various options and additional commands.
|
|
|
|
In its most simple use as a command line program, @command{rotctl} is
|
|
used to set frequency and mode by typing commands after any
|
|
@command{rotctl} options:
|
|
|
|
@example
|
|
@kbd{rotctl P 145.0 23.0}
|
|
@kbd{rotctl M 8 25}
|
|
@end example
|
|
|
|
@noindent
|
|
and then query those values:
|
|
|
|
@example
|
|
@kbd{rotctl p}
|
|
@end example
|
|
|
|
Entering interactive mode is a simple matter of not placing any
|
|
commands after any @command{rotctl} options:
|
|
|
|
@example
|
|
@kbd{rotctl}
|
|
@end example
|
|
|
|
@noindent
|
|
Entering interactive mode allows successive commands to be entered
|
|
without exiting @command{rotctl}. Recent additions to
|
|
@command{rotctl} allow command editing and history recall through use
|
|
of the @url{ http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html,
|
|
Readline} library.
|
|
|
|
Interactive mode is indicated by the spartan prompt:
|
|
|
|
@example
|
|
Rotator command:
|
|
@end example
|
|
|
|
@noindent
|
|
Commands are given at the prompt:
|
|
|
|
@example
|
|
Rotator command: @kbd{M}
|
|
Direction: 16
|
|
Speed: 60
|
|
|
|
Rotator command: @kbd{p}
|
|
Azimuth: 11.352000
|
|
Elevation: 0.000000
|
|
|
|
Rotator command: @kbd{p}
|
|
Azimuth: 27.594000
|
|
Elevation: 0.000000
|
|
|
|
Rotator command:
|
|
@end example
|
|
|
|
An additional prompt is printed when more information is required by
|
|
the command. For @kbd{M} above, @command{rotctl} prompted for the
|
|
``Direction'' and ``Speed'' values. For @kbd{p} above, @command{rotctl}
|
|
returned the ``Azimuth'' and ``Elevation'' values without further prompts.
|
|
The command prompt is returned after each command invocation.
|
|
|
|
The above examples invoked @command{rotctl} without specifying a rotor
|
|
model. This is a feature where the Hamlib internal rotor dummy is
|
|
used instead. The dummy rotor provides a way to test Hamlib functions
|
|
with out the need for actual rotor hardware. However, to develop back
|
|
end capability for a given rotor, having the actual radio connected to
|
|
the computer is necessary for debugging.
|
|
|
|
For example, to quickly set position for RotorEZ:
|
|
|
|
@example
|
|
@kbd{rotctl -m 401 -r /dev/rotor P 100.0 0.0}
|
|
@end example
|
|
|
|
@noindent
|
|
and to query the position:
|
|
|
|
@example
|
|
@kbd{rotctl -m 401 -r /dev/rotor p}
|
|
100.000000
|
|
0.000000
|
|
|
|
@end example
|
|
|
|
@noindent
|
|
The returned values do not have the prompt strings associated with
|
|
interactive mode as shown above.
|
|
|
|
The @option{-m} option takes a numeric value that corresponds to a
|
|
given rotor back end model. The @option{-r} option takes the path to
|
|
the port device on @acronym{POSIX} and the device name on MS Windows.
|
|
|
|
@quotation Note
|
|
A complete list of supported radio models may be seen by use of the
|
|
@option{-l} option:
|
|
|
|
@example
|
|
@kbd{rotctl -l}
|
|
Rig # Mfg Model Version Status
|
|
1 Hamlib Dummy 0.5 Beta
|
|
2 Hamlib NET rotctl 0.3 Beta
|
|
201 Hamlib EasycommI 0.3 Beta
|
|
202 Hamlib EasycommII 0.3 Beta
|
|
.
|
|
.
|
|
.
|
|
1201 AMSAT IF-100 0.1 Untested
|
|
1301 LA7LKA ts7400 0.1 Beta
|
|
1401 Celestron NexStar 0.1 Untested
|
|
@end example
|
|
|
|
@noindent
|
|
The list is long so use @kbd{@key{SHIFT}-PageUp}/
|
|
@kbd{@key{SHIFT}-PageDown} on Linux, @kbd{@key{ScrollLock}} then
|
|
@kbd{@key{PageUp}}/@kbd{@key{PageDown}} on Free BSD, or use the
|
|
scrollbar to the virtual terminal window (@command{cmd} window on MS
|
|
Windows) or the output can be piped to '@command{more}' or
|
|
'@command{less}', e.g.@: '@kbd{rotctl -l | more}' to scroll back up
|
|
the list. The list is sorted numerically by model number since Hamlib
|
|
1.2.15.1. Model numbers of a manufacturer/ protocol family are
|
|
grouped together.
|
|
@end quotation
|
|
|
|
|
|
@node rotctl invocation
|
|
@subsection @command{rotctl} invocation
|
|
@cindex @command{rotctl} invocation
|
|
@cindex invocation, @command{rotctl}
|
|
|
|
Here are some additional examples for invoking @command{rotctl} for
|
|
various situations.
|
|
|
|
Start @command{rotctl} for RotorEZ using the first serial port on
|
|
Linux:
|
|
|
|
@example
|
|
rotctl -m 401 -r /dev/ttyS0
|
|
@end example
|
|
|
|
@noindent
|
|
Start @command{rotctl} for RotorEZ using @code{COM2} on MS Windows:
|
|
|
|
@example
|
|
rotctl -m 401 -r COM2
|
|
@end example
|
|
|
|
@noindent
|
|
Connect to a running @command{rotctld} with rotor model 2 (@code{NET rotctl}) on the
|
|
local host and specifying the @acronym{TCP} port, and querying the position:
|
|
|
|
@example
|
|
rotctl -m 2 -r localhost:4533 \get_pos
|
|
@end example
|
|
|
|
@node rotctl command line options
|
|
@subsection @command{rotctl} command line options
|
|
@cindex @command{rotctl} command line options
|
|
@cindex Command line options, @command{rotctl}
|
|
|
|
@command{rotctl} accepts the following options:
|
|
|
|
@table @option
|
|
@item -m
|
|
@itemx --model=@var{id}
|
|
Select rotator model number. See model list (use @kbd{rotctl -l}).
|
|
|
|
@strong{N.B.} @command{rotctl} (or third party software) will use
|
|
rotor model 2 for NET rotctl (@command{rotctld}).
|
|
|
|
@item -r
|
|
@itemx --rot-file=@var{device}
|
|
Use @var{device} as the file name of the port the rotor is connected.
|
|
Often a serial port, but could be a USB to serial adapter. Typically
|
|
@file{/dev/ttyS0} , @file{/dev/ttyS1} , @file{/dev/ttyUSB0} , etc.@:
|
|
on Linux or @file{COM1} , @file{COM2} , etc.@: on MS Windows. The
|
|
special string @kbd{uh-rig} may be given to enable micro-ham device
|
|
support.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -s
|
|
@itemx --serial-speed=@var{baud}
|
|
Set serial speed to @var{baud} rate. Uses @strong{maximum} serial
|
|
speed from rotor backend capabilities as the default.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -t
|
|
@itemx --send-cmd-term=@var{char}
|
|
Change the termination @var{char} for text protocol when using the
|
|
@code{send_cmd} command. The default value is @code{<CR>}
|
|
(@code{0x0d}). Non @acronym{ASCII} printable characters can be
|
|
specified as an @acronym{ASCII} number, in hexadecimal format,
|
|
prepended with @code{0x}. You may pass an empty string for no
|
|
termination char. The string '@code{-1}' tells @command{rotctl} to
|
|
switch to binary protocol. See the @code{send_cmd} command for further
|
|
explanation.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -L
|
|
@itemx --show-conf
|
|
List all config parameters for the rotor defined with @option{-m}
|
|
above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -C
|
|
@itemx --set-conf=@var{parm}=@var{val}[,@var{parm}=@var{val},@dots{}]
|
|
Set config parameter. e.g.@: @code{stop_bits=2}
|
|
|
|
Use @option{-L} option for a list.
|
|
|
|
@item -l
|
|
@itemx --list
|
|
List all model numbers defined in Hamlib and exit. As of 1.2.15.1 the
|
|
list is sorted by model number.
|
|
|
|
@strong{N.B.} In Linux the list can be scrolled back using
|
|
@kbd{@key{SHIFT}-PageUp}/ @kbd{@key{SHIFT}-PageDown}, or using the
|
|
scrollbars of a virtual terminal in X or the @command{cmd} window in
|
|
MS Windows. The output can be piped to '@command{more}' or
|
|
'@command{less}', e.g.@: '@kbd{rotctl -l | more}'.
|
|
|
|
@item -u
|
|
@itemx --dump-caps
|
|
Dump capabilities for the rotor defined with @option{-m} above and
|
|
exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -i
|
|
@itemx --read-history
|
|
Read previously saved command and argument history from a file
|
|
(default '@file{$HOME/.rotctl_history}') for the current session.
|
|
Available when @command{rotctl} is built with Readline support.
|
|
|
|
@strong{N.B.} To read a history file stored in another directory, set
|
|
the @env{ROTCTL_HIST_DIR} environment variable, e.g.@:
|
|
'@kbd{ROTCTL_HIST_DIR=$HOME/tmp rotctl -i}'. When @env{ROTCTL_HIST_DIR}
|
|
is not set, the value of @env{HOME} is used.
|
|
|
|
@item -I
|
|
@itemx --save-history
|
|
Write current session (and previously saved session(s) if @option{-i}
|
|
option is also given) command and argument history to a file (default
|
|
'@file{$HOME/.rotctl_history}') at the end of the current session.
|
|
Complete commands with arguments are saved as a single line to be
|
|
recalled and used or edited. Available when @command{rotctl} is built
|
|
with Readline support.
|
|
|
|
To write a history file in another directory, set the
|
|
@env{ROTCTL_HIST_DIR} environment variable, e.g.@:
|
|
'@kbd{ROTCTL_HIST_DIR=$HOME/tmp rotctl -I}'. When @env{ROTCTL_HIST_DIR}
|
|
is not set, the value of @env{HOME} is used.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set verbose mode level, cumulative i.e.@: @option{-vvvvv} sets maximum
|
|
debugging output to @file{stderr}.
|
|
|
|
Five different levels of diagnostics can be output to @file{stderr}
|
|
and correspond to @option{-v} for @code{BUG}, @option{-vv} for
|
|
@code{ERR}, @option{-vvv} for @code{WARN}, @option{-vvvv} for
|
|
@code{VERBOSE}, or @option{-vvvvv} for @code{TRACE}. Back end authors
|
|
will use the verbose facility to print critical values useful for
|
|
testing and will often ask for this output in response to a request
|
|
for help.
|
|
|
|
@item -Z
|
|
@itemx --debug-time-stamps
|
|
Enable time stamps on debug output.
|
|
|
|
@item -h
|
|
@itemx --help
|
|
Show summary of these options and exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show version of @command{rotctl} and exit.
|
|
@end table
|
|
|
|
@quotation Note
|
|
Some options may not be implemented by a given backend and will return
|
|
an error. This is most likely to occur with the @option{--set-conf}
|
|
and @option{--show-conf} options.
|
|
@end quotation
|
|
|
|
@node rotctl commands
|
|
@subsection @command{rotctl} commands
|
|
@cindex @command{rotctl} commands
|
|
@cindex commands, @command{rotctl}
|
|
|
|
@xref{rigctl commands}, for command syntax.
|
|
|
|
@strong{Rotor commands}
|
|
|
|
Here is a summary of the supported commands:
|
|
|
|
@table @command
|
|
@item q
|
|
Exit @command{rotctl} in interactive mode (@kbd{q} is not case
|
|
sensitive).
|
|
|
|
When @command{rotctl} is controlling the rotor directly, will close
|
|
the rotor back end and port. When @command{rotctl} is connected to
|
|
@command{rotctld} (rotor model 2), the @acronym{TCP/IP} connection to
|
|
@command{rotctld} is closed and @command{rotctld} remains running,
|
|
available for another @acronym{TCP/IP} network connection.
|
|
|
|
@item P, set_pos @var{Azimuth}, @var{Elevation}
|
|
Set position: @var{Azimuth} and @var{Elevation} as double precision
|
|
floating point values.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item p, get_pos
|
|
Get position: @var{Azimuth} and @var{Elevation} as double precision
|
|
floating point values.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item M, move @var{Direction}, @var{Speed}
|
|
Move the rotator in a specific direction at the given rate.
|
|
|
|
Values are integers where @var{Direction} is defined as @code{2} = Up,
|
|
@code{4} = Down, @code{8} = Left, and @code{16} = Right. @var{Speed}
|
|
is an integer between @code{1} and @code{100}.
|
|
|
|
@strong{N.B.} Not all backends that implement the move command use the
|
|
Speed value. At this time only the gs232a utilizes the Speed
|
|
parameter.
|
|
|
|
@item S, stop
|
|
Stop the rotator.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item K, park
|
|
Park the antenna.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item C, set_conf @var{Token}, @var{Value}
|
|
Set a configuration parameter. It is safe to give @var{Token} a value
|
|
of @code{0} (zero). @var{Value} may be a string up to 20 characters.
|
|
|
|
See @option{-L} output.
|
|
|
|
@item R, reset @var{Reset}
|
|
Reset the rotator.
|
|
|
|
Integer value of @code{1} for Reset All.
|
|
|
|
@item _, get_info
|
|
Get misc information on the rotator.
|
|
|
|
At the moment returns @var{Model Name}.
|
|
|
|
@item w, send_cmd @var{Cmd}
|
|
Send raw command string to the rotator.
|
|
|
|
@code{<CR>} (or @option{send-cmd-term}, see @option{-t} option) is
|
|
appended automatically at the end of the command for text protocols.
|
|
For binary protocols, enter values as @code{\0xAA\0xBB}.
|
|
@end table
|
|
|
|
@strong{Locator Commands}
|
|
|
|
These commands offer conversions of Degrees Minutes Seconds to other
|
|
formats, Maidenhead square locator conversions and distance and
|
|
azimuth conversions.
|
|
|
|
@table @command
|
|
@item L, lonlat2loc @var{Longitude}, @var{Latitude}, @var{Loc Len 2..12}
|
|
Returns the Maidenhead locator for the given @var{Longitude} and
|
|
@var{Latitude}.
|
|
|
|
Both are floating point values. The precision of the returned square
|
|
is controlled by @var{Loc Len} which should be an even numbered
|
|
integer value between @code{2} and @code{12}.
|
|
|
|
For example, @kbd{L -170.000000 -85.000000 12} returns @samp{Locator:
|
|
AA55AA00AA00}.
|
|
|
|
@item l, loc2lonlat @var{Locator}
|
|
Returns @var{Longitude} and @var{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.
|
|
|
|
For example, @kbd{l AA55AA00AA00} returns @samp{Longitude: -169.999983
|
|
Latitude: -84.999991}.
|
|
|
|
@item D, dms2dec @var{Degrees}, @var{Minutes}, @var{Seconds}, @var{S/W}
|
|
Returns @var{Dec Degrees}, a signed floating point value.
|
|
|
|
@var{Degrees} and @var{Minutes} are integer values and @var{Seconds}
|
|
is a floating point value. @var{S/W} is a flag with @code{1}
|
|
indicating South latitude or West longitude and @code{0} North or East
|
|
(the flag is needed as computers don't recognize a signed zero even
|
|
though only the @var{Degrees} value only is typically signed in
|
|
@acronym{DMS} notation).
|
|
|
|
@item d, dec2dms @var{Dec Degrees}
|
|
Returns @var{Degrees}, @var{Minutes}, @var{Seconds}, @var{S/W}.
|
|
|
|
Values are as in @command{dms2dec} above.
|
|
|
|
@item E, dmmm2dec @var{Degrees}, @var{Dec Minutes}, @var{S/W}
|
|
Returns @var{Dec Degrees}, a signed floating point value.
|
|
|
|
@var{Degrees} is an integer value and @var{Minutes} is a floating
|
|
point value. @var{S/W} is a flag with @code{1} indicating South
|
|
latitude or West longitude and @code{0} North or East (the flag is
|
|
needed as computers don't recognize a signed zero even though only the
|
|
@var{Degrees} value only is typically signed in @acronym{DMS}
|
|
notation).
|
|
|
|
@item e, dec2dmmm @var{Dec Deg}
|
|
Returns @var{Degrees}, @var{Minutes}, @var{S/W}.
|
|
|
|
Values are as in @command{dmmm2dec} above.
|
|
|
|
@item B, qrb @var{Lon 1}, @var{Lat 1}, @var{Lon 2}, @var{Lat 2}
|
|
Returns @var{Distance} and @var{Azimuth} where @var{Distance} is in km
|
|
and @var{Azimuth} is in degrees.
|
|
|
|
All @var{Lon}/@var{Lat} values are signed floating point numbers.
|
|
|
|
@item A, a_sp2a_lp @var{Short Path Deg}
|
|
Returns @var{Long Path Deg} or @code{-RIG_EINVAL} upon input error.
|
|
|
|
Both are floating point values within the range @code{0.00} to
|
|
@var{360.00}.
|
|
|
|
@item a, d_sp2d_lp @var{Short Path km}
|
|
Returns @var{Long Path km}.
|
|
|
|
Both are floating point values.
|
|
@end table
|
|
|
|
@node rotctl readline support
|
|
@subsection @command{rotctl} Readline support
|
|
@cindex @command{rotctl} Readline support
|
|
@cindex Readline support, @command{rotctl}
|
|
|
|
If Readline library development files are found at configure time,
|
|
@command{rotctl} will be conditonally built with Readline support for
|
|
command and argument entry. Readline command key bindings are at
|
|
their defaults as described in the
|
|
@url{http://cnswww.cns.cwru.edu/php/chet/readline/rluserman.html,
|
|
Readline manual} although @command{rotctl} sets the name @code{rotctl}
|
|
which can be used in @code{Conditional Init Constructs} in the
|
|
Readline Init File (@file{$HOME/.inputrc} by default) for custom
|
|
keybindings unique to @command{rotctl}.
|
|
|
|
Command history is available with Readline support as described in the
|
|
@url{http://cnswww.cns.cwru.edu/php/chet/readline/history.html#SEC1,
|
|
Readline History manual}. Command and argument strings are stored as
|
|
single lines even when arguments are prompted for input individually.
|
|
Commands and arguments are not validated and are stored as typed with
|
|
values separated by a single space.
|
|
|
|
Normally session history is not saved, however, use of either of the
|
|
@option{-i}/@option{--read-history} or
|
|
@option{-I}/@option{--save-history} options when starting
|
|
@command{rotctl} will cause any previously saved history to be read in
|
|
and/or the current and any previous session history (assuming the
|
|
@option{-i} and @option{-I} options are given together) will be
|
|
written out when @command{rotctl} is closed. Each option is mutually
|
|
exclusive, i.e. either may be given separately or in combination.
|
|
This is useful to save a set of commands and then read them later but
|
|
not write the modified history for a consistent set of test commands
|
|
in interactive mode, for example.
|
|
|
|
History is stored in @file{$HOME/.rotctl_history} by default although the
|
|
destination directory may be changed by setting the
|
|
@env{ROTCTL_HIST_DIR} environment variable. When
|
|
@env{ROTCTL_HIST_DIR} is unset, the value of the @env{HOME} environment
|
|
variable is used instead. Only the destination directory may be
|
|
changed at this time.
|
|
|
|
If Readline support is not found at configure time the original
|
|
internal command handler is used. Readline is not used for
|
|
@command{rotctl} commands entered on the command line regardless if
|
|
Readline support is built in or not.
|
|
|
|
@quotation Note
|
|
Readline support is not included in the MS Windows 32 binary builds
|
|
supplied by the Hamlib Project. Running @command{rotctl} on the MS
|
|
Windows 32 platform in the @command{cmd} shell does give session
|
|
command line history, however, it is not saved to disk between
|
|
sessions.
|
|
@end quotation
|
|
|
|
@node rigctld
|
|
@section @command{rigctld}
|
|
@cindex rigctld
|
|
|
|
The @command{rigctld} program is a network server that accepts the
|
|
familiar commands of @command{rigctl} and provides the response data
|
|
over a @acronym{TCP/IP} network socket to an application. In this
|
|
manner an application can access a @command{rigctl} instance from
|
|
nearly anywhere (caveat, no security is currently provided by
|
|
@command{rigctl}). Applications using @command{rigctl} do not link to
|
|
Hamlib nor use its C API.
|
|
|
|
@menu
|
|
* Introduction to rigctld::
|
|
* rigctld invocation::
|
|
* rigctld command line options::
|
|
* rigctld commands::
|
|
* rigctld protocol::
|
|
@end menu
|
|
|
|
@node Introduction to rigctld
|
|
@subsection Introduction to @command{rigctld}
|
|
@cindex Introduction to @command{rigctld}
|
|
@cindex @command{rigctld}, introduction to
|
|
|
|
Multiple radios can be controlled on different @acronym{TCP} ports by
|
|
use of multiple @command{rigctld} processes. The syntax of the
|
|
commands are the same as @command{rigctl}. It is hoped that
|
|
@command{rigctld} will be especially useful for client authors using
|
|
languages such as @url{http://www.perl.org/, Perl},
|
|
@url{http://www.python.org/, Python}, @url{http://php.net/, PHP},
|
|
@url{http://www.ruby-lang.org/en/, Ruby}, @url{http://www.tcl.tk/,
|
|
TCL}, and others.
|
|
|
|
@command{rigctld} communicates to a client through a @acronym{TCP}
|
|
network socket using text commands shared with @command{rigctl}. The
|
|
protocol is simple; commands are sent to @command{rigctld} on one line
|
|
and @command{rigctld} responds to ``get'' commands with the requested
|
|
values, one per line, when successful, otherwise, it responds with one
|
|
line @samp{RPRT x}, where @samp{x} is a negative number indicating the
|
|
Hamlib error code. Commands that do not return values respond with
|
|
the line @samp{RPRT x}, where @samp{x} is zero when successful,
|
|
otherwise a regative number indicating the Hamlib error code. Each
|
|
line is terminated with a newline @code{\n} character. This protocol
|
|
is primarily for use by the @code{NET rigctl} (rig model 2) backend.
|
|
@xref{rigctld Default protocol}.
|
|
|
|
A separate Extended Response protocol extends the above behavior by
|
|
echoing the received command string as a header, any returned values
|
|
as a key: value pair, and the @samp{RPRT x} string as the end of
|
|
response marker which includes the Hamlib success or failure value.
|
|
Consider using this protocol for clients that will interact with
|
|
@command{rigctld} directly through a @acronym{TCP} network socket.
|
|
@xref{rigctld Extended Response protocol}.
|
|
|
|
@node rigctld invocation
|
|
@subsection @command{rigctld} invocation
|
|
@cindex @command{rigctld} invocation
|
|
@cindex invocation, @command{rigctld}
|
|
|
|
The command line invocation for @command{rigctld} is similar to
|
|
@command{rigctl} except that in POSIX environments a trailing @kbd{&}
|
|
is appended to the command string to ``background'' the
|
|
@command{rigctld} process so the shell can be used to run other
|
|
commands while @command{rigctld} continues to run.
|
|
|
|
Here are some examples for invoking @command{rigctld}.
|
|
|
|
Start @command{rigctld} for a Yaesu FT-920 using a USB-to-serial
|
|
adapter and backgrounding:
|
|
|
|
@example
|
|
rigctld -m 114 -r /dev/ttyUSB1 &
|
|
@end example
|
|
|
|
Start @command{rigctld} for a Yaesu FT-920 using a USB to serial
|
|
adapter while setting baud rate and stop bits, and backgrounding:
|
|
|
|
@example
|
|
rigctld -m 114 -r /dev/ttyUSB1 -s 4800 -C stop_bits=2 &
|
|
@end example
|
|
|
|
Start @command{rigctld} for an Elecraft K3 using @code{COM2} on MS
|
|
Windows:
|
|
|
|
@example
|
|
rigctld -m 229 -r COM2 -T 127.0.0.1 -t 4532
|
|
@end example
|
|
|
|
@quotation Note
|
|
On MS Windows the use of the @option{-T} and @option{-t} options appear
|
|
to be necessary to set the @acronym{IP} address and @acronym{TCP} port
|
|
or else the network socket cannot be found. On @acronym{POSIX} systems
|
|
the @command{rigctld} default values will be used.
|
|
@end quotation
|
|
|
|
Connect to the already running @command{rigctld}, and set current
|
|
frequency to 14.266 MHz with a 1 second read timeout using the default
|
|
protocol from the shell prompt:
|
|
|
|
@example
|
|
echo "\set_freq 14266000" | nc -w 1 localhost 4532
|
|
@end example
|
|
|
|
Connect to a running @command{rigctld} with @command{rigctl} on the
|
|
local host:
|
|
|
|
@example
|
|
rigctl -m2
|
|
@end example
|
|
|
|
@node rigctld command line options
|
|
@subsection @command{rigctld} command line options
|
|
@cindex @command{rigctld} command line options
|
|
@cindex Command line options, @command{rigctld}
|
|
|
|
Many of the @command{rigctld} command line options are shared
|
|
with @command{rigctl} with a few additions.
|
|
|
|
@command{rigctld} accepts the following options:
|
|
|
|
@table @option
|
|
@item -m
|
|
@itemx --model=@var{id}
|
|
Select radio model number. See model list (use @kbd{rigctld -l}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -r
|
|
@itemx --rig-file=@var{device}
|
|
Use @var{device} as the file name of the port the radio is connected.
|
|
Often a serial port, but could be a USB to serial adapter. Typically
|
|
@file{/dev/ttyS0} , @file{/dev/ttyS1} , @file{/dev/ttyUSB0} , etc.@:
|
|
on Linux or @file{COM1} , @file{COM2} , etc.@: on MS Windows. The
|
|
special string @kbd{uh-rig} may be given to enable micro-ham device
|
|
support.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -p
|
|
@itemx --ptt-file=@var{device}
|
|
Use @var{device} as the file name of the Push-To-Talk device using a
|
|
device file as described above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -d
|
|
@itemx --dcd-file=@var{device}
|
|
Use @var{device} as the file name of the Data Carrier Detect device
|
|
using a device file as described above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -P
|
|
@itemx --ptt-type=@var{type}
|
|
Use @var{type} of Push-To-Talk device. Supported types are
|
|
@code{RIG}, @code{DTR}, @code{RTS}, @code{PARALLEL}, @code{NONE},
|
|
overriding @acronym{PTT} type defined in the rig's backend.
|
|
|
|
Some side effects of this command are that when type is set to
|
|
@code{DTR}, read @acronym{PTT} state comes from Hamlib frontend, not
|
|
read from the radio. When set to @code{NONE}, @acronym{PTT} state
|
|
cannot be read or set even if rig backend supports reading/setting
|
|
@acronym{PTT} status from the rig.
|
|
|
|
@item -D
|
|
@itemx --dcd-type=@var{type}
|
|
Use @var{type} of Data Carrier Detect device. Supported types are
|
|
@code{RIG} (@acronym{CAT} command), @code{DSR}, @code{CTS}, @code{CD},
|
|
@code{PARALLEL}, @code{NONE}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -s
|
|
@itemx --serial-speed=@var{baud}
|
|
Set serial speed to @var{baud} rate. Uses @strong{maximum} serial
|
|
speed from rig backend capabilities (set by @option{-m} above) as the
|
|
default.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -c
|
|
@itemx --civaddr=@var{id}
|
|
Use @var{id} as the @acronym{CI-V} address to communicate with the
|
|
rig. Only useful for Icom radios and those using the Icom protocol.
|
|
|
|
@strong{N.B.} The @var{id} is in decimal notation, unless prefixed by
|
|
@code{0x}, in which case it is a hexadecimal value.
|
|
|
|
@item -T
|
|
@itemx --listen-addr=@var{IPADDR}
|
|
Use @var{IPADDR} as the listening @acronym{IP} address. The default is ANY.
|
|
|
|
@strong{N.B.} On MS Windows setting a specific @acronym{IP} address is
|
|
likely necessary.
|
|
|
|
@item -t
|
|
@itemx --port=@var{number}
|
|
Use @var{number} as the @acronym{TCP} listening port. The default is
|
|
@code{4532}.
|
|
|
|
@strong{N.B.} As @command{rotctld}'s default port is @code{4533}, it
|
|
is advisable to use even numbered ports for @command{rigctld}, e.g.
|
|
@code{4532}, @code{4534}, @code{4536}, etc.
|
|
|
|
@item -L
|
|
@itemx --show-conf
|
|
List all config parameters for the radio defined with @option{-m}
|
|
above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -C
|
|
@itemx --set-conf=@var{parm}=@var{val}[,@var{parm}=@var{val},@dots{}]
|
|
Set config parameter. e.g.@: @code{stop_bits=2}
|
|
|
|
Use @option{-L} option for a list.
|
|
|
|
@item -l
|
|
@itemx --list
|
|
List all model numbers defined in Hamlib and exit. As of 1.2.15.1 the
|
|
list is sorted by model number.
|
|
|
|
@strong{N.B.} In Linux the list can be scrolled back using
|
|
@kbd{@key{SHIFT}-PageUp}/ @kbd{@key{SHIFT}-PageDown}, or using the
|
|
scrollbars of a virtual terminal in X or the @command{cmd} window in
|
|
MS Windows. The output can be piped to '@command{more}' or
|
|
'@command{less}', e.g.@: '@kbd{rigctl -l | more}'.
|
|
|
|
@item -u
|
|
@itemx --dump-caps
|
|
Dump capabilities for the radio defined with @option{-m} above and
|
|
exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -o
|
|
@itemx --vfo
|
|
Set vfo mode, requiring an extra @acronym{VFO} argument in front of
|
|
each appropriate command (except @command{set_vfo}!). Otherwise,
|
|
@code{currVFO} is assumed when this option is not set and an extra VFO
|
|
argument is not used. See @command{chk_vfo} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set verbose mode level, cumulative i.e.@: @option{-vvvvv} sets maximum
|
|
debugging output to @file{stderr}.
|
|
|
|
Five different levels of diagnostics can be output to @file{stderr}
|
|
and correspond to @option{-v} for @code{BUG}, @option{-vv} for
|
|
@code{ERR}, @option{-vvv} for @code{WARN}, @option{-vvvv} for
|
|
@code{VERBOSE}, or @option{-vvvvv} for @code{TRACE}. Back end authors
|
|
will use the verbose facility to print critical values useful for
|
|
testing and will often ask for this output in response to a request
|
|
for help.
|
|
|
|
@item -Z
|
|
@itemx --debug_time_stamps
|
|
Enable time stamps on debug output.
|
|
|
|
@item -h
|
|
@itemx --help
|
|
Show summary of these options and exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show version of @command{rigctl} and exit.
|
|
|
|
@end table
|
|
|
|
@quotation Note
|
|
Some options may not be implemented by a given backend and will return
|
|
an error. This is most likely to occur with the @option{--set-conf}
|
|
and @option{--show-conf} options.
|
|
@end quotation
|
|
|
|
@node rigctld commands
|
|
@subsection @command{rigctld} commands
|
|
@cindex @command{rigctld} commands
|
|
@cindex commands, @command{rigctld}
|
|
|
|
Commands can be sent over the @acronym{TCP} socket either as a single
|
|
char, or as a long command name plus the value(s) space separated on
|
|
one @code{\n} terminated line. @xref{rigctld protocol}.
|
|
|
|
Since most of the Hamlib operations have a ``set'' and a ``get''
|
|
method, in general an upper case letter will be used for set methods
|
|
whereas the corresponding lower case letter refers to the get method.
|
|
Each operation also has a long name; in interactive mode, prepend a
|
|
backslash @kbd{\} to enter a long command name.
|
|
|
|
Example (Perl):
|
|
|
|
@example
|
|
print $socket "\\dump_caps\n";
|
|
@end example
|
|
|
|
@noindent
|
|
to see what the radio's backend can do.
|
|
|
|
@quotation N.B.
|
|
In Perl and many other languages a @kbd{\} will need to
|
|
be escaped with a preceding @kbd{\} so that even though two backslash
|
|
characters appear in the code, only one will be passed to
|
|
@command{rigctld}. This is a possible bug, so beware!
|
|
@end quotation
|
|
|
|
Be aware that the backend for the radio to be controlled, or the radio
|
|
itself may not support some commands. In that case, the operation will
|
|
fail with a Hamlib error message.
|
|
|
|
Here is a summary of the supported commands:
|
|
|
|
@itemize
|
|
@item
|
|
Command short name is followed by the long name which is followed by
|
|
any variable names.
|
|
|
|
@item
|
|
Some short commands are noted as hexadecimal digits due to the
|
|
limitation of upper and lower case letters available. Use the
|
|
associated long command name instead.
|
|
|
|
@item
|
|
While a comma is used to separate variable names in this document,
|
|
they are not part of the command syntax used by @command{rigctl}. Use
|
|
a space to separate values.
|
|
|
|
@item
|
|
In the case of ``set'' commands the variable @var{name} is replaced by
|
|
the value in the description.
|
|
|
|
@item
|
|
In the case of ``get'' commands the variable @var{name} is the key
|
|
name of the value returned.
|
|
|
|
@end itemize
|
|
|
|
@table @command
|
|
@item F, set_freq @var{Frequency}
|
|
Set @var{Frequency}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item f, get_freq
|
|
Get @var{Frequency}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item M, set_mode @var{Mode}, @var{Passband}
|
|
Set @var{Mode} to one of: @code{USB}, @code{LSB}, @code{CW},
|
|
@code{CWR}, @code{RTTY}, @code{RTTYR}, @code{AM}, @code{FM},
|
|
@code{WFM}, @code{AMS}, @code{PKTLSB}, @code{PKTUSB}, @code{PKTFM},
|
|
@code{ECSSUSB}, @code{ECSSLSB}, @code{FAX}, @code{SAM}, @code{SAL},
|
|
@code{SAH}, @code{DSB}.
|
|
|
|
Set @var{Passband} frequency in Hertz, or @code{0} for the Hamlib
|
|
backend default.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument
|
|
instead of @var{Mode} will return a space separated list of radio
|
|
backend supported Modes. Use this to determine the supported Modes of
|
|
a given radio backend.
|
|
|
|
@item m, get_mode
|
|
Get @var{Mode}, @var{Passband}.
|
|
|
|
Returns Mode as a string from @command{set_mode} above and Passband
|
|
frequency in Hertz.
|
|
|
|
@item V, set_vfo @var{VFO}
|
|
Set @var{VFO} to one of: @code{VFOA}, @code{VFOB}, @code{VFOC},
|
|
@code{currVFO}, @code{VFO}, @code{MEM}, @code{Main}, @code{Sub},
|
|
@code{TX}, @code{RX}.
|
|
|
|
In @acronym{VFO} mode only a single @acronym{VFO} parameter is
|
|
required.
|
|
|
|
@item v, get_vfo
|
|
Get current @var{VFO}.
|
|
|
|
Returns @acronym{VFO} as a string from @command{set_vfo} above.
|
|
|
|
@item J, set_rit @var{RIT}
|
|
Set @var{RIT}, in Hertz, can be a positive or negative value.
|
|
|
|
A value of @code{0} resets @acronym{RIT} and @emph{should} turn
|
|
@acronym{RIT} off. If not, file a bug report against the Hamlib
|
|
backend.
|
|
|
|
@strong{N.B.} This functionality is under transition and in the future
|
|
will need to be activated with the @command{set_func} command.
|
|
|
|
@item j, get_rit
|
|
Get @var{RIT}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item Z, set_xit @var{XIT}
|
|
Set @var{XIT}, in Hertz, can be a positive or negative value.
|
|
|
|
A value of @code{0} resets @acronym{XIT} and @emph{should} turn
|
|
@acronym{XIT} off. If not, file a bug report against the Hamlib
|
|
backend.
|
|
|
|
@strong{N.B.} This functionality is under transition and in the future
|
|
will need to be activated with the @command{set_func} command.
|
|
|
|
@item z, get_xit
|
|
Get @var{XIT}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item T, set_ptt @var{PTT}
|
|
Set @var{PTT} to one of: @code{0} (RX), @code{1} (TX), @code{2} (TX
|
|
mic), @code{3} (TX data).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item t, get_ptt
|
|
Get @var{PTT} status.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x8b, get_dcd
|
|
Get @var{DCD} (squelch) status, @code{0} (Closed) or @code{1} (Open)
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item R, set_rptr_shift @var{Rptr Shift}
|
|
Set @var{Rptr Shift}: @code{+}, @code{-} or something else for none.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item r, get_rptr_shift
|
|
Get @var{Rptr Shift}. Returns @code{+}, @code{-} or @code{None}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item O, set_rptr_offs @var{Rptr Offset}
|
|
Set @var{Rptr Offset}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item o, get_rptr_offs
|
|
Get @var{Rptr Offset}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item C, set_ctcss_tone @var{CTCSS Tone}
|
|
Set @var{CTCSS Tone}, in tenths of Hertz.
|
|
|
|
@acronym{CTCSS},
|
|
@url{http://en.wikipedia.org/wiki/Continuous_Tone-Coded_Squelch_System,
|
|
Continuous Tone Coded Squelch System}, is a method used to reduce the
|
|
annoyance of listening to other users on a shared two-way
|
|
communications radio channel by imposing a tone on the transmitted
|
|
signal. Also known as @dfn{subaudible tone} and @acronym{PL},
|
|
@dfn{Private Line}.
|
|
|
|
@item c, get_ctcss_tone
|
|
Get @var{CTCSS Tone}, in tenths of Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item D, set_dcs_code @var{DCS Code}
|
|
Set @var{DCS Code}.
|
|
|
|
@acronym{DCS},
|
|
@url{http://en.wikipedia.org/wiki/Digital-Coded_Squelch#DCS,
|
|
Digital-Coded Squelch} is a digital version of @acronym{CTCSS} which
|
|
imposes a digital code on the transmitted signal.
|
|
|
|
@item d, get_dcs_code
|
|
Get @var{DCS Code}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x90, set_ctcss_sql @var{CTCSS Sql}
|
|
Set @var{CTCSS Sql} tone, in tenths of Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x91, get_ctcss_sql
|
|
Get @var{CTCSS Sql} tone, in tenths of Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x92, set_dcs_sql @var{DCS Sql}
|
|
Set @var{DCS Sql} code.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x93, get_dcs_sql
|
|
Get @var{DCS Sql} code.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item I, set_split_freq @var{Tx Frequency}
|
|
Set @var{TX Frequency}, in Hertz for ``split'' frequency operation.
|
|
|
|
See also @command{set_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item i, get_split_freq
|
|
Get @var{TX Frequency}, in Hertz for ``split'' frequency operation.
|
|
|
|
See also @command{get_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item X, set_split_mode @var{TX Mode}, @var{TX Passband}
|
|
Set @var{TX Mode} to one of: @code{AM}, @code{FM}, @code{CW},
|
|
@code{CWR}, @code{USB}, @code{LSB}, @code{RTTY}, @code{RTTYR},
|
|
@code{WFM}, @code{AMS}, @code{PKTLSB}, @code{PKTUSB}, @code{PKTFM},
|
|
@code{ECSSUSB}, @code{ECSSLSB}, @code{FAX}, @code{SAM}, @code{SAL},
|
|
@code{SAH}, @code{DSB}.
|
|
|
|
The @var{TX Passband} is the exact passband frequency in Hertz, or
|
|
@code{0} for the Hamlib backend default. A value of @code{-1} may be
|
|
passed which leaves the rig passband unchanged from the current or
|
|
default value for the mode as defined by the rig.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{TX Mode} will return a space separated list of radio backend
|
|
supported TX Modes. Use this to determine the supported TX Modes of a
|
|
given radio backend.
|
|
|
|
See also @command{set_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item x, get_split_mode
|
|
Get @var{TX Mode}, @var{TX Passband}.
|
|
|
|
Returns TX mode as a string from @command{set_split_mode} above and TX
|
|
passband in Hz.
|
|
|
|
See also @command{get_split_freq_mode} below.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item K, set_split_freq_mode @var{Tx Frequency}, @var{TX Mode}, @var{TX Passband}
|
|
Set @var{TX Frequency}, in Hertz for ``split'' frequency operation.
|
|
Set @var{TX Mode} to one of: @code{AM}, @code{FM}, @code{CW},
|
|
@code{CWR}, @code{USB}, @code{LSB}, @code{RTTY}, @code{RTTYR},
|
|
@code{WFM}, @code{AMS}, @code{PKTLSB}, @code{PKTUSB}, @code{PKTFM},
|
|
@code{ECSSUSB}, @code{ECSSLSB}, @code{FAX}, @code{SAM}, @code{SAL},
|
|
@code{SAH}, @code{DSB}.
|
|
|
|
The @var{TX Passband} is the exact passband frequency in Hertz, or
|
|
@code{0} for the Hamlib backend default. A value of @code{-1} may be
|
|
passed which leaves the rig passband unchanged from the current or
|
|
default value for the mode as defined by the rig.
|
|
|
|
This is a convenience function that combines the effect of
|
|
@command{set_split_freq} and @command{set_split_mode}. It should be
|
|
used when both are required since it allows the back end to optimize
|
|
the operations. For example on many Icom rigs the current VFO must be
|
|
changed temporarily while executing these commands and that can
|
|
disrupt receive or transmit, using this function may minimize that
|
|
disruption.
|
|
|
|
See also @command{set_split_freq} and @command{set_split_mode} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item k, get_split_freq_mode
|
|
Get @var{TX Frequency}, in Hertz for ``split'' frequency operation
|
|
along with the @var{TX Mode} as a string from @command{set_split_mode}
|
|
above and @var{TX Passband} in Hz.
|
|
|
|
This is a convenience function that combines the effect of
|
|
@command{get_split_freq} and @command{get_split_mode}. It should be
|
|
used when both are required since it allows the back end to optimize
|
|
the operations. For example on many Icom rigs the current VFO must be
|
|
changed temporarily while executing these commands and that can
|
|
disrupt receive or transmit, using this function may minimize that
|
|
disruption.
|
|
|
|
See also @command{get_split_freq} and @command{get_split_mode} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item S, set_split_vfo @var{Split}, @var{TX VFO}
|
|
Set @var{Split} mode, @code{0} (off) or @code{1} (on), and @var{TX VFO}
|
|
from @command{set_vfo} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item s, get_split_vfo
|
|
Get @var{Split} mode, @code{0} (off) or @code{1} (on), and @var{TX VFO}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item N, set_ts @var{Tuning Step}
|
|
Set @var{Tuning Step}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item n, get_ts
|
|
Get @var{Tuning Step}, in Hertz.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item U, set_func @var{Func}, @var{Func Status}
|
|
Set @var{Func}, @var{Func Status}.
|
|
|
|
@var{Func} is one of: @code{FAGC}, @code{NB}, @code{COMP}, @code{VOX},
|
|
@code{TONE}, @code{TSQL}, @code{SBKIN}, @code{FBKIN}, @code{ANF},
|
|
@code{NR}, @code{AIP}, @code{APF}, @code{MON}, @code{MN}, @code{RF},
|
|
@code{ARO}, @code{LOCK}, @code{MUTE}, @code{VSC}, @code{REV},
|
|
@code{SQL}, @code{ABM}, @code{BC}, @code{MBC}, @code{RIT}, @code{AFC},
|
|
@code{SATMODE}, @code{SCOPE}, @code{RESUME}, @code{TBURST},
|
|
@code{TUNER}, @code{XIT}.
|
|
|
|
Func Status argument is @code{1} for ``activate'', @code{0} for
|
|
``de-activate'', much as TRUE/FALSE definitions in the C/C++ languages
|
|
(true is non-zero and false is zero).
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Func} will return a space separated list of radio backend
|
|
supported ``set'' functions. Use this to determine the supported
|
|
functions of a given radio backend.
|
|
|
|
@item u, get_func @var{Func}
|
|
Get @var{Func Status}.
|
|
|
|
Returns @var{Func Status} as a non null value for the @var{Func} passed.
|
|
@var{Func} is a token from the list in @command{set_func} above.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Func} will return a space separated list of radio backend
|
|
supported ``get'' functions. Use this to determine the supported
|
|
functions of a given radio backend.
|
|
|
|
@item L, set_level @var{Level}, @var{Level Value}
|
|
Set @var{Level}, @var{Level Value}.
|
|
|
|
@var{Level} is one of: @code{PREAMP}, @code{ATT}, @code{VOX}, @code{AF},
|
|
@code{RF}, @code{SQL}, @code{IF}, @code{APF}, @code{NR}, @code{PBT_IN},
|
|
@code{PBT_OUT}, @code{CWPITCH}, @code{RFPOWER}, @code{MICGAIN},
|
|
@code{KEYSPD}, @code{NOTCHF}, @code{COMP}, @code{AGC}(@code{0}:OFF,
|
|
@code{1}:SUPERFAST, @code{2}:FAST, @code{3}:SLOW, @code{4}:USER,
|
|
@code{5}:MEDIUM, @code{6}:AUTO), @code{BKINDL}, @code{BAL},
|
|
@code{METER}, @code{VOXGAIN}, @code{ANTIVOX}, @code{SLOPE_LOW},
|
|
@code{SLOPE_HIGH}, @code{RAWSTR}, @code{SWR}, @code{ALC},
|
|
@code{STRENGTH}.
|
|
|
|
The @var{Level Value} can be a float or an integer.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Level} will return a space separated list of radio backend
|
|
supported ``set'' levels. Use this to determine the supported levels of a
|
|
given radio backend.
|
|
|
|
@item l, get_level @var{Level}
|
|
Get @var{Level Value}.
|
|
|
|
Returns @var{Level Value} as a float or integer for the @var{Level}
|
|
passed. @var{Level} is a token from the list in @command{set_level}
|
|
above.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Level} will return a space separated list of radio backend
|
|
supported ``get'' levels. Use this to determine the supported levels of a
|
|
given radio backend.
|
|
|
|
@item P, set_parm @var{Parm}, @var{Parm Value}
|
|
Set @var{Parm}, @var{Parm Value}
|
|
|
|
@var{Parm} is one of: @code{ANN}, @code{APO}, @code{BACKLIGHT},
|
|
@code{BEEP}, @code{TIME}, @code{BAT}, @code{KEYLIGHT}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Parm} will return a space separated list of radio backend
|
|
supported ``set'' parameters. Use this to determine the supported
|
|
parameters of a given radio backend.
|
|
|
|
@item p, get_parm @var{Parm}
|
|
Get @var{Parm Value}.
|
|
|
|
Returns @var{Parm Value} as a float or integer for the @var{Parm}
|
|
passed. @var{Parm} is a token from the list in @command{set_parm}
|
|
above.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead
|
|
of @var{Parm} will return a space separated list of radio backend
|
|
supported ``get'' parameters. Use this to determine the supported
|
|
parameters of a given radio backend.
|
|
|
|
@item B, set_bank @var{Bank}
|
|
Set @var{Bank}. Sets the current memory bank number.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item E, set_mem @var{Memory#}
|
|
Set @var{Memory#} channel number.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item e, get_mem
|
|
Get @var{Memory#} channel number.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item G, vfo_op @var{Mem/VFO Op}
|
|
Perform @var{Mem/VFO Op}.
|
|
|
|
@var{Mem/VFO Op}eration is one of: @code{CPY}, @code{XCHG},
|
|
@code{FROM_VFO}, @code{TO_VFO}, @code{MCL}, @code{UP}, @code{DOWN},
|
|
@code{BAND_UP}, @code{BAND_DOWN}, @code{LEFT}, @code{RIGHT},
|
|
@code{TUNE}, @code{TOGGLE}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Mem/VFO Op} will return a space separated list of radio backend
|
|
supported ``set'' Mem/VFO Ops. Use this to determine the supported Mem/VFO
|
|
Ops of a given radio backend.
|
|
|
|
@item g, scan @var{Scan Fct}, @var{Scan Channel}
|
|
Perform @var{Scan Fct} @var{Scan Channel}.
|
|
|
|
Scan function/channel is one of: @code{STOP}, @code{MEM}, @code{SLCT},
|
|
@code{PRIO}, @code{PROG}, @code{DELTA}, @code{VFO}, @code{PLT}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Scan Fct} will return a space separated list of radio backend
|
|
supported Scan Functions. Use this to determine the supported Scan
|
|
Functions of a given radio backend.
|
|
|
|
@item H, set_channel @var{Channel}
|
|
Set memory @var{Channel} data. Not implemented yet.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item h, get_channel
|
|
Get memory @var{Channel} data. Not implemented yet.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item A, set_trn @var{Transceive}
|
|
Set @var{Transceive} mode (reporting event): @code{OFF}, @code{RIG},
|
|
@code{POLL}.
|
|
|
|
@strong{N.B.} Passing a @kbd{?} (query) as the first argument instead of
|
|
@var{Transceive} will return a space separated list of radio backend
|
|
supported Scan Transceive modes. Use this to determine the supported
|
|
Transceive modes of a given radio backend.
|
|
|
|
@item a, get_trn
|
|
Get @var{Transceive} mode (reporting event) as in @command{set_trn}
|
|
above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item Y, set_ant @var{Antenna}
|
|
Set @var{Antenna} number (@code{0}, @code{1}, @code{2}, @dots{}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item y, get_ant
|
|
Get @var{Antenna} number (@code{0}, @code{1}, @code{2}, @dots{}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item *, reset @var{Reset}
|
|
Perform rig @var{Reset}.
|
|
|
|
@code{0} = None, @code{1} = Software reset, @code{2} = @acronym{VFO}
|
|
reset, @code{4} = Memory Clear reset, @code{8} = Master reset. Since
|
|
these values are defined as a bitmask in @file{rig.h}, it should be
|
|
possible to @code{AND} these values together to do multiple resets at
|
|
once, if the backend supports it or supports a reset action via rig
|
|
control at all.
|
|
|
|
@item b, send_morse @var{Morse}
|
|
Send @var{Morse} symbols.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x87, set_powerstat @var{Power Status}
|
|
Set power On/Off/Standby @var{Power Status}.
|
|
|
|
@code{0} = Power Off, @code{1} = Power On, @code{2} = Power Standby.
|
|
Defined as a bitmask in @file{rig.h}.
|
|
|
|
@item 0x88, get_powerstat
|
|
Get power On/Off/Standby @var{Power Status} as in
|
|
@command{set_powerstat} above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x89, send_dtmf @var{Digits}
|
|
Set DTMF @var{Digits}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item 0x8a, recv_dtmf
|
|
Get DTMF @var{Digits}.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item _, get_info
|
|
Get misc information about the rig
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item 1, dump_caps
|
|
Not a real rig remote command, it just dumps capabilities, i.e. what
|
|
the backend knows about this model, and what it can do.
|
|
|
|
TODO: Ensure this is in a consistent format so it can be read into a
|
|
hash, dictionary, etc. Bug reports requested.
|
|
|
|
@strong{N.B.} This command will produce many lines of output so be
|
|
very careful if using a fixed length array! For example, running this
|
|
command against the Dummy backend results in over 5kB of text output.
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item 2, power2mW @var{Power 0.0..1.0}, @var{Frequency}, @var{Mode}
|
|
Returns @var{Power mW}
|
|
|
|
Converts a @var{Power} value in a range of @code{0.0..1.0} to
|
|
the real transmit power in milli-Watts (integer). The @var{Frequency}
|
|
and @var{Mode} also need to be provided as output power may vary
|
|
according to these values.
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item 4, mW2power @var{Power mW}, @var{Frequency}, @var{Mode}
|
|
Returns @var{Power 0.0..1.0}
|
|
|
|
Converts the real transmit power in milli-Watts (integer) to a
|
|
@var{Power} value in a range of @code{[0.0..1.0]}. The
|
|
@var{Frequency} and @var{Mode} also need to be provided as output
|
|
power may vary according to these values.
|
|
|
|
@acronym{VFO} parameter not used in '@acronym{VFO} mode'.
|
|
|
|
@item w, send_cmd @var{Cmd}
|
|
Send raw command string to rig. This is useful for testing and
|
|
troubleshooting rig commands and responses when developing a backend.
|
|
|
|
For binary protocols enter values as @code{\0xAA\0xBB}. Expect a
|
|
@var{Reply} from the rig which will likely be a binary block or an
|
|
@acronym{ASCII} string depending on the rig's protocol (see your
|
|
radio's computer control documentation).
|
|
|
|
The command terminator, set by the @option{--send-cmd-term} option
|
|
above, will terminate each command string sent to the radio. This
|
|
character should not be a part of the input string.
|
|
|
|
@item chk_vfo
|
|
Returns @code{CHKVFO 1} (single line only) if rigctld was invoked with
|
|
the @option{-o} or @option{--vfo} option, @code{CHKVFO 0} if not.
|
|
|
|
@end table
|
|
|
|
@node rigctld protocol
|
|
@subsection @command{rigctld} protocol
|
|
@cindex @command{rigctld} protocol
|
|
@cindex protocol, @command{rigctld}
|
|
|
|
Two protocols exist for communicating with @command{rigctld}. The
|
|
``Default'' protocol is primarily used internally by Hamlib so an
|
|
application that is not written to use @command{rigctld} directly via
|
|
@acronym{TCP} network sockets can still access @command{rigctld}. The
|
|
other ``Extended Response Protocol'' is intended for the more general
|
|
use case where a variety of response formats may be needed.
|
|
|
|
|
|
@menu
|
|
* rigctld Default protocol::
|
|
* rigctld Extended Response protocol::
|
|
@end menu
|
|
|
|
@node rigctld Default protocol
|
|
@subsubsection @command{rigctld} Default protocol
|
|
@cindex @command{rigctld} Default protocol
|
|
@cindex Default protocol, @command{rigctld}
|
|
|
|
The @command{rigctld} protocol is intentionally simple. Commands are
|
|
entered on a single line with any needed values. In Perl, for exampl,
|
|
reliable results are obtained by terminating each command string with
|
|
a newline character, @samp{\n}.
|
|
|
|
@noindent
|
|
Example @code{set} (Perl code):
|
|
|
|
@example
|
|
print $socket "F 14250000\n";
|
|
print $socket "\\set_mode LSB 2400\n"; # escape leading '\'
|
|
@end example
|
|
|
|
@noindent
|
|
A one line response will be sent as a reply to @code{set} commands,
|
|
@samp{RPRT x\n} where @samp{x} is the Hamlib error code with @samp{0}
|
|
indicating success of the command.
|
|
|
|
@noindent
|
|
Responses from @command{rigctld} get commands are text values and
|
|
match the same tokens used in the @code{set} commands. Each value
|
|
is returned on its own line. On error the string @samp{RPRT x\n} is
|
|
returned where @samp{x} is the Hamlib error code.
|
|
|
|
@noindent
|
|
Example @code{get} (Perl code):
|
|
|
|
@example
|
|
print $socket "f\n";
|
|
"14250000\n"
|
|
@end example
|
|
|
|
@noindent
|
|
Most @code{get} functions return one to three values. A notable
|
|
exception is the @command{dump_caps} command which returns many lines
|
|
of @samp{key:value} pairs.
|
|
|
|
This protocol is primarily used by the @code{NET rigctl}
|
|
(@command{rigctl} model 2) backend which allows applications already
|
|
written for Hamlib's C @acronym{API} to take advantage of
|
|
@command{rigctld} without the need of rewriting application code. An
|
|
application's user can select rig model 2 (@code{NET rigctl}) and then
|
|
set @option{rig_pathname} to @kbd{localhost:4532} or other network
|
|
host:port (set by the @option{-t} option above).
|
|
|
|
@node rigctld Extended Response protocol
|
|
@subsubsection @command{rigctld} Extended Response Protocol
|
|
@cindex @command{rigctld} Extended Response Protocol
|
|
@cindex Extended Response Protocol, @command{rigctld}
|
|
|
|
An EXPERIMENTAL Extended Response protocol has been introduced into
|
|
@command{rigctld} as of February 16, 2010. This protocol adds several
|
|
rules to the strings returned by @command{rigctld} and adds a rule for
|
|
the command syntax.
|
|
|
|
@enumerate
|
|
@item
|
|
The command received by @command{rigctld} is echoed with its long
|
|
command name followed by the value(s) (if any) received from the
|
|
client terminated by the specified response separator as the record
|
|
line of the response.
|
|
|
|
@item
|
|
The last line of each block is the string @samp{RPRT x\n} where
|
|
@samp{x} is the numeric return value of the Hamlib backend function
|
|
that was called by the command.
|
|
|
|
@item
|
|
Any records consisting of data values returned by the rig backend are
|
|
prepended by a string immediately followed by a colon then a space and
|
|
then the value terminated by the response
|
|
separator. e.g. @samp{Frequency: 14250000\n} when the command was
|
|
prepended by @code{+}.
|
|
|
|
@item
|
|
All commands received will be acknowledged by @command{rigctld} with
|
|
lines from rules 1 and 2. Lines from rule 3 are only returned when
|
|
data values must be returned to the client.
|
|
|
|
@end enumerate
|
|
|
|
An example response to a @command{+\set_mode} command sent from the
|
|
shell prompt (note the prepended @code{+}):
|
|
|
|
@example
|
|
echo "+M USB 2400" | nc -w 1 localhost 4532
|
|
set_mode: USB 2400
|
|
RPRT 0
|
|
@end example
|
|
|
|
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.
|
|
|
|
An example response to a @command{\get_mode} query:
|
|
|
|
@example
|
|
echo "+\get_mode" | nc -w 1 localhost 4532
|
|
get_mode:
|
|
Mode: USB
|
|
Passband: 2400
|
|
RPRT 0
|
|
@end example
|
|
|
|
In this case, as no value is passed to @command{rigctld}, the first
|
|
line consists only of the long command name. The final line shows
|
|
that the command was processed successfully by the rig backend.
|
|
|
|
Invoking the Extended Response protocol requires prepending a command
|
|
with a punctuation character. As shown in the examples above,
|
|
prepending a '@code{+} character to the command results in the
|
|
responses being separated by a newline character (@samp{\n}). Any
|
|
other punctuation character recognized by the C @code{ispunct()}
|
|
function except @code{\}, @code{?}, or @code{_} will cause that
|
|
character to become the response separator and the entire response
|
|
will be on one line.
|
|
|
|
Separator character summary:
|
|
|
|
@table @code
|
|
@item +
|
|
Each record of the response is appended with a newline (@samp{\n}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item ;, |, or ,
|
|
Each record of the response is appended by the given character
|
|
resulting in entire response on one line.
|
|
|
|
Common record separators for text representations of spreadsheet data,
|
|
etc.
|
|
|
|
@item ?
|
|
Reserved for 'help' in @command{rigctl} short command.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item _
|
|
Reserved for @command{\get_info} in @command{rigctl} short command.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item #
|
|
Reserved for comments when reading a command file script.
|
|
|
|
@end table
|
|
|
|
Other punctuation characters have not been tested! Use at your own
|
|
risk.
|
|
|
|
For example, invoking a @command{;\get_mode} query with a leading
|
|
@code{;} returns:
|
|
|
|
@example
|
|
get_mode:;Mode: USB;Passband: 2400;RPRT 0
|
|
@end example
|
|
|
|
Or, using the vertical bar (pipe) character @code{|} returns:
|
|
|
|
@example
|
|
get_mode:|Mode: USB|Passband: 2400|RPRT 0
|
|
@end example
|
|
|
|
And a @command{\set_mode} command prepended with a @code{|} returns:
|
|
|
|
@example
|
|
set_mode: USB 2400|RPRT 0
|
|
@end example
|
|
|
|
Such a format will allow reading a response as a single event using a
|
|
preferred response separator. Other punctuation characters have not
|
|
been tested!
|
|
|
|
|
|
@node rotctld
|
|
@section @command{rotctld}
|
|
@cindex rotctld
|
|
|
|
The @command{rotctld} program is a network server that accepts the
|
|
familiar commands of @command{rotctl} and provides the response data
|
|
over a @acronym{TCP/IP} network socket to an application. In this
|
|
manner an application can access a @command{rotctl} instance from
|
|
nearly anywhere (caveat, no security is currently provided by
|
|
@command{rotctl}). Applications using @command{rotctl} do not link to
|
|
Hamlib nor use its C API.
|
|
|
|
@menu
|
|
* Introduction to rotctld::
|
|
* rotctld invocation::
|
|
* rotctld command line options::
|
|
* rotctld commands::
|
|
* rotctld protocol::
|
|
@end menu
|
|
|
|
@node Introduction to rotctld
|
|
@subsection Introduction to @command{rotctld}
|
|
@cindex Introduction to @command{rotctld}
|
|
@cindex @command{rotctld}, introduction to
|
|
|
|
@command{rotctld} communicates to a client through a @acronym{TCP}
|
|
socket using text commands shared with @command{rotctl}. The protocol
|
|
is simple, commands are sent to @command{rotctld} on one line and
|
|
@command{rotctld} responds to ``get'' commands with the requested
|
|
values, one per line, when successful, otherwise, it responds with one
|
|
line @samp{RPRT x}, where @samp{x} is a negative number indicating the
|
|
error code. Commands that do not return values respond with the line
|
|
@samp{RPRT x}, where @samp{x} is zero when successful, otherwise is a
|
|
regative number indicating the error code. Each line is terminated
|
|
with a newline @code{\n} character. This protocol is primarily for
|
|
use by the @code{NET rotctl} (rot model 2) backend. @xref{rotctld
|
|
Default protocol}.
|
|
|
|
A separate Extended Response protocol extends the above behavior by
|
|
echoing the received command string as a header, any returned values
|
|
as a key: value pair, and the @samp{RPRT x} string as the end of
|
|
response marker which includes the Hamlib success or failure value.
|
|
Consider using this protocol for clients that will interact with
|
|
@command{rotctld} directly through a @acronym{TCP} network socket.
|
|
@xref{rotctld Extended Response protocol}.
|
|
|
|
@node rotctld invocation
|
|
@subsection @command{rotctld} invocation
|
|
@cindex @command{rotctld} invocation
|
|
@cindex invocation, @command{rotctld}
|
|
|
|
The command line invocation for @command{rotctld} is similar to
|
|
@command{rotctl} except that in POSIX environments a trailing @kbd{&}
|
|
is appended to the command string to ``background'' the
|
|
@command{rotctld} process so the shell can be used to run other
|
|
commands while @command{rotctld} continues to run.
|
|
|
|
Here are some examples for invoking @command{rotctld}.
|
|
|
|
Start @command{rotctld} for a Ham IV rotor with the RotorEZ installed
|
|
using a USB-to-serial adapter and backgrounding:
|
|
|
|
@example
|
|
rotctld -m 401 -r /dev/ttyUSB1 &
|
|
@end example
|
|
|
|
Start @command{rotctld} for RotorEZ using @code{COM2} on MS Windows:
|
|
|
|
@example
|
|
rotctl -m 401 -r COM2 -T 127.0.0.1 -t 4533
|
|
@end example
|
|
|
|
@quotation Note
|
|
On MS Windows the use of the @option{-T} and @option{-t} options appear
|
|
to be necessary to set the @acronym{IP} address and @acronym{TCP} port
|
|
or else the network socket cannot be found. On @acronym{POSIX} systems
|
|
the @command{rotctld} default values will be used.
|
|
@end quotation
|
|
|
|
Connect to the already running rotctld, and set position to 135.0
|
|
degrees azimuth and 30.0 degrees elevation with a 1 second read
|
|
timeout from the shell prompt:
|
|
|
|
@example
|
|
echo "\set_pos 135.0 30.0" | nc -w 1 localhost 4533
|
|
@end example
|
|
|
|
Connect to a running @command{rotctld} with @command{rotctl} on the
|
|
local host:
|
|
|
|
@example
|
|
rotctl -m2
|
|
@end example
|
|
|
|
@node rotctld command line options
|
|
@subsection @command{rotctld} command line options
|
|
@cindex @command{rotctld} command line options
|
|
@cindex Command line options, @command{rotctld}
|
|
|
|
Many of the @command{rotctld} command line options are shared
|
|
with @command{rotctl} with a few additions.
|
|
|
|
@command{rotctld} accepts the following options:
|
|
|
|
@table @option
|
|
@item -m
|
|
@itemx --model=@var{id}
|
|
Select rotator model number. See model list (use @kbd{rotctl -l}).
|
|
|
|
@strong{N.B.} @command{rotctl} (or third party software) will use
|
|
rotor model 2 for NET rotctl (@command{rotctld}).
|
|
|
|
@item -r
|
|
@itemx --rot-file=@var{device}
|
|
Use @var{device} as the file name of the port the rotor is connected.
|
|
Often a serial port, but could be a USB to serial adapter. Typically
|
|
@file{/dev/ttyS0} , @file{/dev/ttyS1} , @file{/dev/ttyUSB0} , etc.@:
|
|
on Linux or @file{COM1} , @file{COM2} , etc.@: on MS Windows. The
|
|
special string @kbd{uh-rig} may be given to enable micro-ham device
|
|
support.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -s
|
|
@itemx --serial-speed=@var{baud}
|
|
Set serial speed to @var{baud} rate. Uses @strong{maximum} serial
|
|
speed from rotor backend capabilities as the default.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -T
|
|
@itemx --listen-addr=@var{IPADDR}
|
|
Use @var{IPADDR} as the listening @acronym{IP} address. The default is ANY.
|
|
|
|
@strong{N.B.} On MS Windows setting a specific @acronym{IP} address is
|
|
likely necessary.
|
|
|
|
@item -t
|
|
@itemx --port=@var{number}
|
|
Use @var{number} as the @acronym{TCP} listening port. The default is
|
|
@code{4533}.
|
|
|
|
@strong{N.B.} As @command{rigctld}'s default port is @code{4532}, it
|
|
is advisable to use odd numbered ports for @command{rotctld}, e.g.
|
|
@code{4533}, @code{4535}, @code{4537}, etc.
|
|
|
|
@item -L
|
|
@itemx --show-conf
|
|
List all config parameters for the rotor defined with @option{-m}
|
|
above.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -C
|
|
@itemx --set-conf=@var{parm}=@var{val}[,@var{parm}=@var{val},@dots{}]
|
|
Set config parameter. e.g.@: @code{stop_bits=2}
|
|
|
|
Use @option{-L} option for a list.
|
|
|
|
@item -l
|
|
@itemx --list
|
|
List all model numbers defined in Hamlib and exit. As of 1.2.15.1 the
|
|
list is sorted by model number.
|
|
|
|
@strong{N.B.} In Linux the list can be scrolled back using
|
|
@kbd{@key{SHIFT}-PageUp}/ @kbd{@key{SHIFT}-PageDown}, or using the
|
|
scrollbars of a virtual terminal in X or the @command{cmd} window in
|
|
MS Windows. The output can be piped to '@command{more}' or
|
|
'@command{less}', e.g.@: '@kbd{rotctl -l | more}'.
|
|
|
|
@item -u
|
|
@itemx --dump-caps
|
|
Dump capabilities for the rotor defined with @option{-m} above and
|
|
exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Set verbose mode level, cumulative i.e.@: @option{-vvvvv} sets maximum
|
|
debugging output to @file{stderr}.
|
|
|
|
Five different levels of diagnostics can be output to @file{stderr}
|
|
and correspond to @option{-v} for @code{BUG}, @option{-vv} for
|
|
@code{ERR}, @option{-vvv} for @code{WARN}, @option{-vvvv} for
|
|
@code{VERBOSE}, or @option{-vvvvv} for @code{TRACE}. Back end authors
|
|
will use the verbose facility to print critical values useful for
|
|
testing and will often ask for this output in response to a request
|
|
for help.
|
|
|
|
@item -Z
|
|
@itemx --debug-time-stamps
|
|
Enable time stamps on debug output.
|
|
|
|
@item -h
|
|
@itemx --help
|
|
Show summary of these options and exit.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show version of @command{rotctl} and exit.
|
|
@end table
|
|
|
|
@quotation Note
|
|
Some options may not be implemented by a given backend and will return
|
|
an error. This is most likely to occur with the @option{--set-conf}
|
|
and @option{--show-conf} options.
|
|
@end quotation
|
|
|
|
@node rotctld commands
|
|
@subsection @command{rotctld} commands
|
|
@cindex @command{rotctld} commands
|
|
@cindex commands, @command{rotctld}
|
|
|
|
Commands can be sent over the @acronym{TCP} socket either as a single
|
|
char, or as a long command name plus the value(s) space separated on
|
|
one @code{\n} terminated line. @xref{rotctld protocol}.
|
|
|
|
Since most of the Hamlib operations have a ``set'' and a ``get''
|
|
method, in general an upper case letter will be used for set methods
|
|
whereas the corresponding lower case letter refers to the get method.
|
|
Each operation also has a long name; in interactive mode, prepend a
|
|
backslash @kbd{\} to enter a long command name.
|
|
|
|
Example (Perl):
|
|
|
|
@example
|
|
print $socket "\\dump_caps\n";
|
|
@end example
|
|
|
|
@noindent
|
|
to see what the rotor's backend can do.
|
|
|
|
@quotation N.B.
|
|
In Perl and many other languages a @kbd{\} will need to
|
|
be escaped with a preceding @kbd{\} so that even though two backslash
|
|
characters appear in the code, only one will be passed to
|
|
@command{rotctld}. This is a possible bug, so beware!
|
|
@end quotation
|
|
|
|
Be aware that the backend for the rotor to be controlled, or the rotor
|
|
itself may not support some commands. In that case, the operation will
|
|
fail with a Hamlib error message.
|
|
|
|
@strong{Rotor commands}
|
|
|
|
Here is a summary of the supported commands:
|
|
|
|
@table @command
|
|
@itemize
|
|
@item
|
|
Command short name is followed by the long name which is followed by
|
|
any variable names.
|
|
|
|
@item
|
|
While a comma is used to separate variable names in this document,
|
|
they are not part of the command syntax used by @command{rotctl}. Use
|
|
a space to separate values.
|
|
|
|
@item
|
|
In the case of ``set'' commands the variable @var{name} is replaced by
|
|
the value in the description.
|
|
|
|
@item
|
|
In the case of ``get'' commands the variable @var{name} is the key
|
|
name of the value returned.
|
|
|
|
@end itemize
|
|
|
|
@item P, set_pos @var{Azimuth}, @var{Elevation}
|
|
Set position: @var{Azimuth} and @var{Elevation} as double precision
|
|
floating point values.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item p, get_pos
|
|
Get position: @var{Azimuth} and @var{Elevation} as double precision
|
|
floating point values.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item M, move @var{Direction}, @var{Speed}
|
|
Move the rotator in a specific direction at the given rate.
|
|
|
|
Values are integers where @var{Direction} is defined as @code{2} = Up,
|
|
@code{4} = Down, @code{8} = Left, and @code{16} = Right. @var{Speed}
|
|
is an integer between @code{1} and @code{100}.
|
|
|
|
@strong{N.B.} Not all backends that implement the move command use the
|
|
Speed value. At this time only the gs232a utilizes the Speed
|
|
parameter.
|
|
|
|
@item S, stop
|
|
Stop the rotator.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item K, park
|
|
Park the antenna.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item C, set_conf @var{Token}, @var{Value}
|
|
Set a configuration parameter. It is safe to give @var{Token} a value
|
|
of @code{0} (zero). @var{Value} may be a string up to 20 characters.
|
|
|
|
See @option{-L} output.
|
|
|
|
@item R, reset @var{Reset}
|
|
Reset the rotator.
|
|
|
|
Integer value of @code{1} for Reset All.
|
|
|
|
@item _, get_info
|
|
Get misc information on the rotator.
|
|
|
|
At the moment returns @var{Model Name}.
|
|
|
|
@item w, send_cmd @var{Cmd}
|
|
Send raw command string to the rotator.
|
|
|
|
@code{<CR>} (or @option{send-cmd-term}, see @option{-t} option) is
|
|
appended automatically at the end of the command for text protocols.
|
|
For binary protocols, enter values as @code{\0xAA\0xBB}.
|
|
@end table
|
|
|
|
@strong{Locator Commands}
|
|
|
|
These commands offer conversions of Degrees Minutes Seconds to other
|
|
formats, Maidenhead square locator conversions and distance and
|
|
azimuth conversions.
|
|
|
|
@table @command
|
|
@item L, lonlat2loc @var{Longitude}, @var{Latitude}, @var{Loc Len 2..12}
|
|
Returns the Maidenhead locator for the given @var{Longitude} and
|
|
@var{Latitude}.
|
|
|
|
Both are floating point values. The precision of the returned square
|
|
is controlled by @var{Loc Len} which should be an even numbered
|
|
integer value between @code{2} and @code{12}.
|
|
|
|
For example, @kbd{+L -170.000000 -85.000000 12\n} returns
|
|
@samp{Locator: AA55AA00AA00\n}.
|
|
|
|
@item l, loc2lonlat @var{Locator}
|
|
Returns @var{Longitude} and @var{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.
|
|
|
|
For example, @kbd{+l AA55AA00AA00} returns @samp{Longitude:
|
|
-169.999983\nLatitude: -84.999991\n}.
|
|
|
|
@item D, dms2dec @var{Degrees}, @var{Minutes}, @var{Seconds}, @var{S/W}
|
|
Returns @var{Dec Degrees}, a signed floating point value.
|
|
|
|
@var{Degrees} and @var{Minutes} are integer values and @var{Seconds}
|
|
is a floating point value. @var{S/W} is a flag with @code{1}
|
|
indicating South latitude or West longitude and @code{0} North or East
|
|
(the flag is needed as computers don't recognize a signed zero even
|
|
though only the @var{Degrees} value only is typically signed in
|
|
@acronym{DMS} notation).
|
|
|
|
@item d, dec2dms @var{Dec Degrees}
|
|
Returns @var{Degrees}, @var{Minutes}, @var{Seconds}, @var{S/W}.
|
|
|
|
Values are as in @command{dms2dec} above.
|
|
|
|
@item E, dmmm2dec @var{Degrees}, @var{Dec Minutes}, @var{S/W}
|
|
Returns @var{Dec Degrees}, a signed floating point value.
|
|
|
|
@var{Degrees} is an integer value and @var{Minutes} is a floating
|
|
point value. @var{S/W} is a flag with @code{1} indicating South
|
|
latitude or West longitude and @code{0} North or East (the flag is
|
|
needed as computers don't recognize a signed zero even though only the
|
|
@var{Degrees} value only is typically signed in @acronym{DMS}
|
|
notation).
|
|
|
|
@item e, dec2dmmm @var{Dec Deg}
|
|
Returns @var{Degrees}, @var{Minutes}, @var{S/W}.
|
|
|
|
Values are as in @command{dmmm2dec} above.
|
|
|
|
@item B, qrb @var{Lon 1}, @var{Lat 1}, @var{Lon 2}, @var{Lat 2}
|
|
Returns @var{Distance} and @var{Azimuth} where @var{Distance} is in km
|
|
and @var{Azimuth} is in degrees.
|
|
|
|
All @var{Lon}/@var{Lat} values are signed floating point numbers.
|
|
|
|
@item A, a_sp2a_lp @var{Short Path Deg}
|
|
Returns @var{Long Path Deg} or @code{-RIG_EINVAL} upon input error.
|
|
|
|
Both are floating point values within the range @code{0.00} to
|
|
@var{360.00}.
|
|
|
|
@item a, d_sp2d_lp @var{Short Path km}
|
|
Returns @var{Long Path km}.
|
|
|
|
Both are floating point values.
|
|
@end table
|
|
|
|
|
|
@node rotctld protocol
|
|
@subsection @command{rotctld} protocol
|
|
@cindex @command{rotctld} protocol
|
|
@cindex protocol, @command{rotctld}
|
|
|
|
Two protocols exist for communicating with @command{rotctld}. The
|
|
``Default'' protocol is primarily used internally by Hamlib so an
|
|
application that is not written to use @command{rotctld} directly via
|
|
@acronym{TCP} network sockets can still access @command{rotctld}. The
|
|
other ``Extended Response Protocol'' is intended for the more general
|
|
use case where a variety of response formats may be needed.
|
|
|
|
|
|
@menu
|
|
* rotctld Default protocol::
|
|
* rotctld Extended Response protocol::
|
|
@end menu
|
|
|
|
@node rotctld Default protocol
|
|
@subsubsection @command{rotctld} Default protocol
|
|
@cindex @command{rotctld} Default protocol
|
|
@cindex Default protocol, @command{rotctld}
|
|
|
|
The @command{rotctld} protocol is intentionally simple. Commands are
|
|
entered on a single line with any needed values. In Perl, for exampl,
|
|
reliable results are obtained by terminating each command string with
|
|
a newline character, @samp{\n}.
|
|
|
|
@noindent
|
|
Example @code{set} (Perl code):
|
|
|
|
@example
|
|
print $socket "P 135 10\n";
|
|
print $socket "\\set_pos 135 10\n"; # escape leading '\'
|
|
@end example
|
|
|
|
@noindent
|
|
A one line response will be sent as a reply to @code{set} commands,
|
|
@samp{RPRT x\n} where @samp{x} is the Hamlib error code with @samp{0}
|
|
indicating success of the command.
|
|
|
|
@noindent
|
|
Responses from @command{rotctld} get commands are text values and
|
|
match the same tokens used in the @code{set} commands. Each value
|
|
is returned on its own line. On error the string @samp{RPRT x\n} is
|
|
returned where @samp{x} is the Hamlib error code.
|
|
|
|
@noindent
|
|
Example @code{get} (Perl code):
|
|
|
|
@example
|
|
print $socket "p\n";
|
|
"135"
|
|
"10"
|
|
@end example
|
|
|
|
@noindent
|
|
Most @code{get} functions return one to four values. A notable
|
|
exception is the @command{dump_caps} command which returns many lines
|
|
of @samp{key:value} pairs.
|
|
|
|
This protocol is primarily used by the @code{NET rotctl}
|
|
(@command{rotctl} model 2) backend which allows applications already
|
|
written for Hamlib's C @acronym{API} to take advantage of
|
|
@command{rotctld} without the need of rewriting application code. An
|
|
application's user can select rotor model 2 (@code{NET rotctl}) and then
|
|
set @option{rig_pathname} to @kbd{localhost:4533} or other network
|
|
host:port (set by the @option{-t} option above).
|
|
|
|
@node rotctld Extended Response protocol
|
|
@subsubsection @command{rotctld} Extended Response Protocol
|
|
@cindex @command{rotctld} Extended Response Protocol
|
|
@cindex Extended Response Protocol, @command{rotctld}
|
|
|
|
An EXPERIMENTAL Extended Response protocol has been introduced into
|
|
@command{rotctld} as of February 10, 2010. This protocol adds several
|
|
rules to the strings returned by @command{rotctld} and adds a rule for
|
|
the command syntax.
|
|
|
|
@enumerate
|
|
@item
|
|
The command received by @command{rotctld} is echoed with its long
|
|
command name followed by the value(s) (if any) received from the
|
|
client terminated by the specified response separator as the record
|
|
line of the response.
|
|
|
|
@item
|
|
The last line of each block is the string @samp{RPRT x\n} where
|
|
@samp{x} is the numeric return value of the Hamlib backend function
|
|
that was called by the command.
|
|
|
|
@item
|
|
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 value terminated by the response
|
|
separator. e.g. @samp{Azimuth: 90.000000\n} when the command was
|
|
prepended by @code{+}.
|
|
|
|
@item
|
|
All commands received will be acknowledged by @command{rotctld} with
|
|
lines from rules 1 and 2. Lines from rule 3 are only returned when
|
|
data values must be returned to the client.
|
|
|
|
@end enumerate
|
|
|
|
An example response to a @command{+P} command sent from the
|
|
shell prompt (note the prepended @code{+}):
|
|
|
|
@example
|
|
echo "+P 90 45" | nc -w 1 localhost 4533
|
|
set_pos: 90 45
|
|
RPRT 0
|
|
@end example
|
|
|
|
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 rotor backend return value indicating success.
|
|
|
|
An example response to a @command{+\get_pos} query:
|
|
|
|
@example
|
|
echo "+\get_pos" | nc -w 1 localhost 4533
|
|
get_pos:
|
|
Azimuth: 90.000000
|
|
Elevation: 45.000000
|
|
RPRT 0
|
|
@end example
|
|
|
|
In this case, as no value is passed to @command{rotctld}, the first
|
|
line consists only of the long command name. The final line shows
|
|
that the command was processed successfully by the rig backend.
|
|
|
|
Invoking the Extended Response protocol requires prepending a command
|
|
with a punctuation character. As shown in the examples above,
|
|
prepending a '@code{+} character to the command results in the
|
|
responses being separated by a newline character (@samp{\n}). Any
|
|
other punctuation character recognized by the C @code{ispunct()}
|
|
function except @code{\}, @code{?}, or @code{_} will cause that
|
|
character to become the response separator and the entire response
|
|
will be on one line.
|
|
|
|
Separator character summary:
|
|
|
|
@table @code
|
|
@item +
|
|
Each record of the response is appended with a newline (@samp{\n}).
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item ;, |, or ,
|
|
Each record of the response is appended by the given character
|
|
resulting in entire response on one line.
|
|
|
|
Common record separators for text representations of spreadsheet data,
|
|
etc.
|
|
|
|
@item ?
|
|
Reserved for 'help' in @command{rotctl} short command.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item _
|
|
Reserved for @command{\get_info} in @command{rotctl} short command.
|
|
@ifhtml
|
|
@*
|
|
@end ifhtml
|
|
|
|
@item #
|
|
Reserved for comments when reading a command file script.
|
|
|
|
@end table
|
|
|
|
Other punctuation characters have not been tested! Use at your own
|
|
risk.
|
|
|
|
For example, invoking a @command{;\get_pos} query with a leading
|
|
@code{;} returns:
|
|
|
|
@example
|
|
get_pos:;Azimuth: 90.000000;Elevation: 45.000000;RPRT 0
|
|
@end example
|
|
|
|
Or, using the vertical bar (pipe) character @code{|} returns:
|
|
|
|
@example
|
|
get_pos:|Azimuth: 90.000000|Elevation: 45.000000|RPRT 0
|
|
@end example
|
|
|
|
And a @command{\set_pos} command prepended with a @code{|} returns:
|
|
|
|
@example
|
|
set_pos: 135 22.5|RPRT 0
|
|
@end example
|
|
|
|
Such a format will allow reading a response as a single event using a
|
|
preferred response separator. Other punctuation characters have not
|
|
been tested!
|
|
|
|
All commands with the exception of @command{\set_conf} have been
|
|
tested with the Extended Response protocol and the included
|
|
@file{testrotctld.pl} script.
|