Zigbee Router Control and Indicating Equipment (CIE)

Introduction

This document discusses how to use the Zigbee CIE Example App and the different parts that compose it. Zigbee CIE Application is an example which exercises different features of TI Z-Stack.

Some of the features exercised include:

Hardware Prerequisites

Software Prerequisites

Functional Description

Software Overview

This section describes the software components and the corresponding source files.

Application Files

Configuration With SysConfig

SysConfig is a GUI configuration tool that allows for TI driver and stack configurations.

To configure using SysConfig, import the SysConfig-enabled project into CCS. Double click the *.syscfg file from the CCS project explorer, where * is the name of the example project. The SysConfig GUI window will appear, where Zigbee stack and TI driver configurations can be adjusted. These settings will be reflected in the generated files.

The example project comes with working default settings for SysConfig. For the purposes of this README, it is not recommended to change the default driver settings, as any changes may impact the functionality of the example. The Zigbee stack settings may be changed as required for your use case.

Note that some Z-Stack settings are stored in non-volatile storage, and Z-Stack prioritizes stored settings over SysConfig settings. To guarantee SysConfig settings are applied, perform a factory reset of the device to clear non-volatile storage.

Example Usage

This section describes how to use this sample application.

Buttons

LEDs

Serial interface

The connection will have the following settings:

    Baud-rate:     115200
    Data bits:          8
    Stop bits:          1
    Parity:          None
    Flow Control:    None

Note: The serial output is known to be formatted incorrectly in Tera Term and in the CCS Terminal.

The serial interface allows you to control the commissioning configuration as well as application behavior. The commissioning interface is common for all applications and is implemented in the module zcl_sampleapps_ui.c/.h. Any application specific behavior of the serial interface is implemented in the example application files.

The serial interface implements a common set of menus described in 'Application Overview' within the Zigbee docs in this SDK. This common menu can be used to commission the device into a network.

Commissioning the Device Into the Network

Zigbee router devices can create a network with limited security capabilities (Distributed network) or join a network. The commissioning process to be done can be configured in the Config screen menu. Note that if both Formation Mode and Steering Mode are enabled when Commissioning is executed, the device will first try to join a network, after which if it fails, the device will create its own network. This sample application uses the stack notifications (zstackmsg_CmdIDs_BDB_NOTIFICATION) on a successful network formation process to open the network and allow new devices join, even if the Steering Mode is not enabled from the common user interface. In the same way, if the device joins a network, it will open the network for 180 seconds. If the network is closed, it can be opened again by enabling the Steering Mode and execute the commissioning process in the Commissioning Screen.

Interfacing with Warning and Zone example Apps

CIE sample application is meant to interact with other Intruder Alarm System (IAS) devices, for which it uses the following IAS clusters:

Cluster as client Purpose of the cluster
IAS Warning device Works as an interface to a Warning device to issue warning indications that trigger sirens, strobes, lights, etc. at the warning device.
IAS Zone Performs enrollment of devices from which the CIE will receive notifications. Those notifications depend on the Zone device type; this sample app processes fire detector alarms only (see zclSampleCIE_ChangeNotificationCB).

CIE sample application illustrates the usage of these two clusters when interacting with either Zone Device or Warning Device.

Cluster as server Purpose of the cluster
IAS ACE Interface to manipulate the IAS System. Eg. Trigger an alarm, bypass an alarm, retrieve status, etc.

While currently there is no ACE sample application to interact with, Z-Stack provides the full ACE commands API and callbacks to process all commands and responses for this cluster (see zcl_ss.c/.h).

Commissioning of Zone Cluster

The CIE sample application has a simple enrollment process for devices which have Zone Cluster as server (such as Zone and Warning sample apps), which consists of verifying if any joining device has the Zone Cluster listed as server in any of its endpoints. There are two unique steps required in the commissioning of the Zone Cluster that differ from commissioning of other clusters:

  1. The IAS Zone Client (CIE) should perform service discovery when new devices join the network, in order to determine if the device supports the IAS Zone Server cluster. After a CIE has determined that another device supports the IAS Zone Server, the CIE SHALL send a CIE IEEE Addr Write Attribute Req to the IAS Zone Server. Per the ZCL spec, the IAS Zone Server is required to have the CIE's IEEE Addr to perform Zone Enrollment, and the IAS Zone Server is not allowed to request the CIE IEEE Addr itself as a security measure, it must be initiated by the CIE. In this CIE sample application, there are three methods by which this process can occur:

    1. When a CIE receives a zstackmsg_CmdIDs_ZDO_DEVICE_ANNOUNCE, it will start to perform service discovery of the new device.

    2. When BDB Finding & Binding is initiated on both devices, if a CIE is acting as an Identify initiator and a target device is acting as an Identify target, the CIE will perform service discovey of the new device upon receiving the zclSampleCIE_IdentifyQueryRspCB().

    3. The CIE and the target device may manually enable Identify initiator + Identify target via the "Discover" application menus.

    The service discovery procedure starts by sending a unicast ZDO Match Descriptor Request (Zstackapi_ZdoMatchDescReq()) to the remote device with the IAS Zone Server cluster as the target. If the remote device responds with a match (in zstackmsg_CmdIDs_ZDO_MATCH_DESC_RSP), the CIE will then send a CIE IEEE Addr Write Attribute Req.

  2. After the CIE IEEE Addr has been written to the IAS Zone Server, the IAS Zone Server may perform Zone Enrollment via the Trip-To-Pair or Auto-Enroll-Request methods. Once a Zone Enroll Request is sent from the IAS Zone Server to the CIE, ZCL on the CIE will process the command and send a response, and the CIE application will receive callback via zclSampleCIE_EnrollRequestCB(). Once a Zone device is enrolled, it is ready to send a Zone Status Change Notification indicating any condition on it such as fire detection, low battery, etc.

CIE sample application supports Trip-To-Pair and Auto-Enroll-Request enrollment methods defined by ZCL specification v7. Please refer to the specification for further details on these enrollment methods.

Creating binds with Warning device

Once CIE and Warning device are in the same network, enable the Finding and Binding Mode and execute it from the Commissioning Screen. When Finding and Binding is executed, the Warning device will be set in Identify mode for 180 seconds. During this time the CIE device must perform Finding and Binding as well to find the Warning device in Identify mode and create a bind to it. The status of the Identify process is shown in the BDB status line.

FindingBinding

NOTE: Since both devices are Initiator and Target due to the clusters implemented in these applications, both devices will create binds to each other using this Base Device Behavior commissioning method. The Warning device bind will be created for the Zone Cluster and CIE will create its bind for WD Cluster.

CIE device will use the bind table to send Start Warning commands to Warning devices indicating any alarms received from Zone Status Change Notification from the Zone devices.

Discovery Zone Devices

As the CIE commissioning process cannot ensure that all zone devices are process during joining, a discovery Zone devices method is provided in the App Menu. To discover Zone devices follow these steps in the CIE and Zone device:

  1. In Zone's App Menu go to the Discover CIE screen. From here you can enable or disable Identify mode on the Zone.
  2. In CIE's App Menu go to the Discover Zone screen and execute it. This will discover the Zone device and will trigger sending a Match Descriptor Request to the Zone device. The process will keep the flow as in "Commissioning of Zone Cluster" described in the previous section, when zstackmsg_CmdIDs_ZDO_MATCH_DESC_RSP is received.

AppMenu

Application menu entrance screen

DiscoverableScreen

Discover screen

Application menu

This application menu has 3 screens: Send Squawk, Manual Zone Discovery, and Service Discovery Configuration.

  1. The Squawk Screen can be used to send a Squawk to all binded Warning device by pressing Enter while on the screen:

    SEND-SQUAWK.png

  2. The Manual Discovery screen is explained more in the previous section.

  3. The Service Discovery Configuration screen can be used to disable automatic Match Descriptors being sent to devices which have newly joined the network. This may be useful if you are joining devices to the network which do not have the IAS Zone Cluster.

    SEND-SQUAWK.png

This application also has a status line which shows the last event happened on relation to the Zone Cluster such as Zone Device added or the process of any zclSampleCIE_ChangeNotificationCB

LAST-ZONE-EVENT.png