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 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 | 148 ++++++++++++++++++++++++++++++++++++++++++++++-
1 file changed, 147 insertions(+), 1 deletion(-)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index b7c4db907..0d6d8b312 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3215,7 +3215,124 @@ Set Experimental Feature Command
Possible errors: Invalid Parameters
Not Powered
- 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:
+
+ 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: 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 +4235,32 @@ 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.
+>>>>>>> c26c91bd3... Describe the new Advertisement Monitor support
--
2.26.2
