Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Message-ID: <e82cef2e672e9b7f413341264f82d90c3c268cf3.camel@hadess.net>
Subject: Re: [PATCH BlueZ v5 4/7] doc: Add Battery Provider API doc
From:   Bastien Nocera <hadess@hadess.net>
To:     Sonny Sasaka <sonnysasaka@chromium.org>,
        linux-bluetooth@vger.kernel.org
Cc:     Miao-chen Chou <mcchou@chromium.org>
Date:   Tue, 01 Dec 2020 17:25:20 +0100
In-Reply-To: <20201130215602.386545-4-sonnysasaka@chromium.org>
References: <20201130215602.386545-1-sonnysasaka@chromium.org>
         <20201130215602.386545-4-sonnysasaka@chromium.org>
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.38.1 (3.38.1-1.fc33) 
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

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.