hamlib - radio and rotator control library
The
Ham Radio Control Libraries,
Hamlib for short, is a
development effort to provide a consistent interface for programmers wanting
to incorporate radio and rotator control in their programs.
Hamlib is not a complete user application, rather, it is a software layer
intended to make controlling various radios and other amateur radio station
(shack) hardware much easier. Hamlib will allow authors of software such as
logging programs, digital communications programs, or those wanting to develop
the ultimate radio control software to concentrate on the user interface and
the basic function of the program rather than radio control. Hamlib consists
of several parts, the programming library, utility programs, and library
interfaces to other programming languages.
Most recent amateur radio transceivers allow external control of their functions
through a serial interface. Unfortunately, control commands are not always
consistent across a manufacturer's product line and each manufacturer's
product line differs greatly from its competitors.
Hamlib attempts to solve this problem by presenting a
virtual radio to
the programmer by providing an interface to actions such as setting a given
Variable Frequency Oscillator's (VFO) frequency, setting the operating mode,
querying the radio of its current status and settings, and giving the
application a list of a given radio's capabilities. Unfortunately, what can be
accomplished by Hamlib is limited by the radios themselves and some offer very
limited capability.
Other devices, such as antenna rotators, can be placed into the Hamlib control
scheme. Other recent developments include network interface servers and a USB
interface capability. Language bindings are provided for
C,
C++,
Perl,
Python,
Lua and
TCL (more to come).
Hamlib is a
front end library providing a
C language Application
Programming Interface (API) to programmers wishing to integrate radio or
rotator control in their applications. Hamlib presents a
virtual radio
or
virtual rotator that is a consistent interface to an application
despite wide differences in radio and rotator interfaces and capabilities.
The front end library uses a number of
back end libraries to translate
from the front end to the various individual radio and rotator models. A back
end library handles conversion of the front end variables to the format needed
by the radio or rotator device it controls. The back end libraries are
generally grouped by manufacturer and in some cases by a common control
protocol.
Hamlib also provides an interface library for each of several common
scripting languages such as
Perl
Python
Lua and
TCL These
language
bindings are generated through the use of
SWIG a
parser/generator for multiple language interfaces to a
C library. A
natively generated
C++ language interface is also provided.
Besides the C and supplemental APIs, Hamlib also provides a pair of network
daemons that provide a text command based API for controlling an attached
radio or rotator through a
TCP/
IP network connection. The
daemons then handle the interface to the Hamlib C API.
More than one type of device, radio or rotator, may be controlled at a time,
however, there is generally a limit of one device per serial port or other
port.
The Hamlib Project was founded by Frank Singleton, VK3FCS/KM5WS in July 2000.
Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib project and
the API and implementation development led to a reasonable level of maturity
in a few years. A major milestone was reached when Hamlib 1.2.0 was released
in March 2004. The API and Application Binary Interface (ABI) interfaces have
remained stable since that time up to the release of 3.3 in mid 2018. Version
4.0 marks a major change to the ABI and certain changes to the API.
Development continues through the major version number 4.
x series and
beyond. The 4.0 release marks a major change in the ABI with several changes
for additional modes and such that will require client programs that use the C
ABI to be recompiled/relinked, etc. Other goals include improving the overall
documentation (this man page with more in progress), and other updates as
warranted.
The Project is hosted by
SourceForge.net at
the
Hamlib
project page As
GitHub has become a
very popular project hosting site, Hamlib also has a dedicated
GitHub
project page GitHub also hosts the
hamlib.org Web site
and the
Hamlib
Wiki
Development discussion and most user support take place on the
hamlib-developer
mailing list While there are
SourceForge.net
discussion forums they are rarely used and not as closely read by the
developers as the mailing list.
For
source code management, the project uses
Git a fast,
distributed content tracker. Among its features is that every developer has
the complete Hamlib development history available locally. For more
information on using Git, see
hamlib-git(7).
-
Note: while a canonical Git repository is hosted at
SourceForge, its availability is not essential to continued development
although development work flows would change temporarily. Several
developers find the GitHub Web interface easier to use and lately
development has centered around GitHub rather than SourceForge.
A number of application developers have taken advantage of Hamlib's capabilities
to implement radio and/or rotator control. While not exhaustive, a list is
maintained at the Hamlib Wiki,
Applications/Screenshots
Developers are encouraged to request their applications be added to the
gallery by way of the hamlib-developer mailing list.
As with other Free Software projects, Hamlib relies heavily on copyleft
licensing to encourage development contributions and provide an open
atmosphere for development. Hamlib's source code is released under two
licenses, the
Lesser General Public License (LGPL) version 2.1 for the
library portion, and the
General Public License (GPL) version 2 for the
utility programs.
The LGPL allows the library to be used (linked) by programs regardless of their
individual license. However, any contributions to the library source remain
under a copyleft license which means that the library source code may not be
used in violation of the terms of the LGPL (see the file
COPYING.LIB in
the main source directory). Concepts learned by studying these sources for the
purpose of understanding the Hamlib API is not covered nor prohibited by the
LGPL, however, directly copying LGPL sources into any work that is
incompatible with the terms of the LGPL is a violation of the terms of the
license.
The utility program source files are released under the GPL. Any direct use of
these sources must be in a form that complies with the terms of the GPL (see
the file
COPYING in the main source directory). Concepts learned by
studying these sources for the purpose of understanding the Hamlib API is not
covered nor prohibited by the GPL, however, directly copying GPL sources into
any work that is incompatible with the terms of the GPL is a violation of the
terms of the license.
Hamlib's focus is on controlling radios that employ a port and command protocol
for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF transceivers do not
employ such control capability but do provide for cloning the memory contents
from radio to another of the same model. A related project,
Chirp
aims to support radios with such a clone capability. Please contact the Chirp
project for support of such radios.
English speakers seem to have two alternate pronunciations for our project:
- •
-
Hamlib (Ham - lib, long ‘i’, as in library.) IPA style: /'ham læb/
- •
-
Hamlib (Ham - lib, short ‘i’, as in liberty.) IPA style: /'ham lɪb/
Then again, we have people who say Linux “L-eye-nux” and those who
say “L-in-nux”...
If you're French, the above does not apply! :-)
This file is part of Hamlib, a project to develop a library that simplifies
radio, rotator, and amplifier control functions for developers of software
primarily of interest to radio amateurs and those interested in radio
communications.
Copyright © 2001-2020 Hamlib Group (various contributors)
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.
hamlib-primer(7)
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot
archives are available via
hamlib.org