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:

• k (KeyboardKeycode): The key to write.

Returns:

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

---

MatrixOS::HID::Keyboard::Press

bool Press(KeyboardKeycode k);

Presses a keyboard key.

Parameters:

• k (KeyboardKeycode): The key to press.

Returns:

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

---

MatrixOS::HID::Keyboard::Release

bool Release(KeyboardKeycode k);

Releases a keyboard key.

Parameters:

• k (KeyboardKeycode): The key to release.

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:

• k (KeyboardKeycode): The key to remove.

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:

• b (GamepadKeycode): The button to press.

---

MatrixOS::HID::Gamepad::Release

void Release(GamepadKeycode b);

Releases a gamepad button.

Parameters:

• b (GamepadKeycode): The button to release.

---

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:

• d (GamepadDPadDirection): Direction for the D-pad.

---

Consumer

MatrixOS::HID::Consumer::Write

void Write(ConsumerKeycode c);

Writes a consumer control key event.

Parameters:

• c (ConsumerKeycode): The consumer control key to write.

---

MatrixOS::HID::Consumer::Press

void Press(ConsumerKeycode c);

Presses a consumer control key.

Parameters:

• c (ConsumerKeycode): The consumer control key to press.

---

MatrixOS::HID::Consumer::Release

void Release(ConsumerKeycode c);

Releases a consumer control key.

Parameters:

• c (ConsumerKeycode): The consumer control key to release.

---

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:

• s (SystemKeycode): The system key to write.

---

MatrixOS::HID::System::Press

void Press(SystemKeycode s);

Presses a system control key.

Parameters:

• s (SystemKeycode): The system key to press.

---

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.