michaelh/zephyr
1
0
Fork 0
Code Releases Activity

docs: Bluetooth: HCI_VS: Updated docs on VS HCI commands

Browse source 
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 2019-10-22 13:44:27 +02:00 • committed by Carles Cufí
commit cc19e72497
1 changed files with 217 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

219
doc/reference/bluetooth/hci.txt
View file

@ -40,8 +40,8 @@ command is supported.
| | 2 | Read Chip Temperature |
| | 3 | Read Host Stack Commands |
| | 4 | Set Scan Request Reports |
| | 5 | Reserved |
| | 6 | Reserved |
| | 5 | Write Tx Power Level (per Role/Connection) |
| | 6 | Read Tx Power Level (per Role/Connection) |
| | 7 | Reserved |
+-------+------+--------------------------------------------+
@ -800,6 +800,221 @@ When the Set_Scan_Request_Reports command has completed, a Command Complete
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
====================