usb_hid module allows you to output data as a HID device.
Available on these boards
Tuple of all active HID device interfaces. The default set of devices is
Device.KEYBOARD, Device.MOUSE, Device.CONSUMER_CONTROL, On boards where
usb_hidis disabled by default,
devicesis an empty tuple.
disable() → None¶
Do not present any USB HID devices to the host computer. Can be called in
boot.py, before USB is connected. The HID composite device is normally enabled by default, but on some boards with limited endpoints, including STM32F4, it is disabled by default. You must turn off another USB device such as
storageto free up endpoints for use by
enable(devices: Optional[Sequence[Device]]) → None¶
Specify which USB HID devices that will be available. Can be called in
boot.py, before USB is connected.
devices (Sequence) –
devicesis empty, HID is disabled. The order of the
Devicesmay matter to the host. For instance, for MacOS, put the mouse device before any Gamepad or Digitizer HID device or else it will not work.
If you enable too many devices at once, you will run out of USB endpoints. The number of available endpoints varies by microcontroller. CircuitPython will go into safe mode after running
boot.pyto inform you if not enough endpoints are available.
Device(*, descriptor: _typing.ReadableBuffer, usage_page: int, usage: int, report_ids: Sequence[int], in_report_lengths: Sequence[int], out_report_lengths: Sequence[int])¶
HID Device specification
report_descriptor (ReadableBuffer) – The USB HID Report descriptor bytes. The descriptor is not not verified for correctness; it is up to you to make sure it is not malformed.
usage_page (int) – The Usage Page value from the descriptor. Must match what is in the descriptor.
usage (int) – The Usage value from the descriptor. Must match what is in the descriptor.
report_ids (Sequence[int]) – Sequence of report ids used by the descriptor. If the
report_descriptordoes not specify any report IDs, use
in_report_lengths (Sequence[int]) – Sequence of sizes in bytes of the HID reports sent to the host. The sizes are in order of the
report_ids. Use a size of
0for a report that is not an IN report. “IN” is with respect to the host.
out_report_lengths (int) – Sequence of sizes in bytes of the HID reports received from the host. The sizes are in order of the
report_ids. Use a size of
0for a report that is not an OUT report. “OUT” is with respect to the host.
out_report_lengthsmust all be the same length.
Here is an example of a
Devicewith a descriptor that specifies two report IDs, 3 and 4. Report ID 3 sends an IN report of length 5, and receives an OUT report of length 6. Report ID 4 sends an IN report of length 2, and does not receive an OUT report:
device = usb_hid.Device( descriptor=b"...", # Omitted for brevity. report_ids=(3, 4), in_report_lengths=(5, 2), out_report_lengths=(6, 0), )
Standard keyboard device supporting keycodes 0x00-0xDD, modifiers 0xE-0xE7, and five LED indicators. Uses Report ID 1 for its IN and OUT reports.
Standard mouse device supporting five mouse buttons, X and Y relative movements from -127 to 127 in each report, and a relative mouse wheel change from -127 to 127 in each report. Uses Report ID 2 for its IN report.
Consumer Control device supporting sent values from 1-652, with no rollover. Uses Report ID 3 for its IN report.
Deprecated: will be removed in CircutPython 8.0.0. Use
The device usage page identifier, which designates a category of device. (read-only)
The device usage identifier, which designates a specific kind of device. (read-only)
For example, Keyboard is 0x06 within the generic desktop usage page 0x01. Mouse is 0x02 within the same usage page.
send_report(self, buf: _typing.ReadableBuffer, report_id: Optional[int] = None) → None¶
Send an HID report. If the device descriptor specifies zero or one report id’s, you can supply
None(the default) as the value of
report_id. Otherwise you must specify which report id to use when sending the report.