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;
MIME-Version: 1.0
References: <20201130200307.386410-1-sonnysasaka@chromium.org>
 <20201130200307.386410-4-sonnysasaka@chromium.org> <CABBYNZJQebV4_CWjaFUVC4Ab6ZWKqWz0K-sp0sdKgMGxVgtZLQ@mail.gmail.com>
In-Reply-To: <CABBYNZJQebV4_CWjaFUVC4Ab6ZWKqWz0K-sp0sdKgMGxVgtZLQ@mail.gmail.com>
From:   Sonny Sasaka <sonnysasaka@chromium.org>
Date:   Mon, 30 Nov 2020 13:56:49 -0800
Message-ID: <CAO271mka6V6sDAg0GH3Cw4Jeo83kH1sEEUegGRkth6L8L0oG2w@mail.gmail.com>
Subject: Re: [PATCH BlueZ v4 4/7] doc: Add Battery Provider API doc
To:     Luiz Augusto von Dentz <luiz.dentz@gmail.com>
Cc:     "linux-bluetooth@vger.kernel.org" <linux-bluetooth@vger.kernel.org>,
        Miao-chen Chou <mcchou@chromium.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

Hi Luiz,

On Mon, Nov 30, 2020 at 1:28 PM Luiz Augusto von Dentz
<luiz.dentz@gmail.com> wrote:
>
> Hi Sonny,
>
> On Mon, Nov 30, 2020 at 12:09 PM Sonny Sasaka <sonnysasaka@chromium.org> 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).
>
> It seems you didn't address my concern related to use of friendly
> names and version numbers here, although this is just an example. I'd
> suggest we only accept UUIDs.
I revised the patch. Please take another look.
>
> > +
> > +
> > +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.
> > +
> > +               object Device [readonly]
> > +
> > +                       The object path of the device that has this battery.
> > --
> > 2.26.2
> >
>
>
> --
> Luiz Augusto von Dentz