mirror
/
Hamlib
kopia lustrzana https://github.com/Hamlib/Hamlib
1
0
Forkuj 0
Kod Zgłoszenia Projekty Wydania Wiki Aktywność

24 Sep 2001 

Added Hamlib manual SGML source files to CVS.


git-svn-id: https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk@665 7ae35d74-ebe9-4afe-98af-79ac388436b8
Hamlib-1.1.3
Nate Bargmann, N0NB 2001-09-25 03:53:06 +00:00
rodzic 6b4830b02e
commit f896e4e7ce
7 zmienionych plików z 4361 dodań i 0 usunięć

11
doc/sgml/backend.sgml 100644
Wyświetl plik

@ -0,0 +1,11 @@
<chapter id="backend">
<title>Writing a backend for hamlib</title>
<para></para>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-parent-document: ("hamlib.sgml" "book" "chapter")
End:
-->

87
doc/sgml/hamlib-doc.sgml 100644
Wyświetl plik

@ -0,0 +1,87 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
<!ENTITY preface SYSTEM "preface.sgml">
<!ENTITY intro SYSTEM "intro.sgml">
<!ENTITY using SYSTEM "using.sgml">
<!ENTITY reference SYSTEM "reference.sgml">
<!ENTITY backend SYSTEM "backend.sgml">
<!ENTITY internals SYSTEM "internals.sgml">
<!ENTITY curver "1.1.0 (ALPHA)">
]>
<book>
<bookinfo>
<title>Ham Radio Control Libraries</title>
<subtitle>API Reference for Version &curver;</subtitle>
<author>
<firstname>Nathan</firstname>
<surname>Bargmann</surname>
</author>
<address>
<email>n0nb@networksplus.net</email>
</address>
<pubdate>23 September 2001</pubdate>
<copyright>
<year>2000</year>
<year>2001</year>
<holder>Frank Singleton, VK3FCS &amp; KM5WS; Stephane Fillod, F4CFE;
Nate Bargmann, N0NB</holder>
</copyright>
<legalnotice id="legalnotice">
<title>Hamlib-doc - Ham Radio Control Libraries Documentation</title>
<para>Copyright (C) 2000-2001 Stephane Fillod, Frank Singleton, Nate
Bargmann. This documentation file is part of the Hamlib
package.</para>
<para>Hamlib-doc is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.</para>
<para>Hamlib-doc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.</para>
<para>You should have received a copy of the GNU General Public
License along with Hamlib-doc; see the file COPYING. If not, write
to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge,
MA 02139, USA.</para>
</legalnotice>
<abstract>
<title>Abstract</title>
<para>Demonstrate the need for Hamlib, document the Hamlib API, provide
an introduction to writing a program using Hamlib, and provide an
introduction to authoring a backend library to control a radio or other
device.</para>
</abstract>
<revhistory>
<revision>
<revnumber>0.1.1</revnumber>
<date>23 September 2001</date>
<authorinitials>nfb</authorinitials>
<revremark>Final final draft for &curver;</revremark>
</revision>
<revision>
<revnumber>0.1.0</revnumber>
<date>24 February 2001</date>
<authorinitials>nfb</authorinitials>
<revremark>Final draft for &curver;</revremark>
</revision>
<revision>
<revnumber>0.0.1</revnumber>
<date>4 February 2001</date>
<authorinitials>nfb</authorinitials>
<revremark>Rough draft of Preface and Chapter 1. Posted on the
Web for critique</revremark>
</revision>
</revhistory>
</bookinfo>
&preface;
&intro;
<!-- Comment out unstarted chapters for 1.1.0 (ALPHA) -->
<!-- &using; -->
&reference;
<!-- &backend; -->
<!-- &internals; -->
</book>

11
doc/sgml/internals.sgml 100644
Wyświetl plik

@ -0,0 +1,11 @@
<chapter id="internals">
<title>A Tour of hamlib</title>
<para></para>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-parent-document: ("hamlib.sgml" "book" "chapter")
End:
-->

293
doc/sgml/intro.sgml 100644
Wyświetl plik

@ -0,0 +1,293 @@
<chapter id="intro">
<title>Introduction to Hamlib</title>
<para>When browsing through the owners manual of that new radio, the pages
devoted to the computer commands seem like an afterthought. While the
manufacturers are not interested in becoming software houses, they do
adequately document the computer control capabilities which allow
independent control software to be written. With the myriad possibilities
of radios and manufacturers available, writing that ultimate logging or
<acronym>PSK31</acronym> application can be a daunting task if even basic
radio control support is desired. The Ham Radio Control Libraries project
aims to develop a solution to this problem.</para>
<section id="overview">
<title>Overview of Hamlib</title>
<para>Hamlib itself is not an end-user application for radio
control. Rather, it is a collection of libraries, both shared, or
dynamic linked libraries, if you will, and static libraries that
provide end-user applications with
a common means of acessing and controlling radios (and perhaps other
ham radio related peripheral devices in the future) directly connected
to a computer or remotely over a network. Hamlib is currently being
developed on the Linux operating system, but plans include it being
usable on various flavors of <trademark>UNIX</trademark> and
<trademark>Windows</trademark>, or whatever platform GNU autoconf
will support.</para>
<para>Hamlib consists of several parts. The application programming
interface, <acronym>API</acronym>, shared library is
<filename>libhamlib-1.1.0.so</filename> which is installed in
<filename class="directory">/usr/local/lib</filename> by default.
For ease of use when linking,
<filename class="symlink">libhamlib.so</filename> is provided as a
symbolic link to the latest version of Hamlib installed. Of course,
the installation directory may be changed by passing the proper
option to the <command>configure</command> script in the base
directory of the source distribution. While the static library is
<filename>libhamlib.a</filename> and installed in <filename
class="directory">/usr/local/lib</filename> as well.</para>
<para>The second main part of Hamlib consists of a number of
"backend" libraries each able to communicate to a specific radio.
For example, <filename>libhamlib-ft747.so</filename> is the shared
backend library that provides Hamlib access to the Yaesu FT-747
radio. By default the backend libraries are also installed in
<filename class="directory">/usr/local/lib</filename>. Both shared
and static libraries are provided by the default
installation.</para>
</section>
<section id="freesoftware">
<title>Hamlib is Free Software</title>
<para>The Hamlib libraries are Free
Software licensed under the GNU Public License, <acronym>GPL</acronym>,
version 2. It is important to be aware that use of Hamlib in a
proprietary program has severe restrictions placed on it by the
<acronym>GPL</acronym>. As a result one must carefully consider
what kind of license to use for your program. Of course we
encourage using the <acronym>GPL</acronym> for your program as it
adds to the pool of available Free Software to the ham
community.</para>
<para>The advantages of Free Software are multitude, but the primary ones
include accessability of your code to others who can fix problems or
add new functionality. Another advantage is that your code is
always available to be studied by other experimenters and your code
has a much lower chance of becoming dead bits that can't be used on
newer operating systems. For an experimenter's hobby like ham
radio, Free Software offers many more advantages than disadvantages
to you and the ham community.</para>
</section>
<section id="resources">
<title>Hamlib development resources</title>
<para>If you are interested in working on Hamlib development itself,
there exist a few resources on the World Wide Web. The main project
page is at <ulink url="http://sourceforge.net/projects/hamlib/">http://sourceforge.net/projects/hamlib/</ulink>.
A homepage is currently in development at <ulink url="http://hamlib.sourceforge.net">http://hamlib.sourceforge.net</ulink>
A development mailing list is hosted by <ulink url="http://sourceforge.net">http://sourceforge.net</ulink>. Subscription information and an archive
can be accessed through the Hamlib project main page.</para>
</section>
<section id="gettinghamlib">
<title>Getting Hamlib</title>
<para>At this time Hamlib is not included as a binary package in any
major distribution that we're aware of (hopefully this will change
soon). Until then you may retrieve the source from the Hamlib project
page at <ulink
url="http://sourceforge.net/projects/hamlib/">http://sourceforge.net/projects/hamlib/</ulink>.</para>
<section id="stablever">
<title>Latest stable version</title>
<para>The latest stable version is &curver;. Currently the project is
in its early stages and only a few backend libraries are included.
Hamlib is currently in heavy development.</para>
</section>
<section id="develver">
<title>Latest development version</title>
<para>The latest development code is available via anonymous
<acronym>CVS</acronym> through the
<ulink url="http://sourceforge.net/projects/hamlib/">project
page</ulink>.</para>
<section id="anonymouscvs">
<title>Accessing anonymous CVS</title>
<para>The following instructions are copied from the
<ulink url="http://sourceforge.net">Sourceforge</ulink> website
(modified with hamlib in the right places) and did work for me.</para>
<section id="anonymouscvsinstr">
<title>Anonymous CVS instructions</title>
<para>Hamlib's SourceForge CVS repository can be checked out through
anonymous (pserver) CVS with the following instruction set. When
prompted for a password for <emphasis>anonymous</emphasis>, simply
press the <keycap>Enter</keycap> key.</para>
<screen format="linespecific">
<prompt>myhost:~/src $</prompt> <command>cvs -d:pserver:anonymous@cvs.hamlib.\</command>
<prompt>&gt;</prompt> <command>sourceforge.net:/cvsroot/hamlib login</command>
<prompt>myhost:~/src $</prompt> <command>cvs -z3 -d:pserver:anonymous@cvs.hamlib.\</command>
<prompt>&gt;</prompt> <command>sourceforge.net:/cvsroot/hamlib co hamlib</command>
</screen>
<note><title>Working with long commandlines</title>
<para>Long commands like those above are difficult to work with
because once the line wraps the <literal>Bash(1)</literal> shell
seems to start doing weird things. The trick is breaking the line
into two (or more) parts with the <quote>\</quote> character.
When the right edge of the screen is reached simply add
<literal>\</literal> to the end of the text you are typing and
then press
<keycap>Enter</keycap>. You will receive a <prompt>&gt;</prompt>
from <literal>Bash(1)</literal> and you may continue typing the
command. If there is no space character in the command you are
typing, be sure you don't add a space before the <literal>\</literal>
or at the beginning of the next line. If you break the line where
a space would exist in the command, either putting the space before
the <literal>\</literal> or at the beginning of the next line.
<literal>Bash(1)</literal> will splice the lines together to form one
command once it receives a <keycap>Enter</keycap> character not
preceded by a <literal>\</literal>.
</note>
<para>Updates from within the hamlib directory do not need the
<command>-d</command> parameter.</para>
<para>If you get the following error:</para>
<literallayout>cvs login: failed to open /home/user/.cvspass for reading:
No such file or directory
cvs [login aborted]: fatal error: exiting
</literallayout>
<para>You can probably solve this by using the <command>touch</command>
command to create the file <literal>.cvspass</literal> in your home
directory:</para>
<screen>
<prompt>myhost:~ $</prompt> <command>touch .cvspass</command>
</screen>
</section>
</section>
</section>
</section>
<section id="building">
<title>Building Hamlib</title>
<para>Building Hamlib from source isn't as daunting as it may seem
at first, thanks to GNU <command>autoconf</command>, a tool used by
the developers that generates the <command>configure</command>
script found in the base directory of the source distribution.
Running <command>configure</command> will test your system to be
sure that any required packages for building Hamlib are present.
While <command>configure</command> checks for many components, the
only critical dependency is that the C library development header
files are installed. Of course, you'll need a C compiler and its
associated libraries.</para>
<section id="unpacking">
<title>Unpacking the source archive</title>
<para>While my favorite method of unpacking
<filename>.tar.gz</filename> files is to use the Linux version of
the Swiss Army Knife, Midnight Commander, the instructions
provided are for using <command>tar</command> at the command
prompt.</para>
<section id="tarunpack">
<title>Using <command>tar</command> to extract the archive</title>
<para>The first order of business is choosing a location for the
source distribution. Some may choose to place the archive under
<filename class="directory">/usr/local/src</filename>, or may
prefer to work within their home directory. The disadvantage of
working in <filename class="directory">/usr/local/src</filename>
is that one must either be logged in as <literal>root</literal> or
be a member of a group such as <literal>staff</literal> that has
write permissions on the directory. The advantage of working in
one's home directory is that writing and deleting files can be
done with much lower risk of damage to the system areas of the
filesystem. Either way, you will need to be logged in as
<literal>root</literal> to install the libraries after compiling.
On with unpacking the archive.</para>
<para>For this example I will make a few assumptions, the archive
is downloaded and stored in <filename class="directory">~/Download</filename>
and the source distribution will be installed in <filename class="directory">~/src</filename>.</para>
<note>
<title>Interpreting <filename class="directory">~</filename></title>
<para>If you are new to <trademark>UNIX</trademark> type
systems, you may be puzzled just what <literal>~</literal>
prepended to a path name means. It is simply a short hand for
your home directory. If your user name is
<literal>fred</literal>, then <literal>~</literal> refers to
<filename class="directory">/home/fred</filename> on most
systems, of course there are exceptions. If you are logged in
as <literal>root</literal> then <literal>~</literal> refers to
<filename class="directory">/root</filename>.</para>
</note>
<para>The following sequence of commands will get the Hamlib
archive to the right place (substitute your paths in the
examples). First we'll move the archive into the directory where
it will be extracted then use the tar command to extract the
archive into its own directory.</para>
<screen format="linespecific">
<prompt>myhost:~ $</prompt> <command>mv Download/hamlib-1.1.0.tar.gz src</command>
<prompt>myhost:~ $</prompt> <command>cd src</command>
<prompt>myhost:~/src $</prompt> <command>tar xvfz hamlib-1.1.0.tar.gz</command>
</screen>
<para>Now you should have a directory called <filename class="directory">hamlib-1.1.0</filename>
in the directory you executed the <command>tar</command> command.
This would be a good time to familiarize yourself with the files in
the archive.</para>
</section>
</section>
<section id="compiling">
<title>Compiling Hamlib</title>
<para>Thanks to the clever design of GNU <literal>autoconf</literal>
compiling Hamlib is as easy as running:</para>
<screen format="linespecific">
<prompt>myhost:~/src/hamlib-1.1.0 $</prompt> <command>./configure</command>
</screen>
<para>The <literal>configure</literal> script checks for the presence of
the proper development files required to build Hamlib. After the checks
<literal>configure</literal> then creates the Makefiles from the
included templates in the archive. The next step is to compile
Hamlib:</para>
<screen format="linespecific">
<prompt>myhost:~/src/hamlib-1.1.0 $</prompt> <command>make</command>
</screen>
<para>Now there should be considerable output to the screen during
the compile process. The main thing here is to make sure that
<command>gcc</command> doesn't fail while reporting an error. The most
common failure is a message saying that a certain file cannot be
found. Most likely the named file will have a <literal>.h</literal>
extension which means the development files of a required library
aren't installed on your system. As of this writing only the glibc
development files are required.</para>
</section>
</section>
<section id="summary">
<title>Summary</title>
<para>Hamlib is a tool for software authors wishing to take advantage of
the computer control capabilities of modern transceivers and other
devices used around the radio shack. When Hamlib reaches maturity
it will likely be available in your favorite packaging format and
manually compiling it won't be necessary unless you wish to customize
Hamlib itself.</para>
<para>The remainder of this manual assumes a working knowledge of
<trademark>UNIX</trademark> type systems. If you are new to Linux,
I suggest getting a copy of Running Linux by O'Reilly and Associates
from your local bookstore. You can preview this excellent reference
on the Web at <ulink url="http://www.oreilly.com/catalog/runux3/">http://www.oreilly.com/catalog/runux3/</ulink>.
</section>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-parent-document: ("hamlib.sgml" "book" "chapter")
End:
-->

64
doc/sgml/preface.sgml 100644
Wyświetl plik

@ -0,0 +1,64 @@
<preface id="preface">
<title>Preface</title>
<para>The Personal Computer has arguably become as prominent of a fixture
in the modern hamshack as HF transceivers and handheld radios. The first
PCs hams used combined with an interface also known as a terminal unit,
<acronym>TU</acronym>, replaced the noisy mechanical radio teletype,
<acronym>RTTY</acronym>, machines. Gradually, other uses became apparent
for the hamshack PC such as logging contact information, operating newer
digital modes such as <acronym>AMTOR</acronym>, a forward error correcting
(<acronym>FEC</acronym>) mode of <acronym>RTTY</acronym>, and packet, an
error checked way of transfering binary data between computers.</para>
<para>In the mid to late 1980s radio manufacturers began to offer computer
control capability to their offerings. Now the shack PC had one more duty
added to its repertoire. However, the amount of control over a given
radio's capability by computer control was often much less than from the
front panel. In large part was due to many analog controls on the front
panel that weren't under control of the radio's <acronym>CPU</acronym>.
Thus most radio control has been limited to control of frequency values
of the variable frequency
oscillators, <acronym>VFO</acronym>, and recalling and setting the radio's
memory channels.</para>
<para>More recent models have more of the front panel controls under the
supervision of the radio's <acronym>CPU</acronym>, consequently
manufacturers have enabled more control of the radio's functions through
the computer interface. This has created an explosion of command functions
not just between the different manufacturers, but also among a given
manufacturer's product line. There may also exist subtle differences in
later versions of a given model.</para>
<para>For the software author wishing to incorporate even the most basic of
radio control functions, the task is daunting. Even the long lived logging
program <trademark>CT</trademark> by Ken Wolff, K1EA has reports of subtle
bugs in one radio model or another (this is not intended as a knock of Ken
or his effort, rather it is an observation of the complexity of supporting
a multitude of radios in a monolithic program by one or a few authors). Is
every programmer doomed to recreate radio control themselves with varying
degrees of success? The answer is, no! </para>
<para>Enter the Hamlib project. Hamlib aims to provide application authors
with a single application programming interface, <acronym>API</acronym>,
regardless of the actual radio in use. Thus Hamlib is not an end user
application, but is a middle software layer that acts as a translator
between the <acronym>API</acronym> and the specific radio commands.</para>
<para>This manual will attempt to explain in detail the Hamlib <acronym>API
</acronym>, how to use Hamlib for writing radio control software, how to
write a radio backend library, and an overview of Hamlib's structure and
design.</para>
<para>Finally, Hamlib is Free Software licensed under the GNU Public
License, <acronym>GPL</acronym>, version 2. This will have certain
implications if you are a software author considering using Hamlib as a
part of your project. Consult the COPYING file in the base directory of
the Hamlib source distribution for more details.</para>
</preface>
<!--
Local Variables:
mode: sgml
sgml-parent-document: ("hamlib.sgml" "book" "preface")
End:
-->

3876
doc/sgml/reference.sgml 100644
Wyświetl plik

Plik diff jest za duży Load Diff

19
doc/sgml/using.sgml 100644
Wyświetl plik

@ -0,0 +1,19 @@
<chapter id="using">
<title>Using the hamlib API</title>
<para></para>
<section id="languages">
<title>Using Hamlib in your project</title>
<para>Currently Hamlib only provides a C language interface,
however, wrappers are planned for popular languages like C++, Perl,
and Python in the future.
</para>
</section>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-parent-document: ("hamlib.sgml" "book" "chapter")
End:
-->