Repository navigation
Releases
v0.8.0
What's Changed
v0.8.0 is a feature release built around two big additions: Xbox controller
emulation and SInput controller support — plus a cleanup of how the
BLE serial side-channel works.
Xbox controllers (XInput)
The library now emulates Xbox One S and Xbox Series X controllers over BLE
via GamepadMode::XInputOneS (PID 0x02FD) and GamepadMode::XInputSeriesX
(PID 0x0B13):
- HID report descriptors captured from real controllers: both sticks, 10-bit
triggers, D-pad, 15 buttons plus Share, and host-to-device rumble
(Output Report 0x03, including trigger vibration). - Simple API for every input — buttons, sticks, triggers, D-pad — with
Xbox host rumble delivered back through
isXInputRumbleReceived()and friends. - Pick One S for the broadest compatibility (including Linux xpad before
6.5), Series X for the Share button (Windows 11 22H2+, Linux 6.5+,
macOS Big Sur and later). - Examples:
XInputOneS,XInputSeriesX,XInputSeriesXFriendly(every
input driven by name), andXInputAllTestwith host-side test scripts.
SInput controllers (Handheld Legend)
GamepadMode::SInput speaks SInput,
the community BLE gamepad protocol created by Handheld Legend: a fixed VID/PID
and standardized report layout that SDL's hidapi driver understands natively,
turning the ESP32 into a full SDL_GameController — 25 buttons, sticks,
triggers, D-pad, motion (IMU), touchpad, player LEDs, RGB and rumble — with
native recognition in SDL3 games and Steam. Examples cover the full gamepad
plus each feature individually (SInputFullGamepad, SInputIMU,
SInputTouchpad, SInputRGB, SInputRumble, SInputPlayerLED,
SInputBattery), with SDL3 host tests to verify against.
BLE serial (NuS) is now an external library
The hand-rolled BleNUS serial implementation (BleNUS.cpp/BleNUS.h) has
been removed. Everything that talks to a phone/PC terminal — the
NuS*Bridge sketches, the NuSSendReceive tutorial — now runs on
NuS-NimBLE-Serial by Ángel
Fernández Pineda (CC BY 4.0), installed from the Arduino Library Manager
(see docs/NuSCompatibility.md).
Why the switch: both the HID gamepad and the Nordic UART Service live as two
services on one shared NimBLE server, using the library's delayAdvertising
mechanism so they advertise together cleanly. Depending on the maintained
upstream library instead of a vendored copy means bug fixes and improvements
arrive without carrying the code here.
Need a COM port instead of BLE?
The sketches above speak Nordic UART over BLE — but some PC applications
only speak plain serial COM ports and can't do BLE at all. For those, use
nus-bridge: a PC-side bridge
that acts as the BLE central, connects to the ESP32, and relays bytes both
ways between NuS and a virtual COM port your legacy application opens
(Windows virtual-COM pair, Linux pty, plus a no-driver TCP mode and a
system-tray app). Your .exe talks COM; the ESP32 still only sees NuS.
Test it from your phone
This release adds NuS Bridge sketches (NuSGenericBridge,
NuSXInputBridge, NuSSInputBridge, plus the NuSSendReceive tutorial)
built to be driven remotely: flash one, pair the gamepad with your PC, then
connect the NuS Gamepad Companion
app (Flutter, Android/iOS) over BLE and work every button, stick, trigger
and hat from your phone while watching the host react. The app speaks the
sketches' NuS line vocabulary (hello/proto identity, ok/err replies,
event pushes, state snapshots) — it picks the matching Generic, XInput
or SInput controller screen on its own, with a raw terminal for everything
else.
Thanks
Thank you to @LeeNX for driving the project
forward — the SInput and XInput support, the host-test rigs, and a large
share of everything else in this release.
Full Changelog: v0.7.5...v0.8.0
v0.7.5
It's been a while since v0.7.3, and a lot has quietly gone in. This release is
mostly about foundations — the kind of plumbing that isn't exciting on its
own but is what everything coming next is built on. If you've been running
master, very little here is new to you. If you've been on the last tagged
release, quite a lot is.
The two things actually worth plugging in for:
- Feature Reports — a proper two-way HID channel. Your host app can now push
configuration to the gamepad (LED colour, rumble strength, profile switches,
whatever you want to define) instead of only reading buttons and axes from
it. Turn it on withsetEnableFeatureReport(true), pick a buffer length, and
pollisFeatureReceived(). There's a Python script in
examples/TestFeatureReports/you can run against a real device in about a
minute. - Nordic UART Service — a plain serial pipe over BLE, alongside the gamepad.
Great for logging, diagnostics, or a companion app that needs to talk to the
device without pretending to be a HID host.beginNUS(),
sendDataOverNUS(),setNUSDataReceivedCallback(). The new
Diagnostics.inoexample streams live device state over it.
Smaller things you might notice: sliders now sit in their own HID collections
(some games will see the axes differently — remap if needed), you can dump the
generated HID descriptor with -DBLE_GAMEPAD_DEBUG=1, and the whole codebase
has had a formatting and warnings cleanup so it builds quietly on current
toolchains.
Behind the scenes there's now a real CI setup: every board (S3/C3/C6) builds on
every PR, sketch sizes are tracked over time, and there's hardware-in-the-loop
testing running against actual silicon. Releases are automated end to end now
too.
Take it for a spin
- Update the library (Arduino Library Manager / PlatformIO) to
0.7.5. - Flash
examples/Diagnostics/Diagnostics.ino, pair, and watch the device
report its own state over the UART service. - Try
examples/TestFeatureReports/and send a feature report from your
computer to the board. - Rebuild an existing sketch of yours — it should just work, and build cleaner
than before.
Feedback very welcome
This is deliberately a base release. New features are coming soon — several
big ones are built directly on top of Feature Reports and NUS. If something
here doesn't behave, the API feels awkward, or you have a use case you want the
foundation to support, please open an issue (there are templates now) or start
a discussion. Early feedback on these primitives is genuinely useful right now,
while they're still easy to change.
What's Changed
- Add comment back of readable if statement by @LeeNX in #281
- Cast char* to const char*, resolve warning: ISO C++ by @LeeNX in #282
- Add debug HID Report Descriptor as a build env 'BLE_GAMEPAD_DEBUG' by @LeeNX in #293
- Bump actions/checkout from 4 to 5 by @dependabot[bot] in #289
- For set functions - Cast char* to const char*, resolve warning: ISO C++ by @LeeNX in #290
- Fix Fightstick.ino state comparison logic by @tachikoma0023 in #299
- Bump actions/checkout from 5 to 6 by @dependabot[bot] in #302
- chore(ci): updates to add
Sketches report size deltato PR workflows by @LeeNX in #296 - chore(ci): remove comment-on-pr, as it does not exist by @LeeNX in #303
- chore(ci): split PR report update into a workflow by @LeeNX in #304
- Bump actions/upload-artifact from 4 to 6 by @dependabot[bot] in #308
- Bump actions/download-artifact from 6 to 7 by @dependabot[bot] in #307
- Put sliders into their own logical collections by @pkendall64 in #318
- Bump actions/download-artifact from 7 to 8 by @dependabot[bot] in #316
- Bump actions/upload-artifact from 6 to 7 by @dependabot[bot] in #315
- chore(ci): improvements, fix the resize and build checks by @LeeNX in #327
- Bump actions/setup-python from 6 to 7 by @dependabot[bot] in #328
- Bump actions/checkout from 6 to 7 by @dependabot[bot] in #324
- chore(ci): fix by removing Diagnostics.ino by @LeeNX in #330
- chore(ci): automate releases and fix monthly size reporting by @LeeNX in #334
- Extend the NUS services for external connection, plus add Diagnostics.ino example by @LeeNX in #329
- chore(ci): build a board matrix (S3/C3/C6) and add per-run memory summary by @LeeNX in #335
- chore: add issue templates by @LeeNX in #336
- Add HID Feature Reports by @LeeNX in #283
- chore(ci): fix report_size_summary.py by not breaking on new or missing example sketches by @LeeNX in #338
- Add GattVsHid.md, document battery level via upower in LinuxHIDTesting.md by @LeeNX in #339
- chore(ci): skip new sketch deltas, plus ReadME updates by @LeeNX in #340
- Add standard linting, CI and correction to bring balance of code to this standard by @LeeNX in #341
- fix: silence -Wreorder and -Wdeprecated-declarations warnings by @lemmingDev in #345
- Add hardware-in-the-loop testing for Linux by @LeeNX in #347
- Add self contained basic test firmware by @LeeNX in #343
- HilTesting.md: step-by-step for creating HIL_DISPATCH_TOKEN by @LeeNX in #349
New Contributors
- @tachikoma0023 made their first contribution in #299
- @pkendall64 made their first contribution in #318
Full Changelog: v0.7.3...v0.7.5
Release v0.7.5-rc0
What's Changed
- Add comment back of readable if statement by @LeeNX in #281
- Cast char* to const char*, resolve warning: ISO C++ by @LeeNX in #282
- Add debug HID Report Descriptor as a build env 'BLE_GAMEPAD_DEBUG' by @LeeNX in #293
- Bump actions/checkout from 4 to 5 by @dependabot[bot] in #289
- For set functions - Cast char* to const char*, resolve warning: ISO C++ by @LeeNX in #290
- Fix Fightstick.ino state comparison logic by @tachikoma0023 in #299
- Bump actions/checkout from 5 to 6 by @dependabot[bot] in #302
- chore(ci): updates to add
Sketches report size deltato PR workflows by @LeeNX in #296 - chore(ci): remove comment-on-pr, as it does not exist by @LeeNX in #303
- chore(ci): split PR report update into a workflow by @LeeNX in #304
- Bump actions/upload-artifact from 4 to 6 by @dependabot[bot] in #308
- Bump actions/download-artifact from 6 to 7 by @dependabot[bot] in #307
- Put sliders into their own logical collections by @pkendall64 in #318
- Bump actions/download-artifact from 7 to 8 by @dependabot[bot] in #316
- Bump actions/upload-artifact from 6 to 7 by @dependabot[bot] in #315
- chore(ci): improvements, fix the resize and build checks by @LeeNX in #327
- Bump actions/setup-python from 6 to 7 by @dependabot[bot] in #328
- Bump actions/checkout from 6 to 7 by @dependabot[bot] in #324
- chore(ci): fix by removing Diagnostics.ino by @LeeNX in #330
- chore(ci): automate releases and fix monthly size reporting by @LeeNX in #334
- Extend the NUS services for external connection, plus add Diagnostics.ino example by @LeeNX in #329
- chore(ci): build a board matrix (S3/C3/C6) and add per-run memory summary by @LeeNX in #335
- chore: add issue templates by @LeeNX in #336
- Add HID Feature Reports by @LeeNX in #283
- chore(ci): fix report_size_summary.py by not breaking on new or missing example sketches by @LeeNX in #338
- Add GattVsHid.md, document battery level via upower in LinuxHIDTesting.md by @LeeNX in #339
- chore(ci): skip new sketch deltas, plus ReadME updates by @LeeNX in #340
- Add standard linting, CI and correction to bring balance of code to this standard by @LeeNX in #341
New Contributors
- @tachikoma0023 made their first contribution in #299
- @pkendall64 made their first contribution in #318
Full Changelog: v0.7.3...v0.7.5-rc0
Release 7.3
Support setting Battery Power State 0x2A1A values
Use nRF Connect on Android for example to test
Full Changelog: v0.7.2...v0.7.3
Release 7.2
Existing setWhichAxes and setAxes function parameters order set to x, y, z, rx, ry, rz as most people seem to prefer this ordering
New setHIDAxes function parameters order set to x, y, z, rz, rx, ry, for people who prefer to set axes values in the order that they exist in the HID report
New setRightThumbAndroid function parameters order set to z, rx to compliment existing setRightThumb function order z, rz which is what Windows usually expects
Examples updated to reflect
Release 7.1
Initial support for motion controls (gyroscope and accelerometer)
Uses commonly used desktop page for compatibility, which just maps them to axes
If another (working) method seems better, let us know
Read the new example
This release also fixes right thumbstick to work correctly
Note: Android and other OSs might need the axes set individually compared to Windows
Release 7.0
TX power level can now be set either initially using the configuration system eg. bleGamepadConfig.setTXPowerLevel(3);
Defaults to 9 if not set
Range: -12 to 9 dBm and the only valid values are: -12, -9, -6, -3, 0, 3, 6 and 9
TX power can also be set at any time using bleGamepad.setTXPower(int8_t)
You can also get the current TX power level by using bleGamepad.getTXPower(int8_t)
See CharacteristicsConfiguration.ino example for more info
Release 6.9
Allow forced pairing and removing of bonds
Much requested features to work around hosts aggressively connecting to gamepad unwantedly.
Example provided
Release 6.8
Revert axes code to working state
oops
Release 6.7
Fix setting axes and update library properties to correct version