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.