diff mbox series

[BlueZ,v3] doc: Add Advertisement Monitoring API

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

Commit Message

Miao-chen Chou April 23, 2020, 9:14 p.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.
---

Changes in v3:
- Introduce SupportedFeatures to reflect the features based on
controller's capabilities.
- Modify SupportedMonitorTypes to list available types of monitors.

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 | 134 ++++++++++++++++++++++++++++++
 1 file changed, 134 insertions(+)
 create mode 100644 doc/advertisement-monitor-api.txt

Comments

Luiz Augusto von Dentz April 24, 2020, 7:38 p.m. UTC | #1
Hi Miao,

On Thu, Apr 23, 2020 at 2:17 PM Miao-chen Chou <mcchou@chromium.org> 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.
> ---
>
> Changes in v3:
> - Introduce SupportedFeatures to reflect the features based on
> controller's capabilities.
> - Modify SupportedMonitorTypes to list available types of monitors.
>
> 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 | 134 ++++++++++++++++++++++++++++++
>  1 file changed, 134 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..b8b01536a
> --- /dev/null
> +++ b/doc/advertisement-monitor-api.txt
> @@ -0,0 +1,134 @@
> +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 the monitor. See SupportedMonitorTypes in
> +                       org.bluez.AdvertisementMonitorManager1 for the available
> +                       options.
> +
> +               (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{uint8} SupportedMonitorTypes [read-only]
> +
> +                       This lists the supported types of advertisement
> +                       monitors. An application should check this before
> +                       instantiate and expose an object of
> +                       org.bluez.AdvertisementMonitor1.
> +
> +                       Possible values for monitor types:
> +
> +                       0x01    Patterns with logic OR applied. With this type,
> +                               property "Patterns" must exist and has at least
> +                               one pattern.

Perhaps we should also have this as string, D-Bus don't really support
enums and it makes the types easier to debug if we express in them as
strings.

> +
> +               array{string} SupportedFeatures [read-only]
> +
> +                       This lists the features of advertisement monitoring
> +                       supported by BlueZ.
> +
> +                       Possible values for features:
> +
> +                       "controller-based-monitor-by-patterns"
> +                               If the controller is capable of performing
> +                               advertisement monitoring by patterns, BlueZ
> +                               would offload the patterns to the controller to
> +                               reduce power consumption.
> --
> 2.24.1

Other than that it looks good to me, the only thing Id mark this
interface as experimental for now so we still allow changes if we deem
necessary.
Miao-chen Chou April 27, 2020, 8:14 p.m. UTC | #2
Hi Luiz,

Thanks for your feedback. Your comments were addressed in v4, please
take another look.

On Fri, Apr 24, 2020 at 12:38 PM Luiz Augusto von Dentz
<luiz.dentz@gmail.com> wrote:
>
> Hi Miao,
>
> On Thu, Apr 23, 2020 at 2:17 PM Miao-chen Chou <mcchou@chromium.org> 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.
> > ---
> >
> > Changes in v3:
> > - Introduce SupportedFeatures to reflect the features based on
> > controller's capabilities.
> > - Modify SupportedMonitorTypes to list available types of monitors.
> >
> > 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 | 134 ++++++++++++++++++++++++++++++
> >  1 file changed, 134 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..b8b01536a
> > --- /dev/null
> > +++ b/doc/advertisement-monitor-api.txt
> > @@ -0,0 +1,134 @@
> > +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 the monitor. See SupportedMonitorTypes in
> > +                       org.bluez.AdvertisementMonitorManager1 for the available
> > +                       options.
> > +
> > +               (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{uint8} SupportedMonitorTypes [read-only]
> > +
> > +                       This lists the supported types of advertisement
> > +                       monitors. An application should check this before
> > +                       instantiate and expose an object of
> > +                       org.bluez.AdvertisementMonitor1.
> > +
> > +                       Possible values for monitor types:
> > +
> > +                       0x01    Patterns with logic OR applied. With this type,
> > +                               property "Patterns" must exist and has at least
> > +                               one pattern.
>
> Perhaps we should also have this as string, D-Bus don't really support
> enums and it makes the types easier to debug if we express in them as
> strings.
>
> > +
> > +               array{string} SupportedFeatures [read-only]
> > +
> > +                       This lists the features of advertisement monitoring
> > +                       supported by BlueZ.
> > +
> > +                       Possible values for features:
> > +
> > +                       "controller-based-monitor-by-patterns"
> > +                               If the controller is capable of performing
> > +                               advertisement monitoring by patterns, BlueZ
> > +                               would offload the patterns to the controller to
> > +                               reduce power consumption.
> > --
> > 2.24.1
>
> Other than that it looks good to me, the only thing Id mark this
> interface as experimental for now so we still allow changes if we deem
> necessary.
>
>
> --
> Luiz Augusto von Dentz

Regards,
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..b8b01536a
--- /dev/null
+++ b/doc/advertisement-monitor-api.txt
@@ -0,0 +1,134 @@ 
+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 the monitor. See SupportedMonitorTypes in
+			org.bluez.AdvertisementMonitorManager1 for the available
+			options.
+
+		(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{uint8} SupportedMonitorTypes [read-only]
+
+			This lists the supported types of advertisement
+			monitors. An application should check this before
+			instantiate and expose an object of
+			org.bluez.AdvertisementMonitor1.
+
+			Possible values for monitor types:
+
+			0x01	Patterns with logic OR applied. With this type,
+				property "Patterns" must exist and has at least
+				one pattern.
+
+		array{string} SupportedFeatures [read-only]
+
+			This lists the features of advertisement monitoring
+			supported by BlueZ.
+
+			Possible values for features:
+
+			"controller-based-monitor-by-patterns"
+				If the controller is capable of performing
+				advertisement monitoring by patterns, BlueZ
+				would offload the patterns to the controller to
+				reduce power consumption.