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