BadBLE

Bluetooth HID keyboard - DuckyScript over BLE

On this page

BadBLE runs DuckyScript payloads as a standard Bluetooth HID keyboard (HOGP). The device advertises as a BLE keyboard, you pair it with a phone, laptop, or tablet, and payloads (or live typing) play out as keystrokes on the paired host - no USB cable required.

Supported Devices

Enabled by default on Bluetooth-capable targets:

  • ESP32 (original)
  • ESP32-C3 / ESP32-C5 / ESP32-C6
  • ESP32-S3
  • ESP32-P4

ESP32-S2 is not supported (no Bluetooth radio).

Using BadBLE

Open BadBLE from the main menu on the device:

  • Run Script - pick a payload from /mnt/ghostesp/badble/ (or the built-in Ghost Art script, which needs no SD card). The device advertises and waits; once a host pairs, the popup flips from “Waiting” to “Running” and the script plays out. Cancel (tap anywhere, or confirm/back on joystick, Enter/Esc on keyboard, encoder press) stops it.
  • BLE Keyboard - live typing screen. Every key is forwarded to the paired host as you press it; exiting the screen stops BadBLE.
  • Set Name - change the advertised name (saved to NVS).
  • Status - current state, advertised name, and whether a host is connected.
  • Stop BadBLE - tear down the BLE profile; Wi-Fi/AP are restored.

The same feature is available from the CLI and the WebUI (BLE page → BadBLE tab).

Pairing

  • Pairing uses a “Just Works” exchange - no passkey to enter.
  • The device initiates pairing as soon as a host connects; accept the pairing/passkey-optional prompt on the host.
  • As with any BLE keyboard, the link must be encrypted before the host delivers keystrokes - pairing normally takes care of this automatically.
  • Default advertised name: GhostESP BadBLE.

Note: Only one host can be paired at a time. If the host drops, the device re-advertises so you can reconnect.

Script Files

  • Place scripts in /mnt/ghostesp/badble/
  • File extension: .txt (only .txt files are listed)
  • Size limit: 64 KB per script
  • The built-in Ghost Art script always appears first in the picker and runs without an SD card

CLI 

badble status
badble list
badble run <filename|"Ghost Art (Built-in)">
badble stop
badble keyboard_start
badble keyboard_stop
badble type <text>
badble keysend <modifier> <keycode>
badble name
badble set_name <text>

badble keyboard_start also accepts the alias badble start.

Limitations

  • BadBLE owns the BLE radio while active: BLE scans, the BLE bridge, and other BLE tools are unavailable until BadBLE is stopped.
  • BadBLE refuses to start while the BLE bridge (blebridge) is running.
  • The advertised name is limited to 31 characters and must be printable ASCII (0x20-0x7E); " and \ are rejected. badble type text is capped at 255 characters.
  • Live typing sends at most one key every 30 ms.
  • The HID device identifies as VID/PID 0x303A:0x4001.
  • Script execution waits until a host is connected.
  • BLE mouse/trackpad reports are not supported.