.. _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.

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

    +-------------------------------------------+------------------------------+------------------------------+------------------------------+
    |                                           | |DEVICE_LOW|                 | |DEVICE_LOW_PLUS|            | |DEVICE_LOW_PLUS_AUTO|       |
    +===========================================+==============================+==============================+==============================+
    | NetWork Processor (NWP) support           | Yes                          | Yes                          | Yes                          |
    +-------------------------------------------+------------------------------+------------------------------+------------------------------+
    | RTOS                                      | FreeRTOS                     | FreeRTOS                     | FreeRTOS                     |
    +-----------------+-------------------------+------------------------------+------------------------------+------------------------------+
    | Bluetooth LE    | Peripheral              | Yes                          | Yes                          | Yes                          |
    | roles           |                         |                              |                              |                              |
    |                 +-------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Broadcaster             | Yes                          | Yes                          | Yes                          |
    |                 |                         |                              |                              |                              |
    |                 +-------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Central                 | No                           | Yes                          | Yes                          |
    |                 |                         |                              |                              |                              |
    |                 +-------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Observer                | No                           | Yes                          | Yes                          |
    |                 |                         |                              |                              |                              |
    |                 +-------------------------+------------------------------+------------------------------+------------------------------+
    |                 | Multi-role              | No                           | Yes                          | Yes                          |
    +-----------------+-------------------------+------------------------------+------------------------------+------------------------------+
    | Security                                  | AES-128, RNG                 | AES-128, RNG                 | AES-128, RNG                 |
    +-------------------------------------------+------------------------------+------------------------------+------------------------------+
    | Maximum Tx Power                          | +8 dBm                       | +8 dBm                       | +8 dBm                       |
    +-----------------+-------------------------+------------------------------+------------------------------+------------------------------+
    |                 |                         |                              |                              |                              |
    | OAD             | on-chip single image    | No                           | Yes                          | Yes                          |
    |                 |                         |                              |                              |                              |
    |                 +-------------------------+------------------------------+------------------------------+------------------------------+
    |                 | on-chip dual image      | No                           | Yes                          | Yes                          |
    |                 |                         |                              |                              |                              |
    |                 +-------------------------+------------------------------+------------------------------+------------------------------+
    |                 | off-chip                | Yes                          | Yes                          | Yes                          |
    |                 |                         |                              |                              |                              |
    +-----------------+-------------------------+------------------------------+------------------------------+------------------------------+
    | Simultaneous connections \*               | 1  *(This value will be      | 8 *(applicable to central,   | 8 *(applicable to central,   |
    |                                           | updated once testing on the  | peripheral and multirole     | peripheral and multirole     |
    |                                           | silicon is completed)*       | roles)*                      | roles)*                      |
    +-------------------------------------------+------------------------------+------------------------------+------------------------------+

\* *The maximum number of Bluetooth LE connections also depends on the
RAM size left by the application.*

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

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


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.
