[BlueZ,v5,4/7] doc: Add Battery Provider API doc

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@chromium.org>

---
 doc/battery-api.txt | 55 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

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@chromium.org>
> 
> ---
>  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.