.. _EnergyTrace Tool: https://www.ti.com/tool/ENERGYTRACE
.. _EnergyTrace overview: https://software-dl.ti.com/ccs/esd/documents/xdsdebugprobes/emu_energytrace.html

.. _energytrace-users-guide:

EnergyTrace User Guide
----------------------

EnergyTrace\ |trade| technology is a power analyzer tool for CCS that measures
the application's current consumption. The tool can be used stand-alone as a
power profiling tool, or in EnergyTrace++ mode within a debug session for code
analysis to help optimize the application for ultra-low-power consumption.

For further information regarding the EnergyTrace Tool, see the 
`EnergyTrace Tool`_ page. Additionally, please visit further EnergyTrace 
documentation at `EnergyTrace overview`_.

.. _energytrace-standalone-instructions:

EnergyTrace stand-alone Instructions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following discusses the necessary steps to use EnergyTrace in
stand-alone-mode on |LP|. In stand-alone mode (EnergyTrace mode), the debugger 
is not active and the displayed current consumption is what to expect for the 
final application. As opposed to EnergyTrace++ where the debug interface on the
device is active and the current consumption from the debugger will be added to
the displayed current.


#. Flash the target device with the application to be analyzed.
   
#. Make sure no debug session is active and click the EnergyTrace Button as seen
   in :numref:`fig-energytrace-standalone-button`

   .. _fig-energytrace-standalone-button:
   .. figure:: resources/fig-energytrace-standalone-button.png
       :align: center

       Start EnergyTrace

#. A dialog with instructions on how to use EnergyTrace Stand-alone Measurement
   Mode will pop-up. Click ``Proceed`` to continue. 

#. The first time EnergyTrace is being used within a CCS Workspace some settings
   needs to be set. In the EnergyTrace Window, click on the ``Advanced Menu`` 
   icon and select ``Preferences``, as 
   :numref:`fig-energytrace-preferences-button` shows.

   .. _fig-energytrace-preferences-button:
   .. figure:: resources/fig-energytrace-preferences-button.png
       :align: center

       EnergyTrace Preferences menu

#. Under ``Target Connection``, set ``Connection`` to ``XDS110`` and ``Voltage``
   to 3300.0 mV. ``ET-HDR Range Selector`` shall be set to ``Low current,
   narrower range higher accuracy``. If you want to save the captured data to a
   .cvs-file for further analysis, select ``Raw data to CSV file``. You can also
   select the battery cell type the application will be using to get an
   estimated life time of the application. Click ``Ok`` to save the preferences.

   .. _fig-energytrace-standalone-settings:
   .. figure:: resources/fig-energytrace-standalone-settings.png
       :align: center

       EnergyTrace Settings
   
#. Select how long you want to capture data by clicking the ``Select Measurement
   Duration`` button as in :numref:`fig-energytrace-standalone-time`

   .. _fig-energytrace-standalone-time:
   .. figure:: resources/fig-energytrace-standalone-time.png
       :align: center

       Select Measurement Duration

#. To start capturing data, click the green play button.

   .. _fig-energytrace-standalone-start:
   .. figure:: resources/fig-energytrace-standalone-start.png
       :align: center

       Start trace collection

#. When EnergyTrace is finished capturing data, review the application's power
   profile and have a closer look in the Current
   graph. :numref:`fig-energytrace-standalone-graph` shows a zoomed-in current
   graph of BLE advertising.

   .. _fig-energytrace-standalone-graph:
   .. figure:: resources/fig-energytrace-standalone-graph.png
       :align: center
       :width: 6.0in

       EnergyTrace Current Graph

   
EnergyTrace++ Instructions
^^^^^^^^^^^^^^^^^^^^^^^^^^

To run EnergyTrace++, which allows more detailed data regarding power
consumption, the Target Configuration file must be configured to allow for a
different debugging interface. Specifically, to use EnergyTrace++, the debugger
must be set to 4-pin cJTAG mode. The following discusses the necessary steps to
modify the Target Configuration file and view EnergyTrace++ data on |LP|.

.. warning:: In EnergyTrace++ mode, the displayed current consists of the
   application current consumption AND the device debugger current
   consumption. Use EnergyTrace stand-alone mode to display only the application
   current consumption.

.. _energytrace-update-target-conf:

EnergyTrace++ Update Target Configuration Instructions
""""""""""""""""""""""""""""""""""""""""""""""""""""""

#. In the CCS, using the Project Explorer, navigate to the ``targetConfigs``
   folder.

#. Double click on the ``*.ccxml`` file to open a configuration menu as seen in
   :numref:`fig-ccxml-config-menu`

   .. _fig-ccxml-config-menu:
   .. figure:: resources/fig-ccxml-config-menu.png
       :width: 3.0in

       Open .ccxml file

#. On the bottom of the window, navigate to the ``Advanced`` tab as seen in
   :numref:`fig-advanced-settings`

   .. _fig-advanced-settings:
   .. figure:: resources/fig-advanced-settings.png
       :width: 3.0in

       Navigate to Advanced Settings Tab

#. In the ``All Connections`` windows pane, click on the highest level from the
   list tree as seen in :numref:`fig-connection-properties`

#. In the ``Connection Properties`` window pane, modify the ``JTAG/SWD/cJTAG
   Mode`` parameter to ``cJTAG (1149.7) 4-pin standard mode`` from the dropdown
   menu as seen in :numref:`fig-connection-properties`

   .. _fig-connection-properties:
   .. figure:: resources/fig-connection-properties_updated.png
       :width: 6.0in

       Configure 4-pin cJTAG Mode

#. After selecting this option, click ``Save`` in the previous ``All
   Connections`` window pane.

#. Close the ``.ccxml`` file.

Using EnergyTrace++ Instructions
""""""""""""""""""""""""""""""""

This section assumes the user has already configured their Target Configuration
settings to point use ``cJTAG (1149.7) 4-pin standard mode`` as described in
the :ref:`energytrace-update-target-conf` section above.

#. After the Build has successfully completed, ``Debug`` the project.

#. Open the EnergyTrace Tool by clicking the button seen below in
   :numref:`fig-energytrace-pp-button`

   .. _fig-energytrace-pp-button:
   .. figure:: resources/fig-energytrace-pp-button.png
       :width: 4.03594in

       Enable EnergyTrace Tool

#. On the far right of the ``EnergyTrace Technology`` window, click the
   ``Switch to EnergyTrace++`` button as seen in
   :numref:`fig-switch-to-energytrace-pp`

   .. _fig-switch-to-energytrace-pp:
   .. figure:: resources/fig-switch-to-energytrace-pp.png
       :width: 6in

       Switch to EnergyTrace++ Mode

#. You should see an additional ``States`` tab popup.

#. Run the Debug session, click the green arrow button (F8).

#. You should now be able to observe the enhanced EnergyTrace++ details in the
   ``EnergyTrace Technology`` and ``States`` tabs as seen in
   :numref:`fig-energytrace-pp-tab` and :numref:`fig-energytrace-pp-tab-states`

.. _fig-energytrace-pp-tab:
.. figure:: resources/fig-energytrace-pp-tab.png
    :width: 100%

    Sample EnergyTrace++ Tab

.. _fig-energytrace-pp-tab-states:
.. figure:: resources/fig-energytrace-pp-tab-states.png
    :width: 100%

    Sample EnergyTrace++ "States" Tab

.. _energytrace-external-target:

Using EnergyTrace with an External Target
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The power profile of an external target can be measured using EnergyTrace and a
compatible debugger: an XDS110 ETHDR Debug Probe or a |LP| Kit (the debug
probe is embedded on the LaunchPad board). In this section, we 
will use a `CC26x2R LaunchPad`_ to measure the power profile of a `CC2640R2F`_.

.. note::
   Other types of LaunchPad that include a XDS110 ETHDR Debug Probe may be used 
   instead of `CC26x2R LaunchPad`_

Before getting started, make sure the external target is already flashed with
the application firmware to be tested.

The following steps are required to use EnergyTrace with an external target:

#. Remove all the jumpers from the top row of both LaunchPads as shown in
   :numref:`fig-energytrace-external-target`.
#. Use jumper wires to supply power to the `CC2640R2F`_ from the `CC26x2R LaunchPad`_ as
   shown below.
#. At this point, connect only the `CC26x2R LaunchPad`_ to the PC via a USB cable. The
   external target will receive power from the `CC26x2R LaunchPad`_.
#. Follow the steps in :ref:`energytrace-standalone-instructions` to measure the
   power profile of the external target.

.. tip::
   Ensure that only one `CC26x2R LaunchPad`_ is connected to the PC at a time to ensure the
   correct LaunchPad is automatically selected by EnergyTrace.

.. _fig-energytrace-external-target:
.. figure:: resources/fig-energytrace-external-target.png
   :align: center

   External Target Hardware Configuration

The above diagram shows the hardware setup required to use EnergyTrace to
measure the power profile of the `CC2640R2F`_.

.. note::
   With the jumpers removed, a 10-pin JTAG cable can be connected to the
   external target for debugging purposes. If UART is required, jumper wires
   should be placed to connect the TX/RX lines of the external target to the
   `CC26x2R LaunchPad`_.

.. only:: MODULAR_LP

   Using EnergyTrace on a Modular Launchpad\ |trade| Design
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

   If you're using one of the new TI Modular Launchpads\ |trade|, you'll need to connect the two sides 
   of the Modular Launchpad\ |trade| together if you want to use EnergyTrace++ functionality. 

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

      Modular LP EnergyTrace++ Configuration

   Otherwise, if you're running stand-alone EnergyTrace, connecting just the 3.3 V and GND lines 
   should be sufficient. 

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

      Modular LP EnergyTrace stand-alone Configuration

   Finally, if you're connecting to an external target with a Modular Launchpad\ |trade|, you just need to
   connect the 3.3 V and GND lines on the Modular LaunchPad\ |trade| Emulator to the external target. The Modular Launchpad\ |trade|
   Target is not needed at all.

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

      Modular LP EnergyTrace for External Target Configuration

Troubleshooting
^^^^^^^^^^^^^^^

If EnergyTrace is not able to properly setup remote controls for the
device, try closing CCS, resetting your Evaluation Board and starting
again.
