diff mbox series

[BlueZ,v2] doc: Add Advertisement Monitoring API

Message ID 20200415200831.BlueZ.v2.1.I137a529ab03c9d0d2327f1659bd1af4954a28e78@changeid (mailing list archive)
State Superseded
Headers show
Series [BlueZ,v2] doc: Add Advertisement Monitoring API | expand

Commit Message

Miao-chen Chou April 16, 2020, 3:09 a.m. UTC 
This patch proposes an Advertisement Monitoring API for an application to
register a job of monitoring ADV reports with content filter and RSSI
thresholds.

Signed-off-by: Miao-chen Chou <mcchou@chromium.org>
---

Changes in v2:
- Rename the interfaces and functions.
- Adopt the object manager mechanism so that a client can expose
multiple monitor objects and expect to get notified on whether the
monitor has been activated or not.
- Change the contract of DeviceFound so that it is called to indicate
the starting point of monitoring on a device instead of reporting every
ADV. In other words, the client is expected to monitor corresponding
device events.

 doc/advertisement-monitor-api.txt | 127 ++++++++++++++++++++++++++++++
 1 file changed, 127 insertions(+)
 create mode 100644 doc/advertisement-monitor-api.txt

Comments

Szymon Janc April 16, 2020, 7:49 a.m. UTC | #1 
Hi,

On Thursday, 16 April 2020 05:09:03 CEST Miao-chen Chou wrote:
> This patch proposes an Advertisement Monitoring API for an application to
> register a job of monitoring ADV reports with content filter and RSSI
> thresholds.
> 
> Signed-off-by: Miao-chen Chou <mcchou@chromium.org>
> ---
> 
> Changes in v2:
> - Rename the interfaces and functions.
> - Adopt the object manager mechanism so that a client can expose
> multiple monitor objects and expect to get notified on whether the
> monitor has been activated or not.
> - Change the contract of DeviceFound so that it is called to indicate
> the starting point of monitoring on a device instead of reporting every
> ADV. In other words, the client is expected to monitor corresponding
> device events.
> 
>  doc/advertisement-monitor-api.txt | 127 ++++++++++++++++++++++++++++++
>  1 file changed, 127 insertions(+)
>  create mode 100644 doc/advertisement-monitor-api.txt
> 
> diff --git a/doc/advertisement-monitor-api.txt
> b/doc/advertisement-monitor-api.txt new file mode 100644
> index 000000000..6491dab29
> --- /dev/null
> +++ b/doc/advertisement-monitor-api.txt
> @@ -0,0 +1,127 @@
> +BlueZ D-Bus Advertisement Monitor API Description
> +*************************************************
> +
> +This API allows an client to specify a job of monitoring advertisements by
> +registering the root of hierarchy and then exposing advertisement monitors
> +under the root with filtering conditions, thresholds of RSSI and timers
> +of RSSI thresholds.
> +
> +Once a monitoring job is activated by BlueZ, the client can expect to get
> +notified on the targeted advertisements no matter if there is an ongoing
> +discovery session (a discovery session is started/stopped with methods in
> +org.bluez.Adapter1 interface).
> +
> +Advertisement Monitor hierarchy
> +===============================
> +Service		org.bluez
> +Interface	org.bluez.AdvertisementMonitor1
> +Object path	freely definable
> +
> +Methods		void Release() [noreply]
> +
> +			This gets called as a signal for a client to 
perform
> +			clean-up when (1)a monitor cannot be activated 
after it
> +			was exposed or (2)a monitor has been 
deactivated.
> +
> +		void Activate() [noreply]

Isn't is enough for RegisterApplication to return to ack this?

> +
> +			After a monitor was exposed, this gets called as 
a
> +			signal for client to get acknowledged when a 
monitor
> +			has been activated, so the client can expect to 
receive
> +			calls on DeviceFound() or DeviceLost().
> +
> +		void DeviceFound(object device) [noreply]
> +
> +			This gets called to notify the client of finding 
the
> +			targeted device. Once receiving the call, the 
client
> +			should start to monitor the corresponding device 
to
> +			retrieve the changes on RSSI and advertisement 
content.
> +
> +		void DeviceLost(object device) [noreply]
> +
> +			This gets called to notify the client of losing 
the
> +			targeted device. Once receiving this call, the 
client
> +			should stop monitoring the corresponding device.
> +
> +Properties	uint8 Type [read-only]
> +
> +			The type of a monitor can be the following 
values. More
> +			will be added.
> +			0x01 - Patterns with logic OR applied
> +				Supported only if "patterns-with-
logic-or-
> +				applied" is supported.
> +
> +		(Int16, Uint16, Int16, Uint16) RSSIThreshholdsAndTimers 
[read-only,
> optional] +
> +			This contains HighRSSIThreshold, 
HighRSSIThresholdTimer,
> +			LowRSSIThreshold, LowRSSIThresholdTimer in 
order. The
> +			unit of HighRSSIThreshold and LowRSSIThreshold 
is dBm.
> +			The unit of HighRSSIThresholdTimer and
> +			LowRSSIThresholdTimer is second.
> +
> +			If these are provided, RSSI would be used as a 
factor to
> +			notify the client of whether a device stays in 
range or
> +			move out of range. A device is considered in-
range when
> +			the RSSIs of the received advertisement(s) 
during
> +			HighRSSIThresholdTimer seconds exceed 
HighRSSIThreshold.
> +			Likewise, a device is considered out-of-range 
when the
> +			RSSIs of the received advertisement(s) during
> +			LowRSSIThresholdTimer do not reach 
LowRSSIThreshold.
> +
> +		array{(uint8, uint8, string)} Patterns [read-only, 
optional]
> +
> +			If Type is set to 0x01, this must exist and has 
at least
> +			one entry in the array.
> +
> +			The structure of a pattern contains the 
following.
> +			uint8 start_position
> +				The index in an AD data field where 
the search
> +				should start. The beginning of an AD 
data field
> +				is index 0.
> +			uint8 AD_data_type
> +				See https://www.bluetooth.com/
specifications/
> +				assigned-numbers/generic-access-
profile/ for
> +				the possible allowed value.
> +			string content_of_pattern
> +				This is the value of the pattern.
> +
> +=======================================
> +Service		org.bluez
> +Interface	org.bluez.AdvertisementMonitorManager1
> +Object path	/org/bluez/{hci0,hci1,...}
> +Methods		void RegisterApplication(object application)
> +
> +			This registers a hierarchy of advertisement 
monitors.
> +			The application object path together with the D-
Bus
> +			system bus connection ID define the 
identification of
> +			the application registering advertisement 
monitors.
> +
> +			Possible errors: 
org.bluez.Error.InvalidArguments
> +					 
org.bluez.Error.AlreadyExists
> +
> +		void UnregisterApplication(object application)
> +
> +			This unregisters advertisement monitors that 
have been
> +			previously registered. The object path parameter 
must
> +			match the same value that has been used on
> +			registration.
> +
> +			Possible errors: 
org.bluez.Error.InvalidArguments
> +					 
org.bluez.Error.DoesNotExist
> +
> +Properties	array{string} SupportedFeatures [read-only]
> +
> +			This reflects the supported features of 
advertisement
> +			monitoring. An application should check this 
before
> +			instantiate and expose an object of
> +			org.bluez.AdvertisementMonitor1.
> +
> +			Here are the potential features. More will be 
added.
> +			software-based-filtering
> +				The filtering process is mainly done 
in BlueZ.
> +			patterns-with-logic-or-applied
> +				Logic OR would be applied among the 
patterns
> +				provided by a monitor object.
> +			rssi-monitoring
> +				Values of RSSIThreshholdsAndTimers 
would be
> +				applied during the filtering process.


I'm bit confused about this API. Why can't this be achieved with (possible 
extended)  SetDiscoveryFilter? We could just add extra prop to Device1 to 
indicate that device is "present".
Miao-chen Chou April 16, 2020, 10:46 p.m. UTC | #2 
Hi Szymon,

Thanks for your comments. Please see my inline replies below.

On Thu, Apr 16, 2020 at 12:49 AM Szymon Janc <szymon.janc@codecoup.pl> wrote:
>
> Hi,
>
> On Thursday, 16 April 2020 05:09:03 CEST Miao-chen Chou wrote:
> > This patch proposes an Advertisement Monitoring API for an application to
> > register a job of monitoring ADV reports with content filter and RSSI
> > thresholds.
> >
> > Signed-off-by: Miao-chen Chou <mcchou@chromium.org>
> > ---
> >
> > Changes in v2:
> > - Rename the interfaces and functions.
> > - Adopt the object manager mechanism so that a client can expose
> > multiple monitor objects and expect to get notified on whether the
> > monitor has been activated or not.
> > - Change the contract of DeviceFound so that it is called to indicate
> > the starting point of monitoring on a device instead of reporting every
> > ADV. In other words, the client is expected to monitor corresponding
> > device events.
> >
> >  doc/advertisement-monitor-api.txt | 127 ++++++++++++++++++++++++++++++
> >  1 file changed, 127 insertions(+)
> >  create mode 100644 doc/advertisement-monitor-api.txt
> >
> > diff --git a/doc/advertisement-monitor-api.txt
> > b/doc/advertisement-monitor-api.txt new file mode 100644
> > index 000000000..6491dab29
> > --- /dev/null
> > +++ b/doc/advertisement-monitor-api.txt
> > @@ -0,0 +1,127 @@
> > +BlueZ D-Bus Advertisement Monitor API Description
> > +*************************************************
> > +
> > +This API allows an client to specify a job of monitoring advertisements by
> > +registering the root of hierarchy and then exposing advertisement monitors
> > +under the root with filtering conditions, thresholds of RSSI and timers
> > +of RSSI thresholds.
> > +
> > +Once a monitoring job is activated by BlueZ, the client can expect to get
> > +notified on the targeted advertisements no matter if there is an ongoing
> > +discovery session (a discovery session is started/stopped with methods in
> > +org.bluez.Adapter1 interface).
> > +
> > +Advertisement Monitor hierarchy
> > +===============================
> > +Service              org.bluez
> > +Interface    org.bluez.AdvertisementMonitor1
> > +Object path  freely definable
> > +
> > +Methods              void Release() [noreply]
> > +
> > +                     This gets called as a signal for a client to
> perform
> > +                     clean-up when (1)a monitor cannot be activated
> after it
> > +                     was exposed or (2)a monitor has been
> deactivated.
> > +
> > +             void Activate() [noreply]
>
> Isn't is enough for RegisterApplication to return to ack this?
RegisterApplication() only registers the root of a hierarchy, it
doesn't actually add any monitor, so the return of it reflects the
result of creating the root only. A client can expose some monitors
later under that root, and once bluetooth gets object-added via object
manager, it would call either Release() or Activate() to let the
client know about whether a monitor has been adopted by bluetoothd or
not.
>
> > +
> > +                     After a monitor was exposed, this gets called as
> a
> > +                     signal for client to get acknowledged when a
> monitor
> > +                     has been activated, so the client can expect to
> receive
> > +                     calls on DeviceFound() or DeviceLost().
> > +
> > +             void DeviceFound(object device) [noreply]
> > +
> > +                     This gets called to notify the client of finding
> the
> > +                     targeted device. Once receiving the call, the
> client
> > +                     should start to monitor the corresponding device
> to
> > +                     retrieve the changes on RSSI and advertisement
> content.
> > +
> > +             void DeviceLost(object device) [noreply]
> > +
> > +                     This gets called to notify the client of losing
> the
> > +                     targeted device. Once receiving this call, the
> client
> > +                     should stop monitoring the corresponding device.
> > +
> > +Properties   uint8 Type [read-only]
> > +
> > +                     The type of a monitor can be the following
> values. More
> > +                     will be added.
> > +                     0x01 - Patterns with logic OR applied
> > +                             Supported only if "patterns-with-
> logic-or-
> > +                             applied" is supported.
> > +
> > +             (Int16, Uint16, Int16, Uint16) RSSIThreshholdsAndTimers
> [read-only,
> > optional] +
> > +                     This contains HighRSSIThreshold,
> HighRSSIThresholdTimer,
> > +                     LowRSSIThreshold, LowRSSIThresholdTimer in
> order. The
> > +                     unit of HighRSSIThreshold and LowRSSIThreshold
> is dBm.
> > +                     The unit of HighRSSIThresholdTimer and
> > +                     LowRSSIThresholdTimer is second.
> > +
> > +                     If these are provided, RSSI would be used as a
> factor to
> > +                     notify the client of whether a device stays in
> range or
> > +                     move out of range. A device is considered in-
> range when
> > +                     the RSSIs of the received advertisement(s)
> during
> > +                     HighRSSIThresholdTimer seconds exceed
> HighRSSIThreshold.
> > +                     Likewise, a device is considered out-of-range
> when the
> > +                     RSSIs of the received advertisement(s) during
> > +                     LowRSSIThresholdTimer do not reach
> LowRSSIThreshold.
> > +
> > +             array{(uint8, uint8, string)} Patterns [read-only,
> optional]
> > +
> > +                     If Type is set to 0x01, this must exist and has
> at least
> > +                     one entry in the array.
> > +
> > +                     The structure of a pattern contains the
> following.
> > +                     uint8 start_position
> > +                             The index in an AD data field where
> the search
> > +                             should start. The beginning of an AD
> data field
> > +                             is index 0.
> > +                     uint8 AD_data_type
> > +                             See https://www.bluetooth.com/
> specifications/
> > +                             assigned-numbers/generic-access-
> profile/ for
> > +                             the possible allowed value.
> > +                     string content_of_pattern
> > +                             This is the value of the pattern.
> > +
> > +=======================================
> > +Service              org.bluez
> > +Interface    org.bluez.AdvertisementMonitorManager1
> > +Object path  /org/bluez/{hci0,hci1,...}
> > +Methods              void RegisterApplication(object application)
> > +
> > +                     This registers a hierarchy of advertisement
> monitors.
> > +                     The application object path together with the D-
> Bus
> > +                     system bus connection ID define the
> identification of
> > +                     the application registering advertisement
> monitors.
> > +
> > +                     Possible errors:
> org.bluez.Error.InvalidArguments
> > +
> org.bluez.Error.AlreadyExists
> > +
> > +             void UnregisterApplication(object application)
> > +
> > +                     This unregisters advertisement monitors that
> have been
> > +                     previously registered. The object path parameter
> must
> > +                     match the same value that has been used on
> > +                     registration.
> > +
> > +                     Possible errors:
> org.bluez.Error.InvalidArguments
> > +
> org.bluez.Error.DoesNotExist
> > +
> > +Properties   array{string} SupportedFeatures [read-only]
> > +
> > +                     This reflects the supported features of
> advertisement
> > +                     monitoring. An application should check this
> before
> > +                     instantiate and expose an object of
> > +                     org.bluez.AdvertisementMonitor1.
> > +
> > +                     Here are the potential features. More will be
> added.
> > +                     software-based-filtering
> > +                             The filtering process is mainly done
> in BlueZ.
> > +                     patterns-with-logic-or-applied
> > +                             Logic OR would be applied among the
> patterns
> > +                             provided by a monitor object.
> > +                     rssi-monitoring
> > +                             Values of RSSIThreshholdsAndTimers
> would be
> > +                             applied during the filtering process.
>
>
> I'm bit confused about this API. Why can't this be achieved with (possible
> extended)  SetDiscoveryFilter? We could just add extra prop to Device1 to
> indicate that device is "present".
This API is fundamentally different from the existing APIs. Currently,
in terms of LE there are 2 entries to perform scanning in BlueZ
(bluetoothd + kernel) - (1) Discovery session (with transport dual or
le) actively managed by D-Bus client (2) passive scanning managed by
kernel for auto-reconnection purpose. The intention of (1) is to find
the device ASAP, and (1) is widely used in the case where people open
a Bluetooth setting page to locate the device for pairing or
connection. The intention of (2) is to detect the LE devices for
reconnection, and this is purely done in the kernel. In addition to
(1) and (2), this API intends to provide the third entry to perform
scanning, and that is to allow D-Bus clients to monitor on LE
advertisements with RSSI thresholds and content filtering but without
the need of actively managed by D-Bus in a power efficient way (There
will be future works around offloading filtering to controllers based
on Microsoft HCI extension or Android HCI extension.) This would
empower applications which requires LE scanning in the background and
eventually trigger some events. For instance, prompting a notification
to the user if a new BLE mouse is close by and asking a user if he/she
would like to pair with it, this way, the user doesn't need to
manually look for the targeted device.

Thanks,
Miao
diff mbox series

Patch

diff --git a/doc/advertisement-monitor-api.txt b/doc/advertisement-monitor-api.txt
new file mode 100644
index 000000000..6491dab29
--- /dev/null
+++ b/doc/advertisement-monitor-api.txt
@@ -0,0 +1,127 @@ 
+BlueZ D-Bus Advertisement Monitor API Description
+*************************************************
+
+This API allows an client to specify a job of monitoring advertisements by
+registering the root of hierarchy and then exposing advertisement monitors
+under the root with filtering conditions, thresholds of RSSI and timers
+of RSSI thresholds.
+
+Once a monitoring job is activated by BlueZ, the client can expect to get
+notified on the targeted advertisements no matter if there is an ongoing
+discovery session (a discovery session is started/stopped with methods in
+org.bluez.Adapter1 interface).
+
+Advertisement Monitor hierarchy
+===============================
+Service		org.bluez
+Interface	org.bluez.AdvertisementMonitor1
+Object path	freely definable
+
+Methods		void Release() [noreply]
+
+			This gets called as a signal for a client to perform
+			clean-up when (1)a monitor cannot be activated after it
+			was exposed or (2)a monitor has been deactivated.
+
+		void Activate() [noreply]
+
+			After a monitor was exposed, this gets called as a
+			signal for client to get acknowledged when a monitor
+			has been activated, so the client can expect to receive
+			calls on DeviceFound() or DeviceLost().
+
+		void DeviceFound(object device) [noreply]
+
+			This gets called to notify the client of finding the
+			targeted device. Once receiving the call, the client
+			should start to monitor the corresponding device to
+			retrieve the changes on RSSI and advertisement content.
+
+		void DeviceLost(object device) [noreply]
+
+			This gets called to notify the client of losing the
+			targeted device. Once receiving this call, the client
+			should stop monitoring the corresponding device.
+
+Properties	uint8 Type [read-only]
+
+			The type of a monitor can be the following values. More
+			will be added.
+			0x01 - Patterns with logic OR applied
+				Supported only if "patterns-with-logic-or-
+				applied" is supported.
+
+		(Int16, Uint16, Int16, Uint16) RSSIThreshholdsAndTimers [read-only, optional]
+
+			This contains HighRSSIThreshold, HighRSSIThresholdTimer,
+			LowRSSIThreshold, LowRSSIThresholdTimer in order. The
+			unit of HighRSSIThreshold and LowRSSIThreshold is dBm.
+			The unit of HighRSSIThresholdTimer and
+			LowRSSIThresholdTimer is second.
+
+			If these are provided, RSSI would be used as a factor to
+			notify the client of whether a device stays in range or
+			move out of range. A device is considered in-range when
+			the RSSIs of the received advertisement(s) during
+			HighRSSIThresholdTimer seconds exceed HighRSSIThreshold.
+			Likewise, a device is considered out-of-range when the
+			RSSIs of the received advertisement(s) during
+			LowRSSIThresholdTimer do not reach LowRSSIThreshold.
+
+		array{(uint8, uint8, string)} Patterns [read-only, optional]
+
+			If Type is set to 0x01, this must exist and has at least
+			one entry in the array.
+
+			The structure of a pattern contains the following.
+			uint8 start_position
+				The index in an AD data field where the search
+				should start. The beginning of an AD data field
+				is index 0.
+			uint8 AD_data_type
+				See https://www.bluetooth.com/specifications/
+				assigned-numbers/generic-access-profile/ for
+				the possible allowed value.
+			string content_of_pattern
+				This is the value of the pattern.
+
+=======================================
+Service		org.bluez
+Interface	org.bluez.AdvertisementMonitorManager1
+Object path	/org/bluez/{hci0,hci1,...}
+Methods		void RegisterApplication(object application)
+
+			This registers a hierarchy of advertisement monitors.
+			The application object path together with the D-Bus
+			system bus connection ID define the identification of
+			the application registering advertisement monitors.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.AlreadyExists
+
+		void UnregisterApplication(object application)
+
+			This unregisters advertisement monitors that have been
+			previously registered. The object path parameter must
+			match the same value that has been used on
+			registration.
+
+			Possible errors: org.bluez.Error.InvalidArguments
+					 org.bluez.Error.DoesNotExist
+
+Properties	array{string} SupportedFeatures [read-only]
+
+			This reflects the supported features of advertisement
+			monitoring. An application should check this before
+			instantiate and expose an object of
+			org.bluez.AdvertisementMonitor1.
+
+			Here are the potential features. More will be added.
+			software-based-filtering
+				The filtering process is mainly done in BlueZ.
+			patterns-with-logic-or-applied
+				Logic OR would be applied among the patterns
+				provided by a monitor object.
+			rssi-monitoring
+				Values of RSSIThreshholdsAndTimers would be
+				applied during the filtering process.