.. _sec-ble-stack-overview:

Overview
========

This section describes the functionality of the Bluetooth Low Energy protocol
stack and provides a list of APIs to interface with the protocol stack. The
stack project and its associated files serve to implement the Bluetooth low
energy protocol stack task. This is the highest priority task in the system
and it implements the Bluetooth Low Energy protocol stack as shown in
:numref:`stack_architecture`

Most of the Bluetooth Low Energy protocol stack is object code in a single
library file (TI does not provide the protocol stack source code as a matter
of policy). A developer must understand the functionality of the various
protocol stack layers and how they interact with the application and profiles.
This section explains these layers.

Introduction
------------

.. attention::
    The |DEVICE| platform is still under development and some of the features
    mentioned on this page might not be available yet.
    Make sure to review the release notes of the |SDK| for a complete overview
    of the features currently supported.

|CORESPEC| allows for two systems of wireless
technology: Basic Rate (BR: BR/EDR for Basic Rate/Enhanced Data Rate) and
Bluetooth Low Energy. The Bluetooth Low Energy system was created to transmit
small packets of data, while consuming significantly less power than BR/EDR
devices.

The TI Bluetooth LE Protocol stack supports the following |CORESPEC| features:

-  Periodic Advertising

-  Randomized Advertising Channel Indexing

As well as legacy features from previous versions:

-  2 Msym/s PHY for LE

-  LE Long Range

-  High Duty Cycle Non-Connectable Advertising

-  LE Advertising Extensions

-  LE Channel Selection Algorithm #2

-  LE Secure Connections

-  LE Data Packet Length Extension

-  LE Privacy

-  LE L2CAP Connection-Oriented Channel Support

-  LE Link Layer Topology

-  LE Ping

-  Peripheral Feature Exchange

-  Connection Parameter Request

Platform Devices Comparison
---------------------------

The Bluetooth LE features available to developers depends on the |DEVICE|
platform device selected and its configuration. The tables below
present a comparison of the devices and the features available for each of them.

.. note::
    Within the SDK and related software tools, the CC2340R2 refers to the CC2340R2(1) device
    and the CC2340R5 refers to the CC2340R5(2) device. The precise device names are used
    in the following table.

.. note::
    The |DEVICEHIGH| is still under development and some of the listed
    features may not be supported yet.

.. _cc23xx-device-comparison:
.. table:: Comparison of the |DEVICE| platform devices

    +---------------------------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                                                   | |DEVICE_LOW|                 | |DEVICE_LOW_PLUS_FLASH_DOWN| | |DEVICE_LOW_PLUS|            | |DEVICE_LOW_PLUS_AUTO|       | |DEVICE_LOW_PLUS_RAM_UP|     |  |DEVICEHIGH|                |
    +===================================================+==============================+==============================+==============================+==============================+==============================+==============================+
    | NetWork Processor (NWP) support                   | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |  Yes                         |
    +---------------------------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | RTOS                                              | FreeRTOS                     | FreeRTOS                     | FreeRTOS                     | FreeRTOS                     | FreeRTOS                     |  FreeRTOS                    |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | Bluetooth LE    | Peripheral                      | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |
    | roles           |                                 |                              |                              |                              |                              |                              |                              |
    |                 +---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Broadcaster                     | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    |                 +---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Central                         | No                           | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    |                 +---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Observer                        | No                           | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    |                 +---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Multi-role                      | No                           | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | Security                                          | AES-128, RNG                 | AES-128, RNG                 | AES-128, RNG                 | AES-128, RNG                 | AES-128, RNG                 |  HSM with AES-128 or         |
    |                                                   |                              |                              |                              |                              |                              |  AES-256, ECC, RSA-PKA       |
    |                                                   |                              |                              |                              |                              |                              |  SHA-2, TRNG                 |             
    +---------------------------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | Maximum Tx Power                                  | +8 dBm                       | +8 dBm                       | +8 dBm                       | +8 dBm                       | +8 dBm                       | +20 dBm                      |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    | OAD             | on-chip single image            | No                           | No                           | Yes                          | Yes                          | Yes                          |  Yes                         |
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    |                 +---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 | on-chip dual image              | No                           | No                           | Yes                          | Yes                          | Yes                          |  Yes                         |
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    |                 +---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    |                 | off-chip                        | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          |  Yes                         |
    |                 |                                 |                              |                              |                              |                              |                              |                              |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | Simultaneous Number of Connections \*             | 3 *(peripheral role)*        | 8 *(central and peripheral   | 8 *(central and peripheral   | 8 *(central and peripheral   | 16 *(central and peripheral  |  32 *(central and peripheral |
    |                                                   |                              | roles)*, 5 *(multirole)*     | roles)*, 5 *(multirole)*     | roles)*, 5 *(multirole)*     | roles)*, 5 *(multirole)*     |  roles)*, 5 *(multirole)*    |
    |                                                   |                              |                              |                              |                              |                              |                              |
    |                                                   |                              |                              |                              |                              |                              |                              |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | Simultaneous Number of Bonds *(Privacy            | 3 *(peripheral role)*        | 8 *(central and peripheral   |  50                          |  50                          | 50                           |  50                          |
    | Disable)* \*                                      |                              | roles)*, 5 *(multirole)*     |                              |                              |                              |                              |
    |                                                   |                              |                              |                              |                              |                              |                              |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
    | Simultaneous Number of Bonds *(Privacy            | 3 *(peripheral role)*        | 5 *(central, peripheral, and |  50                          |  50                          | 50                           |  50                          |
    | Enable)* \*                                       |                              | multirole roles)*            |                              |                              |                              |                              |
    |                                                   |                              |                              |                              |                              |                              |                              |
    +-----------------+---------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+
\* *The maximum number of Bluetooth LE connections also depends on the
RAM size left by the application.*

\* |DEVICE_LOW_PLUS_RAM_UP| *successfully supports up to 16 stable connections when operating on a single PHY. However, when changing PHYs during runtime, a stable operation for up to 8 connections has been verified.
Efforts are being done to improve this aspect of our device's performance. For further information on this and other related topics, we encourage you to refer to the "Known Issues" section in our Bluetooth LE Release Notes.*

.. note::
    The CC2340RxxN devices (operating temperature range of -40C to 85C) are binary compatible with the
    with the CC2340RxxE (operating temperature of -40C to 125C) devices. A complete list of these devices may be found below:

    .. table:: CC2340RxxN & CC2340RxxE devices

        +------------------------------+----------------------------------------+----------------------------------------+
        |                              |              CC2340RxxN                |              CC2340RxxE                |
        +==============================+========================================+========================================+
        |                              |                                        |                                        |
        | |DEVICE_LOW_PLUS_FLASH_DOWN| |          CC2340R22N0RKPR               |           CC2340R22E0RKPR              |
        |                              |                                        |                                        |
        +------------------------------+----------------------------------------+----------------------------------------+
        |                              |                                        |                                        |
        | |DEVICE_LOW_PLUS|            |  CC2340R52N0RGER / CC2340R52N0RKPR     |  CC2340R52E0RGER / CC2340R52E0RKPR     |
        |                              |                                        |                                        |
        +------------------------------+----------------------------------------+----------------------------------------+

.. _cc23xx-ble-features-comparison:
.. table:: Comparison of the Bluetooth LE features supported by the |DEVICE| platform devices

    +-------------------+----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    | Core              | Feature              | |DEVICE_LOW|                 | |DEVICE_LOW_PLUS_FLASH_DOWN| | |DEVICE_LOW_PLUS|            | |DEVICE_LOW_PLUS_AUTO|       | |DEVICE_LOW_PLUS_RAM_UP|     | |DEVICEHIGH|           |
    | Specifications    |                      |                              |                              |                              |                              |                              |                        |
    +===================+======================+==============================+==============================+==============================+==============================+==============================+========================+
    | v4.2              | All                  | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    +-------------------+----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    | v5.0              | LE 2M PHY            | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   |                      |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | LE Coded PHY         | No                           | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   |                      |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | LE Advertising       | No                           | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   | Extensions           |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | High Duty Cycle      | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   | Non-Connectable      |                              |                              |                              |                              |                              |                        |
    |                   | Advertising          |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | LE Periodic          | No                           | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   | Advertising          |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | LE Channel Selection | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   | Algorithm #2         |                              |                              |                              |                              |                              |                        |
    +-------------------+----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    | v5.1              | Connection-less      | No                           | Yes - AoA Only               | Yes - AoA Only               | Yes - AoA Only               | Yes - AoA Only               | Yes - AoA Only         |
    |                   | AoA/AoD              |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | Connection-oriented  | No                           | Yes - AoA Only               | Yes - AoA Only               | Yes - AoA Only               | Yes - AoA Only               | Yes - AoA Only         |
    |                   | AoA/AoD              |                              |                              |                              |                              |                              |                        |
    |                   +----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+
    |                   | Advertising Channel  | Yes                          | Yes                          | Yes                          | Yes                          | Yes                          | Yes                    |
    |                   | Index Changes        |                              |                              |                              |                              |                              |                        |
    +-------------------+----------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------------+------------------------+

.. note::
    Support for AoA is planned in a future |device| platform SDK release.

Bluetooth Low Energy Protocol Stack Basics
------------------------------------------

.. _stack_architecture:

.. figure:: resources/image4.jpeg
    :align: center

    Bluetooth Low Energy Protocol Stack.

:numref:`stack_architecture` shows the Bluetooth Low Energy protocol stack architecture.

The Bluetooth Low Energy protocol stack (or protocol stack) consists
of the controller and the host. This separation of controller and
host derives from the implementation of classic Bluetooth BR/EDR
devices, where the two sections are implemented separately. Any
profiles and applications sit on top of the GAP and GATT layers of
the protocol stack.

The physical layer (PHY) can be 1-Mbps (1M), 2-Mbps (2M), 500-kbps (S2)
or 125-kbps (S8)adaptive frequency-hopping GFSK
(Gaussian frequency-shift keying) radio operating in the unlicensed
2.4-GHz ISM (industrial, scientific, and medical) band.

The :ref:`gap` controls the RF state of the device, with the device in one of
five states:

-  Standby

-  Advertising

-  Scanning

-  Initiating

-  Connected

Advertisers transmit data without connecting, while scanners scan
for advertisers. An initiator is a device that responds to an
advertiser with a request to connect. If the advertiser accepts the
connection request, both the advertiser and initiator enter a
connected state. When a device is connected, it connects as either
Central or Peripheral. The device initiating the connection becomes the
Central and the device accepting the request becomes the Peripheral.

See the :ref:`ble_api_reference` for HCI layer API. The HCI layer
provides communication between the host and controller through a standardized
interface. This layer can be implemented either through a software API or by a
hardware interface such as UART or SPI (See :ref:`sec-using-production-test-mode`
for example).
The |CORESPEC| describes Standard HCI commands and events.
TI's proprietary commands and events are specified in the
`TI Vendor Specific HCI Guide`_.

The :ref:`sec-l2cap` layer provides data encapsulation services to the upper
layers, allowing for logical end-to-end communication of data.

The Security Manager layer defines the methods for pairing and
key distribution, and provides functions for the other layers of
the protocol stack to securely connect and exchange data with another device.

The :ref:`gap` layer directly interfaces with the
application and/or profiles, to handle device discovery and
connection-related services for the device. GAP handles the
initiation of security features.

The ATT layer allows a device to expose certain pieces of data
or *attributes*, to another device. The :ref:`gatt` layer is a service
framework that defines the sub-procedures for using ATT. Data
communications that occur between two devices in a Bluetooth Low Energy
connection are handled through GATT sub-procedures. The application
and/or profiles will directly use GATT.
