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