From: Miao-chen Chou <mcchou@chromium.org>
To: Bluetooth Kernel Mailing List <linux-bluetooth@vger.kernel.org>
Cc: Marcel Holtmann <marcel@holtmann.org>,
Luiz Augusto von Dentz <luiz.von.dentz@intel.com>,
Alain Michaud <alainm@chromium.org>,
Yoni Shavit <yshavit@chromium.org>,
Michael Sun <michaelfsun@google.com>,
Miao-chen Chou <mcchou@chromium.org>
Subject: [BlueZ PATCH v5] doc: Add Advertisement Monitoring API
Date: Fri, 1 May 2020 16:10:59 -0700 [thread overview]
Message-ID: <20200501161017.BlueZ.v5.1.I137a529ab03c9d0d2327f1659bd1af4954a28e78@changeid> (raw)
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 v5:
- Fix indentation of few lines.
- Shorten the name of functions and strings of parameters.
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..eb5c83768
--- /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 RegisterMonitor(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 UnregisterMonitor(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:
+
+ "or_patterns"
+ 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-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
reply other threads:[~2020-05-01 23:11 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200501161017.BlueZ.v5.1.I137a529ab03c9d0d2327f1659bd1af4954a28e78@changeid \
--to=mcchou@chromium.org \
--cc=alainm@chromium.org \
--cc=linux-bluetooth@vger.kernel.org \
--cc=luiz.von.dentz@intel.com \
--cc=marcel@holtmann.org \
--cc=michaelfsun@google.com \
--cc=yshavit@chromium.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).