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: ValueError

The 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: object

One main item: count values of size bits at bit offset.

offset counts from the start of the report after its report ID, the way HOGP delivers it. usages is a list of extended usages (page << 16 | id) and (first, last) ranges, in descriptor order. application is 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 value logical_min + n means. None if the field has no usages at all (padding).

raw(data, n=0)[source]

Element n’s raw value from report data (without its ID), sign-extended if signed.

values(data)[source]

Every element’s raw value, as a list.

class bledev.hidreport.Report(kind, report_id)[source]

Bases: object

The fields of one report: its kind, its report_id (0 if unnumbered) and its size.

property size

Bytes, without the report ID.

class bledev.hidreport.ReportMap(descriptor)[source]

Bases: object

A parsed report descriptor.

reports maps (kind, report_id) to Report; numbered says whether the device uses report IDs; applications lists the top-level collections’ extended usages in order.

inputs()[source]

The input reports, in report ID order.

bledev.hidreport.consumer_keycode(usage)[source]

The keys.K_* code for a consumer-page usage (0xE9, not extended), or None.

class bledev.hidreport.Decoder(report_map, instance_id=0, bounds=None)[source]

Bases: object

Turns 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_id is the joystick instance its joystick events carry.

bounds

(width, height) to keep the mouse pointer inside, or None.

property held

Keyboard usages held now.

axis(n)[source]

Axis n’s last value, -1.0..1.0 (0.0 before any report).

feed(data, report_id=None)[source]

Decode one input report and return its events, as a tuple.

report_id is 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).