X-Input (Xbox 360) controller example#

Presents the ESP32-S3 as a wired Xbox 360 controller over the native USB-OTG peripheral, using espp::UsbDevice’s X-Input function. A PC’s XUSB driver binds it, so it shows up as an Xbox 360 controller in Windows’ “Set up USB game controllers” (joy.cpl) and any X-Input game, or under Linux xpad.

The demo sweeps the sticks/triggers in a circle and steps the face buttons A/B/X/Y one at a time each second, so you can see live input, and logs any rumble / LED reports the host sends back. The console/logs go to UART0 (with USB-Serial-JTAG as an early-boot secondary): on the ESP32-S3 the USB-Serial-JTAG controller shares the native USB port’s PHY with USB-OTG, so keeping the console on it would contend with the emulated controller interface and reboot-loop the device. Use a UART / USB-UART adapter on UART0 for idf.py monitor.

Build & flash#

X-Input is served by a custom TinyUSB application class driver built into the usb_device component, so it needs no built-in USB class enabled — the example’s sdkconfig.defaults disables CDC/vendor/HID entirely. Flash it to an ESP32-S3 and plug the native USB-OTG port into a PC:

idf.py -p <PORT> flash monitor   # console is on UART0 (USB-UART adapter)

Identity (emulation only)#

The device enumerates with Microsoft’s Xbox 360 VID/PID (0x045E:0x028E) and device class 0xFF/0xFF/0xFF — that identity is what makes the host’s XUSB driver bind it. These are Microsoft’s identifiers, for emulation / testing of your own device only; a shipped product must not enumerate under them.

Using it in your own code#

espp::UsbDevice::Config cfg;
espp::UsbDevice::XInputFunction xinput;      // default VID/PID = Xbox 360 wired
xinput.on_rumble = [](std::span<const uint8_t> data) { /* drive motors / LEDs */ };
cfg.xinput = xinput;                          // X-Input as the ONLY function
espp::UsbDevice usb(cfg);
std::error_code ec;
usb.initialize(ec);

espp::xinput::GamepadState state;
state.set(espp::xinput::Button::A, true);
state.lx = 20000;                             // left stick X
usb.update_xinput_state(state);                    // send a 20-byte input report

See components/usb_device/include/xinput.hpp for the GamepadState / Button API and the report layout, and the component README for how a PC recognizes the controller in each configuration.

Composite variant: a WebUSB console beside the controller#

A device that is also something else, a controller with a browser-based configuration console on a WebUSB vendor interface for instance, cannot present the retail controller’s identity: that identity (and a 0xFF device class) makes Windows’ Xbox driver take the whole device, hiding the other interface. The sdkconfig.composite variant builds that case:

idf.py -DSDKCONFIG_DEFAULTS="sdkconfig.defaults;sdkconfig.composite" -p <PORT> flash monitor

It enables TinyUSB’s built-in vendor class driver (the X-Input driver only claims its own interface, so the two coexist) and XINPUT_EXAMPLE_COMPOSITE, which adds a WebUSB vendor interface and gives the device Microsoft’s vendor ID with a product ID of its own (XINPUT_EXAMPLE_COMPOSITE_PID, 0x0E60 by default). The device keeps the composite identity (0x00 device class), and the Microsoft OS 2.0 descriptor that gives the vendor interface WinUSB also carries the XUSB10 compatible ID for the X-Input interface, which Windows’ Xbox 360 driver matches (USB\MS_COMP_XUSB10). Linux’s xpad matches the interface class under the Microsoft vendor ID.

The product ID must be one Windows’ Xbox driver INF does not list by hardware ID (the retail controllers’ 0x028E, 0x0719, … are), or that hardware-ID match again takes the whole device. Still Microsoft’s vendor ID: emulation / testing of your own device only.