Merge branch 'contrib/github_pr_529' into 'master'

leeebo · leeebo · commit 8587ea5262cb · 2025-08-06T10:11:01.000+08:00
feat(keyboard): Add ble battery level report (GitHub PR)

Closes AEGHB-1109

See merge request ae_group/esp-iot-solution!1338
diff --git a/examples/keyboard/README.md b/examples/keyboard/README.md
@@ -8,6 +8,7 @@ The ESP-KeyBoard project is a keyboard project using the ESP32-S3, supporting N-
 * Supports low-power key scanning
 * Supports USB 1K report rate
 * Supports BLE 125Hz report rate
+* Supports BLE battery level reporting
 * Supports local lighting control with over 40 types
 * Supports `Windows 11` dynamic lighting control
 
@@ -78,6 +79,11 @@ Note: keyboard_rgb_martix comes from the **QMK** project. Due to the use of the
 
 ### Change LOG
 
+* v0.3.0 - 2025-08-04
+
+  * Added BLE battery level reporting with ADC-based battery monitoring.
+  * Improved battery capacity estimation using resistor voltage divider circuit.
+
 * v0.2.2 - 2024-11-21
 
   * Added support for waking up a PC from sleep mode (remote wakeup).
diff --git a/examples/keyboard/README_cn.md b/examples/keyboard/README_cn.md
@@ -8,6 +8,7 @@ ESP-KeyBoard 项目是使用 ESP32-S3 的键盘项目，支持全键无冲，USB
     * 支持按键扫描低功耗
     * 支持 USB 1K 回报率
     * 支持 BLE 125hz 回报率
+    * 支持 BLE 电池电量报告
     * 支持本地灯效控制 40+ 种
     * 支持 `Windows 11` 动态灯效控制
 
@@ -78,6 +79,11 @@ Note: keyboard_rgb_martix 来自 **QMK** 工程，由于使用 GPL 协议，如
 
 #### Change LOG
 
+* v0.3.0 - 2025-8-4
+
+  * 增加了基于 ADC 的 BLE 电池电量监控和报告功能
+  * 改进了使用电阻分压电路的电池容量估算
+
 * v0.2.2 - 2024-11-21
 
   * 支持唤醒睡眠状态下的 PC (remote wakeup)
diff --git a/examples/keyboard/components/esp32_s3_kbd_kit/include/bsp/keyboard.h b/examples/keyboard/components/esp32_s3_kbd_kit/include/bsp/keyboard.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -49,7 +49,9 @@ extern "C" {
 #define KBD_WS2812_POWER_IO  1
 
 /*!< Battery monitor GPIO */
-#define KBD_BATTERY_MONITOR_IO  2
+#define KBD_BATTERY_MONITOR_ADC_UNIT ADC_UNIT_1
+#define KBD_BATTERY_MONITOR_IO       2
+#define KBD_BATTERY_MONITOR_CHANNEL  ADC_CHANNEL_1
 
 #ifdef __cplusplus
 }
diff --git a/examples/keyboard/main/CMakeLists.txt b/examples/keyboard/main/CMakeLists.txt
@@ -1,5 +1,5 @@
-idf_component_register(SRCS "main.c" "../hid_device/usb_descriptors.c" "tinyusb_hid.c" "ble_hid.c" "esp_hid_gap.c" "btn_progress.c" "settings.c"
-                    INCLUDE_DIRS "../hid_device")
+idf_component_register(SRCS "main.c" "../hid_device/usb_descriptors.c" "tinyusb_hid.c" "ble_hid.c" "esp_hid_gap.c" "btn_progress.c" "settings.c" "battery_adc.c"
+                       INCLUDE_DIRS "../hid_device")
 
 idf_component_get_property(tusb_lib espressif__tinyusb COMPONENT_LIB)
 
diff --git a/examples/keyboard/main/battery_adc.c b/examples/keyboard/main/battery_adc.c
@@ -0,0 +1,70 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <esp_log.h>
+#include <esp_adc/adc_oneshot.h>
+#include "ble_hid.h"
+#include "bsp/esp-bsp.h"
+#include "battery_adc.h"
+#include "adc_battery_estimation.h"
+
+static const char *TAG = "BATTERY-ADC";
+
+static TaskHandle_t battery_monitor_task_handle;
+static void battery_monitor_task(void *pvParameters);
+
+/* Pull up resistor value. Unit: KOhm */
+#define PULL_UP_RESISTOR    (51)
+/* Pull down resistor value. Unit: KOhm */
+#define PULL_DOWN_RESISTOR  (100)
+
+esp_err_t battery_adc_init(void)
+{
+    if (battery_monitor_task_handle != NULL) {
+        ESP_LOGW(TAG, "Battery monitor task already created! ");
+        return ESP_OK;
+    }
+
+    if (xTaskCreate(battery_monitor_task, "battery_monitor", 4096, NULL, 2, &battery_monitor_task_handle) != pdPASS) {
+        return ESP_ERR_NO_MEM;
+    }
+
+    return ESP_OK;
+}
+
+static void battery_monitor_task(void *pvParameters)
+{
+    ESP_UNUSED(pvParameters);
+    adc_battery_estimation_t config = {
+        .internal = {
+            .adc_unit = KBD_BATTERY_MONITOR_ADC_UNIT,
+            .adc_bitwidth = ADC_BITWIDTH_DEFAULT,
+            /* Theoretical battery voltage measurement range is about 2.45 to 2.78V.
+             * So set the input attenuation to 12 dB (about 4x) */
+            .adc_atten = ADC_ATTEN_DB_12
+        },
+        .adc_channel = KBD_BATTERY_MONITOR_CHANNEL,
+        .lower_resistor = PULL_DOWN_RESISTOR,
+        .upper_resistor = PULL_UP_RESISTOR,
+    };
+
+    adc_battery_estimation_handle_t adc_battery_estimation_handle = adc_battery_estimation_create(&config);
+    if (adc_battery_estimation_handle == NULL) {
+        ESP_LOGE(TAG, "Initialize adc battery estimation failed! ");
+        vTaskDelete(battery_monitor_task_handle);
+        vTaskDelay(portMAX_DELAY);
+    }
+
+    float capacity = 0.0f;
+
+    while (1) {
+        adc_battery_estimation_get_capacity(adc_battery_estimation_handle, &capacity);
+        ble_hid_battery_report((int) capacity);
+
+        /* Sample period. */
+        vTaskDelay(pdMS_TO_TICKS(10000));
+    }
+}
diff --git a/examples/keyboard/main/battery_adc.h b/examples/keyboard/main/battery_adc.h
@@ -0,0 +1,26 @@
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "esp_err.h"
+
+/**
+ * @brief Initialize battery ADC.
+ *
+ * @return
+ *    - ESP_OK: Success
+ *    - ESP_ERR_NO_MEM: Out of memory.
+ */
+esp_err_t battery_adc_init(void);
+
+#ifdef __cpluscpls
+}
+#endif
diff --git a/examples/keyboard/main/ble_hid.c b/examples/keyboard/main/ble_hid.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -161,3 +161,13 @@ void ble_hid_keyboard_report(hid_report_t report)
         break;
     }
 }
+
+void ble_hid_battery_report(int battery_level)
+{
+    if (s_ble_hid_param.is_connected == false) {
+        return;
+    }
+
+    ESP_LOGI(TAG, "Report level: %d", battery_level);
+    esp_hidd_dev_battery_set(s_ble_hid_param.hid_dev, (uint8_t)battery_level);
+}
diff --git a/examples/keyboard/main/ble_hid.h b/examples/keyboard/main/ble_hid.h
@@ -1,4 +1,5 @@
-/* SPDX-FileCopyrightText: 2022-2024 Espressif Systems (Shanghai) CO LTD
+/*
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -36,6 +37,13 @@ esp_err_t ble_hid_deinit(void);
  */
 void ble_hid_keyboard_report(hid_report_t report);
 
+/**
+ * @brief Send ble hid battery level
+ *
+ * @param battery_level
+ */
+void ble_hid_battery_report(int battery_level);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/examples/keyboard/main/idf_component.yml b/examples/keyboard/main/idf_component.yml
@@ -1,5 +1,6 @@
-version: 0.2.2
+version: 0.3.0
 dependencies:
-  idf: ">=5.2"
+  idf: '>=5.2'
   espressif/tinyusb:
-    version: ">=0.15.0~2"
+    version: '>=0.15.0~2'
+  espressif/adc_battery_estimation: =*
diff --git a/examples/keyboard/main/main.c b/examples/keyboard/main/main.c
@@ -10,6 +10,7 @@
 #include "bsp/esp-bsp.h"
 #include "bsp/keycodes.h"
 #include "btn_progress.h"
+#include "battery_adc.h"
 #include "esp_log.h"
 #include "esp_pm.h"
 #include "keyboard_button.h"
@@ -115,4 +116,5 @@ void app_main(void)
     keyboard_button_register_cb(kbd_handle, cb_cfg, NULL);
 
     xTaskCreate(light_progress_task, "light_progress_task", 4096, NULL, 5, &light_progress_task_handle);
+    battery_adc_init();
 }
