.. _sysconfig-ble5:

BLE5-Stack SysConfig Features
*****************************

.. warning::
    SysConfig integration for BLE5-Stack examples is not yet complete. As such,
    certain configurations settings may be generated by SysConfig, but not used
    by the application. Please modify the **application** file sources directly
    as needed to work around this.

.. _sec-sysconfig-ble-check:

Checking if SysConfig is used for BLE
-------------------------------------

Projects that are using SysConfig to configure BLE will have a green check mark
next to BLE as shown in the green rectangle.

.. _fig-ble5-syscfg:
.. figure:: resources/ble5_sysconfig_enabled-cc23xx.png
    :align: center

    Check for SysConfig enabled example applications

.. note::
    :ref:`sysconfig-sysconfig` provides an overview of what Sysconfig is and how
    to get started with it. Please take a look at this if you have not already.

Get started with SysConfig enabled |STACK| projects
---------------------------------------------------

After importing a SysConfig enabled |STACK| project into CCS, by double clicking on the ``*.syscfg``
file, a GUI will appear where the project can be configured more easily. A number
of |STACK| configurable features are included in this GUI. :numref:`fig-after-import`
shows what this looks like when importing the ``basic_ble`` example.

.. _fig-after-import:
.. figure:: resources/syscfg_after_import-basicble.png
    :align: center

    After Import


:numref:`fig-after-import` Also shows many different configurable parameters
for the project. The first few configurable options inside the `Software -> BLE`
panel are as shown below. The generated file name for the |STACK| feature is
``ti_build_config.opt``.

.. _fig-ble5-stack-feature:
.. figure:: resources/ble5_sysconfig_stack_feature-cc23xx.png
    :align: center

    Stack Feature

The ``Device Role`` configurable is an example of a drop down list where
you can select the specific ``Device Role`` you wish to use. ``Device Role``
refers to the :ref:`gap_roles` that the project operates as. This can be seen
in :numref:`fig-role-combinations` There are many different options with
different input methods available.

.. _fig-role-combinations:
.. figure:: resources/syscfg_role_combinations-cc23xx.png
    :align: center

    Device Role

When you first open a SysConfig project all of the settings for that project will
be at their default values that are known to work with that example. Providing
this amount of quick and easy configuration for a project is powerful. However,
as we know, with great power comes great responsibility. Any one specific
example is not guaranteed to function properly with any and all permutations of
the available configurable options. More specifically, |STACK| **projects are written
to implement one (or more) specific** :ref:`gap` **Role Combinations, so one
should not switch this unless you know what you're doing**. As long as the files
that are generated from your input compile, the project will build. Whether or
not it performs to the same degree depends on what you changed the options to.

Furthermore, the options that are available to modify will depend on the
:ref:`gap_roles` that have been selected. Changing the ``Device Role`` may
add or remove options below it. If changing the ``Device Role`` option is
required, it is suggested to change this first so that you do not lose any work
you have already done below.

Open the SysConfig output (see :ref:`sec-sysconfig-view-output`).
After selecting a file you will be able, in real-time, to identify how the
changes in the GUI effect the generated files. This will help you review the
relationship between the GUI and the code.

.. _ fig-code-review:
.. figure:: resources/syscfg_code_review-cc23xx.png
    :align: center

    Code Review

.. note::

    Changes will appear as a diff in the code view. Changes will be applied
    when the project is rebuilt.

Additional Configuration Categories
-----------------------------------
.. note::
    Remember that the following Configuration Categories will depend on the
    ``Role Combination`` (:ref:`gap_roles`) you've chosen. Change
    ``Role Combination`` before changing any of the below options.

.. Radio
.. ^^^^^
.. 
..     #. :ref:`sec-creating-a-custom-ble-app-rf-front-end-and-antennas`
..     #. :ref:`sec-phy`
.. 
.. In this view you can configure the front end mode, the bias configuration and
.. the default TX Power. The CC23XX devices support just one configuration for the RF
.. front end and bias configuration. Changing this RF front end and TX power for CC23XX 
.. devices is not currently supported.
.. 
.. .. _fig-rf-settings:
.. .. figure:: resources/syscfg_rf_settings.png
..     :align: center
.. 
..     Radio
.. 
.. In Radio you will also find the BLE Radio Configuration view. Some of the
.. configurations made in BLE Radio Configuration Settings will show up in the
.. generated ``ti_radio_config`` files and are not applicable for BLE projects. The
.. ``Other Dependencies`` -> ``RF`` options control arguments in the RF Driver and
.. the Power Driver config in the Board.c file. For normal operation they should be
.. left unchanged.
.. 
.. .. _fig-rf-settings-ble-radio-configuration:
.. .. figure:: resources/syscfg_rf_settings_ble_radio_configuration.png
..     :align: center
.. 
..     Radio - BLE Radio Configuration
.. 
.. In BLE Configuration, you will find the RF view. The RF view can be used
.. to select pins for custom antenna switching. The RF view can be also used to
.. enable RF coexistence feature.
.. A few remarks regarding the code generated by SysConfig:
.. 
..   - When required, SysConfig will generate callback functions accordingly to the
..     functionalities activated.
..   - The callback functions are generated in ``ti_drivers_config.c``.
..   - Callback functions are only generated if user defined function name is
..     valid (more than 0 characters, valid C identifier and not "NULL").
..   - All "sub-callback" used in the global callback functions are
..     declared 'weak' for application to override.
..   - Callback function with user defined name acts as a template, with
..     description on how to create a new callback function, and how to filter
..     on triggering events. 
..   - Callback function for antenna switching changes function body if custom
..     antenna switching is enabled.
..   - The antenna switching callback function's code describes, with examples,
..     how to handle pin interaction. It also contains function call to
..     non-existing function with descriptive name, to attract attention at
..     linker time and highlight that a new ('strong') definition of the
..     function is required.
.. 
.. .. figure:: resources/SysConfig_RF_coex_antenna_switching.png
..     :align: center
.. 
..     Radio - BLE Radio Configuration - RF

General Configurations
^^^^^^^^^^^^^^^^^^^^^^

    1. :ref:`Device Name <gatt_services_and_profile>`
    #. :ref:`Address Mode & RPA Read Period <privacy-using-device-addresses-in-applications>`

.. _fig-general-configurations:
.. figure:: resources/syscfg_general_configurations-cc23xx.png
    :align: center
    :width: 75%

    General Configurations

.. _bond_manager_configurations:

Bond Manager
^^^^^^^^^^^^

    1. :ref:`Bond Manager <GAP-bond-manager-and-le-secure-connections>`

These settings control all the bond manager parameters and generate the function
``setBondManagerParameters()`` in **ti_ble_config.c** file. This function sets all the bond
manager parameters as configured by SysConfig, and should be called from the
main application.

.. _fig-bond-manager-configurations:
.. figure:: resources/syscfg_bond_manager_configurations-cc23xx.png
    :align: center
    :width: 75%

    Bond Manager Configurations

.. note::
    Currently, there is a limitation when using SysConfig to configure the
    number of bonds. SysConfig will only successfully configure up to 10 bonds. If
    the user configures more than 10 bonds in SysConfig, the first 10 connections
    will bond and pair successfully while the remaining connections will pair
    successfully, but fail bonding. Please refer to :ref:`gapbondmgr_and_snv` for
    information on how to configure more than 10 bonds.

Advanced Settings
^^^^^^^^^^^^^^^^^

In this category you will find settings that configure the application such as
Power Management. You can also configure whether to use RCOSC and/or PTM mode. 
You will also find ICall options. More information:
    
#. :ref:`sec-freertos-power-management`
#. :ref:`sec-hal-assert`
#. Extended Stack Settings, see :ref:`link_layer`
#. :ref:`gapbondmgr_and_snv`
#. :ref:`sec-using-production-test-mode`
#. ICall, see: :ref:`sec-creating-custom-ble-application-creating-additional-freertos-tasks`
#. :ref:`sec-adaptivity-using-daa`

Central Configuration
^^^^^^^^^^^^^^^^^^^^^

    1. :ref:`gap_roles`
    #. :ref:`sec-phy`


.. _fig-central-configurations:
.. figure:: resources/syscfg_central_configurations.png
    :align: center
    :width: 75%

    Central Configurations

Observer Configuration
^^^^^^^^^^^^^^^^^^^^^^

    #. :ref:`sec-phy`
    #. :ref:`gapscanner`

.. _fig-observer-configurations:
.. figure:: resources/syscfg_observer_configurations-cc23xx.png
    :align: center
    :width: 75%

    Observer Configurations

Peripheral Configuration
^^^^^^^^^^^^^^^^^^^^^^^^

    1. :ref:`gaprole_peripheral_role`
    #. :ref:`Discoverable Mode <gap_limited_advertising>`
    #. :ref:`Connection Params <connection_parameters>`


.. _fig-peripheral-configurations:
.. figure:: resources/syscfg_peripheral_configurations-cc23xx.png
    :align: center
    :width: 75%

    Peripheral Configurations

Broadcaster Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^

    1. :ref:`gap_roles`
    #. :ref:`Advertisements <gap-advertiser>`
        For each advertisement set, the advertisement parameters
        (Advertisment Type, Channels, TX Power...),
        the advertisement data and the scan response can be set.
        **The TX Power parameter will not affect Legacy Advertisement sets.**

.. _fig-broadcaster-configurations:
.. figure:: resources/syscfg_broadcaster_configurations-cc23xx.png
    :align: center
    :width: 75%

    Broadcaster Configurations

Device Configuration
^^^^^^^^^^^^^^^^^^^^^

The Device Configuration pannel located in the Software -> BLE panel is as shown below.
This pannel let you choose the LF Clock Source between ``LF XOSC`` or ``LF RCOSC``.

Voltage regulator ``DC-DC`` or ``GLDO`` can also be selected.

.. _fig-device-configuration:
.. figure:: resources/syscfg_device_configuration.png
    :align: center
    :width: 75%

