Hamlib Frequently Asked Questions
Here are some of the most common questions compiled from the hamlib mailing list and the hamlib documentation.
What is Hamlib?
Hamlib is fundamentally a C language linkable subroutine library, developed primarily using GNU tools on Linux systems. The library aims to provide a "rig-independent" application programming interface (API) that allows programmers to write applications that control transceivers, rotators, and other devices used in Amateur Radio and similar services. (These devices, except for rotators, are called "rigs".)
Hamlib provides bindings for languages other than C, such as C++, Python, Perl, and TCL. (However, these are not all well supported.) There is an application program, rigctl, which may be used to control a rig from the command level or in a script. A network daemon version rigctld is also in development.
Who is the target user of Hamlib?
Hamlib is written to support programmers who are writing rig control, logging, and other applications related to Amateur Radio. General users (non-programmers) of Amateur Radio programs that use Hamlib for rig control may download and install the Hamlib library, but they should normally follow directions provided with their software application and look to the application provider for support.
I downloaded or purchased a program that uses Hamlib; where do I get support?
Support is the responsibility of the provider of your application program -- or its associated Internet discussion group. The Hamlib project is not set up to provide support to non-programmer users.
That said, we do wish to encourage those users interested in helping to test their rigs as we develop support in the associated backend(s). Please post to the Hamlib-developer mailing list to announce your intention to help.
What platforms are supported?
The base platform is x86 Linux, but the source has been compiled in many architectures.
Does Hamlib work under Windows?
Hamlib works under Windows, as made available from download section. It works also under the Unix-like cygwin environment.
Is my rig supported?
Check out the supported radios page. You could also type 'rigctl --list' after having compiled and/or installed hamlib. It will display a neat list with RigId, Manufacturer, Model number and Version number. Here is an example:
Rig# Mfg Model Vers. 1504 Winradio WR-3100 0.6 352 Optoelectronics OptoScan535 0.2 304 Icom IC-275 0.2 1601 Ten-Tec TT-550 0.1 1505 Winradio WR-3150 0.6 401 Icom IC-PCR1000 0.1 353 Optoelectronics OptoScan456 0.2 209 Kenwood TS-850 0.2 1 Hamlib Dummy 0.1 1506 Winradio WR-3500 0.6 etc.
How do I know if my rig really works with hamlib?
There is a fairly good description in the README.betatester file, included with the hamlib source code. The first tool to use would be rigctl, which is very powerful in testing basic rig commands. Suppose I own a Kenwood TS-850, which is hooked up to the first serial port.
$ rigctl -r /dev/ttyS0 -m 209
Now type 'f' to retrieve the rigs frequency or 'm' to retrieve the mode. There is a full list of supported commands if you type rigctl --help.
It doesn't seem to work, what should I do?
You could try and start rigctl in verbose mode and see if you can see the rig output. Here is part of a trace from a Kenwood TS-870:
$ rigctl -vvvvv -r /dev/ttyS0 -m 210 Rig command: f TX 3 bytes 0000 46 52 3b FR; RX 4 characters 0000 46 52 30 3b FR0; TX 3 bytes 0000 46 41 3b FA; RX 14 characters 0000 46 41 30 30 30 31 38 31 31 30 30 30 30 3b FA00018110000; Frequency: 18110000
If this fails, try to use a serial port terminal program like minicom and see if you can communicate with your rig with simple commands. You should set your rig to the highest baud-rate it can handle, which is the default for hamlib.
I have 2 programs which use Hamlib, can I use them with the same radio?
No, you can't. The serial port can only be accessed by one program at the same time. But Hamlib has a solution for this, it is called rigctld. This is a little networking program which accesses your radio and transmits information through a TCP protocol, so any program can use it. You need to run it with appropriate privileges to access serial port:
$ rigctld -m 210 -r /dev/ttyS1 &
Next, you can start you favourite software and select NET rigctl or model 2 to access the information, or simply control it with the following:
$ rigctl -m 2 -r localhost
For more information on the subject, see Net_control.
Rem: the program rpc.rigd and RPC backend (model 1901) are deprecated.
The serial port keeps on getting timeout, the rig works fine under DOS. What's wrong?
Here's an explanation from Wilbert Knol ZL2BSJ:
The problem appears to bite the CAT interface powered from the RTS/CTS/DTR (+10V) and TXD (-10V) lines.
If rigctl is run interactively, the circuit is powered up when the user comes to issue the first command, and all is OK. The rig responds as expected.
However, when running the command from the shell prompt:
$ rigctl -m 314 -r /dev/ttyUSB1 f
...then the first rig query fails, because the electrolytics in the circuit are in the process of coming up to voltage. All subsequent rig queries work fine. So...there is nothing wrong with Hamlib. The hardware needs fixing!
Andrea Borgia IZ4FHT points out also that the previous problem can be fixed by using the rpc.rigd daemon with the "-Crts_state=ON" switch, which will stick the RTS to power on the interface. The DTR signal can be set as well.
What's the name of the 2nd serial port I have to pass under Windows?
rigctl.exe -vvvvv -r com2 -m 117
How come Hamlib can't access serial ports beyond COM9 under Windows?
You need to prefix the COM port name with
rigctl.exe -vvvvv -r \\.\com14 -m 117
This is in fact a subtlety of Windows.
For your convenience, seamless access to ports higher than COM9 has been added in version 188.8.131.52.
I write applications. What do I need to do to link to Hamlib?
Hamlib uses pkg-config. Find a package for your favorite distribution and OS, or build it from source. To build your Hamlib program, try
$ gcc -o myprog `pkg-config --cflags --libs hamlib` myprog.c
This process can be integrated into your autoconf/automake build system with pkg.m4, included in the pkg-config package. Just add the line
PKG_CHECK_MODULES(HAMLIB, hamlib, HAVE_HAMLIB=true, HAVE_HAMLIB=false)
to your configure.ac. In addition to HAVE_HAMLIB, the variables HAMLIB_LIBS and HAMLIB_CFLAGS will be created. To substitute on them you'll have to AC_SUBST both of them separately.
make install is okay, but rigctl complains it cannot find a library. What's wrong?
Eric Ka1eec points out that after building hamlib and installing with make install, you need to run ldconfig (as root) to regenerate the dynamic loader cache.
If you have no root priviledge on your system, you can do without it by appending the install library directory to your LD_LIBRARY_PATH environment variable.
The S-meter reading behaves strange. Do I have to live with it?
Be careful, that kind of minor flaw can make your life a hell. I advise you to have it fixed ;-) It's easy, it takes only 10mn. Here's how to proceed:
- Fire up the rigctl program released with the Hamlib package, and pass along options as needed (serial speed, etc.).
- Tune to some frequency reporting S0 to the radio S-Meter.
- At rigctl prompt, issue "get_level" ('l' in short) of the level RAWSTR.
- Write down the S-level read on radio front panel, and the RAWSTR value retrieved.
- Repeat from step 2 with S9 and S9+60dB. Actually the more plots, the better, otherwise Hamlib does interpolation.
- Send the table to the hamlib-developer mailing list and it will be added in the next release of Hamlib.
NB: you have to know the S-Meter of radio's is far from being accurate. For owners with a fully equipped lab, you may want to make the up-mentioned measurements with a good Signal Generator and a set of calibrated attenuators. Greg W8WWV has an insightful page about S-Meter.