mirror of
https://github.com/Hamlib/Hamlib
synced 2026-08-13 17:32:05 -04:00
5a79fcdbe1
The Texinfo manual is now kept in sync with the project information manual pages. The Texinfo manual may be retired at some later date but for now the two sets of documentation will be kept in sync.
571 lines
18 KiB
Text
571 lines
18 KiB
Text
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 (Application
|
|
Programming Interface) 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 rotator back
|
|
ends and the two network daemons, @command{rigctld} and
|
|
@command{rotcltd} for radio and rotator access via network sockets.
|
|
Also included are three demonstation utilities, @command{rigmem},
|
|
@command{rigsmtr}, and @command{rigswr} which provide functional
|
|
examples of how Hamlib may be used to accomplish various tasks.
|
|
|
|
|
|
@menu
|
|
* rigctl::
|
|
* rotctl::
|
|
* rigctld::
|
|
* rotctld::
|
|
* rigmem::
|
|
* rigsmtr::
|
|
* rigswr::
|
|
@end menu
|
|
|
|
@node rigctl
|
|
@section @command{rigctl}
|
|
@cindex rigctl
|
|
|
|
@command{rigctl} is the most frequently used Hamlib utility. As the
|
|
other ctl 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 reference::
|
|
@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{https://tiswww.case.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 Microsoft
|
|
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
|
|
Microsoft 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 reference
|
|
@subsection @command{rigctl} reference
|
|
@cindex @command{rigctl} reference
|
|
@cindex reference, @command{rigctl}
|
|
|
|
The complete reference for @command{rigctl} can be found in the
|
|
@kbd{rigctl}(1) Unix manual page.
|
|
|
|
|
|
@node rotctl
|
|
@section @command{rotctl}
|
|
@cindex rotctl
|
|
|
|
Identical in function to @command{rigctl}, @command{rotctl} provides a
|
|
means for testing Hamlib functions useful for rotator control and
|
|
@acronym{QTH} (Maidenhead gridsquare system, see
|
|
@url{https://en.wikipedia.org/wiki/Maidenhead_Locator_System,
|
|
Maidenhead Locator System}) locator computations. As rotators have a
|
|
much narrower scope than radios, there are fewer command line options
|
|
and commands for @command{rotctl}.
|
|
|
|
@menu
|
|
* Introduction to rotctl::
|
|
* rotctl reference::
|
|
@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 rotator'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}. Interactive mode allows for command
|
|
editing and history recall through the use of the @url{
|
|
https://tiswww.case.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
|
|
rotator model. This is a feature where the Hamlib internal rotator
|
|
dummy is used instead. The dummy rotator provides a way to test
|
|
Hamlib functions with out the need for actual rotator hardware.
|
|
However, to develop back end capability for a given rotator, having
|
|
the actual controller 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 rotator back end model. The @option{-r} option takes the path to
|
|
the port device on @acronym{POSIX} or 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}
|
|
Rot # 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 reference
|
|
@subsection @command{rotctl} reference
|
|
@cindex @command{rotctl} reference
|
|
@cindex reference, @command{rotctl}
|
|
|
|
The complete reference for @command{rotctl} can be found in the
|
|
@kbd{rotctl}(1) Unix manual page.
|
|
|
|
|
|
@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{rigctld} instance from
|
|
nearly anywhere (caveat, no security is currently provided by
|
|
@command{rigctld}). Applications using @command{rigctld} do not link
|
|
directly to Hamlib nor use its C API.
|
|
|
|
@menu
|
|
* Introduction to rigctld::
|
|
* rigctld reference::
|
|
@end menu
|
|
|
|
@node Introduction to rigctld
|
|
@subsection Introduction to @command{rigctld}
|
|
@cindex Introduction to @command{rigctld}
|
|
@cindex @command{rigctld}, introduction to
|
|
|
|
@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 negative 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} (radio model 2) backend.
|
|
|
|
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.
|
|
|
|
Multiple radios can be controlled on different @acronym{TCP} ports by
|
|
use of multiple @command{rigctld} processes each listening on a unique
|
|
@acronym{TCP} port. 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.
|
|
|
|
@node rigctld reference
|
|
@subsection @command{rigctld} reference
|
|
@cindex @command{rigctld} reference
|
|
@cindex reference, @command{rigctld}
|
|
|
|
The complete reference for @command{rigctld} can be found in the
|
|
@kbd{rigctld}(1) Unix manual page.
|
|
|
|
|
|
@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{rotctld} instance from
|
|
nearly anywhere (caveat, no security is currently provided by
|
|
@command{rotctld}). Applications using @command{rotctld} do not link
|
|
directly to Hamlib nor use its C API.
|
|
|
|
@menu
|
|
* Introduction to rotctld::
|
|
* rotctld reference::
|
|
@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}
|
|
network 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
|
|
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 negative 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 rotctl} (rot model 2) backend.
|
|
|
|
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.
|
|
|
|
Multiple rotators can be controlled on different @acronym{TCP} ports by
|
|
use of multiple @command{rotctld} processes each listening on a unique
|
|
@acronym{TCP} port. It is hoped that @command{rotctld} 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.
|
|
|
|
@node rotctld reference
|
|
@subsection @command{rotctld} reference
|
|
@cindex @command{rotctld} reference
|
|
@cindex reference, @command{rotctld}
|
|
|
|
The complete reference for @command{rotctld} can be found in the
|
|
@kbd{rotctld}(1) Unix manual page.
|
|
|
|
|
|
@node rigmem
|
|
@section @command{rigmem}
|
|
@cindex rigmem
|
|
|
|
@command{rigmem} may be used to backup and restore memory of radio
|
|
transceivers and receivers.
|
|
|
|
@menu
|
|
* Introduction to rigmem::
|
|
* rigmem reference::
|
|
@end menu
|
|
|
|
@node Introduction to rigmem
|
|
@subsection Introduction to @command{rigmem}
|
|
@cindex Introduction to @command{rigmem}
|
|
@cindex @command{rigmem}, introduction to
|
|
|
|
Backup and restore memory of radio transceivers and receivers.
|
|
@command{rigmem} accepts @samp{command}s from the command line only.
|
|
|
|
@node rigmem reference
|
|
@subsection @command{rigmem} reference
|
|
@cindex @command{rigmem} reference
|
|
@cindex reference, @command{rigmem}
|
|
|
|
The complete reference for @command{rigmem} can be found in the
|
|
@kbd{rigmem}(1) Unix manual page.
|
|
|
|
@node rigsmtr
|
|
@section @command{rigsmtr}
|
|
@cindex rigsmtr
|
|
|
|
@command{rigsmtr} uses Hamlib to control a radio to measure S-Meter
|
|
value versus antenna azimuth.
|
|
|
|
@menu
|
|
* Introduction to rigsmtr::
|
|
* rigsmtr reference::
|
|
@end menu
|
|
|
|
@node Introduction to rigsmtr
|
|
@subsection Introduction to @command{rigsmtr}
|
|
@cindex Introduction to @command{rigsmtr}
|
|
@cindex @command{rigsmtr}, introduction to
|
|
|
|
@command{rigsmtr} rotates the antenna from minimum azimuth to maximum
|
|
azimuth. Every second, or time_step if specified in seconds, it
|
|
retrieves the signal strength. Azimuth in degrees and the
|
|
corresponding S-Meter level in dB relative to S9 are then printed on
|
|
stdout.
|
|
|
|
To work correctly, @command{rigsmtr} needs a radio that could measure
|
|
S-Meter and a Hamlib backend that is able to retrieve it, connected to
|
|
a Hamlib supported rotator.
|
|
|
|
@node rigsmtr reference
|
|
@subsection @command{rigsmtr} reference
|
|
@cindex @command{rigsmtr} reference
|
|
@cindex reference, @command{rigsmtr}
|
|
|
|
The complete reference for @command{rigsmtr} can be found in the
|
|
@kbd{rigsmtr}(1) Unix manual page.
|
|
|
|
@node rigswr
|
|
@section @command{rigswr}
|
|
@cindex rigswr
|
|
|
|
@command{rigswr} may be used to measure VSWR vs frequency.
|
|
|
|
@menu
|
|
* Introduction to rigswr::
|
|
* rigswr reference::
|
|
@end menu
|
|
|
|
@node Introduction to rigswr
|
|
@subsection Introduction to @command{rigswr}
|
|
@cindex Introduction to @command{rigswr}
|
|
@cindex @command{rigswr}, introduction to
|
|
|
|
@command{rigswr} uses Hamlib to control a radio to measure
|
|
@acronym{VSWR} (Voltage Standing Wave Ratio) over a frequency range.
|
|
It scans frequencies from @var{start_freq} to @var{stop_freq} with an
|
|
optional increment of @var{freq_step} (default step is 100 kHz). All
|
|
values must be entered as an integer in Hertz (cycles per second).
|
|
|
|
@quotation Note
|
|
@command{rigswr} assumes that @var{start_freq} is less than or equal
|
|
to @var{stop_freq}. If it is greater, @command{rigswr} will exit
|
|
without doing anything.
|
|
@end quotation
|
|
|
|
For each frequency, @command{rigswr} transmits at 25% of total POWER
|
|
during 0.5 second in CW mode and reads @acronym{VSWR}.
|
|
|
|
Frequency and the corresponding @acronym{VSWR} are then printed on
|
|
@file{stdout}.
|
|
|
|
To work correctly, @command{rigswr} needs a radio that can measure
|
|
@acronym{VSWR} and a Hamlib backend that supports reading
|
|
@acronym{VSWR} from the radio.
|
|
|
|
@node rigswr reference
|
|
@subsection @command{rigswr} reference
|
|
@cindex @command{rigswr} reference
|
|
@cindex reference, @command{rigswr}
|
|
|
|
The complete reference for @command{rigswr} can be found in the
|
|
@kbd{rigswr}(1) Unix manual page.
|