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 - datais the value for this HID field and- reportis a HID report’s bytes, this method sets those bits in- reportthat 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
 - datamust have at least- countelements, matching this field’s Report Count.
 - 
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 - HidFieldobjects.- Returns
- a list of - HidFieldobjects
 
 - 
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 - reportis 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
 
 - 
property is_array¶
- Trueif this HID field is an array
 - 
property is_const¶
- Trueif 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- ReportDescriptormay contain one or more HidReports of different types. These comprise of a number of- HidFieldmaking up the exact description of a report.- 
fields¶
- The HidFields comprising this report 
 - 
append(field)¶
- Add a - HidFieldto 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 - HidFieldobjects- 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) – - Trueif 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 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
 
- 
- 
class ReportDescriptor(items)¶
- Bases: - object- Represents a fully parsed HID report descriptor. - When creating a - ReportDescriptorobject,- if your source is a stream of bytes, use - from_bytes()
- if your source is a human-readable descriptor, use - from_human_descr()
 - 
win8¶
- Trueif the device is Windows8 compatible,- Falseotherwise
 - 
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) – - Trueif 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/hidrawevent 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.