.. |ZB_USERS_GUIDE| replace:: :docs_root:`Zigbee User's Guide <zigbee/zigbee-users-guide.html>`
.. |ZB_ZCLIGHT_README| replace:: :docs_root:`Light Coordinator Example <../examples/rtos/LP_EM_CC2340R53/zigbee/onoff_light/README.html>`
.. |ZB_ZEDSW_README| replace:: :docs_root:`Switch End Device Example <../examples/rtos/LP_EM_CC2340R53/zigbee/onoff_switch/README.html>`

.. _quick-start-zigbee:

|ZBOSS_STACK| Quick Start Guide
********************************

This section serves as a roadmap for users developing applications and products
using the TI SimpleLink\ |trade| |DEVICE| Wireless MCU platform using |ZBOSS_STACK|.
Whether a seasoned developer or just getting started, TI has created a variety
of resources to simplify development on the |DEVICE| platform. These resources
will enhance your experience with the |ZBOSS_STACK| software from the
example applications to production. 

Below are resources which developers should be aware of:

#.  |ZB_USERS_GUIDE| is a detailed description of TI's Zigbee stack solution.
#.  |SLA| are extensive guides for learning more about developing with the Zigbee stack.
#.  |ZB_ZCLIGHT_README| and |ZB_ZEDSW_README| READMEs, among others, provide 
    descriptions of the out-of-box Zigbee examples.
#.  `E2E Forum <https://e2e.ti.com/>`_ is a support community providing answers 
    to questions relating to the |ZBOSS_STACK| and the |DEVICE|.

.. _quick-start-zigbee-ccs:

Using |ZBOSS_STACK| Projects with CCS
======================================

Importing |ZBOSS_STACK| projects into CCS will also import a ``README.html`` that
details the example application design, steps on running the example, and how
each example works.

.. No OAD ZBOSS examples at the moment

    Projects that contain Zigbee over-the-air (OTA) upgrade will also 
    import the Boot Image Manager (BIM) into the workspace. For more information on OTA 
    and the BIM see the |ZB_USERS_GUIDE|.

For more details on |ZBOSS_STACK| example applications please see the 
*Application Overview* section of the |ZB_USERS_GUIDE|.

Import Project Using Resource Explorer
--------------------------------------

A quick and easy way to start working with the SDK is to use the TI Resource 
Explorer in CCS.

This section describes how to import and build an existing project and
references the onoff_light project. All of |ZBOSS_STACK| projects included
in the development kit have a similar structure.

#. Open the CCS IDE from the Start Menu.
#. Create a workspace.

.. attention::

    Ensure that the CCS workspace path does not contain a whitespace.

#. Import a CCS Project using Resource Explorer

-   Open Resource Explorer (if not open already) **View** |rarr| **Resource
    Explorer** |rarr| Software |rarr| |SDK| |rarr| Examples |rarr|
    Development Tools |rarr| |DEVICE| LaunchPad |rarr| Z-Stack |rarr|
    onoff_light |rarr| TI-RTOS |rarr| CCS Compiler |rarr| onoff_light

#.  Select the CCS Logo button to import project into Project Explorer

.. attention::

    The import process will also install the |SDK| if a local version does
    not exist. You must accept the End User License Agreement to proceeed.

    .. _fig-zstack-resource-explorer-eula:
    .. figure:: resources/eula.png
        :align: center

        Install |SDK|

    After the installation finishes, you must reopen CCS before importing
    the project.

- If everything is successful, the project should appear in Resource
Explorer.

Import Project Using Import Wizard
----------------------------------

#. Open CCS
#. Choose **Project** |rarr| **Import** CCS Projects from the menu.
#. Select the Browse button in the Import CCS Projects dialog and select the the directory
   ``<SDK_INSTALL_DIR>/examples/rtos/<LAUNCHPAD>/zigbee``

    .. _fig-zigbee-ccs-import-wizard:
    .. figure:: resources/tidrivers/ccs-import-wizard.jpg
        :align: center

        CCS Import Wizard

#. CCS will automatically discover compatible examples.
#. Select the |ZBOSS_STACK| Example Project you would like to use. In this example,
   |ZB_ZCLIGHT_README| is chosen. Click Finish to import the onoff_light project.

Build and Download Project
--------------------------

.. note::
    The |DEVICEHIGH| has a new Hardware Security Module (HSM) that requires 
    firmware to be flashed **after** a project flashed with a valid CCFG and 
    SCFG. This process will have to be followed after every mass chip erase 
    without retaining protoected sectors. This is not required for |DEVICELOW|.

#. Build the onoff_light project.

    - Set the onoff_light project as the active project. Make sure the Debug project
      configuration is used.
    - Select **Project** |rarr| **Rebuild** to build the project.

#. Set to erase all Flash memory

    - Navigate to **Project** |rarr| **Properties** |rarr| **Debug** |rarr| 
      **Flash Settings** and select *Chip Erase* under 
      *Erase Settings during Program Load*
    - This will ensure the NV memory from previous project builds is reset.
    
#. Load the onoff_light project onto the device

    - Select **Run** |rarr| **Debug** to download the onoff_light application.
    - Once the debugging session starts, click the red stop button

#. Flash the HSM firmware 

    - Open UniFlash (see release notes for version information) 
    - Select the correct |DEVICEHIGH| device
    - Select **Settings & Utilities** and go to the **HSM Image** section
    - Enter the path to the HSM binary
        - This will be located <sdk root>/bin/HSM. 
    - Press **Program HSM Image**

.. note::
    You only need to program the HSM once unless a mass chip erase without 
    retaining sectors occurs. In this case go through the process above again.
        
.. No UART UI enabled

    Before beginning execution, open a **PuTTY** terminal window with the following settings:

    +-----------------+-----------------+
    | UART Param      | Default Values  |
    +=================+=================+
    | Baud Rate       | 115200          |
    +-----------------+-----------------+
    | Data length     | 8 bits          |
    +-----------------+-----------------+
    | Parity          | None            |
    +-----------------+-----------------+
    | Stop bits       | 1 bit           |
    +-----------------+-----------------+
    | Flow Control    | None            |
    +-----------------+-----------------+
        
When the debugging session opens, click the Green start button to start
execution. Be aware that this will begin commissioning automatically on the 
Zigbee node.  Continue on to the ``README.html`` for information about using the
example application.

.. _sec-useful-ccs-settings:

Useful CCS IDE Settings
-----------------------

The CCS provides a large number of configurable settings that can be used to
customize the IDE and individual projects. The following examples do not alter
the generated program code, but they can improve the developer's experience
when working with CCS projects. The CCS can reduce project compilation time by
taking advantage of multiple processor cores on the development computer.

To use this feature, navigate to **Project** |rarr| **Properties** |rarr| 
**Build** |rarr| **Builder** and select Enable parallel build, as shown in 
:numref:`fig-properties-light`.

.. _fig-properties-light:
.. figure:: resources/zigbee/fig-properties-onoff-light.png
    :align: center

    Project Properties for onoff_light

Decreasing the **Build** |rarr| **ARM Compiler** |rarr| **Optimization** level to 
*Interprocedure* will also reduce compile times but may increase the code
flash requirements.  CCS users can control the amount of information that is 
displayed in the Console portion of the screen during project compilation and 
linking, ranging from *Verbose* to *Super quiet*. To change this setting, navigate 
to **Window** |rarr| **Preferences** |rarr| **Code Composer Studio** |rarr| **Build** 
and select an entry from the Console verbosity level drop-down, as shown in
:numref:`fig-ccs-console-verbosity`

.. _fig-ccs-console-verbosity:
.. figure:: resources/zigbee/fig-ccs-console-verbosity.png
    :align: center

    Console Verbosity Level Preferences

.. _sec-accessing-preprocessor-symbols-ccs:


Accessing Preprocessor Symbols
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Throughout this document and in the source code, various C preprocessor symbols
may need to be defined or modified at the project level. Preprocessor symbols
(also known as Predefined Symbols) are used to enable and disable features and
set operational values to be considered when the program is compiled. The
preprocessor symbols are split between project specific preprocessor symbols
and configuration header preprocessor symbols.

.. _sec-configuration-preprocessor-symbols-ccs:

Project Specific Preprocessor Symbols
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Configurations for a given example project are stored in CCS's predefined
symbols setting for that project.

In CCS, preprocessor symbols are accessed in the **Project** |rarr| **Properties**
|rarr| **CCS Build** |rarr| **ARM Compiler** |rarr| **Predefined Symbols**. 
To add, delete, or edit a preprocessor symbol, use one of the icons shown in the 
red box in :numref:`fig-ccs-predefined-symbols`.

.. _fig-ccs-predefined-symbols:
.. figure:: resources/zigbee/fig-ccs-predefined-onoff-symbols.png
    :align: center

    Predefined Symbols Pane

A description of preprocessor symbols which can be added or removed is covered
in the |ZB_USERS_GUIDE|: *Developing Zigbee Applications* section.

Other compile options taken from preinclude header files can be accessed by 
opening the appropriate Project Properties.  Right click on the project in the 
Project Explorer and selecting **Properties**, then navigating to **CCS Build** 
|rarr| **ARM Compiler** |rarr| **Include Options**. To add, delete, or edit a
preincluded files, use one of the icons shown in the red box in
:numref:`fig-ccs-preincluded-files`.

.. _fig-ccs-preincluded-files:
.. figure:: resources/zigbee/fig-ccs-preincluded-onoff-files.png
    :align: center

    Include Options Pane

.. ZBOSS IAR examples are not available yet (if ever)

    .. _quick-start-zstack-iar:        

    Using |ZBOSS_STACK| Projects with IAR
    ======================================

    When building with IAR, it is recommended to enable all build messages. This
    can be done by right-clicking in the Build window and selecting "All" as shown
    below:

        .. _fig-zstack-iar-enable-build-messages:
        .. figure:: resources/iar_enable_build_messages.png
            :align: center

            Enable All Build Messages

    Before starting to work with any of the |ZBOSS_STACK| projects in the SDK, you need
    to load a set of variables that will be set for your current workspace.

    1. Select Tools -> Configure Custom Argument Variables

        .. _fig-zstack-iar-configure-argvars:
        .. figure:: resources/iar-configure-argvars.jpg
            :align: center

            Configure Custom Argument Variables

    2. Select the Global tab, then click Import..

        .. _fig-zstack-iar-import-argvars:
        .. figure:: resources/iar-import-argvars.jpg
            :align: center

            Import Global Argument Variables

    3. Import the custom argvars from the SDK. The argvars are stored in a SIMPLELINK_LOWPOWER_F3_SDK.custom_argvars file, which is located in the
    tools/iar directory of the SDK
    (``<SDK_INSTALL_PATH>/tools/iar/SIMPLELINK_LOWPOWER_F3_SDK.custom_argvars``)

        .. _fig-zstack-iar-custom-argvars:
        .. figure:: resources/iar-custom-argvars.jpg
            :align: center

            Custom Argvars Location

    4. You can open
    (``<SDK_INSTALL_PATH>/tools/iar/SIMPLELINK_LOWPOWER_F3_SDK.custom_argvars``)
    in a text editor if you need to modify the default path argument variables.

        .. _fig-zstack-iar-default-argvars:
        .. figure:: resources/iar-default-argvars.jpg
            :align: center

            Default Path Argument Variables

    5. Restart IAR

    Import Project Using Workspace
    ------------------------------
    This section describes how to open and build an existing project and references
    the onoff_light project. 

    #. Open the IAR Embedded Workbench IDE from the Start Menu.
    #. Open an IAR workspace project: **File** |rarr| **Open** |rarr| **Workspace**
    and select <SDK\_INSTALL\_DIR>\\examples\\rtos\\\ *DEVICE* \ \_LAUNCHXL\\zstack\\onoff_light\\tirtos\\iar\\onoff_light\_\ *DEVICE* \ .eww

        .. note:: After selecting, IAR will open a workspace from a template and save
            it in a new folder.  It is important to create this IAR workspace folder directly
            inside the <SDK\_INSTALL\_DIR> in order for the project to build properly.  Do
            not use spaces in the folder name.

    This workspace file is for the onoff_light project. When selected, the
    files associated with the workspace become visible in the Workspace pane on the
    left side of the screen.

    .. _sec-compiling-linking-iar:

    Build and Download Project
    --------------------------

    #. Build the onoff_light project.

        - Set the onoff_light project as the active project. Make sure the Debug project
        configuration is used.
        - Select **Project** |rarr| **Make** to build the project.

    #. Erase all Flash memory

        - Navigate to **Project** |rarr| **Download** |rarr| **Erase memory**
        - This will delete the NV memory from previous project builds.
        
    #. Load the onoff_light project

        - First choose **Project** |rarr| **Options** |rarr| **Runtime Checking** |rarr|
        **Debugger** |rarr| **Driver** from **Emulator** to **TI XDS** if debugging
        with **Project** |rarr| **Download and Debug**
        - To download without debugging: Select **Project** |rarr| **Download** |rarr|
        **Download Active Application**
        - When the download process is complete, you will see a message that the
        .out file was downloaded to flash memory in the Debug Log. 

    Before beginning execution, open a **PuTTY** terminal window with the following settings:

    +-----------------+-----------------+
    | UART Param      | Default Values  |
    +=================+=================+
    | Baud Rate       | 115200          |
    +-----------------+-----------------+
    | Data length     | 8 bits          |
    +-----------------+-----------------+
    | Parity          | None            |
    +-----------------+-----------------+
    | Stop bits       | 1 bit           |
    +-----------------+-----------------+
    | Flow Control    | None            |
    +-----------------+-----------------+
        
    When the debugging session opens, click the start button to start execution.
    See the ``README.html`` for information about using the example application.


    Useful IAR IDE Settings
    -----------------------

    .. _sec-accessing-preprocessor-symbols-iar:


    Accessing Preprocessor Symbols
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Throughout this document and in the source code, various C preprocessor symbols
    may need to be defined or modified at the project level. Preprocessor symbols
    (also known as Predefined Symbols) are used to enable and disable features and
    set operational values to be considered when the program is compiled. The
    preprocessor symbols are split between project specific preprocessor symbols
    and configuration header preprocessor symbols.

    .. _sec-configuration-preprocessor-symbols-iar:

    Project Specific Preprocessor Symbols
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Configurations for a given example project are stored in IAR's *Extra Options*
    in the *Project Options* menu for that project. These are accessed by opening 
    the project options by going **Project** |rarr| **Options**, in the options pane, go to
    **C/C++ Compiler** in the **Extra Options** tab as shown in 
    :numref:`fig-iar-extra-options-symbols`.

    .. _fig-iar-extra-options-symbols:
    .. figure:: resources/zigbee/fig-iar-extra-options-symbols.png
        :align: center

        Extra Options to Define Preprocessor Symbols

    The preprocessor symbols are added in a new line and are preceded by `-D`.  For example:
    to add the compile flag *ZCL_READ*, ``-DZCL_READ`` must be added as an extra option.

    A list of the preprocessor symbols which can be added or removed is located in
    |ZB_USERS_GUIDE|: *Developing Zigbee Applications* |rarr| *Application Overview*

    The precompile files can be accessed by the same way as the preprocessor symbols in 
    :numref:`fig-iar-extra-options-symbols`

.. _quick-start-demo:

Running the Demo
================

The **Light & Switch Example** refers to the example applications
included as part of the |ZBOSS_STACK|. This is the first place where developers
new to |ZBOSS_STACK| should start. These examples help developers to quickly get 
familiar with |ZBOSS_STACK| and with development tools such as CCS. 

The |ZBOSS_STACK| example applications can be modified, built, downloaded, and
debugged from the desktop version of CCS. With the **Light & Switch** Example running on two separate
LaunchPads, you can quickly create a Zigbee network. The first LaunchPad\ |trade| will
run the |ZB_ZCLIGHT_README|. The second LaunchPad will run the |ZB_ZEDSW_README|.
With this configuration, the switch will control the light.

Use CCS to import and build the two example applications. 
See :ref:`quick-start-zigbee-ccs` for instructions on importing, compiling and building
|ZBOSS_STACK| examples. Refer to the example readmes referenced above for instructions
on running the example applications. To view all
example application readmes, refer to the |ZB_USERS_GUIDE|.

.. _quick-start-learn:

Learning more about |ZBOSS_STACK|
==================================

|SLA| contains Zigbee modules to help users learn the fundamentals of |ZBOSS_STACK| and how
to develop a custom Zigbee product. It also provides a comprehensive set of 
other training tools that allow users from beginners to experienced developers to learn about 
the SimpleLink MCU Platform.

.. _quick-start-develop:

Developing a new |ZBOSS_STACK| Based Application
=================================================

The following develop track is intended for programmers who are ready to start 
developing an end product using the |DEVICE|.  To begin:

#.  **Download and install the SDK**.
    The |SDK| contains the FreeRTOS kernel, peripheral drivers and stacks
    needed with the |ZBOSS_STACK|.

#.  **Begin Development with an Integrated Development Environment (IDE).**
    An IDE can be set up to make it easier to
    browse through the relevant projects and view code. All embedded software
    for the |DEVICE| is developed using TI's Code Composer Studio on a Windows
    7\ |reg| or later PC. To begin development in CCS, jump to:
    :ref:`quick-start-zigbee-ccs`.

#.  **Complete the Project Zero SimpleLink Academy Lab**
    The |ZBOSS_STACK| |SLA| includes a Project Zero Lab which helps introduce
    users to the |SDK| and Zigbee basics through step-by-step instructions for
    programming LaunchPads, setting up a Zigbee Network, and sniffing OTA messages.

#.  **Get Familiar with the Zigbee User's Guide.**
    The |ZB_USERS_GUIDE| is meant to be used alongside the
    |ZBOSS_STACK| when developing an end product. It contains documentation on the
    stack architecture, APIs, and suggestions for developing applications.

#.  **Select an Example Project.**
    |ZBOSS_STACK| includes a basic set of projects to use as a starting point
    for development of your custom application. To view examples applications
    available in |ZBOSS_STACK|, refer to the |ZB_USERS_GUIDE|.

#.  **Troubleshooting Help.**
    While developing your custom application, you may run into issues that
    require the use of packet sniffer software or IDE debugger. 
    The Debugging chapter of the |ZB_USERS_GUIDE| provides
    help with configuring your debugger and understanding common problems while the
    Packet Sniffer chapter explains how to run software for recording OTA activity. 

.. _quick-start-support:

Getting Support
===============

`E2E™ <http://e2e.ti.com/>`_ is a support community providing answers to questions relating 
to the |ZBOSS_STACK| and the |DEVICE|. You can browse questions from other developers or ask your
own questions if you run into issues developing with the |ZBOSS_STACK|.
