Transferring data

This section describes how to send data to a remote node and receive the data at the destination. The data polling method is also described, which is used by an End Device to obtain data that arrives at its parent while the End Device is asleep.

Sending data

Data is sent across the wireless network in an Application Protocol Data Unit (APDU). Before calling the function to send the data, an APDU instance must first be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then populated with data using the PDUM function PDUM_u16APduInstanceWriteNBO().

There are five ways to send data to one or more remote nodes:

  • Unicast: Sending data to a single destination endpoint

  • Broadcast: Sending data to (potentially) all endpoints

  • Group Multicast: Sending data to a group of endpoints

  • Bound Transfer: Sending data to bound endpoints

  • Inter-PAN Transfer: Sending data to another ZigBee PRO network

These methods are described in the sub-sections below. However, in all cases except the inter-PAN transfer, a general function zps_eAplAfApsdeDataReq() can be used which imposes no restrictions on the destination address, destination cluster and destination endpoint number - these destination parameters do not need to be known to the stack or defined in the ZPS configuration.

Note:

  1. In all cases, once the data packet has been successfully sent, a ‘DATA_CONFIRM’ stack event is generated. When sending data to one or more individual nodes (not broadcasting), this event is generated after a MAC-level acknowledgment has been received from the ‘next hop’ node.

  2. Where 64-bit IEEE/MAC addresses are used to identify remote nodes, the corresponding 16-bit network addresses must be available in the local Address Map - see Section 5.2.3.

Unicast

A unicast is a data transmission to a single destination - in this case, a single endpoint. The destination node for a unicast can be specified using the network address or the IEEE/MAC address of the node:

  • zps_eAplAfUnicastDataReq() is used to send a data packet to an endpoint on a node with a given network address.

  • zps_eAplAfUnicastIeeeDataReq() is used to send a data packet to an endpoint on a node with a given IEEE/MAC address.

Neither of these functions provide any indication that the data packet has been successfully delivered to its destination. It is possible that a unicast packet will not reach its destination because the packet is lost - for example, it becomes caught in a circular route. However, equivalent functions are available which request the destination node to provide an acknowledgment of data received - these ‘with acknowledgment’ functions are zps_eAplAfUnicastAckDataReq() and zps_eAplAfUnicastIeeeAckDataReq(), requiring network and IEEE/MAC addresses respectively. These functions request end-to-end acknowledgments which, when received, generate zps_EVENT_APS_DATA_ACK events (note that the ‘next hop’ zps_EVENT_APS_DATA_CONFIRM events will also be generated). A timeout of approximately 1600 ms is applied to the acknowledgments. If an acknowledgment has not been received within the timeout period, the data is re-sent, and up to 3 more re-tries can subsequently be performed before the data transfer is abandoned completely (which occurs approximately 3 seconds after the initial send).

Note: If a message is unicast to a destination for which a route has not already been established, the message will not be sent and a route discovery will be performed instead. If this is the case, the unicast function will return zps_NWK_ENUM_ROUTE_ERROR. The application must then wait for the stack event zps_EVENT_NWK_ROUTE_DISCOVERY_CONFIRM(success or failure) before attempting to re-send the message by calling the same unicast function again.

Unicasts from sleepy nodes

To allow a unicast acknowledgment to be received as described above, the source node must remain awake for a time equal to the timeout period. On a battery-powered node which sleeps, the use of acknowledgments and retries may not be desirable from a power-saving point of view. In this case, acknowledgments should not be used, but it is good practice for the application to monitor the route to a remote node by periodically attempting to read an attribute on the node and wait for a response. If the response is not observed within a pre-defined time then the application should take one of the actions listed below, depending on whether the source node is an End Device or Router.

  • If an End Device, the application should notify the parent node about the routing problem by sending it a unicast network status command using the function zps_vNwkSendNwkStatusCommand(), with the status as “No Route Available (0x00)”

  • If a Router, the application should initiate an explicit route discovery to the destination node by calling the function zps_eAplZdoRouteRequest()

Parent topic:Unicast

Fragmenting large unicast packets

The unicast ‘with acknowledgment’ functions, zps_eAplAfUnicastAckDataReq() and zps_eAplAfUnicastIeeeAckDataReq(), also allow a large data packet to be sent that may be fragmented into multiple messages during transmission. Application design issues concerned with fragmented data transfers are outlined in Fragmented data transfers.

Parent topic:Unicast

Parent topic:Sending data

Broadcast

A broadcast is a data transmission to all network nodes, although it is possible to select a subset of nodes. The following destinations are possible:

  • All nodes

  • All nodes for which ‘receiver on when idle’ - these include the Coordinator, Routers and non-sleeping End Devices

  • All Routers and the Coordinator

The function zps_eAplAfBroadcastDataReq() is used to broadcast a data packet. It is possible to specify a particular destination endpoint on the nodes (the same endpoint number for all recipient nodes) or all endpoints. Following this function call, the packet may be broadcast up to four times (in addition, the packet may be subsequently re-broadcast up to four times by each intermediate routing node).

Parent topic:Sending data

Group multicast

A group multicast is a data transmission which is intended for a selection of network nodes or, more specifically, a selection of endpoints on these nodes. The set of destination endpoints must be pre-assembled into a group with an associated ‘group address’, as described in Section 5.3.

The function zps_eAplAfGroupDataReq() is used to send a data packet to the group of endpoints with a given group address. In practice, the data packet is broadcast to all nodes in the network and it is the responsibility of each recipient node to determine whether it has endpoints in the target group (and therefore whether the packet is of interest).

Parent topic:Sending data

Bound transfer

A data packet can be sent from an endpoint to all the remote endpoints with which the source endpoint has been previously bound (see Section 5.4). The function zps_eAplAfBoundDataReq() is used to implement this type of data transfer. This method provides an alternative to a group multicast (see Section 5.5.1.3) for sending data to selected endpoints.

An equivalent to the above function is provided which also requests an ‘end-to-end’ acknowledgment from the destination - zps_eAplAfBoundAckDataReq(). If an acknowledgment has not been received within approximately 1600 ms of the initial request, the data is re-sent, with up to 3 more subsequent re-tries before the data transfer is abandoned completely.

zps_eAplAfBoundAckDataReq() also allows a large data packet to be sent that may need to be fragmented into multiple messages during transmission. Application design issues concerned with fragmented data transfers are outlined in Fragmented data transfers.

Following a call to one of the above bound transfer functions, a deferred zps_EVENT_BIND_REQUEST_SERVER event is generated on the sending node. This event summarizes the status of the transmission (see Section 7.2.2.21), including the number of bound endpoints for which the transmission failed. The event is generated only after receiving MAC-level acknowledgments from the ‘next hop’ nodes or, if requested, after receiving end-to-end acknowledgments from the destination nodes.

Note: In the case of a bound transfer, the ‘next hop’ zps_EVENT_APS_DATA_CONFIRM events and ‘end-to-end’ zps_EVENT_APS_DATA_ACK events are consumed and do not reach the application.

Parent topic:Sending data

Inter-PAN transfer

A data packet can be sent to nodes in other IEEE 802.15.4 networks - this is referred to as an inter-PAN transfer or transmission. Typically, this mechanism could be used to send information to optional low-cost devices that are not part of the local network. Note that no security (encyption/decryption) can be applied to inter-PAN transfers and only one application on a device can perform inter-PAN transmissions. The inter-PAN messages are not forwarded and so will only be received by nodes within direct radio range of the transmitter.

The inter-PAN feature is enabled via the ZPS Configuration Editor. The Inter PANvalue is set to true in the APS Layer Configuration section of the Advanced Properties for the device.

The function zps_eAplAfInterPanDataReq() is used to request an inter-PAN transmission. This function requires the destination(s) for the transfer to specified:

  • Single destination node in a specific network (PAN ID and node address must be specified)

  • Multiple destination nodes in a specific network

(PAN ID and a group address for the nodes must be specified)

  • All nodes in a specific network

(PAN ID and broadcast address of 0xFFFF must be specified)

  • All nodes in all reachable networks

(broadcast PAN ID and broadcast address, both of 0xFFFF, must be specified)

After successfully sending the data packet, the stack will generate the event zps_EVENT_APS_INTERPAN_DATA_CONFIRM (for a single destination, this event is generated once the ‘next hop’ acknowledgment has been received).

A destination endpoint is not specified for this type of data transfer but a cluster must be specified for the destination. On receiving the data packet, the recipient node will automatically pass the packet to the endpoint which supports the given cluster (see Section 5.5.2).

Note:

  1. In the case of a data packet received from another network by means of an inter-PAN transfer, the zps_EVENT_APS_INTERPAN_DATA_INDICATION stack event will be generated. The data packet will be passed to the endpoint which supports the specified cluster. The application must always handle these inter-PAN packets and release the APDU instances (see below). The event will only be generated if the inter-PAN feature has been enabled via the ZPS Configuration Editor. If an application transmits inter-PAN messages but does not need to receive them, the application must enable inter-PAN in the ZPS Configuration Editor and handle any zps_EVENT_APS_INTERPAN_DATA_INDICATION events by releasing the APDU instances.

  2. In the case of the arrival of a response packet which is destined for the ZDO, a zps_EVENT_AF_DATA_INDICATION stack event will be generated with a destination endpoint of 0. It will be necessary for the application to call the function zps_bAplZdpUnpackResponse() to extract the response data from the event.

Parent topic:Sending data

Parent topic:Transferring data

Receiving data

When a data packet (sent using one of the methods described in Section 6.5.1) is received by the destination node, it is put into a message queue. A zps_EVENT_AF_DATA_INDICATION stack event is generated on the destination node to indicate that a data packet has arrived (the destination endpoint is indicated in this event). The packet must then be collected from the message queue using the function ZQ_bZQueueReceive().

Note:

  • Note 1: In case a data packet is received from another network by means of an inter-PAN transfer, the zps_EVENT_APS_INTERPAN_DATA_INDICATION stack event is generated. The data packet is passed to the endpoint that supports the specified cluster. The application must always handle these inter-PAN packets and release the APDU instances (see below). The event will only be generated if the inter-PAN feature has been enabled via the ZPS Configuration Editor. If an application transmits inter-PAN messages but does not need to receive them, the application must enable inter-PAN in the ZPS Configuration Editor and handle any zps_EVENT_APS_INTERPAN_DATA_INDICATION events by releasing the APDU instances.

  • Note 2: In the case of the arrival of a response packet which is destined for the ZDO, a zps_EVENT_AF_DATA_INDICATION stack event is generated with a destination endpoint of 0. It is necessary for the application to call the function zps_bAplZdpUnpackResponse() to extract the response data from the event.

An End Device that is asleep would be unable to receive a data packet directly, so the data is buffered by its parent for collection later. The End Device must explicitly request this data, once awake. This method of receiving data is called data polling and is described in Section 6.5.3.

Once a data packet has been collected from a message queue, the data can be extracted from the APDU instance using the PDUM function PDUM_u16APduInstanceReadNBO(). The APDU instance must then be released using the PDUM function PDUM_eAPduFreeAPduInstance().

Parent topic:Transferring data

Polling for Data

In the case of an End Device which is capable of sleeping, messages are not delivered directly to the device, since it may be asleep when the messages arrive. Instead, the messages are temporarily buffered by the End Device’s parent. Once awake, the End Device can then ask or ‘poll’ its parent for data.

Note: End Devices that are not enabled for sleep can receive messages directly and therefore do not need to poll. An End Device is pre-configured as either sleeping or non-sleeping via the End Device parameter Sleeping in the ZPS Configuration Editor (see Section 12.4.2).

Data polling is performed using the function zps_eAplZdoPoll() in the End Device application. This function requests the buffered data and should normally be called immediately after waking from sleep. If the poll request is successfully sent to the parent, a zps_EVENT_NWK_POLL_CONFIRM stack event will occur on the End Device. The subsequent arrival of data from the parent is indicated by the stack event zps_EVENT_AF_DATA_INDICATION. Any messages forwarded from the parent should then be collected from the relevant message queue using the function ZQ_bZQueueReceive(), just as for normal data reception described in Section 6.5.2.

Application design issues concerned with transferring data to a sleeping End Device are outlined in Appendix B.2.

Parent topic:Transferring data

Security in data transfers

The ‘send data’ functions for unicast, broadcast, group transfer and bound transfer contain a parameter to select the required security setting for the protection of the sent message. In the NXP ZigBee PRO software, there are currently three security options, as follows:

  • No security

  • Network-level security

  • Application-level security

Application-level security is only available for unicast and bound transfers, while network-level security is available for all transfer types except inter-PAN transfers.

Network-level and application-level security are detailed in Section 5.8.

Note:

  1. No security is available for inter-PAN transfers (to other networks).

  2. When application-level security is used in sending data, the IEEE/MAC address and network address of the target node must be available through the local Address Map table - see Section 5.2.3.

Parent topic:Transferring data

Parent topic:Application coding with ZigBee PRO APIs