bledev.hidreport
HID report descriptors, and the reports they describe, as OmniPython events.
A HID device describes its own reports: the report descriptor (Bluetooth
calls it the Report Map) says which bits of which report carry which control.
This module reads one, and turns the device’s input reports into the same
events.Key, events.Motion, events.Button, events.Wheel,
events.JoyAxisMotion, events.JoyHatMotion and
events.JoyButtonDown/Up records a keyboard, a mouse or a joystick
produces on the desktop through SDL:
from bledev.hidreport import ReportMap, Decoder
rmap = ReportMap(descriptor_bytes)
decoder = Decoder(rmap)
for event in decoder.feed(report, report_id=1):
...
Nothing here knows about Bluetooth. A USB host that has the descriptor can
use it the same way; feed(data) without report_id takes the ID from
the report’s first byte when the map numbers its reports, as USB sends them.
Keyboards follow usbif’s boot-keyboard decoder exactly (same event order, same fields), because an app must not be able to tell a BLE keyboard from a USB one. The keyboard says which keys are held; events come from the difference between successive reports: modifier releases, key releases, key presses, then modifier presses. An ErrorRollOver report is ignored, so the eventual releases still balance.
The keyboard table is keys.hid_keycode, the one usbif uses too.
Mice (the mouse and pointer collections) produce MOUSEMOTION,
MOUSEBUTTONDOWN/UP and MOUSEWHEEL, in that order within a report,
with touch False and window None. A relative mouse has no position of
its own, so pos is the sum of its motion from (0, 0), kept inside
Decoder(..., bounds=(width, height)) when you give one. Buttons are
numbered as SDL does: 1 left, 2 middle, 3 right (HID calls right 2 and middle
3). The wheel is y, positive away from you, and AC Pan is x. A motion
event’s buttons is the (left, middle, right) held before that report,
so a press that arrives with a move reads as the move, then the press.
Consumer controls (media keys, remotes) become events.Key as well,
with keys.K_VOLUMEUP and friends, and scancode set to the extended
usage (0x000C00E9 for volume up). A usage with no key constant arrives
with key=None and name "Unknown", as usbif does.
Game controllers (the joystick, gamepad and multi-axis collections)
produce SDL-style joystick events. Axes are numbered by usage, X, Y, Z, Rx,
Ry, Rz, slider, dial, wheel, then the simulation page (accelerator, brake),
and their value is a float from -1.0 to 1.0 across the logical range.
Buttons are numbered from 0 (Button 1 is button 0). A hat is an (x, y)
tuple, y up, (0, 0) when centred, like pygame.
- exception bledev.hidreport.HIDParseError[source]
Bases:
ValueErrorThe descriptor is malformed: truncated, unbalanced, or impossible.
- class bledev.hidreport.Field(kind, report_id, offset, size, count, flags, usages, logical_min, logical_max, physical_min, physical_max, unit, unit_exponent, application)[source]
Bases:
objectOne main item:
countvalues ofsizebits at bitoffset.offsetcounts from the start of the report after its report ID, the way HOGP delivers it.usagesis a list of extended usages (page << 16 | id) and(first, last)ranges, in descriptor order.applicationis the extended usage of the top-level collection the field sits in.- usage(n)[source]
The
n-th usage in the list, ranges expanded; past the end, the last one.For a variable field that’s the usage of element
n; for an array it’s what the valuelogical_min + nmeans.Noneif the field has no usages at all (padding).
- class bledev.hidreport.Report(kind, report_id)[source]
Bases:
objectThe fields of one report: its
kind, itsreport_id(0 if unnumbered) and its size.- property size
Bytes, without the report ID.
- class bledev.hidreport.ReportMap(descriptor)[source]
Bases:
objectA parsed report descriptor.
reportsmaps(kind, report_id)toReport;numberedsays whether the device uses report IDs;applicationslists the top-level collections’ extended usages in order.
- bledev.hidreport.consumer_keycode(usage)[source]
The
keys.K_*code for a consumer-page usage (0xE9, not extended), orNone.
- class bledev.hidreport.Decoder(report_map, instance_id=0, bounds=None)[source]
Bases:
objectTurns one device’s input reports into OmniPython events.
One instance per device: it holds that device’s state (held keys, axis positions) and diffs each report against it.
instance_idis the joystick instance its joystick events carry.- bounds
(width, height)to keep the mouse pointer inside, or None.
- property held
Keyboard usages held now.
- feed(data, report_id=None)[source]
Decode one input report and return its events, as a tuple.
report_idis the ID HOGP gives in the Report Reference; leave it out for a USB-style report, whose first byte is the ID when the map numbers its reports.
- property pointer
Where the mouse pointer is,
(x, y): the sum of its motion, from (0, 0).