[RFC BlueZ] Add Proximity Reporter interface - Proposal 1

[RFC BlueZ] Add Proximity Reporter interface - Proposal 1

[Claudio Takahasi]

Adds API for Immediate Alert Service(IAS) abstraction. Abstraction for
Link Loss is not planned. IAS is used by Proximity Monitors and Find
Me Locators to notify the user that the device(or key fob) has been
found. This new interface combines Proximity Reporter and Find Me
Target in the same API providing the flexibility to implement external
applications to control the alerts(including per device alerts).

This abstraction allows the development of platform specific
applications to control Immediate Alert coming from Proximity Monitor
and Find Me Locator. This provides flexibility to define different level
and tone for each known device.

--
Alternatively, ImmediateAlertChanged signal containing device object
path and the alert level could be exposed avoiding the device object
path in the Proximity Reporter hierarchy. For this case Adapter object
path should be used. Use the Adapter object path makes more difficult
to track alert level changes related to a given device, on other hand
it is more aligned with the current BR/EDR APIs.
---
 doc/proximity-api.txt |   33 +++++++++++++++++++++++++++++++--
 1 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/doc/proximity-api.txt b/doc/proximity-api.txt
index cf64bbf..10f4fa6 100644
--- a/doc/proximity-api.txt
+++ b/doc/proximity-api.txt
@@ -4,8 +4,8 @@ BlueZ D-Bus Proximity API description
 Copyright (C) 2011  Claudio Takahasi <claudio.takahasi@openbossa.org>
 
 
-Proximity hierarchy
-=================
+Proximity Monitor hierarchy
+===========================
 
 Service		org.bluez
 Interface	org.bluez.ProximityMonitor
@@ -52,3 +52,32 @@ Properties
 			"none" will be emitted after the configured timeout.
 			When changing the level, signal is the confirmation
 			that the value was written in the remote.
+
+Proximity Reporter hierarchy
+===========================
+
+Shared service used by Proximity Path Loss and Find Me. Allows per device
+alert level handling.
+
+Service		org.bluez
+Interface	org.bluez.ProximityReporter
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods		dict GetProperties()
+
+			Returns all properties for the interface. See the
+			properties section for available properties.
+
+Signals		PropertyChanged(string name, variant value)
+
+			This signal indicates a changed value of a given
+			property.
+
+Properties
+
+		string ImmediateAlertLevel [readonly]
+
+			New Immediate Alert Level Characteristic value
+			has been written by the remote device. Property
+			shared between Path Loss and Find Me. Values:
+			"none", "mild", "high". Default value is "none".
-- 
1.7.8.1

[RFC BlueZ] Add Proximity Reporter interface - Proposal 2

[Claudio Takahasi]

Adds API for Immediate Alert Service(IAS) abstraction. Abstraction for
Link Loss is not planned. IAS is used by Proximity Monitors and Find
Me Locators to notify the user that the device(or key fob) has been
found. This new interface combines Proximity Reporter and Find Me
Target in the same API providing the flexibility to implement external
applications to control the alerts(including per device alerts).

This abstraction allows the development of platform specific
applications to control Immediate Alert coming from Proximity Monitor
and Find Me Locator. This provides flexibility to define different level
and tone for each device.
---
 doc/proximity-api.txt |   25 +++++++++++++++++++++++--
 1 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/doc/proximity-api.txt b/doc/proximity-api.txt
index cf64bbf..c825fc7 100644
--- a/doc/proximity-api.txt
+++ b/doc/proximity-api.txt
@@ -4,8 +4,8 @@ BlueZ D-Bus Proximity API description
 Copyright (C) 2011  Claudio Takahasi <claudio.takahasi@openbossa.org>
 
 
-Proximity hierarchy
-=================
+Proximity Monitor hierarchy
+===========================
 
 Service		org.bluez
 Interface	org.bluez.ProximityMonitor
@@ -52,3 +52,24 @@ Properties
 			"none" will be emitted after the configured timeout.
 			When changing the level, signal is the confirmation
 			that the value was written in the remote.
+
+Proximity Reporter hierarchy
+===========================
+
+Shared service used by Proximity Path Loss and Find Me. Allows per device
+alert level handling.
+
+Service		org.bluez
+Interface	org.bluez.ProximityReporter
+Object path	[variable prefix]/{hci0,hci1,...}
+
+Methods
+
+
+Signals		ImmediateAlertChanged(object device, string value)
+
+			This signal indicates that Immediate Alert Level
+			characteristic was changed by the remote device.
+			Values: "none", "mild", "high".
+
+Properties
-- 
1.7.8.1

[PATCH BlueZ 1/2] Add Proximity Reporter API

[Claudio Takahasi]

Adds API for Immediate Alert Service(IAS) abstraction. IAS is used
by Proximity Monitors and Find Me Locators to notify the user that
reporter/target has been found. This new interface combines Proximity
Reporter and Find Me Target in the same API providing the flexibility
to implement external applications to control alerts(including per
device alerts).

This abstraction allows the development of platform specific
applications to control Immediate Alert coming from Proximity Monitor
and Find Me Locator. This provides flexibility to define different level
and tone for each device. Use case: watch finding a mobile phone.
---
 doc/proximity-api.txt |   25 +++++++++++++++++++++++--
 1 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/doc/proximity-api.txt b/doc/proximity-api.txt
index cf64bbf..32d6474 100644
--- a/doc/proximity-api.txt
+++ b/doc/proximity-api.txt
@@ -4,8 +4,8 @@ BlueZ D-Bus Proximity API description
 Copyright (C) 2011  Claudio Takahasi <claudio.takahasi@openbossa.org>
 
 
-Proximity hierarchy
-=================
+Proximity Monitor hierarchy
+===========================
 
 Service		org.bluez
 Interface	org.bluez.ProximityMonitor
@@ -52,3 +52,24 @@ Properties
 			"none" will be emitted after the configured timeout.
 			When changing the level, signal is the confirmation
 			that the value was written in the remote.
+
+Proximity Reporter hierarchy
+===========================
+
+Service used by Proximity Path Loss and Find Me. Allows per device
+alert level handling.
+
+Service		org.bluez
+Interface	org.bluez.ProximityReporter
+Object path	[variable prefix]/{hci0,hci1,...}
+
+Methods
+
+
+Signals		ImmediateAlertLevelChanged(object device, string value)
+
+			This signal indicates that Immediate Alert Level
+			characteristic was changed by the remote device.
+			Values: "none", "mild", "high".
+
+Properties
-- 
1.7.8.1

Re: [PATCH BlueZ 1/2] Add Proximity Reporter API

[Johan Hedberg]

Hi Claudio,

On Fri, Jan 13, 2012, Claudio Takahasi wrote:
> +Proximity Reporter hierarchy
> +===========================
> +
> +Service used by Proximity Path Loss and Find Me. Allows per device
> +alert level handling.
> +
> +Service		org.bluez
> +Interface	org.bluez.ProximityReporter
> +Object path	[variable prefix]/{hci0,hci1,...}
> +
> +Methods
> +
> +
> +Signals		ImmediateAlertLevelChanged(object device, string value)
> +
> +			This signal indicates that Immediate Alert Level
> +			characteristic was changed by the remote device.
> +			Values: "none", "mild", "high".
> +
> +Properties

Shouldn't ImmediateAlertLevel and LinkLossAlertLevel be defined as
properties and then you'd have PropertyChanged instead of these custom
signals?

Johan

Re: [PATCH BlueZ 1/2] Add Proximity Reporter API

[Anderson Lizardo]

Hi Johan,

On Wed, Jan 18, 2012 at 8:17 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
> Hi Claudio,
>
> On Fri, Jan 13, 2012, Claudio Takahasi wrote:
>> +Proximity Reporter hierarchy
>> +===========================
>> +
>> +Service used by Proximity Path Loss and Find Me. Allows per device
>> +alert level handling.
>> +
>> +Service              org.bluez
>> +Interface    org.bluez.ProximityReporter
>> +Object path  [variable prefix]/{hci0,hci1,...}
>> +
>> +Methods
>> +
>> +
>> +Signals              ImmediateAlertLevelChanged(object device, string value)
>> +
>> +                     This signal indicates that Immediate Alert Level
>> +                     characteristic was changed by the remote device.
>> +                     Values: "none", "mild", "high".
>> +
>> +Properties
>
> Shouldn't ImmediateAlertLevel and LinkLossAlertLevel be defined as
> properties and then you'd have PropertyChanged instead of these custom
> signals?

Initially, we discarded one approach where we could have Properties on
the _device_ object path, because we would need to monitor each new
created device, check if it has the Immediate/LinkLossAlertLevel
property on the ProximityReporter interface, and if so, listen to the
PropertyChanged signal. This seems too much overhead IMHO.

Unless you are proposing keeping the interface and properties on the
adapter object path? In this case, we will lose the information about
the peer device which issued the alert. I'm unsure if this is a big
problem or not (given that the alert is "global" to the Proximity
Reporter, not a per peer state).

On the other hand, this "custom signal" approach allows to have only
one (or two) listener, no matter how many devices are connected to the
reporter, and still know which peer triggered the alert.

One benefit of knowing which device triggered the alert, is to have
custom alerts (e.g. different sounds) for each device, or if the
reporter has a display, show which device is making alerts.

Any ideas?
-- 
Anderson Lizardo
Instituto Nokia de Tecnologia - INdT
Manaus - Brazil

Re: [PATCH BlueZ 1/2] Add Proximity Reporter API

[Claudio Takahasi]

Hi Johan,

On Wed, Jan 18, 2012 at 9:49 AM, Anderson Lizardo
<anderson.lizardo@openbossa.org> wrote:
> Hi Johan,
>
> On Wed, Jan 18, 2012 at 8:17 AM, Johan Hedberg <johan.hedberg@gmail.com> wrote:
>> Hi Claudio,
>>
>> On Fri, Jan 13, 2012, Claudio Takahasi wrote:
>>> +Proximity Reporter hierarchy
>>> +===========================
>>> +
>>> +Service used by Proximity Path Loss and Find Me. Allows per device
>>> +alert level handling.
>>> +
>>> +Service              org.bluez
>>> +Interface    org.bluez.ProximityReporter
>>> +Object path  [variable prefix]/{hci0,hci1,...}
>>> +
>>> +Methods
>>> +
>>> +
>>> +Signals              ImmediateAlertLevelChanged(object device, string value)
>>> +
>>> +                     This signal indicates that Immediate Alert Level
>>> +                     characteristic was changed by the remote device.
>>> +                     Values: "none", "mild", "high".
>>> +
>>> +Properties
>>
>> Shouldn't ImmediateAlertLevel and LinkLossAlertLevel be defined as
>> properties and then you'd have PropertyChanged instead of these custom
>> signals?
>
> Initially, we discarded one approach where we could have Properties on
> the _device_ object path, because we would need to monitor each new
> created device, check if it has the Immediate/LinkLossAlertLevel
> property on the ProximityReporter interface, and if so, listen to the
> PropertyChanged signal. This seems too much overhead IMHO.
>
> Unless you are proposing keeping the interface and properties on the
> adapter object path? In this case, we will lose the information about
> the peer device which issued the alert. I'm unsure if this is a big
> problem or not (given that the alert is "global" to the Proximity
> Reporter, not a per peer state).
>
> On the other hand, this "custom signal" approach allows to have only
> one (or two) listener, no matter how many devices are connected to the
> reporter, and still know which peer triggered the alert.
>
> One benefit of knowing which device triggered the alert, is to have
> custom alerts (e.g. different sounds) for each device, or if the
> reporter has a display, show which device is making alerts.
>
> Any ideas?
> --
> Anderson Lizardo
> Instituto Nokia de Tecnologia - INdT
> Manaus - Brazil

I will send the proposal that you are suggesting to collect more
feedbacks, it is the RFC "proposal "1 sent some weeks ago.
Complementing what Lizardo wrote, use the device object path is not
aligned with the current APIs.
PropertyChanged for ImmediateAlertLevel or LinkLossAlertLevel will be
sent when the remote device(GATT client) writes a new value in the
alert level characteristic of the local GATT service(Link Loss or
Immediate Alert). If this concept of sending PropertyChanged signal
using the device's object path for an action triggered by the remote
is clear to everyone we can continue this approach.

BR,
Claudio

[PATCH BlueZ 1/2] Add Proximity Reporter API

[Claudio Takahasi]

Adds API for Immediate Alert Service(IAS) abstraction. IAS is used
by Proximity Monitors and Find Me Locators to notify the user that
reporter/target has been found. This new interface combines Proximity
Reporter and Find Me Target in the same API providing the flexibility
to implement external applications to control alerts(including per
device alerts).

This abstraction allows the development of platform specific
applications to control Immediate Alert coming from Proximity Monitor
and Find Me Locator. This provides flexibility to define different level
and tone for each device. Use case: watch finding a mobile phone.
---
 doc/proximity-api.txt |   34 ++++++++++++++++++++++++++++++++--
 1 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/doc/proximity-api.txt b/doc/proximity-api.txt
index cf64bbf..3e49149 100644
--- a/doc/proximity-api.txt
+++ b/doc/proximity-api.txt
@@ -4,8 +4,8 @@ BlueZ D-Bus Proximity API description
 Copyright (C) 2011  Claudio Takahasi <claudio.takahasi@openbossa.org>
 
 
-Proximity hierarchy
-=================
+Proximity Monitor hierarchy
+===========================
 
 Service		org.bluez
 Interface	org.bluez.ProximityMonitor
@@ -52,3 +52,33 @@ Properties
 			"none" will be emitted after the configured timeout.
 			When changing the level, signal is the confirmation
 			that the value was written in the remote.
+
+Proximity Reporter hierarchy
+===========================
+
+Shared service used by Proximity Path Loss and Find Me. Allows per device
+alert level handling.
+
+Service		org.bluez
+Interface	org.bluez.ProximityReporter
+Object path	[variable prefix]/{hci0,hci1,...}/dev_XX_XX_XX_XX_XX_XX
+
+Methods		dict GetProperties()
+
+			Returns all properties for the interface. See the
+			properties section for available properties.
+
+Signals		PropertyChanged(string name, variant value)
+
+			This signal indicates a changed value of a given
+			property.
+
+Properties
+
+		string ImmediateAlertLevel [readonly]
+
+			This property indicates that Immediate Alert Level
+			characteristic in the local Immediate Alert Service
+			was changed by the remote device. Property shared
+			between Path Loss and Find Me. Values: "none", "mild",
+			"high".
-- 
1.7.8.1

Re: [PATCH BlueZ 1/2] Add Proximity Reporter API

[Johan Hedberg]

Hi Claudio,

On Thu, Jan 19, 2012, Claudio Takahasi wrote:
> Adds API for Immediate Alert Service(IAS) abstraction. IAS is used
> by Proximity Monitors and Find Me Locators to notify the user that
> reporter/target has been found. This new interface combines Proximity
> Reporter and Find Me Target in the same API providing the flexibility
> to implement external applications to control alerts(including per
> device alerts).
> 
> This abstraction allows the development of platform specific
> applications to control Immediate Alert coming from Proximity Monitor
> and Find Me Locator. This provides flexibility to define different level
> and tone for each device. Use case: watch finding a mobile phone.
> ---
>  doc/proximity-api.txt |   34 ++++++++++++++++++++++++++++++++--
>  1 files changed, 32 insertions(+), 2 deletions(-)

Both patches have been applied. Thanks.

Johan