Software Architecture
=====================

The TI royalty-free Bluetooth Low Energy protocol stack is a software component
in the |DEVICE| SDK for developing single-mode Bluetooth Low Energy (LE)
standalone and network processor applications. This component is based on the
SimpleLink |DEVICE| family of Bluetooth LE enabled wireless MCUs. The |DEVICE|
combines a 2.4-GHz RF transceiver (some wireless MCUs may also contain a
Sub-1GHz transceiver which is not used with Bluetooth LE), in-system
programmable flash memory and SRAM in the |DEVICE|, and a full complement of
peripherals. The |DEVICE| wireless MCU is centered on an Arm\ |reg|
Cortex\ |reg|-M series processor that handles the application layer and
Bluetooth LE protocol stack, as well as low-level radio control and processing
associated with the physical layer (PHY). 

.. warning::
    As |DEVICE| is a mono-core device (i.e. no separate radio core), processing
    inside HWIs and SWIs may impact the timing of scheduled radio commands. TI
    recommends to keep any code executed in HWIs and SWIs short. For example, it
    is advisable to post an event to handle further, potentially lengthy
    processes rather than handle them in the HWI/SWI context.

For more information on the |DEVICE|, see the |TRM|.

The application developer interfaces with the protocol stack through a set of
C APIs (ICall) to implement a Bluetooth Low Energy application. Although
applications can be created using C++, all Bluetooth LE protocol stack APIs must
be accessed through the C context. The rest of this document intends to document
application development on the |DEVICE| using the Bluetooth Low Energy stack.

|STACK| Protocol Stack and Application Configurations
-----------------------------------------------------

The Bluetooth LE stack platform supports two different protocol stack and
application operational configurations:

-   **Single device:** The Bluetooth LE controller, host, profiles, and
    application are all implemented on the wireless MCU as a true single-chip
    solution. This configuration is the simplest and most common when using the
    |DEVICE|. This configuration is used by most of TI's sample projects. This
    configuration is the most cost-effective technique and provides the
    lowest-power performance.

-   **Network processor:** The Bluetooth LE controller and host reside on the
    wireless MCU with the application and profile residing on an external
    application processer (AP). Communication with the wireless MCU occurs over
    a UART or SPI interface using the serialized Network Processor Interface
    (NPI) protocol. Using NPI, the AP controls the network processor with a
    combination of TI Vendor Specific Host Controller Interface (HCI) commands
    and Bluetooth HCI commands. The network processor option is ideal for adding
    Bluetooth LE to an existing non-wireless application. It is important to
    note that the network processor is not a pure HCI LE controller-only
    implementation and the application must use TI Vendor Specific HCI commands
    for Bluetooth LE Host operations.


Solution Platform
-----------------

This section describes the various components that are installed with
|STACKVER| and the directory structure of the protocol stack
and any tools required for development.

:numref:`fig-cc23xx-sw-architecture` shows the |STACK| development system.
Unless otherwise noted, |STACK| applications must be built with components from
this |DEVICE| SDK.

.. _fig-cc23xx-sw-architecture:
.. figure:: resources/fig-cc23xx-sw-architecture.png
    :align: center

    Bluetooth Low Energy Stack Development System

The solution platform includes the following components within the |DEVICE| SDK:

-   **TI Drivers** provides a device register abstraction layer and is used
    by software and Driverlib to control the |DEVICE| at the lowest level.

-   **The Bluetooth Low Energy protocol stack** is provided in library form with
    parts of the protocol stack stored in the |DEVICE|'s flash.

-   **Sample applications and profiles** make starting development Bluetooth LE 
    application using both custom and adopted solutions easier.

The following integrated development environments (IDEs) are
supported:

-  IAR Embedded Workbench for Arm

-  Code Composer Studio™ (CCS) using the TI Clang Compiler

Refer to the SDK release notes for the specific IDE & toolchain versions
supported by this release.

Bluetooth LE Software Architecture
----------------------------------

The |DEVICE| Bluetooth Low Energy software environment consists of the
following parts:

-  An application with the FreeRTOS kernel, TI Drivers, and Bluetooth profile
-  A stack library that implements Bluetooth Low Energy Host and Controller
   protocol

Some examples implement these as two separate projects. In some examples the
stack is prebuilt and linked as library files.

FreeRTOS is an open-source, real-time operating system kernel for embedded
devices. It implements a minimalist set of functions, basic task handling and
memory management. Both the application and Bluetooth Low Energy protocol stack
exist as separate tasks within the RTOS. The Bluetooth Low Energy protocol stack
has the highest priority. A messaging framework called indirect call (ICall) is
used for thread-safe synchronization between the application and stack. It is
mandatory to use FreeRTOS and ICall when developing an application with the
Bluetooth LE Stack.

-   The stack includes the lower layers of the Bluetooth Low Energy protocol
    stack from the Link Layer up to and including the GAP, GATT and
    Security Manager (SM) layers. Most of the Bluetooth Low Energy protocol
    stack code is provided as a library.

-   The application includes the RTOS, profiles/services, application code,
    drivers, and the ICall module.

.. _sec-architecture-single-project-config:

Single Project Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In |STACKVER|, stack is pre-built as a library that is statically linked
to the application. This saves a build step compared to using a stack library
configuration project. See the example project's README file for the available
project build configurations.

Stack library projects have the following properties:

    - Stack provided as pre-build library files
    - Application project will link the stack library files
    - There is no explicit app/stack boundary. The application's link step
      decides the memory locations of the code within the stack library.
    - This architecture saves flash by allowing the linker work more efficiently.
    - These projects used the improved ICall architecture

.. _sec-inc-architecture-standard-project-task-hierarchy:

Standard Project Task Hierarchy
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Bluetooth Low Energy sample applications use the following task priority
structure. A higher task number corresponds to a higher priority task:

-   Priority 5: Bluetooth Low Energy protocol stack task (must be highest
    priority)
-   Priority 2: NPI task (network processor configurations only)
-   Priority 1: Application task (e.g., basic\_ble)

In addition, Software Interrupts (SWIs) are used for RF Driver operations.
Additional tasks may be introduced but the relative priority structure above
must be preserved.

:ref:`sec-freertos-overview` introduces FreeRTOS tasks.
:ref:`sec-ble-stack-overview` describes interfacing with the Bluetooth low
energy protocol stack. :ref:`start-up-in-main` describes the application task.

.. _sec-inc-architecture-working-with-hex-files:

Working With Hex and Binary Files
---------------------------------

|STACK| projects within this SDK are configured to produce an Intel-extended hex
file in their respective output folders. These hex files can be programmed
individually with a compatible flash programming tool, such as UniFlash. To
simplify the flash programming process, you can combine the application with
other Intel-extended hex files into a super hex file manually or using freely
available tools provided the individual hex files lack overlapping memory
regions. Information on the :wikipedia:`Intel Hex standard <Intel_HEX>`.

One method for creating the super hex file is with the IntelHex python script
hex\_merge.py, available at the `IntelHEX Canonical page <https://launchpad.net/intelhex/+download>`_.
To merge the hex files, install Python\ |reg| 2.7.x and add it to your system
path environment variables.

.. warning::

    Note that when using any python script, you must use a compatible version
    of Python. Refer to the tool documentation or contact the developer to
    verify compatibility.

If conversion of the super hex to a binary file is desired, this can be
accomplished with the “hex2bin.py” or similar tools that support the hex
standard.

.. code-block:: console
    :linenos:

    C:\Python27\Scripts>python hex2bin.py \
        basic_ble_super.hex \
        basic_ble_super.bin


Programming Internal Flash with the ROM Bootloader
--------------------------------------------------

The |DEVICE| internal flash memory can be programmed using the bootloader in the
ROM of the device. Both UART and SPI protocols are supported. For more details
on the programming protocol and requirements, see the Bootloader chapter of the
|TRM|.

.. note::
    Because the ROM bootloader uses predefined DIO pins for internal flash
    programming, allocate these pins in the layout of your board. For details on
    the pins allocated to the bootloader based on the chip package type, see
    |TRM|.