⌨️ BLE Keyboard Keycodes

espidf_ble_keyboard · ESPHome Component Reference

💡 Looking for named actions? sleep shutdown mute volume_up play_pause and more are documented in the README.
Syntax
action: "combo:<modifier_hex>:<keycode_hex>"

"combo:0x00:0x04" # tap 'a'
"combo:0x02:0x04" # shift + a → 'A'
"combo:0x08:0x15" # Win + R (Run dialog)
"combo:0x01:0x06" # Ctrl + C (Copy)
"Hello World" # type a string directly
"ctrl_alt_del" # built-in shortcut

Modifier Keys

ModifierHex
None0x00
Left Ctrl0x01
Left Shift0x02
Left Alt0x04
Left GUI / Win / Cmd0x08
Right Ctrl0x10
Right Shift0x20
Right Alt / AltGr0x40
Right GUI / Win / Cmd0x80
Combine by adding values: Ctrl+Shift = 0x01+0x02 = 0x03

Function Keys

KeyHexKeyHex
F10x3AF70x40
F20x3BF80x41
F30x3CF90x42
F40x3DF100x43
F50x3EF110x44
F60x3FF120x45
Example: Alt+F4 = combo:0x04:0x3D

Letter Keys A–Z

KeyCodeKeyCodeKeyCode
a / A0x04j / J0x0Ds / S0x16
b / B0x05k / K0x0Et / T0x17
c / C0x06l / L0x0Fu / U0x18
d / D0x07m / M0x10v / V0x19
e / E0x08n / N0x11w / W0x1A
f / F0x09o / O0x12x / X0x1B
g / G0x0Ap / P0x13y / Y0x1C
h / H0x0Bq / Q0x14z / Z0x1D
i / I0x0Cr / R0x15
Uppercase: add modifier 0x02 (Left Shift). e.g. combo:0x02:0x04 = A

Number Keys 0–9

KeyCodeShifted
10x1E!
20x1F@
30x20#
40x21$
50x22%
60x23^
70x24&
80x25*
90x26(
00x27)

Special & Navigation Keys

KeyCodeKeyCode
Enter0x28Up Arrow0x52
Escape0x29Down Arrow0x51
Backspace0x2ALeft Arrow0x50
Tab0x2BRight Arrow0x4F
Space0x2CInsert0x49
Caps Lock0x39Delete (Fwd)0x4C
Print Screen0x46Home0x4A
Scroll Lock0x47End0x4D
Pause / Break0x48Page Up0x4B
Menu / App0x65Page Down0x4E

Punctuation & Symbols

KeyCodeShifted
- / _0x2D_
= / +0x2E+
[ / {0x2F{
] / }0x30}
\ / |0x31|
; / :0x33:
' / "0x34"
` / ~0x35~
, / <0x36<
. / >0x37>
/ / ?0x38?

Numpad Keys

KeyCodeKeyCode
Numpad 00x62Numpad 60x5E
Numpad 10x59Numpad 70x5F
Numpad 20x5ANumpad 80x60
Numpad 30x5BNumpad 90x61
Numpad 40x5CNumpad .0x63
Numpad 50x5DNumpad Enter0x58
Numpad +0x57Numpad -0x56
Numpad *0x55Numpad /0x54
Num Lock0x53

Common Shortcuts

Actionaction: value
Win + R (Run)combo:0x08:0x15
Win + L (Lock)combo:0x08:0x0F
Win + D (Desktop)combo:0x08:0x07
Win + E (Explorer)combo:0x08:0x08
Ctrl + C (Copy)combo:0x01:0x06
Ctrl + V (Paste)combo:0x01:0x19
Ctrl + Z (Undo)combo:0x01:0x1D
Ctrl + A (Select All)combo:0x01:0x04
Alt + F4 (Close)combo:0x04:0x3D
Alt + Tab (Switch)combo:0x04:0x2B
Ctrl+Shift+Esc (Tasks)combo:0x03:0x29
Ctrl + Alt + Delctrl_alt_del

Consumer Control Codes — consumer:0x0192

Application Launch
AppCode
Calculator0x0192
Email Client0x018A
File Explorer0x0194
Media Player0x0183
Browser Home0x0223
Browser Search0x0221
Browser Bookmarks0x022A
Screen Saver0x019E
Control Panel0x019F
Task Manager0x01A9
Media & Volume
ActionCode
Play / Pause0x00CD
Stop0x00B7
Next Track0x00B5
Previous Track0x00B6
Mute0x00E2
Volume Up0x00E9
Volume Down0x00EA
Fast Forward0x00B3
Rewind0x00B4
Brightness Up0x006F
Brightness Down0x0070
Use named actions for power: sleep, shutdown, hibernate are more reliable than consumer codes for system power.

Mouse Actions — Report ID 4

Named Actions
ActionValue
Left Clickleft_click
Right Clickright_click
Middle Clickmiddle_click
Parameterised Actions
FormatExample
Click by maskmouse_click:0x01
Move cursormouse_move:50:-20
Scroll wheelmouse_scroll:3
Button mask: 0x01 = left, 0x02 = right, 0x04 = middle. Combine for simultaneous buttons. Move/scroll values: -127 to 127 (relative).

Host Switching

ActionDescription
switch_host:0Switch to host slot 0–9. Reconnects via directed advertising or advertises for new pairing.
forget_host:0Remove BLE bond for host slot 0–9 and clear the stored address.
Up to 10 host slots. Paired hosts are stored in NVS and persist across reboots. Dict format: type: switch_host, slot: 1.

YAML Button Example

button:
  - platform: espidf_ble_keyboard
    keyboard_id: ble_keyboard
    name: "Open Run Dialog"
    action: "combo:0x08:0x15"     # Win + R

  - platform: espidf_ble_keyboard
    keyboard_id: ble_keyboard
    name: "Type Hello"
    action: "Hello World"           # send a string directly

  - platform: espidf_ble_keyboard
    keyboard_id: ble_keyboard
    name: "Left Click"
    action: "left_click"            # mouse left click

  - platform: espidf_ble_keyboard
    keyboard_id: ble_keyboard
    name: "Ctrl+Alt+Del"
    action: "ctrl_alt_del"          # built-in action

  - platform: espidf_ble_keyboard
    keyboard_id: ble_keyboard
    name: "Ctrl+Shift+A"
    action: "combo:0x03:0x04"     # 0x01+0x02=0x03 (Ctrl+Shift), 0x04=A