FreeBSD Manual Pages
home | help
HAMLIB-UTILITIES(7) Hamlib Information Manual HAMLIB-UTILITIES(7)
NAME
hamlib-utilties - radio and rotator control utilities of Hamlib
DESCRIPTION
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 Pro-
gramming Interface) and offering a network accessible API.
This page summarizes the three test programs, ampctl(1) for testing am-
plifier back ends, rigctl(1) for testing radio back ends, and rotctl(1)
for testing rotator back ends and the three network daemons, am-
pctld(1), rigctld(1), and rotcltd(1) for amplifier, radio, and rotator
access via network sockets. Also included are three demonstration
utilities, rigmem(1), rigsmtr(1), and rigswr(1) which provide func-
tional examples of how Hamlib may be used to accomplish various tasks.
rigctl
rigctl(1) is the most frequently used Hamlib utility. As the other ctl
utilities share many of the same characteristics, much of the introduc-
tory information presented in this section is applicable to the other
utility programs.
Introduction to rigctl
Most likely the first of the Hamlib utility programs that is used is
rigctl(1). rigctl is a character based interactive program and a com-
mand line program able to set or query a radio's value with a single
command. rigctl is invoked from a shell command prompt with various
options and additional commands.
In its most simple use as a command line program, rigctl is used to set
frequency and mode by typing commands after any rigctl options:
rigctl F 14205000
rigctl M USB 2400
and then query those values:
rigctl f
rigctl m
Entering interactive mode is a simple matter of not placing any com-
mands after any rigctl options:
rigctl
Entering interactive mode allows successive commands to be entered
without exiting rigctl. Recent additions to rigctl allow command edit-
ing and history recall through use of the Readline
https://tiswww.case.edu/php/chet/readline/rltop.html> library.
Interactive mode is indicated by the spartan prompt:
Rig command:
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:
Rig command: M
Mode: USB
Passband: 2500
Rig command: m
Mode: USB
Passband: 2500
Rig command:
An additional prompt is printed when more information is required by
the command. For M above, rigctl prompted for the Mode and Passband
values. For m above, rigctl returned the Mode and Passband values
without further prompts. The command prompt is returned after each
command invocation.
The above examples invoked rigctl without specifying a radio model.
This is a feature where the Hamlib internal radio model 1 dummy is
used. The dummy radio provides a way to test Hamlib functions without
the need for actual radio hardware. However, to develop the Hamlib
backend 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:
rigctl -m 2029 -r /dev/rig F 3900000
and to query the frequency and then mode:
rigctl -m 2029 -r /dev/rig f
3900000
rigctl -m 2029 -r /dev/rig m
LSB
2000
Note: the returned values do not have the prompt strings associ-
ated with interactive mode as shown above.
The -m option takes a numeric value that corresponds to a given radio
back end model. The -r option takes the path to the port device on
POSIX and the device name on Microsoft Windows.
Note: A complete list of supported radio models may be seen by
use of the -l option:
rigctl -l
Rig # Mfg Model Version Status
1 Hamlib Dummy 0.5 Beta
2 Hamlib NET rigctl 0.3 Beta
1001 Yaesu FT-847 0.5 Beta
1003 Yaesu FT-1000D 0.0.6 Alpha
.
.
.
27002 Rohde&Schwarz EB200 0.1 Untested
28001 Philips/Simoco PRM8060 0.1 Alpha
29001 ADAT www.adat.ch ADT-200A 1.36 Beta
The list is long so use Shift-PageUp/Shift-PageDown on Linux, Scroll-
Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir-
tual terminal window (cmd window on Microsoft Windows) or the output
can be piped to more(1) or less(1), e.g., "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.
rigctl reference
The complete reference for rigctl can be found in the rigctl(1) manual
page.
rotctl
Identical in function to rigctl(1), rotctl(1) provides a means for
testing Hamlib functions useful for rotator control and QTH (Maidenhead
gridsquare system, see Maidenhead Locator System
https://en.wikipedia.org/wiki/Maidenhead_Locator_System>) locator com-
putations. As rotators have a much narrower scope than radios, there
are fewer command line options and commands for rotctl.
Introduction to rotctl
rotctl(1) is a character based interactive program and a command line
program able to set or query a rotator's value with a single 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, rotctl is used to set
azimuth position and (optionally) elevation by typing commands after
any rotctl options:
rotctl P 145.0 23.0
rotctl M 8 25
and then query those values:
rotctl p
Entering interactive mode is a simple matter of not placing any com-
mands after any rotctl options:
rotctl
Entering interactive mode allows successive commands to be entered
without exiting rotctl. Interactive mode allows for command editing
and history recall through the use of the Readline
https://tiswww.case.edu/php/chet/readline/rltop.html> library.
Interactive mode is indicated by the spartan prompt:
Rotator command:
Commands are given at the prompt:
Rotator command: M
Direction: 16
Speed: 60
Rotator command: p
Azimuth: 11.352000
Elevation: 0.000000
Rotator command: p
Azimuth: 27.594000
Elevation: 0.000000
Rotator command:
An additional prompt is printed when more information is required by
the command. For M above, rotctl prompted for the Direction and Speed
values. For p above, rotctl returned the Azimuth and Elevation values
without further prompts. The command prompt is returned after each
command invocation.
The above examples invoked rotctl without specifying a rotator model.
This is a feature where the Hamlib internal rotator model 1 dummy is
used instead. The dummy rotator provides a way to test Hamlib func-
tions without the need for actual rotator hardware. However, to de-
velop back end capability for a given rotator, having the actual con-
troller connected to the computer is necessary for debugging.
For example, to quickly set position for RotorEZ:
rotctl -m 401 -r /dev/rotor P 100.0 0.0
and to query the position:
rotctl -m 401 -r /dev/rotor p
100.000000
0.000000
The returned values do not have the prompt strings associated with in-
teractive mode as shown above.
The -m option takes a numeric value that corresponds to a given rotator
back end model. The -r option takes the path to the port device on
POSIX or the device name on Microsoft Windows.
Note: A complete list of supported rotator models may be seen by
use of the -l option:
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
The list is long so use Shift-PageUp/Shift-PageDown on Linux, Scroll-
Lock then PageUp/PageDown on Free BSD, or use the scrollbar to the vir-
tual terminal window (cmd window on Microsoft Windows) or the output
can be piped to more(1) or less(1), e.g. "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.
rotctl reference
The complete reference for rotctl can be found in the rotctl(1) manual
page.
ampctl
The ampctl(1) utility is a recent addition to the Hamlib utilities as a
part of the 4.0 development cycle. It is intended to test the Hamlib
implementation of amplifier control and is similar in function to the
utilities previously described. See the ampctl(1) manual page for the
complete reference.
rigctld
The rigctld(1) program is a network server that accepts the familiar
commands of rigctl(1) and provides the response data over a TCP/IP net-
work socket to an application. In this manner an application can ac-
cess a rigctld instance from nearly anywhere (caveat, no security is
currently provided by rigctld). Applications using rigctld do not link
directly to Hamlib nor use its C API.
Introduction to rigctld
rigctld(1) communicates to a client through a TCP network socket using
text commands shared with rigctl(1). The protocol is simple; commands
are sent to rigctld on one line and rigctld responds to get commands
with the requested values, one per line, when successful, otherwise, it
responds with one line RPRT x, where x is a negative number indicating
the Hamlib error code. Commands that do not return values respond with
the line RPRT x, where x is zero when successful, otherwise a negative
number indicating the Hamlib error code. Each line is terminated with
a newline, \n, character. This protocol is primarily for use by the
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 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 rigctld directly
through a TCP network socket.
Multiple radios can be controlled on different TCP ports by use of mul-
tiple rigctld processes each listening on a unique TCP port. It is
hoped that rigctld will be especially useful for client authors using
languages such as Perl http://www.perl.org/>, Python
http://www.python.org/>, PHP http://php.net/>, Ruby , TCL http://www.tcl.tk/>, and others.
rigctld reference
The complete reference for rigctld can be found in the rigctld(1) man-
ual page.
rotctld
The rotctld(1) program is a network server that accepts the familiar
commands of rotctl(1) and provides the response data over a TCP/IP net-
work socket to an application. In this manner an application can ac-
cess a rotctld instance from nearly anywhere (caveat, no security is
currently provided by rotctld). Applications using rotctld do not link
directly to Hamlib nor use its C API.
Introduction to rotctld
rotctld(1) communicates to a client through a TCP network socket using
text commands shared with rotctl(1). The protocol is simple, commands
are sent to rotctld on one line and rotctld responds to get commands
with the requested values, one per line, when successful, otherwise, it
responds with one line RPRT x, where x is a negative number indicating
the Hamlib error code. Commands that do not return values respond with
the line RPRT x, where x is zero when successful, otherwise a negative
number indicating the Hamlib error code. Each line is terminated with
a newline, \n character. This protocol is primarily for use by the NET
rotctl (rotator 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 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 rotctld directly
through a TCP network socket.
Multiple rotators can be controlled on different TCP ports by use of
multiple rotctld processes each listening on a unique TCP port. It is
hoped that rotctld will be especially useful for client authors using
languages such as Perl http://www.perl.org/>, Python
http://www.python.org/>, PHP http://php.net/>, Ruby , TCL http://www.tcl.tk/>, and others.
rotctld reference
The complete reference for rotctld can be found in the rotctld(1) man-
ual page.
ampctl
The ampctld(1) utility is a recent addition to the Hamlib utilities as
a part of the 4.0 development cycle. It provides network socket access
for the Hamlib implementation of amplifier control and is similar in
function to the network utilities previously described. See the am-
pctld(1) manual page for the complete reference.
rigmem
rigmem may be used to backup and restore memory of radio transceivers
and receivers.
Introduction to rigmem
Backup and restore memory of radio transceivers and receivers. rigmem
accepts commands from the command line only.
rigmem reference
The complete reference for rigmem can be found in the rigmem(1) manual
page.
rigsmtr
rigsmtr uses Hamlib to control a radio to measure S-Meter value versus
antenna azimuth.
Introduction to rigsmtr
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, 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.
rigsmtr reference
The complete reference for rigsmtr can be found in the rigsmtr(1) man-
ual page.
rigswr
rigswr may be used to measure VSWR vs frequency.
Introduction to rigswr
rigswr uses Hamlib to control a radio to measure VSWR (Voltage Standing
Wave Ratio) over a frequency range.
It scans frequencies from start_freq to stop_freq with an optional in-
crement of freq_step (default step is 100 kHz). All values must be en-
tered as an integer in Hertz (cycles per second).
Note: rigswr assumes that start_freq is less than or equal to
stop_freq. If it is greater, rigswr will exit without doing anything.
For each frequency, rigswr transmits at 25% of total POWER during 0.5
second in CW mode and reads VSWR.
Frequency and the corresponding VSWR are then printed on stdout.
To work correctly, rigswr needs a radio that can measure VSWR and a
Hamlib backend that supports reading VSWR from the radio.
rigswr reference
The complete reference for rigswr can be found in the rigswr(1) manual
page.
COPYING
This file is part of Hamlib, a project to develop a library that sim-
plifies radio and rotator control functions for developers of software
primarily of interest to radio amateurs and those interested in radio
communications.
Copyright (C) 2001-2020 Hamlib Group (various contributors)
This is free software; see the file COPYING for copying conditions.
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.
SEE ALSO
less(1), more(1), ampctl(1), ampctld(1), rigctl(1), rigctld(1),
rotctl(1), rotctld(1), rigmem(1), rigsmtr(1), rigswr(1), hamlib(7),
hamlib-primer(7)
COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily
snapshot archives are available via hamlib.org http://www.hamlib.org>.
Hamlib 2020-09-08 HAMLIB-UTILITIES(7)
NAME |
DESCRIPTION |
rigctl |
rotctl |
ampctl |
rigctld |
rotctld |
ampctl |
rigmem |
rigsmtr |
rigswr |
COPYING |
SEE ALSO |
COLOPHON
Want to link to this manual page? Use this URL:
home | help
|