On Mon, 2020-11-30 at 13:55 -0800, Sonny Sasaka wrote:
> This patch add the documentation of the Battery Provider which lets
> external clients feed battery information to BlueZ if they are able
> to
> decode battery reporting via any profile. BlueZ UI clients can then
> use
> the org.bluez.Battery1 API as a single source of battery information
> coming from many different profiles.
>
> Reviewed-by: Miao-chen Chou <mcchou@xxxxxxxxxxxx>
>
> ---
> doc/battery-api.txt | 55
> +++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 55 insertions(+)
>
> diff --git a/doc/battery-api.txt b/doc/battery-api.txt
> index dc7dbeda2..9a6b4fd39 100644
> --- a/doc/battery-api.txt
> +++ b/doc/battery-api.txt
> @@ -12,3 +12,58 @@ Object path [variable
> prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
> Properties byte Percentage [readonly]
>
> The percentage of battery left as an unsigned
> 8-bit integer.
> +
> + string Source [readonly, optional, experimental]
> +
> + Describes where the battery information comes
> from
> + This property is informational only and may
> be useful
> + for debugging purposes.
> + Providers from BatteryProvider1 may make use
> of this
> + property to indicate where the battery report
> comes from
> + (e.g. "HFP 1.7", "HID", or the profile UUID).
> +
> +
> +Battery Provider Manager hierarchy
> +==================================
> +A battery provider starts by registering itself as a battery
> provider with the
> +RegisterBatteryProvider method passing an object path as the
> provider ID. Then,
> +it can start exposing org.bluez.BatteryProvider1 objects having the
> path
> +starting with the given provider ID. It can also remove objects at
> any time.
> +The objects and their properties exposed by battery providers will
> be reflected
> +on org.bluez.Battery1 interface.
> +
> +BlueZ will stop monitoring these exposed and removed objects after
> +UnregisterBatteryProvider is called for that provider ID.
> +
> +Service org.bluez
> +Interface org.bluez.BatteryProviderManager1 [experimental]
> +Object path /org/bluez/{hci0,hci1,...}
> +
> +Methods void RegisterBatteryProvider(object provider)
> +
> + This registers a battery provider. A
> registered
> + battery provider can then expose objects with
> + org.bluez.BatteryProvider1 interface
> described below.
> +
> + void UnregisterBatteryProvider(object provider)
> +
> + This unregisters a battery provider. After
> + unregistration, the BatteryProvider1 objects
> provided
> + by this client are ignored by BlueZ.
> +
> +
> +Battery Provider hierarchy
> +==========================
> +
> +Service <client D-Bus address>
> +Interface org.bluez.BatteryProvider1 [experimental]
> +Object path {provider_root}/{unique battery object path}
> +
> +Properties Objects provided on this interface contain the same properties
> + as org.bluez.Battery1 interface. Additionally, this interface
> + needs to have the Device property indicating the object path
> + of the device this battery provides.
"this interface needs to have a Device property indicating the object
path this battery information pertains to."
or
"this interface needs to have a Device property indicating the object
path the battery information is provided for."
> +
> + object Device [readonly]
> +
> + The object path of the device that has this
> battery.
