0011-00-16-04-000 zicm357spx thermostat application note: esi · add any custom files into the...

ZICM357SPx Thermostat Application Note: ESI

ZICM3

57SP

x The

rmos

tat D

emo

App

licati

on N

ote: E

SI

Application Note

1

Introduction

A Smart Energy Network allows the public utility to monitor and notify smart energy devices of potential power outages. Smart Energy devices within the home can reduce their power consumption to aid in avoiding a power outage. For demonstration purposes, our Smart Energy Network consists of an Energy Service Interface (ESI), a Thermostat and a Pump used in radiant floor heating. The ESI device is our link to the utility and it serves as the coordinator for our Smart Energy Network. The Thermostat is a device on our Smart Energy Network and it controls the Pump. The Pump is also a device on our Smart Energy Network and is controlled by the Thermostat through the Home Automation Profile. The Pump, when turned on, will pump hot water through tubing underneath the floor to heat the floor. Since heat rises, the room will warm up.

The public utility can send out messages to the ESI to tell it that energy conservation is needed. The ESI then notifies its devices on the network to reduce the load.

A set of Application Notes is provided describing the ESI, the Thermostat and the Pump Software and their interaction with each other in the Smart Energy Network using the appropriate profiles.

This document describes the ESI Application Note.

Hardware Requirements 1. Ember ISA3 (for downloading) 2. CEL Universal Evaluation Board 3. USB connection to a PC; the PC will run some terminal emulation program for the user to enter commands

Software Requirements 1. Ember Insight Desktop Software, Version 2.5 2. IAR ARM Workbench, Version 6.21 3. Ember Stack, Version 4.6.2 or later

Features 1. Based on the ZigBee™ Smart Energy Profile with the ESI as the device type 2. The device is the coordinator of the network 3. ESI sends DRLC events to the devices in the network to reduce energy consumption 4. Processes provisioning to find out who understands its Smart Energy commands (Note: See Silicon Laboratories Application Development Document, Section 4.4 for additional provisioning methods) 5. Uses Smart Energy Security 6. Fragmentation 7. Interpan 8. Reporting 9. Command Line Interface

0011-00-16-04-000ZICM357SPx Thermostat Application Note: ESI

Smart Energy Network

ESI

Thermostat

Pump

70º 74º

MON TUE WED THUR FRI SAT SUN

HOLD


ZICM357SPx Thermostat Application Note: ESI 2

Creating the DemoThe software is based on the sample software created by the Ember AppBuilder Application that is a part of the Ember Insight Desktop. Some understanding of the Ember Insight Desktop environment, the ZigBee Smart Energy Profile, ZigBee Pro specification and the ZigBee Cluster Library is presumed.

Ember AppBuilder

The ESI Software is created from the Ember AppBuilder Application. Using the appropriate installed stack version, the AppBuilder creates an IAR Project with framework code that supports the ZigBee Smart Energy Profile for an ESI Device. The following steps detail how to create the project:

• Step 1 – Confirm the version of the Ember stack you want to use is installed and the latest version of Ember Insight Desktop is installed. Ember Insight Desktop contains the AppBuilder Application.

• Step 2 – Configure the AppBuilder Software to point to the appropriate Ember stack version. Click the “Add” button to enter the directory where the stack version is installed. Once completed, you will see the stack version appear in the list. See Figure 1 below for a list of the available stacks:



Figure 1



• Step 3 – Select the stack version to use; the ESI Software uses the “EmberZNet 4.6 GA EM35X” stack selection.

• Step 4 – Start configuring the ESI using the AppBuilder. See Figures 3 and 4 for the AppBuilder Software for the Pump Software.

ZigBee Cluster Configuration

The ZigBee device type for an ESI should be a coordinator or router so that the ESI can form the network.

There is only one endpoint: SE (Profile ID = 0x0109) Energy Service Interface (Device ID = 0x0500) as specified in the ZCL device type.

By specifying "SE Energy Service Interface" as the ZCL device type, the appropriate mandatory clusters are automatically selected as shown in Figures 3 and 4 on the following pages.

Figure 2



Figure 3



Figure 4

Each cluster has mandatory attributes and optional attributes. AppBuilder highlights optional attributes with boxes in the attribute table. Column F details the attribute settings that will be saved to the internal flash. Column S details the attributes applied to all endpoints (saving storage space). Column B details the min/max boundaries. For the ESI, only the mandatory attributes are used.

Stack Configuration

The "Smart Energy Security Test" is selected, since the device is part of a Smart Energy Network that is in development mode. The development mode is the debug mode. For production mode, use the "Smart Energy Security Full" with the keys purchased from Certicom.

The specification versions are all the latest versions by default.



Figure 5

The Smart Energy profile specifies the radio channels and they are automatically selected by the AppBuilder. The radio power is selected to the default of 3dBm for the chip.

Set the Extended PAN ID to random and enable ZDO messages for debugging the ZigBee Device Object messages.

Other settings include: enable bindings, enable end device bind, enable receive statistics and concentrator support with Low RAM concentrator. (Note: Not all routers are concentrators. It is recommended to select a few devices to be concentrators as concentrators sends out many to one route requests, which increases traffic to the network. Low RAM concentrators do not store the route table which saves on the RAM.)



HAL Configuration

The HAL configuration is for the CEL Evaluation Board for the EM357 SoC platform with no bootloader.

The Peripherals Configuration has the heartbeat LED disabled and the use of two buttons. One button for commissioning (starting the network) and the second for enabling permit joining.

The Application Serial Port is used for connecting a terminal emulator and is by default on Port1. The Virtual UART is through the ISA3 box for Insight Desktop to open a serial connection.

The GPIO register configuration is per the hardware settings for the CEL Universal Evaluation Board.

Figure 6



Plugins

Silicon Laboratories supplies code that may be used “as is” or with minor changes for certain features. The “as is” code is certifiable. These code samples are called “plugins”. Using a certifiable plugin means you do not need to code in support for the feature. The ESI Software uses the following plugins:

1. Fragmentation (“as is” code, no changes needed) 2. General Response Commands (“as is” code, no changes needed) 3. Interpan (“as is” code, no changes needed) 4. Key Establishment (“as is” code, no changes needed) 5. Messageing Server Cluster (“as is” code, no changes needed) 6. Partner Link Key Exchange (“as is” code, no changes needed) 7. Price Server (“as is” code, no changes needed) 8. Reporting Cluster (“as is” code, no changes needed) 9. Smart Energy Registration (“as is” code, no changes needed) 10. Time Server Cluster (“as is” code, no changes needed)

Certain plugins require support in the form of callbacks where the developer needs to supply code to the hardware or the application specific functions. Those are in the form of “defined callbacks”.

The plugins used that have callbacks needing code are as follows (although the option is to do nothing within the callback and therefore no code is necessary):

1. Interpan Plugin (see Figure 7) 2. Reporting Cluster (see Figure 8)



Figure 7



Figure 8



Figure 9

Callback Configuration

In addition to the “defined callbacks” from the plugins, certain callbacks can be enabled to the application for special handling. Examples include: main init for special hardware initialization or main tick for checking for a button press. The “Callback Configuration” tab lists the available callbacks that can be exposed to the application level for special handling. Some of the callbacks are already used in the plugin and are not exposed. The checked boxes are for the callbacks the ESI Software may use.



Figure 10



Figure 11



Add any custom files into the project creation. The ESI custom file is the mytokens.h file for saving data to the internal flash using Ember’s token system APIs.

• Step 5 – Generating the IAR Project and base source code for modification.

Clicking the “Generate” button creates a list of files and an IAR Project under the directory app\builder\CEL_Demo_ESI_Coordinator for this particular demo code. The directory name comes from the “device name” in the AppBuilder GUI.

Under the app\builder\CEL_Demo_ESI_Coordinator directory, the generated application level source code and IAR Project start with the device name CEL_Demo_ESI_Coordinator.

Figure 12



IAR Project and Modifying Code Once the IAR Project has been created, open the IAR Project (.eww file) to start modifying code. All file changes are limited to the CEL_Demo_ESI_Coordinator_callbacks.c file and any generated .h file. The files that were changed for the ESI Software are as follows:

• app\builder\CEL_Demo_ESI_Coordinator\app\builder\CEL_Demo_ESI_Coordinator\ CEL_Demo_ESI_Coordinator_callback.c • app\builder\CEL_Demo_ESI_Coordinator\app\builder\CEL_Demo_ESI_Coordinator\ CEL_Demo_ESI_Coordinator.h

An additional file that was added in is as follows:

• app\builder\CEL_Demo_ESI_Coordinator\mytoken.h

The majority of the enhancements are within CEL_Demo_ESI_Coordinator_callback.c and the supporting *.h files.

CEL_Demo_ESI_Coordinator.h

This file adds a #define to indicate that the Application is supporting custom CLI Commands. The CEL_Demo_ESI_Coordinator_callbacks.c will have the handler code written for the CLI Commands being used. See Section 11.1 (Extending the Command Line Interface) in Application Framework, Version 2 Developer Guide for more information on how to add custom commands.

#define EMBER_AF_ENABLE_CUSTOM_COMMANDS

CEL_Demo_ESI_Coordinator_callbacks.c

The CEL_Demo_ESI_Coordinator_callbacks.c is the file where all the callbacks reside. Any additional support functions have been added to this file.

The types of callbacks used by the ESI are:

1. Ember Initialization Callbacks – Used by the application for software structure or hardware initialization 2. Ember Stack Callbacks – Used to handle ZigBee application incoming messages, network status or transmit status

Ember Initialization Callbacks

emberAfMainInitCallback()

The callback emberAfMainInitCallback()reads in data saved in the internal flash and populates the software structures. The data saved is: Node ID, 64-bit IEEE address, parent node ID for the various clusters and the nodes that joined through the Thermostat.



Ember Stack Callbacks

The Ember stack can generate three types of callbacks:

1. Send – For the developer to do application specific handling once a message has been sent and the stack has returned the status of the send 2. Stack Status – For the developer to handle any network status condition 3. Incoming Message Received – For the developer to handle the message before it is passed up to the Ember application handling

The ESI Demo only uses the Incoming Message type and the Stack Status type.

Stack Status Callbacks

emberAfStackStatusCallback()

The callback emberAfStackStatusCallback()allows the application to do any special processing based on the stack status. For the ESI, it only handles when the network is down and the ESI is no longer part of any network. It updates the LED to off, clears out the structures and updates the internal flash.

emberAfTrustCenterJoinCallback()

The callback emberAfTrustCenterJoinCallback()indicates that a node has joined the network. Information on that node is passed into this callback for any application level processing, then the node information is saved to the internal flash. There is only one trust center and it also serves as the coordinator. The trust center also gets notified when a node leaves so that the application level processing will clear out the information on the internal flash.

Incoming Message Callbacks

emberAfPreMessageReceivedCallback()

The callback emberAfPreMessageReceivedCallback() allows the application to handle the message before the Ember Application Framework processes it. It handles the Match Descriptor Responses through this callback and adds nodes to the tables for the various clusters. Also handles the Match Descriptor response in the emberAfPreZDOMessageReceivedCallback; showing how to handle incoming messages at various stages of the receive process.

emberAfDemandResponseLoadControlClusterReportCallback()

The callback emberAfDemandResponseLoadControlClusterReportEventStatusCallback()is called when the Ember Application Framework has determined that the incoming message is a DRLC command. This callback allows the Application to do its own processing. It adjusts and prints out the message to indicate that the event is completed.



emberAfDemandResponseLoadControlClusterGetScheduledEventsCallback()

The command emberAfDemandResponseLoadControlClusterGetScheduledEventsCallback()is called when the Ember Application Framework has determined that the incoming message is a DRLC, retrieves the scheduled command and allows the Application to do its own processing. Sends a default response since it is not supported. If it were supported, it would need to get the list of scheduled events and create a response and send it out.

mytoken.h

The mytoken.h file defines the custom structures used in allocating storage in the internal flash. Silicon Laboratories provides APIs for storing data into its internal flash. These are referred to as “tokens”. See Section 8 of the Silicon Laboratories Application Development Fundamentals document for more information.

Command Line Interface (CLI)

CLI Commands are provided to do provisioning, sending and canceling a Shed Load Command. The following support the functions that are called when the CLI Command is executed. The structure to add custom CLI Commands is as follows:

EmberCommandEntry emberAfCustomCommands[]= { {"findSE", discoverDRLC, ""}, {"cool", emAfCliShedLoadCommand, ""}, {"cancel", emAfCliCancelShedLoadCommand, ""}, };

Cancel Shed Load

CLI Command: “custom cancel”

Uses the emAfCliCancelShedLoadCommand()function. This function sends a DRLC cancel message to all nodes supporting the DRLC cluster.

Shed Load

CLI Command: “custom cool”

Uses the emAfCliShedLoadCommand()function. This function sends a DRLC message to all nodes supporting the DRLC cluster.

Provisioning

CLI Command: “custom findSE”

Uses the discoverDRLC()function call. This function initiates the provisioning process by broadcasting out a ZigBee Match Descriptor Command with the DRLC cluster value in its payload. Those that support the DRLC cluster should respond.

California Eastern Laboratories 4590 Patrick Henry DriveSanta Clara, CA 95054(408) 919-2500

Professional Grade Wireless Radio Solutions

www.cel.com19


11.14.2012

Revision History

Revision Date Description Page(s)A

0011-00-16-04-000 11/14/12 Initial Release. N/A

References

Silicon Laboratories

1. 120-3028-000 Application Framework, Version 2 Developer Guide 2. 120-3029-000 Application Development Fundamentals

ZigBee

1. IEEE Standard 802.15.4-2003 2. ZigBee Cluster Library Specification, Revision 3 3. ZigBee Specification, Revision 19 4. ZigBee Smart Energy Profile Specification,Version 1.1, Revision 16

0011-00-16-04-000 zicm357spx thermostat application note: esi · add any custom files into the...

Documents