From 8661d1b19d7e78bdefb2bb39b70e8c894db4bf1f Mon Sep 17 00:00:00 2001
From: ReFil <31960031+ReFil@users.noreply.github.com>
Date: Fri, 20 Oct 2023 11:01:12 +0100
Subject: [PATCH] Document charging indication functionality

---
 docs/docs/config/battery.md | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/docs/docs/config/battery.md b/docs/docs/config/battery.md
index 7b7e9436503..f9d32a2f1f0 100644
--- a/docs/docs/config/battery.md
+++ b/docs/docs/config/battery.md
@@ -32,13 +32,25 @@ Applies to: [`/chosen` node](https://docs.zephyrproject.org/latest/guides/dts/in
 
 ## Battery Voltage Divider Sensor
 
-Driver for reading the voltage of a battery using an ADC connected to a voltage divider.
+Driver for reading the voltage of a battery using an ADC connected to a voltage divider. This driver can also read a GPIO pin to detect whether the battery is charging or not if the hardware implementation includes a battery charging IC with an output to indicate charging status. This functionality is optional, the `chg-gpios` devicetree configuration does not have to be set.
 
 ### Devicetree
 
 Applies to: `compatible = "zmk,battery-voltage-divider"`
 
-See [Zephyr's voltage divider documentation](https://docs.zephyrproject.org/latest/build/dts/api/bindings/adc/voltage-divider.html).
+Definition file: [zmk/app/module/dts/bindings/sensor/zmk,battery-voltage-divider.yaml](https://github.com/zmkfirmware/zmk/blob/main/app/module/dts/bindings/sensor/zmk,battery-voltage-divider.yaml)
+
+The ZMK battery voltage divider includes the [Zephyr voltage divider](https://docs.zephyrproject.org/latest/build/dts/api/bindings/adc/voltage-divider.html) and adds on additional functionality.
+
+| Property    | Type       | Description                                      | Default |
+| ----------- | ---------- | ------------------------------------------------ | ------- |
+| `chg-gpios` | GPIO array | GPIO connected to the charging IC's charging pin |         |
+
+:::note Charging indication
+
+The battery charging status is not currently consumed by any indicators and cannot be conveyed to the host over BLE. The battery charging status is updated every `CONFIG_ZMK_BATTERY_REPORT_INTERVAL`
+
+:::
 
 ## nRF VDDH Battery Sensor