.. _stack_features_configuration:

Stack Configurations
--------------------

Most projects are using SysConfig to configure the BLE-Stack. See
:ref:`sec-sysconfig-ble-check` for steps on how to check if SysConfig is
enabled for BLE. Based on the selected SysConfig settings, only the necessary
precompiled libraries will be linked to the project.

.. caution::

  Note that the following section applies only to example applications that are
  **not** configuring the BLE-Stack via SysConfig. For information
  about configuring the BLE-Stack with SysConfig see :ref:`sysconfig-ble5`.


Configuring Bluetooth Low Energy Protocol Stack Features
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Bluetooth Low Energy protocol stack can be configured to include
or exclude certain Bluetooth Low Energy features by changing the
library configuration. The available Bluetooth
Low Energy features are defined in the ``build_config.opt`` file in
the Tools folder of the stack project within the IDE. Based on the features
selected in the ``build_config.opt`` file, the respective precompiled libraries
will be selected during the build process of the stack project.


Run-Time Bluetooth Low Energy Protocol Stack Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Bluetooth Low Energy protocol stack can be configured with
various parameters that control its runtime behavior and RF antenna
layout. The available configuration parameters are described in
the ``ble_user_config.h`` file in the ICallBLE IDE folder of the
application. During initialization, these parameters are supplied to the
Bluetooth Low Energy protocol stack by the ``user0Cfg`` structure, declared in
main.c.

.. code-block:: c

  #include "ble_user_config.h"

  // BLE user defined configuration
  bleUserCfg_t user0Cfg = BLE_USER_CFG;

Because the ``ble_user_config.h`` file is shared filed between the Bluetooth
Low Energy projects within the SDK, TI recommends defining configuration
parameters in the ``.opt`` files found under ``TOOLS\defines``. The ``.opt``
files contain preprocessor symbols of the application when the default value
isn't sufficient. For example, to change the maximum PDU size from the default
27 to 162, set the preprocessor symbol ``MAX_PDU_SIZE=162`` in the
preprocessor symbols for the application project. Increasing certain
parameters may increase heap memory use by the protocol stack;
adjust the ``HEAPMGR_SIZE`` as required (if not using auto sized heap).
:numref:`appconfigurablefeatures` and :numref:`stackconfigurablefeatures`
list the available configuration parameters.

.. _stackconfigurablefeatures:
.. _appconfigurablefeatures:

.. table:: Bluetooth Low Energy Application Configuration Parameters

    =============== =============================== ===================================================================================================================================================================================================
     Configurable?              Define                                                                                                          Description
    =============== =============================== ===================================================================================================================================================================================================
           N        CC23X0                          This selects the chipset - *Note: this symbol is usually also defined in the project properties*
           Y        LP\_EM\_CC2340R5                This define may be changed when migrating to a custom development board
           N        DeviceFamily\_CC23X0            This selects the chipset - *Note: this symbol is usually defined in the project properties*
           Y        Display\_DISABLE\_ALL           If set, the Display module will be disabled.
           Y        EXT\_HAL\_ASSERT                Defining this assert will forward ble asserts to the application
           Y        EXTENDED_STACK_SETTINGS         Bitmask of extended stack settings that are passed to the stack via ble_user_config. Options are defined in build_components.opt.
           N        ICALL\_EVENTS                   This define is used with ICALL - do not modify
           N        ICALL\_JT                       This define is used with ICALL - do not modify
           N        ICALL\_LITE                     This define is used with ICALL - do not modify
           Y        ICALL\_MAX\_NUM\_ENTITIES       This Maximum number of entities that use ICall, including service entities and application entities.
           Y        ICALL\_MAX\_NUM\_TASKS          Defines the max number of ICall enabled tasks. Must be the same as OSAL\_MAX\_NUM\_PROXY\_TASKS + 1. Default is 2.
           Y        L2CAP\_NUM\_CO\_CHANNELS        Maximum number of L2CAP Connection-Oriented (CO) Channels. Default is 3.
           Y        L2CAP\_NUM\_PSM                 Maximum number of L2CAP Protocol/Service Multiplexers (PSM). Default is 3.
           Y        MAX\_NUM\_BLE\_CONNS            This is the maximum number of simultaneous Bluetooth Low Energy collections allowed. Adding more connections uses more RAM and may require increasing HEAPMGR\_SIZE. Profile heap usage accordingly
           Y        MAX\_NUM\_PDU                   Maximum number of Bluetooth Low Energy HCI PDUs. Default is 5. If the maximum number of connections is set to 0, then this number should also be set to 0.
           Y        MAX\_PDU\_SIZE                  Maximum size in bytes of the Bluetooth Low Energy HCI PDU. Default is 27. Valid range is 27 to 255. The maximum ATT\_MTU is MAX\_PDU\_SIZE - 4. See Configuring for Larger MTU Values.
           Y        NPI\_SPI\_CONFIG                When NPI\_USE\_API is defined, this will allows you to choose which SPI driver instance NPI will be used.
           Y        NPI\_USE\_SPI                   Configure NPI to use SPI. Do not define NPI\_USE\_UART and NPI\_USE\_SPI at the same time.
           Y        NPI\_USE\_UART                  Configure NPI to use UART. Do not define NPI\_USE\_SPI and NPI\_USE\_UART at the same time.
           Y        PM\_STARTUP\_MARGIN             Defines time in microseconds (us) the system will wake up before the start of the connection event. Default is 300. This value is optimized for the example projects.
           Y        POWER\_SAVING                   Power management is enabled when defined, and disabled when not defined. 
           Y        PTM\_MODE                       Define this will enable PTM mode.
           Y        SC\_HOST\_DEBUG                 Define this will make the LE Secure Connection use the debug keys specified by the Bluetooth Core Specification, therefore it's easy to decrypt the link and follow the over the air traffic.
           N        STACK\_LIBRARY                  Build/Use the build configuration where the stack is built as a library
           N        USE\_ICALL                      This define is used with ICALL - do not modify
           Y        USE\_RCOSC                      This define will make the software to operate the |DEVICE| in a 32kHz crystal-less mode.
           N        USE\_RCL                        This define indicates the Radio Controller Layer (RCL) is used - *Note: this symbol is usually defined in the project properties*
           N        FREERTOS                        This define indicates FreeRTOS is used as RTOS - *Note: this symbol is usually defined in the project properties*
           N        FLASH\_ONLY\_BUILD              This define indicates all the code is stored in Flash (and not in ROM as it is the case for certain device families) - *Note: this symbol is usually defined in the project properties*
           N        ICALL\_NO\_APP\_EVENTS          This defines indicates the application does not have a special queue for ICall events. This is typically the case for the examples based on the BLEAppUtil framework, as all the events are enqueued to the BLEAppUtil queue and handled there - *Note: this symbol is usually defined in the project properties*
           N        NVOCMP\_NWSAMEITEM              Crypto driver configuration - *Note: this symbol is usually defined in the project properties*
           N        NVOCMP\_POSIX\_MUTEX            Crypto driver configuration - *Note: this symbol is usually defined in the project properties*
           Y        ATT\_DELAYED\_REQ               Allows to reply to a Read Att Request at a later stage, if the request cannot be processed when received (see also :ref:`delaying_an_att_read_request`)
           Y        EXT\_HAL\_ASSERT                Defining this assert will forward ble asserts to the application
           Y        GATT\_NO\_CLIENT                Should only be done for devices that do not wish to discover the RPAO characteristic
           Y        GATT\_NO\_SERVICE\_CHANGED      Used to exclude service changed characteristic from GATT Service
           Y        HEAPMGR\_METRICS                Defining this will enable heap profiling.
           N        ICALL\_EVENTS                   This define is used with ICALL - do not modify
           N        ICALL\_JT                       This define is used with ICALL - do not modify
           N        ICALL\_LITE                     This define is used with ICALL - do not modify
           Y        L2CAP\_COC\_CFG                 Enable L2CAP Connection Oriented Channels
           Y        OBSERVER\_CFG                   Used to include the GAP Observer Role support
           Y        PERIPHERAL\_CFG                 Used to include the GAP Peripheral Role support
           Y        BROADCASTER\_CFG                Used to include the GAP Broadcaster Role support
           Y        CENTRAL\_CFG                    Used to include the GAP Central Role support
           N        STACK\_LIBRARY                  Build/Use the build configuration where the stack is built as a library
           N        USE\_ICALL                      This define is used with ICALL - do not modify
    =============== =============================== ===================================================================================================================================================================================================
