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 use the PyUSB mailing list
hosted at SourceForge. In the PyUSB website (http://pyusb.sourceforge.net)
you can find instructions to subscribe to the mailing list.

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.

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(1) # 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
================

I used to put here the name of all people who have contributed to PyUSB.
(Un)fortunately, the list is getting too long to list here, and I am
affraied of forgetting the name of someone, so I decided to not list
them individually here, but say Thanks to all of you in a bunch, so..

THANK YOU VERY MUCH!

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