[ home | files | links | topics | stickers | about ]

Todays Stats

Visitors: 218
Referrers: 33
User Agents: 99
Pages Served: 644
Total Pages



HOWTO: Configure Hamlib for Linux Hams - Part 1
radio : by Tommy - December 2nd 2013, 8:11PM
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.

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:
Bus 006 Device 004: ID 1a86:7523 QinHeng Electronics HL-340 USB-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:

# 1a86:7523 QinHeng Electronics HL-340 USB-Serial adapter
ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="7523", TEST!="/dev/radio", SYMLINK+="radio"


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:
sudo service udev restart

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

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:
sudo vi /etc/group

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

tags: ham radio hamlib linux satellite

-+- neodux blog -+-
Page generated for in 0.07199 seconds.
rss 2.0 feed