Solaar/lib/hidapi.py

"""Human Interface Device API.

It is little more than a thin ctypes layer over a native hidapi implementation.
The docstrings are mostly copied from the hidapi API header, with changes where
necessary.

The native HID API implemenation is available at
https://github.com/signal11/hidapi.

Using the native hidraw implementation is recommended.
Currently the native libusb implementation (temporarily) detaches the device's
USB driver from the kernel, and it may cause the device to become unresponsive.
"""

__version__ = '0.2-hidapi-0.7.0'


import ctypes as _C


#
# look for a native implementation in the same directory as this file
#

"""The CDLL native library object."""
_native = None

for native_implementation in ('hidraw', 'libusb'):
	try:
		# first look in the default library path
		native_implementation = 'libhidapi-' + native_implementation + '.so'
		_native = _C.cdll.LoadLibrary(native_implementation)
		break
	except OSError:
		pass
del native_implementation

if _native is None:
	raise ImportError('hidapi: failed to load any HID API native implementation')


#
# Structures used by this API.
#


# used by the native implementation when enumerating, no need to expose it
class _NativeDeviceInfo(_C.Structure):
	pass
_NativeDeviceInfo._fields_ = [
				('path', _C.c_char_p),
				('vendor_id', _C.c_ushort),
				('product_id', _C.c_ushort),
				('serial', _C.c_wchar_p),
				('release', _C.c_ushort),
				('manufacturer', _C.c_wchar_p),
				('product', _C.c_wchar_p),
				('usage_page', _C.c_ushort),
				('usage', _C.c_ushort),
				('interface', _C.c_int),
				('next_device', _C.POINTER(_NativeDeviceInfo))
]


# the tuple object we'll expose when enumerating devices
from collections import namedtuple
DeviceInfo = namedtuple('DeviceInfo', [
				'path',
				'vendor_id',
				'product_id',
				'serial',
				'release',
				'manufacturer',
				'product',
				'interface'])
del namedtuple


# create a DeviceInfo tuple from a hid_device object
def _makeDeviceInfo(native_device_info):
	return DeviceInfo(
				path=str(native_device_info.path),
				vendor_id=hex(native_device_info.vendor_id)[2:],
				product_id=hex(native_device_info.product_id)[2:],
				serial=str(native_device_info.serial) if native_device_info.serial else None,
				release=hex(native_device_info.release)[2:],
				manufacturer=str(native_device_info.manufacturer),
				product=str(native_device_info.product),
				interface=native_device_info.interface)


#
# set-up arguments and return types for each hidapi function
#

_native.hid_init.argtypes = None
_native.hid_init.restype = _C.c_int

_native.hid_exit.argtypes = None
_native.hid_exit.restype = _C.c_int

_native.hid_enumerate.argtypes = [_C.c_ushort, _C.c_ushort]
_native.hid_enumerate.restype = _C.POINTER(_NativeDeviceInfo)

_native.hid_free_enumeration.argtypes = [_C.POINTER(_NativeDeviceInfo)]
_native.hid_free_enumeration.restype = None

_native.hid_open.argtypes = [_C.c_ushort, _C.c_ushort, _C.c_wchar_p]
_native.hid_open.restype = _C.c_void_p

_native.hid_open_path.argtypes = [_C.c_char_p]
_native.hid_open_path.restype = _C.c_void_p

_native.hid_close.argtypes = [_C.c_void_p]
_native.hid_close.restype = None

_native.hid_write.argtypes = [_C.c_void_p, _C.c_char_p, _C.c_size_t]
_native.hid_write.restype = _C.c_int

_native.hid_read.argtypes = [_C.c_void_p, _C.c_char_p, _C.c_size_t]
_native.hid_read.restype = _C.c_int

_native.hid_read_timeout.argtypes = [_C.c_void_p, _C.c_char_p, _C.c_size_t, _C.c_int]
_native.hid_read_timeout.restype = _C.c_int

_native.hid_set_nonblocking.argtypes = [_C.c_void_p, _C.c_int]
_native.hid_set_nonblocking.restype = _C.c_int

_native.hid_send_feature_report.argtypes = [_C.c_void_p, _C.c_char_p, _C.c_size_t]
_native.hid_send_feature_report.restype = _C.c_int

_native.hid_get_feature_report.argtypes = [_C.c_void_p, _C.c_char_p, _C.c_size_t]
_native.hid_get_feature_report.restype = _C.c_int

_native.hid_get_manufacturer_string.argtypes = [_C.c_void_p, _C.c_wchar_p, _C.c_size_t]
_native.hid_get_manufacturer_string.restype = _C.c_int

_native.hid_get_product_string.argtypes = [_C.c_void_p, _C.c_wchar_p, _C.c_size_t]
_native.hid_get_product_string.restype = _C.c_int

_native.hid_get_serial_number_string.argtypes = [_C.c_void_p, _C.c_wchar_p, _C.c_size_t]
_native.hid_get_serial_number_string.restype = _C.c_int

_native.hid_get_indexed_string.argtypes = [_C.c_void_p, _C.c_int, _C.c_wchar_p, _C.c_size_t]
_native.hid_get_indexed_string.restype = _C.c_int

_native.hid_error.argtypes = [_C.c_void_p]
_native.hid_error.restype = _C.c_wchar_p


#
# exposed API
# docstrings mostly copied from hidapi.h
#


def init():
	"""Initialize the HIDAPI library.

	This function initializes the HIDAPI library. Calling it is not strictly
	necessary, as it will be called automatically by enumerate() and any of the
	open_*() functions if it is needed.  This function should be called at the
	beginning of execution however, if there is a chance of HIDAPI handles
	being opened by different threads simultaneously.

	:returns: ``True`` if successful.
	"""
	return _native.hid_init() == 0


def exit():
	"""Finalize the HIDAPI library.

	This function frees all of the static data associated with HIDAPI. It should
	be called at the end of execution to avoid memory leaks.

	:returns: ``True`` if successful.
	"""
	return _native.hid_exit() == 0


def enumerate(vendor_id=None, product_id=None, interface_number=None):
	"""Enumerate the HID Devices.

	List all the HID devices attached to the system, optionally filtering by
	vendor_id, product_id, and/or interface_number.

	:returns: a list of matching ``DeviceInfo`` tuples.
	"""
	results = []

	devices = _native.hid_enumerate(vendor_id, product_id)
	d = devices
	while d:
		if interface_number is None or interface_number == d.contents.interface:
			results.append(_makeDeviceInfo(d.contents))
		d = d.contents.next_device

	if devices:
		_native.hid_free_enumeration(devices)

	return results


def open(vendor_id, product_id, serial=None):
	"""Open a HID device by its Vendor ID, Product ID and optional serial number.

	If no serial is provided, the first device with the specified IDs is opened.

	:returns: an opaque device handle, or ``None``.
	"""
	return _native.hid_open(vendor_id, product_id, serial) or None


def open_path(device_path):
	"""Open a HID device by its path name.

	:param device_path: the path of a ``DeviceInfo`` tuple returned by
	enumerate().

	:returns: an opaque device handle, or ``None``.
	"""
	return _native.hid_open_path(device_path) or None


def close(device_handle):
	"""Close a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	"""
	_native.hid_close(device_handle)


def write(device_handle, data):
	"""Write an Output report to a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	:param data: the data bytes to send including the report number as the
	first byte.

	The first byte of data[] must contain the Report ID. For
	devices which only support a single report, this must be set
	to 0x0. 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 0x0, for devices with a
	single report), followed by the report data (16 bytes). In
	this example, the length passed in would be 17.

	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).

	:returns: ``True`` if the write was successful.
	"""
	bytes_written = _native.hid_write(device_handle, _C.c_char_p(data), len(data))
	return bytes_written > -1


def read(device_handle, bytes_count, timeout_ms=-1):
	"""Read an Input report from a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	:param bytes_count: maximum number of bytes to read.
	:param timeout_ms: can be -1 (default) to wait for data indefinitely, 0 to
	read whatever is in the device's input buffer, or a positive integer to
	wait that many milliseconds.

	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.

	:returns: the bytes read, or ``None`` if a timeout was reached.
	"""
	out_buffer = _C.create_string_buffer(b'\x00' * (bytes_count + 1))
	bytes_read = _native.hid_read_timeout(device_handle, out_buffer, bytes_count, timeout_ms)
	if bytes_read > -1:
		return out_buffer[:bytes_read]


def send_feature_report(device_handle, data, report_number=None):
	"""Send a Feature report to the device.

	:param device_handle: a device handle returned by open() or open_path().
	:param data: the data bytes to send including the report number as the
	first byte.
	:param report_number: if set, it is sent as the first byte with the data.

	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 0x0. The remaining bytes
	contain the report data. Since the Report ID is mandatory,
	calls to 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
	send_feature_report(): the Report ID (or 0x0, for
	devices which do not use numbered reports), followed by the
	report data (16 bytes).

	:returns: ``True`` if the report was successfully written to the device.
	"""
	if report_number is not None:
		data = chr(report_number) + data
	bytes_written = _native.hid_send_feature_report(device_handle, _C.c_char_p(data), len(data))
	return bytes_written > -1


def get_feature_report(device_handle, bytes_count, report_number=None):
	"""Get a feature report from a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	:param bytes_count: how many bytes to read.
	:param report_number: if set, it is sent as the report number.

	:returns: the feature report data.
	"""
	out_buffer = _C.create_string_buffer('\x00' * (bytes_count + 2))
	if report_number is not None:
		out_buffer[0] = chr(report_number)
	bytes_read = _native.hid_get_feature_report(device_handle, out_buffer, bytes_count)
	if bytes_read > -1:
		return out_buffer[:bytes_read]


def _read_wchar(func, device_handle, index=None):
	_BUFFER_SIZE = 64
	buf = _C.create_unicode_buffer('\x00' * _BUFFER_SIZE)
	if index is None:
		ok = func(device_handle, buf, _BUFFER_SIZE)
	else:
		ok = func(device_handle, index, buf, _BUFFER_SIZE)
	if ok == 0:
		return buf.value


def get_manufacturer(device_handle):
	"""Get the Manufacturer String from a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	"""
	return _read_wchar(_native.hid_get_manufacturer_string, device_handle)


def get_product(device_handle):
	"""Get the Product String from a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	"""
	return _read_wchar(_native.hid_get_product_string, device_handle)


def get_serial(device_handle):
	"""Get the serial number from a HID device.

	:param device_handle: a device handle returned by open() or open_path().
	"""
	serial = _read_wchar(_native.hid_get_serial_number_string, device_handle)
	if serial is not None:
		return ''.join(hex(ord(c)) for c in serial)


def get_indexed_string(device_handle, index):
	"""Get a string from a HID device, based on its string index.

	Note: may not be implemented by the underlying native library.

	:param device_handle: a device handle returned by open() or open_path().
	:param string_index: the index of the string to get.
	"""
	return _read_wchar(_native.hid_get_indexed_string, device_handle, index)


def last_error(device_handle):
	"""Get a string describing the last error which occurred.

	Note: currently not implemented by the underlying native library.

	:param device_handle: a device handle returned by open() or open_path().
	:returns: a string containing the last error which occurred, or None.
	"""
	return _native.hid_error(device_handle)