PyUSB - USB Access from Python
==============================

The PyUSB module provides Python with easy access to the host
machine's Universal Serial Bus (USB) system.  Although not yet
complete, PyUSB does provide a core set of functionality around which
useful applications can be developed.

As with most Python modules, PyUSB's documentation is based on Python
doc strings and can therefore be manipulated by tools such as pydoc.

PyUSB was developed and tested on the Slackware GNU/Linux
distribution and Windows XP Professional. Some testing has been done on Ubuntu,
Mac OS X and FreeBSD.

If you have any question about PyUSB, you can contact the author at
wander (dot) lairson (at) gmail (dot) com.

Installing PyUSB on GNU/Linux Systems
=====================================

These instructions are for Debian-based systems.  Instructions for
other flavors of GNU/Linux should be similar.  

You will first need to install the following packages:

1) python (PyUSB is useless without it)
2) gcc (the compiler, linker, etc.)
3) python-dev (includes header files needed to compile PyUSB)
4) libusb-dev (C library upon which PyUSB is based)

For example, the command

sudo apt-get install python gcc python-dev libusb-dev

should install all these packages on most Debian-based systems with
access to the proper package repositories.

Once the above packages are installed, you can build and install PyUSB
with the command

python setup.py install

run as root from within the same directory as this README file.

Installing PyUSB on Windows
===========================

These instructions are for installing PyUSB in a Cygwin environment.
See the end of this section for notes on installing in a Visual C++
environment.

You will first need to install the following software:

1) Cygwin: A Linux-like environment for Windows available from
http://www.cygwin.com.  Be sure to include GCC and Python with the
Cygwin installation.

2) libusb-win32: a Windows version of the libusb C library available
from http://libusb-win32.sourceforge.net.

From within a Cygwin terminal, copy the libusb.a file from the
libusb-win32 lib/ directory to $(CYGWINDIR)/usr/lib/, and copy the
usb.h file from the libusb-win32 include/ directory to
$(CYGWINDIR)/usr/include/.  You can build and install PyUSB with the
command

python setup.py install

run from within the same directory as this README file.

To build PyUSB using Visual C++, use Python's distutils tool, which
might request that .NET SDK Framework be installed first.
Alternatively, you can use the Visual C++ .NET 2005 project solution
included in the same directory as this README file.  In this case, you
will need to manually change the project settings to include the
Python and libusb-win32 headers and libraries in the Visual C++ path.

USAGE
=====

This Python program is an example of how PyUSB can be used.

#
# Open a device, look at the alternate interfaces, use the device, and
# then close the connection.
#

import usb                 # import the usb module

bus = usb.busses()         # get a list of all available busses

dev = bus[0].devices[0]    # choose the first device on the first bus

handle = dev.open()        # open the device

for alt in dev.configurations[0].interfaces[0]:
    print alt              # look at the alternate settings.

handle.setConfiguration(0) # choose the first configuration

handle.claimInterface(0)   # choose the first interface

### Use the device here. ###

handle.releaseInterface()  # also called automatically on __del__


TODO/ROADMAP
============

- more tests
- more samples
- better documentation
- utility functions to find devices


ACKNOWLEDGEMENTS
================

Thanks to the following people for their help and contributions to the
PyUSB project.  Where possible, there contributions are noted in the
source code. 

- Damian Staniforth
- Brenno Diegoli
- Israel Florentino
- Xiaofan Chen
- Mario Olimpio de Menezes
- Renato Manzan
- Ray Schumacher
- Mark Rages
- James Barabas
- Andrew Rogers
- Juha Torkkel
- Josh Lifton
- David Merrill
- Srikanth Jandhyala
- Alexander Krause
- Yael Maguire
- Lucio Torre
- Simeon Miteff

PS: this great README file was written by Josh Lifton... :-)