Provided by: libhamlib-utils_4.5.5-2_amd64 
NAME
hamlib - radio and rotator control library
DESCRIPTION
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).
Overview
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 ⟨http://www.perl.org⟩, Python ⟨http://www.python.org⟩, Lua
⟨https://www.lua.org⟩, and TCL ⟨http://www.tcl.tk⟩. These language bindings are generated
through the use of SWIG ⟨http://www.swig.org⟩, 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.
Hamlib project information
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 ⟨https://sourceforge.net⟩ at the Hamlib project
page ⟨https://sourceforge.net/projects/hamlib/⟩. As GitHub ⟨https://github.com⟩ has
become a very popular project hosting site, Hamlib also has a dedicated GitHub project
page ⟨https://github.com/Hamlib/Hamlib⟩. GitHub also hosts the hamlib.org
⟨http://www.hamlib.org⟩ Web site and the Hamlib Wiki
⟨https://github.com/Hamlib/Hamlib/wiki⟩.
Development discussion and most user support take place on the hamlib-developer mailing
list ⟨https://sourceforge.net/p/hamlib/mailman/⟩. While there are SourceForge.net
discussion forums ⟨https://sourceforge.net/p/hamlib/discussion/⟩, they are rarely used and
not as closely read by the developers as the mailing list.
For source code management, the project uses Git ⟨http://git-scm.com/⟩, 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.
Applications using Hamlib
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 ⟨https://github.com/Hamlib/Hamlib/wiki/Applications-
and-Screen-Shots⟩. Developers are encouraged to request their applications be added to
the gallery by way of the hamlib-developer mailing list.
Using Hamlib with your program
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.
Radios with a clone capability
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 ⟨http://chirp.danplanet.com⟩, aims to support
radios with such a clone capability. Please contact the Chirp project for support of such
radios.
Pronouncing Hamlib
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! :-)
COPYING
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.
SEE ALSO
hamlib-primer(7)
COLOPHON
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives
are available via hamlib.org ⟨http://www.hamlib.org⟩.