Bluetooth BLE HID (Keyboard & Mouse Emulation)

Every keyboard and mouse you've ever plugged into a computer speaks a language called HID (Human Interface Device) — it's how the computer knows 'a key was pressed' or 'the cursor moved.'…

Connectivity11 blocksMicroPythonC++

Every keyboard and mouse you've ever plugged into a computer speaks a language called HID (Human Interface Device) — it's how the computer knows "a key was pressed" or "the cursor moved." BLE HID lets your ESP32 pretend to be a wireless Bluetooth keyboard, mouse, or media remote — the computer or phone can't tell the difference, so there's nothing extra to install. It just works the moment you pair it, the same way a real Bluetooth keyboard does.


1. Real-World Uses

BLE HID is for projects that need to control a computer or phone directly, as if a person were typing or clicking:

  • A custom macro keyboard — one button press that types out a whole paragraph, a password, or a keyboard shortcut like Ctrl+C.
  • A wireless presentation clicker — big physical buttons wired to your board that send "Next Slide" (Right Arrow) or "Previous Slide" (Left Arrow) to whatever laptop is running the slideshow.
  • Accessibility devices — a single oversized button that sends Spacebar or Enter, useful for anyone who finds a normal keyboard hard to use.
  • A physical media remote — buttons that control Play/Pause, Volume, and Track Skip on a phone or laptop from across the room.
  • DIY game controllers — since a mouse click and cursor movement are just BLE HID reports, a joystick/button panel can drive simple games that only expect keyboard/mouse input.

2. Hardware Requirements & Compatible Boards

  • Compatible Boards: ESP32 only (boards: ['esp32'] — unlike BLE UART/Bluetooth in Section 7.3, this extension has no Pico W/2W support at all, not even as a no-op).
  • Supported Host Devices: Windows, macOS, Linux, Android, iOS — anything that accepts a standard Bluetooth keyboard/mouse.
  • Conflicts with: Bluetooth BLE UART and ESP-NOW (Sections 7.3/7.2) — you can't combine this extension's blocks with either of those in the same project (only one Bluetooth "personality" can run at a time).

3. Libraries Used

  • C++ (Arduino): ESP32-BLE-Keyboard + ESP32-BLE-Mouse — the standard community libraries for emulating BLE HID devices on ESP32.
  • MicroPython: no external import — OMS's code generator writes a complete, self-contained BLEHID class directly into your generated code the first time any BLE HID block is used. It talks to the radio through MicroPython's raw bluetooth module, registering a real HID GATT service with hand-built USB HID report descriptor bytes (the same low-level format ESP32-BLE-Keyboard/ESP32-BLE-Mouse use internally) — there's nothing to separately install.

4. Supported Blockly Blocks (11 Blocks)

Drawing the blocks…

5. Simulator Behavior

[!IMPORTANT] Same inert-but-crash-free gap as Wi-Fi, ESP-NOW, and BLE UART (Sections 7.1–7.3). OMS's browser Circuit Simulator has no real Bluetooth radio and no simulated host computer/phone to pair with, so:

  • Start BLE Keyboard/Mouse succeeds silently — it builds the HID service and starts advertising, but nothing is actually broadcasting over the air.
  • Is HID Connected? always returns false — no host ever connects.
  • Every keyboard/mouse/media block runs its "is connected" check, finds it false, and does nothing — no key ever actually presses, no cursor ever actually moves, in the simulator. All blocks generate fully correct, real code for actual ESP32 hardware — BLE HID can only be meaningfully tested by pairing a real, uploaded ESP32 with a real computer or phone, never through the Simulate button.
Bluetooth BLE HID (Keyboard & Mouse Emulation) — OMS Parts