ARDUINO LIBRARY · ORIGINAL ESP32 · BLUETOOTH CLASSIC HID

DualShock 4,meet ESP32.

A native HID host for the Sony DualShock 4 on the original ESP32. Pair with SHARE + PS, read sticks, buttons, triggers, motion, touch and battery from a normal Arduino sketch. No console, no dongle, no extra dependencies.

Test your controller live Install the library

input report 0x1178 B full statesticks 0..255SSP just-works pairinglicense MIT

01Install

Two minutes from download to paired controller.

Add this repo as a .ZIP library (Sketch, Include Library), or clone it into your Arduino libraries folder.
Select the DOIT ESP32 DEVKIT V1 board, or any original ESP32 with Bluetooth Classic. S3, C3 and C6 boards have no Classic radio and refuse loudly instead of failing silently.
Flash File, Examples, DS4Arduino, BasicConnect and open Serial Monitor at 115200.
Hold SHARE + PS until the light bar flashes white. Watch for DS4 found, Connecting..., DS4 connected, then move the sticks.

02Minimal sketch

The whole public surface you need for most builds.

#include <DS4Arduino.h>

DS4Controller ds4;

void setup() {
    Serial.begin(115200);
    ds4.begin();
}

void loop() {
    ds4.update();
    if (!ds4.connected()) return;
    Serial.printf("LX=%d LY=%d RX=%d RY=%d\n",
        ds4.leftStickX(), ds4.leftStickY(),
        ds4.rightStickX(), ds4.rightStickY());
}

03API reference

Sticks and triggers read 0..255 (centre 128). Motion is raw int16. Battery is 0..10.

Call	Meaning
`begin() / end()`	Start/stop Bluetooth and discovery
`update()`	Drain and parse queued reports, every `loop()`
`connected()`	True once both HID channels are up
`statusText() / lastErrorText()`	Human-readable state and sticky error
`leftStickX/Y(), rightStickX/Y()`	Analog sticks
`l2(), r2()`	Analog triggers
`cross/circle/square/triangle()`	Face buttons
`l1/r1/l3/r3()`	Shoulders and stick clicks
`share/options/ps/touchpad()`	System buttons
`dpad() + dpadUp/Down/Left/Right()`	Hat 0..7, 8 means released
`gyroX/Y/Z(), accelX/Y/Z()`	Motion sensors
`touch0/1Active/X/Y()`	Touchpad contacts, 1920 by 942
`batteryLevel() / charging()`	Battery and charging flag
`setLED(r,g,b) / setRumble(small,large)`	Light bar and rumble over Bluetooth
`packetCount()`	Parsed-report counter, reveals drops

04Examples

Motor code lives in examples only, never in the core library.

BasicConnect

Bring-up

Connection banners, raw report ID and length, sticks, triggers, buttons, battery. Start here.

ControllerTest

Full input audit

Edge prints for every button, light-bar stepping on triangle, and 20 Hz $DS4 machine lines with checksums that feed the live tester.

$DS4,SEQ,LX,LY,RX,RY,L2,R2,B0,B1,B2,...*CS

RCCar

TB6612FNG car

Left-stick Y drives throttle, right-stick X steers with a differential mix. Pins: PWMA 5, AIN1 18, AIN2 19, PWMB 23, BIN1 21, BIN2 22, STBY 17.

05Troubleshooting

Errors are reported, never silent. Match your symptom:

Not supported on this hardware/core: Wrong board selected, or Bluetooth disabled. Use an original ESP32.
Never finds the DS4: The controller is not in flashing-white SHARE+PS mode. Move closer, unplug USB.
Connects then drops: Unstable 5 V supply is the usual cause. Brownouts kill the link first.
Only small reports, no gyro: Full 0x11 mode enables after the first output report, which the library sends on connect.
Stuck after switching hosts: Reset the controller with a paperclip for five seconds, then SHARE+PS again.