Need help with ESP32-BLE-Gamepad?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

166 Stars 40 Forks 51 Commits 3 Opened issues


Bluetooth LE Gamepad library for the ESP32

Services available


Need anything else?

Contributors list


Hi all DIY gaming enthusiasts. Please be aware that the official name for this library in the library manager has changed from

ESP32 BLE Gamepad  -->  ESP32-BLE-Gamepad

This is to make it consistent with those who were also downloading it from GitHub and had 2 versions with different names and was leading to confusion. The library manager was automatically renaming the folder ESP32BLEGamepad upon installation bue to the spaces in the name. The library with the old name has been de-listed from the manager and only the new one remains. Please remove/delete the old version by deleting the ESP32BLEGamepad folder within your libraries folder.

Apologies for the early adopters, but it will save a lot of confusion moving forward.


Bluetooth LE Gamepad library for the ESP32

This library allows you to make the ESP32 act as a Bluetooth Gamepad and control what it does. E.g. move axes and press buttons

Due to popular demand, it supports a large array of buttons and axes. You only need to wire up the amount you'd like to use in your project. If you need more GPIO on your ESP32, you should search "Arduino GPIO expander". The i2c bus (uses just 2 GPIO pins) can be used to add multiple GPIO expanders to add all the GPIO you would ever need.


  • [x] Button press (64 buttons)
  • [x] Button release (64 buttons)
  • [x] 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))
  • [x] 2 Sliders (16 bit) (Slider 1 and Slider 2)
  • [x] 4 point of view hats (ie. d-pad plus 3 other hat switches)
  • [x] Report optional battery level to host (basically works, but it doesn't show up in Android's status bar)
  • [x] Customize Bluetooth device name/manufacturer
  • [x] Compatible with Windows
  • [x] Compatible with Android (Android OS maps default buttons / axes / hats slightly differently than Windows)
  • [x] Compatible with Linux
  • [x] Compatible with MacOS X
  • [ ] Compatible with iOS (No - not even for accessibility switch - This is not a “Made for iPhone” (MFI) compatible device)



 * This example turns the ESP32 into a Bluetooth LE gamepad that presses buttons and moves axis
 * Possible buttons are:
 * BUTTON_1 through to BUTTON_64 
 * Possible DPAD/HAT switch position values are: 
 * (or HAT_CENTERED, HAT_UP etc)
 * bleGamepad.setAxes takes the following int16_t parameters for the Left/Right Thumb X/Y, uint16_t for the Left/Right Triggers plus slider1 and slider2, and hat switch position as above: 
 * (Left Thumb X, Left Thumb Y, Right Thumb X, Right Thumb Y, Left Trigger, Right Trigger, Hat switch positions (hat1, hat2, hat3, hat4));

#include <blegamepad.h>

BleGamepad bleGamepad;

void setup() { Serial.begin(115200); Serial.println("Starting BLE work!"); bleGamepad.begin(); }

void loop() { if(bleGamepad.isConnected()) { Serial.println("Press buttons 5 and 32. Move all axes to max. Set DPAD (hat 1) to down right.");;; bleGamepad.setAxes(32767, 32767, 32767, 32767, 65535, 65535, 65535, 65535, DPAD_DOWN_RIGHT); //(can also optionally set hat2/3/4 after DPAD/hat1 as seen below) // All axes, sliders, hats can also be set independently. See the IndividualAxes.ino example delay(500);

Serial.println("Release button 5. Move all axes to min. Set DPAD (hat 1) to centred.");
bleGamepad.setAxes(-32767, -32767, -32767, -32767, 0, 0, 0, 0, DPAD_CENTERED, HAT_CENTERED, HAT_CENTERED, HAT_CENTERED);

} } </blegamepad.h>

By default, reports are sent on every button press/release or axis/slider/hat 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. To adjust the battery level later on you can simply call e.g.
(set battery level to 50%). By default the battery level will be set to 100%, the device name will be
ESP32 BLE Gamepad
and the manufacturer will be


Credits to T-vK as this library is based on his ESP32-BLE-Mouse library ( that he provided.

Credits to chegewara as the ESP32-BLE-Mouse library is based on this piece of code that he provided.


Use this Windows test app to test/see all of the buttons

You might also be interested in: - ESP32-BLE-Mouse - ESP32-BLE-Keyboard

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.