Fundamentals
One of the things that occurred to me recently was that there are certain bits of knowlege that I’ve accumulated in a very haphazard and incomplete manner. Some of those things are at the center of the way I play with radio and the things that I enjoy and I don’t really think about them much. rigctld falls into this category as it’s something that I worked with early in my time with ham radio and then more or less forgot once I had it solving whatever problem I had in front of me.
rigctld and rigctl are basic blocks of functionality when it comes to connecting a computer to a radio. Simply put, the rigctld utility handles feeding CAT commands to a radio. What’s a CAT command? OK. What is CAT? CAT is Computer Aided Transceiver. I remember seeing that acronym thrown around in documentation early on in my ham radio travels with no definition. That’s a pet peeve of mine so I will probably find 100 instances in the blog as I go back through things. So, Computer Aided Transciever. That sounds really neat! What does it mean?
Control
When a computer is working with a transceiver, there are things it’s going to need to tell it to do. For example, when I start up WSJT-X and set the band in the user interface, the radio suddenly changes not only to a specific frequency, but also to a mode. In the case of my IC-7300, clicking 20-meters makes it go from whatever frequency it was on to 14.074 and puts it into USB-D (Upper Side Band Data) mode if it wasn’t there already. That’s a pretty neat trick. WSJT-X can do this in a number of ways but the two that I’ve used are:
- Directly addressing the USB device that represents the rig. That means that WSJT-X captures the device and controls it.
- Point WSJT-X to rigctld and let it pass requests to that server and receive feedback from it as well.
Great. Why does that matter?
Irritation
Something that I bumped into recently was that MacLoggerDX, my logging software of choice, wasn’t connecting to my radio. That was a hassle because as I was logging a contact, it took the band, frequency, mode, etc. from my last contact and filled that in instead of the current data from the radio. This was, of course, immediately posted to QRZ, LotW, and eQSL. Great. Now I get to go edit a bunch of entries. Why was it that I didn’t have that turned on?
Right! Because when I used WSJT-X it was hogging the rig control by capturing the USB device directly (I think). This wasn’t a problem when I was making FT8 contacts because MacLoggerDX just grabs the information for the QSO when WSJT-X logs it via another mechanism and does its cool stuff. But if I’m making a contact via Phone or CW I’m stuck doing a lot of data entry that is quite unnecessary because MacLoggerDX will, in fact, talk to rigcltd.
Naturally, the realization that I should just point it at rigctld didn’t come before I did a bunch of looking at other logging software that would have solved the issue in exactly the way I wasn’t letting MacLoggerDX solve it. As usual, I got where I needed to go, but it took me a minute.
How Does It Work?
As mentioned above, rigctld is a piece of software that can be run as a server and it tags along with the utilities that come with Hamlib. (Hamlib is its own discussion…it’s…a thing). What does it mean that rigctld is a server? You start it up and then fire commands at it that either push settings to the rig or pull its current state from it. This is absolutely fundamental to how most ham radio software works if it interacts with the radio at all. fldigi uses it and even has a front end for it in the form of flrig. I don’t love flrig so I don’t use it. I just fire it up in a terminal and let it sit there as long as my rig is powered on. Sometimes I just leave it running in the background as it’s happy to do that as well.
rigctld doesn’t ask for much from a user. Getting the server running does require the device it wants to talk to and the model of the rig. The model number is a 4 digit number that maps to the radio that is connected to the computer. A list of supported radios can be found HERE. Starting it up can be as simple as:
rigctld -m 3073 -r /dev/tty.usbserial-22110 -t 4532
Simply put, that is starting the program with the model of the rig (-m 3073 aka the IC-7300), the device handle (-r /dev/tty.usbserial-22110), and the port (-t 4532). Of those three items, port is the only one that is negotiable. You could make that anything you like but most applications will be looking for that 4532, so be mindful of that. The USB device will be system specific. Finding it will be an exercise that is particular to each operating system. It shouldn’t be too difficult, but there are definitely, well, quirks.
Now, Why Is This Cool Again?
With the server running in the background, a user can point any and all software that needs to handle the transceiver at localhost:port. What I do is run Direwolf, Pat, ardopcf, WSJT-X, and MacLoggerDX against it. Direwolf and WSJT-X can both be up and running together and addressing the server without issue. For a reason I haven’t quite figured out yet, MacLoggerDX and WSJT-X can’t both be talking to the server at the same time without some weird side-effects. I’m sure I’ll figure that out eventually (or not). I can also point fldigi at it when I’m listening in for RTTY or Hellscriber transmissions. It keeps all of my software connected and happy. If I’m logging things from modes that aren’t FT8 I can point MacLoggerDX at it to get all of the state items like frequency and mode. This is really handy when I’m hunting POTA activations on Phone or CW.
But there’s more!
In my experience, rigctl itself can do some really magical stuff. With some of the things I run, there isn’t direct rig control from the software itself. For example, when I want to get on Net105 and monitor some packet traffic, I need to switch the transceiver to 14.105 LSB-D. Unlike WSJT-X, Direwolf doesn’t really want to tell my radio what to do other than key up. It wants to be a modem and assumes that I’m an adult who can put the transceiver into the correct state to do what needs doing. And for the record, I can. Using rigctl I can feed it a relatively simple command and my radio is set to exactly what I want it to be.
rigctl -m 2 -r localhost:4532 M 'PKTLSB' -1 F 14105000
This is telling rigctl to open a connection to localhost:4532 with a rig type of 2 which is the networked control option. Then kindly set the mode to PKTLSB which translates to LSB-D on the IC-7300. After that, set the frequency to 14.105. That -1 means not to change the passband. I could put all of this in a text file and feed it to rigctl but what fun is that? I’m kind of a command line nerd so being able to address these things from a terminal allows me to move faster.
Another fun thing to do is ask a rig what modes it has.
rigctl -m 2 -r localhost:4532 get_modes
That command issued against an IC-7300 will return:
AM AM-D CW USB LSB RTTY FM FM-D CWR CW-R RTTYR RTTY-R PKTLSB PKTUSB LSB-D USB-D PKTFM PKTAM
Bandwidths: AM Normal: 6.0000 kHz, Narrow: 3.0000 kHz, Wide: 9.0000 kHz CW Normal: 500.0 Hz, Narrow: 250.0 Hz, Wide: 1.2000 kHz USB Normal: 2.4000 kHz, Narrow: 1.8000 kHz, Wide: 3.0000 kHz LSB Normal: 2.4000 kHz, Narrow: 1.8000 kHz, Wide: 3.0000 kHz RTTY Normal: 500.0 Hz, Narrow: 250.0 Hz, Wide: 2.4000 kHz FM Normal: 10.0000 kHz, Narrow: 7.0000 kHz, Wide: 15.0000 kHz CWR Normal: 500.0 Hz, Narrow: 250.0 Hz, Wide: 1.2000 kHz RTTYR Normal: 500.0 Hz, Narrow: 250.0 Hz, Wide: 2.4000 kHz PKTLSB Normal: 2.4000 kHz, Narrow: 1.8000 kHz, Wide: 3.0000 kHz PKTUSB Normal: 2.4000 kHz, Narrow: 1.8000 kHz, Wide: 3.0000 kHz FM-D Normal: 10.0000 kHz, Narrow: 7.0000 kHz, Wide: 15.0000 kHz AM-D Normal: 6.0000 kHz, Narrow: 3.0000 kHz, Wide: 9.0000 kHz
A thing that makes this all even more fun is that I could address my Mac, which is attached to my IC-7300 and running rigctld, from any other computer on my network by feeding that very same command but replacing localhost with the IP address of the Mac. And yes, it works as expected. I can even go so far as to turn the rig off from another room with:
rigctl -m 2 -r XX.X.X.XXXX:4532 set_powerstat 0
This is incredibly powerful if you’re the kind of person who looks at the world through the lens of simple shell scripts or bad decisions made hastily in Python. Being able not only to set parameters on the rig but also interrogate the rig for what its current settings are is useful. Not that I’d actually do it, but a person with the right motivations could build a pretty simple logging application with stuff like this to grab the current frequency and all of the other bits and pieces.
If it’s starting to look like the entire world of rig control runs on this, well, that’s because it does. Hamlib is everywhere and that means that, likely, so are these little helper applications. It behooves all of us who operate digital modes to learn a little more about these utilities.
Things To Remember
These utilities are really cool but they only handle one half of the equasion. The other part of most ham radio software is the audio connection. I’m not going to touch that here. There are too many options out there to have a general discussion. I’ve made notes on this site as to what I do when I’m on my Mac vs. my Ubuntu field computer. It’s fiddly and OS specific.
These utilities are deep. If there is something you can do on your rig through the UI, it’s likely that you can do it through these. I’m sure there are limitations or things that aren’t implemented in CAT, but if there are, I’m not bumping up against them in my daily operating. Not yet. What I am finding is that I don’t need a GUI to do some simple tasks and that I can script the kickoff of my setup which makes my life easier.
Run rigctl –help or dig in to the documentation. If nothing else, you can just poke at this utility and you might trip over a solution to a problem you didn’t know you had.
Oh! And if you, like me, are an ICOM devotee and use wfview it runs rigctld under the hood as well. They recommend using a different port (and I think it defaults to something other than 4532 intentionally) but once you know that port, you can issue commands against the IP address of the computer running wfview and the appropriate port and get the same results as above. I’m finding that is really handy when I’m testing things with my IC-705.
Final
I don’t know everything about these utilities and there is a lot that they can do. This post just scratches the surface, but I hope it gives an idea of why you might want to spend some time poking at them. This could seriously improve your quality of life as a digital operator if you are a person willing to mess around at the command line. Let’s face it, as a ham, you’re at least a little interested, right?
Thanks for reading and 73!
