[Bluez,v1,1/2] doc/mgmt-api: Add opcode for adding advertisement monitor with RSSI

Commit Message

Archie Pusaka Dec. 15, 2020, 8:33 a.m. UTC

From: Archie Pusaka <[e-mail]>

This is to leverage the filtering by RSSI feature on those controllers
which supports advertisement packet filtering. To avoid changing the
existing API and breaking it, a new opcode is required.

Reviewed-by: Manish Mandlik <[e-mail]>
Reviewed-by: Miao-chen Chou <[e-mail]>
Reviewed-by: Yun-Hao Chung <[e-mail]>

Signed-off-by: Archie Pusaka <[e-mail]>
---

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

Comments

[e-mail] Dec. 15, 2020, 8:58 a.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=402091

---Test result---

##############################
Test: CheckPatch - PASS

##############################
Test: CheckGitLint - FAIL
Output:
lib/mgmt: Adding Add Adv Patterns Monitor RSSI opcode.
1: T3 Title has trailing punctuation (.): "lib/mgmt: Adding Add Adv Patterns Monitor RSSI opcode."


##############################
Test: CheckBuild - PASS

##############################
Test: MakeCheck - PASS



---
Regards,
Linux Bluetooth

Luiz Augusto von Dentz Dec. 15, 2020, 5:54 p.m. UTC | #2

Hi Archie,

On Tue, Dec 15, 2020 at 12:33 AM Archie Pusaka <[e-mail]> wrote:
>
> From: Archie Pusaka <[e-mail]>
>
> This is to leverage the filtering by RSSI feature on those controllers
> which supports advertisement packet filtering. To avoid changing the
> existing API and breaking it, a new opcode is required.
>
> Reviewed-by: Manish Mandlik <[e-mail]>
> Reviewed-by: Miao-chen Chou <[e-mail]>
> Reviewed-by: Yun-Hao Chung <[e-mail]>
>
> Signed-off-by: Archie Pusaka <[e-mail]>
> ---
>
>  doc/mgmt-api.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 52 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index 1aa43d6c3c..d5c7169630 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -3800,6 +3800,58 @@ Add Extended Advertising Data Command
>                                 Busy
>
>
> +Add Advertisement Patterns Monitor With RSSI Threshold Command
> +==============================================================
> +
> +       Command Code:           0x0056
> +       Controller Index:       <controller id>
> +       Command Parameters:     Pattern_Count (1 Octet)

I'd move the pattern_count after the rssi if the rssi is not per
pattern, well in case the rssi is per pattern then it should be put
inside the Pattern directly.

> +                               RSSI_Data {
> +                                       High_Threshold (1 Octet)
> +                                       High_Threshold_Timer (2 Octets)
> +                                       Low_Threshold (1 Octet)
> +                                       Low_Threshold_Timer (2 Octets)
> +                                       Sampling_Period (1 Octet)
> +                               }
> +                               Pattern1 {
> +                                       AD_Type (1 Octet)
> +                                       Offset (1 Octet)
> +                                       Length (1 Octet)
> +                                       Value (31 Octets)
> +                               }
> +                               Pattern2 { }
> +                               ...
> +       Return Parameters:      Monitor_Handle (2 Octets)
> +
> +       This command is essentially the same as Add Advertisement Patterns
> +       Monitor Command (0x0052), but with an additional RSSI parameters.
> +       As such, if the kernel supports advertisement filtering, then the
> +       advertisement data will be filtered in accordance with the set
> +       RSSI parameters. Otherwise, it would behave exactly the same as the
> +       Add Advertisement Patterns Monitor Command.
> +
> +       Devices would be considered "in-range" if the RSSI of the received adv
> +       packets are greater than High_Threshold dBm for High_Threshold_Timer
> +       seconds. Similarly, devices would be considered lost if no received
> +       adv have RSSI greater than Low_Threshold dBm for Low_Threshold_Timer
> +       seconds. Only adv packets of "in-range" device would be propagated.
> +
> +       The meaning of Sampling_Period is as follows:
> +               0x00    All adv packets from "in-range" devices would be
> +                       propagated.
> +               0xFF    Only the first adv data of "in-range" devices would be
> +                       propagated. If the device becomes lost, then the first
> +                       data when it is found again will also be propagated.
> +               other   Advertisement data would be grouped into 100ms * N
> +                       time period. Data in the same group will only be
> +                       reported once, with the RSSI value being averaged out.
> +
> +       Possible errors:        Failed
> +                               Busy
> +                               No Resources
> +                               Invalid Parameters
> +
> +
>  Command Complete Event
>  ======================
>
> --
> 2.29.2.684.gfbc64c5ab5-goog
>

Archie Pusaka Dec. 16, 2020, 3:45 a.m. UTC | #3

Hi Luiz,

On Wed, 16 Dec 2020 at 01:55, Luiz Augusto von Dentz
<[e-mail]> wrote:
>
> Hi Archie,
>
> On Tue, Dec 15, 2020 at 12:33 AM Archie Pusaka <[e-mail]> wrote:
> >
> > From: Archie Pusaka <[e-mail]>
> >
> > This is to leverage the filtering by RSSI feature on those controllers
> > which supports advertisement packet filtering. To avoid changing the
> > existing API and breaking it, a new opcode is required.
> >
> > Reviewed-by: Manish Mandlik <[e-mail]>
> > Reviewed-by: Miao-chen Chou <[e-mail]>
> > Reviewed-by: Yun-Hao Chung <[e-mail]>
> >
> > Signed-off-by: Archie Pusaka <[e-mail]>
> > ---
> >
> >  doc/mgmt-api.txt | 52 ++++++++++++++++++++++++++++++++++++++++++++++++
> >  1 file changed, 52 insertions(+)
> >
> > diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> > index 1aa43d6c3c..d5c7169630 100644
> > --- a/doc/mgmt-api.txt
> > +++ b/doc/mgmt-api.txt
> > @@ -3800,6 +3800,58 @@ Add Extended Advertising Data Command
> >                                 Busy
> >
> >
> > +Add Advertisement Patterns Monitor With RSSI Threshold Command
> > +==============================================================
> > +
> > +       Command Code:           0x0056
> > +       Controller Index:       <controller id>
> > +       Command Parameters:     Pattern_Count (1 Octet)
>
> I'd move the pattern_count after the rssi if the rssi is not per
> pattern, well in case the rssi is per pattern then it should be put
> inside the Pattern directly.
>
It's not per pattern. I uploaded a newer version which flips the
declaration order, please take another look. Thanks!

> > +                               RSSI_Data {
> > +                                       High_Threshold (1 Octet)
> > +                                       High_Threshold_Timer (2 Octets)
> > +                                       Low_Threshold (1 Octet)
> > +                                       Low_Threshold_Timer (2 Octets)
> > +                                       Sampling_Period (1 Octet)
> > +                               }
> > +                               Pattern1 {
> > +                                       AD_Type (1 Octet)
> > +                                       Offset (1 Octet)
> > +                                       Length (1 Octet)
> > +                                       Value (31 Octets)
> > +                               }
> > +                               Pattern2 { }
> > +                               ...
> > +       Return Parameters:      Monitor_Handle (2 Octets)
> > +
> > +       This command is essentially the same as Add Advertisement Patterns
> > +       Monitor Command (0x0052), but with an additional RSSI parameters.
> > +       As such, if the kernel supports advertisement filtering, then the
> > +       advertisement data will be filtered in accordance with the set
> > +       RSSI parameters. Otherwise, it would behave exactly the same as the
> > +       Add Advertisement Patterns Monitor Command.
> > +
> > +       Devices would be considered "in-range" if the RSSI of the received adv
> > +       packets are greater than High_Threshold dBm for High_Threshold_Timer
> > +       seconds. Similarly, devices would be considered lost if no received
> > +       adv have RSSI greater than Low_Threshold dBm for Low_Threshold_Timer
> > +       seconds. Only adv packets of "in-range" device would be propagated.
> > +
> > +       The meaning of Sampling_Period is as follows:
> > +               0x00    All adv packets from "in-range" devices would be
> > +                       propagated.
> > +               0xFF    Only the first adv data of "in-range" devices would be
> > +                       propagated. If the device becomes lost, then the first
> > +                       data when it is found again will also be propagated.
> > +               other   Advertisement data would be grouped into 100ms * N
> > +                       time period. Data in the same group will only be
> > +                       reported once, with the RSSI value being averaged out.
> > +
> > +       Possible errors:        Failed
> > +                               Busy
> > +                               No Resources
> > +                               Invalid Parameters
> > +
> > +
> >  Command Complete Event
> >  ======================
> >
> > --
> > 2.29.2.684.gfbc64c5ab5-goog
> >
>
>
> --
> Luiz Augusto von Dentz

Regards,
Archie

Patch

diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 1aa43d6c3c..d5c7169630 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3800,6 +3800,58 @@  Add Extended Advertising Data Command
 				Busy
 
 
+Add Advertisement Patterns Monitor With RSSI Threshold Command
+==============================================================
+
+	Command Code:		0x0056
+	Controller Index:	<controller id>
+	Command Parameters:	Pattern_Count (1 Octet)
+				RSSI_Data {
+					High_Threshold (1 Octet)
+					High_Threshold_Timer (2 Octets)
+					Low_Threshold (1 Octet)
+					Low_Threshold_Timer (2 Octets)
+					Sampling_Period (1 Octet)
+				}
+				Pattern1 {
+					AD_Type (1 Octet)
+					Offset (1 Octet)
+					Length (1 Octet)
+					Value (31 Octets)
+				}
+				Pattern2 { }
+				...
+	Return Parameters:	Monitor_Handle (2 Octets)
+
+	This command is essentially the same as Add Advertisement Patterns
+	Monitor Command (0x0052), but with an additional RSSI parameters.
+	As such, if the kernel supports advertisement filtering, then the
+	advertisement data will be filtered in accordance with the set
+	RSSI parameters. Otherwise, it would behave exactly the same as the
+	Add Advertisement Patterns Monitor Command.
+
+	Devices would be considered "in-range" if the RSSI of the received adv
+	packets are greater than High_Threshold dBm for High_Threshold_Timer
+	seconds. Similarly, devices would be considered lost if no received
+	adv have RSSI greater than Low_Threshold dBm for Low_Threshold_Timer
+	seconds. Only adv packets of "in-range" device would be propagated.
+
+	The meaning of Sampling_Period is as follows:
+		0x00	All adv packets from "in-range" devices would be
+			propagated.
+		0xFF	Only the first adv data of "in-range" devices would be
+			propagated. If the device becomes lost, then the first
+			data when it is found again will also be propagated.
+		other	Advertisement data would be grouped into 100ms * N
+			time period. Data in the same group will only be
+			reported once, with the RSSI value being averaged out.
+
+	Possible errors:	Failed
+				Busy
+				No Resources
+				Invalid Parameters
+
+
 Command Complete Event
 ======================