-
Notifications
You must be signed in to change notification settings - Fork 16
/
README
429 lines (317 loc) · 16 KB
/
README
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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
INTRODUCTION
pyhidapi is a Python binding for the hidapi library, which
provides a platform-independent interface to USB Human Interface
Device (HID) hardware from user programs. The hidapi library
itself is an external dependency and is not included in the
pyhidapi package. The hidapi library may be found here:
https://github.com/signal11/hidapi
INSTALLATION
Use the setup.py script to install pyhidapi. Here are some usage
examples:
Install in your user directory:
./setup.py install --user
Install in the system default location:
sudo ./setup.py install
Install under /usr/local:
sudo ./setup.py install --prefix /usr/local
Create a source distribution:
./setup.py sdist
USAGE EXAMPLE
Here is a simple example, showing how to enumerate all HID devices
on the system with pyhidapi:
-------- 8< cut here 8< --------
#!/usr/bin/env python
import hidapi
hidapi.hid_init()
for dev in hidapi.hid_enumerate():
print '------------------------------------------------------------'
print dev.description()
-------- 8< cut here 8< --------
DETAILED DOCUMENTATION
NAME
hidapi - Python binding for the hidapi library.
FILE
hidapi/hidapi.py
DESCRIPTION
pyhidapi is a Python binding for the hidapi library, which provides a
platform-independent interface to USB Human Interface Device (HID)
hardware from user programs. The hidapi library itself is an external
dependency and is not included in the pyhidapi package. The hidapi
library may be found here:
https://github.com/signal11/hidapi
Users of this module must call hid_init() before calling any other
functions defined by the module.
On the Mac, if the hidapi library is installed under /usr/local/lib,
it may be necessary to set the DYLD_LIBRARY_PATH environment variable
to '/usr/local/lib' so that find_library() will search there.
Public classes defined by this module:
hid_device_info
Public functions defined by this module:
hid_close(device)
hid_enumerate(vendor_id=0, product_id=0)
hid_error(device)
hid_exit()
hid_get_feature_report(device, data)
hid_get_indexed_string(device, string_index)
hid_get_manufacturer_string(device)
hid_get_product_string(device)
hid_get_serial_number_string(device)
hid_init()
hid_lib_path()
hid_open(vendor_id, product_id, serial_number=None)
hid_open_path(path)
hid_read(device, length)
hid_read_timeout(device, length, milliseconds)
hid_send_feature_report(device, data)
hid_set_nonblocking(device, nonblock)
hid_write(device, data)
CLASSES
__builtin__.object
hid_device_info
class hid_device_info(__builtin__.object)
| Describes an HID device found by hid_enumerate().
|
| Methods defined here:
|
| __init__(self, _hid_device_info__hid_device=None)
| Constructor for class hid_device_info.
|
| __hid_device argument is for internal use by this module.
|
| description(self)
| Return a printable string describing the device.
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables (if defined)
|
| __weakref__
| list of weak references to the object (if defined)
|
| ----------------------------------------------------------------------
| Data and other attributes defined here:
|
| interface_number = 0
|
| manufacturer_string = u''
|
| path = ''
|
| product_id = 0
|
| product_string = u''
|
| release_number = 0
|
| serial_number = u''
|
| usage = 0
|
| usage_page = 0
|
| vendor_id = 0
FUNCTIONS
hid_close(device)
Close an HID device.
Arguments:
device: A device handle returned by hid_open().
Returns:
None
hid_enumerate(vendor_id=0, product_id=0)
Enumerate the HID devices.
This function returns a list of hid_device_info objects
describing all of the HID devices which match vendor_id and product_id.
If vendor_id is set to the default of 0, then any vendor matches.
If product_id is set to the default of 0, then any product matches.
If both are set to the default of 0, then all HID devices will be returned.
Arguments:
vendor_id: The 16-bit vendor ID (VID) of devices to be enumerated.
product_id: The 16-bit product ID (PID) of devices to be enumerated.
Returns:
List of hid_device_info objects, or an empty list.
hid_error(device)
Get a string describing the last error which occurred.
Arguments:
device: A device handle returned by hid_open().
Returns:
String describing the last error that occurred, or None if no
error has occurred.
hid_exit()
Clean up hidapi library resources.
Arguments:
None
Returns:
None
hid_get_feature_report(device, data)
Get a feature report from a HID device.
Set the first byte of data[] to the Report ID of the report to be read, and
make the size of data equal to the size of the desired report plus one more byte
for the report ID number.
*** This function is not adequately tested, because the author has not yet
*** identified a device which uses feature reports with which to test the
*** code.
Arguments:
device: A device handle returned by hid_open().
data: A bytearray to be sent to the device as the feature report
request. Set the first byte to the desired report ID, or
0x00 if the device does not use numbered reports.
Returns:
Bytearray containing report from device. The first byte
will be the report number.
Raises RuntimeError exception if an error occurs.
hid_get_indexed_string(device, string_index)
Get a string from an HID device, based on its string index.
Arguments:
device: A device handle returned by hid_open().
string_index: String index number to be fetched.
Returns:
Requested unicode string.
Raises RuntimeError exception if error occurs.
hid_get_manufacturer_string(device)
Get the manufacturer string from an HID device.
Arguments:
device: A device handle returned by hid_open().
Returns:
Manufacturer unicode string.
Raises RuntimeError exception if error occurs.
hid_get_product_string(device)
Get the product string from an HID device.
Arguments:
device: A device handle returned by hid_open().
Returns:
Product unicode string.
Raises RuntimeError exception if error occurs.
hid_get_serial_number_string(device)
Get the serial number string from an HID device.
Arguments:
device: A device handle returned by hid_open().
Returns:
Serial number unicode string.
Raises RuntimeError exception if error occurs.
hid_init()
Initialize the hidapi library.
User code must call this function before calling any other functions
defined by this module.
hid_lib_path()
Return path of loaded hidapi library.
Arguments:
none
Returns:
String containing path of loaded hidapi library.
hid_open(vendor_id, product_id, serial_number=None)
Open an HID device by its VID and PID.
Specify the desired device by vendor ID (VID), product ID (PID),
and an optional serial number.
If serial_number is None, open the first device found with the specified
VID and PID.
Arguments:
vendor_id: The 16-bit vendor ID (VID) of the device to be opened.
product_id: The 16-bit product ID (PID) of the device to be opened.
serial_number: Optional serial number Unicode string.
Returns:
Handle to opened device.
Raises RuntimeError exception if device cannot be opened.
hid_open_path(path)
Open an HID device by its path name.
The path name be determined by calling hid_enumerate(), or a
platform-specific path name can be used (eg: /dev/hidraw0 on Linux).
Arguments:
path: Path name of the device to open.
Returns:
Handle to opened device.
Raises RuntimeError exception if device cannot be opened.
hid_read(device, length)
Read an Input report from a HID device.
Input reports are returned to the host through the INTERRUPT IN endpoint.
The first byte will contain the Report number if the device uses numbered
reports.
Arguments:
device: A device handle returned by hid_open().
length: Number of bytes to be read. For devices with multiple reports,
include an extra byte for the report number.
Returns:
bytearray containing data that was read.
Raises RuntimeError exception if an error occurs.
hid_read_timeout(device, length, milliseconds)
Read an Input report from a HID device with timeout.
Input reports are returned to the host through the INTERRUPT IN endpoint.
The first byte will contain the Report number if the device uses numbered
reports.
Arguments:
device: A device handle returned by hid_open().
length: Number of bytes to be read. For devices with multiple reports,
include an extra byte for the report number.
milliseconds: Timeout in milliseconds, or -1 for blocking read.
Returns:
bytearray containing data that was read.
If no packet was available to be read within the timeout,
returns an empty bytearray.
Raises RuntimeError exception if an error occurs.
hid_send_feature_report(device, data)
Send a Feature report to the device.
Feature reports are sent over the Control endpoint as a Set_Report
transfer. The first byte of data[] must contain the Report ID. For
devices which only support a single report, this must be set to 0x00.
The remaining bytes contain the report data. Since the Report ID is
mandatory, calls to hid_send_feature_report() will always contain one
more byte than the report contains. For example, if a hid report is
16 bytes long, 17 bytes must be passed to hid_send_feature_report():
the Report ID (or 0x00, for devices which do not use numbered reports),
followed by the report data (16 bytes). In this example, the length
passed in would be 17.
*** This function is not adequately tested, because the author has not yet
*** identified a device which uses feature reports with which to test the
*** code.
Arguments:
device: A device handle returned by hid_open().
data: A bytearray containing the data to be written.
Returns:
Actual number of bytes written.
Raises RuntimeError exception if an error occurs.
hid_set_nonblocking(device, nonblock)
Set the device handle to be non-blocking.
In non-blocking mode calls to hid_read() will return immediately with
a value of 0 if there is no data to be read. In blocking mode,
hid_read() will wait (block) until there is data to read before
returning. Nonblocking can be turned on and off at any time.
Arguments:
device: A device handle returned by hid_open().
nonblock: Set to True or 1 to enable nonblocking mode.
Set to False or 0 to disable nonblocking mode.
Returns:
None
Raises RuntimeError exception if error occurs.
hid_write(device, data)
Write an Output report to a HID device.
The first byte of the data argument must contain the Report ID. For
devices which only support a single report, this must be set to 0x00.
The remaining bytes contain the report data. Since the Report ID is
mandatory, calls to hid_write() will always contain one more byte
than the report contains. For example, if a hid report is 16 bytes
long, 17 bytes must be passed to hid_write(), the Report ID (or 0x00,
for devices with a single report), followed by the report data (16
bytes). In this example, the length passed in would be 17.
hid_write() will send the data on the first OUT endpoint, if one
exists. If it does not, it will send the data through the Control
Endpoint (Endpoint 0).
Arguments:
device: A device handle returned by hid_open().
data: A bytearray containing the data to be written.
Returns:
Actual number of bytes written.
Raises RuntimeError exception if an error occurs.
AUTHOR
Mark J. Blair, NF6X <[email protected]>
COPYRIGHT
pyhidapi is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
pyhidapi is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with pyhidapi. If not, see <http://www.gnu.org/licenses/>.