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 v4:
- Change the signature of SupportedMonitorTypes to be array of strings.
- Fix document formatting.
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 | 137 ++++++++++++++++++++++++++++++
1 file changed, 137 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..012fce420
--- /dev/null
+++ b/doc/advertisement-monitor-api.txt
@@ -0,0 +1,137 @@
+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 [experimental]
+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.
+
+Advertisement Monitor Manager hierarchy
+=======================================
+Service org.bluez
+Interface org.bluez.AdvertisementMonitorManager1 [experimental]
+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} 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:
+
+ "patterns_with_logic_or"
+ 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.
--
2.24.1
Hi Miao,
On Mon, Apr 27, 2020 at 1:16 PM Miao-chen Chou <[email protected]> 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 v4:
> - Change the signature of SupportedMonitorTypes to be array of strings.
> - Fix document formatting.
>
> 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 | 137 ++++++++++++++++++++++++++++++
> 1 file changed, 137 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..012fce420
> --- /dev/null
> +++ b/doc/advertisement-monitor-api.txt
> @@ -0,0 +1,137 @@
> +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 [experimental]
> +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.
> +
> +Advertisement Monitor Manager hierarchy
> +=======================================
> +Service org.bluez
> +Interface org.bluez.AdvertisementMonitorManager1 [experimental]
> +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} 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:
> +
> + "patterns_with_logic_or"
> + 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.
> --
> 2.24.1
Applied, thanks, note that I did change the Type to be string as well
so we is consistent with SupportMonitorTypes.
--
Luiz Augusto von Dentz
Great! Thank you so much.
On Mon, Apr 27, 2020 at 2:38 PM Luiz Augusto von Dentz
<[email protected]> wrote:
>
> Hi Miao,
>
> On Mon, Apr 27, 2020 at 1:16 PM Miao-chen Chou <[email protected]> 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 v4:
> > - Change the signature of SupportedMonitorTypes to be array of strings.
> > - Fix document formatting.
> >
> > 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 | 137 ++++++++++++++++++++++++++++++
> > 1 file changed, 137 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..012fce420
> > --- /dev/null
> > +++ b/doc/advertisement-monitor-api.txt
> > @@ -0,0 +1,137 @@
> > +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 [experimental]
> > +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.
> > +
> > +Advertisement Monitor Manager hierarchy
> > +=======================================
> > +Service org.bluez
> > +Interface org.bluez.AdvertisementMonitorManager1 [experimental]
> > +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} 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:
> > +
> > + "patterns_with_logic_or"
> > + 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.
> > --
> > 2.24.1
>
> Applied, thanks, note that I did change the Type to be string as well
> so we is consistent with SupportMonitorTypes.
>
> --
> Luiz Augusto von Dentz
Hi Miao-chen,
> 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 v4:
> - Change the signature of SupportedMonitorTypes to be array of strings.
> - Fix document formatting.
>
> 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 | 137 ++++++++++++++++++++++++++++++
> 1 file changed, 137 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..012fce420
> --- /dev/null
> +++ b/doc/advertisement-monitor-api.txt
> @@ -0,0 +1,137 @@
> +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 [experimental]
> +Object path freely definable
can you please at least roughly follow the style regarding the empty lines from the other documents.
> +
> +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().
Do we actually need this? As noted by Szymon we would expect RegisterMonitor to only return when it successfully active a monitor.
> +
> + 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.
This part we really need to discuss and come to an agreement. I am not in favor of doing these as properties on the monitor object. I would give them as dict to the RegisterMonitor.
> +
> +Advertisement Monitor Manager hierarchy
> +=======================================
> +Service org.bluez
> +Interface org.bluez.AdvertisementMonitorManager1 [experimental]
> +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
My choice of method naming would be RegisterMonitor and UnregisterMonitor.
> +
> +Properties array{string} 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:
> +
> + "patterns_with_logic_or"
> + Patterns with logic OR applied. With this type,
> + property "Patterns" must exist and has at least
> + one pattern.
To be consistent they need to be “patterns-with-or-logic”. And maybe “or-patterns” is just enough.
> +
> + 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.
I would consider shortening this to “controller-patterns”.
Regards
Marcel
On Wed, Apr 29, 2020 at 10:11 AM Von Dentz, Luiz
<[email protected]> wrote:
>
> Hi Marcel,
>
> On Wed, Apr 29, 2020 at 1:13 AM Marcel Holtmann <[email protected]> wrote:
>>
>> Hi Miao-chen,
>>
>> > 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 v4:
>> > - Change the signature of SupportedMonitorTypes to be array of strings.
>> > - Fix document formatting.
>> >
>> > 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 | 137 ++++++++++++++++++++++++++++++
>> > 1 file changed, 137 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..012fce420
>> > --- /dev/null
>> > +++ b/doc/advertisement-monitor-api.txt
>> > @@ -0,0 +1,137 @@
>> > +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 [experimental]
>> > +Object path freely definable
>>
>> can you please at least roughly follow the style regarding the empty lines from the other documents.
>>
>> > +
>> > +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().
>>
>> Do we actually need this? As noted by Szymon we would expect RegisterMonitor to only return when it successfully active a monitor.
If we go with the direction where a client is allowed to expose
multiple monitor objects at a time, then we need a way for the client
to get notified once the monitors are activated. We don't need this if
we only allow a client to register one monitor at a time.
>>
>> > +
>> > + 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.
>>
>> This part we really need to discuss and come to an agreement. I am not in favor of doing these as properties on the monitor object. I would give them as dict to the RegisterMonitor.
>>
>
> That was actually my recommendation to do go this way since we do want to support registering multiple objects at once which is usually done with the likes of ObjectManager to list the whole tree of objects, if we go with given this direction to RegisterMonitor this might have to be an array e.g a{oa{sv}} which would require custom code to extract the objects and create proper proxies for them, so I rather keep this simple and just use ObjectManager to list the objects.
>
>>
>> > +
>> > +Advertisement Monitor Manager hierarchy
>> > +=======================================
>> > +Service org.bluez
>> > +Interface org.bluez.AdvertisementMonitorManager1 [experimental]
>> > +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
>>
>> My choice of method naming would be RegisterMonitor and UnregisterMonitor.
>>
>> > +
>> > +Properties array{string} 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:
>> > +
>> > + "patterns_with_logic_or"
>> > + Patterns with logic OR applied. With this type,
>> > + property "Patterns" must exist and has at least
>> > + one pattern.
>>
>> To be consistent they need to be “patterns-with-or-logic”. And maybe “or-patterns” is just enough.
ack
>>
>> > +
>> > + 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.
>>
>> I would consider shortening this to “controller-patterns”.
Ack.
>>
>> Regards
>>
>> Marcel
>>