版本：Matrix OS 3.0

HID API

概述

Matrix OS 中的 HID（人机接口设备）系统允许设备模拟键盘、手柄和自定义通信协议的 USB HID 设备。HID API 可通过 MatrixOS.HID 访问，包含针对不同设备类型的多个子模块。

Python HID API 实现位于 Applications/Python/PikaPython/MatrixOS_HID.py，类型提示位于 Applications/Python/PikaPython/_MatrixOS_HID.pyi。

`MatrixOS.HID.Ready`

def Ready() -> bool

检查 HID 子系统是否准备就绪。

返回值：

bool：HID 准备就绪时返回 True，否则返回 False

示例：

if MatrixOS.HID.Ready():
    print("HID 系统已准备就绪")
    # 可以安全使用 HID 功能
else:
    print("HID 系统不可用")

HID 子模块

Keyboard API - 键盘输入设备

键盘 HID 接口可向连接的设备发送键盘输入。详细信息参见 Keyboard 文档：

按键按下和释放事件
键盘快捷键和组合键
文本输入模拟
功能键和特殊键

示例：

if MatrixOS.HID.Ready():
    # 输入字母 'A'
    MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_A)

    # 发送 Ctrl+C 快捷键
    MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
    MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_C)
    MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_C)
    MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)

Gamepad API - 游戏控制器设备

手柄 HID 接口让设备表现为游戏控制器。详细信息参见 Gamepad 文档：

按钮映射和状态
模拟摇杆模拟
方向键控制
手柄特定功能

RawHID API - 自定义 HID 通信

原始 HID 接口提供自定义通信协议。详细信息参见 RawHID 文档：

自定义数据协议
双向通信
应用特定消息传递
原始数据传输

HID 设备管理

检查 HID 状态

def check_hid_status():
    """检查各种 HID 接口是否准备就绪"""
    if MatrixOS.HID.Ready():
        print("✓ HID 系统已准备就绪")

        # 测试键盘可用性
        try:
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_A)
            print("✓ 键盘 HID 正常工作")
        except:
            print("✗ 键盘 HID 不可用")
    else:
        print("✗ HID 系统未准备就绪")

check_hid_status()

HID 模式检测

def detect_hid_capabilities():
    """检测可用的 HID 功能"""

    capabilities = {
        "keyboard": False,
        "gamepad": False,
        "rawhid": False
    }

    if MatrixOS.HID.Ready():
        # 测试每个 HID 接口
        try:
            # 测试键盘
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_A)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_A)
            capabilities["keyboard"] = True
        except:
            pass

        # 其他功能测试将在此处添加

    return capabilities

caps = detect_hid_capabilities()
print("可用的 HID 功能：", caps)

集成示例

多模式 HID 控制器

def multi_modal_controller():
    """使用多个 HID 接口的示例"""

    mode = "keyboard"  # keyboard, gamepad

    print(f"多模式 HID 控制器 - 模式：{mode}")
    print("按键进行交互，按键 63 切换模式")

    while True:
        if not MatrixOS.HID.Ready():
            print("HID 未准备就绪，重新尝试...")
            MatrixOS.SYS.DelayMs(1000)
            continue

        key_event = MatrixOS.KeyPad.Get(100)
        if key_event is not None:
            key_id = key_event.ID()
            key_info = key_event.KeyInfo()

            if key_info.Active():
                if key_id == 63:  # 模式切换按键
                    modes = ["keyboard", "gamepad"]
                    current_idx = modes.index(mode)
                    mode = modes[(current_idx + 1) % len(modes)]
                    print(f"已切换到 {mode} 模式")

                elif mode == "keyboard":
                    # 键盘模式 - 将按键映射到字母
                    if key_id < 26:  # A-Z
                        keycode = getattr(KeyboardKeycode, f"KEY_{chr(65 + key_id)}")
                        MatrixOS.HID.Keyboard.Tap(keycode)

                elif mode == "gamepad":
                    # 手柄模式 - 映射到手柄按钮
                    print(f"手柄按钮 {key_id} 被按下")

multi_modal_controller()

键盘宏系统

def keyboard_macro_system():
    """使用 HID 接口的键盘宏系统"""

    macros = {
        # 键盘宏
        0: {"name": "复制", "action": "ctrl+c"},
        1: {"name": "粘贴", "action": "ctrl+v"},
        2: {"name": "撤销", "action": "ctrl+z"},
        3: {"name": "重做", "action": "ctrl+y"},
        8: {"name": "全选", "action": "ctrl+a"},
        9: {"name": "保存", "action": "ctrl+s"},
        10: {"name": "查找", "action": "ctrl+f"},
        16: {"name": "Alt+Tab", "action": "alt+tab"},
    }

    def execute_macro(macro):
        """执行键盘宏"""
        action = macro["action"]

        if action == "ctrl+c":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_C)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "ctrl+v":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_V)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "ctrl+z":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_Z)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "ctrl+y":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_Y)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "ctrl+a":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_A)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "ctrl+s":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_S)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "ctrl+f":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_CTRL)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_F)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_CTRL)
        elif action == "alt+tab":
            MatrixOS.HID.Keyboard.Press(KeyboardKeycode.KEY_LEFT_ALT)
            MatrixOS.HID.Keyboard.Tap(KeyboardKeycode.KEY_TAB)
            MatrixOS.HID.Keyboard.Release(KeyboardKeycode.KEY_LEFT_ALT)

    print("键盘宏系统激活")
    print("可用宏：")
    for key_id, macro in macros.items():
        xy = MatrixOS.KeyPad.ID2XY(key_id)
        print(f"  按键 ({xy.x},{xy.y}): {macro['name']}")

    # 点亮宏按键
    for key_id in macros.keys():
        xy = MatrixOS.KeyPad.ID2XY(key_id)
        MatrixOS.LED.SetColor(xy, Color(0, 255, 0), 150)
    MatrixOS.LED.Update(255)

    while True:
        if MatrixOS.HID.Ready():
            key_event = MatrixOS.KeyPad.Get(100)
            if key_event is not None:
                key_id = key_event.ID()
                key_info = key_event.KeyInfo()

                if key_info.Active() and key_id in macros:
                    print(f"执行宏：{macros[key_id]['name']}")
                    execute_macro(macros[key_id])

                    # 视觉反馈
                    xy = MatrixOS.KeyPad.ID2XY(key_id)
                    MatrixOS.LED.SetColor(xy, Color(255, 255, 255), 255)
                    MatrixOS.LED.Update(255)
                    MatrixOS.SYS.DelayMs(150)
                    MatrixOS.LED.SetColor(xy, Color(0, 255, 0), 150)
                    MatrixOS.LED.Update(255)

keyboard_macro_system()

HID 模式和行为

HID 功能取决于各种系统条件：

USB 连接：大多数 HID 功能需要活动的 USB 连接
主机操作系统支持：不同操作系统可能对 HID 设备有不同处理方式
设备配置：HID 功能取决于设备配置和构建选项
接口优先级：某些 HID 接口可能具有优先级
电源管理：HID 操作可能影响功耗和睡眠模式

概述​

MatrixOS.HID.Ready​

HID 子模块​

Keyboard API - 键盘输入设备​

Gamepad API - 游戏控制器设备​

RawHID API - 自定义 HID 通信​

HID 设备管理​

检查 HID 状态​

HID 模式检测​

集成示例​

多模式 HID 控制器​

键盘宏系统​

HID 模式和行为​

Comments

概述