# Installing and Using the ioLabs Python library #

Quick answer:

* Install requirements (see below)
* Run `python setup.py install` to copy files to your `PYTHONPATH`

The library consists of:

* `ioLabs.py`
* `hid/__init__.py`
* `hid/_comming.py`
* `hid/osx.py`
* `hid/win32.py`
* `psyscopex.py`

To start using the library (once you have met the requirements listed below),
copy and `ioLabs.py`, `psyscopex.py` and the `hid` directory to somewhere on your `PYTHONPATH`.
For simplicity this can be the directory that you will be using for your project.

`ioLabs.py` is the USBBox specific code and this is what you will be using for the most part.

`hid` contains the code for the the general purpose Python HID driver and you will most likely
not need to deal with it directly - however it is used by the ioLabs module.  `hid` contains code
for OS X and Windows and will dynamically load the correct module for the OS when `hid` is imported.

`psyscopex.py` is a compatibility layer for people using PsyScopeX, as we cannot use the standard 
hid library when PsyScopeX's kernel extension is installed.

## Requirements ##

* Python 2.5+ (includes ctypes)

or

* Python 2.3.5+
* C Compiler (to compile ctypes)
* ctypes

## OS X 10.5 (Leopard) ##

Leopard ships with Python 2.5 and ctypes so no additional installation is required.

## OS X 10.4 Python 2.5 ##

1. Go to http://python.org/download/
2. Find latest version for OS X (2.5.1 at time of writing) and download .dmg
3. Open .dmg file
4. Run `MacPython.mpkg` package file
5. Enter admin password when prompted

## OS X 10.4 with Stock Python (2.3.5) ##

Need to install ctypes (requires the developer tools for a C compiler):

1. Download and install `easy_install`
 1. visit: http://peak.telecommunity.com/DevCenter/EasyInstall
 2. download: http://peak.telecommunity.com/dist/ez_setup.py
 3. run `sudo python ez_setup.py` to install
 4. if you do not have the `easy_install` command you may need to
    alter your path to include
    `/System/Library/Frameworks/Python.framework/Versions/2.3/bin`
    (where the `easy_install` script resides) or use the full path name
    when invoking e.g. 
    `/System/Library/Frameworks/Python.framework/Versions/2.3/bin/easy_install`
2. Use `easy_install` to install ctypes
 1. `sudo easy_install ctypes` (may take some time, as it has to compile everything)

## Windows XP ##

1. Go to http://python.org/download/
2. Find latest version for Windows Install Python 2.5 (2.5.1 at time of writing) and download .msi
3. Run .msi and follow installer

## Tests ##

To run unit tests for the library use `nosetests` from http://code.google.com/p/python-nose/


# USB Button Box Python API #

To get started simply import the ioLabs module and create a USBBox instance:

    from ioLabs import USBBox
    
    usbbox=USBBox()

If the physical box is not connected (or cannot be detected for some reason) an 
exception will be raised when you create this USBBox instance.

## USBBox structure ##

See the accompanying `rbox_structure` document about the high-level structure of the box.
This document specified the more object oriented API for accessing the USBBox.

## Sending Commands ##

Once you have the USBBox instance you can send commands to the USBBox.  Commands are
sent via the `commands` member variable and are named after IDs specified in the
boxes manual, only in lower case.  e.g.

    usbbox.commands.resrtc() # send RESRTC (reset realtime clock) command
    usbbox.commands.p2set(0x00) # send P2SET with value 0 (should turn on LEDs)
    usbbox.commands.dirset(1,0,0) # enable loopback mode (button presses turn on LED)

## Receiving reports ##

You can register call-back functions on the `commands` object to receive notification
about reports received from the box.  The actual reports are delivered asynchronously,
but to avoid thread safety issues they are stored on a queue until `process_received_reports`
is called.  As most events are time-stamped they can be processed as needed.

To register a call-back and have it called whenever a key is pressed one can doing something
like:

    import time
    from ioLabs import USBBox, REPORT
    # REPORT contains the report IDs
    
    usbbox=USBBox()
    def mycallback(report):
        print "got a report: %s" % report
    # register callback just for KEYDN reports
    usbbox.commands.add_callback(REPORT.KEYDN,mycallback)
    
    while True:
        usbbox.process_received_reports()
        time.sleep(0.1)

Calling `process_received_reports` in this way ensures that out call-back will be called on the
same thread as the rest of the program - avoiding any nasty surprises with asynchronous data
access.  This should also make it easier for integrating with GUI toolkits.

## Recording reports ##

Instead of registering call-backs one can instead opt to have commands sent to a file, using
the `start_recording` method on the USBBox object.  This takes a list of report IDs to record
and a file to output them to:

    import time
    from ioLabs import USBBox, REPORT

    usbbox=USBBox()
    outfile=open('output.txt')
    # record all events
    usbbox.start_recording(REPORT.ALL_IDS(),outfile)
    time.sleep(30)
    usbbox.stop_recording()
    # output.txt should now contain last 30 seconds or so events

## Miscellaneous ##

The underlying HID device for the USB Button Box is stored in `device` on the USBBox instance.
It can be accessed to manually send commands to the device using it's `set_report(report_data)`
command - simply passing a string of the bytes that should be sent in the report.