jn ug 3045 zigbee advanced user guide 1v1

ZigBee Stack

Advanced User Guide

JN-UG-3045

Revision 1.1

22-Oct-2007

Jennic

ZigBee StackAdvanced User Guide

2 © Jennic 2007 JN-UG-3045 v1.1

ZigBee Stack Advanced User Guide Jennic

Contents About this Manual 5

Organisation 5 Conventions 6 Acronyms and Abbreviations 6 Related Documents 6 Feedback Address 6

1 Essential Knowledge 7 1.1 IEEE/MAC Address vs ZigBee Network Address 7 1.2 ZigBee License Key 8 1.3 Application Code Should be Non-Blocking 8 1.4 Do Not Use the Tick-Timer 9 1.5 No BOS Function Calls in JZA_vPeripheralEvent() 9 1.6 BOS Timers are Discarded When they Expire 9 1.7 Check the Status Return When Creating BOS Timers 10 1.8 Simple Descriptors 11

2 ZigBee Low-Power Sensor Networks 13 2.1 Low-Power Sensor Network Model 13 2.2 End Device Polling 13 2.3 Transaction Persistence Time 14

3 Starting and Joining a Network 15 3.1 Setting the Device Type 15 3.2 AutoJoin 15 3.3 Stack Events Related to Starting and Joining 16 3.4 Manual Starting and Joining 16 3.5 The Permit-Joining Attribute 17

4 Establishing Communication between Two Nodes 19 4.1 Direct Communication with the Co-ordinator 19 4.2 Service Discovery 19 4.3 Binding 20

5 Sending Data 23 5.1 AfdeDataRequest() 23 5.2 MSG vs KVP 23 5.3 Broadcast Frames 24

6 End Device Sleep 25 6.1 Requesting Sleep 25 6.2 Sleep Modes 25 6.3 Waking from Sleep 26

JN-UG-3045 v1.1 © Jennic 2007 3

Jennic


7 Saving Network Context/Application Data to Flash 27

7.1 Why Save Network Context and Application Data? 27 7.2 When to Call vAppSaveContexts() 27 7.3 Restoring Network Context and Application Data 28 7.4 Saving Network Context to Flash 28 7.5 Saving Application Data with Network Context 29 7.6 Saving Application Data without Network Context 30 7.7 Sleep with Memory Held without Valid Context 30

8 Detecting Communications Loss 31 8.1 Losing Communication 31 8.2 Detecting a Missing Parent on an End Device 31 8.3 Forcing an End Device to Acquire a New Parent 32 8.4 Enabling Re-use of End Device Network Addresses 32

9 Neighbour, Routing and Binding Tables 35 9.1 Table Sizes 35 9.2 Reading Neighbour Tables 35 9.3 Reading and Purging Routing Tables 36 9.4 Reading Binding Tables 37

10 Address Allocation 39 10.1 Address Allocation Based on Tree Topology 39 10.2 Child Nodes 42 10.3 Dynamic Mesh Routing 42 10.4 Address Allocation Allows Hierarchical Tree Routing 42

11 Effects of Resetting a Device 43 11.1 Effects on Local Node 43 11.2 Effects on Children 44

4 © Jennic 2007 JN-UG-3045 v1.1


About this Manual This manual provides key information on how to use the Jennic ZigBee stack. Before starting ZigBee application development, you are advised to read this manual through completely and then keep it for reference during the development phase.

Note: It is expected that you have already read the k ZigBee StacUser Guide (JN-UG-3017), and studied the operation of simple ZigBee applications, such as those provided in the Application Notes JN-AN-1024 “ZigBee Wireless Lightswitch” and JN-AN-1016 “ZigBee Wireless UART”.

Organisation Th m

• that is essential for programming applications

• he methods that can be used to establish communication

• r 5 describes some of the issues involved in sending data between two

• ting to saving network context and

• ation loss with the

• pplication may access the Neighbour, Routing and

• address allocation works and some of the

• ines the effects of resetting a node without saving its context to Flash memory

is anual consists of 11 chapters, as follows:

Chapter 1 provides information using the Jennic ZigBee stack

• Chapter 2 outlines the ZigBee low-power sensor network model

• Chapter 3 describes the processes involved in starting and joining a network

Chapter 4 presents tbetween two nodes

Chaptenodes

• Chapter 6 outlines the sleep process

Chapter 7 provides information relaapplication data to Flash memory

Chapter 8 outlines how a node may detect communicnetwork, and the steps it may take to overcome this

Chapter 9 shows how an aBinding tables on a node

Chapter 10 describes how ZigBee limitations of the ZigBee protocol

Chapter 11 outl

JN-UG-3045 v1.1 © Jennic 2007 5

http://www.jennic.com/support/view_file.php?fileID=0000000044



Jennic


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 AF Application Framework

API Application Programming Interface

APS Application Support sub-layer

BOS Basic Operating System

ED End Device

NWK Network layer

PAN Personal Area Network

ZDO ZigBee Device Objects

ZDP ZigBee Device Profile

Related Documents [R1] ZigBee Specification version 1.0, ZigBee Alliance document 053474r06,

December 14 2004

[R2] ZigBee Stack User Guide [JN-UG-3017]

[R3] ZigBee Application Framework APIs Reference Manual [JN-RM-2018]

[R4] ZigBee Device Profile APIs Reference Manual [JN-RM-2017]

[R5] ZigBee Application Development API Reference Manual [JN-RM-2014]

[R6] Basic Operating System (BOS) API Reference Manual [JN-RM-2021]

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

[email protected]

6 © Jennic 2007 JN-UG-3045 v1.1


1 Essential Knowledge This chapter contains important information relating to use of the Jennic ZigBee stack, which all applications programmers should be aware of.

1.1 IEEE/MAC Address vs ZigBee Network Address All devices based on the IEEE 802.15.4 low-power radio specification have a unique 64-bit IEEE address, also known as the MAC address or extended address. This includes all ZigBee devices, since IEEE 802.15.4 provides the lower two layers for ZigBee (the PHY and MAC layers).

On the JN5121 and JN5139 wireless microcontrollers, this is stored in Flash memory near the beginning of sector 0. The Jennic JN51xx Flash programmer automatically reads and restores this address when writing a program to Flash.

The MAC address is loaded into RAM at start-up, along with the application and ZigBee stack. It is stored in different Flash locations on different devices. However, a function exists which returns the start location: pvAppApiGetMacAddrLocation(). To use this function, you must include the following lines in your application code:

#include “AppApi.h”

then later

MAC_ExtAddr_s sMacAddr; sMacAddr = *(MAC_ExtAddr_s *)pvAppApiGetMacAddrLocation();

Note that MAC_ExtAddr_s is defined as:

typedef struct { uint32 u32L; /**< Low word */ uint32 u32H; /**< High word */ } MAC_ExtAddr_s;

ZigBee devices also have a 16-bit network address. The Co-ordinator always has a network address of 0x0000. Routers and End Devices are each assigned a network address by their parent. The actual address that the device receives depends on the address of the parent joined and on how many network addresses the parent has already allocated.

JN-UG-3045 v1.1 © Jennic 2007 7

Jennic


1.2 ZigBee License Key On ZigBee-enabled modules (for example, those supplied in Jennic ZigBee evaluation kits), a ZigBee license key is also stored along with the IEEE/MAC address. If this is not present, or has become corrupted, then ZigBee applications will not run.

Normally, calling bBosRun() causes the BOS to start. In this case, bBosRun() does not return. Instead, other functions are scheduled by the BOS which allow the application to run.

However, if the license key is not correct, bBosRun() will return FALSE. The application can then call eBosGetLastError(), which will return the value E_PROTECT_ERROR if the cause of the failure was really an incorrect license key.

1.3 Application Code Should be Non-Blocking Since the ZigBee stack must share the CPU with the application, your application code must be non-blocking. This means that the application should not implement wait states while waiting for events to complete. Instead, events should be tested for completion and then control passed back to the BOS/stack if they are not complete.

As an example, consider the following blocking code: PUBLIC void JZA_vAppEventHandler(void) { while (bAHI_AdcPoll()) /* returns TRUE if ADC busy */ { /* do nothing – wait until poll completes */ } vReadAndProcessADC(); }

In this case, the application forces the CPU to cycle around an empty loop until the ADC poll event is complete. This prevents the BOS and the stack from performing any actions that may be necessary – internal queues may overflow and events may be discarded. The result is that the performance of the stack may be reduced, possibly severely.

In the following example, however, the code is written such that it is non-blocking: PUBLIC void JZA_vAppEventHandler(void) { if (!bAHI_AdcPoll()) { vReadAndProcessADC(); } }

If the ADC is busy, control is passed back to the BOS/stack. Then the ADC is tested again, the next time the BOS passes control back to the application.

8 © Jennic 2007 JN-UG-3045 v1.1


1.4 Do Not Use the Tick-Timer You must not use the tick-timer on the JN5121/JN513x device, since it is used by the stack. Attempts to use the tick-timer will prevent correct functioning of the BOS/stack. Instead, use the BOS software timers, one of the 32-kHz wake timers, or one of the 16-MHz timers.

1.5 No BOS Function Calls in JZA_vPeripheralEvent() Do not call BOS functions from within JZA_vPeripheralEvent(). This is because this function operates in interrupt context. Failure to follow this advice may result in the BOS/stack malfunctioning.

1.6 BOS Timers are Discarded When they Expire BOS timers are software timers that are created by the application through a call to the BOS. They are non-repeating - that is, when the timer expires, the specified function is called once and then the timer is discarded by the BOS. If you require a function to be called periodically then the application must start the timer again after it expires:

PRIVATE void vTimer(void *vpMsg, uint8 u8Param) { /* Execute any timed tasks*/ /* Start the timer again if periodic execution of function required */ bBosCreateTimer(vTimer, NULL, 0, 100, &u8TimerId); }

Note that it is possible to create multiple instances of a BOS timer.

For more information, refer to the Basic Operating System (BOS) API Reference Manual (JN-RM-2021).

JN-UG-3045 v1.1 © Jennic 2007 9



Jennic


1.7 Check the Status Return When Creating BOS Timers The application should check the status returned by bBosCreateTimer(). If it is not equal to TRUE, you must allow the stack some time to free resources before trying again. This can sometimes happen on a node (such as a Router) which is handling a lot of traffic.

For example:

PRIVATE bool_t bRestartTimer = FALSE; PRIVATE void vSomeFunction(void) { uint8 u8TimerId

/* Application function tries to create a BOS timer, and sets a global flag if failure occurs */ if (!bBosCreateTimer(vTimer, NULL, 0, 100, &u8TimerId)) { bRestartTimer = TRUE; } } PUBLIC void JZA_vAppEventHandler(void) { uint8 u8TimerId

/* Main Application function then checks flag later on, and makes an other attempt to create the timer if required. It only clears the flag if success occurs. */ if (bRestartTimer) {

if (bBosCreateTimer(vTimer, NULL, 0, 100, &u8TimerId))

{ bRestartTimer = FALSE; } }

}

10 © Jennic 2007 JN-UG-3045 v1.1


1.8 Simple Descriptors A node must register a simple descriptor for an endpoint, so that the endpoint can receive incoming frames. An endpoint can be considered as an extension of the node’s network address. An incoming frame sent to a particular address:endpoint combination cannot be delivered if the endpoint has not been defined (by registering a simple descriptor for it).

Note: It is not necessar y for a node to register an endpoint in order to send a frame.

Simple descriptors must be registered AFTER the device has successfully started or

ode checks that a simple descriptor has been successfully added to an endpoint:

eSearchEndpoint(u8EndPoint); pAfS

/* Simple Descriptor added successfully */

e

/* Simple Descriptor failed */ }

here u8EndPoint specifies the endpoint that you wish to check.

joined a network. DO NOT try to register a simple descriptor in JZA_boAppStart(). Currently, only 5 simple descriptors can be registered with the stack. The following c

AF_SIMPLE_DESCRIPTOR *pAfSimpleDesc; pAfSimpleDesc = afmif( impleDesc) { } els{

w

JN-UG-3045 v1.1 © Jennic 2007 11

Jennic


12 © Jennic 2007 JN-UG-3045 v1.1


2 ZigBee Low-Power Sensor Networks This chapter explains the underlying model of the ZigBee wireless sensor network.

2.1 Low-Power Sensor Network Model ZigBee is a low data-rate protocol, intended for use in low-power sensing and control applications. It is expected that Co-ordinators and Routers are mains-powered, so that they can always provide joining, routing and binding services for other devices. End Devices are expected to be battery-powered, and spend most of their time asleep. All End Device communications pass through the parent. Therefore, the parent must buffer any frames it receives which are intended for the End Device. Upon waking, the End Device polls its parent for data. The radio receiver of the End Device is off for most of the time, except when polling for data or listening for an Acknowledgement frame.

As a result of this, communications to and from an End Device tend to be relatively slow. However, Routers and Co-ordinators can communicate at a much faster rate, as their radio receivers are always on (except during frame transmission). Depending on the application, it may be more appropriate to use Routers for certain nodes, rather than End Devices.

2.2 End Device Polling The default behaviour is that the End Device will poll its parent immediately upon waking, and then once every second while it remains awake.

Power consumption is minimised by reducing the device’s duty cycle as much as possible. Therefore, the device would wake up, poll its parent for data, receive any data which is waiting, execute any other tasks (for example, read a sensor), and then transmit any new frames, as necessary, before going back to sleep.

Figure 1: Typical End Device Cycle

In this case, the actual polling interval is the same as the sleep period.

It is possible for the application to change the default polling behaviour. The structure JZS_sConfig contains several variables that can be used for this purpose:

JZS_sConfig.bAutoPoll JZS_sConfig.u16AutoPollInterval

WAKE ANDPOLL FOR

DATA

EXECUTEAPPLICATION

CODESLEEP TRANSMIT SLEEP

JN-UG-3045 v1.1 © Jennic 2007 13

Jennic


JZS_sConfig.bAutoPoll is set to true if the End Device is to automatically poll its parent for messages. This is the default behaviour. If it is set to FALSE, the End Device will only poll its parent when requested to do so by the application. The function JZS_vPollParent() is used for this purpose.

JZS_sConfig.u16AutoPollInterval sets the automatic polling interval. The base unit is 10 ms. By default, this is set to END_DEVICE_POLL_INTERVAL_1SEC (that is, a value of 100, which produces an interval of 1 second). This is only relevant if automatic polling is selected.

2.3 Transaction Persistence Time Frames sent to End Devices are held in buffers by their parents until either the End Device polls the parent (in which case they are transmitted to the End Device) or they expire. The time after which they expire can be controlled by the application. The default value is 7.4 seconds. However this can be changed using the following function call:

uint16 u16Value = DESIRED_VALUE nlmeSetRequest(NWK_TRANSACTION_PERSISTENCE_TIME, (void *) &u16Value);

Desired_Value has a base unit of 15 ms.

14 © Jennic 2007 JN-UG-3045 v1.1


3 Starting and Joining a Network This chapter explains the necessary steps for starting and joining a network.

3.1 Setting the Device Type The device type (i.e. Co-ordinator, Router or End Device) is fixed at compile time, by linking to the appropriate library. It is not possible to configure the device type at run-time.

3.2 AutoJoin By default, once the application makes a call to start the stack using JZS_vStartStack(), the starting and joining process is subsequently automated.

A Co-ordinator first searches for other networks. If there is no other network present with the PAN ID adopted by the Co-ordinator, the device starts a new network. However, if a beacon is received with the same PAN ID that the Co-ordinator is using, it will be unable to start a network. In this case, it will then retry repeatedly, but fail each time. A workaround is to detect the first failure to start the network within the JZA_vStackEvent() callback function and then change the PAN ID before the stack retries.

Routers and End Devices will scan for other networks. Then, if one is found with the specified PAN ID, they will attempt to join that network. Otherwise, they will automatically retry, repeatedly.

Each attempt to start or join a network generates a stack event which indicates success or failure (see below).

The PAN ID and channel are specified by setting the following variables before starting the stack:

JZS_sConfig.u16PanId /* valid range: 0-65534 */ JZS_sConfig.u8Channel /* valid range: 0, 11-26 */

Note that if channel 0 is specified then the device will scan across all channels, seraching for other networks.

JN-UG-3045 v1.1 © Jennic 2007 15

Jennic


3.3 Stack Events Related to Starting and Joining Successfully starting or joining a network results in one of the following stack events being generated in the application’s JZA_vStackEvent() callback function:

JZS_EVENT_NWK_STARTED JZS_EVENT_NWK_JOINED_AS_ROUTER JZS_EVENT_NWK_JOINED_AS_ENDDEVICE

The stack event is passed through the parameter eEventId. On Routers and End Devices, the network address allocated to the node is also passed to the application through the puStackEvent parameter:

puStackEvent->sNwkJoinedEvent.u16Addr

If the device fails to join a network, one of the following stack events is generated:

JZS_EVENT_FAILED_TO_START_NETWORK JZS_EVENT_FAILED_TO_JOIN_NETWORK

3.4 Manual Starting and Joining If JZS_sConfig.bAutoJoin is set to FALSE then the application is responsible for initiating network start-up, discovery, joining and retries.

On a Co-ordinator, after starting the stack using JZS_vStartStack() the application must call JZS_vStartNetwork(). The stack will then attempt to start as a Co-ordinator. A stack event is generated as described in Section 3.3, indicating success or failure. If the device fails to start the node, the stack must call the function JZS_vStartNetwork() each time a retry is required.

On Routers and End Devices, the application must first call the function JZS_vDiscoverNetworks(). This causes the device to search for networks to join. Once the scan has completed, the results are passed to the application through the JZA_vStackEvent() callback function. The parameter eEventId is set to JZS_EVENT_NETWORK_DISCOVERY_COMPLETE, and the list of networks found is passed as:

puStackEvent->sNetworkDiscoveryEvent.u8NetworkCount puStackEvent->sNetworkDiscoveryEvent.pNetworkList puStackEvent->sNetworkDiscoveryEvent.eStatus

Refer to the header files JZ_Api.h and nwk.h for further information on the pNetworkList structure and eStatus enumeration.

16 © Jennic 2007 JN-UG-3045 v1.1


Once network discovery is complete, the application must call JZS_vJoinNetwork() in order to initiate joining. The stack will attempt to join the network specified by

JZS_sConfig.u16PanId JZS_sConfig.u8Channel

When this activity is complete, the appropriate stack event is generated to indicate success or failure, as before for Autojoin, along with information on the network address that has been allocated by the parent.

3.5 The Permit-Joining Attribute A parent node’s readiness to accept join requests from other devices can be controlled by setting the PERMIT-JOINING attribute as follows:

nlmePermitJoiningRequest(u8Value);

• If u8Value is set to 0x00, no device will be allowed to join the parent

• If u8Value is set to 0xFF, devices will be allowed to join.

• Any other value enables joining for u8Value seconds, after which joining is disabled.

JN-UG-3045 v1.1 © Jennic 2007 17

Jennic


18 © Jennic 2007 JN-UG-3045 v1.1


4 Establishing Communication between Two Nodes Once a node has started or joined the network, it must then find another node with which to communicate. This chapter describes the three main methods that an application can use to do this.

4.1 Direct Communication with the Co-ordinator The network address of the Co-ordinator is always 0x0000. Therefore, applications running on Routers and End Devices can always send a frame to the Co-ordinator by setting the destination network address of the frame to 0x0000. The application running on the Co-ordinator can then extract the source network address from incoming KVP or MSG frame, and use it to send a frame back to the End Device/Router, as required. An example of an application that uses this method is provided in the Application Note JN-AN-1015 “ZigBee Wireless Sensor Network”.

4.2 Service Discovery Service discovery involves a node requesting services from other nodes and receiving responses. The node making the request issues a broadcast message (known as a Match Descriptor Request) that propagates throughout the network. Any node that has the requested services then uni-casts the response back to the requesting node. This means that more than one response may be received.

In order to provide services, the application running on a node must register a simple descriptor with the stack using the function afmeSimpleDescAdd(). The simple descriptor is registered for a specific endpoint (1-240), and lists the input and output clusters available on that endpoint along with its profile ID. There are also a number of other fields which are not used during service discovery.

The application running on the node which is requesting services calls the function zdpMatchDescReq(). Note that the fields passed to the stack using this function specify the descriptor which must be present on the remote node (i.e. the service provider), rather than that which is present on the local node (i.e. the requestor). For example, if the local node has an input cluster with ID of 7 then the remote node should have an output cluster with ID of 7 in order for a match to occur. The fields passed using zdpMatchDescReq() should then specify an output cluster with ID 7.

When a match occurs and a frame is sent back to the requesting node, it is passed to the application through the JZA_vZdpResponse() callback function. At this point, the application running on the local node can extract the network address of the remote node from the response. Note that the application on the remote node does not receive an indication that a request was received nor that a response was transmitted. The act of responding to a Match Descriptor Request is handled automatically by the ZigBee stack.

If the remote node needs the network address of the local node, it must wait until the local node sends it a data frame and then extract the local node’s network address from that frame.

JN-UG-3045 v1.1 © Jennic 2007 19


Jennic


An example of an application that uses this method is provided in the Application Note JN-AN-1016 “ZigBee Wireless UART”.

4.3 Binding Binding is a service provided by the Co-ordinator, which links two other nodes using entries in the Co-ordinator’s Binding table. For example, a switch node may be linked to a light node using the following process:

1. The user presses a button on the switch node and another button on the light node.

2. Both the switch node and the light node transmit a ZDP_End_Device_Bind_Request frame to the Co-ordinator, by calling zdpEndDeviceBindReq() – this frame contains details of the input and output clusters of each device.

3. If the Co-ordinator receives both requests within 5 seconds of each other, and it is able to match the input and output clusters of the two devices, it adds an entry to its Binding table to link the two devices. Note that the application running on the Co-ordinator does not receive any indication that this has taken place.

4. The Co-ordinator then sends a ZDP_End_Device_Bind_Response frame to each of the two nodes. This status field of this will be set to the one of the following values, as appropriate:

ZDP_SUCCESS_VALID ZDP_TIMEOUT ZDP_NO_MATCH

5. Subsequently, whenever the switch node transmits a data frame, it sends it to the Co-ordinator, which consults the Binding table and forwards it to the light node.

Note: The switch node and the light node are never aware of each other’s network address. All communications are directed through the Co-ordinator, which means that the Co-ordinator is then a single point of failure.

In order for the switch node to send data frames correctly after binding has been sup, when a data request is made by calling the function afdeDataRequest

et (), the

h

eAddrMode parameter should be set to APS_ADDRMODE_NOT_PRESENT.

It is possible for an End Device binding request to be successful, but for one or botof the nodes which issued the requests not to receive the response. Note that the End Device binding request has a toggle action at the Co-ordinator – that is, if the Co-ordinator receives a second request, it removes the entry from the Binding table.

20 © Jennic 2007 JN-UG-3045 v1.1



Therefore, simply retrying due to the absence of a response may produce unwanteresults. The simplest approach is for a user to test the link, and restart the bindingprocess if the link is not present. For this re

d

ason, End Device binding is perhaps

d is provided in the Application

rhaps be used in a professional commissioning system in commercial deployment.

most useful in simple domestic situations.

An example of an application that uses this methoNote JN-AN-1024 “ZigBee Wireless Lightswitch”.

It is also possible for a node to request that the Co-ordinator adds or removes anentry directly. The zdpBindReq() and zdpUnbindReq() functions generate the appropriate frames. These would pe

JN-UG-3045 v1.1 © Jennic 2007 21

Jennic


22 © Jennic 2007 JN-UG-3045 v1.1


5 Sending Data This chapter provides information on sending data frames, and describes the two types of data service that ZigBee provides.

5.1 AfdeDataRequest() Data is sent from a node using the function afdeDataRequest(). Refer to any of the Jennic ZigBee Application Notes for examples of how to use this function. You can check that a request has been successfully passed to the stack by checking the status value returned by afdeDataRequest(). If this is not equal to STACK_SUCCESS then the data request failed. In this case, the application can attempt to make the data request again some time later.

Note: It is important that before the second attempt is made, the application allows the BOS/stack an opportunity to release some resources by passing control back to the BOS.

5.2 MSG vs KVP There are two types of data service available: MSG and KVP.

MSG is a simpler format containing just data and data length fields. The Application Note JN-AN-1015 “ZigBee Wireless Sensor Network” provides an example of how to

KVP

he

sequence of events and the callbacks wh

bject()

5. Local node receives KVP response packet in JZA_vAfKvpResponse()

use MSG frames.

KVP is more complicated, featuring additional fields such as data type, attribute andvalues. This is described in the ZigBee Stack User Guide (JN-UG-3017). Themessage format is used in some ZigBee public profiles, as it is useful where interoperability is required. However, one notable benefit of KVP is that it is possibleto make the stack automatically generate a response frame, which is sent from tremote node back to the local node. The

ich are generated are shown below:

1. Local node afdeDataRequest() 2. Remote node KVP packet received in JZA_bAfKvpO3. Remote node returns TRUE in JZA_bAfKvpObject() 4. Remote node stack automatically generates KVP response packet

JN-UG-3045 v1.1 © Jennic 2007 23



Jennic


The following command types generate a response:

KVP_SET_ACKNOWLEDGMENT – the remote node is required to fill in the error code field, and this is the only data sent back to the local node. For example, the error code may be set to KVP_SUCCESS.

KVP_GET_ACKNOWLEDGMENT – the remote node returns data in addition to the error code.

The Application Note JN-AN-1016 “ZigBee Wireless UART” provides an example of how to use the KVP_SET_ACKNOWLEDGMENT command type.

5.3 Broadcast Frames A broadcast can be generated by sending a frame to address 0xFFFF.

If an End Device generates a broadcast, like all End Devices communications, it is first sent as a uni-cast frame to its parent, which then broadcasts it to the network.

A Router or Co-ordinator, which is either generating its own broadcast frame or relaying one for an End Device child, first sends a broadcast frame to neighbouring Routers/Co-ordinator. They then send individual uni-cast frames for each of their End Device children. This is because End Devices, which sleep most of the time, can only receive frames by polling. If a parent has many End Device children, this can result in the internal stack queues and MAC transmit buffers rapidly becoming full, preventing the device from generating or routing any other frames.

Note: To avoid this problem, where possible, it is recommended that broadcasts are not sent to End Devices, and that instead the application sends a uni-cast to each individual End Device, controlling the number of uni-casts which are sent concurrently. For example, KVP_SET_ACKNOWLEDGEMENT frames may be used, causing the destination node to generate a response. The sender can wait until a response is received for one uni-cast frame before sending the message to the next End Device.

Broadcast frames do not generate acknowledgements. If the application requires an acknowledgement, this is another reason for the application to send uni-casts to End

evice children rather than passing a broadcast request to the stack.

D

24 © Jennic 2007 JN-UG-3045 v1.1



6 End Device Sleep This chapter explains how an application can send an End Device to sleep, how a node can be woken from sleep, and the different sleep modes available.

6.1 Requesting Sleep Sleep is initiated on an End Device by calling the following function:

PUBLIC void vBosRequestSleep(bool_t bMemoryHold);

Routers and the Co-ordinator should not be sent to sleep, as they will then be unable to provide routing services to their children and peers.

6.2 Sleep Modes The parameter bMemoryHold of the function vBosRequestSleep() selects one of two sleep modes.

If bMemoryHold is set to FALSE, sleep without memory retention is selected. After waking, the application and stack are loaded into RAM again from Flash memory. The application starts running again from AppColdStart(). The program must make the following function calls to re-start the BOS and stack:

JZS_u32InitSystem(TRUE); BBosRun(TRUE); JZS_vStartStack();

The stack will then call the function JZA_boAppStart(), followed by the function JZA_vAppEventHandler(), as is usual for a cold start. When JZS_vStartStack() is called, the stack will check the Flash memory to determine if a network context has previously been saved. If this is the case, the stack will restore the network context to RAM, otherwise the stack will proceed to start/join a new network.

If bMemoryHold is set to TRUE, sleep with memory retention is selected. After waking, the application and stack are still held in RAM. The application starts running from AppWarmStart(). The program must make the following function calls to re-start the BOS and stack:

JZS_u32InitSystem(FALSE); BBosRun(FALSE);

In this case, the stack will not call the function JZA_boAppStart() before calling JZA_vAppEventHandler().

JN-UG-3045 v1.1 © Jennic 2007 25

Jennic


6.3 Waking from Sleep The device will wake from sleep when one of three events occurs:

• Wake timer expires

• DIO state changes

• Comparator state changes

The application must configure the hardware to enable the JN5121/JN513x integrated peripherals appropriately. For further information, refer to the Integrated Peripherals API Reference Manual (JN-RM-2001).

26 © Jennic 2007 JN-UG-3045 v1.1




7 Saving Network Context/Application Data to Flash This chapter describes how to save network context and application data to non-volatile memory in situations in which they may be lost from RAM.

7.1 Why Save Network Context and Application Data? The Jennic ZigBee stack allows the application to save the network context to Flash memory. This means that a device can survive a period of power-loss (such as a power failure or a device reset) without having to re-join the network.

For Routers and the Co-ordinator, the device will wake from a reset retaining all knowledge of any children it previously had, along with its parent’s address, radio channel and PAN ID. The Co-ordinator also retains any Binding table entries which previously existed. Since the Co-ordinator and Routers are normally mains-powered, the advantage of saving network context to Flash memory is that the devices can recover from a power failure.

On End Devices, which are normally battery-powered devices, saving network context to Flash allows the device to enter sleep mode without memory retention, and also allows the device to retain its context when the batteries are low or being replaced. An End Device retains its address, parent’s address, radio channel and PAN ID.

The same mechanism can also be used to store application data to Flash.

! Caution: If the application needs to store network context to Flash, it must not write directly to Flash memory itself.

7.2 When to Call vAppSaveContexts() The function used to save network context and application data to Flash memory is vAppSaveContexts(). This function should be called by the application in the following four instances:

• The node has just successfully started/joined a network. This can be detected by looking for the appropriate stack event in JZA_vStackEvent(). Calling vAppSaveContexts() at this point saves the initial stack context, i.e. parent’s address, radio channel, PAN ID

• When a new child has just joined, at a Router or the Co-ordinator

• When a new entry has been added to the Binding table on the Co-ordinator

• When a change has been made to any data which the application needs to store in Flash along with the network context

JN-UG-3045 v1.1 © Jennic 2007 27

Jennic


7.3 Restoring Network Context and Application Data Upon waking, the Flash memory is automatically checked to determine whether a valid context has been saved, and whether any application data was saved. If this is the case, the context and/or application data is restored. Then, the function JZA_vStackEvent() is called by the stack with the eEventId parameter equal to the value JZS_EVENT_CONTEXT_RESTORED.

Note: Flash memory is checke d for a saved context when JZS_vStartStack() is called.

When JZA_AppEventHandler() is called for the first time, the stack context has been restored and any application data saved along with the context has also been restored. The mechanism for saving and retrieving context and application data is described in more detail below.

7.4 Saving Network Context to Flash This section describes how to save network context to Flash memory.

Note: Application data can also be stored at the same time provided that this has been set up as described in Section 7.5.

On e follo

ZS_EventIdentifier eEventId, ackEvent *puStackEvent)

ER:

XT_RESTORED:

break; } }

nodes that are not being used to provide binding services to other nodes, thwing code is sufficient to save network context to Flash: PUBLIC void JZA_vStackEvent(teJ tuJZS_St{ switch (eEventId) { case JZS_EVENT_NWK_STARTED: case JZS_EVENT_NWK_JOINED_AS_ROUT case JZS_EVENT_NWK_JOINED_AS_ENDDEVICE: vAppSaveContexts(); break; case JZS_EVENT_NEW_NODE_HAS_JOINED: vAppSaveContexts(); break; case JZS_EVENT_CONTE break; default:

28 © Jennic 2007 JN-UG-3045 v1.1


On a Co-ordinator that is providing binding services, the following additional code is requ

dingEntriesCount))

u8LastBindingEntriesCount = apsmeBTGetCount(); }

7.5

ired: PUBLIC void JZA_vAppEventHandler(void) {

uint8 u8LastBindingEntriesCount = 0; PRIVATE if (apsmeBTGetCount()!= u8LastBin { vAppSaveContexts();

}

Saving Application Data with Network Context The function vAppSaveContexts() is also used to save application data to FThere is a pair of configuration variables within the structure JZS_sCo

lash. nfig

onsisting of a pointer to the data and the length of data. These are:

JZS_sConfig.u16AppDataLength – number of bytes of data

application may define an array and set the bove pointer to the first element:

JZS_sConfig.pu8AppData = au8AppData;

ry

. If no data was found,

n the application is ready to commit the data to Flash, it calls vAppSaveContexts().

c

JZS_sConfig.pu8AppData - pointer to first byte of data

The pointer to the data must be set before the stack is started (for example, in AppColdStart()). For example, thea

uint8 au8AppData[100];

Subsequently, when the stack checks Flash memory for a stored network context and application data, it will restore any application data found to the area of memowhich starts at JZS_sConfig.pu8AppData. It will then set JZS_sConfig.u16AppDataLength to indicate the number of bytes of data. By the time JZA_vAppEventHandler() is called for the first time after waking, the application data is restored and can be read from the arrayJZS_sConfig.u16AppDataLength will be set to zero.

After this point, the application can write any data to be saved (through the next sleep/power-cycle/reset) to the location set by JZS_sConfig.pu8AppData. The pointer can be changed to point to a different address whenever required – it does not have to be fixed. Then whe

JN-UG-3045 v1.1 © Jennic 2007 29

Jennic


7.6 Saving Application Data without Network Context If you wish to save application data to Flash memory but there is no need to save network context, the standard Flash functions of the Integrated Peripherals API can be used. These are described in the Integrated Peripherals API Reference Manual (JN-RM-2001). In this case, however, it is necessary that the first byte of Flash memory is set to 0xFF. This is because the ZigBee stack checks this location on waking, and uses it to determine whether a valid network context has been stored. A value of 0xFF means no context has been saved, so the stack will proceed to start with a new stack context.

7.7 Sleep with Memory Held without Valid Context If an End Device is using “sleep with memory held”, JZS_vStartStack() should not be called since the context is still retained within RAM, along with all application data. In this case, the device wakes in AppWarmStart() and when the stack is called, it expects to find a valid context in RAM. For this reason, “sleep with memory held” should never be initiated without a valid network context having been established first. Two examples of how this may occur are:

• An End Device wakes, repeatedly tries to join network (failing each time, perhaps because it is out of range) then, after some time, the application times out of this activity and sends the device back to sleep.

• An End Device has joined a network successfully, but then lost contact with its parent. It calls JZA_vRejoinNetwork() (which performs an orphan scan to try to find its old parent and, if this fails, tries to find a new parent), which does not succeed. The application initiates “sleep with memory held” before a new parent has been found.

In both these cases, using “sleep with memory held” will result in the device waking without a valid network context, and making no attempt to find a new one (i.e. start/join a network). Instead, “sleep without memory held” should be used.

There are two additional points, which need to be taken into account to ensure correct operation:

• If vAppSaveContexts() has been called at any point before this, the context should be erased using bAHI_FlashErase() before sleeping.

• If the application needs to save data for the sleep duration, it must use the Flash functions of the Integrated Peripherals API (described in the Integrated Peripherals API Reference Manual (JN-RM-2001)). Note that the first byte must be set to 0xFF, as explained in Section 7.6.

30 © Jennic 2007 JN-UG-3045 v1.1






8 Detecting Communications Loss This chapter describes how to detect a loss of communication and/or parent.

8.1 Losing Communication On the Co-ordinator and Routers, due to the dynamic mesh routing which ZigBee employs, if the next hop node on a route has failed or moved out of range, the Co-ordinator or Router will automatically attempt to either:

• repair the existing route, or

• form a new route when it next tries to send a frame.

If the Co-ordinator/Router is out of range of all other Routers/Co-ordinator then this attempt will fail. Upon moving back into range, a new attempt to send a frame may succeed, without any special action from the application.

On an End Device, since all communications go through the parent, if the parent has failed or is out of range, the End Device will be unable to send or receive any frames at all. It is the responsibility of the application to detect this situation. In this case, it can either periodically re-try the send (in which case, upon moving back into range of its parent, the message send will succeed) or attempt to find a new parent.

8.2 Detecting a Missing Parent on an End Device An End Device can detect that its parent is missing by monitoring the status of the APS confirm, which is generated by afdeDataRequest(). This is passed to the application as a stack event in JZA_vStackEvent() with the parameter eEventId set to JZS_EVENT_APS_DATA_CONFIRM. The status return should be equal to MAC_ENUM_SUCCESS to indicate that the frame was passed down the stack to the IEEE 802.15.4 MAC layer, and successfully transmitted to the parent node. If the value MAC_ENUM_NO_ACK is returned then the End Device did not receive an acknowledgement frame from its parent. If several such stack events are received consecutively then the End Device should try to find a new parent.

JN-UG-3045 v1.1 © Jennic 2007 31

Jennic


8.3 Forcing an End Device to Acquire a New Parent If an End Device loses contact with its parent, it must attempt to find a new parent. The simplest way to do this is to erase any network context that has been saved to Flash memory, and then execute a software reset:

bAHI_FlashErase(); vAHI_SwReset();

Note: If the device is a JN5121, ensure that DIO10 is high be fore resetting the device, otherwise an external clock is selected.

If End Devices move parents too many times, the End Device capacity of all the parents will become exhausted and End Devices will no longer be able to associate with new parents, or even with their old parents.

8.4 Enabling Re-use of End Device Network Addresses When an End Device moves to a new parent, if the old parent is out of range but still operational, the network address it allocated to the End Device becomes redundant.If this happens repeatedly, a parent can exhaust its capacity to acquire End Device children. At this point, it clears its A

ssociation Permit flag, preventing any new nodes

ee protocol,

rent, or

rom its Neighbour table and frees the network address for

ly rent, in order to inform the parent that it is still

provided which the application calls once to ena

ent removes the child from the Neighbour table and re-uses its network address.

from joining it, including Routers.

In ZigBee, there is no network address recycling scheme. However, a scheme has been implemented in the Jennic stack as an enhancement to the ZigBsince in many applications this will be vital for long-term robustness.

In this scheme, each parent monitors communications from its End Device children. When an End Device child has not sent any outgoing frames (either to the pathrough the parent to another node) for a certain amount of time, the parent concludes that the End Device has either failed or moved to a new parent. It then removes the End Device fre-use by another node.

Implementing this scheme may involve the End Device’s application periodicalsending empty packets to its papresent and working correctly.

To facilitate this feature, a function isble End Device address re-use:

PUBLIC void JZS_vEnableEDAddrReuse(uint16 u16CommsLossPeriod); This function includes a timeout period, u16CommsLossPeriod, as a parameter. Subsequently, if an End Device fails to send any frames to/through its parent for u16CommsLossPeriod seconds, the par

32 © Jennic 2007 JN-UG-3045 v1.1


Each time an End Device is removed, a stack event is generated in the JZA_vStackEvent() callback function, with eEventId set to:

JZS_EVENT_INACTIVE_ED_DELETED

The network address of the node that was removed is contained in:

puStackEvent->sInactiveEDDeletedEvent.u16Addr

The function JZS_vEnableEDAddrReuse() and associated software entities are described in the Jennic ZigBee Application Development API Reference Manual (JN-RM-2014).

JN-UG-3045 v1.1 © Jennic 2007 33




9 Neighbour, Routing and Binding Tables This chapter explains how an application may access the Neighbour, Routing and Binding tables.

9.1 Table Sizes The sizes of the Neighbour, Routing and Binding tables are fixed within the stack, and are as follows:

Table Type Node Type Size (entries)

Co-ordinator/Router 24 Neighbour table

End Device 8

Co-ordinator/Router 20 Routing table

End Device Not applicable

Co-ordinator 5 Binding table

Router/End Device Not applicable

Note that Neighbour and Routing table sizes correspond to the ZigBee Home Controls-Lighting profile.

9.2 Reading Neighbour Tables An example of how to access a Neighbour table is given below – this example counts the number of End Device children of a Co-ordinator or Router.

#include “TablesCoordRouter.h” #include “nwk.h” PRIVATE void vReadNeighbourTable(void) { int i; for (i = 0; i < gsNIB.nwkNeighborTableSize; i++) { if ( (gsNIB.nwkNeighborTable[i].eDevicetype == ZIGBEE_ENDDEVICE) && (gsNIB.nwkNeighborTable[i].eRelationship == NEIGHBOR_CHILD) && (gsNIB.nwkNeighborTable[i].u16Addr != 0xffff)) { u8NeighbourListCount++; } } }

JN-UG-3045 v1.1 © Jennic 2007 35

Jennic


In the case of an End Device, the file TablesED.h should be included instead of TablesCoordRouter.h.

The Neighbour table structure NWK_NeighborTable_s is defined in nwk.h.

9.3 Reading and Purging Routing Tables The Routing table is a finite resource. Once it is full on an individual node, that node will resort to using the tree to forward frames with destinations that do not already have entries in the Routing table. If tree routing then fails (for example, due to a broken branch), the frame will not be delivered to its destination.

The following code can be used to monitor the Routing table and clear the table when it becomes full:

#include “TablesCoordRouter.h” #include “nwk.h” PRIVATE void vCheckRoutingTable(void) { int i; bool_t bAllEntriesActive = TRUE; for (i = 0; i < gsNIB.nwkRoutingTableSize; i++) { if (gsNIB.nwkRoutingTable[i].eStatus != ACTIVE) { bAllEntriesActive = FALSE; } } if (bAllEntriesActive) { vDeleteRoutingTable(); } } PRIVATE void vDeleteRoutingTable(void) { int i; for (i = 0; i < gsNIB.nwkRoutingTableSize; i++) { gsNIB.nwkRoutingTable[i].u16AddrDst = 0xfffd; gsNIB.nwkRoutingTable[i].u16AddrNextHop = 0xfffd; gsNIB.nwkRoutingTable[i].eStatus = 0x03; } }

36 © Jennic 2007 JN-UG-3045 v1.1


9.4 Reading Binding Tables An example of how to access a Binding table is given below – this example counts the number of active entries in the table.

#include “aps.h” PRIVATE void vCheckBindingTable(void) { int i; uint8 u8BindingEntriesCount = 0; for (i = 0; i < gsApsIB.apsBindingTableSize; i++) {

if (gsApsIB.BindingTable[i].bInUse) { u8BindingEntriesCount++; } } }

The Binding table structure APS_BindingTable_s is defined in aps.h.

JN-UG-3045 v1.1 © Jennic 2007 37


10 Address Allocation This chapter describes the Cskip address allocation scheme used by ZigBee.

10.1 Address Allocation Based on Tree Topology The underlying address allocation algorithm in ZigBee is based on a tree topology consisting of three node types:

Co-ordinator:

• One and only one Co-ordinator must be present to start the network

• Can have children

• Can directly use meshing

Router:

• None, one or many can be present

• Can have children

• Can directly use meshing

End Device:

• None, one or many can be present

• Cannot have children

• Must communicate through its parent – so the first outbound hop always goes along the tree, then the parent can use meshing to forward the frame. Similarly, the final inbound hop must go along the tree.

When a device joins the network, it is allocated a 16-bit network address. End Devices receive a single address. Routers effectively receive a range of addresses that is sufficient to contain all possible descendants of that Router. The algorithm that is used to calculate this allocation is known as Cskip.

Cksip is way of calculating the total number of possible descendants that lie down any branch in the network. It has four parameters:

• Cm – total number of children that any parent device may have

• Rm – total number of Router children that any parent device may have

• Lm – maximum depth of the network (i.e. the level at which parent devices may no longer have children)

• d – actual depth of the device under consideration

Note that: Max End Devices = Max Children – Max Routers = Cm – Rm

JN-UG-3045 v1.1 © Jennic 2007 39

Jennic


Cskip is defined as follows:

For Rm = 1: Cskip(d) = 1 + Cm.(Lm-d-1) For all other Rm: Cskip(d) = (1 + Cm – Rm – Cm.RmLm-d-1)/(1 – Rm)

The address for the nth Router child of a parent at depth d is found as follows:

ARouter = AParent + Cskip(d).n + 1

The address for the nth End Device child of a parent at depth d is given by:

AEndDevice = AParent + Cskip(d).Rm + n

Figure 1: Cskip Network Address Allocation

In the above figure, at the Co-ordinator d = 0. Cskip(0) can be calculated and found to be equal to 6. It can be seen that 6 is also the total number of possible descendants which lie down each Router-branch from the Co-ordinator, given that Cm = 5, Rm = 2 and Lm = 2.

d = 0Cskip = 6

Coord

RouterEnd Device

Cm = Max Children = 5Rm = Max Routers = 2Lm = Max Depth = 20

1

2 3

4 5 6

7

8 910 11 12

13 14 15

d = 1Cskip = 1

d = 2Cskip = 0

40 © Jennic 2007 JN-UG-3045 v1.1


The total number of potential nodes in a specific tree can be calculated as follows:

NodesTotal = Cskip(0).Rm + (Cm-Rm) + 1

In the system shown in Figure 1, this evaluates as:

NodesTotal = 6x2 + (5-2) + 1 = 16

The maximum number of nodes allowed is 65535 (that is, 216-1), since the network address is expressed as a 16-bit number and 0xFFFF is reserved as the Broadcast address.

It is possible for the network to run out of addresses to allocate, without all addresses actually being used by real devices. This is because a new device requiring an address may not be within range of a parent with available network addresses, although addresses may be available on parents that are out of range. For example, in Figure 1, the Co-ordinator and Router with NwkAddr 7 could be fully populated, while Router with NwkAddr 1 has no children. A new device tries to join and is in range of Router with NwkAddr 7 but not in range of Router with NwkAddr 1. Therefore, although there are unused network addresses in the system, the new device is unable to join the network.

It is easy to set values for Rm, Cm and Lm such that the node limit (of 65535) is exceeded. Such combinations are forbidden. As an example, consider a network where: Cm = 20, Rm = 6 and Lm = 5 (these are the values used in the Home Controls profile). Table 1 shows the total number of nodes in this system, and what happens when each of these parameters is increased by 1.

Increasing value Cm Rm Lm Total Nodes

None 20 6 5 31101

Cm 21 6 5 32656

Rm 20 7 5 56021

Lm 20 6 6 186621

Table 1: Increasing CSkip Parameters by 1

Increasing either Cm or Rm by 1 is permissible, whereas increasing Lm by 1 would exceed the total permissible node count significantly. Increasing Rm by 2 would also result in too many nodes.

JN-UG-3045 v1.1 © Jennic 2007 41

Jennic


For the Jennic ZigBee stack, the maximum permitted values are:

• Cm = 20

• Rm = 20

• Lm = 8

Note: Before setting any combination of values, it is necessary to check that the total number of nodes does not exceed 65535.

10.2 Child Nodes The number of Router children is specified by the Cskip parameter Rm. The numbeof End Device children is the

r difference between Rm and the Cskip parameter Cm

(i.e. Max children). That is:

r table of the old parent (in which its old network address remains allocated to it).

Max End Devices = Cm – Rm When a parent runs out of capacity for either kind of child, it sets the permit-joiningflag in the beacon to FALSE, even though there may be capacity left for the other kind of device. This can prevent a temporarily orphaned child from re-associating with its former parent, even though it still has a place in the Neighbou

10.3 Dynamic Mesh Routing Although address allocation is based on a tree, most message delivery is performeusing mesh routing. This involves a local node initiating a network-wide request inorder to establish the optimum route to a remote node. Only Routers and the Co-ordinator participate in route discovery. The optimum route takes into account sufactors as number of hops and

d

ch signal strength. A partially broken route may be

repaired in a similar process.

10.4 Address Allocation Allows Hierarchical Tree Routing When a Router or the Co-ordinator receives a frame, if it is unable to establish a route using meshing it will use tree routing instead. As network address allocatioalgorithmic, the same algorithm can be used to establish which branch a

n is frame

should be passed along, according to the destination network address.

42 © Jennic 2007 JN-UG-3045 v1.1


11 Effects of Resetting a Device This chapter describes the effects of resets on devices, and on their children.

If a device is reset and its network context is restored afterwards, there are no other effects. However, if a device is reset and no context is restored afterwards, various effects occur, as described in the sections below.

11.1 Effects on Local Node The effects of resetting a node without restoring context are described below from the point-of-view of the local node.

Co-ordinator: The Co-ordinator will perform an active scan for other networks before attempting to start a network.

• Scenario 1: The Co-ordinator receives a beacon from one of its former Router children and concludes that a network with its PAN ID already exists. It is then unable to start a network. On the Jennic implementation, it will periodically retry.

• Scenario 2: If either initially or after a number of re-tries the Co-ordinator receives no beacon from any of its former Router children, it starts what is effectively a new network. It has lost all knowledge of the identities of any children it had. Therefore, any nodes that try to join it may be given network addresses that it has already allocated before the reset. This results in pairs of devices with the same network address. If the joining node is a Router, entire duplicate branches could result.

Router: The Router tries to join the network again.

• Scenario 1: The Router joins a new parent. Its old network address becomes redundant. This means that it remains in the Neighbour table of its old parent, which thinks that the device with the old network address is still its child. However, there is no longer a device with the old network address, so the address is wasted.

If the Router has End Device children, these will no longer be able to communicate with the network and must themselves find new parents, acquiring new network addresses in the process. Their old network addresses become redundant.

If the Router has Router children, these will continue communicating through the mesh, where possible. However, if this fails for some reason and the child Router tries to communicate through the tree, they will not be able to pass frames upwards.

• Scenario 2: The Router joins to its old parent, re-acquiring its old network address.

The Router has lost all knowledge of the identities of any children it had. Therefore, any nodes that try to join it may be given network addresses that it has already allocated before the reset. This results in pairs of devices with the

JN-UG-3045 v1.1 © Jennic 2007 43

Jennic


same network address. If the joining node is a Router, entire duplicate branches could result.

If the Router has End Device children, then these will no longer be able to communicate with the network and must themselves find new parents, acquiring new network addresses in the process. Their old network addresses become redundant.

If the Router has Router children, these will continue communicating through the mesh where possible. However, if this fails for some reason and the child router tries to communicate through the tree, they will not be able to pass frames upwards

End Device: The End Device tries to re-join the network.

• Scenario 1: The End Device joins a new parent. Its old network address is redundant.

• Scenario 2: The End Device joins its old parent, re-acquiring its old network address.

If the parent of an End Device fails, or is no longer able to route messages for its children, then the End Device MUST move to a new parent or else it will not be able to communicate with any other device on the network.

If the parent of a Router fails, then the Router can still communicate with other devices in the network using meshing, provided that it is able to form a route. This means it must have spare Routing table resources and be in range of at least one other Router.

11.2 Effects on Children When a parent resets without restoring context, it breaks all branches in the tree to which it is connected.

End Device children may detect that this has occurred only if they are expecting incoming frames from another node. This may be a frame originating from another node, or it may be a response to an outgoing frame. The parent will still reply with MAC-level acknowledgments to frames sent from the End Device to the parent, and also to poll requests – however, the parent will not route frames back to the End Device.

Router children that are transmitting frames using meshing will not be affected. At worst, there may be some route discovery/repair activity. However, if those children are trying to route frames through the tree (for example, due to a full Routing table), frames will fail if it is necessary to pass them upwards through the parent.

In addition, if the parent is a Router that re-joins a different parent, its old parent will not be able to use tree routing to pass frames down through it.

44 © Jennic 2007 JN-UG-3045 v1.1

ZigBee Stack Advanced User Guide Jennic Revision History

Version Date Description

1.0 26-Sept-2007 First release

1.1 22-Oct-2007 Added sections on forbidding the use of BOS functions in JZA_vPeripheralEvent() and the re-use of redundant network addresses for End Devices.

JN-UG-3045 v1.1 © Jennic 2007 45

Jennic


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 [email protected]

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 [email protected]

Taiwan Sales Office 19F-1, 182, Sec.2 Tun Hwa S. Road Taipei 106 Taiwan


United States Sales Office 1322 Scott Street, Suite 203 Point Loma CA 92106 USA


United States Sales Office 1060 First Avenue, Suite 400 King of Prussia PA 19406 USA


Korean Sales Office 701, 7th Floor, Kunam Building 831-37, Yeoksam-Dong Kangnam-ku Seoul 135-080 Korea


46 © Jennic 2007 JN-UG-3045 v1.1

jn ug 3045 zigbee advanced user guide 1v1

Documents

integrated

entire duplicate

basic operating

api reference

public void

end device

save network

bit network