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
Nate Bargmann
rodzic
e3f1e4adcf
commit
d984a58113
|
|
@ -2,7 +2,8 @@ EXTRA_DIST = hamlib.cfg index.doxygen hamlib.css footer.html \
|
|||
Hamlib_design.eps Hamlib_design.png
|
||||
|
||||
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
|
||||
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