Expand description
§xbox-controller-rs
This repository contains the ESP library, its transport-independent core, embedded examples, and a desktop inspector.
§ESP library
esp-xbox-controller connects an ESP32-C3 to an Xbox Series controller over BLE
and turns its HID notifications into useful controller state. The reusable
parser and state types live in the separate xbox-controller-core crate and are
re-exported by the ESP library.
§Examples
The examples are tested on the Seeed Studio XIAO ESP32-C3. This board costs around 6 euros that comes including an external antenna.
§Inspector
xbox-controller-inspector is a publishable Ubuntu AMD64 GUI for scanning and
connecting to a BLE controller, viewing its address and firmware revision,
diagnosing live inputs, and testing vibration. Install it with
cargo install xbox-controller-inspector. See the
tools/xbox-controller-inspector README
for BlueZ and Linux package requirements.
§Supported controller
The initial target is the standard Xbox Wireless Controller Model 1914, also known as the third-revision controller introduced with Xbox Series X|S in 2020. You can confirm the model number on the label inside the battery compartment. Model 1914 has a Share button, USB-C, and BLE HID-over-GATT support; see the Xbox Wireless Controller model summary.
Model 1914 and model 1708 with firmware 5.23.6.0 are the current test targets.
Before testing, connect the controller to Windows over USB and install the latest
firmware offered by the Xbox Accessories app. Do not downgrade
or try to install exactly 5.13.3143.0.
Models 1537 and 1697 do not support Bluetooth and cannot work with this BLE transport.
BLE notification bytes
|
v
esp_xbox_controller::parse_input_report()
|
v
XboxControllerState§Why separate parsing from BLE?
The report format does not depend on the radio or operating system. Keeping the
parser in its own allocation-free, default-no_std crate makes it easy to test
on a desktop and reuse with any embedded BLE transport. It intentionally does
not depend on esp-hal, Embassy, BLE, or desktop crates such as gilrs and
hidapi. Those desktop crates sit above an OS HID layer, while an ESP32 receives
raw BLE HID notifications.
§Usage
On ESP32-C3, enable the esp32-c3 feature and pass the BLE controller plus the
hardware random-number generator to run. The callback receives every parsed
notification and can forward it to an Embassy channel or watch:
use esp_xbox_controller::{ControllerConfig, ControllerSelector, run};
let config = ControllerConfig::new(ControllerSelector::AnyXbox);
run(ble, &mut random, config, |notification| {
if let Ok(state) = notification {
// Print state, or send it through an Embassy channel/watch.
}
})
.awaitSelect one observed controller with
ControllerSelector::Address([0xaa, 0xbb, 0xcc, 0xdd, 0xee, 0xff]).
Set ControllerConfig::idle_disconnect_after to disconnect after a period with
no changed controller state. Its default of None keeps the connection alive.
The report parser remains available independently and without ESP dependencies:
use esp_xbox_controller::parse_input_report;
fn consume(bytes: &[u8]) -> Result<(), esp_xbox_controller::ParseError> {
let state = parse_input_report(bytes)?;
// Use state.buttons, state.sticks, and state.triggers.
Ok(())
}The parser currently recognizes the 16-byte layout used by the
asukiaaa/arduino-XboxControllerNotificationParser
project. Stick values are translated from unsigned 0..=65535 to signed
-32768..=32767; trigger values remain unsigned and are normally 0..=1023.
§Workspace
- Repository root: publishable
esp-xbox-controllercrate. It re-exports the core state and parser API; theesp32-c3feature adds the ESP BLE connection API. crates/xbox-controller-core: publishable, transport-independentno_stdparser used by the ESP library and desktop inspector.examples/esp32-c3-example: XIAO ESP32-C3no_stdapplication usingesp-hal, Embassy viaesp-rtos, andesp-radioinitialization. See its README for more information.examples/esp32-c3-tasks-example: a more project-like ESP32-C3 application that runs controller input and output printing in separate Embassy tasks, connected by a channel.tools/xbox-controller-inspector: publishable Ubuntu AMD64 desktop GUI using BlueZ to inspect controller identity, input reports, and vibration.
§Testing with a XIAO ESP32-C3 and Model 1914 or 1708
§Test procedure
- Forget/unpair the controller from nearby consoles, PCs, and phones, or turn those devices off so they cannot reclaim it.
- Flash and monitor the example from
examples/esp32-c3-examplewithcargo run --release. - Hold the controller’s Pair button until the Xbox button flashes rapidly.
- Watch the serial log progress through
found,connected,pairing complete, HID discovery, andready. - Press buttons and move the sticks. The monitor prints both untouched notification bytes and the parsed state.
§Selecting which controller connects
The example is configured to accept the first compatible Xbox controller found. This is the easiest behavior for a demo: keep other Xbox controllers out of pairing mode while connecting. Discovery must still verify the advertised Xbox name and/or HID service UUID; it must not connect to the first arbitrary BLE device.
An optional ControllerSelector::Address([u8; 6]) is provided for installations
where multiple Xbox controllers might advertise at once. It filters compatible
advertisements using an address written in normal AA:BB:CC:DD:EE:FF order.
The selector and complete BLE connection lifecycle are provided by the
library’s esp32 module. The example only initializes the ESP peripherals and
passes its chosen selector to esp_xbox_controller::esp32::run.
An advertising address is not necessarily a permanent device MAC: BLE privacy allows private addresses to change. After the initial connection, bonding data and the resolved peer identity should be persisted and used for reconnection. The address filter is therefore a useful first-scan selector, but not a replacement for bonding. A future scan-only tool can list compatible controllers and show their address, address type, advertised name, HID services, and RSSI.
§Status and limitations
This project is experimental. Real notification dumps from Xbox Series controllers across firmware versions are needed to verify offsets, report characteristic selection, pairing/security behavior, and report-ID handling. The parser accepts at least 16 bytes and parses the first 16; it currently supports one known input layout and no output reports.
If you have trouble re-connecting to the same controller: power cycle the ESP32.
§Building
Run parser checks from the repository root:
cargo test
cargo fmt --all --checkThe embedded crate is excluded from the default member set so normal parser
development does not require the RISC-V target or ESP toolchain. Build and flash
it from examples/esp32-c3-example with cargo run --release after installing
espflash. The working directory matters: running there loads its local Cargo
configuration and the required ESP linker script.
The example plays a short best-effort vibration pulse after a controller is fully connected. Controllers without a writable output Report continue working for input and produce only a warning.
§License
Licensed under either Apache License 2.0 or MIT, at your option.
§Contributing and releases
Notable changes are recorded in CHANGELOG.md.
If you want to contribute by testing or extending the features of this repository, for instance to support more ESP32 boards, let me know!
This repository took inspiration from: XboxSeriesXControllerESP32.
Structs§
- Xbox
Button State - Digital button state from one Xbox controller report.
- Xbox
Controller State - The controller state represented by one BLE HID input notification.
- Xbox
Sticks - Stick positions centered around zero.
- Xbox
Triggers - Analog trigger values, normally in the range
0..=1023.
Enums§
- Parse
Error - An error encountered while parsing an Xbox input notification.
Constants§
- INPUT_
REPORT_ LEN - Length of the currently supported Xbox Series input report.
Functions§
- parse_
input_ report - Parse an Xbox Series controller BLE input notification.