Skip to main content
Version: Matrix OS 4.0 🚧

HID API

MatrixOS::HID exposes USB HID helpers for keyboard, gamepad, and Raw HID reports.

This API only covers USB HID. Bluetooth HID is not part of the current public C++ API.

The public declarations are in OS/MatrixOS.h and the implementations are in OS/HID/.

Keyboard​

MatrixOS::HID::Keyboard::Tap​

bool Tap(KeyboardKeycode keycode, uint16_t lengthMs = 100);

Presses a key, waits for lengthMs, then releases it.

MatrixOS::HID::Keyboard::Press​

bool Press(KeyboardKeycode keycode);

Adds a key to the active keyboard report.

MatrixOS::HID::Keyboard::Release​

bool Release(KeyboardKeycode keycode);

Removes a key from the active keyboard report.

MatrixOS::HID::Keyboard::ReleaseAll​

void ReleaseAll(void);

Releases all active keyboard keys.

Gamepad​

Buttons​

void Tap(uint8_t buttonId, uint16_t lengthMs = 100);
void Press(uint8_t buttonId);
void Release(uint8_t buttonId);
void ReleaseAll(void);
void Button(uint8_t buttonId, bool state);
void Buttons(uint32_t buttonMask);

buttonId selects a bit in the 32-bit gamepad button mask. Buttons() replaces the whole button mask.

Axes​

void XAxis(int16_t value);
void YAxis(int16_t value);
void ZAxis(int16_t value);
void RXAxis(int16_t value);
void RYAxis(int16_t value);
void RZAxis(int16_t value);

Axis values are signed 16-bit values. The intended range is -32767..32767.

D-Pad​

void DPad(GamepadDPadDirection direction);

Sets the gamepad D-pad direction. See GamepadDPadDirection.

RawHID​

Raw HID uses report ID 0xFF for application-level reports. The report payload size is 63 bytes.

MatrixOS::HID::RawHID::Get​

size_t Get(uint8_t** report, uint32_t timeoutMs = 0);

Receives one Raw HID report.

Parameters:

  • report: receives a pointer to the report buffer when data is available.
  • timeoutMs: maximum time to wait, in milliseconds.

Returns: number of bytes received. A return value of 0 means no report was available before the timeout.

MatrixOS::HID::RawHID::Send​

bool Send(const vector<uint8_t>& report);

Sends one Raw HID report on report ID 0xFF.

Parameters:

  • report: report payload bytes. The maximum payload size is 63 bytes; shorter reports are padded with zeros.

Returns: true when the report was queued for sending.

Comments