* [BlueZ PATCH v4] doc: Add Advertisement Monitoring API
@ 2020-04-27 20:12 Miao-chen Chou
2020-04-27 21:38 ` Luiz Augusto von Dentz
2020-04-29 8:13 ` Marcel Holtmann
0 siblings, 2 replies; 5+ messages in thread
From: Miao-chen Chou @ 2020-04-27 20:12 UTC (permalink / raw)
To: Bluetooth Kernel Mailing List
Cc: Michael Sun, Luiz Augusto von Dentz, Marcel Holtmann,
Yoni Shavit, Alain Michaud, Miao-chen Chou
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
^ permalink raw reply related [flat|nested] 5+ messages in thread
* Re: [BlueZ PATCH v4] doc: Add Advertisement Monitoring API
2020-04-27 20:12 [BlueZ PATCH v4] doc: Add Advertisement Monitoring API Miao-chen Chou
@ 2020-04-27 21:38 ` Luiz Augusto von Dentz
2020-04-28 22:02 ` Miao-chen Chou
2020-04-29 8:13 ` Marcel Holtmann
1 sibling, 1 reply; 5+ messages in thread
From: Luiz Augusto von Dentz @ 2020-04-27 21:38 UTC (permalink / raw)
To: Miao-chen Chou
Cc: Bluetooth Kernel Mailing List, Michael Sun,
Luiz Augusto von Dentz, Marcel Holtmann, Yoni Shavit,
Alain Michaud
Hi Miao,
On Mon, Apr 27, 2020 at 1:16 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 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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [BlueZ PATCH v4] doc: Add Advertisement Monitoring API
2020-04-27 21:38 ` Luiz Augusto von Dentz
@ 2020-04-28 22:02 ` Miao-chen Chou
0 siblings, 0 replies; 5+ messages in thread
From: Miao-chen Chou @ 2020-04-28 22:02 UTC (permalink / raw)
To: Luiz Augusto von Dentz
Cc: Bluetooth Kernel Mailing List, Michael Sun,
Luiz Augusto von Dentz, Marcel Holtmann, Yoni Shavit,
Alain Michaud
Great! Thank you so much.
On Mon, Apr 27, 2020 at 2:38 PM Luiz Augusto von Dentz
<luiz.dentz@gmail.com> wrote:
>
> Hi Miao,
>
> On Mon, Apr 27, 2020 at 1:16 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 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
^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: [BlueZ PATCH v4] doc: Add Advertisement Monitoring API
2020-04-27 20:12 [BlueZ PATCH v4] doc: Add Advertisement Monitoring API Miao-chen Chou
2020-04-27 21:38 ` Luiz Augusto von Dentz
@ 2020-04-29 8:13 ` Marcel Holtmann
[not found] ` <CACumGO+Ss4s=tcaosXMRfVkccRZ_42Hh3YCr1bgFaUz5a6SUBw@mail.gmail.com>
1 sibling, 1 reply; 5+ messages in thread
From: Marcel Holtmann @ 2020-04-29 8:13 UTC (permalink / raw)
To: Miao-chen Chou
Cc: Bluetooth Kernel Mailing List, Michael Sun,
Luiz Augusto von Dentz, Yoni Shavit, Alain Michaud
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
^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2020-04-30 1:09 UTC | newest]
Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-04-27 20:12 [BlueZ PATCH v4] doc: Add Advertisement Monitoring API Miao-chen Chou
2020-04-27 21:38 ` Luiz Augusto von Dentz
2020-04-28 22:02 ` Miao-chen Chou
2020-04-29 8:13 ` Marcel Holtmann
[not found] ` <CACumGO+Ss4s=tcaosXMRfVkccRZ_42Hh3YCr1bgFaUz5a6SUBw@mail.gmail.com>
2020-04-30 1:09 ` Miao-chen Chou
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).