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_allowlistAPI 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.
-
Open your serial terminal to access the USB console:
# The serial port name can vary # Or run: minicom -D /dev/ttyUSB0 tio /dev/ttyUSB0 -
Type
helpin the console:bp32> help
Use these allowlist console commands:
allowlist_list: List allowlist addressesallowlist_add <bt addr>: Add an address to the allowlistallowlist_remove <bt addr>: Remove an address from the allowlistallowlist_enable <0 | 1>: Disable (0) or enable (1) the allowlist
Watch the demonstration video:
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.
-
Verify that your controller is not already on these lists:
-
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.
- Started the Unijoysticle project (WiFi gamepad for Commodore 64) on 2016-03-28.
- Added Bluetooth support on 2019-01-02.
- Created the Unijoysticle2 repository on 2019-02-06.
- Published firmware release v0.1.0 on 2019-04-27.
- Renamed the firmware to Bluepad32 in November 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