.. _sysconfig-radio-configuration:

Radio Configuration
===================

You can use :term:`SysConfig` to configure the radio settings. E.g. if you are
using a prop_rf project, you can use the Custom RF 
Stack SysConfig view to add settings to ``ti_radio_config.c/h``. It is also
possible to use `SmartRF Studio`_ 8 to configure the RF settings. In this case
you will get files named ``rcl_settings.c/h``, corresponding to the
``ti_radio_config.c/h`` files generated by SysConfig.

Most configurable parameters in the RF STACKS Custom view are also found as a
configurable parameter in SmartRF Studio 8. If there is a specific parameter you
need documentation about, please check `SmartRF Studio`_ 8 or in the |TRM|.

In the following sections, rfPacketTx is used as the example, but the
instructions are valid for any prop_rf example project.

.. note::

    Custom RF Stack configuration in SysConfig will only make changes to
    ``ti_radio_config.c/h``. Any required changes to your application files
    you must do on your own.

Open An Example Project
-----------------------

Open the standalone SysConfig tool or a SysConfig-enabled example project.

Open the ``.syscfg`` file.

.. _sysconfig-rf-driver-add-rf-settings:

Adding RF Settings
------------------

In the RF STACKS view, you can add sets of settings for multiple RF stacks. If
you're not using one of the RF stacks, you can use the Custom option to add a
direct configuration of the radio settings (``ti_radio_config.c/h``).

When you open the Custom RF STACKS view you will see that the RF settings are
divided into modes; BLE mode for BLE compliant PHYs and Proprietary
mode for the  2400 - 2480 MHz band. You can have multiple sets of RF settings
defined simultaneously.

    .. figure:: resources/ccs_syscfg_custom_rfstack_cc23.png
        :align: center

#. **Enable RF Stack**

    In the RF STACKS view, enable at least one option. For example, select
    Custom. You can now configure various PHYs offered there.

    .. figure:: resources/ccs_syscfg_custom_add_cc23.png
        :align: center

#. **Choose PHY Type**

    Within the selected RF Stack, you can select from a variety of RF Settings.
    Each time a setting is enabled, a box will appear in SysConfig that will
    allow further configuration. Multiple RF Settings may be added
    simultaneously.

    .. figure:: resources/ccs_syscfg_custom_add_phy_cc23.png
        :align: center

#. **Name the Set of RF Settings**

    Each set of RF Settings must have a unique name, which is used when
    generating their respective RCL Driver structures. Scroll down to Code
    Export Configuration and select the desired Symbol Name Generation Method:

        * SmartRF Studio - Compatible with SmartRF Studio naming. Only one set of RF
          Settings may use this (e.g. "rclPacketTxCmdGenericTx").
        * Automatic - Unique naming is generated based on the short notation of the
          PHY and an index (e.g. "rclPacketTxCmdGenericTx\_\ **ble_gen_1**").
        * Custom - User may choose a custom name for each of the structures. Note
          that as of 7.40 SDK, this feature is under development; it is recommended
          to use the other two methods.
          
    You can see the generated names in the RF Command Symbols and Data structs 
    tabs.

    .. figure:: resources/ccs_syscfg_custom_code_exp_cc23.png
        :align: center

#. **Set the PHY Properties**

    If using a Custom RF Stack, you can then configure basic PHY parameters such
    as Frequency/Channel and Tx Power, and settings related to packet format
    such as the sync word. Different PHYs may allow different user-configurable
    parameters.

    Each parameter is more thoroughly explained if you press the small circle
    with a question mark next to the parameter name.

    .. NOTE: this is currently not possible due to the settings present.
             will leave this here as a note in case we expose more user-configurable
             parameters in the future.
        Make sure your settings make sense from an RF point of view. Certain parameter
        combinations will give you a build error. Others will give you a hint to a
        file where you need to change a different parameter based on your SysConfig
        parameters. In this case, make sure to comply (as SysConfig will not make
        this change for you).
    
    .. figure:: resources/ccs_syscfg_custom_phy_properties.png
        :align: center

    .. NOTE: unavailable for CC23xx Custom RF Stack.
        #. **Set the Link Layer Options**

            (For BLE and IEEE 802.15.4 settings you will not get this tab.) In the Link Layer 
            tab you can set packet parameters such as packet length and Rx address to 
            filter on.

#. **The Other Dependencies Tab**

    In this tab you can configure options that are defined outside of the
    RF STACKS view in SysConfig. E.g. the RF Design is found under the
    RF DESIGN view. If you change the RF Design settings in RF STACKS view, you
    will see your changes reflected in the RF DESIGN view.

#. **Save the** ``.syscfg`` **file.**

#. **Generate the files**

    You can see the generated files by clicking the ``<>`` symbol. In this
    example, ``ti_drivers_config.c/h`` was generated by the "TI Drivers" view
    and ``ti_radio_config.c/h`` was generated by the RF STACKS view. In
    addition, ``ti_devices_config.c`` (previously called ``ccfg.c``) and
    ``syscfg_c.rov.xs`` are generated. 

    .. figure:: resources/ccs_syscfg_gen_files_list_cc23.png
        :align: center

    After the build has completed, you will find the generated files in the 
    output folder of your project. In this example, it's the folder called 
    "Debug" of the rfPacketTx example.

    .. figure:: resources/ccs_syscfg_custom_file_location.png
        :align: center

    The Radio Settings are shown separately in the generated
    ``ti_radio_config.c`` file. In this example, one set of RF Settings was
    added. A summary of the RF Settings is shown in that file:

    .. code-block:: c
        :caption: **ti_radio_config.h** - RF Settings Summary

        // ****************************************************************
        //  PHY name:            Generic 1 Mbps / 2 Mbps / Coded
        //  PHY abbreviation/ID: ble_gen
        //  PHY definition file: ble_bt5_generic.json
        // ****************************************************************

        // PARAMETER SUMMARY

        // Default sub-PHY: 1_mbps
        // Coded rate in TX: s8
        // Channel - Frequency (MHz): 2440
        // TX Power (dBm): 5

#. **Adjust Your Application Files**

    The names of RF objects have been generated according to the naming rules
    chosen in Code Export Configuration. Make sure your application is using the
    correct name whenever an RF object is used.

    In this example, RF objects are only called from ``rfPacketTx.c``. For each
    RF object, make sure the name is correct according to the RF Settings you
    have generated. This is also valid if your application uses multiple sets of
    RF Settings. Use build errors and warnings to make sure you are using the
    correct names.

    .. attention::

        Whenever you re-build the project, by default SysConfig will re-generate
        the files. Because of this, any changes made directly in the files
        (``ti_radio_config.c/h``) will be overwritten and lost.
        There is also an option to disable SysConfig from generating certain
        files, for more details see :ref:`sysconfig-disable`.

Selecting an RF Design
----------------------

In the RF DESIGN view, you can select which radio features to include in your design,
with respect to frequency band and RF front-end. All designs are based on
existing TI reference designs.

    .. figure:: resources/ccs_syscfg_custom_rf_design_1.png
        :align: center

When using SysConfig through CCS the board is already locked in the IDE and to change the
"Based on RF Design" field, you will need to select USE CUSTOM BOARD first.

    .. figure:: resources/ccs_syscfg_custom_rf_design_2.png
        :align: center

#. **Select RF Design**

    The recommended RF design to use for development is LP_EM_CC2340R5.
    This correlates to the |LP_CC23xx|.

#. **Select Frequency Band**

    For |DEVICE| devices, the 2.4 GHz frequency band should be selected.

#. **Select Front-End**

    Select front-end (and bias mode) for 2.4 GHz, depending on which
    RF design you have. The available options are:

    * External Bias, Differential mode
    * Internal Bias, Differential mode
    * External Bias, Single-Ended mode RFP
    * External Bias, Single-Ended mode RFN
    * Internal Bias, Single-Ended mode RFP
    * Internal Bias, Single-Ended mode RFN

    Some options are only available for custom boards.
