Hamlib/doc/nutshell.texi

The @dfn{Ham Radio Control Libraries}, @dfn{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).

@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
@cindex Virtual rotator
Hamlib is a @dfn{front end} library providing a @emph{C} language
Application Programming Interface @acronym{API} to programmers wishing
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.

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

@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
@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++}
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
an attached radio or rotator through a @emph{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.

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

The Project is hosted by @url{https://sourceforge.net/,
SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/,
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}.

Development discussion and most user support take place on the
@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer
mailing list}.  While there are
@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net
discussion forums}, they are rarely used and not as closely read by
the developers as the mailing list.

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
development history available locally.  For more information on using
Git, @pxref{Working with Git}.

@quotation Note
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.
@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
capabilities to implement radio and/or rotator control.  While not
exhaustive, a list is maintained at the Hamlib Wiki,
@url{https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots,
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

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.

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 copyleft which means that the library
source code may not be used in violation of the terms of the LGPL.

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

@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! :-)