键盘输入 Cluster（KeypadInput）

Cluster ID: 0x0509  |  所在 Endpoint: 媒体端点（电视、机顶盒等）

KeypadInput 负责接收遥控器和外部控制端的按键输入 —— 方向导航、数字键、媒体控制键、颜色功能键等。 它是智能电视、机顶盒等媒体设备的核心交互 Cluster，让手机 App 可以充当遥控器使用。 按键编码沿用 HDMI-CEC 标准（CEC Key Code），覆盖了遥控器上常见的所有按键。

命令（Commands）

KeypadInput Cluster 只有 1 个命令和 1 个响应。控制端发送 SendKey，设备返回 SendKeyResponse 表示处理结果。

SendKey —— 发送按键（0x00）

向设备发送一个 CEC 按键码，模拟遥控器按键操作。 设备收到后根据当前状态处理按键，并返回 SendKeyResponse 告知处理结果。

↑ 返回命令列表

SendKeyResponse —— 按键响应（0x01）

设备对 SendKey 命令的响应，告知控制端按键是否被成功处理。

// SendKey 命令示例
// 发送"确认"键（Select = 0x00）
{
  "KeyCode": 0       // CecKeyCode.Select
}

// 设备返回 SendKeyResponse
{
  "Status": 0        // StatusEnum.Success
}

↑ 返回命令列表

枚举定义

StatusEnum

SendKeyResponse 的处理结果。

CecKeyCode（CEC 按键码）

沿用 HDMI-CEC 标准的按键码定义，覆盖遥控器上常见的所有按键。 按功能分为以下几组，方便按需查阅。

导航键（NV 特性）

方向导航、确认、返回、菜单等基础交互按键，是遥控器最核心的操作区域。

数字键（NK 特性）

0~9 数字输入和 Enter 确认，用于频道号输入、密码输入等场景。

媒体控制键

播放、暂停、快进、快退、录制等媒体播放控制按键。

位置 / 频道键（LK 特性）

频道切换、收藏频道、节目指南等与频道定位相关的按键。

电源 / 音量键

设备电源控制和音量调节。这些按键通常不受 Feature 限制，大多数设备都支持。

颜色功能键

遥控器上的四色快捷键（红、绿、黄、蓝），功能由当前界面上下文决定。

Feature 位图

KeypadInput Cluster 通过 FeatureMap（0xFFFC）声明设备支持的按键类别：

示例数据

KeypadInput Cluster 没有应用属性，以下是读取 FeatureMap 判断设备能力的示例：

{
  // --- Feature Map ---
  "0xFFFC": 7          // FeatureMap = 0b111（NV + LK + NK 全部启用）

  // KeypadInput 没有应用属性，
  // 只通过 SendKey 命令接收按键输入。
  // 读取 FeatureMap 可判断设备支持哪些按键类别。
}

常见场景