README for pyifp


-------
License
-------

Copyright (C) James Evans, 2005; <jaevans@users.sourceforge.net>

This driver is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; only version 2 of the License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License in the file
"COPYING"; if not, write to the Free Software Foundation, Inc., 59 Temple Place
- Suite 330, Boston, MA  02111-1307, USA.


-------
Summary
-------

The pyifp module is a wrapper around the libifp project 
(http://ifp-driver.sourceforge.net/libifp/) designed to make it easy to write 
python based programs to manage the iFP class of devices.

pyifp is currently under development and is not guaranteed in any way.


------------
Requirements
------------

- libifp and the related development files
- libusb and development files (tested with version 0.1.8)
- gcc (tested with 3.4.2 on Fedora Core 3)
- python and development libraries (tested with 2.3.4)


------------------
Build Instructions
------------------

Build the extension in place:
$ tar zxvf pyifp-0.2.2.tar.gz
$ cd pyifp-0.2.2
$ python setup.py build
$ export PYTHONPATH=`pwd`/build/lib.linux-i686-2.3


Create installable RPM package:

$ tar zxvf pyifp-0.2.2.tar.gz
$ cd pyifp-0.2.2
$ python setup.py bdist_rpm
$ rpm -ihv dist/pyifp-0.2.2-1.i386.rpm


-----
Usage
-----

QuickStart:

import ifp
my_ifp = ifp.iFP()
my_ifp.init_device()


The docs in the ifp class are the best source of information for the library.
All interaction with the iFP device goes though the iFP class. Any errors from
the iFP are translated to python exceptions.

NOTE: Callback functions passed to listdir, upload, or download must have the
correct signature, otherwise it will crash the python interpreter. Anyone have
any idea on how to check the signature of the callback?


---------------------
Extension Description
----------------------

Pyifp is organized into three layers. The lowest layer is a SWIG wrapper around
libifp to provide python access to the majority of the libifp functions. Two 
classes of functions needed helpers written in c; those that expect the client 
to provide a buffer and a size to return information (ifp_model,ifp_device_info,
and the radio presets), and those that require a callback to a python function.
This wrapper layer is compiled into a shared object that can be loaded by the
python interpreter.
The next layer is the ifp_core python module. This layer is generated by SWIG
and provides python access to the functions in the shared object.

The top layer consists of the ifp module. This module wraps a python object
around the ifp_core. The object maintains the device handle and translates call
formats to what the lower layers expect. This allows a more "pythonic" interface
to the iFP device. A number of functions are added at this layer to make it 
easier to use some functions.


----
TODO
----

Test the rest of the methods of ifp. The methods in the ifp module that contain
docstrings have been tested.

Better error checking. This needs to be done both in the ifp module and the 
wrappers. There is no range checking on the callsigns or frequency of the 
presets. Checking the signature of the python callback functions would be useful


------
Thanks
------

I'd like to thank Geoff Oakham for creating the libifp library that makes it so
easy to interface with the iFP devices.

Special thanks to Joe Wreschnig for his work in cleaning up and standardizing
the API and implementing much new and improved functionality.

I'd also like to thank my wife Heather for letting me play with HER iRiver (as 
she so often reminds me) and supporting me releasing the extension. And for
putting up with me staying up "just a little longer" to put the software 
together.
