hidtools.hid module
- class HidCollection(value)
Bases:
object
- class Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnum
- 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:
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
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
data
is the value for this HID field andreport
is a HID report’s bytes, this method sets those bits inreport
that 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
data
must have at leastcount
elements, matching this field’s Report Count.
- fill_values_array(report, data)
Assuming
data
is the value for this HID field array andreport
is a HID report’s bytes, this method sets those bits inreport
that 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 keydata
must have at mostcount
elements, 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
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
- property is_array
True
if this HID field is an array
- property is_const
True
if this HID field is const
- property is_null
True
if 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:
object
Represents a HidReport, one of
Input
,Output
,Feature
. AReportDescriptor
may contain one or more HidReports of different types. These comprise of a number ofHidField
making up the exact description of a report.- class Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
The type of a
HidReport
- FEATURE = 3
- INPUT = 1
- OUTPUT = 2
- 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
- property type
One of the types in
HidReport.Type
- class HidUnit(system, units)
Bases:
object
A 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, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnum
- ENGLISH_LINEAR = 3
- ENGLISH_ROTATION = 4
- NONE = 0
- SI_LINEAR = 1
- SI_ROTATION = 2
- classmethod from_string(string)
Returns the correct
HidUnit.System
given the string.
- classmethod from_bytes(data)
Converts the given data bytes into a
HidUnit
object. 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
HidUnit
object.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:
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
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
- 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.
- class Unit(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
Enum
- AMPERE = 'A'
- CANDELA = 'cd'
- CENTIMETER = 'cm'
- DEGREES = 'deg'
- FAHRENHEIT = 'F'
- GRAM = 'g'
- INCH = 'in'
- KELVIN = 'K'
- RADIANS = 'rad'
- RESERVED = 'reserved'
- SECONDS = 's'
- SLUG = 'slug'