| Message ID | 20201120205728.339325-4-sonnysasaka@chromium.org |
|---|---|
| State | New |
| Headers | show |
| Series | [BlueZ,v3,1/7] battery: Add the internal Battery API | expand |
Hi Sonny, On Fri, Nov 20, 2020 at 1:00 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> > > --- > 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. > + > + > +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. > + 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. > + > +Properties Objects provided on this interface contain the same properties > + as org.bluez.Battery1 interface. > -- > 2.26.2 -- Luiz Augusto von Dentz
Hi Luiz, On Tue, Nov 24, 2020 at 1:21 PM Luiz Augusto von Dentz <luiz.dentz@gmail.com> wrote: > > Hi Sonny, > > On Fri, Nov 20, 2020 at 1:00 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> > > > > --- > > 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? > > > + > > +Properties Objects provided on this interface contain the same properties > > + as org.bluez.Battery1 interface. > > -- > > 2.26.2 > > > > -- > Luiz Augusto von Dentz
Hi Sonny, On Tue, Nov 24, 2020 at 1:30 PM Sonny Sasaka <sonnysasaka@chromium.org> wrote: > > Hi Luiz, > > > On Tue, Nov 24, 2020 at 1:21 PM Luiz Augusto von Dentz > <luiz.dentz@gmail.com> wrote: > > > > Hi Sonny, > > > > On Fri, Nov 20, 2020 at 1:00 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> > > > > > > --- > > > 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. > > > > > + > > > +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
Hi Luiz, On Tue, Nov 24, 2020 at 4:23 PM Luiz Augusto von Dentz <luiz.dentz@gmail.com> wrote: > > Hi Sonny, > > On Tue, Nov 24, 2020 at 1:30 PM Sonny Sasaka <sonnysasaka@chromium.org> wrote: > > > > Hi Luiz, > > > > > > On Tue, Nov 24, 2020 at 1:21 PM Luiz Augusto von Dentz > > <luiz.dentz@gmail.com> wrote: > > > > > > Hi Sonny, > > > > > > On Fri, Nov 20, 2020 at 1:00 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> > > > > > > > > --- > > > > 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). > > > > > > > > + > > > > +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
On Tue, 2020-11-24 at 13:29 -0800, Sonny Sasaka wrote: > > 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? You should match on the interface being available, not the object path. UPower does that, it just watches for ObjectManager signals, and checks whether the expected interface is available when a new object appears: https://gitlab.freedesktop.org/upower/upower/-/blob/master/src/linux/up-backend.c#L314-357 There's no reason to care about the object path.
On Tue, 2020-11-24 at 17:20 -0800, Sonny Sasaka wrote: > > 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). org.freedesktop.DBus.ObjectManager.InterfacesAdded would show the interface appearing. It's also what UPower expects bluez to do.
Hi Sonny, On Tue, Nov 24, 2020 at 5:20 PM Sonny Sasaka <sonnysasaka@chromium.org> wrote: > > Hi Luiz, > > On Tue, Nov 24, 2020 at 4:23 PM Luiz Augusto von Dentz > <luiz.dentz@gmail.com> wrote: > > > > Hi Sonny, > > > > On Tue, Nov 24, 2020 at 1:30 PM Sonny Sasaka <sonnysasaka@chromium.org> wrote: > > > > > > Hi Luiz, > > > > > > > > > On Tue, Nov 24, 2020 at 1:21 PM Luiz Augusto von Dentz > > > <luiz.dentz@gmail.com> wrote: > > > > > > > > Hi Sonny, > > > > > > > > On Fri, Nov 20, 2020 at 1:00 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> > > > > > > > > > > --- > > > > > 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
Hi Luiz, On Sat, Nov 28, 2020 at 10:16 PM Luiz Augusto von Dentz <luiz.dentz@gmail.com> wrote: > > Hi Sonny, > > On Tue, Nov 24, 2020 at 5:20 PM Sonny Sasaka <sonnysasaka@chromium.org> wrote: > > > > Hi Luiz, > > > > On Tue, Nov 24, 2020 at 4:23 PM Luiz Augusto von Dentz > > <luiz.dentz@gmail.com> wrote: > > > > > > Hi Sonny, > > > > > > On Tue, Nov 24, 2020 at 1:30 PM Sonny Sasaka <sonnysasaka@chromium.org> wrote: > > > > > > > > Hi Luiz, > > > > > > > > > > > > On Tue, Nov 24, 2020 at 1:21 PM Luiz Augusto von Dentz > > > > <luiz.dentz@gmail.com> wrote: > > > > > > > > > > Hi Sonny, > > > > > > > > > > On Fri, Nov 20, 2020 at 1:00 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> > > > > > > > > > > > > --- > > > > > > 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. I like your idea of explicitly specifying the device path for each provided battery. I will send a v4 for this change. Please take another look. > > > > > > > > > > > > > > > + > > > > > > +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
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). + + +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}/org/bluez/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX + +Properties Objects provided on this interface contain the same properties + as org.bluez.Battery1 interface.
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> --- 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(+)