-
Notifications
You must be signed in to change notification settings - Fork 9
/
README.txt
157 lines (108 loc) · 5.45 KB
/
README.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
# 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.