summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorMiao-chen Chou <mcchou@chromium.org>2020-06-10 19:54:54 +0200
committerMarcel Holtmann <marcel@holtmann.org>2020-06-10 20:01:15 +0200
commit79bd5951a8a2f2690e632d894a51d6c528fc31e9 (patch)
treea630bf81dd9b4c15f35cdb623db750e839e0ae1c /doc
parent7bcb1086ab310f414a9bfe78b17f5a4429d1375c (diff)
downloadbluez-79bd5951a8a2f2690e632d894a51d6c528fc31e9.tar.gz
doc: Describe the new Advertisement Monitor support
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.
Diffstat (limited to 'doc')
-rw-r--r--doc/mgmt-api.txt152
1 files changed, 150 insertions, 2 deletions
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index 23cc1e2dc..21a08ad9e 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -104,8 +104,10 @@ Version 1.18 introduces Read Default System Configuration command, Set
Default System Configuration command, Default System Configuration Changed
event, Read Default Runtime Configuration command, Set Default Runtime
Configuration command, Default Runtime Configuration Changed event, Get
-Device Flags command, Set Device Flags command and Device Flags Changed
-event.
+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.
Example
@@ -3453,6 +3455,124 @@ Set Device Flags Command
Invalid Index
+Read Advertisement Monitor Features Command
+===========================================
+
+ Command Code: 0x0051
+ 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: 0x0052
+ 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: 0x0053
+ 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
======================
@@ -4428,3 +4548,31 @@ Device Flags Changed Event
In case this event is triggered by Add Device then it is sent to
all management sockets.
+
+
+Advertisement Monitor Added Event
+=================================
+
+ Event Code: 0x002b
+ Controller Index: <controller id>
+ Event Parameters: Monitor_Handle (2 Octets)
+
+ This event indicates that an advertisement monitor has been added
+ using the Add Advertisement Patterns 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: 0x002c
+ 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.