Appendix B: Application design notes

This Chapter describes information and recommendations useful to designers who are incorporating non-routine operations in their applications. The topics covered are:

• Fragmented data transfers

• Sending data to sleeping end devices

• Clearing stack context data before a rejoin

• Beacon filtering guidelines

• Table configuration guidelines

• Received message queues

• Noise threshold for forming a network

Fragmented data transfers

The send ‘with acknowledgment’ functions (ZPS_eAplAfUnicastAckDataReq(), ZPS_eAplAfUnicastIeeeAckDataReq(), and ZPS_eAplAfBoundAckDataReq()) allow a large data packet to be sent that may be fragmented into multiple messages/ frames during transmission. As a general rule, one of these two functions should be used when sending a data packet with a payload size greater than 80 bytes. It is important to note, however, that the use of APS security will reduce this limit, as payload bytes are taken up by security data.

The processes of fragmentation at the sender and de-fragmentation at the receiver are transparent to the applications at the two ends, but the points described in the sub-sections below should be noted.

Note:

1. Fragmentation is described further in Fragmented data transmission to sleeping End Device: in connection with fragmented data transfers to sleeping End Devices.

2. The ZigBee network parameters referenced in this section are configured using the ZPS Configuration Editor and are described in Chapter 13, “ZigBee Network Parameters”. When setting up the APDUs to handle Rx fragmentation, care must be taken to ensure that the configuration setting in the ZPS Configuration Editor is sized to be able to handle 3* Tx Fragments.

Enabling/disabling fragmentation

In order to allow fragmented data transfers between two nodes, you must appropriately configure two ZigBee network parameters:

• Set the parameter Maximum Number of Transmitted Simultaneous Fragmented Messagesto a non-zero value on the sending node, to allow transmitted messages to be fragmented.

• Set the parameter Maximum Number of Received Simultaneous Fragmented Messagesto a non-zero value on the receiving node, to allow received fragmented messages to be re-assembled.

Note: Setting either of these parameters to zero would disable the corresponding fragmentation feature but reduce the size of your compiled application code.

Parent topic:Fragmented data transfers

Configuring acknowledgments

You can configure how acknowledgments are generated during a fragmented data transfer by setting the ZigBee network parameter APS Max Window Size. This parameter must be set to the same value on the source and destination nodes. The parameter determines the number of fragments to be transferred before an acknowledgment is generated. For example, if a data packet is divided into 6 fragments and this parameter is set to 3, an acknowledgment will be generated after the third fragment and after the sixth fragment.

Note: Setting this parameter to a low value results in a high level of network traffic, since a large number of acknowledgment packets are sent.

The acknowledgment for a group of fragments contains an indication of any missing fragments from the group, thus requesting the missing fragment(s) to be re-sent.

Parent topic:Fragmented data transfers

Acknowledgment timeout

A timeout of approximately 1600 ms is applied to each acknowledgment, measured from the time at which the last data fragment in the relevant group was transmitted - if no acknowledgment is received within this timeout period, the entire group of fragments is automatically re-sent. Up to 3 more re-tries can subsequently be performed. For a fragmented data transfer, the time that elapses before a completely unacknowledged transmission is abandoned is difficult to estimate, since this time depends on the number of fragments, the network parameter APS Max Window Sizeand the network parameter APS Inter-frame Delay(time between transmissions of consecutive fragments).

Parent topic:Fragmented data transfers

Parent topic:Appendix B: Application design notes

Sending data to sleeping end devices

As described in Polling for Data, data sent to a sleeping End Device is buffered in the node’s parent until the End Device collects the data through a polling mechanism, typically on waking from sleep. It is important that the polling interval is not too long, as the buffered data is discarded after 7 seconds. In addition, there is limited buffering space in the parent and the buffers are shared by all the children of the parent. Therefore, applications should be designed in such a way that data is only sent to a sleeping End Device when it is either awake or will wake in a timely manner to collect the data from its parent.

The following issues should also be considered when sending data to a sleeping End Device using one of the send ‘with acknowledgment’ functions:

• ZPS_eAplAfUnicastAckDataReq()

• ZPS_eAplAfUnicastIeeeAckDataReq()

• ZPS_eAplAfBoundAckDataReq()

Note: The ZigBee network parameters referenced in this appendix are configured using the steps described in Chapter 13, ZPS Configuration Editor.

Acknowledged data transmission to sleeping end device

When data is sent and an acknowledgment is required from the receiver, a timeout of approximately 1600 ms is applied to the acknowledgment. If no acknowledgment is received by the sender within this timeout period, the data is automatically re-sent. Up to 3 more re-tries can subsequently be performed, totalling just over 3 seconds before the data transfer is finally abandoned.

In the case of data sent to a sleeping End Device, the acknowledgment is generated by the End Device after collecting the data from its parent. Thus, if the data is not collected within the acknowledgment timeout period, the data is re-sent to the End Device (via its parent).

Note: There can be a case when the buffered data is collected by the End Device after the final re-try by the sender but before the data is discarded by the parent (between approximately 3 and 7 seconds after the initial transmission). In such cases, the acknowledgment that is eventually generated by the End Device is ignored by the sender, since the transaction has already timed out and terminated.

Parent topic:Sending data to sleeping end devices

Fragmented data transmission to sleeping End Device

The Section 6.5.1 and Fragmented data transfers explain how the send ‘with acknowledgment’ functions can be used to send large data packets that require to be fragmented into multiple NPDUs during transmission. Therefore, when sending a fragmented data packet to a sleeping End Device, the issues described in Acknowledged data transmission to sleeping end device apply.

In such a data transfer, the End Device should aim to collect all buffered data fragments from its parent before the transfer has completely timed out on the sender. Once the sender has abandoned the transaction, it does not respond to any acknowledgments requesting missing fragments (see Appendix B.1).

Once the End Device starts to receive fragmented data, it stays awake until the transaction is complete and runs its own poll timer to automatically collect each fragment - the polling period for this timer is set through the ZigBee advanced device parameter APS Poll Period. This poll timer runs for the duration of the fragmented transaction and then stops. The responsibility for polling then returns to the application.

Sending fragmented data to a sleeping End Device is likely to result in duplicate fragments of the message being sent. A list of the last few fragments received, called the APS Duplicate table, is maintained in the End Device. This table allows new fragments to be compared with previous fragments and duplicates identified. The maximum number of entries (fragments) in this table can be configured through the network parameter APS Duplicate Table Size. This table size should not be made too small, as a short table prevents duplicate fragments from being caught (4 may be a suitable value). This value should be considered in conjunction with the value of the network parameter APS Persistence Time. This parameter represents the time for which resources associated with a message are retained after the complete message has been received. Once the resources have been released, they may be used for a new transaction) - during this period, any duplicate fragments that are received are ignored.

Parent topic:Sending data to sleeping end devices

Parent topic:Appendix B: Application design notes

Clearing stack context data before a rejoin

If a node rejoins the same secured network (with ZigBee PRO security enabled) but its stack context data was cleared before the rejoin (by calling NvErase()), data sent by the node will be rejected by the destination node since the frame counter has been reset on the source node - frame counters are described in Section 2.8 and Appendix A.

• Sent data will be accepted again by the destination node when the frame counter for the source node reaches its last count known before the rejoin. Therefore, you are not recommended to clear the stack context data before a rejoin.

However, it is worth noting that frame counters are reset across the entire network when a new network key is broadcast by the Trust Centre using the function ZPS_eAplZdoTransportNwkKey() - see Section 6.8.4. Thus, if stack context data is cleared before a rejoin, the frame counter problem can be avoided by broadcasting a new network key from the Trust Centre (normally the Coordinator) immediately after the rejoin.

To restore the stack to a default state and not clear the frame counters ZPS\_vDefaultStack should be used - see Section 7.1.1.

Parent topic:Appendix B: Application design notes

Beacon filtering guidelines

A filter can be introduced for filtering beacons in network searches (on a Router or End Device). Beacons can be filtered on the basis of Extended PAN ID (EPID), LQI value and device joining status/capacity (see below). The filter can be applied using the function ZPS_bAppAddBeaconFilter().

If required, the above function must be called immediately before ZPS_eAplZdoDiscoverNetworks(), ZPS_eAplZdoRejoinNetwork() or ZPS_eAplZdoStartStack().

A tsBeaconFilterTypestructure is supplied to the ZPS_bAppAddBeaconFilter()

function in order to specify the details of the filter to be implemented, including:

• A blacklist or whitelist of networks in terms of a list of EPIDs.

• The PAN ID of the network from which acceptable beacons should come.

• The minimum LQI value of an acceptable beacon.

• Flags indicating the properties on which beacons will be filtered, which include:

  • LQI value of beacon.

  • Permit Join enabled on sending device.

  • Capacity of sending device to accept Router children.

  • Capacity of sending device to accept End Device children.

After each discovery or rejoin, the flags are cleared while all other fields of the structure remain intact. The structure is detailed in Section 8.2.3.5.

The following general guidelines should be followed in using beacon filters:

• Do not implement a filter unless attempting a join, as this would prevent some stack operations from working correctly.

• Do not enable a blacklist and whitelist at the same time.

• Do not declare your filter structure as a local variable in a function, as it needs to exist for the duration of the discovery.

The following guidelines are relevant to network rejoins and associations.

Network rejoin

• Do set up a whitelist containing a single EPID corresponding to the network that the node is to rejoin (if only one network is of interest) and/or the PAN ID of this network.

• Do set up an LQI filter to reject distant beacons, if required.

• Do not enable filtering on Permit Join or Router/End Device Capacity.

Parent topic:Beacon filtering guidelines

Association

• Do set up an LQI filter to reject distant beacons, if required.

• Do filter on the Permit Join status to only find potential parents and networks that are accepting association requests.

• Do filter on Router/End Device Capacity, if required, depending on device type.

Note: A blacklist can be built up over several attempts to discover and associate, by keeping on adding to the array of EPIDs, as each network is rejected.

Parent topic:Beacon filtering guidelines

Parent topic:Appendix B: Application design notes

Table configuration guidelines

This section provides guidelines on configuring various tables used by the ZigBee PRO stack. These tables can be configured through ZigBee network parameters in the ZPS Configuration Editor. The tables are sized, by default, to support a network of up to 250 nodes. The table sizes can be increased to support more nodes, but this will be at the expense of RAM and/or Flash usage.

The tables and their configuration are individually described in the sections below, which reference to the ZigBee network parameters used to configure the table sizes (the network parameters are detailed in Chapter 12).

Neighbor table

The Neighbor table on a routing node (Router or Coordinator) holds information about the node’s immediate neighbors:

• The first entry in the table contains information about the node’s parent.

• Part of the table holds information about child nodes which have joined the network through the local device.

• The rest of the table holds information about nodes which are neither children nor the parent (these ‘other’ nodes are only relevant to Mesh networks).

The Neighbor table size is, by default, set to 26 - this is the minimum size required for a ZigBee-Compliant Platform. The table size may be increased through the parameter Active Neighbor Table Sizeto reflect the density of the network. However, increasing the table size uses more RAM. Increasing the Neighbor table size beyond 26 also results in an extra link status packet since one of these packets can accommodate a maximum of 26 neighbors. Thus it doubles the traffic for these periodic packets.

The first two parts of the Neighbor table, for the device’s parent and children, form a sub-table that is persisted in Flash. This sub-table must not occupy more than two-thirds of the Neighbor table. Since this sub-table contains child entries, the size of the sub-table determines the number of children that the device is allowed to have - the maximum number of children is one less than the sub-table size.

The default size for the sub-table is 5, allowing up to 4 child nodes, but the size can be changed through the parameter Child Table Size (which corresponds to the total number of sub-table entries including the parent’s entry, not just the child entries).

Note: Increasing the sub-table size uses more Flash for persisted data.

Parent topic:Table configuration guidelines

Address Map table

The Address Map table on a node is used to keep a record of the address-pairs of network nodes with which the local node needs to communicate directly - that is, the IEEE/MAC address and network address of each of these nodes. In fact, an Address Map table entry only contains an index to an entry in the MAC Address table, where the actual addresses of the node are stored (see MAC Address table). The population of these tables is done as the result of device announcement messages.

The default size of the Address Map table is 10, but the size can be changed through the parameter Address Map Table Size. The Address Map table is fully persisted in Flash. Therefore, increasing the size of this table will impact both RAM and Flash usage.

Parent topic:Table configuration guidelines

MAC Address table

The MAC Address table on a node is used to store the address-pairs of other network nodes - that is, the IEEE/MAC address and network address of each of these nodes. The entries in the MAC Address table are referenced from entries of both the Neighbor table and Address Map table. Therefore, the MAC Address table should be sized according to the combined sizes of the Neighbor table and Address Map table.

The default size of the MAC Address table is 36, but the size can be changed through the parameter Maximum Number of Nodes. The MAC Address table is fully persisted in Flash. Therefore, increasing the size of this table impacts both RAM and Flash usage.

Parent topic:Table configuration guidelines

Routing table

A Routing table is held by the Coordinator and Router nodes to store routing information to other nodes in the network.

The default size of the Routing table is 70, which should be sufficient for most applications, but the size can be changed through the parameter Routing Table Size. The table size should be increased if routing bottlenecks are observed. The Coordinator needs to store routes to all the nodes in the network if it is required to communicate with every node. In this case, the Routing table size should be increased to the size of the network.

The Routing table is not persisted. Therefore, any increase only affects the RAM usage.

Parent topic:Table configuration guidelines

Broadcast Transaction table

The Broadcast Transaction table is used for the origination, processing and passive acknowledgment of broadcast transmissions. The minimum required size of this table for a ZigBee-Compliant Platform is 9. However, an application that produces a large number of broadcasts may need a larger table. The size of the table can be set through the parameter Broadcast Transaction Table Size.

Parent topic:Table configuration guidelines

Route Discovery table

The Route Discovery table is used to hold temporary details of a route discovery transaction. The table size dictates how many individual route discoveries can occur on the local node at a given time. The default size of the Route Discovery table is 2, but the size can be changed through the parameter Route Discovery Table Size. The default value severely restricts the number route discoveries and hence broadcasts on the network. Increasing the table size also requires increases in the Routing table and Broadcast Transaction table sizes.

The Route Discovery table is not persisted. Therefore, any increase only affects the RAM usage.

Parent topic:Table configuration guidelines

Discovery table

A Discovery table is held by the Router and End Device nodes to store the results of a channel scan when searching for a network to join. The default size of the Discovery table is 8, but the size can be changed through the parameter Discovery Neighbor Table Size.

Parent topic:Table configuration guidelines

Route Record table

The Route Record table is only relevant to a device, which will be the concentrator in a network, if many-to-one routing is implemented. This table replaces the Routing table in the node.

• The size of the Route Record table can be set through the parameter Route Record Table Size.

• In the concentrator node, this table size should be set to the size of the network. Since this table then replaces the Routing table in the node, the Routing table size should be set to 1 (see Appendix B.5.4).

• In all other network nodes, the size of the Route Record table should be set to 1.

Parent topic:Table configuration guidelines

Parent topic:Appendix B: Application design notes

Received message queues

All messages received ZPS_msgMcpsInd on a network node are pushed into one of the following two queues:

• ZPS_msgMcpsDcfm

• ZPS_msgMcpsInd

These queues must be created by the application using the function ZQ_vZQueueCreate(). An example code is described in Section 6.9.1.2.

ZPS_msgMcpsDcfm

All IEEE 802.15.4 MAC data deferred confirm events are added to this queue. The default size of this queue is 8 but a different queue size can be set when the queue is created. The queue can overflow if there is heavy network traffic.

Parent topic:Received message queues

ZPS_msgMcpsInd

All IEEE 802.15.4 MAC data packets are added to this queue. The default size of this queue is 24 but a different queue size can be set when the queue is created. The queue can overflow if there is heavy network traffic.

Parent topic:Received message queues

Parent topic:Appendix B: Application design notes

Noise threshold for forming a network

The ZigBee PRO stack provides a mechanism for forming a new network in the quietest IEEE802.15.4 radio channel. The Coordinator (centralized network) or Router (distributed network) that forms the network performs a channel scan to listen for activity from other local networks.

During the channel scan, the activity in each channel is assigned a noise level in the range 0 to 254. This result is compared with a noise level threshold, which is defined by the NIB value u8VsFormEdThreshold (which is part of the structure ZPS_tsNwkNibInitialValues). If the measured noise level for a channel is above this threshold, the channel is excluded from further consideration. Therefore, if all the channels in the scan are noisier than the threshold allows, no network is formed.

The stack then re-scans the channels that passed the noise threshold test (if any) and selects the one with the lowest beacon count in which to form the network.

Note:

• This assessment takes into account IEEE802.15.4 beacons only and no activity from networks based on other systems, such as Wi-Fi.

• The assessment is based on beacons only and does not consider the noise levels of the shortlisted channels.

Default Behavior

To avoid the situation in which no network is formed, the default value of u8VsFormEdThresholdis 0xFF, which is a special value and not a noise threshold. In this case, the network is always formed in the channel with the lowest IEEE802.15.4 beacon activity (no noise level assessment is performed).

Parent topic:Noise threshold for forming a network

Customizing the scan

You can implement network formation based on the noise level threshold, as described above, by setting u8VsFormEdThresholdto an appropriate value in the range 0 to 254. In the following code fragment, a noise level threshold of 100 is set:

ZPS_psNwkNibGetHandle(ZPS_pvAplZdoGetNwkHandle())->u8VsFormEdThreshold = 100

Thus, in the above case, all channels with a noise level above 100 will be rejected.

If no suitable channel is found and no network formed, the application can dynamically increase the value of u8VsFormEdThresholdand initiate another scan.

Parent topic:Noise threshold for forming a network

Parent topic:Appendix B: Application design notes