2013-03-11 02:17:44 +00:00
|
|
|
|
The @dfn{Ham Radio Control Libraries}, @dfn{Hamlib} for short, is a
|
|
|
|
|
development effort to provide a consistent interface for programmers
|
2018-07-30 03:03:24 +00:00
|
|
|
|
wanting to incorporate radio and rotator control in their programs.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
Hamlib is not a complete user application, rather, it is a software
|
2018-07-30 03:03:24 +00:00
|
|
|
|
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.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
Most recent amateur radio transceivers allow external control of their
|
2018-07-30 03:03:24 +00:00
|
|
|
|
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).
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
@menu
|
|
|
|
|
* Overview::
|
|
|
|
|
* The Hamlib project::
|
|
|
|
|
* Applications using Hamlib::
|
|
|
|
|
* Licensing implications::
|
|
|
|
|
* Radio cloning::
|
|
|
|
|
* Pronunciation::
|
|
|
|
|
@end menu
|
|
|
|
|
|
|
|
|
|
@node Overview
|
|
|
|
|
@section A view from the top of the tower
|
|
|
|
|
@cindex Overview
|
|
|
|
|
|
|
|
|
|
@cindex Front end library
|
|
|
|
|
@cindex Virtual radio
|
2018-07-30 03:03:24 +00:00
|
|
|
|
@cindex Virtual rotator
|
2013-03-11 02:17:44 +00:00
|
|
|
|
Hamlib is a @dfn{front end} library providing a @emph{C} language
|
|
|
|
|
Application Programming Interface @acronym{API} to programmers wishing
|
2018-07-30 03:03:24 +00:00
|
|
|
|
to integrate radio or rotator control in their applications. Hamlib
|
|
|
|
|
presents a @dfn{virtual radio} or @dfn{virtual rotator} that is a
|
|
|
|
|
consistent interface to an application despite wide differences in
|
|
|
|
|
radio and rotator interfaces and capabilities.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
@cindex Back end library
|
|
|
|
|
The front end library uses a number of @dfn{back end} libraries to
|
|
|
|
|
translate from the front end to the various individual radio and
|
2018-07-30 03:03:24 +00:00
|
|
|
|
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
|
2013-03-11 02:17:44 +00:00
|
|
|
|
manufacturer and in some cases by a common control protocol.
|
|
|
|
|
|
|
|
|
|
@quotation
|
|
|
|
|
Since a picture is worth quite a few words, here is a visual representation
|
|
|
|
|
of Hamlib's design.
|
|
|
|
|
@ifhtml
|
|
|
|
|
@*@*
|
|
|
|
|
@end ifhtml
|
|
|
|
|
@float Figure, fig:img1
|
|
|
|
|
@image{Hamlib_design,,,Hamlib Design}
|
|
|
|
|
@caption{Hamlib design---@i{courtesy of Martin Ewing, AA6E}.}
|
|
|
|
|
@shortcaption{Hamlib design}
|
|
|
|
|
@end float
|
|
|
|
|
@*
|
|
|
|
|
@end quotation
|
|
|
|
|
|
|
|
|
|
@cindex Scripting languages
|
|
|
|
|
@cindex Languages, scripting
|
|
|
|
|
@cindex Interface, languages
|
|
|
|
|
Hamlib also provides an interface library for each of several common
|
2018-07-30 03:03:24 +00:00
|
|
|
|
@dfn{scripting} languages such as @url{http://www.perl.org, Perl,
|
|
|
|
|
Perl}, @url{http://www.python.org, Python, Python},
|
|
|
|
|
@url{https://www.lua.org, Lua, Lua} and @url{http://www.tcl.tk, TCL,
|
|
|
|
|
TCL}. These language @dfn{bindings} are generated through the use of
|
|
|
|
|
@url{http://www.swig.org, SWIG, SWIG} a parser/generator for multiple
|
|
|
|
|
language interfaces to a C library. A native generated @emph{C++}
|
2013-03-11 02:17:44 +00:00
|
|
|
|
language interface is also provided.
|
|
|
|
|
|
|
|
|
|
@cindex Daemon, network
|
|
|
|
|
@cindex Network, daemon
|
|
|
|
|
Besides the C and supplemental APIs, Hamlib also provides a pair of
|
|
|
|
|
network daemons that provide a text command based API for controlling
|
2018-07-30 03:03:24 +00:00
|
|
|
|
an attached radio or rotator through a @emph{TCP/IP} network
|
|
|
|
|
connection. The daemons then handle the interface to the Hamlib C
|
|
|
|
|
API.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
2018-07-30 03:03:24 +00:00
|
|
|
|
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.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
@node The Hamlib project
|
|
|
|
|
@section Hamlib project information
|
|
|
|
|
@cindex Hamlib project
|
|
|
|
|
@cindex Project, Hamlib
|
|
|
|
|
|
|
|
|
|
The Hamlib Project was founded by Frank Singleton,VK3FCS/KM5WS in July
|
2018-07-30 03:03:24 +00:00
|
|
|
|
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 (@acronym{ABI}) interfaces have remained
|
|
|
|
|
stable since that time up to the latest release of 3.2 in early 2018.
|
|
|
|
|
|
|
|
|
|
Development continues through the major version number 3.x and beyond.
|
|
|
|
|
While some API tweaks are planned, ABI compatibility with the prior
|
|
|
|
|
1.2.@i{x} releases remains a priority. Other goals include
|
|
|
|
|
streamlining the build system (done), improving the SWIG generated
|
|
|
|
|
language bindings (done), improving the overall documentation (this
|
|
|
|
|
manual, in progress), and other updates as warranted.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
The Project is hosted by @url{https://sourceforge.net/,
|
|
|
|
|
SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/,
|
2018-07-30 03:03:24 +00:00
|
|
|
|
Hamlib project page}. As @url{https://github.com/, GitHub} has become
|
|
|
|
|
a very popular project hosting site, Hamlib also has a dedicated
|
|
|
|
|
@url{https://github.com/Hamlib/Hamlib, GitHub project page}. GitHub
|
|
|
|
|
also hosts the @url{http://www.hamlib.org, hamlib.org} Web site and
|
|
|
|
|
the @url{https://github.com/Hamlib/Hamlib/wiki, Hamlib Wiki}.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
Development discussion and most user support take place on the
|
2018-07-30 03:03:24 +00:00
|
|
|
|
@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer
|
|
|
|
|
mailing list}. While there are
|
2013-03-11 02:17:44 +00:00
|
|
|
|
@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net
|
2018-07-30 03:03:24 +00:00
|
|
|
|
discussion forums}, they are rarely used and not as closely read by
|
|
|
|
|
the developers as the mailing list.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
For @dfn{source code management}, the project uses
|
|
|
|
|
@url{http://git-scm.com/, Git}, a fast, distributed content tracker.
|
|
|
|
|
Among its features is that every developer has the complete Hamlib
|
2018-07-30 03:03:24 +00:00
|
|
|
|
development history available locally. For more information on using
|
|
|
|
|
Git, @pxref{Working with Git}.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
@quotation Note
|
2018-07-30 03:03:24 +00:00
|
|
|
|
While a canonical Git repository is hosted as 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.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
@end quotation
|
|
|
|
|
|
|
|
|
|
@node Applications using Hamlib
|
|
|
|
|
@section Applications using Hamlib
|
|
|
|
|
@cindex Hamlib applications
|
|
|
|
|
@cindex Applications, using Hamlib
|
|
|
|
|
|
|
|
|
|
A number of application developers have taken advantage of Hamlib's
|
2018-07-30 03:03:24 +00:00
|
|
|
|
capabilities to implement radio and/or rotator control. While not
|
2013-03-11 02:17:44 +00:00
|
|
|
|
exhaustive, a list is maintained at the Hamlib Wiki,
|
2018-07-30 03:03:24 +00:00
|
|
|
|
@url{https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots,
|
2013-03-11 02:17:44 +00:00
|
|
|
|
Applications/Screenshots}. Developers are encouraged to request their
|
|
|
|
|
applications be added to the gallery by way of the hamlib-developer
|
|
|
|
|
mailing list.
|
|
|
|
|
|
|
|
|
|
@node Licensing implications
|
|
|
|
|
@section Using Hamlib with your program
|
|
|
|
|
@cindex Hamlib licensing
|
|
|
|
|
@cindex Licensing, Hamlib
|
|
|
|
|
|
2018-07-30 03:03:24 +00:00
|
|
|
|
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 (@acronym{LGPL})
|
|
|
|
|
for the library portion, and the General Public License
|
|
|
|
|
(@acronym{GPL}) for the utility programs.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
The LGPL allows the library to be used (linked) by programs regardless
|
2018-07-30 03:03:24 +00:00
|
|
|
|
of their individual license. However, any contributions to the
|
|
|
|
|
library source remain under copyleft which means that the library
|
|
|
|
|
source code may not be used in violation of the terms of the LGPL.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
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. 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 prohibited.
|
|
|
|
|
|
|
|
|
|
@xref{Copying and Redistribution}.
|
|
|
|
|
|
|
|
|
|
@node Radio cloning
|
|
|
|
|
@section Radios with a clone capability
|
|
|
|
|
@cindex Radio cloning
|
|
|
|
|
@cindex Cloning, radio
|
|
|
|
|
|
|
|
|
|
Hamlib's focus is on controlling rigs that employ a port and command
|
2018-07-30 03:03:24 +00:00
|
|
|
|
protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF
|
2013-03-11 02:17:44 +00:00
|
|
|
|
transceivers do not employ such control capability but do provide for
|
2018-07-30 03:03:24 +00:00
|
|
|
|
cloning the memory contents from radio to another of the same model.
|
|
|
|
|
A related project, @url{http://chirp.danplanet.com/, CHIRP}, aims to
|
|
|
|
|
support radios with such a clone capability. Please contact the CHIRP
|
|
|
|
|
project for support of such radios.
|
2013-03-11 02:17:44 +00:00
|
|
|
|
|
|
|
|
|
@node Pronunciation
|
|
|
|
|
@section Pronouncing Hamlib
|
|
|
|
|
@cindex Pronouncing Hamlib
|
|
|
|
|
@cindex Hamlib, pronouncing
|
|
|
|
|
|
|
|
|
|
English speakers seem to have two alternate pronunciations for our
|
|
|
|
|
project:
|
|
|
|
|
|
|
|
|
|
@itemize @bullet
|
|
|
|
|
@item Hamlib (Ham - lib, long "i", as in library.) IPA style: /'ham læb/
|
|
|
|
|
@item Hamlib (Ham - lib, short "i", as in liberty.) IPA style: /'ham lɪb/
|
|
|
|
|
@end itemize
|
|
|
|
|
|
|
|
|
|
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! :-)
|