3.3. hamlib

⁠3.3. hamlib

hamlib is a library to be used by other programs to interface to radios and rotors. However, since hamlib maintains no configuration information (type of rig, connection method, etc.) itself, programs must provide that configuration.

Some programs such as fldigi provide the necessary hamlib information in a fashion somewhat hidden from the user, but others (grig, soundmodem) require the user understand hamlib configuration. Even with fldigi, advanced users may find it necessary to provide hamlib commands.

While primarily for use with other programs, hamlib includes a few applications which may be used directly, including:

rigctl - allows for control of the rig from the command line
rigmem - save and restore a radio's memories
rigswr - measure SWR across a range of frequencies
rotctl - control the rotor
rigsmtr - collect S meter readings versus azimuth. Needs rotctl.

In addition, there are daemons provided for controlling the rig and rotor.

The various hamlib applications require certain switches to describe the rig and its connection, and most take a number of commands.

⁠

Table 1. Rig description switches

Switch	Meaning
`-m, --model=id`	Select radio model number. See model list (use '`rigctl -l`').
`-r, --rig-file=device`	Use 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 `/dev/ttyS0`, `/dev/ttyS1`, `/dev/ttyUSB0`, etc.
`-p, --ptt-file=device`	Use device as the file name of the Push-To-Talk device using a device file as described above.
`-d, --dcd-file=device`	Use device as the file name of the Data Carrier Detect device using a device file as described above.
`-P, --ptt-type=type`	Use type of Push-To-Talk device. Supported types are RIG, DTR, RTS, PARALLEL, NONE, overriding PTT type defined in the rig's backend.
`-D, --dcd-type=type`	Use type of Data Carrier Detect device. Supported types are RIG, DSR, CTS, CD, PARALLEL, NONE.
`-s, --serial-speed=baud`	Set serial speed to baud rate. Uses maximum serial speed from rig backend capabilities as the default.
`-c, --civaddr=id`	Use id as the CI-V address to communicate with the rig. Only useful for Icom rigs.
`-t, --send-cmd-term=char`	Change the termination char for text protocol when using the send_cmd command. The default value is <CR> (0x0d). Non ASCII printable characters can be specified as an ASCII number, in hexadecimal format, prepended with 0x. You may pass an empty string for no termination char. The string '`-1`' tells rigctl to switch to binary protocol. See the send_cmd command for further explanation.
`-L, --show-conf`	List all config parameters for the radio defined with `-m` above.
`-C, --set-conf=parm=val[,parm=val]`	Set config parameter. e.g. `stop_bits=2`. Use `-L` option for a list.
`-l, --list`	List all model numbers defined in Hamlib and exit.
`-u, --dump-caps`	Dump capabilities for the radio defined with `-m` above and exit.
`-o, --vfo`	Set vfo mode, requiring an extra VFO argument in front of each appropriate command. Otherwise, VFO_CURR is assumed when this option is not set.
`-v, --verbose`	Set verbose mode, cumulative.
`-h, --help`	Show summary of these options and exit.
`-V, --version`	Show version of rigctl and exit.

For example, to communicate with an Icom 7000 on /dev/ttyUSB0 at 19,200 baud:

      rigctl -m 360 -r /dev/ttyUSB0 -s 19200 -c 0x70

⁠3.3.1. rigctl

rigtcl can accept a large number of commands, either on the command line or in interactive mode. The following table lists some of the more common commands. For more details see man rigctl.

⁠

Table 2. Rig description switches

Command	Meaning
`F, set_freq 'Frequency'`	Set 'Frequency', in Hz.
`f, get_freq`	Get 'Frequency', in Hz.
`M, set_mode 'Mode' 'Passband'`	Set 'Mode': USB, LSB, CW, CWR, RTTY, RTTYR, AM, FM, WFM, AMS, PKTLSB, PKTUSB, PKTFM, ECSSUSB, ECSSLSB, FAX, SAM, SAL, SAH, DSB.
`m, get_mode`	Get 'Mode' 'Passband'.
`V, set_vfo 'VFO'`	Set 'VFO': VFOA, VFOB, VFOC, currVFO, VFO, MEM, Main, Sub, TX, RX.
`v, get_vfo`	Get current 'VFO'.
`R, set_rptr_shift 'Rptr Shift'`	Set 'Rptr Shift': "+", "-" or something else for none.
`r, get_rptr_shift`	Get 'Rptr Shift'. Returns "+", "-" or "None".
`O, set_rptr_offs 'Rptr Offset'`	Set 'Rptr Offset', in Hz.
`o, get_rptr_offs`	Get 'Rptr Offset', in Hz.
`U, set_func 'Func' 'Func Status'`	Set 'Func' 'Func Status'. Func is one of: FAGC, NB, COMP, VOX, TONE, TSQL, SBKIN, FBKIN, ANF, NR, AIP, APF, MON, MN, RF, ARO, LOCK, MUTE, VSC, REV, SQL, ABM, BC, MBC, AFC, SATMODE, SCOPE, RESUME, TBURST, TUNER.
`u, get_func`	Get 'Func' 'Func Status'.
`L, set_level 'Level' 'Level Value'`	Set 'Level' and 'Level Value'. Level is one of: PREAMP, ATT, VOX, AF, RF, SQL, IF, APF, NR, PBT_IN, PBT_OUT, CWPITCH, RFPOWER, MICGAIN, KEYSPD, NOTCHF, COMP, AGC (0:OFF, 1:SUPERFAST, 2:FAST, 3:SLOW, 4:USER, 5:MEDIUM, 6:AUTO), BKINDL, BAL, METER, VOXGAIN, ANTIVOX, SLOPE_LOW, SLOPE_HIGH, RAWSTR, SWR, ALC, STRENGTH. The Level Value can be a float or an integer.
`l, get_level`	Get 'Level' 'Level Value'. Returns Level as a string from set_level above and Level value as a float or integer.

For example, the following command asks to display the frequency and mode. The mode display always also shows the bandwidth:

⁠

Figure 14. rigctl - show mode and frequency

The following example asks whether the tone squelch is on and what are the volume and squelch control settings:

⁠

Figure 15. rigctl - show tone squelch, AF and Squelch controls

The radio can be controlled as well. In the following example the radio is set to CW mode with a 500 Hz filter, and the frequency is set to 3.563 MHz:

⁠

Figure 16. rigctl - set frequency and mode

⁠3.3.2. rigmem

rigmem reads or restores the radio's memories. rigmem uses the same communication parameters as rigctl folowed by two more parameters; the action to be performed and the file name to save memories to or restore memories from.

rigmem queries the radio for the number of memories available, then asks for all the information about each of those memories. Because not all radios support all possible parameters, this may result in hundreds of messages asrigmem asks the radio questions it cannot answer. These messages are benign.

⁠3.3.3. rigswr

rigswr takes the same communication parameters as the other commands, followed by start and end frequencies and a step size. rigswr then cycles through the frequencies, keying the transmitter in CW mode for a half second at quarter power at each frequency and reporting the SWR. For this to work the rig must support sending the SWR while the rig is keyed.

⁠

Figure 17. rigswr

⁠3.3.4. rotctl

⁠3.3.5. rigsmtr

rigsmtr works with rotctl to measure the signal strength versus azimuth. rigsmtr requires both rig and rotor configuration as well as an optional time step. rigsmtr records the S reading every second as the rotor rotates, or every time_step if time_step has been specified. Refer to man rigsmtr.