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