kopia lustrzana https://github.com/Hamlib/Hamlib
517 wiersze
18 KiB
Plaintext
517 wiersze
18 KiB
Plaintext
Hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)
|
|
(C) Stephane Fillod 2000-2011
|
|
(C) The Hamlib Group 2000-2011
|
|
|
|
Take a look at http://sourceforge.net/projects/hamlib/
|
|
Here you will find a mail list, and the latest SVN releases.
|
|
|
|
See README for frontend/backend outline.
|
|
|
|
|
|
The shared libs provide functions for both radio control,
|
|
and data retrieval from the radio.
|
|
|
|
The structure of the libraries is as follows.
|
|
|
|
(1) There is one frontend library "libhamlib" that
|
|
provides the generic API for user applications.
|
|
|
|
(2) There are "n" backend libraries that "wrap"
|
|
rig specific communications inside frontend API.
|
|
|
|
(3) Frontend lib loads (on demand) the appropriate
|
|
backend lib as required.
|
|
|
|
Frontend Library
|
|
----------------
|
|
|
|
libhamlib.so - frontend lib that provides generic API
|
|
for all RIG types. This is what Application
|
|
programmers will "see".
|
|
|
|
Backend Examples are:
|
|
---------------------
|
|
|
|
1.hamlib-yaesu.so will provide connectivity to Yaesu
|
|
FT 747GX Transceiver, FT 847 "Earth Station", etc. via a standard API.
|
|
|
|
2. hamlib-xxxx.so will provide connectivity to the Wiz-bang
|
|
moon-melter 101A (yikes..)
|
|
|
|
Hamlib also enables developers to develop professional looking
|
|
GUI's towards a standard control library API, and they would not have
|
|
to worry about the underlying connection towards physical hardware.
|
|
|
|
Serial (RS232) connectivity is built in as are IP (also via a socket
|
|
utility) and USB. Other connectivity will follow afterwards.
|
|
|
|
|
|
General Guidelines.
|
|
-------------------
|
|
|
|
0. The top level directory looks like this as of 19 Jan 2011
|
|
(Note, it has grown considerably).
|
|
|
|
~/test/hamlib $ tree -d -I .svn
|
|
|
|
.
|
|
|-- alinco
|
|
|-- aor
|
|
|-- ars
|
|
|-- bindings
|
|
|-- c++
|
|
|-- doc
|
|
| `-- sgml
|
|
|-- drake
|
|
|-- dummy
|
|
|-- easycomm
|
|
|-- flexradio
|
|
|-- fodtrack
|
|
|-- gnuradio
|
|
|-- gs232a
|
|
|-- heathkit
|
|
|-- icom
|
|
|-- include
|
|
| `-- hamlib
|
|
|-- jrc
|
|
|-- kachina
|
|
|-- kenwood
|
|
|-- kit
|
|
|-- kylix
|
|
| `-- tests
|
|
|-- lib
|
|
|-- libltdl
|
|
| |-- config
|
|
| |-- libltdl
|
|
| |-- loaders
|
|
| `-- m4
|
|
|-- lowe
|
|
|-- m2
|
|
|-- macros
|
|
|-- microtune
|
|
|-- miniVNA
|
|
|-- pcr
|
|
|-- perl
|
|
|-- prm80
|
|
|-- racal
|
|
|-- rft
|
|
|-- rotorez
|
|
|-- rpcrig
|
|
|-- rpcrot
|
|
|-- rs
|
|
|-- sartek
|
|
|-- skanti
|
|
|-- spid
|
|
|-- src
|
|
|-- tapr
|
|
|-- tentec
|
|
|-- tests
|
|
| |-- config
|
|
| |-- rigctl.test
|
|
| |-- testbcd.test
|
|
| |-- testfreq.test
|
|
| `-- testloc.test
|
|
|-- tuner
|
|
|-- uniden
|
|
|-- winradio
|
|
| `-- linradio
|
|
|-- wj
|
|
`-- yaesu
|
|
|
|
62 directories
|
|
|
|
|
|
1. Building
|
|
|
|
If you just want to recompile the library, please refer
|
|
to the INSTALL file. This document introduces hacking the code of Hamlib.
|
|
|
|
|
|
1.1 Obtaining sources: SVN trunk checkout
|
|
|
|
svn co https://hamlib.svn.sourceforge.net/svnroot/hamlib/trunk hamlib
|
|
|
|
N.B.: If the "trunk" subdirectory is ommited then the entire SVN
|
|
reposity will be downloaded! This includes all branches and tags that
|
|
have ever been created in the history of Hamlib. That is quite large,
|
|
abut 22 MiB as of this writing (March 2009).
|
|
|
|
The check out has only to be done the first time.
|
|
|
|
After the initial retrieval, whenever you want to update your local
|
|
version, issue the following command in the root directory of hamlib.
|
|
|
|
svn update
|
|
|
|
|
|
1.1.1 Obtaining more info on SVN
|
|
|
|
Check out the sourceforge page at https://sourceforge.net/svn/?group_id=8305
|
|
for more information about how to use the SVN repository of Hamlib.
|
|
|
|
A SVN manual is online at http://svnbook.red-bean.com/
|
|
|
|
|
|
1.1.5 Experimental Git repository
|
|
|
|
An experimental Git repository has been set up. As of this moment it is
|
|
only tracking SVN trunk/* as its master branch. Commits are made first to
|
|
SVN (git svn dcommit) and then pushed to this repository to tie the SVN ID
|
|
to the Git commits. The hosting address for cloning is:
|
|
|
|
git://hamlib.git.sourceforge.net/gitroot/hamlib/hamlib
|
|
|
|
Nate, N0NB, will accept patches emailed from Git (they may be posted to the
|
|
hamlib-developer mailing list). Patches should apply to the current SVN
|
|
trunk/* tree. Keep in mind that with the SVN repository being the primary
|
|
repository that things like your local branching information will be lost.
|
|
|
|
|
|
1.2. Requirements
|
|
|
|
Hamlib is entirely developed using GNU tools, under various Linux systems.
|
|
Note that it is not restricted to Linux systems. We welcome anyone who
|
|
has access to a POSIXish system to port Hamlib. Contact us for help.
|
|
|
|
That is, if you want to take part in the development of Hamlib,
|
|
you'll need the following tools. Make sure you have at least the required
|
|
version or you won't even be able to build from the SVN checkout.
|
|
|
|
N.B. The Debian and derivatives (Ubuntu and friends) 'build-essentials'
|
|
package will install a number of tools and minimize the number of packages
|
|
that need to be installed manually.
|
|
|
|
* Gnu C or any C99 compliant compiler # gcc --version
|
|
* Gnu make (or any modern one, BSD okay) # make --version
|
|
* autoconf 2.54 # autoconf --version
|
|
* automake 1.7 # automake --version
|
|
* libtool 2.2.6b # libtool --version
|
|
* svn for connection to hamlib.svn.sourceforge.net
|
|
|
|
N.B. Hamlib no longer supports versions of libtool earlier than 2.2.6b in
|
|
compliance with CVE-2009-3736. If an older version is found, Hamlib will use
|
|
the bundled libtool 2.2.6b instead.
|
|
|
|
Optional, but highly recommended:
|
|
* GNU C++ # g++ --version
|
|
* swig (for bindings) 1.3.14 # swig -version
|
|
* perl devel # h2xs
|
|
* tcl devel # tcltk-depends
|
|
* python devel # python-config
|
|
* libxml2 devel # xml2-config --version
|
|
* libgd2 devel # gdlib-config --version
|
|
* libusb devel # libusb-config --version (not 1.0.0!)
|
|
* RPC devel (libc-dev) # rpcgen --version
|
|
|
|
N.B The libusb package is required for building most of the 'kit' backend.
|
|
The older version is needed, not 1.0.0 or higher. Debian and derivatives
|
|
package libusb 0.1.12 which is what is needed.
|
|
|
|
Documentation:
|
|
* Doxygen
|
|
* DocBook # Deprecated in favor of Doxygen
|
|
|
|
N.B.: Some systems can have several versions of the autotools installed. In
|
|
that case, autoconf may be called "autoconf2.50", autoheader
|
|
"autoheader2.50", and automake "automake-1.7", aclocal "aclocal-1.7" or a
|
|
newer version.
|
|
|
|
IMPORTANT: If autoconf or automake are installed on your system,
|
|
make sure they are matching *at least* the version shown above.
|
|
Some people experience troubles with automake 1.5, if you're one of those,
|
|
it's recommended to upgrade to automake 1.7, which is a lot more stable.
|
|
|
|
|
|
1.3. configure and build stage
|
|
|
|
It is important to note that the SVN repository holds no autogenerated
|
|
files, i.e. configure, config.guess, Makefile, etc. Hence after a fresh
|
|
checkout, you'll have to generate those files.
|
|
|
|
NOTE: Hamlib previously included a script 'autofixer.sh'. It has been
|
|
removed, as hamlib no longer supports the use of libtool 1.x versions in
|
|
compliance with CVE-2009-3736. The autogen.sh script will upgrade the
|
|
bundled libtool source only if a newer version is installed on the system.
|
|
|
|
To proceed, first edit the autogen.sh script, and set appropriately the
|
|
AUTOCONF, AUTOHEADER, AUTOHEADER, and ACLOCAL variables with the required
|
|
versions seen in the previous section (most systems will be fine with the
|
|
default names, only do this if a problem arises).
|
|
|
|
cd hamlib
|
|
sh ./autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
|
|
make
|
|
make install
|
|
|
|
If you don't want the build files cluttering the source directories, do the
|
|
following in the same parent directory of hamlib:
|
|
|
|
mkdir build && cd build
|
|
sh ../hamlib/autogen.sh --disable-static --prefix=/usr/local CFLAGS="-g -O0"
|
|
make
|
|
make install
|
|
|
|
This will keep the binary output files seperate from the source tree and aid
|
|
in development by reducing clutter in the source tree.
|
|
|
|
Once you've run `autogen.sh', make sure you've got some recent config.guess
|
|
and config.sub (needed to guess your system type). Anything of at least
|
|
year 2004 should be fine, unless you run some exotic hardware/software system:
|
|
|
|
./config.guess --version
|
|
./config.sub --version
|
|
|
|
The '--prefix' option to `autogen.sh' is optional. Convention is that
|
|
locally built packages be installed in /usr/local away from distribution
|
|
installed packages. The '--disable-static' and 'CFLAGS="-g -O0"' speeds up
|
|
compilation if you don't plan to use static libraries and can bear less
|
|
optimized binaries while the '-g' option adds debugging info which can be
|
|
changed to -ggdb to generate debugging info for gdb.
|
|
|
|
Additionally, you may want to add the '--with-perl-binding' or
|
|
'--with-python-binding' or '--enable-tcl-binding' if you are interested in
|
|
Swig binding support for those scripting languages (This is a change as of
|
|
1.2.11svn revision 2882 where Swig generated bindings are no longer built by
|
|
default).
|
|
|
|
NOTE: The autogen.sh script has only to be run the first time after a fresh
|
|
checkout or when a Makefile.am or other build file is modified or added.
|
|
|
|
The difference between building as a beta tester and a developer is in the
|
|
'--enable-maintainer-mode' option passed to configure from autogen.sh. This
|
|
option will add new Makefile targets and dependencies and not force a
|
|
rebuild of the Makefiles when make is executed. This is why we recommend
|
|
that beta testers use the daily SVN snapshot from:
|
|
|
|
http://n0nb.users.sourceforge.net
|
|
|
|
For a Tcl build, add this if needed:
|
|
|
|
--with-tcl=/usr/lib/tcl8.2
|
|
|
|
Note: C-shell users may have to run autogen.sh and make through a bourne
|
|
shell instead, or pass "SHELL=bash" as a parameter to make.
|
|
|
|
NOTE! If Hamlib has not been previously installed as a locally built
|
|
package you will need to make sure that `ldconfig' is configured correctly
|
|
and run periodically after `make install'. Most modern distributions have
|
|
an /etc/ld.so.conf.d/ directory where local configuration can be made.
|
|
Later versions of Debian and derivatives have a file named 'libc.conf' in
|
|
this directory. The contents of libc.conf are:
|
|
|
|
# libc default configuration
|
|
/usr/local/lib
|
|
|
|
If your system does not have such a file, one will need to be created and
|
|
then `ldconfig' will need to be run as the root user so that applications
|
|
using the Hamlib libraries can find them.
|
|
|
|
|
|
1.4. Feedback
|
|
|
|
The Hamlib team is very interested to hear from you, how Hamlib builds and
|
|
works on your system, especially on non-Linux or non-PC systems. We are
|
|
trying to make Hamlib as portable as possible. Please report problems to our
|
|
developer mailing list, hamlib-developer@lists.sourceforge.net
|
|
|
|
Patches are welcome too! Just send them to the mailing list. Unified diff
|
|
(diff -u) is the prefered format and patches should apply to the current SVN
|
|
trunk, if possible. If you're patching against an older released version of
|
|
Hamlib, we can take those as well.
|
|
|
|
So far, Hamlib has been tested successfully under the following systems:
|
|
(if your system is not present, please report to the mailing list)
|
|
|
|
* Debian i386 (plus derivatives--Ubuntu, etc.)
|
|
* Debian sid mipsel
|
|
* RedHat i386
|
|
* Linux ppc
|
|
* Slackware i386
|
|
* FreeBSD & NetBSD
|
|
* Solaris 2.6
|
|
* Mac OS X
|
|
* win32: Cygwin, Mingw
|
|
|
|
|
|
2. How to add a new backend
|
|
|
|
The rule is one backend per protocol family.
|
|
Try to share code between rigs of the same family, if applicable.
|
|
|
|
2.1. mkdir mybackend
|
|
Create a new subdir, of the name of the protocol backend.
|
|
NB: the directory MUST be the same as the backend name.
|
|
|
|
2.2. Add <mybackend> to the DIST_SUBDIRS variable in the topdir Makefile.am
|
|
|
|
2.3. Add the backend name to the BACKEND_LIST variable (add to
|
|
ROT_BACKEND_LIST for a new rotor backend) in configure.ac.ltv1
|
|
and configure.ac.ltv2 (configure.ac is deprecated at the moment).
|
|
|
|
2.4. Add "mybackend/Makefile" in the AC_CONFIG_FILES macro at the bottom
|
|
of configure.ac.ltv1 and configure.ac.ltv2 (configure.ac is deprecated
|
|
at the moment)
|
|
|
|
2.5. Create mybackend/Makefile.am, mybackend.c mybackend.h
|
|
Use 'dummy' backend as a template.
|
|
Here are commands for the bourne shell:
|
|
|
|
$ automake mybackend/Makefile
|
|
$ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status
|
|
|
|
make in topdir to rebuild all
|
|
|
|
2.6. Commit your work (developer access to Hamlib SVN required):
|
|
(Please let N0NB know if the commands below are incorrect)
|
|
$ svn add mybackend
|
|
$ cd mybackend
|
|
(The following command might not be necessary)
|
|
$ svn add Makefile.am mybackend.c mybackend.h
|
|
$ svn commit -m "Initial release" Makefile.am mybackend.c mybackend.h
|
|
|
|
Note: The `-m' switch passes a short message to the SVN repository
|
|
upon a commit. If a longer message is desired, do not use the `-m'
|
|
option. The editor specified in the EDITOR or VISUAL environment
|
|
variables will be started where a more detailed message may be
|
|
composed.
|
|
|
|
|
|
3. How to add a new model to an existing backend
|
|
|
|
3.1. make sure there's already a (unique) ID for the model to be added
|
|
in include/hamlib/riglist.h
|
|
|
|
3.2. locate the existing backend
|
|
3.3. Clone the most similar model in the backend
|
|
3.4. Add the new C file to the _SOURCES variable
|
|
of the backend's Makefile.am
|
|
|
|
3.5. Add "extern const struct rig_caps <mymodel>_caps;" to mybackend.h
|
|
3.6. In initrigs_<mybackend> of mybackend.c,
|
|
add "rig_register(&<mymodel>_caps);"
|
|
|
|
3.7. Run `make' if you have dependencies, or the following to regenerate
|
|
the makefile:
|
|
$ automake mybackend/Makefile
|
|
$ CONFIG_HEADERS= CONFIG_LINKS= CONFIG_FILES=mybackend/Makefile ./config.status
|
|
|
|
Run `make' in topdir to rebuild all.
|
|
|
|
3.8. Commit your work (once tests are satisfactory):
|
|
$ svn add mybackend/mymodel.c
|
|
$ svn commit -m "added <mymodel> to <mybackend>" Makefile.am mybackend.c mybackend.h mymodel.c
|
|
|
|
Note: See Note in section 2.6 above.
|
|
|
|
|
|
4. Read README.betatester to test the new backend/model.
|
|
Report to mailing list.
|
|
|
|
|
|
5. Basic functions: set/get_freq, set/get_mode, and set/get_vfo would be a
|
|
good starting point for your new backend.
|
|
|
|
|
|
6. C code examples.
|
|
|
|
A C code snippet to connect to a FT847 and set the frequency of the main VFO
|
|
to 439,700,000 Hz, using FM as the required mode, would look something like
|
|
this. The error checking is removed for simplicity.
|
|
|
|
See tests/testrig.c
|
|
|
|
|
|
7. Where are the GUI's?
|
|
|
|
"Build it and they will come ..."
|
|
|
|
Seriously, I am hoping the API's will provide a solid framework for some
|
|
cool GUI development. I would like to see some GTK or Qt apps that use the
|
|
hamlib API's so they can be used by end users as a nice part of the Ham shack.
|
|
|
|
Starting points (not exhaustive):
|
|
gmfsk, gpredict, grig, klog, kontakt, ktrack, xlog, xtlf
|
|
|
|
|
|
8. Contributing code
|
|
|
|
8.1 License
|
|
|
|
Contributed code to the Hamlib frontend must be released under the LGPL.
|
|
Contributed code to Hamlib backends must follow backend current license.
|
|
Needless to say, the LGPL is the license of choice.
|
|
|
|
End user applications like rigctl, rotctl and RPC daemons should be released
|
|
under the GPL, so any contributed code must follow the rule.
|
|
|
|
8.2 Coding guidelines and style
|
|
|
|
Try to keep current style of existing code. Improvements are welcome though.
|
|
Contributed code should always keep the source base in a compilable state,
|
|
and not regress unless stated otherwise.
|
|
|
|
There's no need to tag the source in a patch with your name in comments
|
|
behind each modification, we already know the culprit from commit logs. :-)
|
|
|
|
Patches should take portability issues into account.
|
|
Keep in mind Hamlib has to run under:
|
|
|
|
* various Linux's
|
|
* NetBSD, FreeBSD
|
|
* MacOS X
|
|
* Windows: MinGW/Cygwin, and VisualC++ support for rig.h
|
|
|
|
Hamlib should also compile with the following common compilers:
|
|
|
|
* gcc-2.9x (most likely deprecated)
|
|
* gcc-3.0 and gcc-3.2+ (nearly deprecated?)
|
|
* gcc-4.x and newer
|
|
* in shared and static
|
|
* C++ compiler against rig.h, riglist.h, rotator.h
|
|
|
|
Portability issues to watch:
|
|
|
|
* little vs. big endian systems (use shifts or adhoc functions)
|
|
* 64 bit int: avoid them in API
|
|
* printf/scanf of 64bit int: use PRIll and SCNll
|
|
* printf/scanf of freq_t: use PRIfreq and SCNfreq
|
|
|
|
8.3 Submitting patches
|
|
|
|
Patches should be in unified format (diff -u), against SVN trunk/ or latest
|
|
release. This format makes it easily readable. The patches are to be sent to
|
|
the hamlib-developer mailing list. If the file is too big, you can send it
|
|
as a compressed attachment.
|
|
|
|
8.3.1 Changelog
|
|
|
|
Caveat: The svn2cl program is used before each release to generate the
|
|
Changelog file so any changes made directly to it WILL BE LOST! Simply
|
|
summarize your changes when the files are committed to SVN or, if providing
|
|
patches to the mailing list, provide a summary so the uploader can include
|
|
it in the commit message which will show in the Changelog.
|
|
|
|
8.4 SVN commit access
|
|
|
|
Generally, volunteers can get access to SourceForge Hamlib SVN upon asking
|
|
one of the project administrators. Sometimes we'll ask you!
|
|
|
|
However, before your start commiting, the project admins would like first to
|
|
have a look at your "style", just to make sure you grok the Hamlib approach
|
|
(c.f. previous section on submitting a patch). Then you'll be able to commit
|
|
by yourself to the backend you have maintainance of. Please follow the rules
|
|
hereunder:
|
|
|
|
* Always keep the SVN trunk repository in a compilable state.
|
|
* Follow the coding guidelines
|
|
* Touching the frontend (files in src/ and include/hamlib) always
|
|
requires discussion beforehand on the hamlib-developer list.
|
|
* Announce on the hamlib-developer list if you're about to do serious
|
|
maintainance work
|
|
|
|
Thanks for contributing and have fun!
|
|
|
|
|
|
|
|
Stephane Fillod f8cfe and The Hamlib Group
|