Hamlib/README.developer

[FIXME: this doc is out dated! --SF 03/20/01]

hamlib - (C) Frank Singleton 2000 (vk3fcs@ix.netcom.com)

Take a look at http://sourceforge.net/projects/hamlib/
Here you will find a mail list, and  the latest CVS releases.


See README for frontend/backend outline.

General Guidelines.
-------------------

0. The top level directory looks like thus.

[frank@kirk hamlib]$ tree -d
.
|-- CVS
|-- common
|   `-- CVS
|-- ft1000
|   `-- CVS
|-- ft1000d
|   `-- CVS
|-- ft747
|   |-- CVS
|   |-- include
|   |   `-- CVS
|   |-- lib
|   |   `-- CVS
|   `-- test
|       `-- CVS
|-- ft840
|   `-- CVS
|-- ft847
|   |-- CVS
|   |-- include
|   |   `-- CVS
|   |-- lib
|   |   `-- CVS
|   `-- test
|       `-- CVS
|-- ft920
|   `-- CVS
|-- ts570d
|   `-- CVS
|-- ts870s
|   `-- CVS
`-- ts950
    `-- CVS    

1.Every new shared lib should be created autonomously
  within its own directory. eg ft747/ for libft747.so

2. Every lib should have the following structure
[frank@kirk ft747]$ tree

.
|-- CVS
|   |-- Entries
|   |-- Entries.Log
|   |-- Repository
|   `-- Root
|-- Makefile
|-- README.ft747
|-- TODO.ft747
|-- ft747.c
|-- ft747.h
|-- include
|   `-- CVS
|       |-- Entries
|       |-- Repository
|       `-- Root
|-- lib
|   `-- CVS
|       |-- Entries
|       |-- Repository
|       `-- Root
`-- test
    |-- CVS
    |   |-- Entries
    |   |-- Repository
    |   `-- Root
    |-- Makefile
    |-- testlibft747.c
    `-- testlibft747.h

3. Use the ft847 tree for examples of coding style. If there
   are any glaring problems,let me know..

4. The "test" directory should contain source code of the
   form testlibXXXX.[ch]

5. The "test" directory should build a test suite that
   excercises the API you are implementing.

6. libXXXX.so should be built to allow TX (PTT) to be disabled
   if required. See ft847.[ch] for how this is done.

7. The Makefile for the test suite should have a target like
   this to allow testing the API.

	# run test program in local directory
 
	.PHONY: runtest
	runtest:
        	(LD_LIBRARY_PATH="../lib" ./testlibft747 )  


8. You may wish to make an example out from your test suite
   program available as follows.

	make runtest > RESULT.example

9. Your header file (eg ft747.h, ft847.h etc) documents
   your backend API, so please describe it so others can understand.
   If this cannot be done, I may consider an "API.xxx" that
   decsribes the API (eg: API.ft847 )

10. C code examples.
    An example piece of code may  uses the ft847 API could
    look like this..

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 testrig.c for an example.

<snip>

	#define SERIAL_PORT "/dev/ttyS1"
...

	my_rig = rig_init(RIG_MODEL_FT847);
	strncpy(my_rig->state.rig_path,SERIAL_PORT,FILPATHLEN);

	/*
	 * Example of setting rig Main VFO to 439.700 Mhz FM -- FS
	 * and some error checking on the return code.
	 */

	retcode = rig_set_vfo(my_rig, RIG_VFO_MAIN);

	if (retcode != RIG_OK ) {
	  printf("rig_set_vfo: error = %i \n", retcode);
	}

	rig_set_freq(my_rig, 439700000); /* cq de vk3fcs */

	if (retcode != RIG_OK ) {
	  printf("rig_set_freq: error = %i \n", retcode);
	} 

	rig_set_mode(my_rig, RIG_MODE_FM);

	if (retcode != RIG_OK ) {
	  printf("rig_get_mode: error = %i \n", retcode);
	} 

<snip>


11. 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 apps that use the hamlib API's
   so they can be used by end users as a nice part of the
   Ham shack.



Frank Singleton vk3fcs/km5ws