0011-00-16-03-000 zicm357spx thermostat demo application ... · add any custom files into the...

ZICM3

57SP

x The

rmos

tat D

emo

Appli

catio

n Note

: The

rmos

tat

Application Note

ZICM357SPx Thermostat Demo Application Note: Thermostat 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 Thermostat Application Note.

Hardware Requirements 1. CEL Thermostat 2. Ember ISA3 (for downloading) 3. CEL Universal Evaluation Board simulating a Pump (Optional)

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 Energy Service Interface as the device type 2. The device is a router 3. The ESI sends DRLC events to the devices in the network to reduce energy consumption 4. Processes provisioning to find out who understands the Smart Energy DRLC commands and who understands Home Automation On/Off commands (Note: There are many ways to do provisioning; see Section 4.4 of the Silicon Laboratories Application Development document for other provisioning methods) 5. Uses Smart Energy Security 6. Fragmentation 7. Interpan 8. Reporting 9. Push Button State Change (from commissioning to provisioning to leaving the network) 10. LED Status Indicator (indicates state status) 11. Controls the Pump based on temperature 12. E-mode Commissioning (uses push button)

0011-00-16-03-000 ZICM357SPx Thermostat Demo Application Note: Thermostat

Smart Energy Network

ESI

Thermostat

Pump

70º 74º

MON TUE WED THUR FRI SAT SUN

HOLD

ZICM357SPx Thermostat Demo Application Note: Thermostat


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 is needed. Understanding of the ZigBee Smart Energy Profile, ZigBee Home Automation Profile, ZigBee Pro specification and the ZigBee Cluster Library is presumed.

Ember AppBuilder

The Thermostat 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 a Programmable Communicating Thermostat device and a ZigBee Home Automation Pump Controller. 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 Thermostat using the AppBuilder. See Figures 3 and 4 for the AppBuilder Software for the Thermostat.

ZigBee Cluster Configuration

The ZigBee device type for the Thermostat should be a router. The Thermostat will be joining the Smart Energy Network.

There are two endpoints:

• SE (Profile ID = 0x0109) Programmable Communicating Thermostat (Device ID = 0x0503) as specified in the ZCL device type for endpoint 1 • HA (Profile ID = 0x0104) Pump Controller (Device ID = 0x0304) as specified in the ZCL device type for endpoint 2

By specifying SE Programmable Communicating Thermostat (PCT) as the ZCL device type for endpoint 1 (highlighted in gray), the appropriate mandatory clusters are automatically selected as shown in Figures 3 and 4 on the following pages.

Figure 2



Figure 3



Figure 4

To differentiate from endpoint 0, assign endpoint 1 its own configuration name which the AppBuilder uses to remember its settings.

By specifying HA Pump Controller as the ZCL device type for endpoint 1 (highlighted in gray), the appropriate mandatory clusters are automatically selected as shown in Figure 5.



By clicking on the cluster names, the attributes will be displayed in the attribute table on the right. Each cluster has mandatory attributes and optional attributes. The AppBuilder highlights optional attributes with boxes in the attribute table on the right side. Column F details the attribute settings that will be saved to the internal flash. Column S column details the attributes applied to all of the endpoints (saving storage space). Column B details the min/max boundaries. For the Thermostat, 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, use the "Smart Energy Security Full" with the keys purchased from Certicom.

Figure 5



The specification versions are all the latest versions by default.

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 the concentrators send 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).

Figure 6



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; the code for both application buttons is disabled. The application buttons will be used for another purpose.

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 hardware settings for the Thermostat.

Figure 7



Plugins

Silicon Laboratories supplies the code that may be used “as is” or with minor changes for certain features. The “as is” code is certifiable. The code samples are called "plugins". Using a certifiable plugin means you do not need to code in support for the feature. The Thermostat 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. ESI Management (“as is” code, no changes needed) 6. Partner Link Key Exchange (“as is” code, no changes needed) 7. Identify Cluster (requires extending but use “as is” since this cluster is not used for the demo) 8. Reporting Cluster (“as is” code, no changes needed) 9. Smart Energy Registration (“as is” code, no changes needed) 10. Time Client Cluster (“as is” code, no changes needed)

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

The plugins used that have "defined 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 8) 2. Reporting Cluster (see Figure 9) 3. DRLC Cluster Client (see Figure 10)



Figure 8



Figure 9



Figure 10

Extend the plugin using additional callbacks in the “Callback Configuration” tab.

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 Thermostat Software may use. A good rule is if you suspect you may need a callback, enable the callback. Users can leave the callback unpopulated with no code without causing any damage.



Figure 11



Figure 12



Figure 13



Figure 14

Add any custom files into the project creation. The Thermostat 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_Thermostat, for this particular demo code. The directory name comes from the “device name” in the AppBuilder GUI.

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



IAR Project and Modifying CodeOnce 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_Thermostat_callbacks.c file and any generated .h file. Refer to the Silicon Laboratories Application Framework, Version 2 Developer Guide for detailed information on the structure of the software and how the callbacks interact with the software generated.

The files that were changed for the Thermostat Demo are as follows:

• app\builder\CEL_Demo_Thermostat\CEL_Demo_Thermostat.h • app\builder\CEL_Demo_Thermostat\CEL_Demo_Thermostat_callbacks.c

An additional file that was added in is as follows:

• app\builder\CEL_Demo_Thermostat\mytoken.h

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

CEL_Demo_Thermostat.h

This file adds a #define to indicate that the application is supplying the handler for the push button and not the HAL Configuration. The CEL_Demo_Thermostat_callbacks.c will have the handler code written for the buttons being used.

#define EMBER_APPLICATION_HAS_BUTTON_HANDLER 1

CEL_Demo_Thermostat_callbacks.c

The CEL_Demo_Termostat_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 Thermostat are:

1. Ember Initialization Callbacks – Used by the application for the software structure or hardware initialization 2. Ember Application Tick Callback – For the application usage to monitor push buttons or blink LED, etc. 3. Ember Stack Callbacks – Used to handle the ZigBee application incoming messages, network status or transmit status 4. Ember DRLC Event Callback – Notifies application of a DRLC event, the application can then do special handling if needed



Ember Initialization Callbacks

emberAfMainInitCallback()

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

Ember Application Tick Callback

emberAfMainTickCallback()

The callback emberAfMainTickCallback()monitors button presses that are generated by the interrupt service routine. A push button state machine is implemented to handle commissioning and provisioning. The flowchart below details the state flow.

There are three valid states:

1. NO NETWORK – Node has not joined a PAN 2. NWK_PROVISION – Node has joined a PAN, but needs provisioning 3. PROVISION_DONE – Node has been provisioned and can now run the demo

Next valid state for NO NETWORK is NWK_PROVISION.

Next valid state for NWK_PROVISION is PROVISION_DONE.

Figure 15



Provisioning

Provisioning is done by using the Match Descriptor method of discovering the devices that support the same services. There are other methods discussed in the Application Development Fundamentals document provided by Silicon Laboratories. The Match Descriptor is the simplest to use for a small network.

The Ember API emberAfFindDevicesByProfileAndCluster() supports this method. Use this to discover the devices that support DRLC Clusters and On/Off Clusters. There is a two second wait for nodes to respond for each cluster. This method takes a total of four seconds to complete.

Ember Stack Callbacks

The Ember stack can generate three types of callbacks:

1. Send - Allows 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 – Allows the developer to handle any network status condition 3. Incoming Message Received – Allows the developer to handle the message before it is passed up to the Ember application handling The Thermostat Demo is only concerned with the Incoming Message type and the Stack Status type.

Stack Status Callbacks

emberAfStackStatusCallback()

The callback emberAfStackStatusCallback()allows the application to do any special process based on the stack status. For the Thermostat, only handle when the network is down, which means we are no longer part of any network. Update the LED to off, clear out our structures and update the internal flash.

emberAfRegistrationCallback()

The callback emberAfRegistrationCallback()notifies the application that the Smart Energy registration is complete. The Ember plugin code takes care of Smart Energy specific profile requirements. Update the state machine for the push button and set the LED.

emberAfJoinableNetworkFoundCallback()

The callback emberAfJoinableNetworkFoundCallback()notifies the application that a joinable network has been found. Implement any FCC restrictions before actually joining. Use the Ember API emberAfJoinNetwork()to join.



emberAfScanErrorCallback()

The callback emberAfScanErrorCallback()is called when a network is not found. Print out the message.

emberAfStartSearchForJoinableNetworkCallback()

The callback emberAfStartSearchForJoinableNetworkCallback()is used by the Ember stack to start scanning for a PAN to join. The Ember API emberScanForJoinableNetwork()is used to start the scan. Pass in the channel bit mask with bits set in the appropriate positions indicating which channels to scan (Example: 0x00000002 means channel 1 is to be scanned).

emberAfContinueJoinableNetworkSearchCallback()

The callback emberAfContinueJoinableNetworkSearchCallback()continues the joinable network search. This callback is called when a particular channel did not produce a joinable network. Call the Ember API emberScanForNextJoinableNetwork()to continue onto the next channel in the channel mask.

emberAfNetworkFindOperationCompleteCallback()

The callback emberAfNetworkFindOperationCompleteCallback()is the join complete notification to the Application. Print out message.

Incoming Message Callbacks

emberAfPreMessageReceivedCallback()

The callback emberAfPreMessageReceivedCallback()allows the application to handle the message before the Ember Application Framework processes it. Add notes to the tables for the various clusters through the Match Descriptor Responses in the emberAfPreZDOMessageReceivedCallback. Completing at this stage allows the user to handle incoming messages at various stages of the receive process.

emberAfPreCommandReceivedCallback()

The callback emberAfPreCommandReceivedCallback()is called by the Application Framework when any command is received. The attribute report command is completed here since this command is not a ZDO command. Creates the response and sends it out as well as sends a message to turn on the Pump based on the temperature. Returning TRUE tells the Ember Application Framework that the command has been handled and it does not need to do anything.



emberAfPreZDOMessageReceivedCallback()

The callback emberAfPreZDOMessageReceivedCallback()passes an incoming ZDO message to the application and gives the application the opportunity to handle it. To handle the Device Announce ZDO command, add the newly joined node into the list of nodes and save the new list to the internal flash.

DRLC Cluster Callbacks

emberAfPluginDrlcEventActionCallback()

The callback emberAfPluginDrlcEventActionCallback()allows the application to take action on the event. The DRLC cluster specifies various event statuses. The Thermostat Demo is interested in the following only:

1. EVENT_STARTED 2. EVENT_CANCELED 3. EVENT_COMPLETED

EVENT_STARTED sends a message out to all the Pumps to turn off as they are shedding load as an action.

EVENT_COMPLETED or EVENT_CANCELED sends a message to turn on the Pump.

Button ISR

The API halButtonIsr()must be supplied by the developer for handling button presses. The API requires two inputs: the button state (pressed or released) and the button number (0-3). The Ember Application framework will call this application level API when the button is pressed, passing in the button state and the button number. The developer supplies the code as to how it would like to relay the passed-in information to the application. This is usually in the form of setting global flags for the MainTickCallback to monitor and handle.

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 in the internal flash; referred to as “tokens”. See Section 8 of the Silicon Laboratories Application Development Fundamentals for more information.

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

Professional Grade Wireless Radio Solutions

www.cel.com23


11.14.2012

Revision History

Revision Date Description Page(s)A

0011-00-16-03-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 Home Automation Profile Specification Version 1.2, Revision 29 3. ZigBee Cluster Library Specification, Revision 3 4. ZigBee Specification, Revision 19 5. ZigBee Smart Energy Profile Specification, Version 1.1, Revision 16

0011-00-16-03-000 zicm357spx thermostat demo application ... · add any custom files into the...

Documents