Zigbee Router Light Sink Example App
- Introduction
- Hardware Prerequisites
- Software Prerequisites
- Functional Description
- Configuration With SysConfig
- Example Usage
Introduction
This document discusses how to use the Zigbee Light Sink Example App and the different parts that compose it. Zigbee Light Sink Application is an example which exercises different features of TI Z-Stack. This example has the same behavior as the Zigbee Light but with addition of Green Power (GP) Sink functionality to process Green Power Device Switch commands.
Some of the features exercised include:
- Base Device Behavior attribute configuration.
- Green Power Sink functionality enabled for a light application.
- Light device that acts as Target of Finding and Binding.
- Optional cluster implementations such as _Level Control_ Cluster.
- Reportable Attributes.
Hardware Prerequisites
- The Launchpad which is used by this particular project.
Software Prerequisites
Code Composer Studio™ (CCS) v9.1 or newer
Functional Description
Software Overview
This section describes the software components and the corresponding source files.
Application Files
- zcl_samplelight.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 light specific logic.
- zcl_samplelight_data.c: Contains the endpoint, cluster and attribute definitions for this sample application. The optional _Level Control_ cluster is also defined in these files.
- 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 zclSampleLight_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 the commissioning process.BTN-2
: If hold after reset, perform Factory New reset (erase network and application persistent data)
LEDs
DIO6
: Is set to On when the Light is On, Off otherwise.
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 COM port can be determined via Device Manager in Windows or via
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 the Green Power Device Switch Example App
Once the Light Sink and another routing device are in the same network, put the Light Sink in GP Commissioning Mode from the App Menu in the Green Power Sink Commissioning Screen. Executing this screen will change the GPS Commissioning status from 'DISABLED' to 'ENABLED'
Once the GP commissioning mode is disabled, sending the On/Off GPDF with the Green Power Device Switch will toggle the Light Sink LED and the Application status line will be updated accordingly.
NOTE: If the LED is not toggled just repeat the commissioning process and try again.
Interfacing with the Switch Example App
Once the Light and Switch 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 Light device be set in Identify mode for 180 seconds. During this time the Switch device must perform Finding and Binding as well to find the Light device in Identify mode and create a bind to it. The status of the Identify process is shown in the BDB status line.
Finding and binding status in the BDB status line
IdXXX shows the remaining XXX seconds in Identify mode, SrchYYY/ZZ shows the remaining YYY seconds searching for devices in Identify mode and ZZ the number of binds created during this process. Once the Switch device has the bind, it will be able to toggle the Light in the Toggle Light screen.
Light device will set IdXXX, while Switch device will set SrcYYY and count the binds in ZZ. Multiple devices can perform this procedure at the same time, by default up to 4 lights can be binded to a single Switch (defined by NWK_MAX_BINDING_ENTRIES). There is no limit on the number of Switches that can control a single Light.
Enter into App Menu to access to application specific application controls.
Application menu entrance screen
The local Light can be Toggled in the Toggle Screen. This can be done in the Light device to Toggle the Light locally, or can be done remotely by Switch device. The state of the Light will be displayed on the Application Status line
Toggle light menu and Light state in App Status line
The light device can also report its light state if it creates a bind to another device. SampleLight and Switch provide a Discover mechanism to allow a Light device create a bind to a Switch to illustrate this.
- In the App Menu of the switch device go to the Discover screen and execute it, it will set the switch in identify mode.
- In the App Menu of the Light device go to the Discover screen and execute it, that will make Light device to send an Identify Query request.
Discover menu
When Switch devices responds to this query, the Light device will discover the missing information from the responding device to create the bind, after which it will start sending reports when the light state changes or periodically every 10 seconds.