hidtools.hidraw module — hid-tools documentation

# hidtools.hidraw module

class HidrawDevice(device)

  Bases: `object`

  A device as exposed by the kernel `hidraw` module. `hidraw` allows direct access to the HID device, both for reading and writing.

      with open('/dev/hidraw0', 'r+b') as fd:
          dev = HidrawDevice(fd)
          while True:
              dev.read_events()  # this blocks
              print(f'We received {len(dev.events)} events so far')

  Parameters:

    device (File) – a file-like object pointing to `/dev/hidrawX`

  name

    The device name

  bustype

    The `hidtools.util.BusType` for this device.

  vendor_id

    16-bit numerical vendor ID

  product_id

    16-bit numerical product ID

  report_descriptor

    The `hidtools.hid.ReportDescriptor` for this device

  events

    All events accumulated so far, a list of `HidrawEvent`

  time_offset

    The offset to be be applied for incoming events. Where the offset is not set by the caller, the offset is the timestamp of the first event. This offset can be used to synchronize events from multiple devices, simply apply the offset of the first device to receive an event to all other devices to get synchronized time stamps for all devices.

  dump(file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, from_the_beginning=False)

    Format this device in a file format in the form of

        R: 123 43 5 52 2 ... # the report descriptor size, followed by the integers
        N: the device name
        I: 3 124 abcd # bustype, vendor, product
        # comments are allowed
        E: 00001.000002 AB 12 34 56 # sec, usec, length, data
        ...

    This method is designed to be called repeatedly and only print the new events on each call. To repeat the dump from the beginning, set `from_the_beginning` to True.

    Parameters:

      - file (File) – the output file to write to

      - from_the_beginning (bool) – if True, print everything again instead of continuing where we left off

  get_feature_report(report_ID)

    Fetch the Feature Report with the given report ID

    Note that the returned array contains the report ID as the first byte, but only if the report is a numbered report.

    Returns:

      an array of bytes with the Feature Report data.

  read_events()

    Read events from the device and append them to `events`.

    This function simply calls `os.read()`, it is the caller’s task to either make sure the device is set nonblocking or to handle any `KeyboardInterrupt` if this call does end up blocking.

    Returns:

      a tuple of `(index, count)` of the `events` added.

  set_feature_report(report_ID, data)

    Set the Feature Report with the given report ID

    Note that the data array must always contain the report ID as the first byte.

class HidrawEvent(sec, usec, bytes)

  Bases: `object`

  A single event from a hidraw device. The first event always has a timestamp of 0.0, all other events are offset accordingly.

  sec

    Timestamp seconds

  usec

    Timestamp microseconds

  bytes

    The data bytes read for this event