HAMLIB-UTILITIES(7)

📦

version 4.7.2 · 2 versions

4.7.2 · alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu stonking (latest)
4.6.5 · debian bookworm, debian trixie, epel 9, fedora 43, fedora 44, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute

, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu stonking

🎀 NAME 🎀

hamlib-utilities — the radio + rotator control utilities that come with Hamlib. It's the Hamlib Information Manual bestie, and yes, this is that page. 💖

✨ DESCRIPTION ✨

Okay so, the Hamlib distribution ships with a whole lil squad of utility programs. And not just for vibes — they give developers a way to test new code and bug fixes, but they also serve as a reference implementation for interfacing with the Hamlib library functions. Both through the C API (Application Programming Interface) and through a network accessible API. So it's giving ⭐essential⭐.

This page summarizes:

the three test programs:
- ampctl(1) — for testing amplifier back ends
- rigctl(1) — for testing radio back ends
- rotctl(1) — for testing rotator</rotctl> back ends

Wait no, rotctl(1) — for testing rotator back ends

the three network daemons:
- ampctld(1), rigctld(1), and rotcltd(1) — for amplifier, radio, and rotator access via network sockets 🛰️
and the three demonstration utilities:
- rigmem(1), rigsmtr(1), and rigswr(1) — which are functional examples of how Hamlib may be used to accomplish various tasks. Living proof it works, fr fr.

🌸 rigctl 🌸

rigctl(1) is the most frequently used Hamlib utility. And because the other ctl utilities share soooo many of the same characteristics, basically most of the intro info in this section applies to the other utility programs too. You're welcome bestie 🫶

Introduction to rigctl

Most likely the first of the Hamlib utility programs you'll ever use is rigctl(1). rigctl is a character based interactive program and a command line program that can set or query a radio's value with a single command. It's 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 commands after any rigctl options:

rigctl

Entering interactive mode allows successive commands to be entered without exiting rigctl. And recent additions to rigctl allow command editing and history recall through use of the Readline library. Iconic behavior tbh 💅

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. No shortcuts on that one 😭

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 associated 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, 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. Organized ✨

rigctl reference

The complete reference for rigctl can be found in the rigctl(1) manual page. Go read it bestie, it's the moment 👑

🦋 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) locator computations. And because rotators have a much narrower scope than radios, there are fewer command line options and commands for rotctl. Less chaos, more chill 🌈

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 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. Same energy as before, no cap 😤

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.

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, 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. ✨

rotctl reference

The complete reference for rotctl can be found in the rotctl(1) manual page. Read it, it ate 💅

💜 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. New kid on the block, and it's serving 🎀

✨ rigctld ✨

Like, rigctld(1) is a network server bestie that takes the familiar commands from rigctl(1) and sends the response data over a TCP/IP network socket to whatever application is asking. So an app can access a rigctld instance from almost anywhere — but bestie, caveat: no security is currently provided by rigctld. Apps that use rigctld do not link directly to Hamlib and they don't use its C API. Periodt. 💅

🦋 Introduction to rigctld 🦋

rigctld(1) talks to a client through a TCP network socket using text commands that are shared with rigctl(1). The protocol is simple, bestie: commands get sent to rigctld on one line, and rigctld responds to get commands with the requested values, one per line, when it's successful. If it's not successful, it responds with one line RPRT x, where x is a negative number indicating the Hamlib error code. Commands that don't return values respond with the line RPRT x, where x is zero when successful, otherwise a negative number indicating the Hamlib error code. Every line ends with a newline, \n, character. This protocol is primarily for use by the NET rigctl (radio model 2) backend. Iykyk.

There's also a separate Extended Response protocol that 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. It's giving organized. ✨

Multiple radios can be controlled on different TCP ports by using 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. Slay for the polyglots. 🐍🐘💎

🌸 rigctld reference 🌸

The complete reference for rigctld can be found in the rigctld(1) manual page. Go read it, bestie. 💖

🎀 rotctld 🎀

Like, rotctld(1) is a network server bestie that takes the familiar commands from rotctl(1) and sends the response data over a TCP/IP network socket to whatever application is asking. So an app can access a rotctld instance from almost anywhere — but bestie, caveat: no security is currently provided by rotctld. Apps that use rotctld do not link directly to Hamlib and they don't use its C API. Periodt. 💅

🦋 Introduction to rotctld 🦋

rotctld(1) talks to a client through a TCP network socket using text commands that are shared with rotctl(1). The protocol is simple, bestie: commands get sent to rotctld on one line, and rotctld responds to get commands with the requested values, one per line, when it's successful. If it's not successful, it responds with one line RPRT x, where x is a negative number indicating the Hamlib error code. Commands that don't return values respond with the line RPRT x, where x is zero when successful, otherwise a negative number indicating the Hamlib error code. Every line ends with a newline, \n, character. This protocol is primarily for use by the NET rotctl (rotator model 2) backend. Iykyk.

There's also a separate Extended Response protocol that 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. It's giving organized. ✨

Multiple rotators can be controlled on different TCP ports by using 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. Slay for the polyglots. 🐍🐘💎

🌸 rotctld reference 🌸

The complete reference for rotctld can be found in the rotctld(1) manual page. Go read it, bestie. 💖

💜 ampctl 💜

The ampctld(1) utility is a recent addition to the Hamlib utilities, 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 ampctld(1) manual page for the complete reference. New fave unlocked. 🔥

🍓 rigmem 🍓

rigmem may be used to backup and restore memory of radio transceivers and receivers. Memory keeping? We love to see it. 💾✨

🧚 Introduction to rigmem 🧚

Backup and restore memory of radio transceivers and receivers. rigmem accepts commands from the command line only. No network shenanigans here, just direct vibes. ⌨️

🌈 rigmem reference 🌈

The complete reference for rigmem can be found in the rigmem(1) manual page. Go off, bestie. 💅

⭐ rigsmtr ⭐

rigsmtr uses Hamlib to control a radio to measure S-Meter value versus antenna azimuth. Science but make it cute. 📡

🦋 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. Numbers go brrr. 📈

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. So make sure your gear is compatible, bestie. No cap.

🌸 rigsmtr reference 🌸

The complete reference for rigsmtr can be found in the rigsmtr(1) manual page. Periodt. 💖

🔥 rigswr 🔥

rigswr may be used to measure VSWR vs frequency. Another day, another measurement slay. 📶

🧚 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 increment of freq_step (default step is 100 kHz). All values must be entered as an integer in Hertz (cycles per second). So like, 1000000 for 1 MHz, got it? 💯

Note: rigswr assumes that start_freq is less than or equal to stop_freq. If it is greater, rigswr will exit without doing anything. So don't try to be cute and reverse it, bestie. It's not the vibe. 🚫

For each frequency, rigswr transmits at 25% of total POWER during 0.5 second in CW mode and reads VSWR. Big yikes if you're not ready for that. ⚡

Frequency and the corresponding VSWR are then printed on stdout. Look at those numbers, iconic. 📊

To work correctly, rigswr needs a radio that can measure VSWR and a Hamlib backend that supports reading VSWR from the radio. Compatibility check, bestie. ✅

🌈 rigswr reference 🌈

The complete reference for rigswr can be found in the rigswr(1) manual page. Go read it. 💖

👑 COPYING 👑

This file is part of Hamlib, a project to develop a library that simplifies radio and rotator control functions for developers of software primarily of interest to radio amateurs and those interested in radio communications. So like, it's for the radio girlies and everyone into radio comms. 📻💖

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. So don't come for us if something breaks, bestie. It's giving as-is. 💀

🌟 SEE ALSO 🌟

Go check them out, queen. 👑

💫 COLOPHON 💫

Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via hamlib.org. So like, if you want more, you know where to go. 🌐✨

That's it, bestie. This page is from Hamlib, dated 2020-09-08, and it's HAMLIB-UTILITIES(7). Stay iconic, keep your rigs close, and never forget to read the man page. Mwah! 💋🌸

📦 where this page comes from

alpine 3.24: hamlib-doc 4.7.1-r0 · LGPL-2.0-or-later
arch rolling: hamlib 4.7.2-2 · GPL-2.0-or-later AND LGPL-2.0-or-later
nixos 26.05: hamlib 4.7.2
nixpkgs unstable: hamlib 4.7.2
opensuse-leap 16.0: hamlib 4.7.2-bp160.1.1 · LGPL-2.1-only
opensuse-leap 16.0: hamlib 4.7.2-bp160.1.1 · LGPL-2.1-only
opensuse-leap 16.0: hamlib 4.7.2-bp160.1.1 · LGPL-2.1-only
opensuse-leap 16.0: hamlib 4.7.2-bp160.1.1 · LGPL-2.1-only
ubuntu stonking: libhamlib-utils 4.7.2-2 · LGPL-2.1-or-later AND GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms