[PATCH BlueZ 2/4] doc: Document component battery objects
From: Matthias Kurz <hidden>
Date: 2026-08-19 22:32:23
Subsystem:
the rest · Maintainer:
Linus Torvalds
Describe the experimental component Battery1 properties, their opaque object paths, and how BatteryProvider1 implementations publish several batteries for one device. Assisted-by: Codex:gpt-5.6-sol --- doc/org.bluez.Battery.rst | 35 +++++++++++++++++++++++++++++-- doc/org.bluez.BatteryProvider.rst | 16 ++++++++++++++ 2 files changed, 49 insertions(+), 2 deletions(-)
diff --git a/doc/org.bluez.Battery.rst b/doc/org.bluez.Battery.rst
index 5f9c6e7c6..e68c5d260 100644
--- a/doc/org.bluez.Battery.rst
+++ b/doc/org.bluez.Battery.rst@@ -17,15 +17,27 @@ Interface :Service: org.bluez :Interface: org.bluez.Battery1 :Object path: [variable prefix]/{hci0,hci1,...}/dev_{BDADDR} + [/battery_{identifier}] + +Component battery objects are experimental. Their object paths are +implementation details and shall be treated as opaque. Clients shall use the +``Device`` and ``Identifier`` properties to associate a component with its +parent device and its stable identity. + +For diagnostic purposes, ASCII letters and digits in the identifier are kept +in the object path. Every other byte is encoded as an underscore followed by +two lowercase hexadecimal digits. Properties ---------- -byte Percentage [readonly] -`````````````````````````` +byte Percentage [readonly, optional] +```````````````````````````````````` The percentage of battery left as an unsigned 8-bit integer. +The property is absent while the battery level is unknown. + string Source [readonly, optional] ``````````````````````````````````
@@ -36,3 +48,22 @@ This property is informational only and may be useful for debugging purposes. Providers from **org.bluez.BatteryProvider(5)** may make use of this property to indicate where the battery report comes from (e.g. "HFP 1.7", "HID", or the profile UUID). + +object Device [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +The object path of the device containing this battery. + +This property is present on component battery objects below the device object. + +string Identifier [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +A stable identifier for this battery within the device, such as ``left``, +``right``, or ``case``. + +boolean Charging [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +Indicates whether this battery is currently charging. The property is absent +while the charging state is unknown.
diff --git a/doc/org.bluez.BatteryProvider.rst b/doc/org.bluez.BatteryProvider.rst
index 2373cebf9..b79cbe6f5 100644
--- a/doc/org.bluez.BatteryProvider.rst
+++ b/doc/org.bluez.BatteryProvider.rst@@ -30,3 +30,19 @@ object Device [readonly] ```````````````````````` The object path of the device that has this battery. + +string Identifier [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +A non-empty identifier that is unique among the batteries for this device. +Multiple batteries may refer to the same device when each provides a unique +identifier. They are reflected as component **org.bluez.Battery1** objects. + +A provider object without this property represents the legacy aggregate +battery and is reflected directly on the device object. + +boolean Charging [readonly, optional, experimental] +```````````````````````````````````````````````````````````` + +Indicates whether this battery is currently charging. The property is absent +while the charging state is unknown.
--
2.55.0