Adjusting |DEVICE| txPower
***************************

To optimize application power budget or performance, it is important to change the txPower
to achieve the following scenario.

* When peer devices are in close range, reduce the TX power can save the power budget.
* When you want your device to increase range by increasing the TX power.
* Increase the visibility of your application in a crowded environnement 

.. note::
   Note that for |DEVICE| the TX power range goes from -20dBm to 8dBm.

Changing txPower for an advertising set
=======================================

SysConfig can be used to modify the TxPower used for each advertising set.

* Open the sysconfig file of your example
* Go to **RF Stacks** > **BLE** > **Advertisement Set** > **Advertisement Parameters**
* Change the **TX Power** field from ``The Controller will choose the Tx power`` to ``TX Power Value``
* A new field appears below called **TX Power Value**, enter the value in dBm. 

.. _fig-SysConfig_Txpower_cc23xx:
.. figure:: resources/SysConfig_Txpower_cc23xx.png
   :align: center

   txPower configuration

Changing txPower at run time
============================

To modify the txPower at running time, use the HCI command: ``HCI_EXT_SetTxPowerDbmCmd(int8 txPower, uint8 fraction)``
The **txPowerDbm** parameter corresponds to the power in dBm value, the **fraction** is currently not used.
Find more details concerning the HCI function in the
`API references section of the user's guide <../ble-stack-5.x-guide/api-reference-cc23xx.html>`_.

.. note::
   To check whether the txPower value has been updated you can either:

   * Check the current consumption: the higher the current consumption indicates higher the txPower.
   * Check the RSSI value: smaller RSSI indicates lower txPower.

   RSSI will also vary by environment and that assuming all variables are equal and the devices are in the same location.

   Lowering the txPower will lead to a smaller (more negative) RSSI. 

    ``HCI_EXT_SetTxPowerDbmCmd(int8 txPower, uint8 fraction)`` will have no impact on DTM test functions.

Changing txPower for DTM
========================

To modify the txPower in DTM for the purpose of running DTM tests, use the HCI command: ``HCIExt_SetMaxDtmTxPowerDbmCmd(int8 txPower, uint8 fraction)``
The **txPowerDbm** parameter corresponds to the power in dBm value, the **fraction** is currently not used (i.e. should be set to ``0``).
Find more details concerning the HCI function in the
`API references section of the user's guide <../ble-stack-5.x-guide/api-reference-cc23xx.html>`_.

.. note::
   When changing txPower using this method, only the DTM test functions such as ``EnhancedModemTestTxCmd`` and
   ``HCIExt_ModemTestTxCmd`` will have the new txPower.

   ``HCIExt_SetMaxDtmTxPowerDbmCmd(int8 txPower, uint8 fraction)`` will have no impact on the txPower used for
   non-DTM functionality such as advertising, connections, etc.

Power Control Feature
=====================

The Power Control Feature enable us to keep channels less noisy and to save power. The feature enable the option to 
query the peer device for what is the Accepted Power Reduction (APR) on an active connection and to reduce the amount 
of power the peer device allows in the connection. The detailed defination of Power Control Request procedure is
found in the |CORESPEC|, Vol 6, Part B, Chapter 5.1.

Depending on the RSSI Monitor feature implemented, there will be an option to enable a monitor of the RSSI value on a 
specific connection and to ask the peer device autonomously to decrease or increase its power respectively to the RSSI 
that local device receive in the connection. 

Once the power control procedure is done, the TX power changes to the value that was decided for all connection events 
on a specific connection handle and a specific PHY until another power procedure occurs or the connection is lost.

The power control procedure can be triggered from the host/application layer by the HCI command, or by the peer device 
in which case the procedure is handled in the controller layer and notify the host/application if configured. Related 
HCI commands are listed in below. More details about HCI function are in the 
`API references section of the user's guide <../ble-stack-5.x-guide/api-reference-cc23xx.html>`_.

   - HCI_LE_EnhancedReadTransmitPowerLevelCmd ( uint16_t connHandle, uint8_t txPhy )
   - HCI_LE_ReadRemoteTransmitPowerLevelCmd ( uint16_t connHandle, uint8_t txPhy )
   - HCI_LE_SetTransmitPowerReportingEnableCmd ( uint16_t connHandle, uint8_t localEnable, uint8_t remoteEnable )
   - HCI_EXT_SendPowerControlRequestCmd ( uint16_t connHandle, uint8_t txPhy, uint8_t deltaPowerDb, uint8_t aprEnable )
