2018-07-30 03:00:14 +00:00
|
|
|
|
.\" Hey, EMACS: -*- nroff -*-
|
|
|
|
|
.\"
|
|
|
|
|
.\" For layout and available macros, see man(7), man-pages(7), groff_man(7)
|
|
|
|
|
.\" Please adjust the date whenever revising the manpage.
|
|
|
|
|
.\"
|
|
|
|
|
.\" Please keep this file in sync with doc/nutshell.texi
|
|
|
|
|
.\"
|
2020-09-10 13:40:04 +00:00
|
|
|
|
.TH HAMLIB "7" "2020-09-08" "Hamlib" "Hamlib Information Manual"
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SH NAME
|
|
|
|
|
.
|
|
|
|
|
hamlib \- radio and rotator control library
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
.
|
|
|
|
|
The
|
|
|
|
|
.BR "Ham Radio Control Libraries" ,
|
|
|
|
|
.B Hamlib
|
|
|
|
|
for short, is a development effort to provide a consistent interface for
|
|
|
|
|
programmers wanting to incorporate radio and rotator control in their
|
|
|
|
|
programs.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
Hamlib attempts to solve this problem by presenting a
|
|
|
|
|
.I 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.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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
|
|
|
|
|
.BR C ", " C++ ", " Perl ", " Python ", " Lua " and " TCL
|
|
|
|
|
(more to come).
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SS Overview
|
|
|
|
|
.
|
|
|
|
|
Hamlib is a
|
|
|
|
|
.I front end
|
|
|
|
|
library providing a
|
|
|
|
|
.B C
|
|
|
|
|
language Application Programming Interface (API) to programmers wishing to
|
|
|
|
|
integrate radio or rotator control in their applications.
|
|
|
|
|
.
|
|
|
|
|
Hamlib presents a
|
|
|
|
|
.I virtual radio
|
|
|
|
|
or
|
|
|
|
|
.I virtual rotator
|
|
|
|
|
that is a consistent interface to an application despite wide differences in
|
|
|
|
|
radio and rotator interfaces and capabilities.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
The front end library uses a number of
|
|
|
|
|
.I 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.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
Hamlib also provides an interface library for each of several common
|
|
|
|
|
.I scripting
|
|
|
|
|
languages such as
|
|
|
|
|
.UR http://www.perl.org
|
|
|
|
|
.B Perl
|
|
|
|
|
.UE ,
|
|
|
|
|
.UR http://www.python.org
|
|
|
|
|
.B Python
|
|
|
|
|
.UE ,
|
|
|
|
|
.UR https://www.lua.org
|
|
|
|
|
.B Lua
|
|
|
|
|
.UE ,
|
|
|
|
|
and
|
|
|
|
|
.UR http://www.tcl.tk
|
|
|
|
|
.B TCL
|
|
|
|
|
.UE .
|
|
|
|
|
.
|
|
|
|
|
These language
|
|
|
|
|
.I bindings
|
|
|
|
|
are
|
|
|
|
|
generated through the use of
|
|
|
|
|
.UR http://www.swig.org
|
|
|
|
|
.B SWIG
|
|
|
|
|
.UE ,
|
|
|
|
|
a parser/generator for multiple language interfaces to a
|
|
|
|
|
.B C
|
|
|
|
|
library.
|
|
|
|
|
.
|
|
|
|
|
A natively generated
|
|
|
|
|
.B C++
|
|
|
|
|
language interface is also provided.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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
|
|
|
|
|
.BR TCP / IP
|
|
|
|
|
network connection.
|
|
|
|
|
.
|
|
|
|
|
The daemons then handle the interface to the Hamlib C API.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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.
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SS 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
|
2020-09-10 13:40:04 +00:00
|
|
|
|
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.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
Development continues through the major version number
|
2020-09-10 13:40:04 +00:00
|
|
|
|
.RI 4. x
|
2018-07-30 03:00:14 +00:00
|
|
|
|
series and beyond.
|
|
|
|
|
.
|
2020-09-10 13:40:04 +00:00
|
|
|
|
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.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
2020-09-10 13:40:04 +00:00
|
|
|
|
Other goals include improving the overall documentation (this man page with
|
|
|
|
|
more in progress), and other updates as warranted.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
The Project is hosted by
|
|
|
|
|
.UR https://sourceforge.net
|
|
|
|
|
SourceForge.net
|
|
|
|
|
.UE
|
|
|
|
|
at the
|
|
|
|
|
.UR https://sourceforge.net/projects/hamlib/
|
|
|
|
|
Hamlib project page
|
|
|
|
|
.UE .
|
|
|
|
|
.
|
|
|
|
|
As
|
|
|
|
|
.UR https://github.com
|
|
|
|
|
GitHub
|
|
|
|
|
.UE
|
|
|
|
|
has become a very popular project hosting site, Hamlib also has a dedicated
|
|
|
|
|
.UR https://github.com/Hamlib/Hamlib
|
|
|
|
|
GitHub project page
|
|
|
|
|
.UE .
|
|
|
|
|
.
|
|
|
|
|
GitHub also hosts the
|
|
|
|
|
.UR http://www.hamlib.org
|
|
|
|
|
hamlib.org
|
|
|
|
|
.UE
|
|
|
|
|
Web site and the
|
|
|
|
|
.UR https://github.com/Hamlib/Hamlib/wiki
|
|
|
|
|
Hamlib Wiki
|
|
|
|
|
.UE .
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
Development discussion and most user support take place on the
|
|
|
|
|
.UR https://sourceforge.net/p/hamlib/mailman/
|
|
|
|
|
hamlib-developer mailing list
|
|
|
|
|
.UE .
|
|
|
|
|
While there are
|
|
|
|
|
.UR https://sourceforge.net/p/hamlib/discussion/
|
|
|
|
|
SourceForge.net discussion forums
|
|
|
|
|
.UE ,
|
|
|
|
|
they are rarely used and not as closely read by the developers as the mailing
|
|
|
|
|
list.
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
For
|
|
|
|
|
.IR "source code management" ,
|
|
|
|
|
the project uses
|
|
|
|
|
.UR http://git-scm.com/
|
|
|
|
|
.B Git
|
|
|
|
|
.UE ,
|
|
|
|
|
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
|
|
|
|
|
.BR hamlib\-git (7).
|
|
|
|
|
.
|
|
|
|
|
.IP
|
|
|
|
|
.BR 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.
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SS 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,
|
|
|
|
|
.UR https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots
|
|
|
|
|
Applications/Screenshots
|
|
|
|
|
.UE .
|
|
|
|
|
Developers are encouraged to request their applications be added to the
|
|
|
|
|
gallery by way of the hamlib-developer mailing list.
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SS 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
|
|
|
|
|
.B Lesser General Public License
|
2020-09-10 13:40:04 +00:00
|
|
|
|
(LGPL) version 2.1 for the library portion, and the
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.B General Public License
|
2020-09-10 13:40:04 +00:00
|
|
|
|
(GPL) version 2 for the utility programs.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
The LGPL allows the library to be used (linked) by programs regardless of
|
|
|
|
|
their individual license.
|
|
|
|
|
.
|
2020-09-10 13:40:04 +00:00
|
|
|
|
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
|
|
|
|
|
.B 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.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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
|
2020-09-10 13:40:04 +00:00
|
|
|
|
of the GPL (see the file
|
|
|
|
|
.B COPYING
|
|
|
|
|
in the main source directory).
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
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
|
2020-09-10 13:40:04 +00:00
|
|
|
|
GPL is a violation of the terms of the license.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SS 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,
|
|
|
|
|
.UR http://chirp.danplanet.com
|
2020-09-10 13:40:04 +00:00
|
|
|
|
.B Chirp
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.UE ,
|
|
|
|
|
aims to support radios with such a clone capability.
|
|
|
|
|
.
|
2020-09-10 13:40:04 +00:00
|
|
|
|
Please contact the Chirp project for support of such radios.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SS Pronouncing Hamlib
|
|
|
|
|
.
|
|
|
|
|
English speakers seem to have two alternate pronunciations for our project:
|
|
|
|
|
.
|
|
|
|
|
.nf
|
|
|
|
|
.IP \(bu 4
|
|
|
|
|
Hamlib (Ham \- lib, long \(oqi\(cq, as in library.) IPA style: /\(aqham læb/
|
|
|
|
|
.
|
|
|
|
|
.IP \(bu 4
|
|
|
|
|
Hamlib (Ham \- lib, short \(oqi\(cq, as in liberty.) IPA style: /\(aqham lɪb/
|
|
|
|
|
.fi
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
Then again, we have people who say Linux \(lqL-eye-nux\(rq and those who say
|
|
|
|
|
\(lqL-in-nux\(rq...
|
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
If you're French, the above does not apply! :-)
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SH COPYING
|
|
|
|
|
.
|
|
|
|
|
This file is part of Hamlib, a project to develop a library that simplifies
|
2020-09-10 13:40:04 +00:00
|
|
|
|
radio, rotator, and amplifier control functions for developers of software
|
|
|
|
|
primarily of interest to radio amateurs and those interested in radio
|
|
|
|
|
communications.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.PP
|
2020-09-10 13:40:04 +00:00
|
|
|
|
Copyright \(co 2001-2020 Hamlib Group (various contributors)
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.
|
|
|
|
|
.PP
|
|
|
|
|
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.
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
.
|
|
|
|
|
.BR hamlib-primer (7)
|
|
|
|
|
.
|
|
|
|
|
.
|
|
|
|
|
.SH COLOPHON
|
|
|
|
|
.
|
|
|
|
|
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot
|
2020-09-10 13:40:04 +00:00
|
|
|
|
archives are available via
|
|
|
|
|
.
|
2018-07-30 03:00:14 +00:00
|
|
|
|
.UR http://www.hamlib.org
|
|
|
|
|
hamlib.org
|
|
|
|
|
.UE .
|