* [BlueZ PATCH v6] doc: Describe the new Advertisement Monitor support
@ 2020-05-07 21:54 Miao-chen Chou
2020-05-18 21:17 ` Miao-chen Chou
0 siblings, 1 reply; 2+ messages in thread
From: Miao-chen Chou @ 2020-05-07 21:54 UTC (permalink / raw)
To: Bluetooth Kernel Mailing List
Cc: Luiz Augusto von Dentz, Marcel Holtmann, Alain Michaud,
Michael Sun, Yoni Shavit, 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 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 | 147 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 147 insertions(+)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 39f23c456..3290cc76f 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3138,6 +3138,125 @@ Read Security Information Command
Invalid Index
+Read Advertisement Monitor Features Command
+===========================================
+
+ Command Code: 0x0049
+ 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:
+
+ 1 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: 0x004A
+ 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: 0x004B
+ 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
+ Invalid Index
+
+
Command Complete Event
======================
@@ -4020,3 +4139,31 @@ PHY Configuration Changed Event
one through which the change was triggered.
Refer Get PHY Configuration command for PHYs parameter.
+
+
+Advertisement Monitor Added Event
+=================================
+
+ Event Code: 0x0027
+ 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: 0x0028
+ 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.24.1
^ permalink raw reply related [flat|nested] 2+ messages in thread
* Re: [BlueZ PATCH v6] doc: Describe the new Advertisement Monitor support
2020-05-07 21:54 [BlueZ PATCH v6] doc: Describe the new Advertisement Monitor support Miao-chen Chou
@ 2020-05-18 21:17 ` Miao-chen Chou
0 siblings, 0 replies; 2+ messages in thread
From: Miao-chen Chou @ 2020-05-18 21:17 UTC (permalink / raw)
To: Bluetooth Kernel Mailing List
Cc: Luiz Augusto von Dentz, Marcel Holtmann, Alain Michaud,
Michael Sun, Yoni Shavit
Hi Marcel and Luiz,
Can you help with giving more comments if any?
Thanks,
Miao
On Thu, May 7, 2020 at 2:54 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 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 | 147 +++++++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 147 insertions(+)
>
> diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
> index 39f23c456..3290cc76f 100644
> --- a/doc/mgmt-api.txt
> +++ b/doc/mgmt-api.txt
> @@ -3138,6 +3138,125 @@ Read Security Information Command
> Invalid Index
>
>
> +Read Advertisement Monitor Features Command
> +===========================================
> +
> + Command Code: 0x0049
> + 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:
> +
> + 1 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: 0x004A
> + 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: 0x004B
> + 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
> + Invalid Index
> +
> +
> Command Complete Event
> ======================
>
> @@ -4020,3 +4139,31 @@ PHY Configuration Changed Event
> one through which the change was triggered.
>
> Refer Get PHY Configuration command for PHYs parameter.
> +
> +
> +Advertisement Monitor Added Event
> +=================================
> +
> + Event Code: 0x0027
> + 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: 0x0028
> + 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.24.1
>
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2020-05-18 21:17 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-05-07 21:54 [BlueZ PATCH v6] doc: Describe the new Advertisement Monitor support Miao-chen Chou
2020-05-18 21:17 ` Miao-chen Chou
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.