[Hamlib-developer] IC-756, XBasic, and beta-testing

[Stephane F. <f4...@fr...>]

Hi John!

I've Cc: my reply to the hamlib-developer mailing list. So information
circulates. And you're not the first one to use Hamlib with an IC-756.

On Wed, Jan 23, 2002, John Simmons wrote:
> Thanks for the help on getting rigctl running.
> I did not find any read me file that explained how to get
> rigctl started and one of the mistakes that I was making was
> entering -c 50 when it should have been -c 80 dec to
> indicate 50 hex.

You're right, nowhere it was mentionned it is decimal. This is now fixed
in the cvs repository: rigctl(1) man page mentions it, and rigctl now
accepts -c 80 or -c 0x50, whichever you prefer.

>  I have look at the CVS and it is a bit confusing as to just
> what file I will need to down load to compile  the  current
> developement version.    I am not familiar with compiling
> such large program from scrach.    

Okay, this is good to say what's missing. I tend to overlook some bits,
because I spend maybe too much time on the code.

> When I tryed running some of the commands such as get_mode
> command "m" the order of the command line does not seem to
> match what I am seeing in my manual. With the rig set to
> USB.
> Rig command: m
> TX 7 bytes
> 0000     ff fe fe 50 e0 04 fd   ...P...
> RX 7 bytes
> 0000     ff fe fe 50 e0 04 fd   ...P...
> RX 6 bytes
> 0000     fe fe e0 50 04 01      ...P..
> RX 1 bytes
> 0000     01     .
> RX 1 bytes
> 0000     fd     .
> Mode: 4
> Passband: 2400
>  My manual says that the command line should be 
> 'fe fe e0 50 Cn Sc data fd
> e0 is the Controller's address.
> 50hex is the IC-756 address
> The reply from the rig was 'fe fe e0 50 04 01 01 fd'
>  I a assuming that 'e0' is the command and '04' is the sub
> command.   Is sub command '04' a undocument command?

The first reply from the rig is actually exactly what Hamlib sent. This is
because according to the CI-V spec, the TXD and RXD signals are
tighed together. So you have to expect this kind of echo.
Now, the 'fe fe e0 50 04 01 01 fd' break down into:

  fe fe: preamble
  e0: destination address, i.e. the controller
  50: send address, i.e. the transceiver
  04: "Cn" read display mode, here the response
      there's no "Sc" sub command
  01 01: the data area, here USB, normal operation

What is confusing is the ouput of rigctl from version 1.1.2.
Newer version now displays "USB" instead of the Hamlib internal 
constant 4, and passband width is simply 2400 kHz.

>  Using the M: set_mode also gives starange results.
> 
> Rig command: M
> Mode: 01
> Passband: 8000
> TX 8 bytes
> 0000     ff fe fe 50 e0 06 02 fd        ...P....
> RX 8 bytes
> 0000     ff fe fe 50 e0 06 02 fd        ...P....
> RX 6 bytes
> 0000     fe fe e0 50 fb fd      ...P..
> The command '06' and '02' would be correct to set the rig in
> AM mode which it does and the 8000 sets the passband to 15k
> (no AM filter)  The '01' command should set the rig to USB.

Sorry for the lack of documention which lead you to confusion.
First of all, rigctl is tool that knows absolutly nothing about 
a rig protocol and the specific values in use by this protocol.
Historically, rigctl was just to a unitary test tool for Hamlib functions.
So, to make it quick to develop, arguments were read as integer in
internal representation of Hamlib. Hence, mode 01 is actually RIG_MODE_AM,
as defined in include/hamlib/rig.h. That's why the rig was set to AM.
And passband is expressed in Hz. In that case, it looks like Hamlib
decided to select closest passband.

This was version 1.1.2. The code in the cvs rep now accepts modes as "AM",
"USB", etc. instead of obscure numbers only known by developers...

> This may have been fixed in later versions or this command
> structure may be based on the 756pro or 756proII.   If it
> would help I can copy the command table for the 756 and send
> it as a attachment.

This might help anyway, to check if the icom backend supports all the
features of your 756.

> On XBasic i belive that if I 'Include' the lib as external
> files in the prolog of the program I can make calls to the
> lib files.   The question is if I make the calls does the
> data have to be entered as BCD code as stated in the manual
> or do the lib's make the conversion for dec. or hex?   I

Think simple, think easy. The whole philosophy behind Hamlib is to hide
the gory details of protocols to the library user. Forgot about BCD code
and such, this is all taken care of in the icom/ subdirectoy.
Keep in mind that any application using Hamlib becomes able to control
*any* rig supported by Hamlib. Some rigs have BCD code, some others use an
ASCII protocol. Whatever, this is all hidden to the application, which has
better to concentrate on by the way.
So how do I specify mode AM for example when changing mode? would you ask.
This is achieved through constants, defined in rig.h include file.
Here it is in C:

	rig_set_mode(my_rig, RIG_VFO_CURR, RIG_MODE_AM, 15000);

my_rig is a handle, obtained after rig_init and rig_open.
RIG_VFO_CURR is a constant indicating you want the mode set is to take
	place on the current VFO.
RIG_MODE_AM an interger constant for AM mode.
15000 is an integer specifying a passband of 15kHz.

> guess I am going to have to learn to read C a little better
> in order the understand the structure of the calls and what
> the calls are looking for.   I need a hint on what files i
> should 'include' to start up the serial ports and get the
> rig initalized.  Also what lib's should be included.
> Xbasic has it own io , math Gui and drawing  lib.

Hamlib is using the libc io and math lib, and is standalone.
However, there's no Gui in Hamlib, because this is the upper
level/application duty.
As I told you, I don't know how Xbasic binding works. However,
you'll most probably have to #include <hamlib/rig.h>  somewhere,
and link against libhamlib-1.1.3.so.0

There's a very basic C program using Hamlib in the tests/testrig.c 
of the source package. Once you get the logic, you will find more calls in
include/hamlib/rig.h or from http://hamlib.sf.net in manual section.

> I am guessing I  will need to be able to setup and compile
> the current version of the file to get all the current
> upgrades to the code.   The zip and rpm file dated the in
> Sept. may not be current enough.   Any help such as a list
> of file and which make , make install file or possibly point
> me in the direction of the proper Readme file.   

Ah, another thing missing. So here it is. 
Please feel free to comment on it, fix english mistakes, add or tell
me what's still missing or not clear, and tips of yours.
I'll then turn it later into a 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's a great deal of protocols and rigs around the
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
ham...@li... 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 check out 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:
 - live internet access
 - cvs
 - gcc toolchain
 
So here we go:

* anonymous (pserver) cvs checkout:

  cvs -d:pserver:ano...@cv...:/cvsroot/hamlib login
  cvs -z3 -d:pserver:ano...@cv...:/cvsroot/hamlib co hamlib

When prompted for a password for anonymous, simply press the Enter key.
The check out has only to be done the first time. In the case you don't
have cvs access through your firewall, but http gets through, daily
cvs snapshots are available. The previous commands can be replaced
by the following:

	wget http://cvs.sf.net/cvstarballs/hamlib-cvsroot.tar.gz
	tar zxvf hamlib-cvsroot.tar.gz
	mv hamlib hroot
	export CVSROOT=`pwd`/hroot
	cvs co hamlib

After the initial retrieval, whenever you want to update your local
version, issue the following command in the root directory of hamlib.

  cvs -z3 -d:pserver:ano...@cv...:/cvsroot/hamlib update -d

Tip: 
I use the following alias:
alias hcvs='cvs -z3  -d:pserver:ano...@cv...:/cvsroot/hamlib'
This way, I just have to do "hcvs update -d" whenever I want to keep to
date.

For the braves who want to peruse the contents, here's what all the
subdirectories are for:

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:		exported header files go there
src:			Hamlib frontend source directory
tests:			rigctl/rotctl and various C programs for testing

* build
Reading the INSTALL file in top directory will explain you more verbosely
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.

* 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.

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 -vvvv -r /dev/ttyS0 -m 326

The -vvvv 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.)

NB: some functions may not be implemented in the backend of
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 -vvvv -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.


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, patchs are also very welcome :-)


>[snip]  By the way I have the Kenwood TS 790A
> also.  I have not checked into that but if I am successful
> with this project I would probably try to get something
> going on the Kenwood.   I have the manuals and the manual on
> the serial interface for the kenwood but since the rig was
> purchased used I don't know if the serial option was
> installed.      

I just commited the TS-790 description to cvs. So if you have the IF-232
cable or box, you're ready to play with it!
BTW, I would be very interrested to have a copy of the manual on the
serial interface for the kenwood, specially the protocol spec.
Can you scan it and send files attached to f4...@fr...? Thanks.

Cheers,
Stephane F8CFE