Skip to content

FAQ

Why can't I connect my DualShock or Switch controller to my ESP32-S3 or ESP32-C3?

TL;DR

Answer: ESP32-S3 and ESP32-C3 do not support the Bluetooth Classic protocol.

Only the original ESP32 chip supports Bluetooth Classic (BR/EDR). ESP32-S3, ESP32-C3, ESP32-C5, ESP32-C6, and ESP32-H2 do not support BR/EDR.

Switch, Wii, DualSense, and DualShock controllers use BR/EDR instead of BLE. Use an original ESP32 or a Pico W to connect BR/EDR controllers.

The following tables list chip and controller protocols. For the latest support list, see Supported gamepads.

Chip BR/EDR BLE
ESP32
ESP32-S3
ESP32-C3
ESP32-C5
ESP32-C6
ESP32-H2
Pico W
Pico 2 W

Supported Bluetooth gamepads and their protocols:

Gamepad BR/EDR BLE
DualSense (PS5)
DualShock 4 (PS4)
DualShock 3 (PS3)
Nintendo Switch Pro
Nintendo Switch JoyCons
Nintendo Wii U Pro
Nintendo Wii Remote
Nintendo Balance Board
Xbox Wireless * *
Xbox Adaptive *
Steam **
Stadia ***
Android **** ****
8BitDo
Atari
iCade
Nimbus
OUYA 1st gen

*: Xbox Controller Firmware v3.x and v4.x use BR/EDR. Firmware v5.x and newer use BLE.

**: Requires the Steam Controller Bluetooth firmware update.

***: Requires the Stadia Bluetooth firmware update.

****: Android controllers use either BR/EDR or BLE.

What are the supported boards?

TL;DR

Answer: Pico W and ESP32-family boards.

Bluepad32 supports Bluetooth-enabled Pico W and ESP32 processors.

On ESP32, Bluepad32 runs on the main processor, such as the Espressif ESP32-DevKitC.

If standard Arduino supports an ESP32 board, Bluepad32 also supports that board.

How do I pair one controller to one specific board?

TL;DR

Answer: Use the Bluetooth allowlist.

Suppose you want to control eight robots with eight separate controllers. Controller A must control only robot A, and controller B must control only robot B.

Use one of these two methods to configure the allowlist:

  • Call the uni_bt_allowlist API in your code
  • Run allowlist commands from the USB console

Use the uni_bt_allowlist API

Use these core functions from the uni_bt_allowlist API:

  • bool uni_bt_allowlist_add_addr(bd_addr_t addr);: Adds a Bluetooth address to the allowlist.
  • void uni_bt_allowlist_set_enabled(bool enabled);: Enables or disables the allowlist.

For the full API reference, see uni_bt_allowlist.h.

Complete example:

// Arduino sketch
// Include Uni API.
#include <uni.h>

// The address of the gamepad that is allowed to connect.
// You can add up to four entries.
static const char * controller_addr_string = "00:11:22:33:44:55";

void setup() {
    // Add the following lines inside setup():
    bd_addr_t controller_addr;

    // Parse human-readable Bluetooth address.
    sscanf_bd_addr(controller_addr_string, controller_addr);

    // Bluepad32 saves this address in Non-Volatile Storage (NVS).
    // The address persists across reboots.
    // Duplicate entries are ignored.
    // You can add up to four entries in the allowlist.
    uni_bt_allowlist_add_addr(controller_addr);

    // Enable the allowlist.
    // Bluepad32 also saves this setting in NVS.
    uni_bt_allowlist_set_enabled(true);
}

Use allowlist commands from the USB console

Note

Only the Arduino ESP-IDF Template project, the ESP-IDF raw API, and Unijoysticle provide the USB console.

  1. Open your serial terminal to access the USB console:

    # The serial port name can vary
    # Or run: minicom -D /dev/ttyUSB0
    tio /dev/ttyUSB0
    
  2. Type help in the console:

    bp32> help
    

Use these allowlist console commands:

  • allowlist_list: List allowlist addresses
  • allowlist_add <bt addr>: Add an address to the allowlist
  • allowlist_remove <bt addr>: Remove an address from the allowlist
  • allowlist_enable <0 | 1>: Disable (0) or enable (1) the allowlist

Watch the demonstration video:

asciicast

Bluepad32 saves allowlist addresses and the enabled state in Non-Volatile Storage (NVS). These settings persist when you reset the ESP32.

How do I detect when a gamepad is out of range?

TL;DR

Answer: Disconnect the controller if no data arrives within 5 seconds.

Bluetooth has a limited wireless range:

BR/EDR BLE
up to 100 meters up to 50 meters

When a gamepad moves out of range, the board stops receiving input packets. The Bluetooth stack can take 20 seconds or more to detect a lost link and close the connection.

Track the last update timestamp and disconnect the controller after a timeout:

// Arduino Sketch

void processControllers() {
    for (auto myController : myControllers) {
        if (myController && myController->isConnected()) {
            if (myController->hasData()) {
                // Process controller input
                processGamepad(myController);
                lastUpdate = millis();
            } else {
                // No data arrived from the controller.
                if ((millis() - lastUpdate) > 5000) {
                    // Stop the car if no data arrives for 5000 ms.
                    stopCar();
                    myController->disconnect();
                }
            }
        }
    }
}

void loop() {
    bool dataUpdated = BP32.update();
    if (dataUpdated) {
        processControllers();
    }

    vTaskDelay(1);
}

See GitHub Issue #42 for more details.

Can you add support for an unsupported controller?

TL;DR

Answer: Send us the controller hardware and we will try to add support.

  1. Verify that your controller is not already on these lists:

  2. If Bluepad32 does not support your controller, send a private message on Discord or file a feature request .

Follow this process to sponsor controller support:

  • Send a purchase link for the controller (such as Amazon or AliExpress).
  • Send the cost of the controller plus US shipping via PayPal , Ko-fi , Venmo , or an Amazon gift card.
  • We will buy the controller and attempt to add support. We cannot guarantee compatibility, especially for low-cost clone controllers.

Why does the internal Bluepad32 API use the uni prefix?

TL;DR

Answer: Legacy naming from the Unijoysticle2 project.

The Unijoysticle2 project originally combined hardware and firmware in a single repository. In November 2020, we ported the Unijoysticle firmware to the Adafruit AirLift module.

That port decoupled the firmware from the Unijoysticle2 hardware. We kept the uni prefix to minimize code changes across the internal C API.

The Bluepad32 Arduino C++ API does not use the uni prefix because it is a new interface.

Why does Bluepad32 use BTstack as the Bluetooth stack?

TL;DR

Answer: BTstack was the only Bluetooth Classic stack for ESP32 in 2019.

In January 2019, ESP32 lacked an open Bluetooth Classic (BR/EDR) HID host implementation.

We chose BlueKitchen BTstack instead of writing a custom stack. BTstack provides two major benefits:

  • Pico W also uses BTstack, which simplified the Pico W port.
  • BTstack runs on POSIX systems, which accelerates development for new controllers.

Which IDE should I use?

TL;DR

Answer: Use the IDE that matches your workflow.

Select an IDE based on your C and C++ experience:

  • Arduino IDE: Best for standard Arduino sketches.
  • Visual Studio Code: General-purpose editor that supports C and C++ through extensions.
  • CLion: Full-featured IDE for C and C++ development.

When did the Bluepad32 project start?

TL;DR

Answer: Bluetooth support started in 2019 from the 2016 Unijoysticle project, and took the name Bluepad32 in 2020.

timeline
        2016-03-28: First Unijoysticle commit, ESP8266 + WiFi only
        2019-01-02: Initial Unijoysticle ESP32 port, with Bluetooth support
        2019-02-06: Created Unijoysticle2 repo
        2019-04-27: Released v0.1.0, first public release
        2020-11-20: Released v2.0.0-beta0: Renamed to Bluepad32