diff --git a/doc/Hamlib_design.png b/doc/Hamlib_design.png new file mode 100644 index 000000000..b21ed02e1 Binary files /dev/null and b/doc/Hamlib_design.png differ diff --git a/doc/Makefile.am b/doc/Makefile.am index 916b13fd2..1a2e16b32 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html -dist_doc_DATA = hamlib.html hamlib.pdf +dist_doc_DATA = Hamlib_design.png hamlib.html hamlib.pdf SRCDOCLST = ../src/rig.c ../src/rotator.c ../src/tones.c ../src/locator.c \ ../src/event.c ../src/conf.c ../src/mem.c ../src/settings.c diff --git a/doc/hamlib.texi b/doc/hamlib.texi index 7ec76ee3b..eb732de86 100644 --- a/doc/hamlib.texi +++ b/doc/hamlib.texi @@ -2,6 +2,7 @@ @c %**start of header @setfilename hamlib.info @include version.texi +@documentencoding UTF-8 @settitle Ham Radio Control Libraries @value{VERSION} @c %**end of header @@ -9,7 +10,7 @@ This manual is for the Ham Radio Control Libraries (version @value{VERSION} updated @value{UPDATED}), which is a development effort to provide a consistent programming interface for programmers wanting to incorporate -radio and rotator control into their programs. +radio and rotor control into their programs. Copyright @copyright{} 2013 Nate Bargmann @@ -42,79 +43,401 @@ License''. @ifnottex @node Top -@top Hamlib +@top Ham Radio Control Libraries -This manual is for Ham Radio Control Libraries (version @value{VERSION}, +This manual is for Ham Radio Control Libraries (Hamlib) (version @value{VERSION}, @value{UPDATED}). @end ifnottex @menu * Copying and Redistribution:: * Hamlib in a Nutshell:: +* Getting started:: * GNU Free Documentation License:: -* Index:: +* Working with Git:: +* List of Figures:: +* Concept Index:: @end menu + @node Copying and Redistribution -@chapter Copying and Redistribution +@unnumbered Copying and Redistribution +@cindex Copying, redistribution +@cindex Redistribution, copying +@cindex Copyleft -This manual describes Hamlib, a programming library and various supplied -programs, which is Free Software. Besides often being distributed at no -cost to you, Free in this context means that the copyright holders to -Hamlib have agreed to offer their collective work under terms that give you +This manual documents Hamlib, a programming library and various supplied +programs, which is +@url{http://en.wikipedia.org/wiki/Free_Software_Definition, Free +Software, Free Software}. Besides often being distributed at no cost to +you, Free in this context means that the copyright holders to Hamlib +have agreed to offer their collective work under terms that give you certain rights that allow you to modify and/or redistribute Hamlib under -the same terms that you received it. +the same terms that you received it from them. -Such licensing is often termed ``copyleft'' as a play against the common -``all rights reserved'' terms of normal copyright. In general, copyleft -provides everyone with a license to modify and distribute the modified work -or to simply distribute a copyrighted work under certain terms. Hamlib -source code is copyrighted by its authors and is licensed by them under two -common licenses---the GNU Lesser General Public License (LGPL) for the -``front end'' and ``back end'' library source code files, and the GNU -General Public License (GPL) for the supplied programs source code files. -The full text of the LGPL and the GPL can be found in the files COPYING.LIB -and COPYING in the root directory of the Hamlib source archive. +Such licensing is often termed +@url{http://en.wikipedia.org/wiki/Copyleft, copyleft, copyleft} as a +play against the common ``all rights reserved'' terms of normal +@url{http://en.wikipedia.org/wiki/Copyright, copyright, copyright}. In +general, copyleft provides everyone with a license to modify and +distribute the modified work or to simply distribute a copyrighted work +under certain terms. Hamlib source code is copyrighted by its authors +and is licensed by them under two common licenses---the +@url{http://en.wikipedia.org/wiki/GNU_Lesser_General_Public_License, GNU +Lesser General Public License, GNU Lesser General Public License} +@acronym{LGPL} for the ``front end'' and ``back end'' library source +code files, and the +@url{http://en.wikipedia.org/wiki/GNU_General_Public_License, GNU +General Public License, GNU General Public License} @acronym{GPL} for +the supplied programs source code files. The full text of the LGPL and +the GPL can be found in the files COPYING.LIB and COPYING in the root +directory of the Hamlib source archive. -This manual is covered by the GNU Free Documentation License, with no -invariant and no cover texts. Source code examples in this manual are -parallel licensed under the GPL unless otherwise noted. +This manual is covered by the +@url{http://en.wikipedia.org/wiki/GNU_Free_Documentation_License, GNU +Free Documentation License, GNU Free Documentation License} +@acronym{GFDL} with no Invariant Sections, no Front-Cover Texts, and no +Back-Cover Texts. Source code examples in this manual are parallel +licensed under the GPL unless otherwise noted. -As part of the Copyleft nature of the licenses, the authors of Hamlib must -forbid you from distributing Hamlib under terms that forbid others from -exercising the same rights you received. You must give anyone you -distribute Hamlib to the same rights to obtain, modify, and distribute the -Hamlib source code that you received nor may you license Hamlib under other -terms than those you received. Any recipients of Hamlib must be informed -of the rights to the source code that they have received. +As part of the Copyleft nature of the licenses, the authors of Hamlib +must forbid you from distributing Hamlib under terms that forbid others +from exercising the same rights you received. You must give anyone you +distribute Hamlib to the same rights to obtain, modify, and distribute +the Hamlib source code that you received nor may you license Hamlib +under other terms than those you received. Any recipients of Hamlib +must be informed of the rights to the source code that they have +received. -Finally, the authors of Hamlib require that it be understood that no -warranty of any kind is offered to anyone receiving the Hamlib source code -distribution. Anyone distributing modified versions of Hamlib has the -responsibility to inform any recipients that what they have is not the -official release of Hamlib by its authors and should be prepared to support -the modified version(s). This is to preserve the reputations of the Hamlib -authors and the Hamlib Project. While it is not a requirement of the -licenses, it is courteous to offer modifications back to the Hamlib authors -for possible incorporation into their official release(s). +@cindex NO WARRANTY +Finally, the authors of Hamlib require that it be understood that NO +WARRANTY of any kind is offered to anyone receiving the Hamlib source +code distribution. Anyone distributing modified versions of Hamlib has +the responsibility to inform any recipients that what they have is not +the official release of Hamlib by its authors and should be prepared to +support the modified version(s). This is to preserve the reputations of +the Hamlib authors and the Hamlib Project. While it is not a +requirement of the licenses, it is courteous to offer modifications back +to the Hamlib authors for possible incorporation into their official +release(s). + +@c ------------ Chapter ------------ @node Hamlib in a Nutshell @chapter Hamlib in a Nutshell +@cindex Nutshell -Hamlib is a ``front end'' library providing a C language Application -Programming Interface (API) that provides a ``virtual radio'' or ``virtual -rotator'' to an application. The front end library uses a number of ``back -end'' libraries to translate to individual radio models. Hamlib also -provides an interface library to several ``scripting'' languages such as -Perl, Python, and TCL (known as ``bindings''). A C++ language interface is -also provided. +The @dfn{Ham Radio Control Libraries}, @dfn{Hamlib} for short, is a +development effort to provide a consistent interface for programmers +wanting to incorporate radio control in their programs. -Besides the C and supplemental APIs, Hamlib also provides a pair a network -daemons that provide an API for controlling an attached radio or rotator -through a network connection. +Hamlib is not a complete user application, rather, it is a software +layer intended to make controlling various radios and other shack +hardware much easier. Hamlib will allow authors of such software 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 VFO's 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 rotors, 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, and TCL (more to come). + +@menu +* Overview:: +* The Hamlib project:: +* Applications using Hamlib:: +* Licensing implications:: +* Radio cloning:: +* Pronunciation:: +@end menu + +@node Overview +@section A view from the top of the tower +@cindex Overview + +@cindex Front end library +@cindex Virtual radio +@cindex Virtual rotor +Hamlib is a @dfn{front end} library providing a @emph{C} language +Application Programming Interface @acronym{API} to programmers wishing +to integrate radio or rotor control in their applications. Hamlib +presents a @dfn{virtual radio} or @dfn{virtual rotor} that is a +consistent interface to an application despite wide differences in radio +and rotor interfaces and capabilities. + +@cindex Back end library +The front end library uses a number of @dfn{back end} libraries to +translate from the front end to the various individual radio and +rotor models. A back end library handles conversion of the +front end variables to the format needed by the radio or rotor +device it controls. The back end libraries are generally grouped by +manufacturer and in some cases by a common control protocol. + +@quotation +Since a picture is worth quite a few words, here is a visual representation +of Hamlib's design. +@ifhtml +@*@* +@end ifhtml +@float Figure, fig:img1 +@image{Hamlib_design,,,Hamlib Design} +@caption{Hamlib design---@i{courtesy of Martin Ewing, AA6E}.} +@shortcaption{Hamlib design} +@end float +@* +@end quotation + +@cindex Scripting languages +@cindex Languages, scripting +@cindex Interface, languages +Hamlib also provides an interface library for each of several common +@dfn{scripting} languages such as @url{http://www.perl.org, Perl, Perl}, +@url{http://www.python.org, Python, Python}, and @url{http://www.tcl.tk, +TCL, TCL}. These language @dfn{bindings} are generated through the use +of @url{http://www.swig.org, SWIG, SWIG} a parser/generator for multiple +language interfaces to a C library. A native generated @emph{C++} +language interface is also provided. + +@cindex Daemon, network +@cindex Network, daemon +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 rotor through a @emph{TCP/IP} network connection. +The daemons then handle the interface to the Hamlib C API. + +More than one type of device, radio or rotor, may be controlled at a +time, however, there is generally a limit of one device per serial port +or other port. + +@node The Hamlib project +@section Hamlib project information +@cindex Hamlib project +@cindex Project, Hamlib + +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 (@acronym{ABI}) interfaces have remained stable since +that time up to the latest release of 1.2.15.3 in late 2012. + +Development continues with a bump of the public version number to 3.0 +(essentially simply dropping the ``1.'' of previous releases). While some +API tweaks are planned, ABI compatibility with the prior 1.2.@i{x} +releases remains a priority. Other goals include streamlining the +build system (done), improving the SWIG generated language bindings +(in progress), improving the overall documentation (this manual, in +progress), and other updates as warranted. + +The Project is hosted by @url{https://sourceforge.net/, +SourceForge.net} at the @url{https://sourceforge.net/projects/hamlib/, +Hamlib project page} and the +@url{http://sourceforge.net/apps/mediawiki/hamlib/index.php, Hamlib +Wiki}. + +Development discussion and most user support take place on the +@url{https://sourceforge.net/p/hamlib/mailman/, hamlib-developer mailing +list}. While there are +@url{https://sourceforge.net/p/hamlib/discussion/, SourceForge.net +discussion forums}, they are rarely used and not as closely read by the +developers as the mailing list. + +For @dfn{source code management}, the project uses +@url{http://git-scm.com/, Git}, a fast, distributed content tracker. +Among its features is that every developer has the complete Hamlib +development history available locally. While a canonical Git +repository is hosted as SourceForge, its availability is not essential to +continued development, although development work flows would change +temporarily. For more information on using Git, @pxref{Working with +Git}. + +@quotation Note +The SourceForge.net Web interface to the Hamlib Git repository is +currently broken (a ticket is pending) as of late February, 2013. A +mirror exists at @url{https://github.com/N0NB/hamlib, GitHub} which +supports browsing via the Web and other Git commands. Access of the +SF.net repository by other means (SSH or Git protocols) is unaffected +by this issue. +@end quotation + +@node Applications using Hamlib +@section Applications using Hamlib +@cindex Hamlib applications +@cindex Applications, using Hamlib + +A number of application developers have taken advantage of Hamlib's +capabilities to implement radio and/or rotor control. While not +exhaustive, a list is maintained at the Hamlib Wiki, +@url{https://sourceforge.net/apps/mediawiki/hamlib/, +Applications/Screenshots}. Developers are encouraged to request their +applications be added to the gallery by way of the hamlib-developer +mailing list. + +@node Licensing implications +@section Using Hamlib with your program +@cindex Hamlib licensing +@cindex Licensing, Hamlib + +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 @acronym{LGPL} for the library portion, and the +@acronym{GPL} 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 copyleft which means that the library source code +may not be used in violation of the terms of the LGPL. + +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. 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 prohibited. + +@xref{Copying and Redistribution}. + +@node Radio cloning +@section Radios with a clone capability +@cindex Radio cloning +@cindex Cloning, radio + +Hamlib's focus is on controlling rigs 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, @url{http://chirp.danplanet.com/, CHIRP}, aims to +support rigs with such a clone capability. Please contact the CHIRP +project for support of such rigs. + +@node Pronunciation +@section Pronouncing Hamlib +@cindex Pronouncing Hamlib +@cindex Hamlib, pronouncing + +English speakers seem to have two alternate pronunciations for our +project: + +@itemize @bullet +@item Hamlib (Ham - lib, long "i", as in library.) IPA style: /'ham læb/ +@item Hamlib (Ham - lib, short "i", as in liberty.) IPA style: /'ham lɪb/ +@end itemize + +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! :-) + + +@c ------------ Chapter ------------ +@node Getting started +@chapter Getting started + +There are several ways to obtain a working installation of Hamlib. In +the following sections discuss installing from a package manager, +building from source, and installing Hamlib project supplied binaries on +Microsoft Windows@registeredsymbol{}. + +@menu +* Unix binary packages:: +* Source options:: +* Building from source:: +@end menu + +@node Unix binary packages +@section Installing binary packages on Linux and BSD +@cindex Binary packages, Linux, BSD +@cindex Linux binary packages +@cindex BSD binary packages + +The easiest way to install a released version of Hamlib on a Linux based +distribution or a BSD variant is through the provided @dfn{package +manager}. While package managers vary according to the distribution +(it's easy to lump BSD variants in this group too) their end goal is to +provide ready to use packages. Since such a wide variety of package +managers exist, it is best to recommend that the documentation for your +chosen distribution be your guide. + + +@node Source options +@section A variety of Hamlib sources + +Distribution packages are most often official Hamlib releases and in +some cases could be quite old and lacking support for newer radios or +rotors. In some cases support is improved in existing radio or +rotor back ends and bugs are fixed. Often times to get improved +support building from source will be required. Relax, it's not hard. +:-) + +Source code is available as official releases, testing snapshots, and +the bleeding edge of development. As a rule, even the bleeding edge +tarballs should configure and compile without error even though certain +implementation work may be in progress and be incomplete or have errors. + +@menu +* Source releases:: +* Source snapshots:: +@end menu + +@node Source releases +@subsection Getting released source +@cindex Getting released source +@cindex Source, getting released +@cindex Source, obtaining releases + +Official Hamlib source releases, commonly called @dfn{tarballs} can be +found on the @url{http://sourceforge.net/projects/hamlib/files/hamlib/, +SourceForge.net Hamlib files} Web page. The most recent release is +listed first. + +@node Source snapshots +@subsection Getting source snapshots +@cindex Getting source snapshots +@cindex Source, getting snapshots +@cindex Source, obtaining snapshots +@cindex Source, daily snapshots + +Testing release candidates and daily snapshots of the development +repository are available via the World Wide Web from +@url{http://n0nb.users.sourceforge.net/, Hamlib Git daily snapshots}. +These are not official releases but are provided for testing new +features and bug fixes. + + +@node Building from source +@section Building from source +@cindex Building from source +@cindex Source, building from + +Building from source will be required for various reasons including an +older version provided by your distribution, you'd like to test recent +changes to Hamlib---either a specific back end or API changes---and offer +a report to the developers, or you'd like to take part in development +and offer your contribution to the project, of you'd just like to learn +how to build a relatively comprehensive package from source. Let's get +started. + + +@c ----------------- Appendixes start here ------------------ -More than one device may be controlled at a time, however, there is -generally a limit of one device per serial port, etc. @node GNU Free Documentation License @appendix GNU Free Documentation License @@ -122,8 +445,20 @@ generally a limit of one device per serial port, etc. @include fdl.texi -@node Index -@unnumbered Index +@node Working with Git +@appendix Working with Git + +Git offers a myriad of commands and options. Fortunately, only a few +are needed for Hamlib development. + + +@node List of Figures +@unnumbered List of Figures +@listoffloats Figure + + +@node Concept Index +@unnumbered Concept Index @printindex cp