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 event - MGMT_EV_DEVICE_FOUND to pass advertisements to
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 adds a flag in the exiting 'Device Found' event to
indicate that the device is being tracked by an Advertisement Monitor.
Kernel updates this flag based on the receipt of the controller event
HCI_VS_MSFT_LE_Monitor_Device_Event. A new MGMT event - 'Device Lost'
has been added to indicate that the controller has stopped tracking a
device already being tracked.
Please let me know what you think about this or if you have any further
questions.
Thanks,
Manish.
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.
- 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.
- Update function name adv_monitor_tracking_callback() to
adv_monitor_device_lost_callback() as it will receive only Device Lost
event.
Manish Mandlik (3):
doc: Introduce the Adv Monitor Device Lost event
lib: Add definition of the Adv Monitor Device Lost event
adv_monitor: Receive the Device Lost event
doc/mgmt-api.txt | 32 +++++++++++++++++++++++++++++++-
lib/mgmt.h | 9 +++++++++
src/adv_monitor.c | 25 +++++++++++++++++++++++++
3 files changed, 65 insertions(+), 1 deletion(-)
--
2.33.0.882.g93a45727a2-goog
Add a flag 'Device Tracked' to the existing 'Device Found' event to
indicate that the controller has started tracking the device matching
an Advertisement Monitor with handle 'Monitor_Handle'.
Add a new event 'Adv Monitor Device Lost' to indicate that the
controller has stopped tracking that particular device.
---
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 | 32 +++++++++++++++++++++++++++++++-
1 file changed, 31 insertions(+), 1 deletion(-)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 5355fedb0..0fd884ed0 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -107,7 +107,8 @@ Configuration command, Default Runtime Configuration Changed event, Get
Device Flags command, Set Device Flags command, Device Flags Changed event,
Read Advertisement Monitor Features command, Add Advertisement Patterns
Monitor command, Remove Advertisement Monitor command, Advertisement Monitor
-Added event and Advertisement Monitor Removed event.
+Added event, Advertisement Monitor Removed event, Updated Device Found event
+and Added Advertisement Monitor Device Lost event.
Example
@@ -4247,6 +4248,7 @@ Device Found Event
Address_Type (1 Octet)
RSSI (1 Octet)
Flags (4 Octets)
+ Monitor_Handle (2 Octets)
EIR_Data_Length (2 Octets)
EIR_Data (0-65535 Octets)
@@ -4263,6 +4265,7 @@ Device Found Event
1 Legacy Pairing
2 Not Connectable
3 Reserved (not in use)
+ 4 Device Tracked
For the RSSI field a value of 127 indicates that the RSSI is
not available. That can happen with Bluetooth 1.1 and earlier
@@ -4285,6 +4288,10 @@ Device Found Event
accept any connections. This can be indicated by Low Energy
devices that are in broadcaster role.
+ The Device Tracked flag indicates that the controller has started
+ monitoring a particular device matching the Advertisement Monitor
+ with handle Monitor_Handle.
+
Discovering Event
=================
@@ -4910,3 +4917,26 @@ 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 Lost Event
+=======================================
+
+ Event code: 0x002f
+ 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 the
+ device that was being tracked by monitor with 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 BR/EDR
+ 1 LE Public
+ 2 LE Random
+
+ This event will be sent to all management sockets.
--
2.33.0.882.g93a45727a2-goog
This patch adds a flag to the Device Found event to indicate that the
controller is tracking a device and adds definition of the new Device
Lost event to indicate that the controller has stopped tracking that
device.
---
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.
lib/mgmt.h | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/lib/mgmt.h b/lib/mgmt.h
index 0a6349321..70e3d31f9 100644
--- a/lib/mgmt.h
+++ b/lib/mgmt.h
@@ -856,12 +856,14 @@ struct mgmt_ev_auth_failed {
#define MGMT_DEV_FOUND_CONFIRM_NAME 0x01
#define MGMT_DEV_FOUND_LEGACY_PAIRING 0x02
#define MGMT_DEV_FOUND_NOT_CONNECTABLE 0x04
+#define MGMT_DEV_FOUND_MONITORING 0x10
#define MGMT_EV_DEVICE_FOUND 0x0012
struct mgmt_ev_device_found {
struct mgmt_addr_info addr;
int8_t rssi;
uint32_t flags;
+ uint16_t monitor_handle;
uint16_t eir_len;
uint8_t eir[0];
} __packed;
@@ -1014,6 +1016,12 @@ struct mgmt_ev_controller_resume {
uint8_t wake_reason;
} __packed;
+#define MGMT_EV_ADV_MONITOR_DEVICE_LOST 0x002f
+struct mgmt_ev_adv_monitor_device_lost {
+ uint16_t monitor_handle;
+ struct mgmt_addr_info addr;
+} __packed;
+
static const char *mgmt_op[] = {
"<0x0000>",
"Read Version",
@@ -1152,6 +1160,7 @@ static const char *mgmt_ev[] = {
"Advertisement Monitor Removed",
"Controller Suspend",
"Controller Resume",
+ "Advertisement Monitor Device Lost", /* 0x002f */
};
static const char *mgmt_status[] = {
--
2.33.0.882.g93a45727a2-goog
Hi Manish,
> Add a flag 'Device Tracked' to the existing 'Device Found' event to
> indicate that the controller has started tracking the device matching
> an Advertisement Monitor with handle 'Monitor_Handle'.
>
> Add a new event 'Adv Monitor Device Lost' to indicate that the
> controller has stopped tracking that particular device.
>
> ---
>
> 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 | 32 +++++++++++++++++++++++++++++++-
> 1 file changed, 31 insertions(+), 1 deletion(-)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index 5355fedb0..0fd884ed0 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -107,7 +107,8 @@ Configuration command, Default Runtime Configuration Changed event, Get
> Device Flags command, Set Device Flags command, Device Flags Changed event,
> Read Advertisement Monitor Features command, Add Advertisement Patterns
> Monitor command, Remove Advertisement Monitor command, Advertisement Monitor
> -Added event and Advertisement Monitor Removed event.
> +Added event, Advertisement Monitor Removed event, Updated Device Found event
> +and Added Advertisement Monitor Device Lost event.
>
>
> Example
> @@ -4247,6 +4248,7 @@ Device Found Event
> Address_Type (1 Octet)
> RSSI (1 Octet)
> Flags (4 Octets)
> + Monitor_Handle (2 Octets)
> EIR_Data_Length (2 Octets)
> EIR_Data (0-65535 Octets)
you can not do this. This breaks ABI.
Regards
Marcel
Hi Marcel, Manish,
On Wed, Oct 13, 2021 at 6:15 AM Marcel Holtmann <[email protected]> wrote:
>
> Hi Manish,
>
> > Add a flag 'Device Tracked' to the existing 'Device Found' event to
> > indicate that the controller has started tracking the device matching
> > an Advertisement Monitor with handle 'Monitor_Handle'.
> >
> > Add a new event 'Adv Monitor Device Lost' to indicate that the
> > controller has stopped tracking that particular device.
> >
> > ---
> >
> > 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 | 32 +++++++++++++++++++++++++++++++-
> > 1 file changed, 31 insertions(+), 1 deletion(-)
> >
> > diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> > index 5355fedb0..0fd884ed0 100644
> > --- a/doc/mgmt-api.txt
> > +++ b/doc/mgmt-api.txt
> > @@ -107,7 +107,8 @@ Configuration command, Default Runtime Configuration Changed event, Get
> > Device Flags command, Set Device Flags command, Device Flags Changed event,
> > Read Advertisement Monitor Features command, Add Advertisement Patterns
> > Monitor command, Remove Advertisement Monitor command, Advertisement Monitor
> > -Added event and Advertisement Monitor Removed event.
> > +Added event, Advertisement Monitor Removed event, Updated Device Found event
> > +and Added Advertisement Monitor Device Lost event.
> >
> >
> > Example
> > @@ -4247,6 +4248,7 @@ Device Found Event
> > Address_Type (1 Octet)
> > RSSI (1 Octet)
> > Flags (4 Octets)
> > + Monitor_Handle (2 Octets)
> > EIR_Data_Length (2 Octets)
> > EIR_Data (0-65535 Octets)
>
> you can not do this. This breaks ABI.
I was going to say that, we can't be adding parameters to existing
commands/events as that is not backward compatible (old bluetoothd
won't be able to parse them properly). That said, I wonder why it
needs the handle though? Wouldn't a flag be enough to indicate that
has been found via monitor filtering or do we need to know the exact
monitor rule that has triggered it?
Btw, afaik monitor handles as 1 octet not 2.
--
Luiz Augusto von Dentz