hidtools.hid module
- class HidCollection(value: int)
Bases:
object
- class Type(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnum
- class HidField(report_ID: int, logical: int | None, physical: int | None, application: int | None, collection: Tuple[int, int, int] | None, value: int, usage_page: int, usage: int, logical_min: int, logical_max: int, physical_min: int, physical_max: int, unit: int, unit_exp: int, item_size: int, count: int)
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
- fill_values(report: List[int], data: List[int]) None
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: List[int], data: List[Any]) None
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: int, logical: int | None, physical: int | None, application: int | None, collection: Tuple[int, int, int] | None, value: int, usage_page: int, usages: List[int], usage_min: int, usage_max: int, logical_min: int, logical_max: int, physical_min: int, physical_max: int, unit: int, unit_exp: int, item_size: int, count: int)
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: int) str | None
Return the Usage name for this field at the given index. Use this function when the HID field has multiple Usages.
- get_values(report: List[int]) List[int | str]
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
- class HidReport(report_ID: int, application: int | None, type: 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
- append(field: HidField) None
Add a
HidField
to this report- Parameters:
field (HidField) – the object to add to this report
- create_report(data: List[Any], global_data: Any) List[int]
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: List[HidField]) None
Extend this report by the list of
HidField
objects- Parameters:
fields (list) – a list of objects to append to this report
- format_report(data: List[Any], split_lines: bool = True) str
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 type: Type
One of the types in
HidReport.Type
- class HidUnit(system: System, units: Dict[Unit | None, int])
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
.
- class System(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
IntEnum
- classmethod from_string(string: str) System | None
Returns the correct
HidUnit.System
given the string.
- property luminous_intensity: Unit | None
Returns the right
Unit
for the luminous intensity measurement in this system.
- classmethod from_bytes(data: bytes) HidUnit
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.
- exception RangeError(field: HidField, value: int)
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: List[_HidRDescItem])
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
- create_report(data: Any, global_data: Any | None = None, reportID: int | None = None, application: str | int | None = None) List[int]
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') None
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: bytes | List[int]) ReportDescriptor
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: str) ReportDescriptor
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: str) ReportDescriptor
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: int, reportSize: int) HidReport | None
Return the input report with the given Report ID or
None