picoware.system.usb.USBKeyboard

class documentation

class USBKeyboard:

Constructor: USBKeyboard(manufacturer, product, serial)

USB HID keyboard device that runs alongside the built-in CDC (serial) interface.

Builds a composite USB descriptor by appending a HID keyboard interface to the existing CDC configuration so both the REPL serial port and the keyboard are available at the same time.

Method	`__init__`	Create a USBKeyboard instance.
Method	`init`	Initialise and activate the composite CDC + HID USB device.
Method	`press`	Press and immediately release a key.
Method	`release`	Send an all-zeros HID report to release all currently held keys.
Method	`send_key`	Send a single HID key-down report without releasing the key.
Method	`shortcut`	Press a key combination and wait briefly after releasing.
Method	`type_string`	Type a string by pressing each character in sequence.
Constant	`HID_IAD`	Undocumented
Constant	`HID_REPORT_DESC`	Undocumented
Constant	`KEY_DELETE`	Undocumented
Constant	`KEY_DOWN`	Undocumented
Constant	`KEY_ENTER`	Undocumented
Constant	`KEY_ESC`	Undocumented
Constant	`KEY_F1`	Undocumented
Constant	`KEY_F10`	Undocumented
Constant	`KEY_F11`	Undocumented
Constant	`KEY_F12`	Undocumented
Constant	`KEY_F2`	Undocumented
Constant	`KEY_F3`	Undocumented
Constant	`KEY_F4`	Undocumented
Constant	`KEY_F5`	Undocumented
Constant	`KEY_F6`	Undocumented
Constant	`KEY_F7`	Undocumented
Constant	`KEY_F8`	Undocumented
Constant	`KEY_F9`	Undocumented
Constant	`KEY_LEFT`	Undocumented
Constant	`KEY_RIGHT`	Undocumented
Constant	`KEY_SPACE`	Undocumented
Constant	`KEY_TAB`	Undocumented
Constant	`KEY_UP`	Undocumented
Constant	`KEYMAP`	Undocumented
Constant	`MOD_LALT`	Undocumented
Constant	`MOD_LCTRL`	Undocumented
Constant	`MOD_LGUI`	Undocumented
Constant	`MOD_LSHIFT`	Undocumented
Constant	`MOD_RALT`	Undocumented
Constant	`MOD_RCTRL`	Undocumented
Constant	`MOD_RGUI`	Undocumented
Constant	`MOD_RSHIFT`	Undocumented
Constant	`SHIFT_CHARS`	Undocumented
Method	`_on_control_xfer_cb`	Control-transfer callback invoked by the USB stack for HID class requests.
Method	`_on_xfer_cb`	Transfer-complete callback invoked by the USB stack.
Method	`_wait`	Block until the previous HID transfer completes or the timeout expires.
Instance Variable	`_manufacturer`	Undocumented
Instance Variable	`_product`	Undocumented
Instance Variable	`_serial`	Undocumented
Instance Variable	`_usbdev`	Undocumented
Instance Variable	`_xfer_done`	Undocumented

def __init__(self, manufacturer='MicroPython', product='Picoware Keyboard', serial='000000'): ¶

Create a USBKeyboard instance.

Parameters
manufacturer:`str`	Manufacturer string in the USB device descriptor. Defaults to "MicroPython".
product:`str`	Product string in the USB device descriptor. Defaults to "Picoware Keyboard".
serial:`str`	Serial number string in the USB device descriptor. Defaults to "000000".

def init(self): ¶

Initialise and activate the composite CDC + HID USB device.

Appends a HID keyboard interface to the built-in CDC descriptor, re-configures the USBDevice, and activates it. Must be called once before any key-sending methods are used.

def press(self, modifier=0, keycode=0): ¶

Press and immediately release a key.

Parameters
modifier:`int`	Modifier byte (e.g. `MOD_LSHIFT`, `MOD_LCTRL`). Defaults to 0.
keycode:`int`	HID usage-ID of the key to press. Defaults to 0.

def release(self): ¶

Send an all-zeros HID report to release all currently held keys.

def send_key(self, modifier=0, keycode=0): ¶

Send a single HID key-down report without releasing the key.

Parameters
modifier:`int`	Modifier byte (e.g. `MOD_LSHIFT`, `MOD_LCTRL`). Defaults to 0.
keycode:`int`	HID usage-ID of the key to press. Defaults to 0.

def shortcut(self, modifier, keycode, delay_ms=100): ¶

Press a key combination and wait briefly after releasing.

Useful for OS-level shortcuts where a short post-press delay ensures the host has time to process the keystroke.

Parameters
modifier:`int`	Modifier byte (e.g. `MOD_LGUI`, `MOD_LCTRL`).
keycode:`int`	HID usage-ID of the key to press.
delay_ms:`int`	Milliseconds to sleep after the key is released. Defaults to 100.

def type_string(self, s, delay_ms=50): ¶

Type a string by pressing each character in sequence.

Characters in SHIFT_CHARS are sent with the left-shift modifier. Characters not found in KEYMAP are silently skipped.

Parameters
s:`str`	The string to type.
delay_ms:`int`	Milliseconds to wait between each keystroke. Defaults to 50.

HID_IAD = ¶

Undocumented

Value

bytes([8, 11, 2, 1, 3, 1, 1, 0])

HID_REPORT_DESC = ¶

Undocumented

Value

bytes([5,
       1,
       9,
       6,
       161,
       1,
       5,
...

KEY_DELETE: int = ¶

Undocumented

Value

KEY_DOWN: int = ¶

Undocumented

Value

KEY_ENTER: int = ¶

Undocumented

Value

KEY_ESC: int = ¶

Undocumented

Value

KEY_F1: int = ¶

Undocumented

Value

KEY_F10: int = ¶

Undocumented

Value

KEY_F11: int = ¶

Undocumented

Value

KEY_F12: int = ¶

Undocumented

Value

KEY_F2: int = ¶

Undocumented

Value

KEY_F3: int = ¶

Undocumented

Value

KEY_F4: int = ¶

Undocumented

Value

KEY_F5: int = ¶

Undocumented

Value

KEY_F6: int = ¶

Undocumented

Value

KEY_F7: int = ¶

Undocumented

Value

KEY_F8: int = ¶

Undocumented

Value

KEY_F9: int = ¶

Undocumented

Value

KEY_LEFT: int = ¶

Undocumented

Value

KEY_RIGHT: int = ¶

Undocumented

Value

KEY_SPACE: int = ¶

Undocumented

Value

KEY_TAB: int = ¶

Undocumented

Value

KEY_UP: int = ¶

Undocumented

Value

KEYMAP: dict[str, int] = ¶

Undocumented

Value

{'a': 4,
 'b': 5,
 'c': 6,
 'd': 7,
 'e': 8,
 'f': 9,
 'g': 10,
...

MOD_LALT: int = ¶

Undocumented

Value

MOD_LCTRL: int = ¶

Undocumented

Value

MOD_LGUI: int = ¶

Undocumented

Value

MOD_LSHIFT: int = ¶

Undocumented

Value

MOD_RALT: int = ¶

Undocumented

Value

MOD_RCTRL: int = ¶

Undocumented

Value

MOD_RGUI: int = ¶

Undocumented

Value

MOD_RSHIFT: int = ¶

Undocumented

Value

SHIFT_CHARS = ¶

Undocumented

Value

set('ABCDEFGHIJKLMNOPQRSTUVWXYZ!@#$%^&*()_+{}|:"<>?~')

def _on_control_xfer_cb(self, stage, request): ¶

Control-transfer callback invoked by the USB stack for HID class requests.

Handles GET_DESCRIPTOR (HID report descriptor), SET_IDLE / SET_PROTOCOL, and GET_PROTOCOL requests required by the HID class specification.

Parameters
stage:`int`	Transfer stage (1 = SETUP, 3 = ACK).
request:`bytes`	Raw 8-byte SETUP packet.

Returns
`bytes, bool`	Requested data, True to ACK with no data, or False to stall.

def _on_xfer_cb(self, ep, res, num_bytes): ¶

Transfer-complete callback invoked by the USB stack.

Sets _xfer_done when the HID IN endpoint (0x83) finishes so that _wait can unblock.

Parameters
ep:`int`	Endpoint address that completed the transfer.
res:`int`	Result code from the USB stack.
num_bytes:`int`	Number of bytes transferred.

def _wait(self, timeout_ms=500): ¶

Block until the previous HID transfer completes or the timeout expires.

Parameters
timeout_ms:`int`	Maximum number of milliseconds to wait. Defaults to 500.

Returns
`bool`	True if the transfer completed within the timeout, False otherwise.

_manufacturer = ¶

Undocumented

_product = ¶

Undocumented

_serial = ¶

Undocumented

_usbdev = ¶

Undocumented

_xfer_done: bool = ¶

Undocumented