This patch adds the following to mgmt-api:
- Add Extended Advertising Parameters Command
- Add Extended Advertising Data Command
- Read Controller Capabilities Command
- Advertisement Tx Power Selected Event
Reviewed-by: Sonny Sasaka <sonnysasaka@xxxxxxxxxxxx>
Reviewed-by: Alain Michaud <alainm@xxxxxxxxxxxx>
---
Changes in v2:
- Removed extra space in Add Extended Advertising Parameters API
doc/mgmt-api.txt | 242 +++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 242 insertions(+)
diff --git a/doc/mgmt-api.txt b/doc/mgmt-api.txt
index ca0d38469..62f976a11 100644
--- a/doc/mgmt-api.txt
+++ b/doc/mgmt-api.txt
@@ -3574,6 +3574,234 @@ Remove Advertisement Monitor Command
Busy
+Add Extended Advertising Parameters Command
+===========================================
+
+ Command Code: 0x0054
+ Controller Index: <controller id>
+ Command Parameters: Instance (1 Octet)
+ Flags (4 Octets)
+ Params (2 Octets)
+ Duration (2 Octets)
+ Timeout (2 Octets)
+ MinInterval (4 Octets)
+ MaxInterval (4 Octets)
+ TxPower (1 Octet)
+ Return Parameters: Instance (1 Octet)
+
+ This command is used to configure the parameters for Bluetooth Low
+ Energy advertising instance. This command is expected to be followed
+ by an Add Extended Advertising Data command to complete and enable
+ the advertising instance.
+
+ Added advertising information with this command will not be visible
+ immediately if advertising is enabled via the Set Advertising
+ command. The usage of the Set Advertising command takes precedence
+ over this command. Instance information is stored and will be
+ advertised once advertising via Set Advertising has been disabled.
+
+ The Instance identifier is a value between 1 and the number of
+ supported instances. The value 0 is reserved.
+
+ With the Flags value the type of advertising is controlled and
+ the following flags are defined:
+
+ 0 Switch into Connectable mode
+ 1 Advertise as Discoverable
+ 2 Advertise as Limited Discoverable
+ 3 Add Flags field to Adv_Data
+ 4 Add TX Power field to Adv_Data
+ 5 Add Appearance field to Scan_Rsp
+ 6 Add Local Name in Scan_Rsp
+ 7 Secondary Channel with LE 1M
+ 8 Secondary Channel with LE 2M
+ 9 Secondary Channel with LE Coded
+
+ When the connectable flag is set, then the controller will use
+ undirected connectable advertising. The value of the connectable
+ setting can be overwritten this way. This is useful to switch a
+ controller into connectable mode only for LE operation. This is
+ similar to the mode 0x02 from the Set Advertising command.
+
+ When the connectable flag is not set, then the controller will
+ use advertising based on the connectable setting. When using
+ non-connectable or scannable advertising, the controller will
+ be programmed with a non-resolvable random address. When the
+ system is connectable, then the identity address or resolvable
+ private address will be used.
+
+ Using the connectable flag is useful for peripheral mode support
+ where BR/EDR (and/or LE) is controlled by Add Device. This allows
+ making the peripheral connectable without having to interfere
+ with the global connectable setting.
+
+ Secondary channel flags can be used to advertise in secondary
+ channel with the corresponding PHYs. These flag bits are mutually
+ exclusive and setting multiple will result in Invalid Parameter
+ error. Choosing either LE 1M or LE 2M will result in using
+ extended advertising on the primary channel with LE 1M and the
+ respectively LE 1M or LE 2M on the secondary channel. Choosing
+ LE Coded will result in using extended advertising on the primary
+ and secondary channels with LE Coded. Choosing none of these flags
+ will result in legacy advertising.
+
+ To allow future parameters to be optionally extended in this structure,
+ the Params member is used to specify which of the structure fields were
+ purposefully set by the caller. Unspecified parameters will be given
+ sensible defaults by the kernel before the advertisement is registered.
+ The Params bit field uses the following bit to parameter relationship:
+
+ 0 The Duration parameter should be used
+ 1 The Timeout parameter should be used
+ 2 The Interval parameters should be used
+ 3 The Tx Power parameter should be used
+
+ The Duration parameter configures the length of an Instance. The
+ value is in seconds. The default is 2 seconds.
+
+ If only one advertising Instance has been added, then the Duration
+ value will be ignored. It only applies for the case where multiple
+ Instances are configured. In that case every Instance will be
+ available for the Duration time and after that it switches to
+ the next one. This is a simple round-robin based approach.
+
+ The Timeout parameter configures the life-time of an Instance. In
+ case the value 0 is used it indicates no expiration time. If a
+ timeout value is provided, then the advertising Instance will be
+ automatically removed when the timeout passes. The value for the
+ timeout is in seconds. Powering down a controller will invalidate
+ all advertising Instances and it is not possible to add a new
+ Instance with a timeout when the controller is powered down.
+
+ When a Timeout is provided, then the Duration subtracts from
+ the actual Timeout value of that Instance. For example an Instance
+ with Timeout of 5 and Duration of 2 will be scheduled exactly 3
+ times, twice with 2 seconds and once with one second. Other
+ Instances have no influence on the Timeout.
+
+ MinInterval and MaxInterval define the minimum and maximum advertising
+ intervals, with units as number of .625ms advertising slots. The Max
+ interval is expected to be greater than or equal to the Min interval,
+ and both must have values in the range [0x000020, 0xFFFFFF]. If either
+ condition is not met, the registration will fail.
+
+ The provided Tx Power parameter will only be used if the controller
+ supports it, which can be determined by the presence of the
+ CanSetTxPower member of the Read Advertising Features command.
+
+ The acceptable range for requested Tx Power is defined in the spec
+ (Version 5.2 | Vol 4, Part E, page 2585) to be [-127, +20] dBm, and the
+ controller will select a power value up to the requested one. The
+ transmission power selected by the controller is not guaranteed
+ to match the requested one, but the caller can determine the power
+ chosen by the controller by listening for the Tx Power Selected MGMT
+ event that follows this command. If the requested Tx Power is outside
+ the valid range, the registration will fail.
+
+ Re-adding an already existing instance (i.e. issuing the Add Extended
+ Advertising Parameters command with an Instance identifier of an
+ existing instance) will update that instance's configuration.
+
+ An instance being added or changed while another instance is
+ being advertised will not be visible immediately but only when
+ the new/changed instance is being scheduled by the round robin
+ advertising algorithm.
+
+ Changes to an instance that is currently being advertised will
+ cancel that instance and switch to the next instance. The changes
+ will be visible the next time the instance is scheduled for
+ advertising. In case a single instance is active, this means
+ that changes will be visible right away.
+
+ LE must already be enabled, and the controller must be powered,
+ otherwise a "rejected" status will be returned.
+
+ This command generates a Command Complete event on success or a
+ Command Status event on failure.
+
+ Possible errors: Failed
+ Rejected
+ Not Supported
+ Invalid Parameters
+ Busy
+
+
+Add Extended Advertising Data Command
+=====================================
+
+ Command Code: 0x0055
+ Controller Index: <controller id>
+ Command Parameters: Instance (1 Octet)
+ Advertising Data Length (1 Octet)
+ Scan Response Length (1 Octet)
+ Advertising Data (0-255 Octets)
+ Scan Response (0-255 Octets)
+ Return Parameters: Instance (1 Octet)
+
+ The Add Extended Advertising Data command is used to update the
+ advertising data of an existing advertising instance known to the
+ kernel. It is expected to be called after an Add Extended Advertising
+ Parameters command, as part of the advertisement registration
+ process.
+
+ If extended advertising is available, this call will initiate HCI
+ commands to set the instance's advertising data, set scan response
+ data, and then enable the instance. If extended advertising is
+ unavailable, the advertising instance structure maintained in kernel
+ will have its advertising data and scan response updated, and the
+ instance will either be scheduled immediately or left in the queue
+ for later advertisement as part of round-robin advertisement rotation
+ in software.
+
+ If Scan_Rsp_Len is zero and the flags defined in Add Extended
+ Advertising Parameters command do not have connectable flag set and
+ the global connectable setting is off, then non-connectable
+ advertising is used. If Scan_Rsp_Len is larger than zero and
+ connectable flag is not set and the global advertising is off,
+ then scannable advertising is used. This small difference is
+ supported to provide less air traffic for devices implementing
+ broadcaster role.
+
+ If the Instance provided does not match a known instance, or if the
+ provided advertising data or scan response are in an unrecognized
+ format, an "Invalid Parameters" status will be returned.
+
+ If a "Set LE" or Advertising command is still in progress, a "Busy"
+ status will be returned.
+
+ If the controller is not powered, a "rejected" status will be returned.
+
+ This command generates a Command Complete event on success or a
+ Command Status event on failure.
+
+ Possible errors: Failed
+ Rejected
+ Invalid Parameters
+ Busy
+
+
+Read Controller Capabilities Command
+====================================
+
+ Command Code: 0x0056
+ Controller Index: <controller id>
+ Command Parameters:
+ Return Parameters: Parameter1 {
+ Capability_Tag (2 Octet)
+ Value_Length (1 Octet)
+ Value (0-255 Octets)
+ }
+ Parameter2 { }
+ ...
+
+ This command is used to read a list of controller capabilities.
+
+ Currently defined Capability_Tag values are:
+
+ 0x0000 Minimum Supported LE Tx Power (dBm)
+ 0x0001 Maximum Supported LE Tx Power (dBm)
+
+
Command Complete Event
======================
@@ -4577,3 +4805,17 @@ Advertisement Monitor Removed Event
The event will only be sent to management sockets other than the
one through which the command was sent.
+
+
+Advertisement Tx Power Selected Event
+===================================
+
+ Event Code: 0x002d
+ Controller Index: <controller id>
+ Event Parameters: Instance (1 Octet)
+ TxPower (1 Octet)
+
+ This event indicates that the controller selected a transmission
+ power for an advertising instance. The event is emitted on platforms
+ that support extended advertising after an Add Extended Advertising
+ Parameters command is submitted.
\ No newline at end of file
--
2.28.0.681.g6f77f65b4e-goog
