Zigbee End Device Door Lock Example App
- Introduction
- Hardware Prerequisites
- Software Prerequisites
- Functional Description
- Configuration With SysConfig
- Example Usage
Introduction
This document discusses how to use the Zigbee Door Lock Example App and the different parts that compose it. Zigbee Door Lock Application is an example which exercises different features of TI Z-Stack.
Some of the features exercised include:
- Base Device Behavior attribute configuration.
- This Door Lock device that acts as Target and Initiator of Finding and Binding.
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_sampledoorlock.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 Door Lock specific logic.
- zcl_sampledoorlock_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 zclSampleDoorLock_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 Door is Locked, 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 end devices can only join networks. This is done using the Steering Mode and executing the commissioning process in the Commissioning Screen. Zigbee end devices must also have a router parent device (this can be either Zigbee Coordinator or Zigbee Router), which is the device that allows it to join. End Devices cannot transmit/receive frames unless these goes through its parent. If an end device lost its parent, then it cannot be active in the network until it finds another suitable parent. This sample application uses stack notifications (zstackmsg_CmdIDs_BDB_NOTIFICATION) to automatically find a new suitable parent if it is lost (unresponsive due to any reason).
Interfacing with the Door Lock Controller Example App
Setup for automatic Attribute reports
Once the Door Lock and Door Lock Controller 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 Door Lock Controller device will be set in Identify mode for 180 seconds. During this time the the Door Lock device must perform Finding and Binding as well to find the Door Lock Controller 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 Door Lock device has the bind, it will be able to send Report Attribute commands periodically according to the reporting configuration.
Door Lock Controller device will set IdXXX, while Door Lock 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 Door Lock Controllers can be binded to a single Door Lock (defined by NWK_MAX_BINDING_ENTRIES). There is no limit on the number of attribute reports that a single Door Lock Controller can receive, but is up to the application how to handle/ignore those.
Setup to control the Door Lock
As Finding and Binding does not create the binds needed in the Door Lock Controller to control the Door Lock, a custom commissioning method is available in the App Menu. To create the bind in the Door Lock Controller follow these steps:
- In Door Lock's App Menu, go to the Discover screen and execute it. This will enable Identify mode in the in Door Lock for 1 minute.
- In Door Lock Controller's App Menu, go to the Discover screen and execute it. This will discover the Door Lock and will create the bind to it.
Application menu entrance screen
Discover screen
Controlling the Door Lock
In the Change PIN screen, the PIN can be changed. Both devices, Door Lock and Door Lock Controller, must have the same PIN in order to lock or unlock the door.
Change PIN screen
The status of the door is displayed in the Door Lock status line. The Doorlock LOCK and UNLOCK App Menu screens can be used to change the local lock state.
LOCK screen and Doorlock Status Line