USPP Library

		 Universal Serial Port Python Library	

              Copyright 2006 Isaac Barona <ibarona@gmail.com>


Contents
--------
 1. Introduction
 2. Motivation
 3. Where can I find it
 4. Features
 5. Pre-requisites
 6. Usage and documentation
 7. Where does it work
 8. Known problems
 9. To-do list
10. Porting to other platforms 
11. Licence
12. Author 
13. Version 


1. Introduction
---------------

USPP Library is a multi-platform Python module to access serial ports. At the
moment, it only works in Windows, Linux and MacOS but as it is written entirely
in Python (doesn't wrap any C/C++ library) I hope you can extend it to support
any other platforms. 


2. Motivation
-------------

I like very much to make electronic widgets with microcontrollers, specially
those that can be connected to the computer to send and receive data.
Some months ago, I discovered Python and inmediatelly liked it a lot. 
I started playing with it and saw that I could use it to make prototypes of
comunication protocols between computer and microcontrollers really
fast and easily than using C. At the same time, I was interested in
working over different platforms.
I started looking for Python modules to access serial port and I found
the following projects:

	* win32comport_demo from the win32 extension module
	* win32comm module of wheineman@uconect.net
	* Sio Module of Roger Rurnham (rburnham@cri-inc.com)
	* pyxal (Python X10 Abstraction Layer) of Les Smithson 
	  (lsmithson@open-networks.co.uk)

but they were not multi-platform, were just a wrap of propietary libraries or 
were just simple examples of serial port access.
For these reasons and also for learning more Python, I decided to start
this project. Of course, I have used all this projects as reference to
my module and so, I want to thanks the authors for their excellent work and
for allowing us to study the code.
I hope you enjoy using the uspp module as much as I am enjoying doing it.


3. Where can I find it
----------------------

You may find it at:
 * http://ibarona.googlepages.com/uspp
 * http://www.telefonica.net/web/babur

as a tar.gz package or as a winzip file.


4. Features
-----------

This module has the following features:

	- hight level access to serial port under several platforms.
	- autodetects the platform in which it is working and exports
	  the correct classes for that platform.
	- object oriented approach.
	- file object semantic operations over the ports.
	- allows using the serial port with different speeds and
	  characteristics.
	- RS-232 and RS-485 modes (now only RS-232). In RS-485 mode
	  the communication is half-duplex and uses the RTS line
	  to control the direction of the transference.
	- blocking, non-blocking or configurable timeout reads.


5. Prerequisites
----------------

You need the following to use the library:

	- Python 2.1 or better
	- In windows you need the win32 extension modules


6. Usage and documentation
--------------------------

You only have to import in your program the uspp module and automatically
it loads the correct classes for the platform in which you are running
the program.

First of all you have to create a SerialPort object with the settings you
want. If a SerialPortException is not generated then you just can
use the read and write methods of the object to read and write to
the serial port.

Example:

>>> from uspp import *
>>> tty=SerialPort("COM2", 1000, 9600)  
>>> # Opens COM2 at 9600 bps and with a read timeout of 1 second.
>>> tty.write("a")  # Writes a character to the COM2 port
>>> # Now suppose we receive the string "abc"
>>> tty.inWaiting()
3
>>> tty.read()
'a'
>>> tty.inWaiting()
2
>>> tty.read(2)
'bc'


Documentation of the different classes and methods can be found on
uspp module docstring.


7. Where does it work
---------------------

The library has been tested in  Windows 95, Windows XP and Windows 2000  
machines with Python 2.1+ and in a Linux (2.0.34 kernel) machine with 
Python 2.1+.


8. Known problems
-----------------




9. To-do list
-------------

This is the to-do list:

	- implement RS-485 mode.
	- port the library to other platforms so that it can be really
	  multi-platform.


10. Porting to other platforms
-----------------------------

If you want to port the library to other platforms you only have to follow
these steps:

* Create a new python file called SerialPort_XXXX.py in which you 
implement the same public classes and methods found in the SerialPort_win
and SerialPort_linux modules.
* Append the new platform to the uspp.py file.


11. Licence
----------

This code is released under the "LGPL" that can be found in
http://www.gnu.org/copyleft/lesser.html or in the lesser.txt file that 
is with the library.
If you use this software, I'd like to know about it.


12. Author
---------

This library has been created by Isaac Barona Martinez <ibarona@gmail.com>.


13. Version
----------

0.1 - 09/01/2001 (September 2001)
0.2 - 05/13/2003
1.0 - 02/24/2006