.. _sysconfig-zigbee-configuration:

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

These instructions cover all Zigbee 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>/zigbee`` 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_zigbee_config.h`` 
(which appears after building the project).

Here is an example of what you would see for an End Device switch example:

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


Generic Zigbee Options
^^^^^^^^^^^^^^^^^^^^^^

**Enable Logging**: Enables logging capability for both the Zigbee application 
and stack.

**Zigbee Pro 3.0 Revision**: Option to choose between the Zigbee PRO 2017 (R22) 
or PRO 2023 (R23) specification

**Enabled Device Types**: The *Device Type* (Coordinator, Router, End Device, 
Green Power Device) can be selected.  Certain combinations are not supported, 
like a ZC plus ZED.

**Enable Green Power Direct Support**: Ability to receive any Green Power frame 
in both direct or tunneled modes.

**Enable use of APIs to Join a Pre-Installed Network**: Allow factory new 
devices to join using pre-installed network parameters using the APIs in 
``zb_bdb_preinst_nwk.h``

Power Management (ZED only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Power Mode of Operation of ZED**: Enabled sleepy or Always-on ZED operation.

**Poll Period**: Frequency of ZED Data Requests to its parent.

.. _sysconfig-zigbee-radio-configuration:

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

**Primary Channels**: Selection of channels for which the Zigbee device forms 
a network or searches for a network to join.

**Transmit Power**: Default transmit power in units of dBm.

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

**Default Network Key**: Set to 0 to generate a random network key

**End Device Timeout**: Time after the latest data poll for which a ZED is 
removed from its parent's association table.

**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 (GPD only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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 (GPD only)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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_zigbee_config.h`` were generated respectively 
by the  *TI DEVICES*, *TI DRIVERS*, and *RF STACKS* |rarr| *Zigbee* views.

.. figure:: resources/show_generated_zboss.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_zigbee_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_zigbee_config.h`` will be overwritten.
