diff mbox series

[BlueZ,v6,1/6] doc: Introduce the Adv Monitor Device Found/Lost events

Message ID 20211120072449.BlueZ.v6.1.I7f6bdb9282c1e12ffc6c662674678f2b1cb69182@changeid (mailing list archive)
State Accepted
Delegated to: Luiz Von Dentz
Headers show
Series [BlueZ,v6,1/6] doc: Introduce the Adv Monitor Device Found/Lost events | expand

Checks

Context Check Description
tedd_an/checkpatch success Checkpatch PASS
tedd_an/gitlint success Gitlint PASS
tedd_an/setupell success Setup ELL PASS
tedd_an/buildprep success Build Prep PASS
tedd_an/build success Build Configuration PASS
tedd_an/makecheck success Make Check PASS
tedd_an/makedistcheck success Make Distcheck PASS
tedd_an/build_extell success Build External ELL PASS
tedd_an/build_extell_make success Build Make with External ELL PASS

Commit Message

Manish Mandlik Nov. 20, 2021, 3:29 p.m. UTC
This patch introduces two new MGMT events
MGMT_EV_ADV_MONITOR_DEVICE_FOUND and MGMT_EV_ADV_MONITOR_DEVICE_LOST to
indicate that the controller has started/stopped tracking a particular
device matching one of the already added Advertisement Monitor.

If the controller offloading support is not available,
MGMT_EV_ADV_MONITOR_DEVICE_FOUND event is also used to report all
advertisements to perform software based filtering whenever we are not
active scanning.

Reviewed-by: Miao-chen Chou <mcchou@google.com>
---
Hello Bt-Maintainers,

Bluetooth Advertisement Monitor API was introduced to support background
scanning and proximity detection based on the application specified RSSI
thresholds and content filters on LE advertisement packets.

To optimize the power consumption, the API offloads the content
filtering and RSSI tracking to the controller if the controller
offloading support is available. However, this monitoring is not
completely offloaded as the bluetoothd also handles RSSI thresholds and
timeouts in order to fulfill high/low thresholds/timeouts filtering with
D-bus clients.

There is further room to achieve better power optimization by supporting
the controller event HCI_VS_MSFT_LE_Monitor_Device_Event to fulfill true
monitor offloading. This is currently not supported as it was originally
desired to minimize the changes to the MGMT interface and reuse the
existing MGMT_EV_DEVICE_FOUND event to pass advertisements to the
bluetoothd and let bluetoothd handle the RSSI thresholds and timeouts in
order to fulfill the D-bus API requirements for the client.

This patch series introduces MGMT events MGMT_EV_ADV_MONITOR_DEVICE_FOUND
and MGMT_EV_ADV_MONITOR_DEVICE_LOST to indicate that the controller has
started/stopped monitoring a particular device.

Please let me know what you think about this or if you have any further
questions.

Thanks,
Manish.

(no changes since v5)

Changes in v5:
- Update the Adv Monitor Device Found event to include fields from the
  existing Device Found event.

Changes in v4:
- Add Advertisement Monitor Device Found event, make Address_Type 0 as
  reserved.

Changes in v3:
- Discard changes to the Device Found event and notify bluetoothd only
  when the controller stops monitoring the device via new Device Lost
  event.

Changes in v2:
- Instead of creating a new 'Device Tracking' event, add a flag 'Device
  Tracked' in the existing 'Device Found' event and add a new 'Device
  Lost' event to indicate that the controller has stopped tracking that
  device.

 doc/mgmt-api.txt | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

Comments

bluez.test.bot@gmail.com Nov. 20, 2021, 4 p.m. UTC | #1
This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list.
This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=583423

---Test result---

Test Summary:
CheckPatch                    PASS      8.80 seconds
GitLint                       PASS      5.68 seconds
Prep - Setup ELL              PASS      49.12 seconds
Build - Prep                  PASS      0.54 seconds
Build - Configure             PASS      9.13 seconds
Build - Make                  PASS      205.71 seconds
Make Check                    PASS      9.38 seconds
Make Distcheck                PASS      240.14 seconds
Build w/ext ELL - Configure   PASS      8.69 seconds
Build w/ext ELL - Make        PASS      202.00 seconds



---
Regards,
Linux Bluetooth
Luiz Augusto von Dentz Nov. 22, 2021, 10:59 p.m. UTC | #2
Hi Manish,

On Sat, Nov 20, 2021 at 8:01 AM <bluez.test.bot@gmail.com> wrote:
>
> This is automated email and please do not reply to this email!
>
> Dear submitter,
>
> Thank you for submitting the patches to the linux bluetooth mailing list.
> This is a CI test results with your patch series:
> PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=583423
>
> ---Test result---
>
> Test Summary:
> CheckPatch                    PASS      8.80 seconds
> GitLint                       PASS      5.68 seconds
> Prep - Setup ELL              PASS      49.12 seconds
> Build - Prep                  PASS      0.54 seconds
> Build - Configure             PASS      9.13 seconds
> Build - Make                  PASS      205.71 seconds
> Make Check                    PASS      9.38 seconds
> Make Distcheck                PASS      240.14 seconds
> Build w/ext ELL - Configure   PASS      8.69 seconds
> Build w/ext ELL - Make        PASS      202.00 seconds
>
>
>
> ---
> Regards,
> Linux Bluetooth

Applied, thanks.
diff mbox series

Patch

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 97d33e30a..8e7b5ef70 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -4910,3 +4910,63 @@  Controller Resume Event
 	Address_Type. Otherwise, Address and Address_Type will both be zero.
 
 	This event will be sent to all management sockets.
+
+
+Advertisement Monitor Device Found Event
+========================================
+
+	Event code:		0x002f
+	Controller Index:	<controller_id>
+	Event Parameters:	Monitor_Handle (2 Octets)
+				Address (6 Octets)
+				Address_Type (1 Octet)
+				RSSI (1 Octet)
+				Flags (4 Octets)
+				AD_Data_Length (2 Octets)
+				AD_Data (0-65535 Octets)
+
+	This event indicates that the controller has started tracking a device
+	matching an Advertisement Monitor with handle Monitor_Handle.
+
+	Monitor_Handle 0 indicates that we are not active scanning and this
+	is a subsequent advertisement report for already matched Advertisement
+	Monitor or the controller offloading support is not available so need
+	to report all advertisements for software based filtering.
+
+	The address of the device being tracked will be shared in Address and
+	Address_Type.
+
+	Possible values for the Address_Type parameter:
+		0	Reserved (not in use)
+		1	LE Public
+		2	LE Random
+
+	For the RSSI field a value of 127 indicates that the RSSI is
+	not available. That can happen with Bluetooth 1.1 and earlier
+	controllers or with bad radio conditions.
+
+	This event will be sent to all management sockets.
+
+
+Advertisement Monitor Device Lost Event
+=======================================
+
+	Event code:		0x0030
+	Controller Index:	<controller_id>
+	Event Parameters:	Monitor_Handle (2 Octets)
+				Address (6 Octets)
+				Address_Type (1 Octet)
+
+	This event indicates that the controller has stopped tracking a device
+	that was being tracked by an Advertisement Monitor with the handle
+	Monitor_Handle.
+
+	The address of the device being tracked will be shared in Address and
+	Address_Type.
+
+	Possible values for the Address_Type parameter:
+		0	Reserved (not in use)
+		1	LE Public
+		2	LE Random
+
+	This event will be sent to all management sockets.