hidtools.hid module
- class HidCollection(value)
Bases:
object- class Type(value)
Bases:
IntEnumAn enumeration.
- APPLICATION = 1
- LOGICAL = 2
- NAMED_ARRAY = 4
- PHYSICAL = 0
- REPORT = 3
- USAGE_MODIFIER = 6
- USAGE_SWITCH = 5
- classmethod from_str(string)
Return the value of this HidCollection given the human-readable string.
- property is_reserved
- property is_vendor_defined
- class HidField(report_ID, logical, physical, application, collection, value, usage_page, usage, logical_min, logical_max, physical_min, physical_max, unit, unit_exp, item_size, count)
Bases:
objectRepresents 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
The numerical HID field’s Usage, e.g. 0x38 for “Wheel”. If the field has multiple usages, this refers to the first one.
- usage_page
The numerical HID field’s Usage Page, e.g. 0x01 for “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
- physical_min
The physical minimum of this HID field
- physical_max
The physical maximum of this HID field
- unit
The unit of this HID field
- unit_exp
The unit exponent 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 andreportis a HID report’s bytes, this method sets those bits inreportthat are his HID field tovalue.Example:
if this field is Usage
X, usefill_values(report, [x-value])if this field is Usage
X,Y, usefill_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 leastcountelements, matching this field’s Report Count.
- fill_values_array(report, data)
Assuming
datais the value for this HID field array andreportis a HID report’s bytes, this method sets those bits inreportthat are his HID field tovalue.Example: - if this field is an array of keys, use
fill_values(report, ['a or A', 'b or B', ...], i.e. one string representation for each pressed keydatamust have at mostcountelements, 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, physical_min, physical_max, unit, unit_exp, 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 is_null
Trueif this HID field is null
- property logical_name
The logical name or
None
- 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, type)
Bases:
objectRepresents a HidReport, one of
Input,Output,Feature. AReportDescriptormay contain one or more HidReports of different types. These comprise of a number ofHidFieldmaking up the exact description of a 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
- property type
One of the types in
HidReport.Type
- class HidUnit(system, units)
Bases:
objectA parsed field of a HID Report Descriptor Unit specification.
- units
A dict of { unit: exponent } of the applicable units. Where the Unit is
None, the return value isNone.
- system
The system the units belong to, one of
HidUnit.System.
- NONE = None
- class System(value)
Bases:
IntEnumAn enumeration.
- ENGLISH_LINEAR = 3
- ENGLISH_ROTATION = 4
- NONE = 0
- SI_LINEAR = 1
- SI_ROTATION = 2
- classmethod from_string(string)
Returns the correct
HidUnit.Systemgiven the string.
- classmethod from_bytes(data)
Converts the given data bytes into a
HidUnitobject. The data bytes must not include the 0b011001nn prefix byte.Where the HID unit system is None, the returned value is None.
- classmethod from_string(string)
The inverse of __str__()
- classmethod from_value(value)
Converts the given 8, 16 or 32-bit value into a
HidUnitobject.Where the HID unit system is None, the returned value is None.
- property value
Returns the numerical value for this unit as required by the HID specification.
- exception RangeError(field, value)
Bases:
ExceptionException 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:
objectRepresents 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.