TX Power
========

TX power, short for transmit power, is a parameter used to set a desired
output power during packet transmissions. The TX power level is programmable
at run-time and will only take effect on the next transmission.

.. _tx_power_configuration:

TX Power Configuration
----------------------
The default values for all parameters are usually measured by Texas Instruments for
a specific front-end configuration on TI LaunchPads hardware; if instead a custom board
is used the values will need to be re-tuned for the specific custom hardware. 

TX Power Tables
---------------

TX power configuration is usually done by `SysConfig`_  or by code export in
`SmartRF Studio`_. A default TX power configuration is set, in addition to a
TX power table being configured/exported alongside the settings.

For example if you are using `SysConfig`_ and leave the txPower undefined, or as
default then the ``RCL_CmdGenericTx`` struct will use ``RCL_CmdGenericTx_Default()`` 
which sets the TX power to 0 dBm:

.. code-block:: c  
    :caption: Default configuration for the generic transmit command, found in the generic.h file.

        #define RCL_CmdGenericTx_Default()                      \
    {                                                           \
        .common = RCL_Command_Default(RCL_CMDID_GENERIC_TX,     \
                                    RCL_Handler_Generic_Tx),    \
        .rfFrequency = 2440000000U,                             \
        .txBuffers = { 0 },                                     \
        .syncWord = 0x930B51DE,                                 \
        .txPower = {.dBm = 0, .fraction = 0},                   \
        .config = {                                             \
            .fsOff = 1,                                         \
            .reserved = 0,                                      \
        },                                                      \
    }

A TX power table is a lookup table of all TX power table entries which are
characterized for the given RF front-end configuration. A TX power table entry
is a key-value pair, where the key is a human-readable power level in dBm and
the value a TX power configuration value. You can find a example of the TX power
table in ``rcl_settings.c`` as ``LRF_txPowerTable``. 

If you generate or export any RF settings for |DEVICEAND|, depending on which RF
front-end configuration you are using, you will see in *rcl_settings.c* in a new 
array called :code:`LRF_txPowerTable` with the following
syntax:

.. note::
    When exporting new RF configs with `SmartRF Studio`_ on the code export page, if you select `Use PHY abbreviation`
    the file naming will change from ``rcl_settings.c`` to ``rcl_settings_msk_250_kbps.c`` for example (the new name depends on 
    which example, and custom naming you use in `SmartRF Studio`_ PHYs). 

.. code-block:: c 
    :caption: Tx power table obtained from `SmartRF Studio`_ 8 code export - it shows the internal structure of how the transmit power is generated.

    // LRF_TxPowerTable data structure
    const LRF_TxPowerTable LRF_txPowerTable = {
        .numEntries            = 0x0000000E,
        .powerTable            = {
            { .power = { .fraction = 0, .dBm = -20 }, .tempCoeff = 0, .value = { .reserved = 0, .ib = 18, .gain = 0, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = -16 }, .tempCoeff = 0, .value = { .reserved = 0, .ib = 20, .gain = 1, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = -12 }, .tempCoeff = 5, .value = { .reserved = 0, .ib = 17, .gain = 3, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = -8 }, .tempCoeff = 12, .value = { .reserved = 0, .ib = 17, .gain = 4, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = -4 }, .tempCoeff = 25, .value = { .reserved = 0, .ib = 17, .gain = 5, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 0 }, .tempCoeff = 40, .value = { .reserved = 0, .ib = 19, .gain = 6, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 1 }, .tempCoeff = 65, .value = { .reserved = 0, .ib = 30, .gain = 6, .mode = 0, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 2 }, .tempCoeff = 41, .value = { .reserved = 0, .ib = 39, .gain = 4, .mode = 1, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 3 }, .tempCoeff = 43, .value = { .reserved = 0, .ib = 31, .gain = 5, .mode = 1, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 4 }, .tempCoeff = 50, .value = { .reserved = 0, .ib = 37, .gain = 5, .mode = 1, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 5 }, .tempCoeff = 55, .value = { .reserved = 0, .ib = 27, .gain = 6, .mode = 1, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 6 }, .tempCoeff = 75, .value = { .reserved = 0, .ib = 38, .gain = 6, .mode = 1, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 7 }, .tempCoeff = 80, .value = { .reserved = 0, .ib = 25, .gain = 7, .mode = 1, .noIfampRfLdoBypass = 0 } },
            { .power = { .fraction = 0, .dBm = 8 }, .tempCoeff = 180, .value = { .reserved = 0, .ib = 63, .gain = 7, .mode = 1, .noIfampRfLdoBypass = 0 } } 
        }
    };

Programming the TX Power Level
------------------------------

In the proprietary RF examples, the desired tx power is set via `SysConfig` or by setting the txPower parameter in code. 

An example on how you can set the txPower parameter in code before calling ``RCL_Command_submit()``: 

.. code-block:: c

    RCL_CmdGenericTxTest   txCmd;
    ... //define application code here, use rfpacketTX example to start off with 
    txCmd.txPower.dBm = txpow;      // Set the TX power in dBm
    ... //send the packet

