=================================================
Optimizing Bluetooth Low Energy Power Consumption
=================================================

This section describes how to configure the |DEVICE| devices in order to evaluate
its power consumption while running Advertisement and Connection Bluetooth LE
operations. To this end, the ``basic_ble`` project found inside the
`SDK <https://www.ti.com/tool/download/SIMPLELINK-LOWPOWER-F3-SDK>`_ examples,
is used as the starting reference.

The following steps are modifications to consider before doing power
measurements calculations:

Power Optimization
^^^^^^^^^^^^^^^^^^

1. Disable UART display operations: go inside ``basic_ble.syscfg`` -->
   RF Stacks --> BLE --> Advanced Settings, select "Disable The Display Module".
   In addition, make sure to disable any other peripheral that is not being
   used, such as LEDs or buttons.

.. _disable_display_mode:
.. figure:: resources/disable_display_mode.png
    :align: center

    SysConfig - Disable UART display operations.

2. Set the advertisement parameters: go inside ``basic_ble.syscfg`` -->
   RF Stacks --> BLE --> Broadcaster Configuration --> Advertisement Set 1 -->
   Advertisement Parameters 1, modify:

    * Legacy Event Properties Options: Select the advertisement mode
      (Connectable and Scannable Undirected, Connectable directed,
      Non-connectable and Non-scannable undirected). It is important
      to take into consideration that Non-connectable and Non-scannable
      advertisement modes will not schedule RX operations as they are
      not expecting information to be shared with them, therefore reducing the
      amount of power consumption. Example of this are applications that do not 
      require extra information through scan responses, such as Bluetooth LE beacons. 

    * Primary PHY Interval Minimum and Maximum (ms): Consider that for longer
      intervals, the device will spend more time in standby mode, considerably
      reducing the power consumption.
    * Tx Power Value: Consider that increasing or decreasing this value
      will have a considerable impact on power consumption.

.. _config_adv_parameters:
.. figure:: resources/config_adv_parameters.png
    :align: center

    SysConfig - Set Advertisement Parameters.

3. Set TX power for connection events: if the device is configured as
   ``central``, go to ``app_central.c`` and add the
   ``HCI_EXT_SetTxPowerDbmCmd()`` after registering the event handler inside
   the ``Central_start()`` function. Alternatively, if the device is configured
   as ``peripheral``, go to ``app_peripheral.c`` and add the
   ``HCI_EXT_SetTxPowerDbmCmd()`` after registering the event handler inside
   the ``Peripheral_start()`` function. See more details about this topic inside the 
   following reference: `Adjusting TX Power <../cc23xx/txpower-cc23xx.html>`_.

   .. code-block:: c
    :caption: Set TX power for connection events - ``HCI_EXT_SetTxPowerDbmCmd()``.
    :linenos:

    //...
    const int8_t txPower = 8;
    const uint8_t fraction = 0; // Should always be 0 for CC23xx devices
    HCI_EXT_SetTxPowerDbmCmd(txPower, fraction);
    //...

.. warning::
    The ``Fraction`` parameter must remain 0 as this feature is not supported
    at the moment.

4. Modify the type and amount of data the device is sending during advertisement:
   go to ``basic_ble.syscfg`` --> RF Stacks --> BLE --> Broadcaster Configuration -->
   Advertisement Set 1 --> Advertisement Data 1. There, it is possible to add
   different type of data as required by the application. Make sure to avoid
   adding data that is not used, as power consumption increases with payload
   size. It is possible to see the payload size by going into ``ti_ble_config.c``
   and looking into the number of elements inside ``advData1[]``.

.. _adv_data_size_setup:
.. figure:: resources/adv_data_size_setup.png
    :align: center

    SysConfig - Modify Advertisement Data.

5. Avoid waking up the device every time the advertisement starts: go
   to ``gap_advertiser.h`` and create a new ``GAP_ADV_EVT_MASK``, that
   will only consider ``GAP_ADV_EVT_MASK_SCAN_REQ_NOTI`` and
   ``GAP_ADV_EVT_MASK_START_AFTER_ENABLE`` events. Replace this new
   mask at the function ``BLEAppUtil_initAdvSet()`` in ``bleapputil_init.c``
   instead of ``GAP_ADV_EVT_MASK _ALL`` mask.

.. code-block:: c
    :caption: ``gap_advertiser.h`` - Create new ``GAP_ADV_EVT_MASK``.
    :linenos:

    //...
    GAP_ADV_EVT_MASK_ALMOST_ALL  = GAP_ADV_EVT_MASK_SCAN_REQ_NOTI |
                                   GAP_ADV_EVT_MASK_START_AFTER_ENABLE,
    //...

6. To save some extra power, the External Flash can also be turned off
   during board initialization using ``Board_shutDownExtFlash();``. This
   is already done by default at the ``basic_ble.c`` project, as can be
   seen inside ``ti_drivers_config.c`` at the very end of the ``Board_init()``
   function.

   .. warning::
    Power consumption is significantly increased while being in debug mode.
    The device should be flashed and power cycled before running power
    measurements.

7. Enable power control feature by using HCI commands. See more details about 
   this topic inside the following reference: `Power Control Feature <../cc23xx/txpower-cc23xx.html>`_.