Skip to main content
Version: Matrix OS 4.0 🚧

HID API

Overview​

MatrixOS.HID exposes keyboard, gamepad, and RawHID helpers.

Use press(...) and release(...) when the key or button should stay active across multiple loop iterations. Use tap(...) for a short press-and-release action.

MatrixOS.HID.Keyboard.tap​

tap(keycode: int, length_ms: int = 100) -> bool

Presses and releases one keyboard key.

Parameters:

  • keycode: USB HID keyboard keycode.
  • length_ms: Press duration in milliseconds.

Returns:

  • bool: True when the tap was sent.

MatrixOS.HID.Keyboard.press​

press(keycode: int) -> bool

Presses one keyboard key and leaves it held.

Parameters:

  • keycode: USB HID keyboard keycode.

Returns:

  • bool: True when the press was sent.

MatrixOS.HID.Keyboard.release​

release(keycode: int) -> bool

Releases one keyboard key.

Parameters:

  • keycode: USB HID keyboard keycode.

Returns:

  • bool: True when the release was sent.

MatrixOS.HID.Keyboard.release_all​

release_all() -> None

Releases all pressed keyboard keys.

MatrixOS.HID.Gamepad.tap​

tap(button_id: int, length_ms: int = 100) -> None

Presses and releases one gamepad button.

Parameters:

  • button_id: Gamepad button ID.
  • length_ms: Press duration in milliseconds.

MatrixOS.HID.Gamepad.press​

press(button_id: int) -> None

Presses one gamepad button and leaves it held.

Parameters:

  • button_id: Gamepad button ID.

MatrixOS.HID.Gamepad.release​

release(button_id: int) -> None

Releases one gamepad button.

Parameters:

  • button_id: Gamepad button ID.

MatrixOS.HID.Gamepad.release_all​

release_all() -> None

Releases all gamepad buttons.

MatrixOS.HID.Gamepad.button​

button(button_id: int, state: bool) -> None

Sets one gamepad button state.

Parameters:

  • button_id: Gamepad button ID.
  • state: True for pressed, False for released.

MatrixOS.HID.Gamepad.buttons​

buttons(button_mask: int) -> None

Sets all gamepad button states from a bitmask.

Parameters:

  • button_mask: Bitmask of pressed buttons.

MatrixOS.HID.Gamepad.x_axis​

x_axis(value: int) -> None

Sets the gamepad X axis.

Parameters:

  • value: Axis value. Values are clamped to -32768..32767.

MatrixOS.HID.Gamepad.y_axis​

y_axis(value: int) -> None

Sets the gamepad Y axis.

Parameters:

  • value: Axis value. Values are clamped to -32768..32767.

MatrixOS.HID.Gamepad.z_axis​

z_axis(value: int) -> None

Sets the gamepad Z axis.

Parameters:

  • value: Axis value. Values are clamped to -32768..32767.

MatrixOS.HID.Gamepad.rx_axis​

rx_axis(value: int) -> None

Sets the gamepad RX axis.

Parameters:

  • value: Axis value. Values are clamped to -32768..32767.

MatrixOS.HID.Gamepad.ry_axis​

ry_axis(value: int) -> None

Sets the gamepad RY axis.

Parameters:

  • value: Axis value. Values are clamped to -32768..32767.

MatrixOS.HID.Gamepad.rz_axis​

rz_axis(value: int) -> None

Sets the gamepad RZ axis.

Parameters:

  • value: Axis value. Values are clamped to -32768..32767.

MatrixOS.HID.Gamepad.dpad​

dpad(direction: int) -> None

Sets the gamepad D-pad direction.

Parameters:

  • direction: Gamepad D-pad direction value.

MatrixOS.HID.RawHID.get​

get(timeout_ms: int = 0) -> bytes | None

Reads one RawHID report.

Parameters:

  • timeout_ms: Maximum time to wait in milliseconds. 0 is non-blocking.

Returns:

  • bytes | None: Report bytes, or None when no report is available.

MatrixOS.HID.RawHID.send​

send(data: bytes) -> bool

Sends one RawHID report.

Parameters:

  • data: Report bytes.

Returns:

  • bool: True when sent.

Keyboard And Gamepad Examples​

import MatrixOS

# Tap sends a press and release for a simple one-shot action.
MatrixOS.HID.Keyboard.tap(0x04)  # HID keycode for "a"
MatrixOS.HID.Gamepad.tap(1)

RawHID Echo Example​

import MatrixOS

# Poll once without blocking. Use a timeout if the app should wait.
report = MatrixOS.HID.RawHID.get(0)
if report:
    # Echo the exact report bytes back to the host.
    MatrixOS.HID.RawHID.send(report)

This echo pattern is useful for a custom host protocol.

Comments