NAME CHANGE IN LIBRARAY MANAGER - PLEASE READ

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 ESP32_BLE_Gamepad upon installation due 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 ESP32_BLE_Gamepad folder within your libraries folder.

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

ESP32-BLE-Gamepad

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.

Features

• Button press (64 buttons)
• Button release (64 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)
• Report optional battery level to host (basically works, but it doesn't show up in Android's status bar)
• Customize Bluetooth device name/manufacturer
• Compatible with Windows
• Compatible with Android (Android OS maps default buttons / axes / hats slightly differently than Windows)
• Compatible with Linux
• Compatible with MacOS X
• Compatible with iOS (No - not even for accessibility switch - This is not a “Made for iPhone” (MFI) compatible device)

Installation

• (Make sure you can use the ESP32 with the Arduino IDE. Instructions can be found here.)
• Download the latest release of this library from the release page.
• In the Arduino IDE go to "Sketch" -> "Include Library" -> "Add .ZIP Library..." and select the file you just downloaded.
• You can now go to "File" -> "Examples" -> "ESP32 BLE Gamepad" and select the example to get started.

Example

/*
 * 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: 
 * DPAD_CENTERED, DPAD_UP, DPAD_UP_RIGHT, DPAD_RIGHT, DPAD_DOWN_RIGHT, DPAD_DOWN, DPAD_DOWN_LEFT, DPAD_LEFT, DPAD_UP_LEFT
 * (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.press(BUTTON_5);
    bleGamepad.press(BUTTON_32);
    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.release(BUTTON_5);
    bleGamepad.setAxes(-32767, -32767, -32767, -32767, 0, 0, 0, 0, DPAD_CENTERED, HAT_CENTERED, HAT_CENTERED, HAT_CENTERED);
    delay(500);
  }
}

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. bleGamepad.setBatteryLevel(50) (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 Espressif.

Credits

Credits to T-vK as this library is based on his ESP32-BLE-Mouse library (https://github.com/T-vK/ESP32-BLE-Mouse) that he provided.

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

Notes

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

You might also be interested in:

• ESP32-BLE-Mouse
• ESP32-BLE-Keyboard