Skip to content

Commit da97d9f

Browse files
author
Lincoln Smith
committed
Uploaded the latest version (3.1) of the python library to the beanstalk repository.
git-svn-id: http://iolab.svn.beanstalkapp.com/iolab/trunk/python@2 71f8c1b2-6f87-4638-bd5e-d7580a58d9d7
0 parents  commit da97d9f

51 files changed

Lines changed: 13814 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎INSTALL.txt‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Installing and Using the ioLabs Python library #
2+
3+
The library consists of:
4+
5+
* `ioLabs.py`
6+
* `hid/__init__.py`
7+
* `hid/_comming.py`
8+
* `hid/osx.py`
9+
* `hid/win32.py`
10+
11+
To start using the library (once you have met the requirements listed below),
12+
copy and `ioLabs.py` and the `hid` directory to somewhere on your `PYTHONPATH`.
13+
For simplicity this can be the directory that you will be using for your project.
14+
15+
`ioLabs.py` is the USBBox specific code and this is what you will be using for the most part.
16+
17+
`hid` contains the code for the the general purpose Python HID driver and you will most likely
18+
not need to deal with it directly - however it is used by the ioLabs module. `hid` contains code
19+
for OS X and Windows and will dynamically load the correct module for the OS when `hid` is imported.
20+
21+
## Requirements ##
22+
23+
* Python 2.5+ (includes ctypes)
24+
25+
or
26+
27+
* Python 2.3.5+
28+
* C Compiler (to compile ctypes)
29+
* ctypes
30+
31+
## OS X 10.4 Python 2.5 ##
32+
33+
1. Go to http://python.org/download/
34+
2. Find latest version for OS X (2.5.1 at time of writing) and download .dmg
35+
3. Open .dmg file
36+
4. Run `MacPython.mpkg` package file
37+
5. Enter admin password when prompted
38+
39+
## OS X 10.4 with Stock Python (2.3.5) ##
40+
41+
Need to install ctypes (requires the developer tools for a C compiler):
42+
43+
1. Download and install `easy_install`
44+
1. visit: http://peak.telecommunity.com/DevCenter/EasyInstall
45+
2. download: http://peak.telecommunity.com/dist/ez_setup.py
46+
3. run `sudo python ez_setup.py` to install
47+
4. if you do not have the `easy_install` command you may need to
48+
alter your path to include
49+
`/System/Library/Frameworks/Python.framework/Versions/2.3/bin`
50+
(where the `easy_install` script resides) or use the full path name
51+
when invoking e.g.
52+
`/System/Library/Frameworks/Python.framework/Versions/2.3/bin/easy_install`
53+
2. Use `easy_install` to install ctypes
54+
1. `sudo easy_install ctypes` (may take some time, as it has to compile everything)
55+
56+
## Windows XP ##
57+
58+
1. Go to http://python.org/download/
59+
2. Find latest version for Windows Install Python 2.5 (2.5.1 at time of writing) and download .msi
60+
3. Run .msi and follow installer
61+

‎README.txt‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# USB Button Box Python API #
2+
3+
To get started simply import the ioLabs module and create a USBBox instance:
4+
5+
from ioLabs import USBBox
6+
7+
usbbox=USBBox()
8+
9+
If the physical box is not connected (or cannot be detected for some reason) an
10+
exception will be raised when you create this USBBox instance.
11+
12+
## USBBox structure ##
13+
14+
See the accompanying `rbox_structure` document about the high-level structure of the box.
15+
This document specified the more object oriented API for accessing the USBBox.
16+
17+
## Sending Commands ##
18+
19+
Once you have the USBBox instance you can send commands to the USBBox. Commands are
20+
sent via the `commands` member variable and are named after IDs specified in the
21+
boxes manual, only in lower case. e.g.
22+
23+
usbbox.commands.resrtc() # send RESRTC (reset realtime clock) command
24+
usbbox.commands.p2set(0x00) # send P2SET with value 0 (should turn on LEDs)
25+
usbbox.commands.dirset(1,0,0) # enable loopback mode (button presses turn on LED)
26+
27+
## Receiving reports ##
28+
29+
You can register call-back functions on the `commands` object to receive notification
30+
about reports received from the box. The actual reports are delivered asynchronously,
31+
but to avoid thread safety issues they are stored on a queue until `process_received_reports`
32+
is called. As most events are time-stamped they can be processed as needed.
33+
34+
To register a call-back and have it called whenever a key is pressed one can doing something
35+
like:
36+
37+
import time
38+
from ioLabs import USBBox, REPORT
39+
# REPORT contains the report IDs
40+
41+
usbbox=USBBox()
42+
def mycallback(report):
43+
print "got a report: %s" % report
44+
# register callback just for KEYDN reports
45+
usbbox.commands.add_callback(REPORT.KEYDN,mycallback)
46+
47+
while True:
48+
usbbox.process_received_reports()
49+
time.sleep(0.1)
50+
51+
Calling `process_received_reports` in this way ensures that out call-back will be called on the
52+
same thread as the rest of the program - avoiding any nasty surprises with asynchronous data
53+
access. This should also make it easier for integrating with GUI toolkits.
54+
55+
## Recording reports ##
56+
57+
Instead of registering call-backs one can instead opt to have commands sent to a file, using
58+
the `start_recording` method on the USBBox object. This takes a list of report IDs to record
59+
and a file to output them to:
60+
61+
import time
62+
from ioLabs import USBBox, REPORT
63+
64+
usbbox=USBBox()
65+
outfile=open('output.txt')
66+
# record all events
67+
usbbox.start_recording(REPORT.ALL_IDS(),outfile)
68+
time.sleep(30)
69+
usbbox.stop_recording()
70+
# output.txt should now contain last 30 seconds or so events
71+
72+
## Miscellaneous ##
73+
74+
The underlying HID device for the USB Button Box is stored in `device` on the USBBox instance.
75+
It can be accessed to manually send commands to the device using it's `set_report(report_data)`
76+
command - simply passing a string of the bytes that should be sent in the report.
77+

0 commit comments

Comments
 (0)