Zigbee Router Warning Device

• Introduction
• Hardware Prerequisites
• Software Prerequisites
• Functional Description
  • Software Overview
    • Application Files
• Configuration With SysConfig
• Example Usage
  • Buttons
  • Serial Interface
  • Commissioning the Device Into the Network
  • Interfacing with the CIE Example App using Zone Cluster
  • Interfacing with the CIE Example App using Warning Cluster

Introduction

This document discusses how to use the Zigbee Warning Example App and the different parts that compose it. Zigbee Warning Application is an example which exercises different features of TI Z-Stack. This application is an extension to the existing Zone device, as it implements the same clusters plus the Warning cluster, which means that this application has the same logic implemented plus the handling of the Warning cluster.

Some of the features exercised include:

• Base Device Behavior attribute configuration.
• Z-Stack API to manage attribute/binds access and permissions.
• Nv API usage to store application configuration attributes.

Hardware Prerequisites

• The Launchpad which is used by this particular project.
  • SimpleLink™ CC26x2R1 Launchpad
  • SimpleLink™ CC1352P Launchpad
  • SimpleLink™ CC1352R1 Launchpad
  • SimpleLink™ CC2652RB Launchpad
  • SimpleLink™ CC2652RSIP Launchpad

Software Prerequisites

• Code Composer Studio™ (CCS) v10.3 or newer

• SimpleLink™ CC13x2/CC26x2 SDK

Functional Description

Software Overview

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

Application Files

• zcl_samplewarningdevice.c/.h: Contains the application's event loop, device initialization function calls (for timers, peripherals, Nvm, LEDs, Switches, Serial interface), Zigbee stack notifications and all IAS Warning specific logic.
• zcl_samplewarningdevice_data.c: Contains the endpoint, cluster and attribute definitions for this sample application.
• main.c: Defines the application task and the application stack size.
• bdb_interface.h: Defines commissioning parameters to be used and configured in the application upon calling commissioning methods (see zclSampleWarningDevice_initParameters()).

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

• BTN-1: Starts BDB commissioning process.
• BTN-2: If hold after reset, perform Factory New reset (erase network and application persistent data)
• BTN-2: Nothing if not enrolled and no CIE IEEE address is present. Send Enroll Request to CIE if IEEE address is present. Send Change notification toggling between fire alarm and no alarm if Warning Device is enrolled to a CIE.

LEDs

• DIO6: LED1 reflects the status of the fire alarm of the Warning Device by Blinking if there is fire, solid On if the fire is notified by CIE and Off if there is no alarm active.

Serial interface

• Open a serial session (e.g. PuTTY, etc.) to the appropriate COM port.
  • The COM port can be determined via Device Manager in Windows or via ls /dev/tty* in Linux.

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 applications 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 open again by enabling the Steering Mode and execute the commissioning process in the Commissioning Screen.

Interfacing with CIE Example App using Zone Cluster

Upon joining the network, any CIE already present in the network will attempt to write its IEEE address in the Warning Device, after which, the UI or the Button-2 can be used to send an Enroll Request command. This will cause the CIE to issue an Enrollment Response command containing the Zone ID assigned to the Warning Device. This Zone ID will be used when the Warning Device generates a Change Notification.

Once the device is enrolled, the user can send Change notifications toggling between fire alarm and No-Alarm notifications with the UI or by pressing Button-2.

Becoming discoverable to CIE

If the CIE does not write the IEEE address into the Warning Device, the discovery process can be triggered from the App Menu with the Discover CIE screen. To allow Warning Devices to be discovered by CIE, follow these steps in the CIE and Warning Device:

1. In Warning Device's App Menu go to the Discover CIE screen. From here you can enable or disable Identify mode on the Warning Device.
2. In CIE's App Menu go to the Discover Zone screen and execute it. This will discover the Warning Device and will trigger the commissioning method on CIE to write its IEEE address into the Warning Device.

Discover screen

Using the serial UI

Enter into App Menu to access to application specific controls.

Application menu entrance screen.

Inside of the application menu there are 4 screens: Enrollment Mode, Manual Discovery, Send Enroll Request, and Toggle Alarm.

1. The Enrollment Mode screen can be used to change the current Enrollment Mode. Modes supported in this sample application are Trip-To-Pair and Auto Enroll Request.

   

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

3. The Send Enroll Request screen can be used when using the Trip-to-Pair enrollment method. This screen will manually send a Zone Enroll Request to the CIE, if the CIE's IEEE Addr has already been written to the local device.

   

4. The Toggle Alarm screen can be used to change the alarm state of the local device, which will update the Zone Alarmed status line element locally, and it will also send a Zone Change notification to the CIE.

   

This application also has 3 status lines, which displays various information about the current state of the IAS Zone cluster on the local device.

After Zone device joins a network, the CIE IEEE Addr will be populated by the CIE, and then the Zone device may send an Enroll Request to the CIE, after which the status line elements above will be updated appropriately.

The Enrollment status screen summarizes the enrollment status of the Zone device by displaying if the process is completed or not. This screen also displays the type of the Zone (fire alarm for this sample application).

Warning Application considerations (using Zone Cluster)

The Zone Cluster attributes are saved in Nvm whenever those are updated using zclport_writeNV API. The attributes stored in Nvm are zclSampleWarningDevice_ZoneState, zclSampleWarningDevice_CIE_Address, zclSampleWarningDevice_ZoneId. For further details on Nvm API see zcl_port.h. Once the Warning Device has the CIE IEEE address, the CIE address attribute can be changed only by the CIE device. The authentication of any write command to this attribute is done in the callback zclSampleWarningDevice_AuthenticateCIE. In the same way, once the CIE IEEE address is written, the binds to Zone cluster are protected from being changed by a device which is not the CIE. This is done using the API Zstackapi_ZdoSetBindUnbindAuthAddrReq. Once the enrollment is done, the application will also create a bind to CIE using Zstackapi_ZdoBindReq. This allows the Warning application to send the Change Notification request commands using the bind table. NOTE: Since the binds are used to send the notifications to the enrolled CIE device, the developer is encouraged to be careful when using Finding and Binding commissioning process, as it may create unintended binds to other CIE devices.

User interaction to send an Enroll Request is known as Trip-To-Pair enrollment, while waiting 30 seconds for sending it automatically is known as Auto Enroll Request enrollment. Please refer to the Zigbee Cluster Library document for more details on these.

Interfacing with CIE Example App using Warning Cluster

The warning cluster does not require any special commissioning process, as the CIE must send the Start Warning commands. CIE devices usually rely on using binds to send the commands to Warning Devices to indicate any condition in the alarm system, for which the BDB Finding and Binding method can be used. The end user must take care to not trigger Finding and Binding on multiple devices creating unintended binds. Once a CIE device has binds established to a Warning Device, any Change Notification received by the CIE will be sent to the binded Warning Devices with a Start Warning Device command (processed in the application callback zclSampleWarningDevice_StartWarningCB). The Warning Device sample application will turn on LED1 (Solid On) if the notification was triggered by another device and there is no alarm in the local device during the Warning duration indicated by the command (unless it is higher than SAMPLEWARNINGDEVICE_ALARM_MAX_DURATION).

The Start Warning command will also be shown in the serial UI. The Strobe Alarmed status line element will reflect the current state of receiving these commands.

CIE may send a Squawk command to identify the Warning Device, which is processed in zclSampleWarningDevice_SquawkCB and will cause LED1 to blink once, only if there is no Warning or Alarm in progress. If the alarm was generated in the local device, this will overwrite the other warning or squawk LED indications.