ESPHome BLE Keyboard

Custom esphome component to implement a virtual BLE keyboard.

More info

• Base configuration
  • Requirements
  • Adding a component
  • Configuration
  • Actions
    • ble_keyboard.print
    • ble_keyboard.press
    • ble_keyboard.release
    • ble_keyboard.combination
    • ble_keyboard.start
    • ble_keyboard.stop
• Supported OS
• Keys
  • Default
  • Media
• Entities
• Cookbook
  • Sending a simple message
  • Pressing the ENTER key
  • Press CTRL + ALT + DELETE
  • Press CTRL + A
  • Lock an iPad
• Examples
  • esp32
  • esp32c3
• Credits

Supported OS

OS	Description
Windows	Fully supported
Linux	Fully supported
Android	Fully supported
MacOS	It does not work stably
IOS	It does not work stably

Base configuration

Requirements

• Board: esp32, esp32s2, esp32s3, esp32c3 and esp32h2;
• Framework: arduino.

Adding a component

external_components:
  - source: github://zachdekoning/esphome-blekeyboard

Enable BT support (required for ESPHome 2025.10+)

As of ESPHome 2025.10+ onwards, you must manually enable 'CONFIG_BT_ENABLED' in the framework sdkconfig_options

framework:
  type: arduino
  version: latest
  sdkconfig_options:
    CONFIG_BT_ENABLED: "y"

Configuration

ble_keyboard:
  id: mamontech_keyboard
  name: "MamonTechKeyboard"
  manufacturer_id: "MamonTech"
  battery_level: 50
  reconnect: true
  advertise_on_start: true
  buttons: true
  use_default_libs: false
  pairing_code: 123456

• id (Optional, string): Component ID. Needed for action;
• name (Optional, string): Keyboard name (default: Esp32BleKeyboard);
• manufacturer_id (Optional, string): Keyboard manufacturer (default: Esp32BleKeyboard);
• battery_level (Optional, int): Keyboard battery level (default: 100);
• reconnect (Optional, bool): Automatic reconnect service after disconnecting the device. (default: true);
• advertise_on_start (Optional, bool): Automatic advertisement when the ESP device starts. (default: true);
• buttons (Optional, bool): Whether to add separate buttons for keys (default: true);
• use_default_libs (Optional, bool): Whether to use the arduino standard library. (default: false).
• pairing_code (Optional, int): The pairing code required to be entered on the connecting device. (default: 123456).

Controlling keyboard availability when advertise_on_start is False

By default, the keyboard advertises its existence on start. You can turn this off, but this creates a problem — how to ensure that the keyboard is available on demand?

In your ESP description, you can create a switch that does exactly that:

globals:
  - id: keyboard_enabled
    type: bool
    restore_value: no
    initial_value: "false"

switch:
  - platform: template
    name: Enabled
    icon: mdi:power
    lambda: |-
      return id(keyboard_enabled);
        return true;
      } else {
        return false;
      }
    turn_on_action:
      - ble_keyboard.start: le_keyboard
      - globals.set:
           id: keyboard_enabled
           value: "true"
    turn_off_action:
      - ble_keyboard.stop: le_keyboard
      - globals.set:
           id: keyboard_enabled
           value: "false"

When toggled on, the switch will start the keyboard and begin advertising it. When toggled off, the keyboard will disconnect all clients and stop advertising — ensuring clients cannot reconnect.

Actions

ble_keyboard.print

Print arbitrary text.

ble_keyboard.print:
  id: my_ble_keyboard 
  text: "hello"

• id (Required, string): Component ID;
• text (Required, string): The text to be printed. Supports lambda.

ble_keyboard.press

Press a key.

ble_keyboard.press:
  id: my_ble_keyboard 
  code: 0x80

For media keys:

ble_keyboard.press:
  id: my_ble_keyboard 
  code:
    - 0
    - 1

• id (Required, string): Component ID;
• code (Required, int|list[int]): Key code. Supports lambda for int only.

ble_keyboard.release

Release keys.

ble_keyboard.release: my_ble_keyboard

ble_keyboard.combination

Press a key combination.

ble_keyboard.combination:
  id: my_ble_keyboard
  delay: 8
  keys:
    - 0x80 # Left CTRL
    - "a"

• id (Required, string): Component ID;
• delay (Required, int): Delay between clicks. Supports lambda;
• keys (Required, list[int, string]): Key list. Doesn't support lambda.

ble_keyboard.start

Start advertising.

ble_keyboard.start: my_ble_keyboard

ble_keyboard.stop

Stop advertising and disable customers.

ble_keyboard.stop: my_ble_keyboard

Credits

• Thanks to all ESPHome contributors;
• Thanks to @T-vK for the ESP32-BLE-Keyboard library;
• Thanks to @h2zero for the NimBLE-Arduino library.