1HAMLIB(7)                  Hamlib Information Manual                 HAMLIB(7)
2
3
4

NAME

6       hamlib - radio and rotator control library
7

DESCRIPTION

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
13       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
23       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
28       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
36       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
41   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
49       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
56       Hamlib  also  provides  an interface library for each of several common
57       scripting  languages  such  as   Perl   http://www.perl.org⟩,   Python
58http://www.python.org⟩,    Lua    https://www.lua.org⟩,    and    TCL
59http://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
64       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
69       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
73   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 latest release of 3.2 in early 2018.
81
82       Development continues through the major version number 3.x  series  and
83       beyond.   While some API tweaks are planned, ABI compatibility with the
84       prior 1.2.x releases remains a priority.  Other goals  include  stream‐
85       lining  the  build system (done), improving the SWIG generated language
86       bindings (done), improving the overall  documentation  (this  man  page
87       with more in progress), and other updates as warranted.
88
89       The  Project  is hosted by SourceForge.net ⟨https://sourceforge.net⟩ at
90       the Hamlib project page ⟨https://sourceforge.net/projects/hamlib/⟩.  As
91       GitHub  ⟨https://github.com⟩  has become a very popular project hosting
92       site,   Hamlib   also   has   a   dedicated   GitHub    project    page
93https://github.com/Hamlib/Hamlib⟩.   GitHub  also hosts the hamlib.org
94http://www.hamlib.org⟩    Web    site    and    the    Hamlib     Wiki
95https://github.com/Hamlib/Hamlib/wiki⟩.
96
97       Development  discussion and most user support take place on the hamlib-
98       developer  mailing  list   ⟨https://sourceforge.net/p/hamlib/mailman/⟩.
99       While      there      are     SourceForge.net     discussion     forums
100https://sourceforge.net/p/hamlib/discussion/⟩, they  are  rarely  used
101       and not as closely read by the developers as the mailing list.
102
103       For source code management, the project uses Git http://git-scm.com/⟩,
104       a fast, distributed content tracker.  Among its features is that  every
105       developer   has  the  complete  Hamlib  development  history  available
106       locally.  For more information on using Git, see hamlib-git(7).
107
108              Note: while a canonical Git repository is hosted at SourceForge,
109              its  availability  is  not  essential  to  continued development
110              although development work flows would change temporarily.   Sev‐
111              eral  developers find the GitHub Web interface easier to use and
112              lately  development  has  centered  around  GitHub  rather  than
113              SourceForge.
114
115   Applications using Hamlib
116       A  number  of  application  developers have taken advantage of Hamlib's
117       capabilities to implement radio  and/or  rotator  control.   While  not
118       exhaustive,    a    list    is   maintained   at   the   Hamlib   Wiki,
119       Applications/Screenshots
120https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots⟩.
121       Developers are encouraged to request their applications be added to the
122       gallery by way of the hamlib-developer mailing list.
123
124   Using Hamlib with your program
125       As with other Free Software projects, Hamlib relies heavily on copyleft
126       licensing to encourage development contributions and  provide  an  open
127       atmosphere for development.  Hamlib's source code is released under two
128       licenses, the Lesser General Public License (LGPL) for the library por‐
129       tion, and the General Public License (GPL) for the utility programs.
130
131       The  LGPL allows the library to be used (linked) by programs regardless
132       of their individual license.  However, any contributions to the library
133       source  remain  under copyleft which means that the library source code
134       may not be used in violation of the terms of the LGPL.
135
136       The utility program source files  are  released  under  the  GPL.   Any
137       direct  use  of  these sources must be in a form that complies with the
138       terms of the GPL.  Concepts learned by studying these sources  for  the
139       purpose  of  understanding the Hamlib API is not covered nor prohibited
140       by the GPL, however, directly copying GPL sources into any work that is
141       incompatible with the terms of the GPL is prohibited.
142
143   Radios with a clone capability
144       Hamlib's  focus is on controlling radios that employ a port and command
145       protocol for setting frequency, mode,  VFO,  PTT,  etc.   Most  VHF/UHF
146       transceivers  do  not employ such control capability but do provide for
147       cloning the memory contents from radio to another of the same model.  A
148       related  project,  CHIRP  ⟨http://chirp.danplanet.com⟩, aims to support
149       radios with such a clone capability.  Please contact the CHIRP  project
150       for support of such radios.
151
152   Pronouncing Hamlib
153       English  speakers  seem  to  have  two alternate pronunciations for our
154       project:
155
156       ·   Hamlib (Ham - lib, long ‘i’, as in library.)  IPA style: /'ham læb/
157
158       ·   Hamlib (Ham - lib, short ‘i’, as in liberty.)  IPA style: /'ham lɪb/
159
160       Then again, we have people who say Linux “L-eye-nux” and those who  say
161       “L-in-nux”...
162
163       If you're French, the above does not apply! :-)
164

COPYING

166       This  file  is part of Hamlib, a project to develop a library that sim‐
167       plifies radio and rotator control functions for developers of  software
168       primarily  of  interest to radio amateurs and those interested in radio
169       communications.
170
171       Copyright © 2001-2018 Hamlib Group (various contributors)
172
173       This is free software; see the file  COPYING  for  copying  conditions.
174       There  is  NO  warranty;  not even for MERCHANTABILITY or FITNESS FOR A
175       PARTICULAR PURPOSE.
176

SEE ALSO

178       hamlib-primer(7)
179

COLOPHON

181       Links to the Hamlib Wiki, Git repository, release archives,  and  daily
182       snapshot archives:
183
184              hamlib.org ⟨http://www.hamlib.org⟩.
185
186
187
188Hamlib                            2018-05-21                         HAMLIB(7)
Impressum