usbhid

This module contains low level functions to interact with USB HID devices. The hidapi module is used to abstract the access to the devices across all different operating systems.

This module can also simulate devices:

  • if you define the RIVALCFG_DRY environment variable, a fake device will be returned instead of a real one. This is useful for debugging and testing:

    RIVALCFG_DRY=1 rivalcfg -c ff0000

  • If you define the RIVALCFG_PROFILE environment variable with a vendor id and a product id, this module will report the corresponding device as being plugged:

    RIVALCFG_PROFILE=1038:1702 rivalcfg -h

Constants

rivalcfg.usbhid.HID_REPORT_TYPE_OUTPUT = 2

HID output report

rivalcfg.usbhid.HID_REPORT_TYPE_FEATURE = 3

HID feature report

Functions

rivalcfg.usbhid.is_device_plugged(vendor_id, product_id)

Returns True if the given HID device is plugged to the computer.

Parameters:

  • vendor_id (int) – The vendor id of the device (e.g. 0x1038)).

  • product_id (int) – The product id of the device (e.g. 0x1710).

Return type:

bool

>>> from rivalcfg import usbhid
>>> usbhid.is_device_plugged(0x1038, 0xbaad)
False
rivalcfg.usbhid.open_device(vendor_id, product_id, endpoint)

Opens and returns the HID device

Parameters:

  • vendor_id (int) – The vendor id of the device (e.g. 0x1038)).

  • product_id (int) – The product id of the device (e.g. 0x1710).

  • endpoint (int) – The number of the endpoint to open on the device (e.g. 0).

Raises:

  • DeviceNotFound – The requested device is not plugged to the computer or it does not provide the requested endpoint.

  • IOError – The device or its interface cannot be opened (permission issue, device busy,…).

Return type:

hid.device

>>> from rivalcfg import usbhid
>>> usbhid.open_device(0x1038, 0x1702, 0)
<hid.device at 0x...>

Exceptions

class rivalcfg.usbhid.DeviceNotFound

Exception raised when the requested device was not found (device not plugged to the computer) or when it does not provide the requested endpoint.

Fake HID device

When the RIVALCFG_DRY environment variable is set, the open_device() function of this module returns a fake device instead opening a real one. This is useful for debuging and testing purpose.

class rivalcfg.usbhid.FakeDevice

This class simulate an HID device as provided by the hidapi module.

Data sent to the fake device can be read-back from the bytes attribute of this class.

bytes

A BytesIO instance where every simulated write will be done.

close()

Closes the simulated device.

open_path(path)

Simulate opening the device from given path.

Parameters:

path (bytes) – The device path.

send_feature_report(data)

Simulate a feature report write to an HID device.

Given data will be writen to bytes, prefixed with the HID_REPORT_TYPE_FEATURE byte.

Parameters:

data (bytes) – The data to send to the device.

>>> from rivalcfg.usbhid import FakeDevice
>>> dev = FakeDevice()
>>> dev.send_feature_report(b"\x00\xAA\xBB\xCC")
>>> dev.bytes.seek(0)
0
>>> dev.bytes.read()
b'\x03\x00\xaa\xbb\xcc'
write(data)

Simulate a write to an HID device.

Given data will be writen to bytes, prefixed with the HID_REPORT_TYPE_OUTPUT byte.

Parameters:

data (bytes) – The data to send to the device.

>>> from rivalcfg.usbhid import FakeDevice
>>> dev = FakeDevice()
>>> dev.write(b"\x00\xAA\xBB\xCC")
>>> dev.bytes.seek(0)
0
>>> dev.bytes.read()
b'\x02\x00\xaa\xbb\xcc'