1HAMLIB(7) Hamlib Information Manual HAMLIB(7)
2
6 hamlib - radio and rotator control library
7
9 The Ham Radio Control Libraries, Hamlib for short, is a development
10 effort to provide a consistent interface for programmers wanting to
11 incorporate radio and rotator control in their programs.
12 Hamlib is not a complete user application, rather, it is a software
14 layer intended to make controlling various radios and other amateur
15 radio station (shack) hardware much easier. Hamlib will allow authors
16 of software such as logging programs, digital communications programs,
17 or those wanting to develop the ultimate radio control software to con‐
18 centrate on the user interface and the basic function of the program
19 rather than radio control. Hamlib consists of several parts, the pro‐
20 gramming library, utility programs, and library interfaces to other
21 programming languages.
22 Most recent amateur radio transceivers allow external control of their
24 functions through a serial interface. Unfortunately, control commands
25 are not always consistent across a manufacturer's product line and each
26 manufacturer's product line differs greatly from its competitors.
27 Hamlib attempts to solve this problem by presenting a virtual radio to
29 the programmer by providing an interface to actions such as setting a
30 given Variable Frequency Oscillator's (VFO) frequency, setting the
31 operating mode, querying the radio of its current status and settings,
32 and giving the application a list of a given radio's capabilities.
33 Unfortunately, what can be accomplished by Hamlib is limited by the
34 radios themselves and some offer very limited capability.
35 Other devices, such as antenna rotators, can be placed into the Hamlib
37 control scheme. Other recent developments include network interface
38 servers and a USB interface capability. Language bindings are provided
39 for C, C++, Perl, Python, Lua and TCL (more to come).
40 Overview
42 Hamlib is a front end library providing a C language Application Pro‐
43 gramming Interface (API) to programmers wishing to integrate radio or
44 rotator control in their applications. Hamlib presents a virtual radio
45 or virtual rotator that is a consistent interface to an application
46 despite wide differences in radio and rotator interfaces and capabili‐
47 ties.
48 The front end library uses a number of back end libraries to translate
50 from the front end to the various individual radio and rotator models.
51 A back end library handles conversion of the front end variables to the
52 format needed by the radio or rotator device it controls. The back end
53 libraries are generally grouped by manufacturer and in some cases by a
54 common control protocol.
55 Hamlib also provides an interface library for each of several common
57 scripting languages such as Perl ⟨http://www.perl.org⟩, Python
58 ⟨http://www.python.org⟩, Lua ⟨https://www.lua.org⟩, and TCL
59 ⟨http://www.tcl.tk⟩. These language bindings are generated through the
60 use of SWIG ⟨http://www.swig.org⟩, a parser/generator for multiple lan‐
61 guage interfaces to a C library. A natively generated C++ language
62 interface is also provided.
63 Besides the C and supplemental APIs, Hamlib also provides a pair of
65 network daemons that provide a text command based API for controlling
66 an attached radio or rotator through a TCP/IP network connection. The
67 daemons then handle the interface to the Hamlib C API.
68 More than one type of device, radio or rotator, may be controlled at a
70 time, however, there is generally a limit of one device per serial port
71 or other port.
72 Hamlib project information
74 The Hamlib Project was founded by Frank Singleton, VK3FCS/KM5WS in July
75 2000. Shortly after Stephane Fillod, F8CFE, joined Frank on the Hamlib
76 project and the API and implementation development led to a reasonable
77 level of maturity in a few years. A major milestone was reached when
78 Hamlib 1.2.0 was released in March 2004. The API and Application
79 Binary Interface (ABI) interfaces have remained stable since that time
80 up to the release of 3.3 in mid 2018. Version 4.0 marks a major change
81 to the ABI and certain changes to the API.
82 Development continues through the major version number 4.x series and
84 beyond. The 4.0 release marks a major change in the ABI with several
85 changes for additional modes and such that will require client programs
86 that use the C ABI to be recompiled/relinked, etc. Other goals include
87 improving the overall documentation (this man page with more in
88 progress), and other updates as warranted.
89 The Project is hosted by SourceForge.net ⟨https://sourceforge.net⟩ at
91 the Hamlib project page ⟨https://sourceforge.net/projects/hamlib/⟩. As
92 GitHub ⟨https://github.com⟩ has become a very popular project hosting
93 site, Hamlib also has a dedicated GitHub project page
94 ⟨https://github.com/Hamlib/Hamlib⟩. GitHub also hosts the hamlib.org
95 ⟨http://www.hamlib.org⟩ Web site and the Hamlib Wiki
96 ⟨https://github.com/Hamlib/Hamlib/wiki⟩.
97 Development discussion and most user support take place on the hamlib-
99 developer mailing list ⟨https://sourceforge.net/p/hamlib/mailman/⟩.
100 While there are SourceForge.net discussion forums
101 ⟨https://sourceforge.net/p/hamlib/discussion/⟩, they are rarely used
102 and not as closely read by the developers as the mailing list.
103 For source code management, the project uses Git ⟨http://git-scm.com/⟩,
105 a fast, distributed content tracker. Among its features is that every
106 developer has the complete Hamlib development history available
107 locally. For more information on using Git, see hamlib-git(7).
108 Note: while a canonical Git repository is hosted at SourceForge,
110 its availability is not essential to continued development
111 although development work flows would change temporarily. Sev‐
112 eral developers find the GitHub Web interface easier to use and
113 lately development has centered around GitHub rather than
114 SourceForge.
115 Applications using Hamlib
117 A number of application developers have taken advantage of Hamlib's
118 capabilities to implement radio and/or rotator control. While not
119 exhaustive, a list is maintained at the Hamlib Wiki,
120 Applications/Screenshots
121 ⟨https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots⟩.
122 Developers are encouraged to request their applications be added to the
123 gallery by way of the hamlib-developer mailing list.
124 Using Hamlib with your program
126 As with other Free Software projects, Hamlib relies heavily on copyleft
127 licensing to encourage development contributions and provide an open
128 atmosphere for development. Hamlib's source code is released under two
129 licenses, the Lesser General Public License (LGPL) version 2.1 for the
130 library portion, and the General Public License (GPL) version 2 for the
131 utility programs.
132 The LGPL allows the library to be used (linked) by programs regardless
134 of their individual license. However, any contributions to the library
135 source remain under a copyleft license which means that the library
136 source code may not be used in violation of the terms of the LGPL (see
137 the file COPYING.LIB in the main source directory). Concepts learned
138 by studying these sources for the purpose of understanding the Hamlib
139 API is not covered nor prohibited by the LGPL, however, directly copy‐
140 ing LGPL sources into any work that is incompatible with the terms of
141 the LGPL is a violation of the terms of the license.
142 The utility program source files are released under the GPL. Any
144 direct use of these sources must be in a form that complies with the
145 terms of the GPL (see the file COPYING in the main source directory).
146 Concepts learned by studying these sources for the purpose of under‐
147 standing the Hamlib API is not covered nor prohibited by the GPL, how‐
148 ever, directly copying GPL sources into any work that is incompatible
149 with the terms of the GPL is a violation of the terms of the license.
150 Radios with a clone capability
152 Hamlib's focus is on controlling radios that employ a port and command
153 protocol for setting frequency, mode, VFO, PTT, etc. Most VHF/UHF
154 transceivers do not employ such control capability but do provide for
155 cloning the memory contents from radio to another of the same model. A
156 related project, Chirp ⟨http://chirp.danplanet.com⟩, aims to support
157 radios with such a clone capability. Please contact the Chirp project
158 for support of such radios.
159 Pronouncing Hamlib
161 English speakers seem to have two alternate pronunciations for our
162 project:
163 · Hamlib (Ham - lib, long ‘i’, as in library.) IPA style: /'ham læb/
165 · Hamlib (Ham - lib, short ‘i’, as in liberty.) IPA style: /'ham lɪb/
167 Then again, we have people who say Linux “L-eye-nux” and those who say
169 “L-in-nux”...
170 If you're French, the above does not apply! :-)
172
174 This file is part of Hamlib, a project to develop a library that sim‐
175 plifies radio, rotator, and amplifier control functions for developers
176 of software primarily of interest to radio amateurs and those inter‐
177 ested in radio communications.
178 Copyright © 2001-2020 Hamlib Group (various contributors)
180 This is free software; see the file COPYING for copying conditions.
182 There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
183 PARTICULAR PURPOSE.
184
186 hamlib-primer(7)
187
189 Links to the Hamlib Wiki, Git repository, release archives, and daily
190 snapshot archives are available via hamlib.org ⟨http://www.hamlib.org⟩.
191Hamlib 2020-09-08 HAMLIB(7)