Hamlib/README.betatester

* Why does Hamlib need beta-testers?

Hamlib is developed by a team of enthusiasts around the world, for fun,
much in the spirit of hamradio. (Note that it is not restricted for ham
usage only). There are a great deal of protocols and rigs around the world
developers may not own. However, protocols may be available, so backends
can be implemented, but cannot always be tested by developers. That's where 
beta-testers are so precious. On top of that, I've been told that there's 
no such sure thing like bug free code. 

Feedback and improvement requests are also valuable.


* Okay, you volunteer as beta-tester, how to proceed?

First of all, you can start testing official releases. They are easier to
test because they come in precompiled and packaged (.rpm, .deb) but they
have the drawback of being older than the CVS repository. Reports from these
versions are still very appreciated, on hamlib-developer@lists.sourceforge.net
mailing list.

However, the development of Hamlib is still very active, so it's better to
test from the latest CVS version of the code.  And, depending on feedback you
make, developers can commit a fix, so you can try out the change soon after,
without waiting for the next official version.

So to proceed, you will have first to obtain either a snapshot or a check out
of the latest sources from cvs, then rebuild the Hamlib package and finally
test it with your rig. Don't worry, it's much simpler than how it looks,
despite the size of the package.

Pre-requisite:
 - some kind of internet access
 - POSIXish compiler toolchain (gcc, GNU Autotools, Perl, etc., 
				see README.developer)

 
So here we go:

* snapshots:

Download the latest snapshot from http://www.hamlib.org/bleeding-edge/
You'll find tar balls with names like hamlib-1.2.6cvs-20061107.tar.gz,
i.e. a check out made 07 Nov 2006, ready for building.

If you cannot afford the cvs checkout, and want a more recent snapshot,
just ask for it on the hamlib-developer mailing list.

* cvs checkout:

Please read the begining of README.developer file, especially about how to
obtain a cvs checkout, what are the required tools versions (very important
or make won't even work!), and how to use autogen.sh.

* build

Reading the INSTALL file in top directory will explain in more detail how
to do the following commands. 

	./configure --disable-static --prefix=/some/where
	make
	make install

The prefix argument is optional.  Convention is that local packages be placed
in /usr/local away from distribution installed packages and this is the default
location for the snapshots.  The --disable-static option speeds up compilation
if you don't plan to use static libraries.


* Structure

For the brave who want to peruse the contents, here are what all the
subdirectories are for (these are just a sample as more are added):

alinco,aor,icom,
jrc,kachina,kenwood,
pcr,tentec,uniden,
winradio,yaesu:		rig backends
rpcrig:			special networked rig backend (through RPC)
rpcrot:        		special networked rotator backend (through RPC)
easycomm:		rotator backends
dummy:			virtual dummy rig and rotator, for developer's use.
c++,tcl,kylix:		C++, tcl, and Kylix bindings
lib:			library for functions missing on your system
libltdl:		wrapper for shared module loader
debian:			debian package scripts
doc:			documentation base and scripts to extract from src
include/hamlib:		exported header files go here
include:		non-distributed header files go there
src:			Hamlib frontend source directory
tests:			rigctl/rotctl and various C programs for testing


* testing Hamlib

Don't attempt to test Hamlib from source directory unless you're a developer
and you understand what are the side effects of *not* installing freshly
generated objects (basically having to mess with LD_LIBRARY_PATH and .libs).

So here we go. First of all, identify your rig model id.  Make sure 
/some/where/bin is in your PATH, rigctl has to be reachable. Run "rigctl -l"
to get a list of rigs supported by Hamlib.

If you cannot find yours in the list, please report to the hamlib-developer
mailing list. The protocol manual and rig specifications may help a lot.

You found your rig's ID?  Good!  You're almost ready to use rigctl.
Have a quick look at its manual page:

	man rigctl
or:
	man -M /some/where/man rigctl
or simply:
	rigctl --help

Let's say you own an Icom IC-756:

	rigctl -vvvvv -r /dev/ttyS0 -m 326

The -vvvvv is very important since this will increase verbosity, and give
precious traces to developpers if something goes wrong. At this level, 
the protocol data exchanged will also be dumped to the screen.

Unless some problem shows up, you should be presented with a menu
like "Rig command: ". Enter "?" followed by return to have the list 
of available commands. 'Q' or 'q' quits rigctl immediately.

Most wanted functions to be tested are:
'_'	get misc information on the rig
'f'	get frequency
'F'	set frequency, in Hz
'm'	get mode
'M'	set mode (AM,FM,CW,USB,etc. and passband width in Hz)
'v'	get vfo
'V'	set vfo (VFOA, VFOB, etc.)

f,F     get_freq/set_freq       try various (<1MHz, <30Mhz and >1GHz)
v,V     get_vfo/set_vfo         VFOA, VFOB
m,M     get_mode/set_mode       FM, USB, LSB, CW, WFM, etc.
                                passband is in Hz (pass 0 for default)
G       vfo_op                  UP, DOWN
_       get_info                should give remote Id and firmware vers

NB: some functions may not be implemented in the backend or simply not
available on this rig.

When reporting to hamlib-developer mailing list, please include traces and
also comments to tell developers if the action performed correctly on the rig.

Tip: traces can be hard to cut and paste sometimes. In that case,
	there's a handy tool for you:  script(1). It will make
	a typescript of everything printed on your terminal.

	$ script my_rig_traces.txt
	Script started, file is my_rig_traces.txt
	$ rigctl -vvvvv -r /dev/ttyS0 -m 326
	rig:rig_init called
	rig: loading backend icom
	icom: _init called
	rig_register (309)
	rig_register (326)
	rig:rig_open called
	Opened rig model 326, 'IC-756'

	Rig command: q
	rig:rig_close called
	rig:rig_cleanup called
	$ exit
	exit
	Script done, file is my_rig_traces.txt
	$

And then send my_rig_traces.txt to the hamlib-developer mailing list.


Okay fellows, test as much as you can, in the weirdest situations if
possible. There is a special prize for those who find 'Segmentation fault'
and other nasty bugs.

Needless to say, patches are also very welcome :-)


Stephane - F8CFE and The Hamlib Group