* [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support
@ 2020-05-19 3:37 Miao-chen Chou
2020-05-27 21:26 ` Miao-chen Chou
2020-06-10 17:56 ` Marcel Holtmann
0 siblings, 2 replies; 3+ messages in thread
From: Miao-chen Chou @ 2020-05-19 3:37 UTC (permalink / raw)
To: Bluetooth Kernel Mailing List
Cc: Michael Sun, Yoni Shavit, Alain Michaud, Luiz Augusto von Dentz,
Marcel Holtmann, Miao-chen Chou
This describes the following commands and event.
- Read Advertisement Monitor Features command
- Add Advertisement Patterns Monitor command
- Remove Advertisement Monitor command
- Advertisement Monitor Added event
- Advertisement Monitor Removed event
Note that the content of a monitor can differ based on its type. For now we
introduce only pattern-based monitor, so you may find that unlike the
command of removing monitor(s), the Add command is tied to a specific type.
---
Changes in v8:
- Fix bit index of advertisement monitor feature and remove a tailing line.
Changes in v7:
- Update command/event opcodes after rebasing.
Changes in v6:
- Refine the description of commands.
- Add Monitor_Handle as the return parameter of Remove Advertisement
Monitor command.
Changes in v5:
- Add more fields in the return value of Read Advertisement Monitor
Features command.
- Refine the description of commands and events.
Changes in v4:
- In Read Advertisement Monitor Features command, rename
Adopted_Features to Enabled_Features.
Changes in v3:
- Remove Advertisement Monitor can perform the removal of one monitor
or all monitors.
- Add Read Advertisement Monitor Features command.
- Add Advertisement Monitor Added event and dvertisement Monitor Removed
event.
Changes in v2:
- Combine commands to remove one monitor and remove all monitors. The
refined command takes multiple handles and an extra field to indicate
whether to remove all monitors.
doc/mgmt-api.txt | 146 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 146 insertions(+)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index b7c4db907..211f085fa 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3218,6 +3218,124 @@ Set Experimental Feature Command
Invalid Index
+Read Advertisement Monitor Features Command
+===========================================
+
+ Command Code: 0x004b
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters: Supported_Features (4 Octets)
+ Enabled_Features (4 Octets)
+ Max_Num_Handles (2 Octets)
+ Max_Num_Patterns (1 Octet)
+ Num_Handles (2 Octets)
+ Handle1 (2 Octets)
+ Handle2 (2 Octets)
+ ...
+
+ This command is used to read the advertisement monitor features
+ supported by the controller and stack. Supported_Features lists all
+ related features supported by the controller while Enabled_Features
+ lists the ones currently used by the kernel.
+
+ Supported_Features and Enabled_Features are bitmasks with currently
+ the following available bits:
+
+ 0 Advertisement content monitoring based on patterns with
+ logic OR.
+
+ Max_Num_Handles indicates the maximum number of supported
+ advertisement monitors. Note that the actual number of supported
+ ones might be less depending on the limitation of the controller.
+
+ Max_Num_Pattern indicates the maximum number of supported patterns
+ in an advertisement patterns monitor. Note that the actual number
+ of supported ones might be less depending on the limitation of the
+ controller.
+
+ Num_Handles indicates the number of added advertisement monitors,
+ and it is followed by a list of handles.
+
+ This command can be used when the controller is not powered.
+
+
+Add Advertisement Patterns Monitor Command
+=========================================
+
+ Command Code: 0x004c
+ Controller Index: <controller id>
+ Command Parameters: Pattern_Count (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 used to add an advertisement monitor whose
+ filtering conditions are patterns. The kernel will trigger scanning
+ if there is at least one monitor added. If the controller supports
+ advertisement filtering, the kernel would offload the content
+ filtering to the controller in order to reduce power consumption;
+ otherwise the kernel ignores the content of the monitor. Note that
+ if the there are more than one patterns, OR logic would applied
+ among patterns during filtering. In other words, any advertisement
+ matching at least one pattern in a given monitor would be
+ considered as a match.
+
+ A pattern contains the following fields.
+ AD_Data_Type Advertising Data Type. The possible values
+ are defined in Core Specification
+ Supplement.
+ Offset The start index where pattern matching
+ shall be performed with in the AD data.
+ Length The length of the pattern value in bytes.
+ Value The value of the pattern in bytes.
+
+ Here is an example of a pattern.
+ {
+ 0x16, // Service Data - 16-bit UUID
+ 0x02, // Skip the UUID part.
+ 0x04,
+ {0x11, 0x22, 0x33, 0x44},
+ }
+
+ This command can be used when the controller is not powered and
+ all settings will be programmed once powered.
+
+ Possible errors: Failed
+ Busy
+ No Resources
+ Invalid Parameters
+
+
+Remove Advertisement Monitor Command
+====================================
+
+ Command Code: 0x004d
+ Controller Index: <controller id>
+ Command Parameters: Monitor_Handle (2 Octets)
+ Return Parameters: Monitor_Handle (2 Octets)
+
+ This command is used to remove advertisement monitor(s). The kernel
+ would remove the monitor(s) with Monitor_Handle and update the LE
+ scanning.
+
+ When the Monitor_Handle is set to zero, then all previously added
+ handles will be removed.
+
+ Removing a monitor while it is being added will be ignored.
+
+ This command can be used when the controller is not powered and
+ all settings will be programmed once powered.
+
+ Possible errors: Failed
+ Busy
+
+
Command Complete Event
======================
@@ -4118,3 +4236,31 @@ Experimental Feature Changed Event
one through which the change was triggered.
Refer to Set Experimental Feature command for the Flags parameter.
+
+
+Advertisement Monitor Added Event
+=================================
+
+ Event Code: 0x0028
+ Controller Index: <controller id>
+ Event Parameters: Monitor_Handle (2 Octets)
+
+ This event indicates that an advertisement monitor has been added
+ using the Add Advertisement Monitor command.
+
+ The event will only be sent to management sockets other than the
+ one through which the command was sent.
+
+
+Advertisement Monitor Removed Event
+===================================
+
+ Event Code: 0x0029
+ Controller Index: <controller id>
+ Event Parameters: Monitor_Handle (2 Octets)
+
+ This event indicates that an advertisement monitor has been removed
+ using the Remove Advertisement Monitor command.
+
+ The event will only be sent to management sockets other than the
+ one through which the command was sent.
--
2.26.2
^ permalink raw reply related [flat|nested] 3+ messages in thread* Re: [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support
2020-05-19 3:37 [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support Miao-chen Chou
@ 2020-05-27 21:26 ` Miao-chen Chou
2020-06-10 17:56 ` Marcel Holtmann
1 sibling, 0 replies; 3+ messages in thread
From: Miao-chen Chou @ 2020-05-27 21:26 UTC (permalink / raw)
To: Bluetooth Kernel Mailing List
Cc: Michael Sun, Yoni Shavit, Alain Michaud, Luiz Augusto von Dentz,
Marcel Holtmann
Hi Maintainers,
Any further comments are appreciated. Looking forward to hearing from you.
Regards,
Miao
On Mon, May 18, 2020 at 8:37 PM Miao-chen Chou <mcchou@chromium.org> wrote:
>
> This describes the following commands and event.
> - Read Advertisement Monitor Features command
> - Add Advertisement Patterns Monitor command
> - Remove Advertisement Monitor command
> - Advertisement Monitor Added event
> - Advertisement Monitor Removed event
> Note that the content of a monitor can differ based on its type. For now we
> introduce only pattern-based monitor, so you may find that unlike the
> command of removing monitor(s), the Add command is tied to a specific type.
> ---
>
> Changes in v8:
> - Fix bit index of advertisement monitor feature and remove a tailing line.
>
> Changes in v7:
> - Update command/event opcodes after rebasing.
>
> Changes in v6:
> - Refine the description of commands.
> - Add Monitor_Handle as the return parameter of Remove Advertisement
> Monitor command.
>
> Changes in v5:
> - Add more fields in the return value of Read Advertisement Monitor
> Features command.
> - Refine the description of commands and events.
>
> Changes in v4:
> - In Read Advertisement Monitor Features command, rename
> Adopted_Features to Enabled_Features.
>
> Changes in v3:
> - Remove Advertisement Monitor can perform the removal of one monitor
> or all monitors.
> - Add Read Advertisement Monitor Features command.
> - Add Advertisement Monitor Added event and dvertisement Monitor Removed
> event.
>
> Changes in v2:
> - Combine commands to remove one monitor and remove all monitors. The
> refined command takes multiple handles and an extra field to indicate
> whether to remove all monitors.
>
> doc/mgmt-api.txt | 146 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 146 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index b7c4db907..211f085fa 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -3218,6 +3218,124 @@ Set Experimental Feature Command
> Invalid Index
>
>
> +Read Advertisement Monitor Features Command
> +===========================================
> +
> + Command Code: 0x004b
> + Controller Index: <controller id>
> + Command Parameters:
> + Return Parameters: Supported_Features (4 Octets)
> + Enabled_Features (4 Octets)
> + Max_Num_Handles (2 Octets)
> + Max_Num_Patterns (1 Octet)
> + Num_Handles (2 Octets)
> + Handle1 (2 Octets)
> + Handle2 (2 Octets)
> + ...
> +
> + This command is used to read the advertisement monitor features
> + supported by the controller and stack. Supported_Features lists all
> + related features supported by the controller while Enabled_Features
> + lists the ones currently used by the kernel.
> +
> + Supported_Features and Enabled_Features are bitmasks with currently
> + the following available bits:
> +
> + 0 Advertisement content monitoring based on patterns with
> + logic OR.
> +
> + Max_Num_Handles indicates the maximum number of supported
> + advertisement monitors. Note that the actual number of supported
> + ones might be less depending on the limitation of the controller.
> +
> + Max_Num_Pattern indicates the maximum number of supported patterns
> + in an advertisement patterns monitor. Note that the actual number
> + of supported ones might be less depending on the limitation of the
> + controller.
> +
> + Num_Handles indicates the number of added advertisement monitors,
> + and it is followed by a list of handles.
> +
> + This command can be used when the controller is not powered.
> +
> +
> +Add Advertisement Patterns Monitor Command
> +=========================================
> +
> + Command Code: 0x004c
> + Controller Index: <controller id>
> + Command Parameters: Pattern_Count (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 used to add an advertisement monitor whose
> + filtering conditions are patterns. The kernel will trigger scanning
> + if there is at least one monitor added. If the controller supports
> + advertisement filtering, the kernel would offload the content
> + filtering to the controller in order to reduce power consumption;
> + otherwise the kernel ignores the content of the monitor. Note that
> + if the there are more than one patterns, OR logic would applied
> + among patterns during filtering. In other words, any advertisement
> + matching at least one pattern in a given monitor would be
> + considered as a match.
> +
> + A pattern contains the following fields.
> + AD_Data_Type Advertising Data Type. The possible values
> + are defined in Core Specification
> + Supplement.
> + Offset The start index where pattern matching
> + shall be performed with in the AD data.
> + Length The length of the pattern value in bytes.
> + Value The value of the pattern in bytes.
> +
> + Here is an example of a pattern.
> + {
> + 0x16, // Service Data - 16-bit UUID
> + 0x02, // Skip the UUID part.
> + 0x04,
> + {0x11, 0x22, 0x33, 0x44},
> + }
> +
> + This command can be used when the controller is not powered and
> + all settings will be programmed once powered.
> +
> + Possible errors: Failed
> + Busy
> + No Resources
> + Invalid Parameters
> +
> +
> +Remove Advertisement Monitor Command
> +====================================
> +
> + Command Code: 0x004d
> + Controller Index: <controller id>
> + Command Parameters: Monitor_Handle (2 Octets)
> + Return Parameters: Monitor_Handle (2 Octets)
> +
> + This command is used to remove advertisement monitor(s). The kernel
> + would remove the monitor(s) with Monitor_Handle and update the LE
> + scanning.
> +
> + When the Monitor_Handle is set to zero, then all previously added
> + handles will be removed.
> +
> + Removing a monitor while it is being added will be ignored.
> +
> + This command can be used when the controller is not powered and
> + all settings will be programmed once powered.
> +
> + Possible errors: Failed
> + Busy
> +
> +
> Command Complete Event
> ======================
>
> @@ -4118,3 +4236,31 @@ Experimental Feature Changed Event
> one through which the change was triggered.
>
> Refer to Set Experimental Feature command for the Flags parameter.
> +
> +
> +Advertisement Monitor Added Event
> +=================================
> +
> + Event Code: 0x0028
> + Controller Index: <controller id>
> + Event Parameters: Monitor_Handle (2 Octets)
> +
> + This event indicates that an advertisement monitor has been added
> + using the Add Advertisement Monitor command.
> +
> + The event will only be sent to management sockets other than the
> + one through which the command was sent.
> +
> +
> +Advertisement Monitor Removed Event
> +===================================
> +
> + Event Code: 0x0029
> + Controller Index: <controller id>
> + Event Parameters: Monitor_Handle (2 Octets)
> +
> + This event indicates that an advertisement monitor has been removed
> + using the Remove Advertisement Monitor command.
> +
> + The event will only be sent to management sockets other than the
> + one through which the command was sent.
> --
> 2.26.2
>
^ permalink raw reply [flat|nested] 3+ messages in thread* Re: [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support
2020-05-19 3:37 [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support Miao-chen Chou
2020-05-27 21:26 ` Miao-chen Chou
@ 2020-06-10 17:56 ` Marcel Holtmann
1 sibling, 0 replies; 3+ messages in thread
From: Marcel Holtmann @ 2020-06-10 17:56 UTC (permalink / raw)
To: Miao-chen Chou
Cc: Bluetooth Kernel Mailing List, Michael Sun, Yoni Shavit,
Alain Michaud, Luiz Augusto von Dentz
Hi Miao-chen,
> This describes the following commands and event.
> - Read Advertisement Monitor Features command
> - Add Advertisement Patterns Monitor command
> - Remove Advertisement Monitor command
> - Advertisement Monitor Added event
> - Advertisement Monitor Removed event
> Note that the content of a monitor can differ based on its type. For now we
> introduce only pattern-based monitor, so you may find that unlike the
> command of removing monitor(s), the Add command is tied to a specific type.
> ---
>
> Changes in v8:
> - Fix bit index of advertisement monitor feature and remove a tailing line.
>
> Changes in v7:
> - Update command/event opcodes after rebasing.
>
> Changes in v6:
> - Refine the description of commands.
> - Add Monitor_Handle as the return parameter of Remove Advertisement
> Monitor command.
>
> Changes in v5:
> - Add more fields in the return value of Read Advertisement Monitor
> Features command.
> - Refine the description of commands and events.
>
> Changes in v4:
> - In Read Advertisement Monitor Features command, rename
> Adopted_Features to Enabled_Features.
>
> Changes in v3:
> - Remove Advertisement Monitor can perform the removal of one monitor
> or all monitors.
> - Add Read Advertisement Monitor Features command.
> - Add Advertisement Monitor Added event and dvertisement Monitor Removed
> event.
>
> Changes in v2:
> - Combine commands to remove one monitor and remove all monitors. The
> refined command takes multiple handles and an extra field to indicate
> whether to remove all monitors.
>
> doc/mgmt-api.txt | 146 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 146 insertions(+)
I adjusted the command and event codes and then applied your patch.
Regards
Marcel
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-06-10 17:56 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-19 3:37 [BlueZ PATCH v8] doc: Describe the new Advertisement Monitor support Miao-chen Chou
2020-05-27 21:26 ` Miao-chen Chou
2020-06-10 17:56 ` Marcel Holtmann
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).