hidtools.uhid module — hid-tools documentation

# hidtools.uhid module

class `UHIDDevice`

  Bases: `object`

  A uhid device. uhid is a kernel interface to create virtual HID devices based on a report descriptor.

  This class also acts as context manager for any `UHIDDevice` objects. See `dispatch()` for details.

  `device_nodes`

    A list of evdev nodes associated with this HID device. Populating this list requires udev events to be processed, ensure that `dispatch()` is called and that you wait for some reasonable time after creating the device.

  `hidraw_nodes`

    A list of hidraw nodes associated with this HID device. Populating this list requires udev events to be processed, ensure that `dispatch()` is called and that you wait for some reasonable time after creating the device.

  `uniq`

    A uniq string assigned to this device. This string is autogenerated and can be used to reliably identify the device.

  `UHID_FEATURE_REPORT` = 0
  `UHID_INPUT_REPORT` = 2
  `UHID_OUTPUT_REPORT` = 1
  property `bus`

    The device’s bus type (0x3 for USB, 0x5 for Bluetooth, etc.)

  `call_input_event`(data)

    Send an input event from this device.

    Parameters

      data (list) – a list of 8-bit integers representing the HID report for this input event

  `close`()

    Called when a userspace client closes the created kernel device.

    Sending events on a closed device will not result in anyone reading it.

    This message is sent by the kernel, to receive this message you must call `dispatch()`

  `create_kernel_device`()

    Create a kernel device from this device. Note that the device is not immediately ready to go after creation, you must wait for `start()` and ideally for `open()` to be called.

    Raises

      `UHIDIncompleteException` if the device does not have a name, report descriptor or the info bits set.

  `create_report`(data, global_data=None, reportID=None, application=None)

    Convert the data object to an array of ints representing the report. Each property of the given data object is matched against the field usage name (think `hasattr`) and filled in accordingly.:

        mouse = MouseData()
        mouse.b1 = int(l)
        mouse.b2 = int(r)
        mouse.b3 = int(m)
        mouse.x = x
        mouse.y = y

        data_bytes = uhid_device.create_report(mouse)

    The `UHIDDevice` will create the report according to the device’s report descriptor.

  `destroy`()

    Destroy the device. The kernel will trigger the appropriate messages in response before removing the device.

    This function is called automatically on __exit__()

  classmethod `dispatch`(timeout=None)

    Process any events available on any internally registered file descriptor and deal with the events.

    The caller must call this function regularly to make sure things like udev events are processed correctly. There’s no indicator of when to call `dispatch()` yet, call it whenever you’re idle.

    Returns

      the number of devices data was available on

  property `fd`

    The fd to the `/dev/uhid` device node

  `get_report`(req, rnum, rtype)

    Callback invoked when a process calls SetReport on this UHID device.

    Return `(0, [data bytes])` on success or `(errno, [])` on failure.

    The default method always returns `(EIO, [])` for a failure. Override this in your device if you want GetReport to succeed.

    Parameters

      - req – the request identifier

      - rnum –

        ???

      - rtype – one of `UHID_FEATURE_REPORT`, `UHID_INPUT_REPORT`, or `UHID_OUTPUT_REPORT`

  property `info`

    The devices’s bus, vendor ID and product ID as tuple

  property `name`

    The devices HID name

  `open`()

    Called when a userspace client opens the created kernel device.

    This message is sent by the kernel, to receive this message you must call `dispatch()`

  `output_report`(data, size, rtype)

    Callback invoked when a process sends raw data to the device.

    Parameters

      - data – the data sent by the kernel

      - size – size of the data

      - rtype – one of `UHID_FEATURE_REPORT`, `UHID_INPUT_REPORT`, or `UHID_OUTPUT_REPORT`

  property `phys`

    The device’s phys string

  property `pid`

    The device’s 16-bit product ID

  property `rdesc`

    The device’s report descriptor

  `set_report`(req, rnum, rtype, data)

    Callback invoked when a process calls SetReport on this UHID device.

    Return `0` on success or an errno on failure.

    The default method always returns `EIO` for a failure. Override this in your device if you want SetReport to succeed.

    Parameters

      - req – the request identifier

      - rnum –

        ???

      - rtype – one of `UHID_FEATURE_REPORT`, `UHID_INPUT_REPORT`, or `UHID_OUTPUT_REPORT`

      - data (list) – a byte string with the data

  `start`(flags)

    Called when the uhid device is ready to accept IO.

    This message is sent by the kernel, to receive this message you must call `dispatch()`

  `stop`()

    Called when the uhid device no longer accepts IO.

    This message is sent by the kernel, to receive this message you must call `dispatch()`

  property `sys_path`

    The device’s /sys path

  property `udev_device`

    The devices’ udev device.

    The device may be None if udev hasn’t processed the device yet.

  `udev_event`(event)

    Callback invoked on a udev event.

  property `vid`

    The device’s 16-bit vendor ID

exception `UHIDIncompleteException`

  Bases: `Exception`

  An exception raised when a UHIDDevice does not have sufficient information to create a kernel device.