Skip to content

Releases

v0.8.0

Choose a tag to compare

@github-actions github-actions released this 17 Sep 20:31

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), and XInputAllTest with 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

Choose a tag to compare

@github-actions github-actions released this 06 Sep 13:16
a02be5d

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 with setEnableFeatureReport(true), pick a buffer length, and
    poll isFeatureReceived(). 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.ino example 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

  1. Update the library (Arduino Library Manager / PlatformIO) to 0.7.5.
  2. Flash examples/Diagnostics/Diagnostics.ino, pair, and watch the device
    report its own state over the UART service.
  3. Try examples/TestFeatureReports/ and send a feature report from your
    computer to the board.
  4. 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 delta to 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

Full Changelog: v0.7.3...v0.7.5

Release v0.7.5-rc0

Release v0.7.5-rc0 Pre-release
Pre-release

Choose a tag to compare

@LeeNX LeeNX released this 27 Aug 09:26
05599be

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 delta to 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

Full Changelog: v0.7.3...v0.7.5-rc0

Release 7.3

Choose a tag to compare

@lemmingDev lemmingDev released this 15 Feb 04:22
7a35a86

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

Choose a tag to compare

@lemmingDev lemmingDev released this 07 Feb 04:59
fd94938

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

Choose a tag to compare

@lemmingDev lemmingDev released this 02 Feb 01:15
09e2099

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

Choose a tag to compare

@lemmingDev lemmingDev released this 31 Jan 07:29
c48ca5d

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

Choose a tag to compare

@lemmingDev lemmingDev released this 29 Jan 11:49
51f41f4

Allow forced pairing and removing of bonds

Much requested features to work around hosts aggressively connecting to gamepad unwantedly.

Example provided

Release 6.8

Choose a tag to compare

@lemmingDev lemmingDev released this 25 Jan 04:47
b41352e

Revert axes code to working state

oops

Release 6.7

Choose a tag to compare

@lemmingDev lemmingDev released this 24 Jan 10:17
4b49c5c

Fix setting axes and update library properties to correct version