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.
