Skip to main content

HID API

Overview​

The HID namespace provides APIs for controlling various Human Interface Device (HID) peripherals like keyboards, mice, gamepads, and more. It also includes support for Raw HID communication.

Unlike MIDI system. The HID system is more straightforward and does not require the user to manage ports. So all input from different source devices is mixed together and sent to the application as a single stream and all outbound messages are sent to all endpoints. (If there's a need for more complex routing, please let me know and I will consider adding support for it.)

This API only supports USB HID. Bluetooth HID are not supported at this time.

The header file for this API is part of os/MatrixOS.h and the implementation is in os/system/HID/.

Keyboard​

MatrixOS::HID::Keyboard::Write​

bool Write(KeyboardKeycode k);

Writes a keyboard key event.

Parameters:

Returns:

  • bool: true if the event was written successfully, otherwise false.

MatrixOS::HID::Keyboard::Press​

bool Press(KeyboardKeycode k);

Presses a keyboard key.

Parameters:

Returns:

  • bool: true if the key press was successful, otherwise false.

MatrixOS::HID::Keyboard::Release​

bool Release(KeyboardKeycode k);

Releases a keyboard key.

Parameters:

Returns:

  • bool: true if the key release was successful, otherwise false.

MatrixOS::HID::Keyboard::Remove​

bool Remove(KeyboardKeycode k);

Removes a key event from the active key list.

Parameters:

Returns:

  • bool: true if the key was removed successfully, otherwise false.

MatrixOS::HID::Keyboard::ReleaseAll​

void ReleaseAll(void);

Releases all pressed keyboard keys.

Mouse​

MatrixOS::HID::Mouse::Click​

void Click(MouseKeycode b = MOUSE_LEFT);

Simulates a mouse click.

Parameters:

  • b (MouseKeycode, optional): The button to click. Defaults to MOUSE_LEFT.

MatrixOS::HID::Mouse::Press​

void Press(MouseKeycode b = MOUSE_LEFT);

Presses a mouse button.

Parameters:

  • b (MouseKeycode, optional): The button to press. Defaults to MOUSE_LEFT.

MatrixOS::HID::Mouse::Release​

void Release(MouseKeycode b = MOUSE_LEFT);

Releases a mouse button.

Parameters:

  • b (MouseKeycode, optional): The button to release. Defaults to MOUSE_LEFT.

MatrixOS::HID::Mouse::ReleaseAll​

void ReleaseAll(void);

Releases all mouse buttons.

MatrixOS::HID::Mouse::Move​

void Move(signed char x, signed char y, signed char wheel = 0);

Moves the mouse cursor.

Parameters:

  • x (signed char): Horizontal movement.
  • y (signed char): Vertical movement.
  • wheel (signed char, optional): Scroll wheel movement. Defaults to 0.

Touch​

MatrixOS::HID::Touch::Click​

void Click(MouseKeycode b = MOUSE_LEFT);

Simulates a mouse click in touch mode.

Parameters:

  • b (MouseKeycode, optional): The button to click. Defaults to MOUSE_LEFT.

MatrixOS::HID::Touch::Press​

void Press(MouseKeycode b = MOUSE_LEFT);

Presses a mouse button in touch mode.

Parameters:

  • b (MouseKeycode, optional): The button to press. Defaults to MOUSE_LEFT.

MatrixOS::HID::Touch::Release​

void Release(MouseKeycode b = MOUSE_LEFT);

Releases a mouse button in touch mode.

Parameters:

  • b (MouseKeycode, optional): The button to release. Defaults to MOUSE_LEFT.

MatrixOS::HID::Touch::MoveTo​

void MoveTo(signed char x, signed char y, signed char wheel = 0);

Moves the cursor to an absolute position in touch mode.

Parameters:

  • x (signed char): Horizontal position.
  • y (signed char): Vertical position.
  • wheel (signed char, optional): Scroll wheel movement. Defaults to 0.

MatrixOS::HID::Touch::Move​

void Move(signed char x, signed char y, signed char wheel = 0);

Moves the cursor relative to its current position in touch mode.

Parameters:

  • x (signed char): Horizontal movement.
  • y (signed char): Vertical movement.
  • wheel (signed char, optional): Scroll wheel movement. Defaults to 0.

Gamepad​

MatrixOS::HID::Gamepad::Press​

void Press(GamepadKeycode b);

Presses a gamepad button.

Parameters:

MatrixOS::HID::Gamepad::Release​

void Release(GamepadKeycode b);

Releases a gamepad button.

Parameters:

MatrixOS::HID::Gamepad::ReleaseAll​

void ReleaseAll(void);

Releases all pressed gamepad buttons.

MatrixOS::HID::Gamepad::Buttons​

void Buttons(uint32_t b);

Sets the state of all gamepad buttons.

Parameters:

  • b (uint32_t): Bitmask representing the state of all buttons.

MatrixOS::HID::Gamepad::XAxis​

void XAxis(int8_t a);

Sets the X-axis value for the gamepad.

Parameters:

  • a (int8_t): Value of the X-axis (range: -128 to 127).

MatrixOS::HID::Gamepad::YAxis​

void YAxis(int8_t a);

Sets the Y-axis value for the gamepad.

Parameters:

  • a (int8_t): Value of the Y-axis (range: -128 to 127).

MatrixOS::HID::Gamepad::ZAxis​

void ZAxis(int8_t a);

Sets the Z-axis value for the gamepad.

Parameters:

  • a (int8_t): Value of the Z-axis (range: -128 to 127).

MatrixOS::HID::Gamepad::RXAxis​

void RXAxis(int8_t a);

Sets the value of the right X-axis for the gamepad.

Parameters:

  • a (int8_t): Value of the right X-axis (range: -128 to 127).

MatrixOS::HID::Gamepad::RYAxis​

void RYAxis(int8_t a);

Sets the value of the right Y-axis for the gamepad.

Parameters:

  • a (int8_t): Value of the right Y-axis (range: -128 to 127).

MatrixOS::HID::Gamepad::RZAxis​

void RZAxis(int8_t a);

Sets the value of the right Z-axis for the gamepad.

Parameters:

  • a (int8_t): Value of the right Z-axis (range: -128 to 127).

MatrixOS::HID::Gamepad::DPad​

void DPad(GamepadDPadDirection d);

Sets the D-pad direction.

Parameters:

Consumer​

MatrixOS::HID::Consumer::Write​

void Write(ConsumerKeycode c);

Writes a consumer control key event.

Parameters:

MatrixOS::HID::Consumer::Press​

void Press(ConsumerKeycode c);

Presses a consumer control key.

Parameters:

MatrixOS::HID::Consumer::Release​

void Release(ConsumerKeycode c);

Releases a consumer control key.

Parameters:

MatrixOS::HID::Consumer::ReleaseAll​

void ReleaseAll(void);

Releases all pressed consumer control keys.

System​

MatrixOS::HID::System::Write​

void Write(SystemKeycode s);

Writes a system control key event.

Parameters:

MatrixOS::HID::System::Press​

void Press(SystemKeycode s);

Presses a system control key.

Parameters:

MatrixOS::HID::System::Release​

void Release(void);

Releases the last pressed system control key.

MatrixOS::HID::System::ReleaseAll​

void ReleaseAll(void);

Releases all pressed system control keys.

RawHID​

MatrixOS::HID::RawHID::Get​

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

Retrieves a 16 byte HID report from report ID 255.

Parameters:

  • report (uint8_t**): Pointer to store the retrieved report.
  • timeout_ms (uint32_t, optional): Timeout for retrieving the report in milliseconds. Defaults to 0.

Returns:

  • size_t: Size of the retrieved report.

MatrixOS::HID::RawHID::Send​

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

Sends a Raw HID report from report ID 255. The max report size is 16 bytes (extra bytes will be padded with zeros).

Parameters:

  • report (const vector<uint8_t>&): The report to send.

Returns:

  • bool: true if the report was sent successfully, otherwise false.

Comments