Tag: hamlib

This is a continuation of a two part series about how to configure hamlib for Linux ham radio users.
To get started, be sure to read through Part 1.

In the last post, I pointed out that hamlib was create to simplify the once fragmented world of computer control for amateur radio. With hamlib in place, developers can interact with hamlib which serves as an abstraction layer of sorts for software development. Developers don't need to worry that you're running a particular model of radio, so long as you get your radio working with hamlib, your radio is supported.
I'm going to assume you have /dev/radio and /dev/rotator already configured (since we did that in the previous post). Now, we're going to configure the daemons (servers) that allow a myriad of radio related applications to interact with your amateur radio equipment.

Daemons
Hamlib centers around two core daemons: rigctld and rotctld. The daemons receive commands from applications via TCP. It is possible to have these daemons controlled via the network if you so wish. That functionality is a bit beyond the scope of this article, but the concepts below are exactly the same and just requires the correct ports be opened. Speaking of ports, rigctld and rotctld use ports 4532 and 4533, respectively. Also note that there is no security built into these devices. Should you need external connectivity, you should create an SSH tunnel.

Find your equipment
The first step in configuring rigctld is to find if your particular radio (and rotator for rotctld) is supported. Here is a list of all supported radios for rigctld (chances are, if it's a modern radio with computer interface, it's supported). For rotctld, things get a little more difficult. In order to see if your rotator controller is supported, you need to identify which protocol is supported. As I stated before, my rotator is a Yaesu G-5500 and my interface is the ARRL Satellite Tracker Interface. I know from prior experience and documentation this uses the EasyComm 1 protocol. Armed with this information I can proceed with configuring each daemon independently.

Gathering Radio Settings Information
Now that we know our radio is supported, we can determine all of the command line options necessary to setup rigctld. My radio is a Yaesu FT-847, so I'll be using that for my examples - adjust accordingly. For starters, we need to be on the command line so open Terminal or a shell. This whole time I've been referencing rigctld, but for initial configuration and testing we're going to use rigctl. The two programs are essentially the same except the daemon is "headless" (no uder interface) listens for commands via a TCP port. rigctl gives us an internal command line wherein we can issue commands to check communication with our radio. Both rigctl and rigctld require 3 pieces of information, although you can get by with only 2 (we'll give it 4 just to be specific and safe).
The first information rigctl wants to know is what kind of radio are you using. You can find rigctl's list of radios by issuing the following command

(That's a lowercase L, by the way - short for "list") That's going to be a long list though. You could scroll and find your radio or you can pare it down with grep
:
That's more like it. Now I only see the line of info for my FT-847. The key information we're after is the number on the left. In this case, 101.

The other pieces of information rigctl wants are the device name and the speed at which we'll communicate with the device. For the name, we created the symlink /dev/radio using udev in the previous HOWTO. For the speed, you'll need to check your radio's menu settings. It should be be something like CAT rate, COMM rate or Serial rate (refer to your manual for assistance). I currently have my FT-847 set to 9600 baud, though it's capable of 57600 and 4800 as well. rigctl takes our pieces of information in the form of command line arguments which are -m for model, -r for device (rig) and -s for speed. Another argument we'll pass to rigctld later on, just to be specific, is -t for TCP port. note: you Icom users will need to specify the CI-V address of your radio using the -c argument.

Running and testing rigctl
To establish a connection with the radio, we'll issue the following command:
Once rigctl is up and running, you'll be able to issue commands to the radio directly to either read a setting or set a setting. If you have successfully started rigctl, try issuing the "read frequency" command. To do this, simply enter f by itself and press enter. The radio should respond with it's current frequency in Hertz.
To set the radio's frequency, enter F followed by the frequency in Hertz. (In hamlib, capitalized letters set, lowercase letters get)

Switching over to rigctld
If everything has checked out thus far, we can now quit rigctl (enter q) and begin moving over to rigctld.
Essentially, you can run rigctld with the exact same settings as rigctl. For safety, I also issue -t 4532 to specify the port I want rigctld listening to. This is the default port and is unnecessary, but it's nice say exactly what you mean even when it's implied. :)
So, to start rigctld, we run something like the following:
(You can run the command above with an ampersand at the end to "background" the process, but for the time being it's unnecessary.)

With the daemon running, you should now be able to interact with your radio with you program of choice. If you do not yet have a program installed, check out grig which should have come with hamlib. grig is a Graphical Rig that gives you a generic radio graphical interface where you can change frequency on the screen and see the frequency change on the radio and vice versa. It's nothing special and you probably will get a more useful interface with your application of choice, but this is a good testbed.

To keep things tidy (and so I don't have to manually run rigctld everytime I boot up, I created an entry in rc.local (found in /etc) to run with the same settings I used above. (Just remember to "background" the process by putting a & at the end.

Now with rotctl...
Configuring rotctl and rotctld isn't all that different from rigctl. Refer to the man page for rigctl for specific command line flags for it, but you should have no difficulty if you already know the rotator controller's protocol. It's very satisfying to issue a command to rotctl and hear the rotator turning and see the indicator needles moving.
My setup looks like this:
Once you have rotctl setup how you like, create an entry in rc.local using rigctld, configure your application for the appropriate settings (remember rotctld likes port 4533 by default) and enjoy the fruits of your labor. (Again, don't forget to background the process with & at the end of the line in your rc.local entry.

Final Overview
So, with everything working correctly, I shouldn't have to do anything to get the functionality I want. udev detects our device connecting our radio and rotator and creates the symlinks of our choosing. rc.local, after the OS has mounted the devices, will startup rigctld and rotctld with the settings specific to our radio and rotator. All that's left is to run our application of choice (CQRLog, gpredict, fldigi, etc) and configure the application to talk to our daemon running on localhost.

Overall, the whole process is not too terribly complex. It's a few new steps you may not have done before, but in the end it all works out nicely. 73 and good DX!

Linux and ham radio, where two of the geek worlds collide. Fortunately, with so many geeks involved in both pursuits, a lot of great tools have emerged. Unfortunately, documentation on how to configure some of it was hard to come by. (At least, it seemed that way to me.) Here, I hope to layout as quickly and easily as possible the steps required for other hams to configure hamlib on their linux computers. I'm going to assume you're running a modern version of linux and have a USB connection to your radio and/or rotator.

What is Hamlib?
First of all, Hamlib is a set of ham radio control libraries that allows amateur radio operators to control their radio and antenna rotators via their computer. Hamlib abstracts many device-specific control issues from application developers, allowing for a more robust user experience across several programs. Prior to hamlib, there were several different tools and libraries. None of these tools provided a common API for programmers to interface. As a result, the application landscape was fragmented and functionality suffered. Now, with hamlib, programmers can utilize hamlib to interact with a whole range of devices.

Interface
To use hamlib, you must first have a computer interface cable from your radio to your computer. Without this, everything else here is pretty useless. If you don't have a cable yet, look on eBay for cables tailored to your radio. (It's where I found mine.)
My radio is a Yaesu FT-847 which has a DB9 serial port for CAT computer control. To interface with my computer, I use a cheap USB-to-serial adapter - nothing special. My antenna rotator is a Yaesu FT-5500 with the brilliantly simple WA8SME Satellite Tracker Interface from the ARRL.

USB, Linux and udev
Most modern distributions of Linux include a subsystem to handle when USB devices are inserted. This system will detect the device, query what sort of device it is then attempt to mount the device (commonly in /dev). For my setup, I'm running Ubuntu 12.04. When I plugin my radio interface (the USB-to-serial adapter), the devices gets mounted as /dev/ttyUSB0 or /dev/ttyUSB1 (depending on whether or not my satellite tracker is plugged in and the order in which they are connected, etc.) Herein lies the problem for most linux-using hams. Unless you want to manually determine (ick!) which port your radio is connected to and which one your rotator is connected to every time you reboot or reconnect the device, you need to have a device name you can count on. Thankfully, we have udev.
udev is a tool created just for such a need. udev allows you to specify a device based on it's manufacturer and device ID and give the device a name (symlink to the actual device) and/or launch a program upon insertion (a lot like AutoPlay in Windows). In Ubuntu, you specify these rules in files found in /etc/udev/rules.d/, other distros will have udev rules located in a similar directory. When you locate your udev rules, I would recommend you create one titled hamlib.rules.

Device identification
There's a lot of ways to specify a device in udev, but I'll cut to the chase. I discovered this great guide from Hack-A-Day while configuring my setup and it helped me get started. In the Hack-A-Day tutorial, he's configuring a thumbdrive, whereas we're trying to configure a /dev/tty device, so we'll diverge a bit. The steps we need to follow, at least initially, are the same.
First, we need to identify the device we want to use:
From this screen, we're looking for the device ID. If you have more than one serial interface, you may need to unplug one of your devices, run lsusb again, see what disappeared then reconnect, and run lsusb. The information we're looking for are the two 4-alphanumeric strings immediately after ID on the row associated with your device. Here's a line for my USB-to-Serial adapter:

In this case, I'd take note of 1a86 and 7523. (The number on the left of the colon is known as the idVendor and the number on the right is the idProduct.) Your numbers will almost certainly vary, so don't use these numbers find the id numbers associated with your device.

udev Rules
Armed our device ID, we can now proceed to build our udev rules. udev operates by running a series of checks which are defined by rules. These checks are "equal to" (==) and "not equal to" (!=). There are others, but these two are all we'll use.
To define our rules, open the hamlib.rules file we created earlier (in /etc/udev/rules.d/ or someplace similar). I want to show you the file I created, then explain what each piece does. Here are the contents of my hamlib.rules file:
The first line essentially says "System, if the device isn't a tty device, jump down to "hamlib_end", (which, surprisingly, is the end of our file). This is just a way to have the system skip running any checks that aren't associated with our tty device needs.
The second line is a comment and helps differentiate which rule is associated with which device.
The third line starts with checking the idVendor field of the attributes for a device. If that checks out, it looks to the idProduct. In effect, it's saying "if the idVendor is _____..." and "if the idProduct is ____..."
The next part of the third line checks to see if a device named /dev/radio already exists. If it doesn't exist (not eual to), then move on to the next part of the statement. (One thing I didn't mention: if any one part of this statement fails, the rule fails and it moves on...)
The final part of this statement (SYMLINK) creates the symbolic link with the name we specified. Notice we're using a special += to assign the name of the symlink.
The last line creates the label "hamlib_end" so the first line can skip to the end.

Now, with this rule in place, whenever the system encounters a device that has been plugged in, it will not only mount the device but also create a alias /dev/radio that points to the device, whatever it is actually mounted as.
One last thing you'll need to do in order to enable this rule is to reload the udev service or reboot. To reload in Ubuntu:


That's it, your device should now showup when you check for it. Run the following command to see if it checks out:

Group Permissions
Permissions, permissions. If you notice the permissions on /dev/ttyUSBx, you'll see it belongs to the group dialout. (This is a throwback to the days when tty devices were used to dialout to BBSs and other services via modems.) In order to use this, simply add yourself to the dialout group. You can do this with usermod, groupadd, or by using your favorite text editor to open /etc/group and append your username to the end of the line for dialout:
Once you're part of the group, you're device is now available for you to access with rigctl (or rotctl if it's a rotator).

Continue on to Part 2 to configure rigctld and rotctld...