This page summarizes the three test programs, ampctl(1) for testing amplifier back ends, rigctl(1) for testing radio back ends, and rotctl(1) for testing rotator back ends and the three network daemons, ampctld(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 functional examples of how Hamlib may be used to accomplish various tasks.
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 commands after any rigctl options:
rigctl
Entering interactive mode allows successive commands to be entered without exiting rigctl. Recent additions to rigctl allow command editing and history recall through use of the Readline 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
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.
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, ScrollLock then PageUp/PageDown on Free BSD, or use the scrollbar to the virtual 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.
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 commands 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 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 functions without 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:
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 interactive 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.
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, ScrollLock then PageUp/PageDown on Free BSD, or use the scrollbar to the virtual 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.
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 multiple 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 Python PHP Ruby TCL and others.
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 Python PHP Ruby TCL and others.
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.
It scans frequencies from start_freq to stop_freq with an optional increment of freq_step (default step is 100 kHz). All values must be entered 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.
Copyright © 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.