ESP32 BLE Gamepad


This library allows you to make the ESP32 act as a Bluetooth gamepad and control what it does. The library uses ESP32 NimBLE for faster and lighter communication.


Using this library you can do the following:

  • Button press (128 buttons)

  • Button release (128 buttons)

  • Axes movement (6 axes (16 bit) (x, y, z, rZ, rX, rY) –> (Left Thumb X, Left Thumb Y, Right Thumb X, Right Thumb Y, Left Trigger, Right Trigger))

  • 2 Sliders (16 bit) (Slider 1 and Slider 2)

  • 4 point of view hats (ie. d-pad plus 3 other hat switches)

  • Simulation controls (rudder, throttle, accelerator, brake, steering)

  • Configurable HID descriptor

  • Report optional battery level to host (basically works, but it doesn’t show up in Android’s status bar)

  • Customize Bluetooth device name/manufacturer

  • Uses efficient NimBLE bluetooth library

  • Compatible with Windows

  • Compatible with Android (Android OS maps default buttons / axes / hats slightly differently than Windows)

  • Compatible with Linux (limited testing)

  • Compatible with MacOS X (limited testing)


  1. Add COMPONENT_DEPENDS += BLEGamepad to your application file.

  2. Add these lines to your application:

    #include <BleGamepad.h>
            BleGamepad bleGamepad;
            // ...
    } // namespace
    void init()
            // ...


By default, reports are sent on every button press/release or axis/slider/hat/simulation movement, however this can be disabled, and then you manually call sendReport on the gamepad instance as shown in the IndividualAxes.ino example.

There is also Bluetooth specific information that you can use (optional):

Instead of BleGamepad bleGamepad; you can do BleGamepad bleGamepad("Bluetooth Device Name", "Bluetooth Device Manufacturer", 100);. The third parameter is the initial battery level of your device. Adjusting the battery level later on doesn’t work. By default the battery level will be set to 100%, the device name will be ESP32 BLE Gamepad and the manufacturer will be Espressif.


Used by

SoC support

  • esp32

  • esp32c3

  • esp32s3

Submodule: ESP32-BLE-Gamepad