-
Notifications
You must be signed in to change notification settings - Fork 16
pyhidapi is a Python binding for the hidapi library.
License
awelkie/pyhidapi
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
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 <nf6x@nf6x.net>
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/>.
About
pyhidapi is a Python binding for the hidapi library.
Resources
License
Stars
Watchers
Forks
Packages 0
No packages published