ZigBee Home Sensor Demonstration User Guide

ZigBee Home Sensor Demonstration JN-UG-3033 Revision 1.3 5-Feb-2008

Jennic ZigBee Home Sensor Demonstration 2 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic Contents About this Manual 4 Organisation 4 Conventions 4 Acronyms and Abbreviations 4 Related Documents 5 Feedback Address 5 1 Operational Features 7 1.1 Hardware Components 7 1.2 Operating Instructions 7 1.2.1 Controller Board 7 1.2.2 Sensor Board 9 1.3 Routing 10 2 Application Design 11 2.1 Software Architecture 11 2.2 Context, Interrupts and Callbacks 11 3 Unpacking, Build and Download Instructions 13 3.1 Unpacking the Application 13 3.2 Building the Application 14 3.2.1 Using Makefiles 15 3.2.2 Using Code::Blocks 16 3.3 Downloading the Application 17 4 Code Description 19 4.1 Overview 19 4.2 Co-ordinator 20 4.2.1 Overview 20 4.2.2 Function Descriptions 21 4.3 Router 25 4.3.1 Overview 25 4.3.2 Function Descriptions 25 4.4 End Device 28 4.4.1 Overview 28 4.4.2 Function Descriptions 28 JN-UG-3033 v1.3 Jennic 2008 3

Jennic ZigBee Home Sensor Demonstration About this Manual This provides a description of the ZigBee Home Sensor Demonstration application for the Jennic JN5121 and JN513x wireless microcontrollers. Source and binary code for this demonstration are provided in an Application Note (JN-AN-1052), available on the: Jennic ZigBee Evaluation Kit CD Support area of the Jennic web site (www.jennic.com/support) This binary code for this application is also supplied as the default Flash memory contents in the Jennic ZigBee Evaluation Kit (EK010). Organisation This manual consists of four chapters, as follows: Chapter 1 provides a high-level view of the application in terms of its hardware components and operation. Chapter 2 outlines the application design in terms of the software used, and the use of callbacks and interrupts. Chapter 3 describes how to build the application and download it to the hardware. Chapter 4 describes the application code, including the functions used. Conventions Files, folders, functions and parameter types are represented in bold type. Function parameters are represented in italics type. Code fragments are represented in the Courier typeface. Acronyms and Abbreviations API BOS FFD IDE MAC PAN RFD SDK Application Programming Interface Basic Operating System Full Function Device Integrated Development Environment Media Access Control (sub-layer) Personal Area Network Reduced Function Device Software Developer s Kit 4 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic Related Documents [1] Jennic ZigBee Stack (JN-UG-3017) [2] Jennic Code::Blocks IDE (JN-UG-3028) [3] Jennic JN51xx Flash Programmer Application (JN-UG-3007) Feedback Address If you wish to comment on this manual, or any other Jennic user documentation, please provide your feedback by writing to us (quoting the manual reference number and version) at the following postal address or e-mail address: Applications Jennic Ltd Furnival Street Sheffield S1 4QT United Kingdom doc@jennic.com JN-UG-3033 v1.3 Jennic 2008 5

Jennic ZigBee Home Sensor Demonstration 6 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 1 Operational Features The Home Sensor Demonstration application is intended as an aid to understanding how an application can be built on top of the Jennic ZigBee software stack, and how to use the sensors and LCD panel of the Jennic ZigBee Evaluation Kit (EK010). 1.1 Hardware Components The evaluation kit consists of: One controller board with an LCD panel, a temperature sensor, humidity sensor and light sensor, four control buttons and four LEDs Four sensor boards, each with a temperature sensor, humidity sensor and light sensor, two control buttons and two LEDs. The kit is supplied with software which allows the units in the kit to emulate a home sensor and control system, known as the ZigBee Home Sensor Demonstration application. The controller enables each sensor board to be monitored, and allows alarms to be set for temperature and light levels on the sensor boards. The controller can be set to operate on a specific channel to avoid interference on busy frequencies, and the sensor boards automatically scan for the controller and synchronise with it. Note: In this ZigBee application, the controller board acts as the Co-ordinator, and the sensor boards can be used as End Devices and Routers (see Section 1.3). 1.2 Operating Instructions This section describes the buttons and screens used in operation of the controller and sensor boards. 1.2.1 Controller Board The central controller (which acts as the Co-ordinator) has several modes: Introductory splash screen, with channel selection Network display Individual node display The modes are accessed by pressing buttons on the controller, with the hierarchy of screens shown below. JN-UG-3033 v1.3 Jennic 2008 7

Jennic ZigBee Home Sensor Demonstration Button Conventions The switches on the controller board are used to navigate around a menu system, and change their function depending on which screen is being shown. On all screens, the function of a particular switch is displayed on the bottom of the LCD above the switch position. Start Software Version Information SW1 Splash Screen Done key Done key 'Node' key Network screen Node 1 display screen 'Node' key Node 2 display screen 'Node' key Node x display screen 'Node' key Splash Screen Figure 1: Controller Screen Flow Diagram This is the introductory screen. Once a sensor board has been turned on and has joined the network, this screen disappears and the Network screen is displayed. Pressing the button SW1 while the Splash screen is displayed will cause software version information to be displayed. Software Version Information Screen This screen shows the version of the demonstration application software. Network Screen The Network screen shows the current value and trend graph for one sensor type and for all sensor boards simultaneously. It is possible to choose the sensor type to 8 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic display by pressing the Temp, Humidity or Light button - the currently selected sensor type is indicated by the corresponding button label being inverted. To select a Node Display screen, the Node button should be pressed. If there are no nodes, the Node button has no effect. Node Display Screen The Node Display screen shows the current value and trend graph for all sensor types simultaneously for one sensor board at a time. The format is the same as for the Network screen. The Node Display screen also displays the number of frames that have been missed. To select another sensor board, the Node button should be pressed. When the final sensor board is displayed, pressing the Node button again causes the Network screen to appear. Pressing On or Off controls the remote switch at the sensor board, as described in Section 1.2.2. 1.2.2 Sensor Board A sensor board has two switches (SW1 and SW2) and two LEDs (D1 and D2). With the antenna at the top of the board, the left switch is SW1 and the right switch is SW2. LED D1 is the one on the left (under SW1) and LED D2 is the one on the right (under SW2). A sensor board can be in one of two modes: scanning or operating. Scanning Mode When a sensor board is switched on, it automatically enters scanning mode. 1. First the sensor board performs a channel scan. It repeatedly tries until it finds the channel on which the network is operating. 2. The board then associates with a suitable parent that is operating on this network. Again, this will be repeated until successful. During initial association, the sensor board is assigned a role by the controller. The roles are given in the order in which each board associates, in the order Hall, Bedroom, Lounge and Bathroom. The first sensor board to associate will be assigned Hall, the second Bedroom, and so on. 3. After a first successful association, the controller remembers the role it assigned to a particular sensor board, so if that sensor board loses the communication link and has to re-associate, it will be assigned the same role again. 4. Once associated, the sensor board moves into operating mode. JN-UG-3033 v1.3 Jennic 2008 9

Jennic ZigBee Home Sensor Demonstration Operating Mode While in operating mode, the sensor board periodically transmits the sensor values to the Co-ordinator. The controller can then display this information. LED D1 is controlled by the remote switch setting on the Node screen on the controller (see Section 1.2.1). There is a switch emulation performed by the sensor board. This has no visible effect at the sensor board, but an LED will be illuminated or extinguished on the controller board. Pressing SW1 turns the LED off and pressing SW2 turns it on. 1.3 Routing The sensor boards that are fitted with a ceramic antenna have been programmed as End Devices. These boards periodically send their sensor data to the Co-ordinator, as described earlier in this chapter. The sensor boards that are fitted with SMA connectors act as Routers - they relay messages from other boards that cannot reach the Co-ordinator directly. The Routers also run and report their own monitoring application, as for the End Devices. This functionality can be demonstrated as follows: 1. Turn on the controller board. 2. Turn on one of the sensor boards that is programmed as an End Device. 3. Confirm that the two boards are communicating - a graph should be displayed on the LCD screen that displays data from one of the board s sensors. 4. Take the sensor board out of range of the controller board. When this happens, the number of missed frames displayed on the screen will reach 8. 5. Now place a sensor board programmed as a Router in between the two boards and turn it on. A new node should appear on the LCD screen that represents the state of the Router. 6. Turn the End Device (first sensor board) off then on again. Its data will then appear as a new node on the controller. This data is being relayed via the Router. 10 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 2 Application Design This chapter describes architectural and certain operational aspects of the demonstration application. 2.1 Software Architecture An application sits above the ZigBee stack, which sits on top of the 802.15.4 MAC stack, which in turn sits directly above the baseband hardware. This is illustrated in the figure below. Application layer Includes mechanisms to ensure ZigBee devices can operate with each other ZigBee networking Provides unique self-configuration and routing capabilities IEEE 802.15.4 Runs on wireless microcontroller to provide transport and data packing/unpacking Figure 2: Basic Software Architecture for ZigBee The ZigBee stack is provided with defined entry points to request actions and also expects specific entry points to be provided by the application for callbacks. The ZigBee stack includes a simple task scheduler called the BOS (Basic Operating System). There are three tasks used by the ZigBee stack itself, and others can be defined by the application, if desired. It is not necessary to define a task for the application since the task scheduler calls the application regularly through a defined entry point. Note: For further information on the ZigBee software architecture, refer to the Jennic ZigBee Stack (JN-UG-3017). The Integrated Peripherals API and Board API (from the Jennic SDK) sit logically to the side of the ZigBee stack and are independent of it. 2.2 Context, Interrupts and Callbacks The ZigBee stack and the application operate within the processor s application context. Callbacks due to hardware events are passed to the application in the processor s interrupt context. It is therefore vital that code to implement the hardware event callback is kept as small and as efficient as possible. JN-UG-3033 v1.3 Jennic 2008 11

Jennic ZigBee Home Sensor Demonstration 12 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 3 Unpacking, Build and Download Instructions This chapter describes how to build and download the demonstration application. Note: The Home Sensor Demonstration application is preprogrammed in Flash memory of the boards provided with the Jennic evaluation kit. You can therefore run the demonstration without having to build and download it to the boards. This chapter is provided in case you wish to build and download a modified version of the application. 3.1 Unpacking the Application You must first unzip the JN-AN-1052 Application Note into the directory C:\Jennic\cygwin\jennic\SDK\Application\ Note: The above directory is automatically created when you install the latest Jennic Software Developer s Kit (SDK). You can obtain the latest versions of the SDK libraries and SDK toolchain from the Support area of the Jennic web site (www.jennic.com/support). The relevant part codes are JN-SW-4030 for the SDK libraries and JN-SW-4031 for the SDK toolchain. JN-UG-3033 v1.3 Jennic 2008 13

Jennic ZigBee Home Sensor Demonstration 3.2 Building the Application There are two possible methods of building the demonstration application using makefiles or the Code::Blocks IDE (Integrated Development Environment). These methods are described in the sub-sections below. In both cases, you must build the separate applications for the Co-ordinator, Routers and End Devices (HomeSensorCoord.c, HomeSensorRouter.c and HomeSensorEndDevice.c) to produce the binary files (HomeSensorCoord.bin, HomeSensorRouter.bin and HomeSensorEndDevice.bin) to be downloaded to the relevant network nodes. All files are located in the directory SDK\Application\JN-AP-1052-ZigBee-Home-Sensor-Demo The source files are located in the Source sub-directory. The binary files are output to a sub-directory which depends on the build method: If using the Code::Blocks IDE, this sub-directory is created during the build process and named according to the type of microcontroller targeted: JN5121_Build for the JN5121 JN5139_Build for the JN5139 If using makefiles, this sub-directory is Build. 14 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 3.2.1 Using Makefiles This section describes how to build the demonstration application using the supplied makefile, called Makefile, which can be used to build the source files HomeSensorCoord.c, HomeSensorRouter.c and HomeSensorEndDevice.c. The makefile is located in the Build sub-directory. Before using a makefile, you need to edit it to specify the target chip (your chip type is marked on the chip or module). The makefile contains a number of lines, some of which are commented out by default for example: #JENNIC_CHIP = JN5121 (for the JN5121 chip) #JENNIC_CHIP = JN5139R1 (for the JN5139R1 chip) JENNIC_CHIP = JN5139 (for the JN5139 chip) You should ensure that the # is removed from the start of the line corresponding to the target chip that you want to use. You can build the application as follows: 1. Start Cygwin and navigate to the folder SDK\Application\JN-AP-1052-ZigBee-Home-Sensor-Demo\Build 2. To build the code for all three device types (HomeSensorCoord.bin, HomeSensorRouter.bin and HomeSensorEndDevice.bin), enter: make clean make Alternatively, when building for both the JN5121 and JN5139 devices, it may be desirable to refresh the Board API library during the build. To do this, enter: make cleanall make JN-UG-3033 v1.3 Jennic 2008 15

Jennic ZigBee Home Sensor Demonstration 3.2.2 Using Code::Blocks This section describes how to build the demonstration application using the Code::Blocks Integrated Development Environment (IDE). Code::Blocks project files (with extension.cbp) are provided for use with the Jennic version of Code::Blocks.! Caution: You must use the version of Code::Blocks that is available for download from the Support area of the Jennic web site (www.jennic.com/support). Step 1 Step 2 The Code::Blocks project files are located in the directory SDK\Application\JN-AP-1052-ZigBee-Home-Sensor-Demo\CodeBlocksProject A project file is provided for each ZigBee device type (Co-ordinator, Router, End Device), for each type of Jennic microcontroller (your chip type is marked on the chip or module). For the JN5121 wireless microcontroller, the files are: JN5121_Coordinator.cbp JN5121_Router.cbp JN5121_EndDevice.cbp For the JN5139 wireless microcontroller, the files are: JN5139_Coordinator.cbp JN5139_Router.cbp JN5139_EndDevice.cbp Note that there may also be files prefixed with JN5139R1 for an early version of the JN5139 chip. Follow the procedure below for each application. Start Code::Blocks and open the project to be built by following the menu path File >Open. In the Open file screen, choose the project file to be opened (e.g. JN5139_Coordinator.cbp). To display the source code, navigate to the required source file under the Projects tab of the left pane and double-click on the filename. Step 3 To compile the application, click on the Build button in the toolbar of Code::Blocks. To see the build log, click on the Build log tab in the bottom pane of the Code::Blocks window. Note: For more information on using Code::Blocks, refer to the Jennic Code::Blocks IDE (JN-UG-3028). 16 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 3.3 Downloading the Application The build process produces three binary files, one for each ZigBee device type (Co-ordinator, Router, End Device): HomeSensorCoord.bin HomeSensorRouter.bin HomeSensorEndDevice.bin You must download each of these files to the relevant device(s) - HomeSensorCoord.bin to the controller board, HomeSensorRouter.bin to the two sensor boards with SMA connectors and HomeSensorEndDevice.bin to the two sensor boards with ceramic antennae. There are two possible ways of downloading your binary file to the target device: If you are using Code::Blocks (the version available from the Jennic web site), you can download your.bin file from within Code::Blocks refer to the Jennic Code::Blocks IDE (JN-UG-3028). Otherwise, you must use the Jennic JN51xx Flash Programmer application to download your.bin file refer to the Jennic JN51xx Flash Programmer Application (JN-UG-3007). JN-UG-3033 v1.3 Jennic 2008 17

Jennic ZigBee Home Sensor Demonstration 18 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 4 Code Description This chapter provides details of the code used in the demonstration application. This should help you understand the code sufficiently to adapt the application. 4.1 Overview The demonstration system consists of a Co-ordinator which is also the system controller, and several sensor boards which may be either Routers or End Devices. The general structure of the code in each device is the same, with an initialisation followed by a main loop. The Co-ordinator is initialised and starts a non-beaconing network. The Routers and End Devices then join the network and start to send regular sensor readings. There is no specific binding operation, since the network is pre-configured. The sensor devices send readings once per second, timed by a wake timer. The Co-ordinator uses the source address of the received sensor readings to determine if it has received data from that device before, and displays the information as appropriate. As each device joins the network, a new graph is displayed for it. JN-UG-3033 v1.3 Jennic 2008 19

Jennic ZigBee Home Sensor Demonstration 4.2 Co-ordinator The Co-ordinator code (for the controller board) is in the HomeSensorCoord.c file in the directory: JN-AP-1052-ZigBee-Home-Sensor-Application\Source 4.2.1 Overview The general operation of the Co-ordinator is described in Chapter 1. It goes through a series of states that reflect which screen is being shown at any time, as shown below. Start Splash screen Network view Node view For each screen, there are associated functions in the code to create the screen, update the screen and handle any button presses. Upon being started, the first action of the application is the initialisation of the hardware, stack and application variables. Once this has completed, the first screen is shown and the main control loop is entered. This loop runs for the duration of the demonstration. The main loop iterates 20 times per second, driven by events from a wake-up timer. The buttons are checked once per iteration of the loop, which avoids the need for any key de-bounce software algorithm without adding any perceived operating delay. Any events from the ZigBee stack are processed as they occur, handling received frames from endpoints. Once per second, the Co-ordinator updates the screen. At this time, it also keeps track of received frames from each node that it has previously seen data from. In this way, it can produce a count of the number frames it has missed from each node. 20 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic Note: Although there are light, humidity and temperature sensors on the evaluation kit controller board, they are not used by this demonstration. 4.2.2 Function Descriptions The function descriptions in this section are intended to assist in building a ZigBee application using the Jennic Application Programming Interfaces (APIs). As such, some functions are not mentioned, as they are not directly relevant to this goal. AppColdStart() This function is the main entry point for the application, called after the ROMresident boot loader has finished. It sets the channel and PAN ID, then calls the initialisation function vinitdemosystem(). AppWarmStart() This function is required as the main entry point for the application after a warm start (i.e. the CPU has been powered down and then restarted, with the RAM contents retained). This mode is not used in the demonstration application and is included just to call AppColdStart() as a fail safe mechanism. JZA_ boappstart() This function is called by the ZigBee stack after it has initialised. This sets up the descriptor for the profile that is implemented in the demonstration application (a private profile) and then calls a function in the ZigBee stack to start the network. JZA_vAppEventHandler() This function is called regularly by the ZigBee stack. It is used to process events that have previously been queued as results of hardware interrupts. In this case, there is only one, the wake timer, which fires every 50 ms. This is used to time the reading of the buttons and to update the display. JZA_vPeripheralEvent() This function is called when an interrupt is generated by a hardware peripheral. It is called while the processor is running in interrupt context. Therefore, in order to minimise the time spent in the interrupt context, the information about the interrupt is placed in a simple FIFO queue to be later read by JZA_vAppEventHandler(). JZA_vStackEvent() This function is called to handle miscellaneous events from the lower layers of the stack; for example, an APS layer data transmission confirmation. This demonstration application does not use this function. JN-UG-3033 v1.3 Jennic 2008 21

Jennic ZigBee Home Sensor Demonstration JZA_vAppDefineTasks() This function can be used to add application tasks. This demonstration application does not use any. JZA_eAfKvpObject() This function is called when a KVP transaction message is received and it is used to store the information passed from a sensor node. It supports up to four nodes and identifies the sending device through the device s address. If the address is not found in the list of known sensor nodes, the device is added as a new node and the screen updated. In addition, this function is used to move from the Splash screen to the Network Display screen. JZA_vAfKvpResponse() This function is called when a KVP transaction with acknowledgement has been previously requested, and the response received. It is not used in this demonstration. JZA_pu8AfMsgObject() This function is called when a MSG transaction has been received, and is not used in this demonstration. JZA_vZdpResponse() This function is called when a ZDP response is received, and is not used in this demonstration. vinitdemosystem() This function calls the ZigBee stack initialisation function. It then initialises the hardware that is being used and sets up the Splash screen. The wake-up timer used for the 20-Hz pulses is calibrated and then enabled here, but not started. The final action is to start the BOS. This function only returns if the BOS fails to start. InitCoord() Data relating to the endpoint sensor information is initialised here, as is the demonstrator configuration. vsettimer() This function uses the Integrated Peripherals API to start the wake-up timer for 1600 cycles, approximately 1/20th of a second. vprocesscurrenttimeblock() This function implements the state machine. There is only one action that is, to update the display. 22 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic vprocesskeys() This function relays button presses to the appropriate function, depending on which screen is being shown. The buttons are all soft that is, their function is dependent on the screen. vupdatetimeblock() If the Co-ordinator is in the correct state, this function increments the state machine. The state machine is effectively disabled when some screens are displayed. vsenddata() This function creates and requests the transmission of a KVP transaction, to control an LED on the sensor nodes. vprocessupdateblock() This function updates the graphs for all nodes, scaling the data to fit, and then updates the display, if the appropriate screen is being shown. Keypresses vprocesssplashkeypress vprocessnetworkkeypress vprocessnodekeypress These functions all operate in much the same way, responding to button presses to adjust values, set data or move to another screen. vupdatenetworksensor() This function is called to refresh the Network screen, which shows the same sensor types from all nodes at the same time. LCD screens vbuildnetworkscreen() vbuildnodescreen() These functions all demonstrate the creation of a fresh screen on the LCD, using the Board API. Note that the font definition requires some odd characters to be used. For instance, \ is used for a + and ] is used for -. Normally, a call to vlcdrefreshall() would be used to put the new display onto the LCD, but in all cases an associated update function is called instead, which then calls vlcdrefreshall(). Extensive use is made of vlcdwritetext(), and vbuildsetchannelscreen() also uses vlcdwritebitmap(), using the bitmap that is defined in JennicLogo.c. JN-UG-3033 v1.3 Jennic 2008 23

Jennic ZigBee Home Sensor Demonstration vupdatesetchannelscreen() vupdatenetworkscreen() vlcdupdateelement() vupdatenodescreen() vupdatenodecontrolscreen() vupdatesetupscreen() These functions all update an existing LCD screen whilst retaining what was there before. Note the use of space characters to delete unwanted text. Since the font is proportional, each space is only 3 pixels wide, while most characters are 5 pixels wide. It is therefore necessary to use additional space characters to successfully erase a series of text characters. vdrawgraph() This function takes an array of 32 values, in the range 0 to 13, and makes a bitmap graph from them. This is an alternative to using a pre-defined bitmap and allows simple graphics to be created without the complication of a line-drawing algorithm. An array is created for the two rows of data used by each graph, and a constant array is defined containing the values required for each value in the range 0 to 13. The array is then filled with the appropriate data for each item in the series of values. A structure defines the bitmap in terms of the array, as being 33 columns wide and 2 character rows high. Finally, a call to the Board API writes the bitmap to the LCD shadow memory. A call to vlcdrefreshall() must be made after calling this function for the bitmap to appear on the LCD. Miscellaneous vstringcopy() vvaltodec() These functions do not make use of the stack or API, so are not described here. 24 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic 4.3 Router The Router code is in the HomeSensorRouter.c file in the directory: JN-AP-1052-ZigBee-Home-Sensor-Application\Source 4.3.1 Overview Like the Co-ordinator code, the Router code uses a wake timer to determine the system timing. Once per second, the code reads the sensors and generates a set of KVP transactions to pass the read information to the Co-ordinator. It also uses hardware events on the DIO pins to detect when keys are pressed and when the sensor readings have completed. 4.3.2 Function Descriptions The function descriptions are intended to assist in building a ZigBee application using the APIs. As such, some functions are not mentioned as they are not directly relevant to this goal. AppColdStart() This function is the main entry point for the application, called after the ROMresident boot loader has finished. It searches for the network (PAN ID and channel) and calls the initialisation function vinitdemosystem(). AppWarmStart() This function is required as the main entry point for the application after a warm start (i.e. the CPU has been powered down and then restarted, with the RAM contents retained). This mode is not used in the demonstration application, so this function is included just to call AppColdStart() as a fail safe mechanism. JZA_boAppStart() This function is called by the ZigBee stack after it has initialised. It sets up the descriptor for the profile that is implemented in the demonstration application (a private profile), then calls a function in the ZigBee stack to join the network as a Router. This is determined by which library file is linked by the makefile or included by Code::Blocks. JZA_vAppDefineTasks() This can be used to add application tasks, but this demonstration application does not use any. JZA_eAfKvpObject() This function is called when a KVP transaction message is received. The information is used to control LED 0. JN-UG-3033 v1.3 Jennic 2008 25

Jennic ZigBee Home Sensor Demonstration JZA_vAfKvpResponse() This function is called a response is received to a KVP transaction with acknowledgement has been previously requested. The function is not used in this demonstration. JZA_pu8AfMsgObject() This function is called when an MSG transaction has been received. It is not used in this demonstration. JZA_vZdpResponse() This is called when a ZDP response is received. The function is not used in this demonstration. JZA_vAppEventHandler() This function is called regularly by the ZigBee stack. It is used to process events that have previously been queued as results of hardware interrupts. The wake timer is used to start reading the sensors in a simple state machine. The state machine is advanced by an interrupt on a DIO pin, which is controlled by the humidity/temperature sensor completing a read operation. Interrupts on the DIO pins connected to the buttons on the sensor board are used to set a value which is passed to the Co-ordinator to control an LED. JZA_vPeripheralEvent() This function is called when an interrupt is generated by a hardware peripheral. It is called while the processor is running in interrupt context. Therefore, in order to keep activity to a minimum, the information about the interrupt is placed in a simple FIFO queue to be later read by JZA_vAppEventHandler(). vinitdemosystem() This function calls the ZigBee stack initialisation function and then initialises the hardware that is being used. The wake-up timer used for the 20-Hz pulses is calibrated and then enabled here, but not started. The final action is to start the BOS. There is no return from this function. vsenddata() This function creates and requests the transmission of a set of KVP transactions, to send the sensor information and to control an LED on the Co-ordinator. vstartreadsensors() This function starts reading the temperature sensor and starts the wake timer for the next second. It sets up the interrupt on the DIO pin used by the temperature sensor. 26 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic vreadsensor2() This function reads the temperature value and starts reading the humidity sensor. It sets up the interrupt on the DIO pin used by the temperature sensor. vreadsensor3() This function reads the humidity value and the light level value. There is no delay in reading the light level. It then calls vsenddata() to send a frame containing the sensor readings. vinitendpoint() This function sets certain internal variables. u8findmin() vdebug() This function returns the minimum of two values. This function is optionally used to display error messages via serial port 0, using the Integrated Peripherals API. In order to compile in this feature, UART0_DEBUG must be defined in the makefile HomeSensorRouter.mk. JN-UG-3033 v1.3 Jennic 2008 27

Jennic ZigBee Home Sensor Demonstration 4.4 End Device The End Device code is in the HomeSensorEndDevice.c file in the directory: JN-AP-1052-ZigBee-Home-Sensor-Application\Source 4.4.1 Overview Like the Co-ordinator and Router code, the End Device code uses a wake timer to determine the system timing. Once per second, the code reads the sensors and generates a set of KVP transactions to pass the read information to the Coordinator. It also uses hardware events on the DIO pins to detect when keys are pressed and when the sensor readings have completed. 4.4.2 Function Descriptions The function descriptions are intended to assist in building a ZigBee application using the APIs. As such, some functions are not mentioned as they are not directly relevant to this goal. AppColdStart() This function is the main entry point for the application, called after the ROMresident boot loader has finished. It searches for the network (PAN ID and channel) and calls the initialisation function vinitdemosystem(). AppWarmStart() This function is required as the main entry point for the application after a warm start (i.e. the CPU has been powered down and then restarted, with the RAM contents retained). This mode is not used in the demonstration application, so this function is included just to call AppColdStart() as a fail safe mechanism. JZA_boAppStart() This function is called by the ZigBee stack after it has initialised. It sets up the descriptor for the profile that is implemented in the demonstration application (a private profile), then calls a function in the ZigBee stack to join the network as an End Device. This is determined by which library file is linked by the makefile or included in Code::Blocks. JZA_vAppDefineTasks() This can be used to add application tasks, but this demonstration application does not use any. JZA_eAfKvpObject() This function is called when a KVP transaction message is received. The information is used to control LED 0. 28 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Jennic JZA_vAfKvpResponse() This function is called a response is received to a KVP transaction with acknowledgement has been previously requested. The function is not used in this demonstration. JZA_pu8AfMsgObject() This function is called when an MSG transaction has been received. It is not used in this demonstration. JZA_vZdpResponse() This is called when a ZDP response is received. The function is not used in this demonstration. JZA_vAppEventHandler() This function is called regularly by the ZigBee stack. It is used to process events that have previously been queued as results of hardware interrupts. The wake timer is used to start reading the sensors in a simple state machine. The state machine is advanced by an interrupt on a DIO pin, which is controlled by the humidity/temperature sensor completing a read operation. Interrupts on the DIO pins connected to the buttons on the sensor board are used to set a value which is passed to the Co-ordinator to control an LED. JZA_vPeripheralEvent() This function is called when an interrupt is generated by a hardware peripheral. It is called while the processor is running in interrupt context. Therefore, in order to keep activity to a minimum, the information about the interrupt is placed in a simple FIFO queue to be later read by JZA_vAppEventHandler(). vinitdemosystem() This function calls the ZigBee stack initialisation function and then initialises the hardware that is being used. The wake-up timer used for the 20-Hz pulses is calibrated and then enabled here, but not started. The final action is to start the BOS. There is no return from this function. vsenddata() This function creates and requests the transmission of a set of KVP transactions, to send the sensor information and to control an LED on the Co-ordinator. vstartreadsensors() This function starts reading the temperature sensor and starts the wake timer for the next second. It sets up the interrupt on the DIO pin used by the temperature sensor. JN-UG-3033 v1.3 Jennic 2008 29

Jennic ZigBee Home Sensor Demonstration vreadsensor2() This function reads the temperature value and starts reading the humidity sensor. It sets up the interrupt on the DIO pin used by the temperature sensor. vreadsensor3() This function reads the humidity value and the light level value. There is no delay in reading the light level. It then calls vsenddata() to send a frame containing the sensor readings. vinitendpoint() This function sets certain internal variables. u8findmin() vdebug() This function returns the minimum of two values. This function is optionally used to display error messages via serial port 0, using the Integrated Peripherals API. In order to compile in this feature, UART0_DEBUG must be defined in the makefile HomeSensorEndDevice.mk. 30 Jennic 2008 JN-UG-3033 v1.3

ZigBee Home Sensor Demonstration Revision History Jennic Version Date Description 1.0 22-Feb-2007 First release 1.1 04-Apr-2007 Makefile description modified to correspond to updated makefiles 1.2 25-May-2007 Updated for R1 of JN5139 device 1.3 05-Feb-2008 Updated for JN5139 device and new SDK JN-UG-3033 v1.3 Jennic 2008 31

Jennic ZigBee Home Sensor Demonstration Important Notice Jennic reserves the right to make corrections, modifications, enhancements, improvements and other changes to its products and services at any time, and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders, and should verify that such information is current and complete. All products are sold subject to Jennic s terms and conditions of sale, supplied at the time of order acknowledgment. Information relating to device applications, and the like, is intended as suggestion only and may be superseded by updates. It is the customer s responsibility to ensure that their application meets their own specifications. Jennic makes no representation and gives no warranty relating to advice, support or customer product design. Jennic assumes no responsibility or liability for the use of any of its products, conveys no license or title under any patent, copyright or mask work rights to these products, and makes no representations or warranties that these products are free from patent, copyright or mask work infringement, unless otherwise specified. Jennic products are not intended for use in life support systems/appliances or any systems where product malfunction can reasonably be expected to result in personal injury, death, severe property damage or environmental damage. Jennic customers using or selling Jennic products for use in such applications do so at their own risk and agree to fully indemnify Jennic for any damages resulting from such use. All trademarks are the property of their respective owners. Corporate Headquarters Furnival Street Sheffield S1 4QT United Kingdom Tel +44 (0)114 281 2655 Fax +44 (0)114 281 2951 E-mail info@jennic.com Japan Sales Office Osakaya building 4F 1-11-8 Higashigotanda Shinagawa-ku, Tokyo 141-0022, Japan Tel +81 3 5449 7501 Fax +81 3 5449 0741 E-mail info@jp.jennic.com Taiwan Sales Office 19F-1, 182, Sec.2 Tun Hwa S. Road Taipei 106 Taiwan Tel +886 2 2735 7357 Fax +886 2 2739 5687 E-mail info@tw.jennic.com United States Sales Office 1060 First Avenue, Suite 400 King of Prussia PA 19406 USA Tel +1 619 223 2215 Fax +1 619 223 2081 E-mail info@us.jennic.com Korean Sales Office 601, Bethel B/D, #324-1 Yangjae-dong Seocho-gu Seoul 137-897 Korea Tel +82 2 552 5325 Fax +82 2 577 9130 E-mail info@kr.jennic.com 32 Jennic 2008 JN-UG-3033 v1.3