hidtools.hid module — hid-tools documentation

# hidtools.hid module

class `HidField`(report_ID, logical, physical, application, collection, value, usage_page, usage, logical_min, logical_max, item_size, count)

  Bases: `object`

  Represents one field in a HID report. A field is one element of a HID report that matches a specific set of bits in that report.

  `usage`

    A string with HID field’s Usage, e.g. “Wheel”. If the field has multiple usages, this refers to the first one.

  `usage_page`

    The string with HID field’s Usage Page, e.g. “Generic Desktop”

  `report_ID`

    The numeric Report ID this HID field belongs to

  `logical_min`

    The logical minimum of this HID field

  `logical_max`

    The logical maximum of this HID field

  `size`

    Report Size in bits for this HID field

  `count`

    Report Count for this HID field

  `copy`()

    Return a full copy of this HIDField.

  `fill_values`(report, data)

    Assuming `data` is the value for this HID field and `report` is a HID report’s bytes, this method sets those bits in `report` that are his HID field to `value`.

    Example:

    - if this field is Usage `X` , use `fill_values(report, [x-value])`

    - if this field is Usage `X`, `Y`, use `fill_values(report, [x, y])`

    - if this field is a button mask, use `fill_values(report, [1, 0, 1, ...]`, i.e. one value for each button

    `data` must have at least `count` elements, matching this field’s Report Count.

    Parameters

      - report (list) – an integer array representing this report, modified in place

      - data (list) – the data for this hid field with one element for each Usage.

  classmethod `getHidFields`(report_ID, logical, physical, application, collection, value, usage_page, usages, usage_min, usage_max, logical_min, logical_max, item_size, count)

    This is a function to be called by a HID report descriptor parser.

    Given the current parser state and the various arguments, create the required number of `HidField` objects.

    Returns

      a list of `HidField` objects

  `get_usage_name`(index)

    Return the Usage name for this field at the given index. Use this function when the HID field has multiple Usages.

  `get_values`(report)

    Assume `report` is a list of bytes that are a full HID report, extract the values that are this HID field.

    Example:

    - if this field is Usage `X` , this returns `[x-value]`

    - if this field is Usage `X`, `Y`, this returns `[x, y]`

    - if this field is a button mask, this returns `[1, 0, 1, ...]`, i.e. one value for each button

    Parameters

      report (list) – a list of bytes that are a HID report

    Returns

      a list of integer values of len `count`

  property `is_array`

    `True` if this HID field is an array

  property `is_const`

    `True` if this HID field is const

  property `physical_name`

    The physical name or `None`

  property `usage_name`

    The Usage name for this field (e.g. “Wheel”).

  property `usage_page_name`

    The Usage Page name for this field, e.g. “Generic Desktop”

class `HidReport`(report_ID, application)

  Bases: `object`

  Represents a HidReport, one of `Input`, `Output`, `Feature`. A `ReportDescriptor` may contain one or more HidReports of different types. These comprise of a number of `HidField` making up the exact description of a report.

  Parameters

    - report_ID (int) – the report ID

    - application (int) – the HID application

  `fields`

    The HidFields comprising this report

  `append`(field)

    Add a `HidField` to this report

    Parameters

      field (HidField) – the object to add to this report

  property `application_name`
  property `bitsize`

    The size of the HidReport in bits

  `create_report`(data, global_data)

    Convert the data object to an array of ints representing this report. Each property of the given data object is matched against the field usage name (using `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 = hid_report.create_report(mouse)

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

  `extend`(fields)

    Extend this report by the list of `HidField` objects

    Parameters

      fields (list) – a list of objects to append to this report

  `format_report`(data, split_lines=True)

    Format the HID Report provided as a list of 8-bit integers into a human-readable format.

    Parameters

      - data (list) – a list of 8-bit integers that are this report

      - split_lines (boolean) – `True` if the format can be split across multiple lines. This makes for easier reading but harder automated processing.

  property `numbered`

    True if the HidReport was initialized with a report ID

  property `size`

    The size of the HidReport in bytes

exception `ParseError`

  Bases: `Exception`

  Exception thrown during report descriptor parsing

exception `RangeError`(field, value)

  Bases: `Exception`

  Exception thrown for an out-of-range value

  `value`

    The invalid value

  `range`

    A `(min, max)` tuple for the allowed logical range

  `field`

    The `HidField` that triggered this exception

class `ReportDescriptor`(items)

  Bases: `object`

  Represents a fully parsed HID report descriptor.

  When creating a `ReportDescriptor` object,

  - if your source is a stream of bytes, use `from_bytes()`

  - if your source is a human-readable descriptor, use `from_human_descr()`

  `win8`

    `True` if the device is Windows8 compatible, `False` otherwise

  `input_reports`

    All `HidReport` of type `Input`, addressable by the report ID

  `output_reports`

    All `HidReport` of type `Output`, addressable by the report ID

  `feature_reports`

    All `HidReport` of type `Feature`, addressable by the report ID

  property `bytes`

    This report descriptor as a list of 8-bit integers.

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

        rdesc = ReportDescriptor.from_bytes([10, ab, 20, cd, ...])

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

        data_bytes = rdesc.create_report(mouse)

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

  `dump`(dump_file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, output_type='default')

    Write this ReportDescriptor into the given file

    The “default” format prints each item as hexadecimal format with a double-slash comment, e.g.

        0x05, 0x01,                    // Usage Page (Generic Desktop)        0
        0x09, 0x02,                    // Usage (Mouse)                       2

    The “kernel” format prints each item in valid C format, for easy copy-paste into a kernel or C source file:

        0x05, 0x01,         /* Usage Page (Generic Desktop)         */
        0x09, 0x02,         /* Usage (Mouse)                        */

    Parameters

      - dump_file (File) – the file to write to

      - output_type (str) – the output format, one of “default” or “kernel”

  `format_report`(data, split_lines=True)

    Format the HID Report provided as a list of 8-bit integers into a human-readable format.

    Parameters

      - data (list) – a list of 8-bit integers that are this report

      - split_lines (boolean) – `True` if the format can be split across multiple lines. This makes for easier reading but harder automated processing.

  classmethod `from_bytes`(rdesc)

    Parse the given list of 8-bit integers.

    Parameters

      rdesc (list) – a list of bytes that are this report descriptor

  classmethod `from_human_descr`(rdesc_str)

    Parse the given human-readable report descriptor, e.g.

        Usage Page (Digitizers)
        Usage (Finger)
        Collection (Logical)
         Report Size (1)
         Report Count (1)
         Logical Minimum (0)
         Logical Maximum (1)
         Usage (Tip Switch)
         Input (Data,Var,Abs)
         Report Size (7)
         Logical Maximum (127)
         Input (Cnst,Var,Abs)
         Report Size (8)
         Logical Maximum (255)
         Usage (Contact Id)

  classmethod `from_string`(rdesc)

    Parse a string in the format of series of hex numbers:

        12 34 ab cd ...

    and the first number in that series is the count of bytes, excluding that first number. This is the format returned by your `/dev/hidraw` event node, so just pass it along.

    Parameters

      rdesc (list) – a string that represents the list of bytes

  `get`(reportID, reportSize)

    Return the input report with the given Report ID or `None`

  `get_report_from_application`(application)

    Return the Input report that matches the application or `None`

  property `size`

    Returns the size of the report descriptor in bytes.