Loading...
Searching...
No Matches
README.developer

    Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
             (C) Stephane Fillod 2000-2011
             (C) The Hamlib Group 2000-2025

    Primary site for the latest development version of Hamlib is https://github.com/Hamlib/Hamlib
    Also take a look at http://sourceforge.net/projects/hamlib/
    Here you will find a mail list, and the latest releases.

    See README.md for frontend/backend outline.
    See README.betatester for background on testing Hamlib.

    The library provides functions for both radio, rotator, and amplifier control,
    and data retrieval from the radio, rotator, or amplifier.  A number of functions useful
    for calculating distance and bearing and grid square conversion are included.

    libhamlib.so -  library that provides generic API for all RIG types.
        This is what Application programmers will "see".  Will have different
        names on other platforms, e.g. libhamlib-2.dll on MS windows.  Also
        contains all radio, rotator, and amplifier "backends" (formerly in their own
        dlopen'ed libraries) provided by Hamlib.

    Backend Examples are:
    ---------------------

    1. yaesu will provide connectivity to Yaesu FT 747GX Transceiver, FT 847
       "Earth Station", etc. via a standard API.

    2. xxxx. will provide connectivity to the Wiz-bang moon-melter 101A (yikes..)

    Hamlib also enables developers to develop professional looking
    GUI's towards a standard control library API, and they would not have
    to worry about the underlying connection towards physical hardware.

    Serial (RS232) connectivity is built in as are RPC, IP (also via a socket
    utility), and USB.  Other connectivity will follow afterwards.

    General Guidelines.
    -------------------

    0. The top level directory looks like this as of 2025-05-03

    $ tree -d -I .git
    .
    .
    ├── amplifiers
    │   ├── elecraft
    │   ├── expert
    │   └── gemini
    ├── android
    ├── autom4te.cache
    ├── bindings
    │   └── csharp
    │       └── multicast
    ├── build-aux
    ├── c++
    ├── doc
    │   ├── man1
    │   ├── man7
    │   └── manuals
    ├── docker-build
    ├── extra
    │   ├── gnuradio
    │   └── kylix
    │       └── tests
    ├── include
    │   └── hamlib
    ├── lib
    ├── macros
    ├── perl
    ├── rigs
    │   ├── adat
    │   ├── alinco
    │   ├── anytone
    │   ├── aor
    │   ├── barrett
    │   ├── codan
    │   ├── commradio
    │   ├── dorji
    │   ├── drake
    │   ├── dummy
    │   ├── elad
    │   ├── flexradio
    │   ├── gomspace
    │   │   └── gs100_sim
    │   ├── icmarine
    │   ├── icom
    │   ├── jrc
    │   ├── kachina
    │   ├── kenwood
    │   ├── kit
    │   ├── lowe
    │   ├── mds
    │   ├── motorola
    │   ├── pcr
    │   ├── prm80
    │   ├── racal
    │   ├── rft
    │   ├── rs
    │   ├── skanti
    │   ├── tapr
    │   ├── tentec
    │   ├── tuner
    │   ├── uniden
    │   ├── winradio
    │   │   └── linradio
    │   ├── wj
    │   └── yaesu
    ├── rotators
    │   ├── amsat
    │   ├── androidsensor
    │   ├── apex
    │   ├── ars
    │   ├── celestron
    │   ├── cnctrk
    │   ├── easycomm
    │   ├── ether6
    │   ├── flir
    │   ├── fodtrack
    │   ├── grbltrk
    │   ├── gs232a
    │   ├── heathkit
    │   ├── indi
    │   ├── ioptron
    │   ├── m2
    │   ├── meade
    │   ├── prosistel
    │   ├── radant
    │   ├── rotorez
    │   ├── saebrtrack
    │   ├── sartek
    │   ├── satel
    │   ├── skywatcher
    │   ├── spid
    │   └── ts7400
    │       └── include
    ├── scripts
    │   └── MSVC
    ├── security
    ├── simulators
    ├── src
    └── tests
        ├── config
        ├── rigctl.test
        ├── testbcd.test
        ├── testfreq.test
        └── testloc.test

    103 directories

    1. Building

    If you just want to recompile the library, please refer to the INSTALL
    file.  This document introduces hacking the code of Hamlib.

    1.1 Obtaining sources: git clone

      git clone git://git.code.sf.net/p/hamlib/code hamlib

    The clone has to only be done the first time.

    After the initial clone, whenever you want to update your local
    repository, issue the following command in the root directory of Hamlib:

      git pull

    This will download and merge any changes from the canonical Hamlib Git
    repository (what Git calls origin by default).  This command actually
    combines two Git commands, fetch and merge into one that will first check
    for conflicting changes between your local repository and the remote
    (origin) repository and will not apply any changes if conflicts are found.

    A pull can be restricted to just a single branch if desired:

      git pull origin master

    1.1.1 Obtaining more info on Git

    Check out the Source Forge page at
    https://sourceforge.net/scm/?type=git&group_id=8305 for more information
    about how to use the Git repository of Hamlib.

    Much documentation on Git exists.  A good starting point is:

    http://git-scm.com/documentation

    From this page are links to tutorials, books (Pro Git proved useful for me),
    and references (http://gitref.org/ is another good resource).

    Another site:

    http://www-cs-students.stanford.edu/~blynn/gitmagic/

    1.1.2 Providing patches with Git

    Git provides tools to generate patches and submit them to the Hamlib developers
    via email.  Use of these tools is preferred as Git allows credit to be given
    to the author and submitter of the patches.  Please submit the patches to
    the hamlib-developer mailing list.  See section 8.3.

    1.1.3 Git and branches

    One of the most powerful features of Git is its ability to make working with
    branches easy.  It also allows the developers to "cherry pick" patches from
    the master development branch into stable release branches.  In this manner
    we can accommodate patches submitted against a stable release and merge them
    into master as well.  Such parallel development is a new feature for our
    project and there will be a learning curve!

    After cloning the repository as above, the repository is synchronized with
    the "master" branch.  This can be confirmed by 'git branch'.  A new branch
    can be created by providing a name, 'git branch n0nb_k3_level' which will
    now exist as a branch in your local repository.  This is a good way to work
    on new features as Git keeps changes to files in each branch separate.

    As you can see:

    $ git branch
      Hamlib-1.2.13
      Hamlib-1.2.13.1
    * master
      n0nb_k3

    there are a number of branches in my local repository.  Most, such as
    "Hamlib-1.2.13", exist in the canonical repository as well.  They can be
    seen by 'git branch -r' and you can switch to any of them using the 'git
    checkout BRANCH_NAME' command.

    Finally, once your changes are ready for inclusion in Hamlib, commit your
    changes to the branch you are working in, checkout the master branch, and
    use 'git merge' to synchronize your changes into the master branch.  Lastly,
    push your changes to the canonical repository (developer write access and
    checkout using the SSH protocol required.  See
    https://sourceforge.net/scm/?type=git&group_id=8305) or email them to
    hamlib-developer@lists.sourceforge.net for inclusion into Hamlib.

    1.1.4 Summary

    This is a very brief introduction to Git for Hamlib developers.  Day-to-day
    Git usage involves a handful of commands--clone, status, commit, pull,
    branch, checkout, merge, and push are probably the most common.  Other
    useful commands are log and diff to see changes (especially when color
    output is enabled in your Git configuration).  See the references above
    to learn about setting up Git to your preference.

    If you like a GUI tool several exist.  Gitk and Gitg are similar with the
    former being written with the Tk toolkit and the latter in GTK+.  Another is
    Giggle with its own interface.  All allow looking at the complete history of
    the repository and changes made to any file.

    1.2. Requirements

    Hamlib is entirely developed using GNU tools, under various Linux systems.
    Note that Hamlib is not restricted to Linux systems. We welcome anyone who
    has access to a POSIXish system to port Hamlib. Contact us for help.

    That is, if you want to take part in the development of Hamlib,
    you'll need the following tools. Make sure you have at least the required
    version or you won't even be able to build from the Git clone.

    N.B. The Debian and derivatives (Ubuntu and friends) 'build-essential'
    package will install a number of tools and minimize the number of packages
    that need to be installed manually (Debian package names are listed, other
    distributions may differ).

    * Gnu C or any C99 compliant compiler       # gcc --version
    * Gnu make  (or any modern one, BSD okay)   # make --version
    * autoconf      2.67                        # autoconf --version
    * automake      1.11                        # automake --version
    * libtool       2.2.6b+                     # libtool --version
    * Git for connection to git.code.sf.net/p/hamlib/code

    N.B. Hamlib requires libtool >= 2.2.6b in compliance with CVE-2009-3736.

    Optional, but highly recommended:
    * GNU C++                           # g++ --version
    * swig (for bindings)               # swig -version
    * perl devel                        # h2xs
    * tcl devel                         # tcltk-depends
    * python devel                      # python-config
    * lua devel
    * libxml2 devel                     # xml2-config --version
    * libgd2 devel                      # gdlib-config --version (rigmatrix)
    * libindi devel                     # INDI rotators
    * libnova devel
    * libusb-1.0 devel                  # 1.0.0 or newer
    * libreadline devel                 # ver 5.2 or newer
    * pkg-config                        # pkg-config --version (libxml and USRP)
    * zlib1g devel                      # (rigmatrix)

    N.B.:  The libusb-1.0 package is required for building most of the 'kit'
    backend.  The older version of libusb 0.1.x is no longer supported.

    N.B.:  Some systems can have several versions of the autotools installed. In
    that case, autoconf may be called "autoconf2.59", autoheader
    "autoheader2.59", and automake "automake-1.9", aclocal "aclocal-1.9" or a
    newer version.

    IMPORTANT: If autoconf or automake are installed on your system,
    make sure they are matching *at least* the version shown above.

    1.3. configure and build stage

    It is important to note that the Git repository holds no Autotools
    generated files, i.e. configure, config.guess, Makefile, etc.  Hence
    after a fresh checkout, you'll have to generate those files.

    To proceed, first edit the bootstrap script, and set appropriately the
    AUTORECONF, AUTOMAKE, and LIBTOOLIZE variables with the required versions seen
    in the previous section (most systems will be fine with the default names,
    only do this if a problem arises and please let us know).

        cd hamlib
        ./bootstrap
        ./configure [CFLAGS="-g -O0"]
        make
        make install

    Note: Depending on the value of '--prefix' passed to 'configure', superuser
    (root) privileges may be needed for 'make install'.

    If you don't want the build files cluttering the source directories, do the
    following in the same parent directory of hamlib:

        mkdir build && cd build
        ../hamlib/bootstrap
        ../hamlib/configure [CFLAGS="-g -O0"]
        make
        make install

    Note: In the examples above, passing the CFLAGS environment variable is
    optional as shown using the square brackets..

    This will keep the binary output files separate from the source tree and aid
    in development by reducing clutter in the source tree.

    Once you've run 'bootstrap', make sure you've got some recent config.guess
    and config.sub (needed to guess your system type).  Anything of at least
    year 2004 should be fine, unless you run some exotic hardware/software system
    (modern Linux distributions and Cygwin keep these up to date):

        ./config.guess --version
        ./config.sub --version

    The '--prefix' option to 'configure' is optional and not shown as it defaults
    to /usr/local.  Convention is that locally built packages be installed in
    /usr/local away from distribution installed packages.  The 'CFLAGS="-g -O0"'
    environment variable generates less optimized binaries with the '-O0'  while the
    '-g' option adds debugging info which can be changed to -ggdb to generate
    debugging info for gdb.

    Additionally, you may want to add the '--with-perl-binding' or
    '--with-python-binding' or '--with-tcl-binding' or '--with-lua-binding' if you are
    interested in SWIG binding support for those scripting languages.

    For LUA bindings if you run "lua luatest.lua" and see this error message:
    luatest.lua:44: Error in Rig::set_mode (arg 2), expected 'rmode_t' got 'string'
    This means you need to upgrade both swig and lua for 64-bit lua support
    This is known to work on swig 4.0.1 and lua 5.3.5

    NOTE: The bootstrap script has only to be run the first time after a fresh
    checkout or when a Makefile.am or other build file is modified or added.

    For a Tcl build, add this if needed:

        --with-tcl=/usr/lib/tcl8.2

    Note: C-shell users may have to run bootstrap and make through a bourne
    shell instead, or pass "SHELL=bash" as a parameter to make.

    Some basic testing is accomplished with the 'make check' target which will
    run a few predetermined tests using the 'dummy' (rig model 1) backend and
    some other Hamlib functions in the build tree. This is a basic sanity check
    and cannot test all backends.

    Likewise, a complete test of the build system is accomplished with
    'make distcheck' which exercises a complete build sequence from creating
    a distribution tarball, building, installing, uninstalling, and cleaning
    Hamlib.  All packages listed above except for Swig and Doxygen are required
    for this target as neither the bindings or old documentation are generated
    in a default build.

    NOTE!  If Hamlib has not been previously installed as a locally built
    package you will need to make sure that 'ldconfig' is configured correctly
    and run periodically after 'make install'.  Most modern distributions have
    an /etc/ld.so.conf.d/ directory where local configuration can be made.
    Later versions of Debian and derivatives have a file named 'libc.conf' in
    this directory.  The contents of libc.conf are:

    # libc default configuration
    /usr/local/lib

    If your system does not have such a file, one will need to be created and
    then 'ldconfig' will need to be run as the root user so that applications
    using the Hamlib libraries can find them.

    1.3.1 Doxygen generated reference manual

    The following packages need to be installed:
    * Doxygen
    * GNU Source-highlight

    1.3.1.1 HTML manual

    In the top level of the build directory:

        cd doc
        make doc

    will build the HTML manual.  The resulting 'doc/html' directory contains all
    of the files needed for the HTML manual.  The 'index.html' file is the entry
    point to the manual.

    1.3.1.2 PDF manual

    To generate the PDF version of the reference manual the following texlive
    packages are required (Debian package names shown):
    * texlive-latex-base
    * texlive-latex-recommended
    * texlive-latex-extra

    Set GENERATE_LATEX in 'doc/hamlib.cfg.in' to 'YES' which will enable the LaTEX
    build.  Then run:

        make doc

    as above and once the run is complete:

        cd latex
        make

    The resulting generated document in the 'latex' directory is 'refman.pdf'.

    1.4. Feedback

    The Hamlib team is very interested to hear from you, how Hamlib builds and
    works on your system, especially on non-Linux or non-PC systems. We are
    trying to make Hamlib as portable as possible. Please report problems to our
    developer mailing list, hamlib-developer@lists.sourceforge.net

    Patches are welcome too!  Just send them to the mailing list.  Git formatted
    patches are preferred.  Unified diff format (diff -u) is also welcome.
    Patches should apply to the current Git master branch or a testing branch,
    if possible.  If you're patching against an older released version of
    Hamlib, we can take those as well but please document the release the diff
    is generated against.

    So far, Hamlib has been tested successfully under the following systems:
    (if your system is not present, please report to the mailing list)

        * Debian i386 (plus derivatives--Ubuntu, etc.)
        * Debian sid mipsel
        * Raspbian armhf (Raspberry Pi Debian derivative)
        * RedHat i386
        * Linux ppc
        * Slackware i386
        * FreeBSD & NetBSD
        * Solaris 2.6
        * Mac OS X
        * MS Windows: Cygwin, Mingw

    2. How to add a new backend

        The rule is one backend per protocol family.
        Try to share code between rigs of the same family, if applicable.
        The steps in Section 3 below will need to be followed as well.
        Version numbers used are in the form YYYYMMDD.N where the .N is
        intended for multiple versions in one day....so typically would be .0

        2.1. mkdir mybackend
             Create a new subdir, of the name of the protocol backend.
             NB: the directory MUST be the same as the backend name.

        2.2. Add <mybackend> to the DIST_SUBDIRS variable in the topdir
             Makefile.am (not needed for rotators)

        2.3. Add the backend name to the BACKEND_LIST variable (add to
             ROT_BACKEND_LIST for a new rotor backend or to AMP_BACKEND_LIST for
             a new amplifier) in configure.ac.

        2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom
             of configure.ac.

        2.5. Add DEFINE_INITRIG_BACKEND(mybackend); to the end of the existing list
             in src/register.c or, for a new rotor backend, add
             DEFINE_INITROT_BACKEND(myrotbackend); to src/rot_reg.c.

        2.6. Add { RIG_MYBACKEND, RIG_BACKEND_MYBACKEND, RIG_FUNCNAM(mybackend) }, to
             the rig_backend_list structure in src/register.c or, add
             { ROT_MYROTBACKEND, ROT_BACKEND_MYROTBACKEND, ROT_FUNCNAMA(myrotbackend) },
             to the rot_backend_list structure in src/rot_reg.c.
             { AMP_MYAMPBACKEND, AMP_BACKEND_MYAMPBACKEND, AMP_FUNCNAMA(myaotbackend) },
             to the aot_backend_list structure in src/amp_reg.c.

        2.7. Add the new backend to include/hamlib/riglist.h or include/hamlib/rotlist.h or include/hamlib/amplist.h
             by selecting the next higher backend ID number.

        2.8. Create mybackend/Makefile.am, mybackend.c mybackend.h
             Use 'dummy' backend as a template.
             Here are commands for the bourne shell:

                $ automake mybackend/Makefile
                $ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status

             make in topdir to rebuild all

        2.9. Commit your work to your local repository. (developer access to
             Hamlib Git required for pushing to the canonical Hamlib repository
             (origin))  Provide patches to the mailing list:
             (Please let N0NB know if the commands below are incorrect)

             $ git status   # Show uncommitted/staged/unstaged files
             $ git add mybackend
             $ cd mybackend
             (The following command might not be necessary)
             $ git add Makefile.am mybackend.c mybackend.h

             While specifying each file individually as above allows for fine-
             grained control, git offers a wildcard shortcut to add all new files:

             $ git add .

             Be careful!  If you have other files that were created as part of the
             build process, this command will add them too unless they match a
             pattern in .gitignore.  Always check with 'git status' first!

             $ git commit -m "Initial release" Makefile.am mybackend.c mybackend.h

             Note: The '-m' switch passes a short message to the Git repository
             upon a commit.  If a longer message is desired, do not use the '-m'
             option.  The editor specified in the EDITOR or VISUAL environment
             variables will be started where a more detailed message may be
             composed.

        2.10 If you have developer access to the Git repository hosted at Source
             Forge, you can do the following:
             $ git push origin

             Your changes will now be available to others.

    3. How to add a new model to an existing backend

        3.1. make sure there's already a (unique) ID for the model to be added
             in include/hamlib/riglist.h or include/hamlib/rotlist.h or include/hamlib/amplist.h

        3.2. locate the existing backend
        3.3. Clone the most similar model in the backend
        3.4. Add the new C file to the _SOURCES variable
             of the backend's Makefile.am

        3.5. Add "extern const struct rig_caps <mymodel>_caps;" to mybackend.h
        3.6. In initrigs_<mybackend> of mybackend.c,
             add "rig_register(&<mymodel>_caps);"

        3.7. Run 'make' if you have dependencies, or the following to regenerate
             the makefile:
                $ automake mybackend/Makefile
                $ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status

                Run 'make' in topdir to rebuild all.

        3.8. Commit your work (once tests are satisfactory):
             $ git add .
             $ git commit -m "added <mymodel> to <mybackend>".

             Note:  See Note in section 2.6 above.
             Note:  The '.' character is a Git wildcard that includes all new and
                    modified files in your working tree.

                    The '-m' option may be omitted, in which case Git will start
                    your default editor for a longer commit message.  Commit
                    messages generally have the form of a short subject line, then
                    a blank line, and then as much text (broken into paragraphs as
                    needed) as needed for a good description of the commit.

                    Assuming your working tree was cloned from the SF.net repository
                    or N0NB's GitHub repository, you can now issue a pull request
                    inclusion of your new model into Hamlib.

    4. Read README.betatester to test the new backend/model.
       Report to mailing list.

    5. Basic functions: set/get_freq, set/get_mode, and set/get_vfo would be a
    good starting point for your new backend.

    6. C code examples.

    A C code snippet to connect to a FT847 and set the frequency of the main VFO
    to 439,700,000 Hz, using FM as the required mode, would look something like
    this. The error checking is removed for simplicity.

        See tests/testrig.c

    7. Where are the GUI's?

    "Build it and they will come ..."

    Seriously, I am hoping the API's will provide a solid framework for some
    cool GUI development. I would like to see some GTK or Qt apps that use the
    hamlib API's so they can be used by end users as a nice part of the Ham shack.

    Starting points (not exhaustive):
        Fldigi, CQRlog, gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog

    8. Contributing code

    8.1 License

    Contributed code to the Hamlib frontend must be released under the LGPL.
    Contributed code to Hamlib backends must follow backend current license.
    Needless to say, the LGPL is the license of choice.

    End user applications like rigctl, rotctl, ampctl and networked daemons should be
    released under the GPL, so any contributed code must follow the license.

    8.2 Coding guidelines and style

    For specific requirements for formatting the C source code, see
    README.coding_style.

    Any header files included from the hamlib/ directory should be enclosed in '<>':

    #include <hamlib/rig.h>         # Per GNU GCC documentation

    Other included header files (backend and rig specific headers) should be
    enclosed in "":

    #include "yaesu.h"

    Contributed code should always keep the source base in a compilable state,
    and not regress unless stated otherwise.

    There's no need to tag the source in a patch with your name in comments
    behind each modification, we already know the culprit from commit logs
    (also see "git blame"). :-)

    Patches should take portability issues into account.
    Keep in mind Hamlib has to run under:

        * various Linux's
        * NetBSD, FreeBSD
        * MacOS X
        * Windows: MinGW/Cygwin, and VisualC++ support for rig.h

    Hamlib should also compile with the following common compilers:

        * gcc-3.0 and gcc-3.2+  (nearly deprecated?)
        * gcc-4.x and newer
        * in shared and static
        * C++ compiler against rig.h, riglist.h, rotator.h, amplifier.h
        * clang compiler

    Portability issues to watch:

        * C99 is probably (in 2016) a reasonable target
        * little vs. big endian systems (use shifts or adhoc functions)
        * 64 bit int: avoid them in API
        * printf/scanf of 64bit int: use PRIll (cast value to int64_t) and SCNll
        * printf/scanf of freq_t: use PRIfreq and SCNfreq

    Testing:

        * The acid test for the build system is 'make distcheck' which will
          make a distribution tarball, extract, configure, and build it in a
          subdirectory, run 'make check', install it, uninstall it, and clean
          it up.  When all those tests pass, the GNU build system declares the
          package ready for distribution.  This is a good test if you have
          touched the build system files or added a backend.

    Simulators:
        * The 'simulators' directory contains programs to simulate the protocol
          of many devices.  They are built invoking "make -C simulators/ check"
          or "make check" from topdir.  While simulators are made to test Hamlib
          with rigctl and rigctld, you should be able to guess the model number
          that corresponds to a given simulator and configure an application such
          as wsjtx to use that model and the port name printed by the simulator,
          as shown in the examples below.

          To use a simulator on *nix-like systems, run its executable and take
          note of the port name:
            $ ./simulators/simft991
            name=/dev/pts/6
          then from another terminal run rigctl/rigctld using that port and a
          matching model number (see rigctl --list):
            $ ./tests/rigctl --model=1035 --rig-file=/dev/pts/6 \get_freq
            14074000

          To use a simulator on Windows, first install a virtual COM port, then
          run the simulator passing the port name as first and only argument:
            > simulators\simft991 COM1234
          then from another command prompt run rigctl/rigctld or your
          application.

          The COM port argument is currently ignored on *nix but it can be
          handled if there is a need to test a low level issue with RS-232
          and/or USB communication, if your machine has the needed hardware.

    8.2.1 Use of rig_debug() function

    Hamlib provides a debugging aid in the form of the rig_debug() function,  It
    is essentially a wrapper around printf() and takes many of the same flags
    and conversion specifiers as the C library's various printf() functions.  It
    adds an additional parameter for specifying the desired debug level for the
    output string.  Six levels of debugging are defined in include/hamlib/rig.h
    and they are:

      NONE          No bug reporting
      BUG           Serious bug
      ERR           Error case (e.g. protocol, memory allocation)
      WARN          Warning
      VERBOSE       Verbose
      TRACE         Tracing

    They correspond to the use of the -v switch (from no -v switch to -vvvvv)
    to rigctl's command line.  Hamlib applications can also set the debug level
    via the Hamlib API.  From an application's perspective, setting a specific
    level includes all messages at that level and all at any lower level.

    In the library, passing RIG_DEBUG_ERR to rig_debug() limits display of that
    message to a level setting of ERR or any higher level.  In this case if the
    application sets the message level to RIG_DEBUG_INFO, the message will not
    be seen.  Use of a given level can show the value of a critical variable
    without the need of a TRACE level message where it can get lost in the
    stream of output produced by low-level Hamlib functions.

    Here are my (N0NB's) suggested use of rig_debug() levels in backends.

    * Many backend functions should have an initial call to rig_debug() as follows:

        rig_debug(RIG_DEBUG_VERBOSE, "%s() entered\n", __func__);

      The use of RIG_DEBUG_VERBOSE allows tracking the chain of function calls
      through the backend while still keeping rigctl's output mostly
      uncluttered by use of the -vvvv switch.

    * Developers will want to call rig_debug() to display values of critical
      variable(s) in a backend function.  For this RIG_DEBUG_VERBOSE
      (rigctl -vvvv) should be a good choice as the output won't be lost in the
      stream of RIG_DEBUG_TRACE (rigctl -vvvvv) level output by various
      low-level Hamlib functions.  It will also match the display of the values
      of critical variable(s) with the function calls as above.

    * Use RIG_DEBUG_TRACE when it makes sense to see the variable(s) in the
      context of a lot of low-level debugging output (rigctl -vvvvv).

    * Lower levels (BUG, ERR, and WARN) should be used where it makes sense that
     information be printed when the user selects less verbosity.  Use sparingly.

    Many backends do not conform to this suggestion at the moment.  The use of
    the RIG_DEBUG_LEVEL values has been somewhat haphazard (at least by this
    scribe) so fixing these when working in a given backend is encouraged.

    If an application sets the debugging level to RIG_DEBUG_NONE, then
    rig_debug() functions will produce no output.  Therefore rig_debug() cannot
    be counted on to output a message in all runtime cases.

    The debugging levels may be an area for consideration in Hamlib 3.

    8.3 Submitting patches

    Git provides tools to generate patches and submit them to the Hamlib
    developers via email.  Use of these tools is preferred as Git allows credit
    to be given to the author and submitter of the patches.  Alternately,
    patches can be submitted in unified format (diff -u), against the Git master
    branch or a given release (please note well which one!). Both formats make
    patches easily readable. The patches are to be sent to the hamlib-developer
    mailing list (hamlib-developer@lists.sourceforge.net). If the file is too
    big, you can send it as a compressed attachment.

    8.3.1 Changelog

    A ChangeLog file is no longer manually maintained.  At some point it may be
    automatically generated from the Git commit log for source tarballs.

    Simply summarize your changes when the files are committed to Git or, if
    providing patches to the mailing list, provide a summary so the uploader can
    include it in the commit message which will show in the commit log (Git
    formatted emails will include this already).

    8.4 Git commit access

    Generally, volunteers can get commit access to the SourceForge Hamlib Git
    repository upon asking one of the project administrators.  Sometimes we'll
    ask you!

    However, before your start committing, the project admins would like first
    to have a look at your "style", just to make sure you grok the Hamlib
    approach (c.f. previous section on submitting a patch). Then you'll be able
    to commit by yourself to the backend you chose to maintain. Please follow
    the rules hereunder:

        * Always keep the Git repository (all branches) in a compilable state.
        * Follow the coding guidelines
        * Touching the frontend (files in src/ and include/hamlib) always
          requires discussion beforehand on the hamlib-developer list.
        * Announce on the hamlib-developer list if you're about to do serious
          maintenance work

    Thanks for contributing and have fun!

    Stephane Fillod f8cfe and The Hamlib Group