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).
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 latest cvs version of the code.
And depending on feedback you made, developers can commit a fix
of a patch, so you can try out the change right 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 what it looks, despite the size of the package.

Pre-requisite:
 - some kind of internet access
 - POSIXish compiler toolchain

 
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.1.4-cvs-021021.tar.gz,
i.e. a check out made 21-10-02, 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 how
to obtain a cvs checkout, what are the required tools versions
(very important or make won't even work!), and how to deal with 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 optionnal. The --disable-static 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):

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
developper and you understand what are the side effect 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. Protocol manual and rig specification may
help a lot.

You found your id? good! You're almost ready to use rigctl.
Have a quick look at its manual page:
	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.

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 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 :-)


Oct 29, 2002
Stephane - F8CFE