.. _sysconfig-zigbee-configuration:

Zigbee Configuration
====================

These instructions cover all Z-Stack sample applications.
Configurables differ between standard Zigbee device types (ie. Coordinator, 
Router, End Device, ZNP) and Green Power Devices (GPD).

.. note::

    SysConfig will only make changes to selected files, listed in the
    *Generated Files* view. Any required changes to your application files 
    must be done on your own.


Open An Example Project
-----------------------

Open the stand-alone SysConfig tool or import a SysConfig-enabled example project 
(found in the ``{SDK_INSTALL_DIR}/examples/rtos/<board>/zstack`` folder) and open the 
``.syscfg`` file with the *System Configuration Editor*.

Zigbee Settings
---------------

In the *RF STACKS* |rarr| *Z-Stack* view, you can configure Zigbee stack parameters.
Parameters are explained in the tooltip that appears when you hover over it but
further explanations are provided in the :ref:`z-stack-overview` and
:ref:`sec-migrate-zigbee-specific` sections.
Zigbee stack settings are stored in ``default/sysconfig/ti_zstack_config.h`` 
(which appears after building the project).

Here is an example of what you would see for a coordinator example:

.. figure:: resources/syscfg_settings_zigbee.png
    :align: center

Device Type and Power Management Configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Standard Zigbee Device**

The *Device Type* (Coordinator, Router, End Device, Network Processor) 
is pre-determined for each example project and cannot be changed.
The *Power Mode of Operation* (see :ref:`z-stack-overview-logical-device-end-device`) 
and multiple poll period (see :ref:`sec-child-management`)
are only configurable for End Device and ZNP projects.

**Green Power Device**

The device type is *Green Power Device*.  The :ref:`sec-gpd-configuration` section
shows all of the definitions which are configured with this project type.  

.. _sysconfig-zigbee-touchlink-configuration:

Touchlink Commissioning Endpoint
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Standard Zigbee Device**

Allows the ability to enable Touchlink Commissioning of a ZED or ZR role for either
the Initiator or Target modes (see :ref:`z-stack-overview-touchlink-commissioning`)

.. _sysconfig-zigbee-radio-configuration:

Radio Configuration
^^^^^^^^^^^^^^^^^^^

**Standard Zigbee Device**

The basic Radio parameters to consider for the Zigbee stack include primary and
secondary channel mask selection (:ref:`z-stack-overview-configuring-channel`).  
This is also where the TX power output can be selected and the internal Power 
Amplifier (PA) is enabled if applicable (:ref:`power-config`).

**Green Power Device**

Configure the channel which the GPD will operate on and the TX power it will use.

Network Configuration
^^^^^^^^^^^^^^^^^^^^^

**Standard Zigbee Device**

The network configurations involve basic Zigbee network settings, such as the PAN ID
(:ref:`z-stack-overview-configuring-pan-id-and-network-joining`), extended PAN ID
(:ref:`extended-pan-id`), default network and TC link keys (:ref:`z-stack-overview-security`),
and End Device Timeout (:ref:`sec-child-management`).  
Joining devices can also select the distributed global link key (:ref:`sec-distributed-security-network`) 
whereas routing devices have a maximum device list option (:ref:`network-config`). Routing devices
can select the number of devices allowed to directly associate and coordinators
can determine the maximum number of TCLK entries stored (:ref:`sec-tc-joining`).

**Green Power Device**

Green Power Device Type determines what function the GPD embodies in the network (eg. switch, temperature sensor, etc).
Green Power Device ID Type determines how the GPD identifies itself (eg. Configurable GPD ID, IEEE address).
If Configurable GPD ID is selected, the developer may choose a 32-bit ID which the GPD will use
(:ref:`sec-green-power-device`).

Security Configuration
^^^^^^^^^^^^^^^^^^^^^^

**Green Power Device**

Security settings which are specific towards Green Power devices, such as level and
key type, and key, which are further discussed in :ref:`sec-green-power-security`.

Advanced Configuration
^^^^^^^^^^^^^^^^^^^^^^

**Standard Zigbee Device**

The advanced configuration parameters require in-depth knowledge of the
Zigbee network operation. They are separated into different sections for joining
(:ref:`z-stack-overview-miscellaneous`), routing
(:ref:`z-stack-overview-routing-protocol`), data polling
(:ref:`z-stack-overview-portable-devices`), packet sending
(:ref:`z-stack-overview-end-toend-ack`), and maximum table sizes
(:ref:`z-stack-overview-network-address-assignment`).  Several of these settings 
are also explained in :ref:`network-config`.

**Green Power Device**

Data Frame Retries determines how many times the GPD will transmit each packet.
Auto-commissioning determines whether the GPD will set the auto-commissioning bit in the packets
(:ref:`sec-green-power-commissioning`). Radio Receive After Transmit determines whether the GPD 
should expect to receive a packet after transmitting. Sequence Number Capability determines 
whether the GPD will use sequential MAC sequence numbers (:ref:`sec-green-power-data-frames`). 

Adjust Your Application
-----------------------

When you have finished adjusting the parameters, save the ``.syscfg`` file.

You can preview the files which will be generated by clicking the ``<>`` symbol. In this example,
``ti_devices_config.c``, ``ti_drivers_config.c/h``, and ``ti_zstack_config.h`` were generated respectively 
by the  *TI DEVICES*, *TI DRIVERS*, and *RF STACKS* |rarr| *Z-Stack* views.

.. figure:: resources/show_generated_zigbee.png
    :align: center

If you are using the System Configuration stand-alone tool, you will have to
import every generated file to your IDE.  For the SysConfig :term:`CCS` plug-in, 
you can generate all the files by building your project. After the build has 
completed, you will find the generated files in the output folder of your project, 
called ``default/syscfg``.  All parameters configured in the Zigbee view of 
SysConfig will result in a \#define in ``ti_zstack_config.h`` alongside other macros 
which are not included in SysConfig.

.. attention::

    Whenever you re-build the project, SysConfig will re-generate the files.
    Because of this, any changes made directly to ``ti_zstack_config.h`` will be overwritten.

.. _sysconfig-zigbee-application-builder:

Application Builder
-------------------

The Zigbee Application Builder is an extension of SysConfig whose 
purpose is to kick-start development of a Zigbee application using TI’s Z-Stack. 
It is designed to save developers time with setting up the specific ZCL characteristics
of the Zigbee application endpoint so that they can quickly begin adding unique 
functionality to the application itself.  

.. note:: Please refer to ZCL Specification documentation from the Zigbee
    Alliance when attempting to determine what qualifications are necessary
    to pass Zigbee endpoint certification.

To start the *SampleApp* example which features the Zigbee Application Builder,
import the following project into CCS or IAR: 
``examples/rtos/<development board>/zstack/<zc/zed/zr>_sampleapp``

The Zigbee Application Builder can be located in SysConfig through *RF STACKS* 
|rarr| *Z-Stack* |rarr| *Zigbee Application Endpoint*.  After building the project,
additional :code:`zcl_config.c/h` files will be created alongside the other
generated files.  These replace the :code:`zcl_sample*_data.c` file that exists
in other Z-Stack example projects.  For instructions on further developing
applications using these generated settings, refer to
:ref:`sec-custom-application-builder-functionality`.

.. figure:: resources/zigbee_application_builder_main.png
    :align: center

.. note:: Currently, it is not possible to add multiple Zigbee Application Endpoints
    in SysConfig.  If a developer wishes to combine two certifiable Zigbee device 
    types into one application, it is recommended that they reference a separate 
    SampleApp project from which the second device type is selected inside the 
    SysConfig Application Builder.  That way the generated :code:`zcl_config.c/h`
    files from this second project can easily be transferred as application files 
    for the first project.  

Application Name and Zigbee Device Type
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The application name must be alphanumeric, starting with a letter, and can include 
spaces.  It is used as a starting point for most of the variables
(ex. :code:`SAMPLEAPP_ENDPOINT`) and functions 
(ex. :code:`sampleApp_ResetAttributesToDefaultValues`) declared in 
:code:`zcl_config.h` and :code:`zcl_config.c`.

The Zigbee device type drop-down menu establishes the default settings for the
other Application Builder SysConfig submodules.  The options provided are common
devices which can be certified with Zigbee 3.0 clusters.  Developers are given
the option to configure additional attributes, commands, or clusters as seen fit
for their application.  By selecting *Generic* it is possible to use a blank
configuration, in which case only the *Basic* and *Identify* server clusters
are used as they are mandatory for certification.  Any further clusters would be
added under the **Additional Clusters** menu.

Mandatory Clusters
^^^^^^^^^^^^^^^^^^

These include the server and client clusters and their corresponding 
attributes/commands required to pass Zigbee endpoint certification.  It is 
therefore highly recommended that no mandatory clusters, attributes, or commands 
be removed.  It is still possible to add 
**Optional Attributes & Commands Generated/Received** to the mandatory clusters 
generated, however these do not need to be supported for certification.

Additional Clusters
^^^^^^^^^^^^^^^^^^^

Additional clusters required for the end application which exist outside of the
default configuration of the *Zigbee Device Type* selected can be added here.  
After a cluster is chosen, the 
**Mandatory/Optional Attributes & Commands Generated/Received** submodules will
appear to allow for further modifications.  There are some optional
additional clusters recommended per device type by the Zigbee Alliance, but these 
do not have to be supported for the device to become certified.

BDB Reporting
^^^^^^^^^^^^^

Whenever a cluster which supports BDB Reporting (ex. *OnOff* or 
*TemperatureMeasurement*) is selected, this submodule appears.
*Max Analog Attribute Size* represents the most bytes for which an analog
attribute can be reported.  This value affects the *Reportable Change* range,
which specifies the minimum amount of change in the attribute's value required
to trigger the sending of a report so long as this event occurs inside the
*Maximum/Minimum Reporting Interval* window.  If the *Minimum Reporting Interval*
time has not yet been surpassed since the last report then the action will be
delayed until this requirement is fulfilled.  The value can be set at *0x0000* to
disable the minimum limit.  If the *Maximum Reporting Interval* time occurs since 
the last report then one will be sent automatically.  If set to *0x0000* then
periodic reporting will be disabled.

.. figure:: resources/zigbee_application_builder_advanced.png
    :align: center

Advanced Settings
^^^^^^^^^^^^^^^^^

*Endpoint* specifies the endpoint used within the node.  *0x00* is not allowed as
it is reserved for the Zigbee Device Object (ZDO) and values between *0xF1* and
*0xFE* are not recommended unless approved by the Zigbee Alliance.  
*Device Version* is a 4-bit value that specifies the version of the device
description supported on this endpoint and *Flags* contain any 
manufacturer-specific values, both of which are displayed in the simple descriptor.

Over-The-Air Upgrade Client Endpoint
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

For developers wishing to build upon the *SampleApp* example to include
over-the-air download capabilities, an *Over-The-Air Upgrade Client Endpoint*
module is also provided inside SysConfig.  This serves the same purpose as the
*Zigbee Application Endpoint* but pertains to the OTA endpoint instead of the
application itself.  Besides enabling functionality through selecting
*OTA Client Enabled*, specific values for *Current File Version* and
*Manufacturer ID* can be configured.  *Type ID* cannot be altered as it is
pre-determined by the project version imported and SimpleLink device being used.  
For further information on integrating OTA into an application, please refer to 
:ref:`sec-adding-client-functionality`.

.. figure:: resources/zigbee_application_builder_ota.png
    :align: center