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

The TI royalty-free |ZIGBEE| protocol stack is a software component in the 
|DEVICE| SDK for developing single-mode Zigbee standalone and network processor 
applications. This component is based on the SimpleLink |DEVICE| family of 
|ZIGBEE| enabled wireless MCUs. The |DEVICE| combines a 2.4-GHz RF transceiver, 
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
|ZIGBEE| 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|.

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

The |STACK| stack platform supports two different protocol stack and
application operational configurations:

-   **Single device:** The |ZIGBEE| applications 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 |ZIGBEE| networking 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 interface using the serialized Network Processor Interface
    (NPI) protocol. Using NPI, the AP controls the network processor with
    |ZIGBEE| commands. The network processor option is ideal for adding
    |ZIGBEE| protocol to an existing non-wireless application.


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

    Zigbee 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 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 |ZIGBEE| 
    application using both custom and adopted solutions easier.

The following integrated development environments (IDEs) are
supported:

.. -  IAR Embedded Workbench for Arm //comment out until included in SDK

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

Zigbee Software Architecture
----------------------------

The |DEVICE| Zigbee software environment consists of the following parts:

-  An application with the FreeRTOS kernel, TI Drivers, and Zigbee profile
-  A |STACK| library that implements Zigbee 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. 

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

.. _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_zigbee_super.hex \
        basic_zigbee_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|.