oracular (7) hamlib.7.gz

Provided by: libhamlib-utils_4.5.5-4_amd64 bug

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 Perlhttp://www.perl.org⟩,   Pythonhttp://www.python.org⟩,    Lua    ⟨https://www.lua.org⟩,    and    TCLhttp://www.tcl.tk⟩.     These    language   bindings   are   generated   through   the   use   of   SWIGhttp://www.swig.org⟩, 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  ⟨https://sourceforge.net⟩  at  the  Hamlib  project   page
       ⟨https://sourceforge.net/projects/hamlib/⟩.   As  GitHub  ⟨https://github.com⟩  has become a very popular
       project hosting site, Hamlib also has a dedicated GitHub project page ⟨https://github.com/Hamlib/Hamlib⟩.
       GitHub   also   hosts   the   hamlib.org   ⟨http://www.hamlib.org⟩   Web   site   and   the  Hamlib  Wiki
       ⟨https://github.com/Hamlib/Hamlib/wiki⟩.

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

       For  source  code  management,  the  project  uses Githttp://git-scm.com/⟩, 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           ⟨https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots⟩.
       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,  Chirphttp://chirp.danplanet.com⟩,  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 ⟨http://www.hamlib.org⟩.