kopia lustrzana https://github.com/Hamlib/Hamlib
New project information manual pages
Project information manual pages (section 7) have been created from the Texinfo manual that provide a set of general information pages about Hamlib.Hamlib-3.3
rodzic
e3f1e4adcf
commit
d984a58113
|
@ -2,7 +2,8 @@ EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html \
|
||||||
Hamlib_design.eps Hamlib_design.png
|
Hamlib_design.eps Hamlib_design.png
|
||||||
|
|
||||||
dist_man_MANS = man1/rigctl.1 man1/rigctld.1 man1/rigmem.1 man1/rigsmtr.1 \
|
dist_man_MANS = man1/rigctl.1 man1/rigctld.1 man1/rigmem.1 man1/rigsmtr.1 \
|
||||||
man1/rigswr.1 man1/rotctl.1 man1/rotctld.1
|
man1/rigswr.1 man1/rotctl.1 man1/rotctld.1 man7/hamlib.7 \
|
||||||
|
man7/hamlib-primer.7 man7/hamlib-utilities.7
|
||||||
|
|
||||||
htmldir = $(docdir)/html
|
htmldir = $(docdir)/html
|
||||||
dist_html_DATA = Hamlib_design.png hamlib.html
|
dist_html_DATA = Hamlib_design.png hamlib.html
|
||||||
|
|
|
@ -0,0 +1,838 @@
|
||||||
|
.\" Hey, EMACS: -*- nroff -*-
|
||||||
|
.\"
|
||||||
|
.\" For layout and available macros, see man(7), man-pages(7), groff_man(7)
|
||||||
|
.\" Please adjust the date whenever revising the manpage.
|
||||||
|
.\"
|
||||||
|
.\" Please keep this file in sync with doc/getting_started.texi
|
||||||
|
.\"
|
||||||
|
.TH HAMLIB-PRIMER "7" "2018-05-27" "Hamlib" "Hamlib Information Manual"
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH NAME
|
||||||
|
.
|
||||||
|
hamlib-primer \- compiling and using the radio and rotator control library
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.
|
||||||
|
There are several ways to obtain a working installation of Hamlib.
|
||||||
|
.
|
||||||
|
The following sections discuss installing from a package manager, building
|
||||||
|
from source, and installing Hamlib project supplied binaries on Microsoft
|
||||||
|
Windows\*R.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Installing binary packages on Linux and BSD
|
||||||
|
.
|
||||||
|
The easiest way to install a released version of Hamlib on a Linux based
|
||||||
|
distribution or a BSD variant is through the provided
|
||||||
|
.IR "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
|
||||||
|
software 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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS 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 rotators.
|
||||||
|
.
|
||||||
|
In some cases support is improved in existing radio or rotator back ends and
|
||||||
|
bugs are fixed in newer releases.
|
||||||
|
.
|
||||||
|
Often times to get the improved support/bug fixes, building from source will
|
||||||
|
be required.
|
||||||
|
.
|
||||||
|
Relax, it's not hard. :-)
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Source code is available as official releases, testing snapshots, daily
|
||||||
|
development snapshots, and the bleeding edge of development directly from the
|
||||||
|
.UR https://github.com/Hamlib/Hamlib
|
||||||
|
Git repository
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
As a rule, even the bleeding edge tarballs should configure and compile
|
||||||
|
without error even though certain implementation work may be in progress and
|
||||||
|
may be incomplete or have errors.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Getting released source
|
||||||
|
.
|
||||||
|
.
|
||||||
|
Official Hamlib source releases, commonly called
|
||||||
|
.I tarballs
|
||||||
|
can be
|
||||||
|
found on the
|
||||||
|
.UR http://sourceforge.net/projects/hamlib/files/hamlib/
|
||||||
|
SourceForge.net Hamlib files
|
||||||
|
.UE
|
||||||
|
Web page.
|
||||||
|
.
|
||||||
|
As a convenience, release archives are also mirrored at the
|
||||||
|
.UR https://github.com/Hamlib/Hamlib/releases
|
||||||
|
GitHub Hamlib releases
|
||||||
|
.UE
|
||||||
|
page.
|
||||||
|
.
|
||||||
|
The most recent release is listed first.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Getting source snapshots
|
||||||
|
.
|
||||||
|
Testing release candidates (RCs) are posted during the period (often a few
|
||||||
|
weeks) before a planned release.
|
||||||
|
.
|
||||||
|
Beginning with the 3.2 release, RCs are hosted by the
|
||||||
|
.UR https://github.com/Hamlib/Hamlib/releases
|
||||||
|
GitHub release archive
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
RCs are identifed by having a
|
||||||
|
.I ~rc
|
||||||
|
suffix.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Daily snapshots of the development repository are available via the World Wide
|
||||||
|
Web from
|
||||||
|
.UR http://n0nb.users.sourceforge.net/
|
||||||
|
Hamlib Git daily snapshots
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
These are not official releases but are provided for testing new features and
|
||||||
|
bug fixes.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The daily development snapshot is made and posted each day by around 1030 UTC.
|
||||||
|
.
|
||||||
|
Daily snapshots
|
||||||
|
.I should
|
||||||
|
compile but sometimes a bug creeps in that prevents compilation.
|
||||||
|
.
|
||||||
|
If that should happen, please report it to the
|
||||||
|
.MT hamlib-developer@@lists.sourceforge.net
|
||||||
|
hamlib-developer mailing list
|
||||||
|
.ME .
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Git repository
|
||||||
|
.
|
||||||
|
The source repository can be
|
||||||
|
.I cloned
|
||||||
|
which copies the repository to your computer including its entire history,
|
||||||
|
branches, and release tag information.
|
||||||
|
.
|
||||||
|
In other words, once the
|
||||||
|
.BR git "(1) " clone
|
||||||
|
command is finished a complete copy of the Hamlib development will be on your
|
||||||
|
computer.
|
||||||
|
.
|
||||||
|
You can do quite a lot with this as nothing is hidden from view since the
|
||||||
|
entire history of Hamlib is right there all the way from the very first commit
|
||||||
|
to the present.
|
||||||
|
.
|
||||||
|
None of the meta-data is hidden away on some central server.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
To clone the repository use the following command:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
git clone https://git.code.sf.net/p/hamlib/code hamlib
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
or:
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
git clone https://github.com/Hamlib/Hamlib.git
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.
|
||||||
|
Odds are that you will want to run the above command in a sub directory of
|
||||||
|
your home directory.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.I hamlib
|
||||||
|
directory will be created by Git and the
|
||||||
|
.I master
|
||||||
|
branch will be checked out for you as the
|
||||||
|
.IR "working copy" .
|
||||||
|
.
|
||||||
|
The master branch is one of several branches used in Hamlib development.
|
||||||
|
.
|
||||||
|
It is the main branch of new features and bug fixes.
|
||||||
|
.
|
||||||
|
The working copy will be the latest revision of every file at the time of the
|
||||||
|
clone.
|
||||||
|
.
|
||||||
|
Later updates from the developers will require using another Git command to
|
||||||
|
update your local repository.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Building from source
|
||||||
|
.
|
||||||
|
Building from source will be required for various reasons.
|
||||||
|
.
|
||||||
|
Perhaps only an older release is provided by your distribution, or you would like
|
||||||
|
to test recent changes to Hamlib\(emeither a specific back end or API
|
||||||
|
changes\(emand offer a report to the developers, or you would like to take part in
|
||||||
|
development and offer your contribution to the project, or you would just like to
|
||||||
|
learn how to build a relatively comprehensive package from source.
|
||||||
|
.
|
||||||
|
Any is a good reason to build from the source code archive.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Before going further, this manual assumes familiarity with working from the
|
||||||
|
command prompt in a Linux/BSD/Unix like system's
|
||||||
|
.I shell
|
||||||
|
environment, either in a
|
||||||
|
.I virtual console
|
||||||
|
(a text only screen with no graphics) or in a
|
||||||
|
.I terminal
|
||||||
|
in a desktop environment
|
||||||
|
.RB ( xterm ,
|
||||||
|
.BR rxvt ,
|
||||||
|
.BR konsole ,
|
||||||
|
.BR gnome\-terminal ,
|
||||||
|
.BR xfce4\-terminal ,
|
||||||
|
.BR terminal ,
|
||||||
|
etc.).
|
||||||
|
.
|
||||||
|
If this is new to you, take some time and read up on using the shell.
|
||||||
|
.
|
||||||
|
A good tutorial can be found at
|
||||||
|
.UR http://linuxcommand.org/
|
||||||
|
LinuxCommand.org
|
||||||
|
.UE
|
||||||
|
which also offers an in-depth book that can be purchased or downloaded for no
|
||||||
|
cost (the Hamlib project is not associated with nor has any interest in the
|
||||||
|
sale of this book, it just looks like a very good effort on the part of its
|
||||||
|
author).
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Let's get started.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Compiling source tarballs
|
||||||
|
.
|
||||||
|
Before proceeding, it is essential to read the information in the files,
|
||||||
|
.IR README ,
|
||||||
|
.IR INSTALL ,
|
||||||
|
and
|
||||||
|
.I README.betatester
|
||||||
|
supplied in the Hamlib
|
||||||
|
.I top-level
|
||||||
|
directory which will be named
|
||||||
|
something like
|
||||||
|
.I hamlib-3.3~git
|
||||||
|
where the latter part is the release version.
|
||||||
|
.
|
||||||
|
In this case the
|
||||||
|
.I 3.3~git
|
||||||
|
indicates this is a development snapshot of the Git master branch.
|
||||||
|
.
|
||||||
|
These files provide detailed information for compiling Hamlib and will vary
|
||||||
|
some from release to release.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Compiling from a source tarball whether it is an official release or a testing
|
||||||
|
or daily development snapshot follows the same set of commands, known as the
|
||||||
|
.I three step
|
||||||
|
which are each run from the top-level directory:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
\&./configure
|
||||||
|
make
|
||||||
|
sudo make install
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.SS configure
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.IB ./ configure
|
||||||
|
command examines your system and checks it for any packages that are required
|
||||||
|
or good to have options for compiling Hamlib.
|
||||||
|
.
|
||||||
|
The leading
|
||||||
|
.I ./
|
||||||
|
tells the shell to only run the
|
||||||
|
.B configure
|
||||||
|
command found in the current directory.
|
||||||
|
.
|
||||||
|
It is always possible that a
|
||||||
|
.B configure
|
||||||
|
command could be lurking elsewhere and we don't want to run that!
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Run:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
\&./configure
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
from the top-level directory.
|
||||||
|
.
|
||||||
|
.IP
|
||||||
|
.BR Note :
|
||||||
|
Some distributions are configured so commands can only be run from directories
|
||||||
|
listed in the
|
||||||
|
.B PATH
|
||||||
|
environment variable.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.I ./
|
||||||
|
is necessary or the
|
||||||
|
.B configure
|
||||||
|
command will not be run as the
|
||||||
|
.I current directory
|
||||||
|
(defined as
|
||||||
|
.IR . )
|
||||||
|
is not in the
|
||||||
|
.BR PATH .
|
||||||
|
.
|
||||||
|
This is considered a default security feature so that only programs provided
|
||||||
|
by the distribution are run.
|
||||||
|
.
|
||||||
|
.B PATH
|
||||||
|
can be modified for your own session, but that is a topic for the
|
||||||
|
LinuxCommand.org reference above.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Of course, things are usually complicated a bit by options and Hamlib is no
|
||||||
|
exception.
|
||||||
|
.
|
||||||
|
The good news is that the defaults, i.e., no options, work well in most
|
||||||
|
situations.
|
||||||
|
.
|
||||||
|
Options are needed to enable the compilation of certain portions of Hamlib
|
||||||
|
such as the language bindings.
|
||||||
|
.
|
||||||
|
Optional features usually require that more development tools are installed.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.I INSTALL
|
||||||
|
and
|
||||||
|
.I README.betatester
|
||||||
|
files in the Hamlib top-level directory will have details on the options
|
||||||
|
available for that release.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
A useful option is
|
||||||
|
.B \-\-prefix
|
||||||
|
which tells
|
||||||
|
.B configure
|
||||||
|
where in the file system hierarchy Hamlib should be installed.
|
||||||
|
.
|
||||||
|
If it is not given, Hamlib will be installed in the
|
||||||
|
.I /usr/local
|
||||||
|
file system hierarchy.
|
||||||
|
.
|
||||||
|
Perhaps you want to install to your home directory instead:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
\&./configure \-\-prefix=$HOME/local
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.IP
|
||||||
|
.BR Note :
|
||||||
|
For practice you may wish to start out using the
|
||||||
|
.BR \-\-prefix = \fI$HOME/local\fP
|
||||||
|
option to install the Hamlib files into your home directory and avoid
|
||||||
|
overwriting any version of Hamlib installed into the system directories.
|
||||||
|
.
|
||||||
|
The code examples in the remainder of this manual will assume Hamlib has been
|
||||||
|
installed to
|
||||||
|
.IR $HOME/local .
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
All of the files will be installed in the
|
||||||
|
.I local
|
||||||
|
directory of your home directory.
|
||||||
|
.
|
||||||
|
.I local
|
||||||
|
will be created if it does not exist during installation as will several other
|
||||||
|
directories in it.
|
||||||
|
.
|
||||||
|
Installing in your home directory means that
|
||||||
|
.IR root ,
|
||||||
|
or superuser (administrator) privileges are not required when running
|
||||||
|
.BR "make install" .
|
||||||
|
.
|
||||||
|
On the other hand, some extra work will need to be done so other programs can
|
||||||
|
use the library.
|
||||||
|
.
|
||||||
|
.\" (TODO: describe library hackery in an appendix).
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Another useful option is
|
||||||
|
.B \-\-help
|
||||||
|
which will give a few screens full of options for
|
||||||
|
.BR configure .
|
||||||
|
.
|
||||||
|
If in a desktop environment the scroll bar can be used to scroll back up
|
||||||
|
through the output.
|
||||||
|
.
|
||||||
|
In either a terminal or a virtual console Linux supports the Shift\-PageUp key
|
||||||
|
combination to scroll back up.
|
||||||
|
.
|
||||||
|
Conversely, Shift\-PageDown can be used to scroll down toward the end of the
|
||||||
|
output and the shell prompt (Shift\-UpArrow/Shift\-DownArrow may also work to
|
||||||
|
scroll one line at a time).
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
After a fair amount of time, depending on your computer, and a lot of screen
|
||||||
|
output,
|
||||||
|
.B configure
|
||||||
|
will finish its job.
|
||||||
|
.
|
||||||
|
So long as the few lines previous to the shell prompt don't say \(lqerror\(rq
|
||||||
|
or some such failure message Hamlib is ready to be compiled.
|
||||||
|
.
|
||||||
|
If there is an error and all of the required packages listed in
|
||||||
|
.I README.betatester
|
||||||
|
have been installed, please ask for help on the
|
||||||
|
.MT hamlib\-developer@@lists.sourceforge.net
|
||||||
|
hamlib-developer mailing list
|
||||||
|
.ME .
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS make
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.BR make (1)
|
||||||
|
command is responsible for running the
|
||||||
|
.I compiler
|
||||||
|
which reads the source files and from the instructions it finds in them writes
|
||||||
|
.I object
|
||||||
|
files which are the binary instructions the CPU of a computer can execute.
|
||||||
|
.
|
||||||
|
.B make
|
||||||
|
then calls the
|
||||||
|
.I linker
|
||||||
|
which puts the object files together in the correct order to create the Hamlib
|
||||||
|
library files and its executable programs.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Run:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
make
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
from the top-level directory.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Any error that causes
|
||||||
|
.B make
|
||||||
|
to stop early is cause for a question to the
|
||||||
|
.MT hamlib\-developer@@lists.sourceforge.net
|
||||||
|
hamlib-developer mailing list
|
||||||
|
.ME .
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
In general
|
||||||
|
.B make
|
||||||
|
will take longer than
|
||||||
|
.B configure
|
||||||
|
to complete its run.
|
||||||
|
.
|
||||||
|
As it is a system command, and therefore found in the
|
||||||
|
.BR PATH ,
|
||||||
|
prefixing
|
||||||
|
.B make
|
||||||
|
with
|
||||||
|
.I ./
|
||||||
|
will cause a \(lqcommand not found\(rq error from the shell.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS make install
|
||||||
|
.
|
||||||
|
Assuming that you have not set the installation prefix to your home directory,
|
||||||
|
root (administrator) privileges will be required to install Hamlib to the
|
||||||
|
system directories.
|
||||||
|
.
|
||||||
|
Two popular methods exist for gaining root privileges,
|
||||||
|
.BR su (1)
|
||||||
|
and
|
||||||
|
.BR sudo (8).
|
||||||
|
.
|
||||||
|
.B sudo
|
||||||
|
is probably the most popular these days, particularly when using the
|
||||||
|
.UR http://www.ubuntu.com
|
||||||
|
Ubuntu
|
||||||
|
.UE
|
||||||
|
family of distributions.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Run:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
sudo make install
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
as root from the top-level directory.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Running
|
||||||
|
.B make install
|
||||||
|
will call the installer to put all of the newly compiled files and other files
|
||||||
|
(such as this document) in predetermined places set by the
|
||||||
|
.B \-\-prefix
|
||||||
|
option to
|
||||||
|
.B configure
|
||||||
|
in the directory hierarchy (yes, this is by design and
|
||||||
|
.B make
|
||||||
|
is not just flinging files any old place!).
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
A lot of screen output will be generated.
|
||||||
|
.
|
||||||
|
Any errors will probably be rather early in the process and will likely be
|
||||||
|
related to your
|
||||||
|
.I username
|
||||||
|
not having write permissions in the system directory structure.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS ldconfig
|
||||||
|
.
|
||||||
|
Once the installation is complete one more step is required if Hamlib has
|
||||||
|
never been installed from a local build before.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.B ldconfig
|
||||||
|
command tells the system library loader where to find the newly installed
|
||||||
|
Hamlib libraries.
|
||||||
|
.
|
||||||
|
It too will need to be run with root privileges:
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Run:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
sudo ldconfig
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
as root from any directory.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.BR Note :
|
||||||
|
Subsequent installations of Hamlib will not need to have
|
||||||
|
.B ldconfig
|
||||||
|
run after each installation if a newer version of Hamlib was not installed,
|
||||||
|
i.e. when recompiling the same version during development.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
On some distributions a bit of configuration will be needed before
|
||||||
|
.B ldconfig
|
||||||
|
will add locally compiled software to its database.
|
||||||
|
.
|
||||||
|
Please consult your distribution's documentation.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Bootstrapping from a \(aqgit clone\(aq
|
||||||
|
.
|
||||||
|
Choosing to build from from a
|
||||||
|
.B git clone
|
||||||
|
requires a few more development tools (notice a theme here?) as detailed in
|
||||||
|
.IR README.developer .
|
||||||
|
.
|
||||||
|
The most critical will be the GNU Autotools
|
||||||
|
.RB ( autoconf ,
|
||||||
|
.BR automake ,
|
||||||
|
.BR libtool ,
|
||||||
|
and more) from which the build system consisting of
|
||||||
|
.BR configure ,
|
||||||
|
the various
|
||||||
|
.IR Makefile.in s
|
||||||
|
throughout the directory structure, and the final
|
||||||
|
.IR Makefile s
|
||||||
|
are generated.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
In the top-level directory is the
|
||||||
|
.B bootstrap
|
||||||
|
script from which the build system is
|
||||||
|
.IR bootsrapped\(emthe
|
||||||
|
process of generating the Hamlib build system from
|
||||||
|
.I configure.ac
|
||||||
|
and the various
|
||||||
|
.IR Makefile.am s.
|
||||||
|
.
|
||||||
|
At its completion the
|
||||||
|
.B configure
|
||||||
|
script will be present to configure the build system.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Next
|
||||||
|
.B configure
|
||||||
|
is run with any needed build options
|
||||||
|
.RB ( "configure \-\-help"
|
||||||
|
is useful) to enable certain features or provide paths for locating needed
|
||||||
|
build dependencies, etc.
|
||||||
|
.
|
||||||
|
Environment variables intended for the preprocessor and/or compiler may also
|
||||||
|
be set on the
|
||||||
|
.B configure
|
||||||
|
command line.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
After the configuration is complete, the build may proceed with the
|
||||||
|
.B make
|
||||||
|
step as for the source tarballs above.
|
||||||
|
.
|
||||||
|
Or
|
||||||
|
.B configure \-\-help
|
||||||
|
may be run, and
|
||||||
|
.B configure
|
||||||
|
run again with specific options in which case the
|
||||||
|
.IR Makefile s
|
||||||
|
will be regenerated and the build can proceed with the new configuration.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Other make targets
|
||||||
|
.
|
||||||
|
Besides
|
||||||
|
.BR "make install" ,
|
||||||
|
other
|
||||||
|
.I targets
|
||||||
|
exist when running
|
||||||
|
.BR make .
|
||||||
|
.
|
||||||
|
Running
|
||||||
|
.B make clean
|
||||||
|
from the top-level directory removes all of the generated object and
|
||||||
|
executable files generated by running
|
||||||
|
.B make
|
||||||
|
freeing up considerable disk space.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.BR Note :
|
||||||
|
During development of individual source files, it is not necessary to
|
||||||
|
run
|
||||||
|
.B make clean
|
||||||
|
each time before
|
||||||
|
.BR make .
|
||||||
|
.
|
||||||
|
Simply run
|
||||||
|
.B make
|
||||||
|
and only the modified file(s) and any objects that depend on them will be
|
||||||
|
recompiled.
|
||||||
|
.
|
||||||
|
This speeds up development time considerably.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
To remove even the generated
|
||||||
|
.IR Makefile s,
|
||||||
|
run
|
||||||
|
.B make distclean
|
||||||
|
from the top-level directory.
|
||||||
|
.
|
||||||
|
After this target is run,
|
||||||
|
.B configure
|
||||||
|
will need to be run again to regenerate the
|
||||||
|
.IR Makefile s.
|
||||||
|
.
|
||||||
|
This command may not be as useful as the
|
||||||
|
.IR Makefile s
|
||||||
|
do not take up much space, however it can be useful for rebuilding the
|
||||||
|
.IR Makefile s
|
||||||
|
when modifying a
|
||||||
|
.I Makefile.am
|
||||||
|
or
|
||||||
|
.I confgure.ac
|
||||||
|
during build system development.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Parallel build trees
|
||||||
|
.
|
||||||
|
One feature of the GNU build system used by Hamlib is that the object files
|
||||||
|
can be kept in a directory structure separate from the source files.
|
||||||
|
.
|
||||||
|
While this has no effect on the
|
||||||
|
.B make
|
||||||
|
targets described above, it does help the developer find files in the source
|
||||||
|
tree!
|
||||||
|
.
|
||||||
|
One such way of using parallel builds is described in
|
||||||
|
.IR README.developer .
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Parallel builds can be very useful as one build directory can be configured
|
||||||
|
for a release and another build directory can be configured for debugging with
|
||||||
|
different options passed to
|
||||||
|
.B configure
|
||||||
|
from each directory.
|
||||||
|
.
|
||||||
|
The generated
|
||||||
|
.IR Makefile s
|
||||||
|
are unique to each build directory and will not interfere with each other.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Adding debugging symbols
|
||||||
|
.
|
||||||
|
When additional debugging symbols are needed with, for example, the GNU
|
||||||
|
Debugger,
|
||||||
|
.BR gdb ,
|
||||||
|
the needed compiler and linker options are passed as environment variables.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Run:
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
\&../hamlib/configure CFLAGS="-ggdb3 -O0" CXXFLAGS="-ggdb3 -O0"
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
from a sibling build directory intended for a debugging build.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.B \-ggdb3
|
||||||
|
option tells the C compiler, in this case the GNU C Compiler,
|
||||||
|
.BR gcc ,
|
||||||
|
to add special symbols useful for GDB, the GNU debugger.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.B -O0
|
||||||
|
option tells
|
||||||
|
.B gcc
|
||||||
|
to turn off all optimizations which will make it easier to follow some
|
||||||
|
variables that might otherwise be optimized away.
|
||||||
|
.
|
||||||
|
.B CFLAGS
|
||||||
|
and
|
||||||
|
.B CXXFLAGS
|
||||||
|
may be set independently for each compiler.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.BR Note :
|
||||||
|
There are a number compiler options available for controlling debugging
|
||||||
|
symbols and setting optimization levels.
|
||||||
|
.
|
||||||
|
Please consult the compiler's manual for all the details.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Compiling for Microsoft Windows
|
||||||
|
.
|
||||||
|
Currently compiling is done on a Debian 8 (Jessie) virtual machine using
|
||||||
|
.UR http://www.mingw.org
|
||||||
|
MinGW
|
||||||
|
.UE .
|
||||||
|
.I README.build-win32
|
||||||
|
in the
|
||||||
|
.I scripts
|
||||||
|
directory has details on how this is accomplished.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Pre-compiled binaries for Microsoft Windows
|
||||||
|
.
|
||||||
|
Pre-compiled binaries for Microsoft Windows 32 and 64 bit architectures
|
||||||
|
(Windows NT and newer) are available for both official releases and daily
|
||||||
|
development snapshots.
|
||||||
|
.
|
||||||
|
Official releases are available through the
|
||||||
|
.UR http://sourceforge.net/projects/hamlib/files/hamlib/
|
||||||
|
SourceForge.net file download service
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
As an alternative, official releases are also available though the
|
||||||
|
.UR https://github.com/Hamlib/Hamlib/releases
|
||||||
|
Hamlib archive at GitHub
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
Daily development snapshots are available from the
|
||||||
|
.UR http://n0nb.users.sourceforge.net/
|
||||||
|
daily snapshots page
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Beginning with the Hamlib 1.2.15.3 release a self-extracting installer is
|
||||||
|
available.
|
||||||
|
.
|
||||||
|
Among its features are selecting which portions of Hamlib are installed.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.B PATH
|
||||||
|
environment variable will need to be set manually per the included
|
||||||
|
.I README.w32-bin
|
||||||
|
or
|
||||||
|
.I README.w64-bin
|
||||||
|
file.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Daily development snapshots feature both a .ZIP archive and the self
|
||||||
|
extracting installer.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Bug reports and questions about these archives should be sent to the
|
||||||
|
.MT hamlib-developer@@lists.sourceforge.net
|
||||||
|
hamlib-developer mailing list
|
||||||
|
.ME .
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH COPYING
|
||||||
|
.
|
||||||
|
This file is part of Hamlib, a project to develop a library that simplifies
|
||||||
|
radio and rotator control functions for developers of software primarily of
|
||||||
|
interest to radio amateurs and those interested in radio communications.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Copyright \(co 2001-2018 Hamlib Group (various contributors)
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH SEE ALSO
|
||||||
|
.
|
||||||
|
.BR git (1),
|
||||||
|
.BR hamlib (7),
|
||||||
|
.BR ldconfig (8),
|
||||||
|
.BR make (1),
|
||||||
|
.BR su (1),
|
||||||
|
.BR sudo (8)
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH COLOPHON
|
||||||
|
.
|
||||||
|
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot
|
||||||
|
archives:
|
||||||
|
.IP
|
||||||
|
.UR http://www.hamlib.org
|
||||||
|
hamlib.org
|
||||||
|
.UE .
|
|
@ -0,0 +1,835 @@
|
||||||
|
.\" Hey, EMACS: -*- nroff -*-
|
||||||
|
.\"
|
||||||
|
.\" For layout and available macros, see man(7), man-pages(7), groff_man(7)
|
||||||
|
.\" Please adjust the date whenever revising the manpage.
|
||||||
|
.\"
|
||||||
|
.\" Please keep this file in sync with doc/utility-programs.texi
|
||||||
|
.\"
|
||||||
|
.TH HAMLIB-UTILITIES "7" "2018-05-27" "Hamlib" "Hamlib Information Manual"
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH NAME
|
||||||
|
.
|
||||||
|
hamlib-utilties \- radio and rotator control utilities of Hamlib
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.
|
||||||
|
Included with the Hamlib distribution are several utility programs.
|
||||||
|
.
|
||||||
|
Besides providing a way for developers to test new code and bug fixes, the
|
||||||
|
programs also offer a reference implementation for interfacing to the Hamlib
|
||||||
|
library functions both through the
|
||||||
|
.B C
|
||||||
|
.SM API
|
||||||
|
(Application Programming Interface) and offering a network accessible
|
||||||
|
.SM API.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
This page summarizes the two test programs,
|
||||||
|
.BR rigctl (1)
|
||||||
|
for testing radio back ends and
|
||||||
|
.BR rotctl (1)
|
||||||
|
for testing rotator back ends and the two network daemons,
|
||||||
|
.BR rigctld (1)
|
||||||
|
and
|
||||||
|
.BR rotcltd (1)
|
||||||
|
for radio and rotator access via network sockets.
|
||||||
|
.
|
||||||
|
Also included are three demonstation utilities,
|
||||||
|
.BR rigmem (1),
|
||||||
|
.BR rigsmtr (1),
|
||||||
|
and
|
||||||
|
.BR rigswr (1)
|
||||||
|
which provide functional examples of how Hamlib may be used to accomplish
|
||||||
|
various tasks.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rigctl
|
||||||
|
.
|
||||||
|
.BR rigctl (1)
|
||||||
|
is the most frequently used Hamlib utility.
|
||||||
|
.
|
||||||
|
As the other
|
||||||
|
.I ctl
|
||||||
|
utilities share many of the same characteristics, much of the introductory
|
||||||
|
information presented in this section is applicable to the other utility
|
||||||
|
programs.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rigctl
|
||||||
|
.
|
||||||
|
Most likely the first of the Hamlib utility programs that is used is
|
||||||
|
.BR rigctl (1).
|
||||||
|
.
|
||||||
|
rigctl is a character based interactive program and a command line program
|
||||||
|
able to set or query a radio's value with a single command.
|
||||||
|
.
|
||||||
|
rigctl is invoked from a shell command prompt with various options and
|
||||||
|
additional commands.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
In its most simple use as a
|
||||||
|
.I "command line"
|
||||||
|
program, rigctl is used to set frequency and mode by typing commands after any
|
||||||
|
rigctl options:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rigctl F 14205000
|
||||||
|
.br
|
||||||
|
rigctl M USB 2400
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
and then query those values:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rigctl f
|
||||||
|
.br
|
||||||
|
rigctl m
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Entering
|
||||||
|
.I "interactive mode"
|
||||||
|
is a simple matter of not placing any commands after any rigctl options:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rigctl
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Entering interactive mode allows successive commands to be entered without
|
||||||
|
exiting rigctl.
|
||||||
|
.
|
||||||
|
Recent additions to rigctl allow command editing and history recall through
|
||||||
|
use of the
|
||||||
|
.UR https://tiswww.case.edu/php/chet/readline/rltop.html
|
||||||
|
Readline
|
||||||
|
.UE
|
||||||
|
library.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Interactive mode is indicated by the spartan prompt:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
Rig command:
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Commands are given at the prompt and follow the general rule that upper case
|
||||||
|
letters set a value and lower case letters query a value:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
Rig command: M
|
||||||
|
.br
|
||||||
|
Mode: USB
|
||||||
|
.br
|
||||||
|
Passband: 2500
|
||||||
|
.sp
|
||||||
|
Rig command: m
|
||||||
|
.br
|
||||||
|
Mode: USB
|
||||||
|
.br
|
||||||
|
Passband: 2500
|
||||||
|
.sp
|
||||||
|
Rig command:
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
An additional prompt is printed when more information is required by the
|
||||||
|
command.
|
||||||
|
.
|
||||||
|
For \f(CWM\fP above, rigctl prompted for the \f(CWMode\fP and \f(CWPassband\fP
|
||||||
|
values.
|
||||||
|
.
|
||||||
|
For \f(CWm\fP above, rigctl returned the \f(CWMode\fP and \f(CWPassband\fP
|
||||||
|
values without further prompts.
|
||||||
|
.
|
||||||
|
The command prompt is returned after each command invocation.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The above examples invoked rigctl without specifying a radio model.
|
||||||
|
.
|
||||||
|
This is a feature where the Hamlib internal radio model 1
|
||||||
|
.I dummy
|
||||||
|
is used instead.
|
||||||
|
.
|
||||||
|
The dummy radio provides a way to test Hamlib functions without the need for
|
||||||
|
actual radio hardware.
|
||||||
|
.
|
||||||
|
However, to develop the Hamlib backend capability for a given radio, having
|
||||||
|
the actual radio connected to the computer is necessary for debugging.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
For example, to quickly set frequency on an Elecraft K3:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rigctl -m 229 -r /dev/rig F 3900000
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
and to query the frequency and then mode:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rigctl -m 229 -r /dev/rig f
|
||||||
|
.br
|
||||||
|
3900000
|
||||||
|
.sp
|
||||||
|
rigctl -m 229 -r /dev/rig m
|
||||||
|
.br
|
||||||
|
LSB
|
||||||
|
.br
|
||||||
|
2000
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.BR Note :
|
||||||
|
the returned values do not have the prompt strings associated with interactive
|
||||||
|
mode as shown above.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.B \-m
|
||||||
|
option takes a numeric value that corresponds to a given radio back end model.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.B \-r
|
||||||
|
option takes the path to the port device on
|
||||||
|
.SM POSIX
|
||||||
|
and the device name on Microsoft Windows.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.BR Note :
|
||||||
|
A complete list of supported radio models may be seen by use of the
|
||||||
|
.B -l
|
||||||
|
option:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rigctl -l
|
||||||
|
.br
|
||||||
|
Rig # Mfg Model Version Status
|
||||||
|
.br
|
||||||
|
1 Hamlib Dummy 0.5 Beta
|
||||||
|
.br
|
||||||
|
2 Hamlib NET rigctl 0.3 Beta
|
||||||
|
.br
|
||||||
|
101 Yaesu FT-847 0.5 Beta
|
||||||
|
.br
|
||||||
|
103 Yaesu FT-1000D 0.0.6 Alpha
|
||||||
|
.br
|
||||||
|
\&.
|
||||||
|
.br
|
||||||
|
\&.
|
||||||
|
.br
|
||||||
|
\&.
|
||||||
|
.br
|
||||||
|
2702 Rohde&Schwarz EB200 0.1 Untested
|
||||||
|
.br
|
||||||
|
2801 Philips/Simoco PRM8060 0.1 Alpha
|
||||||
|
.br
|
||||||
|
2901 ADAT www.adat.ch ADT-200A 1.36 Beta
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The list is long so use \f(CWShift\-PageUp\fP/\f(CWShift\-PageDown\fP on
|
||||||
|
Linux, \f(CWScrollLock\fP then \f(CWPageUp\fP/\f(CWPageDown\fP on Free BSD, or
|
||||||
|
use the scrollbar to the virtual terminal window
|
||||||
|
.RB ( cmd
|
||||||
|
window on Microsoft Windows) or the output can be piped to
|
||||||
|
.BR more (1)
|
||||||
|
or
|
||||||
|
.BR less (1),
|
||||||
|
e.g. \(lq\f(CWrigctl -l | more\fP\(rq to scroll back up the list.
|
||||||
|
.
|
||||||
|
The list is sorted numerically by model number since Hamlib 1.2.15.1.
|
||||||
|
.
|
||||||
|
Model numbers of a manufacturer/protocol family are grouped together.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rigctl reference
|
||||||
|
.
|
||||||
|
The complete reference for rigctl can be found in the
|
||||||
|
.BR rigctl (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rotctl
|
||||||
|
.
|
||||||
|
Identical in function to
|
||||||
|
.BR rigctl (1),
|
||||||
|
.BR rotctl (1)
|
||||||
|
provides a means for testing Hamlib functions useful for rotator control and
|
||||||
|
QTH (Maidenhead gridsquare system, see
|
||||||
|
.UR https://en.wikipedia.org/wiki/Maidenhead_Locator_System
|
||||||
|
Maidenhead Locator System
|
||||||
|
.UE )
|
||||||
|
locator computations.
|
||||||
|
.
|
||||||
|
As rotators have a much narrower scope than radios, there are fewer command
|
||||||
|
line options and commands for rotctl.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rotctl
|
||||||
|
.
|
||||||
|
.BR rotctl (1)
|
||||||
|
is a character based interactive program and a command line program able to
|
||||||
|
set or query a rotator's value with a single command.
|
||||||
|
.
|
||||||
|
rotctl is invoked from a shell command prompt with various options and
|
||||||
|
additional commands.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
In its most simple use as a
|
||||||
|
.I "command line"
|
||||||
|
program, rotctl is used to set azimuth position and (optionally) elevation by
|
||||||
|
typing commands after any rotctl options:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rotctl P 145.0 23.0
|
||||||
|
.br
|
||||||
|
rotctl M 8 25
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
and then query those values:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rotctl p
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Entering
|
||||||
|
.I "interactive mode"
|
||||||
|
is a simple matter of not placing any commands after any rotctl options:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rotctl
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Entering interactive mode allows successive commands to be entered without
|
||||||
|
exiting rotctl.
|
||||||
|
.
|
||||||
|
Interactive mode allows for command editing and history recall through the use
|
||||||
|
of the
|
||||||
|
.UR https://tiswww.case.edu/php/chet/readline/rltop.html
|
||||||
|
Readline
|
||||||
|
.UE
|
||||||
|
library.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Interactive mode is indicated by the spartan prompt:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
Rotator command:
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Commands are given at the prompt:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
Rotator command: M
|
||||||
|
.br
|
||||||
|
Direction: 16
|
||||||
|
.br
|
||||||
|
Speed: 60
|
||||||
|
.sp
|
||||||
|
Rotator command: p
|
||||||
|
.br
|
||||||
|
Azimuth: 11.352000
|
||||||
|
.br
|
||||||
|
Elevation: 0.000000
|
||||||
|
.sp
|
||||||
|
Rotator command: p
|
||||||
|
.br
|
||||||
|
Azimuth: 27.594000
|
||||||
|
.br
|
||||||
|
Elevation: 0.000000
|
||||||
|
.sp
|
||||||
|
Rotator command:
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
An additional prompt is printed when more information is required by the
|
||||||
|
command.
|
||||||
|
.
|
||||||
|
For \f(CWM\fP above, rotctl prompted for the \f(CWDirection\fP and
|
||||||
|
\f(CWSpeed\fP values.
|
||||||
|
.
|
||||||
|
For \f(CWp\fP above, rotctl returned the \f(CWAzimuth\fP and \f(CWElevation\fP
|
||||||
|
values without further prompts.
|
||||||
|
.
|
||||||
|
The command prompt is returned after each command invocation.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The above examples invoked rotctl without specifying a rotator model.
|
||||||
|
.
|
||||||
|
This is a feature where the Hamlib internal rotator model 1
|
||||||
|
.I dummy
|
||||||
|
is used instead.
|
||||||
|
.
|
||||||
|
The dummy rotator provides a way to test Hamlib functions without the need for
|
||||||
|
actual rotator hardware.
|
||||||
|
.
|
||||||
|
However, to develop back end capability for a given rotator, having the actual
|
||||||
|
controller connected to the computer is necessary for debugging.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
For example, to quickly set position for RotorEZ:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rotctl -m 401 -r /dev/rotor P 100.0 0.0
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
and to query the position:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rotctl -m 401 -r /dev/rotor p
|
||||||
|
.br
|
||||||
|
100.000000
|
||||||
|
.br
|
||||||
|
0.000000
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The returned values do not have the prompt strings associated with interactive
|
||||||
|
mode as shown above.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The
|
||||||
|
.B -m
|
||||||
|
option takes a numeric value that corresponds to a given rotator back end model.
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.B -r
|
||||||
|
option takes the path to the port device on
|
||||||
|
.SM POSIX
|
||||||
|
or the device name on Microsoft Windows.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
.BR Note :
|
||||||
|
A complete list of supported rotator models may be seen by use of the
|
||||||
|
.B -l
|
||||||
|
option:
|
||||||
|
.
|
||||||
|
.sp
|
||||||
|
.RS 0.5i
|
||||||
|
.EX
|
||||||
|
rotctl -l
|
||||||
|
.br
|
||||||
|
Rot # Mfg Model Version Status
|
||||||
|
.br
|
||||||
|
1 Hamlib Dummy 0.5 Beta
|
||||||
|
.br
|
||||||
|
2 Hamlib NET rotctl 0.3 Beta
|
||||||
|
.br
|
||||||
|
201 Hamlib EasycommI 0.3 Beta
|
||||||
|
.br
|
||||||
|
202 Hamlib EasycommII 0.3 Beta
|
||||||
|
.br
|
||||||
|
\&.
|
||||||
|
.br
|
||||||
|
\&.
|
||||||
|
.br
|
||||||
|
\&.
|
||||||
|
.br
|
||||||
|
1201 AMSAT IF-100 0.1 Untested
|
||||||
|
.br
|
||||||
|
1301 LA7LKA ts7400 0.1 Beta
|
||||||
|
.br
|
||||||
|
1401 Celestron NexStar 0.1 Untested
|
||||||
|
.EE
|
||||||
|
.RE
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The list is long so use \f(CWShift\-PageUp\fP/\f(CWShift\-PageDown\fP on
|
||||||
|
Linux, \f(CWScrollLock\fP then \f(CWPageUp\fP/\f(CWPageDown\fP on Free BSD, or
|
||||||
|
use the scrollbar to the virtual terminal window
|
||||||
|
.RB ( cmd
|
||||||
|
window on Microsoft Windows) or the output can be piped to
|
||||||
|
.BR more (1)
|
||||||
|
or
|
||||||
|
.BR less (1),
|
||||||
|
e.g. \(lq\f(CWrotctl -l | more\fP\(rq to scroll back up the list.
|
||||||
|
.
|
||||||
|
The list is sorted numerically by model number since Hamlib 1.2.15.1.
|
||||||
|
.
|
||||||
|
Model numbers of a manufacturer/protocol family are grouped together.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rotctl reference
|
||||||
|
.
|
||||||
|
The complete reference for rotctl can be found in the
|
||||||
|
.BR rotctl (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rigctld
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.BR rigctld (1)
|
||||||
|
program is a network server that accepts the familiar commands of
|
||||||
|
.BR rigctl (1)
|
||||||
|
and provides the response data over a
|
||||||
|
.SM TCP/IP
|
||||||
|
network socket to an application.
|
||||||
|
.
|
||||||
|
In this manner an application can access a rigctld instance from nearly
|
||||||
|
anywhere (caveat, no security is currently provided by rigctld).
|
||||||
|
.
|
||||||
|
Applications using rigctld do not link directly to Hamlib nor use its C API.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rigctld
|
||||||
|
.
|
||||||
|
.BR rigctld (1)
|
||||||
|
communicates to a client through a
|
||||||
|
.SM TCP
|
||||||
|
network socket using text commands shared with
|
||||||
|
.BR rigctl (1).
|
||||||
|
.
|
||||||
|
The protocol is simple; commands are sent to rigctld on one line and rigctld
|
||||||
|
responds to
|
||||||
|
.B get
|
||||||
|
commands with the requested values, one per line, when successful, otherwise,
|
||||||
|
it responds with one line
|
||||||
|
.B RPRT
|
||||||
|
.IR x ,
|
||||||
|
where
|
||||||
|
.I x
|
||||||
|
is a negative number indicating the Hamlib error code.
|
||||||
|
.
|
||||||
|
Commands that do not return values respond with the line
|
||||||
|
.B RPRT
|
||||||
|
.IR x ,
|
||||||
|
where
|
||||||
|
.I x
|
||||||
|
is zero when successful, otherwise a negative number indicating the Hamlib
|
||||||
|
error code.
|
||||||
|
.
|
||||||
|
Each line is terminated with a newline,
|
||||||
|
.IR \en ,
|
||||||
|
character.
|
||||||
|
.
|
||||||
|
This protocol is primarily for use by the
|
||||||
|
.B NET rigctl
|
||||||
|
(radio model 2) backend.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
A separate Extended Response protocol extends the above behavior by echoing
|
||||||
|
the received command string as a header, any returned values as a key: value
|
||||||
|
pair, and the
|
||||||
|
.B RPRT
|
||||||
|
.I x
|
||||||
|
string as the end of response marker which includes the Hamlib success or
|
||||||
|
failure value.
|
||||||
|
.
|
||||||
|
Consider using this protocol for clients that will interact with
|
||||||
|
rigctld directly through a TCP network socket.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Multiple radios can be controlled on different TCP ports by use of multiple
|
||||||
|
rigctld processes each listening on a unique TCP port.
|
||||||
|
.
|
||||||
|
It is hoped that rigctld will be especially useful for client authors using
|
||||||
|
languages such as
|
||||||
|
.UR http://www.perl.org/
|
||||||
|
Perl
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.python.org/
|
||||||
|
Python
|
||||||
|
.UE ,
|
||||||
|
.UR http://php.net/
|
||||||
|
PHP
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.ruby-lang.org/en/
|
||||||
|
Ruby
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.tcl.tk/
|
||||||
|
TCL
|
||||||
|
.UE ,
|
||||||
|
and others.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rigctld reference
|
||||||
|
.
|
||||||
|
The complete reference for rigctld can be found in the
|
||||||
|
.BR rigctld (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rotctld
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.BR rotctld (1)
|
||||||
|
program is a network server that accepts the familiar commands of
|
||||||
|
.BR rotctl (1)
|
||||||
|
and provides the response data over a \f(CWTCP/IP\fP network socket to an
|
||||||
|
application.
|
||||||
|
.
|
||||||
|
In this manner an application can access a rotctld instance from nearly
|
||||||
|
anywhere (caveat, no security is currently provided by rotctld).
|
||||||
|
.
|
||||||
|
Applications using rotctld do not link directly to Hamlib nor use its C API.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rotctld
|
||||||
|
.
|
||||||
|
.BR rotctld (1)
|
||||||
|
communicates to a client through a
|
||||||
|
.SM TCP
|
||||||
|
network socket using text commands shared with
|
||||||
|
.BR rotctl (1).
|
||||||
|
.
|
||||||
|
The protocol is simple, commands are sent to rotctld on one line and
|
||||||
|
rotctld responds to
|
||||||
|
.B get
|
||||||
|
commands with the requested values, one per line, when successful, otherwise,
|
||||||
|
it responds with one line
|
||||||
|
.B RPRT
|
||||||
|
.IR x ,
|
||||||
|
where
|
||||||
|
.I x
|
||||||
|
is a negative number indicating the Hamlib error code.
|
||||||
|
.
|
||||||
|
Commands that do not return values respond with the line
|
||||||
|
.B RPRT
|
||||||
|
.IR x ,
|
||||||
|
where
|
||||||
|
.I x
|
||||||
|
is zero when successful, otherwise a negative number indicating
|
||||||
|
the Hamlib error code.
|
||||||
|
.
|
||||||
|
Each line is terminated with a newline,
|
||||||
|
.I \en
|
||||||
|
character.
|
||||||
|
.
|
||||||
|
This protocol is primarily for use by the
|
||||||
|
.B NET rotctl
|
||||||
|
(rotator model 2) backend.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
A separate Extended Response protocol extends the above behavior by echoing
|
||||||
|
the received command string as a header, any returned values as a key: value
|
||||||
|
pair, and the
|
||||||
|
.B RPRT
|
||||||
|
.I x
|
||||||
|
string as the end of response marker which includes the Hamlib success or
|
||||||
|
failure value.
|
||||||
|
.
|
||||||
|
Consider using this protocol for clients that will interact with
|
||||||
|
rotctld directly through a TCP network socket.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Multiple rotators can be controlled on different TCP ports by use of multiple
|
||||||
|
rotctld processes each listening on a unique TCP port.
|
||||||
|
.
|
||||||
|
It is hoped that rotctld will be especially useful for client authors using
|
||||||
|
languages such as
|
||||||
|
.UR http://www.perl.org/
|
||||||
|
Perl
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.python.org/
|
||||||
|
Python
|
||||||
|
.UE ,
|
||||||
|
.UR http://php.net/
|
||||||
|
PHP
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.ruby-lang.org/en/
|
||||||
|
Ruby
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.tcl.tk/
|
||||||
|
TCL
|
||||||
|
.UE ,
|
||||||
|
and others.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rotctld reference
|
||||||
|
.
|
||||||
|
The complete reference for rotctld can be found in the
|
||||||
|
.BR rotctld (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rigmem
|
||||||
|
.
|
||||||
|
.B rigmem
|
||||||
|
may be used to backup and restore memory of radio transceivers and receivers.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rigmem
|
||||||
|
.
|
||||||
|
Backup and restore memory of radio transceivers and receivers.
|
||||||
|
.B rigmem
|
||||||
|
accepts
|
||||||
|
.IR command s
|
||||||
|
from the command line only.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rigmem reference
|
||||||
|
.
|
||||||
|
The complete reference for rigmem can be found in the
|
||||||
|
.BR rigmem (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rigsmtr
|
||||||
|
.
|
||||||
|
.B rigsmtr
|
||||||
|
uses
|
||||||
|
.B Hamlib
|
||||||
|
to control a radio to measure S-Meter value versus antenna azimuth.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rigsmtr
|
||||||
|
.
|
||||||
|
rigsmtr rotates the antenna from minimum azimuth to maximum azimuth.
|
||||||
|
Every second, or
|
||||||
|
.I time_step
|
||||||
|
if specified in seconds, it retrieves the signal strength. Azimuth in degrees
|
||||||
|
and the corresponding S-Meter level in dB relative to S9 are then printed on
|
||||||
|
.BR stdout .
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
To work correctly, rigsmtr needs a radio that could measure S-Meter and a Hamlib
|
||||||
|
backend that is able to retrieve it, connected to a Hamlib supported rotator.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rigsmtr reference
|
||||||
|
.
|
||||||
|
The complete reference for rigsmtr can be found in the
|
||||||
|
.BR rigsmtr (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH rigswr
|
||||||
|
.
|
||||||
|
.B rigswr
|
||||||
|
may be used to measure VSWR vs frequency.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Introduction to rigswr
|
||||||
|
.
|
||||||
|
rigswr uses Hamlib to control a radio to measure VSWR (Voltage Standing
|
||||||
|
Wave Ratio) over a frequency range.
|
||||||
|
|
||||||
|
It scans frequencies from
|
||||||
|
.I start_freq
|
||||||
|
to
|
||||||
|
.I stop_freq
|
||||||
|
with an optional increment of
|
||||||
|
.I freq_step
|
||||||
|
(default step is 100 kHz).
|
||||||
|
.
|
||||||
|
All values must be entered as an integer in Hertz (cycles per second).
|
||||||
|
|
||||||
|
.BR Note :
|
||||||
|
rigswr assumes that
|
||||||
|
.I start_freq is less than or equal to
|
||||||
|
.IR stop_freq .
|
||||||
|
.
|
||||||
|
If it is greater, rigswr will exit without doing anything.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
For each frequency, rigswr transmits at 25% of total POWER during 0.5 second
|
||||||
|
in CW mode and reads VSWR.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Frequency and the corresponding VSWR are then printed on stdout.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
To work correctly, rigswr needs a radio that can measure VSWR and a
|
||||||
|
Hamlib backend that supports reading VSWR from the radio.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS rigswr reference
|
||||||
|
.
|
||||||
|
The complete reference for rigswr can be found in the
|
||||||
|
.BR rigswr (1)
|
||||||
|
manual page.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH COPYING
|
||||||
|
.
|
||||||
|
This file is part of Hamlib, a project to develop a library that simplifies
|
||||||
|
radio and rotator control functions for developers of software primarily of
|
||||||
|
interest to radio amateurs and those interested in radio communications.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Copyright \(co 2001-2018 Hamlib Group (various contributors)
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH SEE ALSO
|
||||||
|
.
|
||||||
|
.BR less (1),
|
||||||
|
.BR more (1),
|
||||||
|
.BR rigctl (1),
|
||||||
|
.BR rigctld (1),
|
||||||
|
.BR rotctl (1),
|
||||||
|
.BR rotctld (1),
|
||||||
|
.BR rigmem (1),
|
||||||
|
.BR rigsmtr (1),
|
||||||
|
.BR rigswr (1),
|
||||||
|
.BR hamlib (7),
|
||||||
|
.BR hamlib-primer (7)
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH COLOPHON
|
||||||
|
.
|
||||||
|
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot
|
||||||
|
archives:
|
||||||
|
.IP
|
||||||
|
.UR http://www.hamlib.org
|
||||||
|
hamlib.org
|
||||||
|
.UE .
|
|
@ -0,0 +1,345 @@
|
||||||
|
.\" Hey, EMACS: -*- nroff -*-
|
||||||
|
.\"
|
||||||
|
.\" For layout and available macros, see man(7), man-pages(7), groff_man(7)
|
||||||
|
.\" Please adjust the date whenever revising the manpage.
|
||||||
|
.\"
|
||||||
|
.\" Please keep this file in sync with doc/nutshell.texi
|
||||||
|
.\"
|
||||||
|
.TH HAMLIB "7" "2018-05-21" "Hamlib" "Hamlib Information Manual"
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH NAME
|
||||||
|
.
|
||||||
|
hamlib \- radio and rotator control library
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH DESCRIPTION
|
||||||
|
.
|
||||||
|
The
|
||||||
|
.BR "Ham Radio Control Libraries" ,
|
||||||
|
.B Hamlib
|
||||||
|
for short, is a development effort to provide a consistent interface for
|
||||||
|
programmers wanting to incorporate radio and rotator control in their
|
||||||
|
programs.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Hamlib attempts to solve this problem by presenting a
|
||||||
|
.I 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.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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
|
||||||
|
.BR C ", " C++ ", " Perl ", " Python ", " Lua " and " TCL
|
||||||
|
(more to come).
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Overview
|
||||||
|
.
|
||||||
|
Hamlib is a
|
||||||
|
.I front end
|
||||||
|
library providing a
|
||||||
|
.B C
|
||||||
|
language Application Programming Interface (API) to programmers wishing to
|
||||||
|
integrate radio or rotator control in their applications.
|
||||||
|
.
|
||||||
|
Hamlib presents a
|
||||||
|
.I virtual radio
|
||||||
|
or
|
||||||
|
.I virtual rotator
|
||||||
|
that is a consistent interface to an application despite wide differences in
|
||||||
|
radio and rotator interfaces and capabilities.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The front end library uses a number of
|
||||||
|
.I 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.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Hamlib also provides an interface library for each of several common
|
||||||
|
.I scripting
|
||||||
|
languages such as
|
||||||
|
.UR http://www.perl.org
|
||||||
|
.B Perl
|
||||||
|
.UE ,
|
||||||
|
.UR http://www.python.org
|
||||||
|
.B Python
|
||||||
|
.UE ,
|
||||||
|
.UR https://www.lua.org
|
||||||
|
.B Lua
|
||||||
|
.UE ,
|
||||||
|
and
|
||||||
|
.UR http://www.tcl.tk
|
||||||
|
.B TCL
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
These language
|
||||||
|
.I bindings
|
||||||
|
are
|
||||||
|
generated through the use of
|
||||||
|
.UR http://www.swig.org
|
||||||
|
.B SWIG
|
||||||
|
.UE ,
|
||||||
|
a parser/generator for multiple language interfaces to a
|
||||||
|
.B C
|
||||||
|
library.
|
||||||
|
.
|
||||||
|
A natively generated
|
||||||
|
.B C++
|
||||||
|
language interface is also provided.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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
|
||||||
|
.BR TCP / IP
|
||||||
|
network connection.
|
||||||
|
.
|
||||||
|
The daemons then handle the interface to the Hamlib C API.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS 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 latest release of 3.2 in early 2018.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Development continues through the major version number
|
||||||
|
.RI 3. x
|
||||||
|
series and beyond.
|
||||||
|
.
|
||||||
|
While some API tweaks are planned, ABI compatibility with the prior
|
||||||
|
.RI 1.2. x
|
||||||
|
releases remains a priority.
|
||||||
|
.
|
||||||
|
Other goals include streamlining the build system (done), improving the SWIG
|
||||||
|
generated language bindings (done), improving the overall documentation (this
|
||||||
|
man page with more in progress), and other updates as warranted.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
The Project is hosted by
|
||||||
|
.UR https://sourceforge.net
|
||||||
|
SourceForge.net
|
||||||
|
.UE
|
||||||
|
at the
|
||||||
|
.UR https://sourceforge.net/projects/hamlib/
|
||||||
|
Hamlib project page
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
As
|
||||||
|
.UR https://github.com
|
||||||
|
GitHub
|
||||||
|
.UE
|
||||||
|
has become a very popular project hosting site, Hamlib also has a dedicated
|
||||||
|
.UR https://github.com/Hamlib/Hamlib
|
||||||
|
GitHub project page
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
GitHub also hosts the
|
||||||
|
.UR http://www.hamlib.org
|
||||||
|
hamlib.org
|
||||||
|
.UE
|
||||||
|
Web site and the
|
||||||
|
.UR https://github.com/Hamlib/Hamlib/wiki
|
||||||
|
Hamlib Wiki
|
||||||
|
.UE .
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Development discussion and most user support take place on the
|
||||||
|
.UR https://sourceforge.net/p/hamlib/mailman/
|
||||||
|
hamlib-developer mailing list
|
||||||
|
.UE .
|
||||||
|
While there are
|
||||||
|
.UR https://sourceforge.net/p/hamlib/discussion/
|
||||||
|
SourceForge.net discussion forums
|
||||||
|
.UE ,
|
||||||
|
they are rarely used and not as closely read by the developers as the mailing
|
||||||
|
list.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
For
|
||||||
|
.IR "source code management" ,
|
||||||
|
the project uses
|
||||||
|
.UR http://git-scm.com/
|
||||||
|
.B Git
|
||||||
|
.UE ,
|
||||||
|
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
|
||||||
|
.BR hamlib\-git (7).
|
||||||
|
.
|
||||||
|
.IP
|
||||||
|
.BR 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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS 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,
|
||||||
|
.UR https://github.com/Hamlib/Hamlib/wiki/Applications-and-Screen-Shots
|
||||||
|
Applications/Screenshots
|
||||||
|
.UE .
|
||||||
|
Developers are encouraged to request their applications be added to the
|
||||||
|
gallery by way of the hamlib-developer mailing list.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS 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
|
||||||
|
.B Lesser General Public License
|
||||||
|
(LGPL) for the library portion, and the
|
||||||
|
.B General Public License
|
||||||
|
(GPL) for the utility programs.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS 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,
|
||||||
|
.UR http://chirp.danplanet.com
|
||||||
|
CHIRP
|
||||||
|
.UE ,
|
||||||
|
aims to support radios with such a clone capability.
|
||||||
|
.
|
||||||
|
Please contact the CHIRP project for support of such radios.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SS Pronouncing Hamlib
|
||||||
|
.
|
||||||
|
English speakers seem to have two alternate pronunciations for our project:
|
||||||
|
.
|
||||||
|
.nf
|
||||||
|
.IP \(bu 4
|
||||||
|
Hamlib (Ham \- lib, long \(oqi\(cq, as in library.) IPA style: /\(aqham læb/
|
||||||
|
.
|
||||||
|
.IP \(bu 4
|
||||||
|
Hamlib (Ham \- lib, short \(oqi\(cq, as in liberty.) IPA style: /\(aqham lɪb/
|
||||||
|
.fi
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Then again, we have people who say Linux \(lqL-eye-nux\(rq and those who say
|
||||||
|
\(lqL-in-nux\(rq...
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
If you're French, the above does not apply! :-)
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH COPYING
|
||||||
|
.
|
||||||
|
This file is part of Hamlib, a project to develop a library that simplifies
|
||||||
|
radio and rotator control functions for developers of software primarily of
|
||||||
|
interest to radio amateurs and those interested in radio communications.
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
Copyright \(co 2001-2018 Hamlib Group (various contributors)
|
||||||
|
.
|
||||||
|
.PP
|
||||||
|
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.
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH SEE ALSO
|
||||||
|
.
|
||||||
|
.BR hamlib-primer (7)
|
||||||
|
.
|
||||||
|
.
|
||||||
|
.SH COLOPHON
|
||||||
|
.
|
||||||
|
Links to the Hamlib Wiki, Git repository, release archives, and daily snapshot
|
||||||
|
archives:
|
||||||
|
.IP
|
||||||
|
.UR http://www.hamlib.org
|
||||||
|
hamlib.org
|
||||||
|
.UE .
|
Ładowanie…
Reference in New Issue