Hi Sonny,
On Tue, Nov 24, 2020 at 5:20 PM Sonny Sasaka <sonnysasaka@xxxxxxxxxxxx> wrote:
>
> Hi Luiz,
>
> On Tue, Nov 24, 2020 at 4:23 PM Luiz Augusto von Dentz
> <luiz.dentz@xxxxxxxxx> wrote:
> >
> > Hi Sonny,
> >
> > On Tue, Nov 24, 2020 at 1:30 PM Sonny Sasaka <sonnysasaka@xxxxxxxxxxxx> wrote:
> > >
> > > Hi Luiz,
> > >
> > >
> > > On Tue, Nov 24, 2020 at 1:21 PM Luiz Augusto von Dentz
> > > <luiz.dentz@xxxxxxxxx> wrote:
> > > >
> > > > Hi Sonny,
> > > >
> > > > On Fri, Nov 20, 2020 at 1:00 PM Sonny Sasaka <sonnysasaka@xxxxxxxxxxxx> 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>
> > > > >
> > > > > ---
> > > > > Changes in v3:
> > > > > * Remove doc duplication in BatteryProvider1 and mention that it's the
> > > > > same as Battery1 instead.
> > > > > * Suggest profile UUID in Source property.
> > > > >
> > > > > doc/battery-api.txt | 49 +++++++++++++++++++++++++++++++++++++++++++++
> > > > > 1 file changed, 49 insertions(+)
> > > > >
> > > > > diff --git a/doc/battery-api.txt b/doc/battery-api.txt
> > > > > index dc7dbeda2..b5c9a7be1 100644
> > > > > --- a/doc/battery-api.txt
> > > > > +++ b/doc/battery-api.txt
> > > > > @@ -12,3 +12,52 @@ 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).
> > > >
> > > > We might need to remove the version number here since there is no
> > > > equivalent on UUID, in fact friendly names may be a bad idea after all
> > > > since for new profiles we may not have a friendly name to do the
> > > > translation and since this is property that would be hard to notify
> > > > the provider that we don't understand what is the Source while UUIDs,
> > > > if well formatted, should not have this problem so Id just get rid of
> > > > the use of friendly names altogether and expect the Source to be a
> > > > 128bits UUID in string format.
> > > Ack. Will change to 128bit UUID format.
> > > >
> > > > > +
> > > > > +
> > > > > +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.
> > > >
> > > > We should probably mention this expects an object implementing
> > > > ObjectManaged in order to list the Battery1 provider.
> > > Ack. Will add more explanation.
> > > >
> > > > > + 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}/org/bluez/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
> > > >
> > > > If this is on the client the object path does not necessarily need to
> > > > follow our object hierarchy.
> > > We need a convention to match the exposed object by the battery
> > > provider and BlueZ's device. I am suggesting that the simplest
> > > convention is to use the same path of the BlueZ's device object, which
> > > is easy to follow and implement by providers. Otherwise, we would
> > > still need another convention to match them, but I think any other
> > > convention is likely more complex to implement by battery providers.
> > > Can you suggest an alternative convention to match the battery and the
> > > device?
> >
> > I thought the objects would be registered directly on the device
> > object itself but it looks like it is on the adapter thus why you need
> > the device in the first place, but if you are using the object path it
> > is just a matter of moving BatteryProviderManager1 to the device
> > object.
> If we move BatteryProviderManager1 to the device object, that means we
> can't use the object manager style and providers have to register each
> battery once rather than registering once in the beginning and expose
> several objects afterwards, so this would lose your suggestion to use
> object manager in the first place. I prefer we stick to using object
> manager style, it is simple, easy to understand and implement for
> providers (refer to my python test app in one of the patches in this
> series).
Well not really, you can still use the object manager style the only
difference is that you will register on a per-device basis instead of
per adapter, not every device is going to have battery providers but
some can have multiple providers from different profiles, but I guess
you were suggesting that one could register a single time per adapter
so we don't have round trips of registration per device in which case
then I would prefer to just have a property indicating the device
object path, but note that if there are different entities handling
different profiles each would have to register individually anyway.
> >
> > > >
> > > > > +
> > > > > +Properties Objects provided on this interface contain the same properties
> > > > > + as org.bluez.Battery1 interface.
> > > > > --
> > > > > 2.26.2
> > > >
> > > >
> > > >
> > > > --
> > > > Luiz Augusto von Dentz
> >
> >
> >
> > --
> > Luiz Augusto von Dentz
--
Luiz Augusto von Dentz
