KeypadInput Cluster
Cluster ID: 0x0509 |
Endpoint: Media endpoint (TV, set-top box, etc.)
KeypadInput receives key inputs from remote controls and external controllers — directional navigation, numeric keys, media control keys, color function keys, etc. It is the core interaction Cluster for media devices such as smart TVs and set-top boxes, allowing phone apps to serve as remote controls. Key codes follow the HDMI-CEC standard (CEC Key Code), covering all common remote control buttons.
KeypadInput uses three Features to indicate which key categories the device supports: NV (Navigation keys: directional, select, menu, etc.), LK (Location keys: channel numbers, favorites, etc.), NK (Number keys: 0~9, Enter, etc.). Check the FeatureMap before sending keys to avoid sending unsupported key categories.
Commands
The KeypadInput Cluster has only 1 command and 1 response. The controller sends SendKey, and the device returns SendKeyResponse with the processing result.
| ID | Name | Direction | Description |
|---|---|---|---|
0x00 |
SendKey | Client → Server | Send a key press to the device |
0x01 |
SendKeyResponse | Server → Client | Device processing result for SendKey |
SendKey — Send Key Press (0x00)
Sends a CEC key code to the device, simulating a remote control key press.
The device processes the key based on its current state and returns SendKeyResponse with the result.
| Parameter | Type | Description |
|---|---|---|
| KeyCode | CecKeyCode | Key code to send (see enum below) |
Usage Scenarios
When the phone app serves as a remote control, the user taps a directional or select key, and the app sends the corresponding CecKeyCode via SendKey to the TV.
For example, when the user presses "OK", it sends KeyCode = 0x00 (Select).
SendKeyResponse — Key Response (0x01)
The device's response to the SendKey command, indicating whether the key press was successfully processed.
| Field | Type | Description |
|---|---|---|
| Status | StatusEnum | Key processing result (see enum below) |
// SendKey command example
// Send "Select" key (Select = 0x00)
{
"KeyCode": 0 // CecKeyCode.Select
}
// Device returns SendKeyResponse
{
"Status": 0 // StatusEnum.Success
}
Controllers should handle exceptions based on StatusEnum:
on UnsupportedKey, grey out or hide the corresponding button in the UI;
on InvalidKeyInCurrentState, notify the user that the key is not available in the current state (e.g., pressing pause when not playing).
Enum Definitions
StatusEnum
Processing results for SendKeyResponse.
CecKeyCode (CEC Key Codes)
Key code definitions following the HDMI-CEC standard, covering all common remote control buttons. Grouped by function for easy reference.
Navigation Keys (NV Feature)
Directional navigation, select, back, menu, and other basic interaction keys — the core control area of the remote.
Number Keys (NK Feature)
0~9 numeric input and Enter confirmation, used for channel number entry, password input, etc.
Media Control Keys
Play, pause, fast-forward, rewind, record, and other media playback control keys.
Location / Channel Keys (LK Feature)
Channel switching, favorite channels, program guide, and other channel-related keys.
Power / Volume Keys
Device power control and volume adjustment. These keys are typically not limited by Features and are supported by most devices.
Color Function Keys
The four color shortcut keys on the remote (red, green, yellow, blue), with functions determined by the current UI context.
Only the most commonly used key codes are listed above. The complete CecKeyCode enum is defined in Matter 1.4 spec Section 9.10.4.1, with 80+ values including text input keys (F1~F5), audio selection, subtitle control, etc. In practice, only implement the keys used by the device and App UI.
Feature Bitmap
The KeypadInput Cluster declares supported key categories via FeatureMap (0xFFFC):
Devices do not necessarily support all keys. Check the FeatureMap before sending SendKey:
without NV, do not send directional or menu keys;
without NK, do not send numeric keys;
without LK, do not send channel-related keys.
Sending unsupported keys causes the device to return UnsupportedKey.
Example Data
The KeypadInput Cluster has no application attributes. Below is an example of reading the FeatureMap to determine device capabilities:
{
// --- Feature Map ---
"0xFFFC": 7 // FeatureMap = 0b111 (NV + LK + NK all enabled)
// KeypadInput has no application attributes,
// it only receives key input via the SendKey command.
// Reading FeatureMap determines which key categories the device supports.
}
KeypadInput is a "command-only" Cluster — it has no readable application attributes and interacts solely through the SendKey command.
The controller's remote UI should dynamically display key areas based on FeatureMap:
show the directional pad if NV is supported, show the numeric keypad if NK is supported, and show channel switching buttons if LK is supported.
Common Scenarios
Scenario 1: Phone app as remote control
- Read the device's
FeatureMap (0xFFFC)to determine supported key categories - Dynamically render the remote UI based on Features:
- NV enabled → show directional D-pad + select key + menu/back
- NK enabled → show numeric keypad (0~9 + Enter)
- LK enabled → show Channel +/- buttons and EPG entry
- The user clicks a key on the UI and sends
SendKey (0x00)with the corresponding CecKeyCode enum value - Check the
SendKeyResponseStatus:Success (0)— normal, no further action neededUnsupportedKey (1)— key not supported, mark as unavailable in the UIInvalidKeyInCurrentState (2)— not available in the current state, notify the user
Scenario 2: Voice assistant controls TV playback
- The user says "pause", and the voice assistant parses the intent as pause playback
- Send
SendKeywith KeyCode =0x43 (Pause) - The device returns
Successand playback pauses - The user says "resume playback" and sends
SendKeywith KeyCode =0x41 (Play) -
Note: If the device is on a menu screen instead of in playback state, sending Pause may return
InvalidKeyInCurrentState— the voice assistant should provide appropriate voice feedback