Advanced features
This section describes the implementation of advanced ZigBee features that have been introduced in ZigBee 3.0.
End device aging
A Router that is a parent needs to maintain its Neighbor table. This involves discarding inactive children (that may have left the network) in order to make way for potential new children. An End Device Aging mechanism is available to support this maintenance.
In this mechanism, a timeout is applied to every child entry in the Router’s Neighbor table. If a packet, called a ‘keep-alive’ packet, is not received from an End Device child before its timeout expires, the child is assumed to be no longer active and is removed from the table (and therefore from the Router’s children).
Timeout period
The timeout period is specific to an individual child and is set on the End Device using the function zps_bAplAfSetEndDeviceTimeout(). This period is communicated to the parent via an End Device Timeout Request when the End Device joins (or re-joins) the network. The timeout is applied by the Router to the Neighbor table entry for the End Device. The arrival of a keep-alive packet from the End Device will result in the timeout being re-started from the beginning. If the timeout is allowed to expire (without a keep-alive packet), the Router will delete the relevant child entry from the Neighbor table.
Note 1: The Router initially sets the timeout for all End Device children to the default value defined in the NIB, which is 256 minutes in the NXP software. The timeout will remain at this value unless changed by the End Device, as described above.
Note 2: After receiving the End Device Timeout Request, the parent will send an End Device Timeout Response to the End Device, indicating the outcome of the request. If the request has been successful, the End Device can subsequently send keep-alive packets
Parent topic:End device aging
Keep-alive packets
A keep-alive packet can be sent from the End Device using the function zps_eAplAfSendKeepAlive(). It is recommended that this function is called at least three times within the timeout period defined for the End Device, in order to prevent the child from being accidentally removed from the network due to missed keep-alive packets at the parent.
A keep-alive packet can be either of the following types:
MAC Data Poll: In this case, the parent may send pending data back to the End Device. The arrival of this data at the End Device will be indicated by a zps_EVENT_AF_DATA_INDICATION event (as described in Section 6.5.2).
End Device Timeout Request: This packet type simply has the effect of re- starting the timeout for the End Device on the parent, which will return an End Device Timeout Response to the End Device, indicating the outcome of the request.
The keep-alive packet type to be used is determined by the Router parent and is configured in the NIB on the parent - in the NXP software, a Router is configured to accept either packet type, by default. This information is communicated to the End Device in the initial End Device Timeout Response that is sent to the End Device on joining the network. The zps_eAplAfSendKeepAlive() function will then automatically send the appropriate keep-alive packet type - where either packet type is accepted by the parent, the function sends a Data Poll packet.
Parent topic:End device aging
Parent topic:Advanced features
Distributed security networks
In a traditional ZigBee network, security is implemented by a Trust Centre, which is normally the Coordinator - this uses a centralized security scheme. In a distributed security network, any Router node can manage security and so security management is distributed throughout the network. A distributed security network does not have a Coordinator/Trust Centre, and consists only of Routers and End Devices - any Router can create the network.
In a distributed security network, only network-level security can be implemented. A network key is generated by the Router that creates the network (as described in Section 6.8.3) and is passed on to other nodes, including other Routers, as the network grows. During this distribution, the network key is encrypted using a ‘Distributed Security Global Link Key’, which is a type of pre-configured global link key (see Section 6.8.2).
A distributed security network can be started on a Router node using the function zps_eAplFormDistributedNetworkRouter(). The start parameters are specified through a zps_tsAftsStartParamsDistributedstructure (see Section 8.2.3.7). These parameters include:
PAN ID
Extended PAN ID (EPID)
Radio channel
Pointer to a location to receive the network key
This first node of the network will generate the network key (saved to the above location) and pass this key to nodes that join it.
The function zps_eAplFormDistributedNetworkRouter() can also be called on other Router nodes to join them to the network. An End Device can be joined to a distributed network using the function zps_eAplInitEndDeviceDistributed().
However, these nodes are more likely to be introduced to the network via other commissioning methods, such as Touchlink and NFC commissioning.
Parent topic:Advanced features
Filtering packets on LQI Value/Link cost
This section describes the operation and configuration of the filtering of received data packets based on LQI value (detected signal strength). Packet filtering results in some received packets with low LQI values being discarded.
In practice, the measured LQI values of packets are translated into ‘link cost’ values for filtering, as detailed in Section 6.10.3.1.
Packet filtering is optional and can be beneficial during:
network joining
route discovery
normal network operation
The operation and benefits of packet filtering are described in Section 6.10.3.2. Packet filtering can be enabled using the function zps_vAplAfEnableMcpsFilter() and modified as described in Section 6.10.3.3.
Link cost
For the purpose of packet filtering, LQI values are translated into ‘link cost’ values. Thus, a range of LQI values maps to a single link cost, which is an integer value. The default mappings implemented by the ZigBee PRO stack are shown in the table below.
‘LQI to Link Cost’ Mappings
LQI Range |
Link Cost |
|---|---|
≥ 51 |
1 |
46 - 50 |
2 |
41 - 45 |
3 |
39 - 40 |
4 |
36 - 38 |
5 |
25 - 35 |
6 |
≤ 24 |
7 |
The above mappings can be modified, as described in Section 6.10.3.3. A link cost of 5 is used as the packet filtering threshold by the NXP ZigBee PRO stack. Thus, packets with link costs greater than 5 may be discarded. For the device, this threshold is more suitable than the value of 3 proposed in the ZigBee specification. However, the threshold is configurable, as described in Section 6.10.3.3.
Parent topic:Filtering packets on LQI Value/Link cost
Packet filtering in operation
Packet filtering is an optional feature of the ZigBee PRO stack that is applied by the IEEE 802.15.4 MAC layer. It is useful during network joining, route discovery and normal network operation to optimize the processing of received packets.
Network joining
During network joining, a form of packet filtering is applied to the results of the network discovery phase. Any potential parents that have been discovered are filtered such that nodes with link costs greater than 5 (low LQI values) are discarded. This feature aids the formation of networks with strong links between neighbors and is most effective in dense networks. For more information about this process during network joining, refer to the ZigBee specification.
Parent topic:Packet filtering in operation
Route discovery and normal network operation
In a large network, traffic levels are high during both route discovery and normal operation, and a node is likely to receive many data packets. There is, however, limited storage capacity on a node to hold these packets until they can be processed. To restrict the number of received packets that are submitted to the receive queue, the following filtering system is applied:
All unicast packets are queued (without filtering) provided that sufficient space is available in the receive queue.
Broadcast packets are queued provided that at least 50% of the receive queue capacity is free, otherwise the packet filtering mechanism is applied and only packets with a link cost of 5 or less are queued.
During route discovery, this filtering prevents nodes with low associated LQI values from being entered into the Neighbor table, allowing reliable routes to be established. For example, it may be more desirable to establish a route comprising multiple hops with good LQI values than a single hop with a poor LQI value.
Parent topic:Packet filtering in operation
Parent topic:Filtering packets on LQI Value/Link cost
Packet filtering configuration
Packet filtering is disabled by default but can be enabled and re-configured as described below.
Basic configuration
The function zps_vAplAfEnableMcpsFilter() allows the stack’s packet filtering to be enabled and the link cost threshold to be adjusted (from the default value of 5). This function is detailed in Section 8.1.1. If required, it can be called at any time after zps_eAplAfInit().
Parent topic:Packet filtering configuration
Link cost configuration
The mappings between LQI values and link costs can be modified from the default mappings detailed in Section 6.10.3.1. To modify the mappings, the following function must be user-defined, which translates an LQI value (input) into a link cost (output):
uint8 APP\_u8LinkCost\(uint8 u8Lqi\);
An example function that implements the default mapping is shown below:
PRIVATE uint8 APP_u8LinkCost ( uint8 u8Lqi )
{
uint8 u8Lc;
if (u8Lqi > 50)
{
u8Lc = 1;
}
else if ((u8Lqi <= 50) && (u8Lqi > 45))
{
u8Lc = 2;
}
else if ((u8Lqi <= 45) && (u8Lqi > 40))
{
u8Lc = 3;
}
else if ((u8Lqi <= 40) && (u8Lqi > 38))
{
u8Lc = 4;
}
else if ((u8Lqi <= 38) && (u8Lqi > 35))
{
u8Lc = 5;
}
else if ((u8Lqi <= 35) && (u8Lqi > 24))
{
u8Lc = 6;
}
else
{
u8Lc = 7;
}
return u8Lc;
}
The above function must be registered as a callback function using the following callback registration function zps_vNwkLinkCostCallbackRegister(), which is detailed in Section 8.1.1. This function takes a pointer to the APP_u8LinkCost() function to be registered. If required, the registration function must be called before zps_eAplAfInit(), and on both cold and warm starts.
Parent topic:Packet filtering configuration
Parent topic:Filtering packets on LQI Value/Link cost
Parent topic:Advanced features
Device permissions
The function zps_eAplZdoSetDevicePermission() allows certain permissions to be set on the local device. These permissions are as follows:
Device permissions
Enumeration |
Description |
|---|---|
zps_DEVICE_PERMISSIONS_ALL_PERMITED |
Allow all requests from other nodes |
zps_DEVICE_PERMISSIONS_JOIN_DISALLOWED |
Do not allow join requests from other nodes |
zps_DEVICE_PERMISSIONS_DATA_REQUEST_DISALLOWED |
Do not allow data requests from other nodes and disable end-to-end acknowledgments |
When a device joins the network, the ALL_PERMITED option is set by default, so the device can respond to requests from other nodes.
However, if the network employs security set up using the ZigBee Key Establishment cluster (for example, a Smart Energy network), it is necessary to disallow data requests and end-to-end acknowledgments on the newly joined node during the key establishment process. The application must do this as follows:
Once an event has occurred to indicate that the device has joined the network (the event zps_EVENT_NWK_JOINED_AS_ROUTER or zps_EVENT_NWK_JOINED_AS_ENDDEVICE), the application must disallow data requests and APS end-to-end acknowledgments by calling zps_eAplZdoSetDevicePermission() with the option DATA_REQUEST_DISALLOWED.
The key establishment process can then be started using the function provided for the Key Establishment cluster.
Once the key establishment process has successfully completed, data requests and APS end-to-end acknowledgments can be allowed again by calling zps_eAplZdoSetDevicePermission() with the ALL_PERMITED option.
The key establishment process and associated resources are fully described in the documentation for the Key Establishment cluster (for example, in the ZigBee Smart Energy User Guide).
Parent topic:Advanced features
Parent topic:Application coding with ZigBee PRO APIs