Support setting Battery Power State 0x2A1A values

Use nRF Connect on Android to test

Author: lemmingDev

BleGamepad.cpp

@@ -20,13 +20,26 @@
 static const char *LOG_TAG = "BLEGamepad";
 #endif
 
-#define SERVICE_UUID_DEVICE_INFORMATION        "180A"      // Service - Device information
+#define SERVICE_UUID_DEVICE_INFORMATION         "180A"      // Service - Device information
+
+#define CHARACTERISTIC_UUID_MODEL_NUMBER        "2A24"      // Characteristic - Model Number String - 0x2A24
+#define CHARACTERISTIC_UUID_SOFTWARE_REVISION   "2A28"      // Characteristic - Software Revision String - 0x2A28
+#define CHARACTERISTIC_UUID_SERIAL_NUMBER       "2A25"      // Characteristic - Serial Number String - 0x2A25
+#define CHARACTERISTIC_UUID_FIRMWARE_REVISION   "2A26"      // Characteristic - Firmware Revision String - 0x2A26
+#define CHARACTERISTIC_UUID_HARDWARE_REVISION   "2A27"      // Characteristic - Hardware Revision String - 0x2A27
+#define CHARACTERISTIC_UUID_BATTERY_POWER_STATE "2A1A"      // Characteristic - Battery Power State - 0x2A1A
+
+#define POWER_STATE_UNKNOWN         0 // B00
+#define POWER_STATE_NOT_SUPPORTED   1 // B01
+#define POWER_STATE_NOT_PRESENT     2 // B10
+#define POWER_STATE_NOT_DISCHARGING 2 // B10
+#define POWER_STATE_NOT_CHARGING    2 // B10
+#define POWER_STATE_GOOD            2 // B10
+#define POWER_STATE_PRESENT         3 // B11
+#define POWER_STATE_DISCHARGING     3 // B11
+#define POWER_STATE_CHARGING        3 // B11
+#define POWER_STATE_CRITICAL        3 // B11
 
-#define CHARACTERISTIC_UUID_MODEL_NUMBER       "2A24"      // Characteristic - Model Number String - 0x2A24
-#define CHARACTERISTIC_UUID_SOFTWARE_REVISION  "2A28"      // Characteristic - Software Revision String - 0x2A28
-#define CHARACTERISTIC_UUID_SERIAL_NUMBER      "2A25"      // Characteristic - Serial Number String - 0x2A25
-#define CHARACTERISTIC_UUID_FIRMWARE_REVISION  "2A26"      // Characteristic - Firmware Revision String - 0x2A26
-#define CHARACTERISTIC_UUID_HARDWARE_REVISION  "2A27"      // Characteristic - Hardware Revision String - 0x2A27
 
 
 uint8_t tempHidReportDescriptor[150];
@@ -77,7 +90,12 @@ BleGamepad::BleGamepad(std::string deviceName, std::string deviceManufacturer, u
   _aX(0),
   _aY(0),
   _aZ(0),
-  hid(0)
+  _batteryPowerInformation(0),
+  _dischargingState(0),
+  _chargingState(0),
+  _powerLevel(0),
+  hid(0),
+  pCharacteristic_Power_State(0)
 {
   this->resetButtons();
   this->deviceName = deviceName;
@@ -1906,14 +1924,65 @@ void BleGamepad::setMotionControls(int16_t gX, int16_t gY, int16_t gZ, int16_t a
     sendReport();
   }
 }
+    
+void BleGamepad::setPowerStateAll(uint8_t batteryPowerInformation, uint8_t dischargingState, uint8_t chargingState, uint8_t powerLevel)
+{
+    uint8_t powerStateBits = B00000000;
+    
+    _batteryPowerInformation = batteryPowerInformation;
+    _dischargingState = dischargingState;
+    _chargingState = chargingState;
+    _powerLevel = powerLevel;
+
+    // HID Battery Power State Bits:
+    // Bits 0 and 1: Battery Power Information : 0(B00) = Unknown, 1(B01) = Not Supported,  2(B10) = Not Present,               3(B11) = Present
+    // Bits 2 and 3: Discharging State         : 0(B00) = Unknown, 1(B01) = Not Supported,  2(B10) = Not Discharging,           3(B11) = Discharging
+    // Bits 4 and 5: Charging State            : 0(B00) = Unknown, 1(B01) = Not Chargeable, 2(B10) = Not Charging (Chargeable), 3(B11) = Charging (Chargeable)
+    // Bits 6 and 7: Power Level               : 0(B00) = Unknown, 1(B01) = Not Supported,  2(B10) = Good Level,                3(B11) = Critically Low Level
+
+    powerStateBits |= (_batteryPowerInformation << 0);  // Populate first 2 bits with data
+    powerStateBits |= (_dischargingState        << 2);  // Populate second 2 bits with data
+    powerStateBits |= (_chargingState           << 4);  // Populate third 2 bits with data
+    powerStateBits |= (_powerLevel              << 6);  // Populate last 2 bits with data
+
+    if (this->pCharacteristic_Power_State) 
+    {
+      this->pCharacteristic_Power_State->setValue(&powerStateBits, 1);
+      this->pCharacteristic_Power_State->notify();
+    }
+}
+
+
+void BleGamepad::setBatteryPowerInformation(uint8_t batteryPowerInformation)
+{
+  _batteryPowerInformation = batteryPowerInformation;
+  setPowerStateAll(_batteryPowerInformation, _dischargingState, _chargingState, _powerLevel);
+}
+
+void BleGamepad::setDischargingState(uint8_t dischargingState)
+{
+  _dischargingState = dischargingState;
+  setPowerStateAll(_batteryPowerInformation, _dischargingState, _chargingState, _powerLevel);
+}
 
+void BleGamepad::setChargingState(uint8_t chargingState)
+{
+  _chargingState = chargingState;
+  setPowerStateAll(_batteryPowerInformation, _dischargingState, _chargingState, _powerLevel);
+}
+
+void BleGamepad::setPowerLevel(uint8_t powerLevel)
+{
+  _powerLevel = powerLevel;
+  setPowerStateAll(_batteryPowerInformation, _dischargingState, _chargingState, _powerLevel);
+}
 
 void BleGamepad::taskServer(void *pvParameter)
 {
   BleGamepad *BleGamepadInstance = (BleGamepad *)pvParameter; // static_cast<BleGamepad *>(pvParameter);
 
   NimBLEDevice::init(BleGamepadInstance->deviceName);
-  NimBLEDevice::setPower(powerLevel); // Set transmit power for advertising (Range: -127 to +9 dBm)
+  NimBLEDevice::setPower(powerLevel); // Set transmit power for advertising (Range: -12 to +9 dBm)
   NimBLEServer *pServer = NimBLEDevice::createServer();
   pServer->setCallbacks(BleGamepadInstance->connectionStatus);
   pServer->advertiseOnDisconnect(true);
@@ -1964,6 +2033,13 @@ void BleGamepad::taskServer(void *pvParameter)
         NIMBLE_PROPERTY::READ
       );
   pCharacteristic_Hardware_Revision->setValue(hardwareRevision);
+  
+  NimBLECharacteristic* pCharacteristic_Power_State = BleGamepadInstance->hid->getBatteryService()->createCharacteristic(
+        CHARACTERISTIC_UUID_BATTERY_POWER_STATE,
+        NIMBLE_PROPERTY::READ | NIMBLE_PROPERTY::NOTIFY
+      );
+  BleGamepadInstance->pCharacteristic_Power_State = pCharacteristic_Power_State; // Assign the created characteristic
+  BleGamepadInstance->pCharacteristic_Power_State->setValue(B00000000); // Now it's safe to call setValue <- Set all to unknown by default
 
   BleGamepadInstance->hid->setPnp(0x01, vid, pid, guidVersion);
   BleGamepadInstance->hid->setHidInfo(0x00, 0x01);
@@ -1975,12 +2051,14 @@ void BleGamepad::taskServer(void *pvParameter)
   uint8_t *customHidReportDescriptor = new uint8_t[hidReportDescriptorSize];
   memcpy(customHidReportDescriptor, tempHidReportDescriptor, hidReportDescriptorSize);
 
-  // Testing
+  // Testing - Ask ChatGPT to convert it into a commented HID descriptor
+  //Serial.println("------- HID DESCRIPTOR START -------");
   //for (int i = 0; i < hidReportDescriptorSize; i++)
   //{
   //    Serial.printf("%02x", customHidReportDescriptor[i]);
   //    Serial.println();
   //}
+  //Serial.println("------- HID DESCRIPTOR END -------");
 
   BleGamepadInstance->hid->setReportMap((uint8_t *)customHidReportDescriptor, hidReportDescriptorSize);
   BleGamepadInstance->hid->startServices();

BleGamepad.h

@@ -40,6 +40,10 @@ class BleGamepad
     int16_t _aX;
     int16_t _aY;
     int16_t _aZ;
+    uint8_t _batteryPowerInformation;
+    uint8_t _dischargingState;
+    uint8_t _chargingState;
+    uint8_t _powerLevel;
 
     //BleGamepadConfiguration configuration;
 
@@ -50,6 +54,7 @@ class BleGamepad
     NimBLEHIDDevice *hid;
     NimBLECharacteristic *inputGamepad;
     NimBLECharacteristic *outputGamepad;
+    NimBLECharacteristic *pCharacteristic_Power_State;
 
     uint8_t *outputBackupBuffer;
 
@@ -117,7 +122,12 @@ class BleGamepad
     bool isConnected(void);
     void resetButtons();
     void setBatteryLevel(uint8_t level);
-	  void setTXPowerLevel(int8_t level = 9);
+    void setPowerStateAll(uint8_t batteryPowerInformation, uint8_t dischargingState, uint8_t chargingState, uint8_t powerLevel);
+    void setBatteryPowerInformation(uint8_t batteryPowerInformation);
+    void setDischargingState(uint8_t dischargingState);
+    void setChargingState(uint8_t chargingState);
+    void setPowerLevel(uint8_t powerLevel);
+    void setTXPowerLevel(int8_t level = 9);
     int8_t getTXPowerLevel();
     uint8_t batteryLevel;
     std::string deviceManufacturer;

BleGamepadConfiguration.cpp

@@ -22,7 +22,7 @@ BleGamepadConfiguration::BleGamepadConfiguration() : _controllerType(CONTROLLER_
                                                      _modelNumber("1.0.0"),
                                                      _softwareRevision("1.0.0"),
                                                      _serialNumber("0123456789"),
-                                                     _firmwareRevision("0.7.2"),
+                                                     _firmwareRevision("0.7.3"),
                                                      _hardwareRevision("1.0.0"),
                                                      _enableOutputReport(false),
                                                      _outputReportLength(64),

BleGamepadConfiguration.h

@@ -199,6 +199,17 @@
 #define VOLUME_DEC_BUTTON 6
 #define VOLUME_MUTE_BUTTON 7
 
+#define POWER_STATE_UNKNOWN         0 // B00
+#define POWER_STATE_NOT_SUPPORTED   1 // B01
+#define POWER_STATE_NOT_PRESENT     2 // B10
+#define POWER_STATE_NOT_DISCHARGING 2 // B10
+#define POWER_STATE_NOT_CHARGING    2 // B10
+#define POWER_STATE_GOOD            2 // B10
+#define POWER_STATE_PRESENT         3 // B11
+#define POWER_STATE_DISCHARGING     3 // B11
+#define POWER_STATE_CHARGING        3 // B11
+#define POWER_STATE_CRITICAL        3 // B11
+
 class BleGamepadConfiguration
 {
 private:

README.md

@@ -11,6 +11,8 @@ It would be great however if any improvements are fed back into this version.
  - [x] Button release (128 buttons)
  - [x] Axes movement (6 axes (configurable resolution up to 16 bit) (x, y, z, rX, rY, rZ) --> In Windows usually (Left Thumb X, Left Thumb Y, Right Thumb X, Left Trigger, Right Trigger, Right Thumb Y))
  - [x] Gyroscope and Accelerometer
+ - [x] Set battery percentage
+ - [x] Set battery power state information using UUID 0x2A1A. Use nRF Connect on Android for example to see this information
  - [x] 2 Sliders (configurable resolution up to 16 bit) (Slider 1 and Slider 2)
  - [x] 4 point of view hats (ie. d-pad plus 3 other hat switches)
  - [x] Simulation controls (rudder, throttle, accelerator, brake, steering)
@@ -44,7 +46,7 @@ This was due to the fact that non-Windows operating systems and some online web-
 
 This version endeavors to be compatible with the latest released version of NimBLE-Arduino through the Arduino Library Manager; currently version 2.2.1 at the time of this writing; --> https://github.com/h2zero/NimBLE-Arduino/releases/tag/2.2.1
 
-setAxes accepts them in the order (x, y, z, rx, ry, rz)
+setAxes accepts axes in the order (x, y, z, rx, ry, rz)
 setHIDAxes accepts them in the order (x, y, z, rz, rx, ry)
 
 Please see updated examples

examples/SetBatteryPowerState/SetBatteryPowerState.ino

@@ -0,0 +1,64 @@
+/*
+   This example builds on the SetBatteryLevel example by also showing how to set the battery power state information to be reported to the host OS
+   Use nRF Connect on Android for example to see the set information
+
+   You can set:
+
+   - Whether there is a battery installed or not
+   - Whether the device is discharging or not
+   - Whether the device is charging or not
+   - Whether the power level is good or critically low
+
+   Each of the above also supports unknown or not supported states
+
+   You can use the definitions as shown below, or direct values
+
+   #define POWER_STATE_UNKNOWN         0 // B00
+   #define POWER_STATE_NOT_SUPPORTED   1 // B01
+   #define POWER_STATE_NOT_PRESENT     2 // B10
+   #define POWER_STATE_NOT_DISCHARGING 2 // B10
+   #define POWER_STATE_NOT_CHARGING    2 // B10
+   #define POWER_STATE_GOOD            2 // B10
+   #define POWER_STATE_PRESENT         3 // B11
+   #define POWER_STATE_DISCHARGING     3 // B11
+   #define POWER_STATE_CHARGING        3 // B11
+   #define POWER_STATE_CRITICAL        3 // B11
+
+*/
+
+#include <Arduino.h>
+#include <BleGamepad.h>
+
+BleGamepad bleGamepad;
+
+int batteryLevel = 100;
+
+void setup()
+{
+  Serial.begin(115200);
+  Serial.println("Starting BLE work!");
+  bleGamepad.begin();
+}
+
+void loop()
+{
+  if (bleGamepad.isConnected())
+  {
+    // bleGamepad.setPowerStateAll(POWER_STATE_PRESENT, POWER_STATE_NOT_DISCHARGING, POWER_STATE_CHARGING, POWER_STATE_GOOD); // Can set all values together or separate as below
+    bleGamepad.setBatteryPowerInformation(POWER_STATE_PRESENT);   // POWER_STATE_UNKNOWN or POWER_STATE_NOT_SUPPORTED or POWER_STATE_NOT_PRESENT or POWER_STATE_PRESENT
+    bleGamepad.setDischargingState(POWER_STATE_NOT_DISCHARGING);  // POWER_STATE_UNKNOWN or POWER_STATE_NOT_SUPPORTED or POWER_STATE_NOT_DISCHARGING or POWER_STATE_DISCHARGING
+    bleGamepad.setChargingState(POWER_STATE_CHARGING);            // POWER_STATE_UNKNOWN or POWER_STATE_NOT_SUPPORTED or POWER_STATE_NOT_CHARGING or POWER_STATE_CHARGING
+    bleGamepad.setPowerLevel(POWER_STATE_GOOD);                   // POWER_STATE_UNKNOWN or POWER_STATE_NOT_SUPPORTED or POWER_STATE_GOOD or POWER_STATE_CRITICAL
+
+    if (batteryLevel > 0)
+    {
+      batteryLevel -= 1;
+    }
+
+    Serial.print("Battery Level Set To: ");
+    Serial.println(batteryLevel);
+    bleGamepad.setBatteryLevel(batteryLevel);
+
+    delay(10000);
+  }
+}

keywords.txt

@@ -79,8 +79,13 @@ setIncludeGyroscope	KEYWORD2
 setIncludeAccelerometer	KEYWORD2
 setWhichSimulationControls	KEYWORD2
 resetButtons	KEYWORD2
-setBatteryLevel	KEYWORD2
-pressSpecialButton	KEYWORD2
+setBatteryLevel KEYWORD2
+setPowerStateAll  KEYWORD2
+setBatteryPowerInformation KEYWORD2
+setDischargingState KEYWORD2
+setChargingState  KEYWORD2
+setPowerLevel KEYWORD2
+pressSpecialButton  KEYWORD2
 releaseSpecialButton	KEYWORD2
 pressStart	KEYWORD2
 releaseStart	KEYWORD2

library.properties

@@ -1,5 +1,5 @@
 name=ESP32-BLE-Gamepad
-version=0.7.2
+version=0.7.3
 author=lemmingDev
 maintainer=lemmingDev
 sentence=Bluetooth LE Gamepad library for the ESP32.