NAME

       hamlib - radio and rotator control library

DESCRIPTION

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

   Overview
       Hamlib is a front end  library  providing  a  C  language  Application  Programming  Interface  (API)  to
       programmers  wishing  to  integrate  radio  or  rotator control in their applications.  Hamlib presents a
       virtual radio or virtual  rotator  that  is  a  consistent  interface  to  an  application  despite  wide
       differences in radio and rotator interfaces and capabilities.

       The  front end library uses a number of 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.

       Hamlib  also  provides  an interface library for each of several common scripting languages such as Perl,
       Python, Lua, and TCL.  These language bindings are generated through the use of SWIG, a  parser/generator
       for  multiple  language  interfaces  to a C library.  A natively generated C++ language interface is also
       provided.

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

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

       Development continues through the major version number 4.x series and beyond.  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.  Other goals include  improving  the  overall
       documentation (this man page with more in progress), and other updates as warranted.

       The Project is hosted by SourceForge.net at the Hamlib project page.  As GitHub has become a very popular
       project  hosting site, Hamlib also has a dedicated GitHub project page.  GitHub also hosts the hamlib.org
       Web site and the Hamlib Wiki.

       Development discussion and most user support take  place  on  the  hamlib-developer mailing list.   While
       there  are  SourceForge.net discussion forums,  they  are  rarely  used  and  not  as closely read by the
       developers as the mailing list.

       For source code management, the project uses  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, see hamlib-git(7).

              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.

   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,
       Applications/Screenshots.   Developers  are  encouraged  to  request  their  applications be added to the
       gallery by way of the hamlib-developer mailing list.

   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 Lesser General  Public  License  (LGPL)  version  2.1  for  the  library
       portion, and the General Public License (GPL) version 2 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 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 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.

       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 (see the file  COPYING  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 GPL, however, directly copying GPL sources into any work that is incompatible with
       the terms of the GPL is a violation of the terms of the license.

   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, Chirp,  aims  to
       support  radios  with  such  a  clone  capability.   Please contact the Chirp project for support of such
       radios.

   Pronouncing Hamlib
       English speakers seem to have two alternate pronunciations for our project:

       •   Hamlib (Ham - lib, long ‘i’, as in library.)  IPA style: /'ham læb/

       •   Hamlib (Ham - lib, short ‘i’, as in liberty.)  IPA style: /'ham lɪb/

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

COPYING

       This file is part of Hamlib, a project to develop a library that simplifies radio, rotator, and amplifier
       control functions for developers of software primarily of interest to radio amateurs and those interested
       in radio communications.

       Copyright © 2001-2020 Hamlib Group (various contributors)

       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.

SEE ALSO

       hamlib-primer(7)

COLOPHON

       Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot archives are available via
       hamlib.org.

Hamlib                                             2020-09-08                                          HAMLIB(7)