docs: Bluetooth: HCI_VS: Updated docs on VS HCI commands
This commit complements documentation of Zephyr HCI VS commands. In particular, it documents the newly introduced commands - BT_HCI_OP_VS_WRITE_TX_POWER_LEVEL - BT_HCI_OP_VS_READ_TX_POWER_LEVEL These provide HCI-level control over the Tx power of the BLE radio on a per role/connection basis. The functionality is enabled upon the Kconfig advanced configuration triggered by - BT_CTLR_TX_PWR_DYNAMIC_CONTROL depending on the enablement of Zephyr HCI vendor-specific command extensions. Signed-off-by: Andrei Stoica <stoica.razvan.andrei@gmail.com>
This commit is contained in:
Andrei Stoica
Carles Cufí
parent
930d178c69
commit
cc19e72497
1 changed files with 217 additions and 2 deletions
|
|
@ -40,8 +40,8 @@ command is supported.
|
||||||
| | 2 | Read Chip Temperature |
|
| | 2 | Read Chip Temperature |
|
||||||
| | 3 | Read Host Stack Commands |
|
| | 3 | Read Host Stack Commands |
|
||||||
| | 4 | Set Scan Request Reports |
|
| | 4 | Set Scan Request Reports |
|
||||||
| | 5 | Reserved |
|
| | 5 | Write Tx Power Level (per Role/Connection) |
|
||||||
| | 6 | Reserved |
|
| | 6 | Read Tx Power Level (per Role/Connection) |
|
||||||
| | 7 | Reserved |
|
| | 7 | Reserved |
|
||||||
+-------+------+--------------------------------------------+
|
+-------+------+--------------------------------------------+
|
||||||
|
|
||||||
|
|
@ -800,6 +800,221 @@ When the Set_Scan_Request_Reports command has completed, a Command Complete
|
||||||
event shall be generated.
|
event shall be generated.
|
||||||
|
|
||||||
|
|
||||||
|
Zephyr Write Tx Power Level (per Role/Connection) Command
|
||||||
|
=========================================================
|
||||||
|
|
||||||
|
This command dynamically modifies BLE Tx power level given a handle and a
|
||||||
|
handle type (advertiser, scanner, connection).
|
||||||
|
|
||||||
|
+--------------------------+-------+--------------------+--------------------+
|
||||||
|
| Command | OCF | Command | Return |
|
||||||
|
| | | Parameters | Parameters |
|
||||||
|
+--------------------------+-------+--------------------+--------------------+
|
||||||
|
| Write_Tx_Power_Level | 0x00E | Handle_Type, | Status, |
|
||||||
|
| | | Handle, | Handle_Type, |
|
||||||
|
| | | Tx_Power_Level | Handle, |
|
||||||
|
| | | | Selected_Tx_Power |
|
||||||
|
+--------------------------+-------+--------------------+--------------------+
|
||||||
|
|
||||||
|
The Tx power of the BLE radio interface is modified for any low-level link by
|
||||||
|
the controller with a high degree of flexibility. The BLE link whose power is
|
||||||
|
set is identified based on a handle type (advertiser, scanner, connection) and
|
||||||
|
handle pair.
|
||||||
|
|
||||||
|
The role/state defining input parameter is the Handle_Type, whereas its
|
||||||
|
corresponding handle is provided by the Handle input parameter. Note that
|
||||||
|
for Advertisements, the Handle input parameter is ignored in the case that
|
||||||
|
Advertising Extensions are not configured, whereas Advertising Sets are to be
|
||||||
|
identified by their corresponding Handle in case Advertising Extensions are
|
||||||
|
enabled.
|
||||||
|
|
||||||
|
The desired transmitter power level for the selected link instance is inputted
|
||||||
|
as Tx_Power_Level. The power setup and control can be performed dynamically
|
||||||
|
without the need of restarting the advertiser and scanner role/states. In case
|
||||||
|
of connections, the Tx power changes take effect only if the connections are
|
||||||
|
in a connected state.
|
||||||
|
|
||||||
|
The inputs Handle_Type and Handle are passed through as outputs to aid the
|
||||||
|
asynchronous service of the command as well. In addition, the command returns
|
||||||
|
also with the Selected_Tx_Power by the controller which addresses and corrects
|
||||||
|
the possible mismatches between the desired Tx_Power_Level and the achievable
|
||||||
|
Tx powers given each individual controller capabilities.
|
||||||
|
|
||||||
|
Handle_Type: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| 0x00 | Handle of type Advertiser (Adv) |
|
||||||
|
| 0x01 | Handle of type Scanner (Scan) |
|
||||||
|
| 0x02 | Handle of type Connection (Conn) |
|
||||||
|
| 0x03-0xFF | Reserved (HCI command error) |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Handle: Size: 2 Octets
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| | Handle of the selected Handle_Type |
|
||||||
|
| | that identifies the instance to set |
|
||||||
|
| | the power of. See below for a |
|
||||||
|
| | description corresponding to each |
|
||||||
|
| | Handle_Type |
|
||||||
|
| | |
|
||||||
|
| | Handle_Type_Adv: |
|
||||||
|
| 0x0000 - 0xFFFF | Legacy Advertisement Handle |
|
||||||
|
| | (Handle value is ignored) |
|
||||||
|
| 0x0000 - 0x00EF | Advertisement Extensions (AE) |
|
||||||
|
| | enabled Advertisement set |
|
||||||
|
| | Handle |
|
||||||
|
| | |
|
||||||
|
| | Handle_Type_Scan: |
|
||||||
|
| 0x0000 - 0xFFFF | Scanner Handle (Handle value is |
|
||||||
|
| | ignored) |
|
||||||
|
| | |
|
||||||
|
| | Handle_Type_Conn: |
|
||||||
|
| 0x0000 - 0x0EFF | Connection Handle |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Tx_Power_Level: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| -127 <= N <= 126 | The desired Tx_Power_Level in signed |
|
||||||
|
| | 1 octet integer format to be set to |
|
||||||
|
| | the Handle_Type and Handle pair. The |
|
||||||
|
| | controller shall choose a power |
|
||||||
|
| | level lower than or equal to the one |
|
||||||
|
| | specified by the host unless the host|
|
||||||
|
| | desired power is lower than the |
|
||||||
|
| | minimum supported Tx power of the |
|
||||||
|
| | controller, in which case the |
|
||||||
|
| | controller shall use its minimum Tx |
|
||||||
|
| | power. |
|
||||||
|
| | Units: dBm |
|
||||||
|
| | |
|
||||||
|
| 127 | No preference for the Tx_Power_Level,|
|
||||||
|
| | the controller shall revert to using |
|
||||||
|
| | its default setting for Tx power. |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Status: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| 0x00 | Command succeeded |
|
||||||
|
| 0x01-0xFF | Command failed |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Selected_Tx_Power: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| -127 <= N <= 126 | The controller selected Tx power to |
|
||||||
|
| | set for the given Handle_Type and |
|
||||||
|
| | and pair formatted as a 1 octet |
|
||||||
|
| | signed integer. The controller shall |
|
||||||
|
| | not modify this transmit power unless|
|
||||||
|
| | it is directed to do so by the Host. |
|
||||||
|
| | Units: dBm |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
When the Write_Tx_Power_Level command has completed, a Command Complete
|
||||||
|
event shall be generated.
|
||||||
|
|
||||||
|
|
||||||
|
Zephyr Read Tx Power Level (per Role/Connection) Command
|
||||||
|
========================================================
|
||||||
|
|
||||||
|
This command reads the BLE Tx power level. In contrast to the standardized HCI
|
||||||
|
command, i.e. Read_Transmit_Power_Level, which returns the transmitted power
|
||||||
|
level only for a specified connection handle, this command operates for both
|
||||||
|
connected and unconnected states. It gets the BLE Tx power level for any given
|
||||||
|
handle type (advertiser, scanner, connection) and handle.
|
||||||
|
|
||||||
|
+--------------------------+-------+--------------------+--------------------+
|
||||||
|
| Command | OCF | Command | Return |
|
||||||
|
| | | Parameters | Parameters |
|
||||||
|
+--------------------------+-------+--------------------+--------------------+
|
||||||
|
| Read_Tx_Power_Level | 0x00F | Handle_Type, | Status, |
|
||||||
|
| | | Handle | Handle_Type, |
|
||||||
|
| | | | Handle, |
|
||||||
|
| | | | Tx_Power_Level |
|
||||||
|
+--------------------------+-------+--------------------+--------------------+
|
||||||
|
|
||||||
|
The Tx power of the BLE radio interface used for a low-level link identified
|
||||||
|
by a pair of Handle_Type and Handle is retrieved from the controller.
|
||||||
|
|
||||||
|
The role/state defining input parameter is the Handle_Type, whereas its
|
||||||
|
corresponding handle is provided by the Handle input parameter. Note that
|
||||||
|
for Advertisements, the Handle input parameter is ignored in the case that
|
||||||
|
Advertising Extensions are not configured, whereas Advertising Sets are to be
|
||||||
|
identified by their corresponding Handle in case Advertising Extensions are
|
||||||
|
enabled.
|
||||||
|
|
||||||
|
The command returns with an operational Status, and the replicated Handle_Type
|
||||||
|
and Handle input parameters supplemented by the current Tx_Power_Level in use
|
||||||
|
by the controller for the requested Handle_Type and Handle.
|
||||||
|
|
||||||
|
Handle_Type: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| 0x00 | Handle of type Advertiser (Adv) |
|
||||||
|
| 0x01 | Handle of type Scanner (Scan) |
|
||||||
|
| 0x02 | Handle of type Connection (Conn) |
|
||||||
|
| 0x03-0xFF | Reserved (HCI command error) |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Handle: Size: 2 Octets
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| | Handle of the selected Handle_Type |
|
||||||
|
| | that identifies the instance to read |
|
||||||
|
| | the power of. See below for a |
|
||||||
|
| | description corresponding to each |
|
||||||
|
| | Handle_Type |
|
||||||
|
| | |
|
||||||
|
| | Handle_Type_Adv: |
|
||||||
|
| 0x0000 - 0xFFFF | Legacy Advertisement Handle |
|
||||||
|
| | (Handle value is ignored) |
|
||||||
|
| 0x0000 - 0x00EF | Advertisement Extensions (AE) |
|
||||||
|
| | enabled Advertisement set |
|
||||||
|
| | Handle |
|
||||||
|
| | |
|
||||||
|
| | Handle_Type_Scan: |
|
||||||
|
| 0x0000 - 0xFFFF | Scanner Handle (Handle value is |
|
||||||
|
| | ignored) |
|
||||||
|
| | |
|
||||||
|
| | |
|
||||||
|
| | Handle_Type_Conn: |
|
||||||
|
| 0x0000 - 0x0EFF | Connection Handle |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Status: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| 0x00 | Command succeeded |
|
||||||
|
| 0x01-0xFF | Command failed |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
Tx_Power_Level: Size: 1 Octet
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| Value | Parameter Description |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
| -127 <= N <= 126 | The current Tx_Power_Level formatted |
|
||||||
|
| | as a 1 octet signed integer at which |
|
||||||
|
| | the controller is operating the |
|
||||||
|
| | low-level link identified by the |
|
||||||
|
| | Handle_Type and Handle pair. |
|
||||||
|
| | Units: dBm |
|
||||||
|
+--------------------+--------------------------------------+
|
||||||
|
|
||||||
|
When the Read_Tx_Power_Level command has completed, a Command Complete
|
||||||
|
event shall be generated.
|
||||||
|
|
||||||
|
|
||||||
Zephyr Vendor Events
|
Zephyr Vendor Events
|
||||||
====================
|
====================
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue