Data Transfer functions

The AF Data Transfer functions are used to request the transmission of data, in the form of an Application Protocol Data Unit (APDU), to one or more remote nodes.

The functions are listed below.

Note: Functions for handling APDUs are provided in the PDUM API, described in the JN51xx Core Utilities User Guide (JNUG3133).

APDUs for Requests and Responses

A request generated by this API is sent in an APDU (Application Protocol Data Unit). A local APDU instance for the request must first be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance(). This function returns a handle for the APDU instance, which is subsequently used in the relevant AF API request function. Once the request has been successfully sent, the APDU instance is automatically de-allocated by the stack (there is no need for the application to de-allocate it).

Note: If the request is not successfully sent (the send function does not return ZPS_E_SUCCESS), then the APDU instance is not automatically de-allocated and the application should de-allocate it using the PDUM function PDUM_eAPduFreeAPduInstance().

When a response is subsequently received, the stack automatically allocates a local APDU instance and includes its handle in the notification event for the response. Once the response has been dealt with, the application must de-allocate the APDU instance using the function PDUM_eAPduFreeAPduInstance().

ZPS_eAplAfApsdeDataReq

ZPS\_teStatus ZPS\_eAplAfApsdeDataReq\(
        PDUM\_thAPduInstance hAPduInst,
        ZPS\_tsAfProfileDataReq *psProfileDataReq,
        uint8 *pu8SeqNum);

Description

This function submits a request to send data to a remote node, with no restrictions on the type of transmission, destination address, destination application profile, destination cluster and destination endpoint number - these destination parameters do not need to be known to the stack or defined in the ZPS configuration. In this sense, this is most general of the Data Transfer functions.

The destination details and type of transmission are specified in the function call in a ZPS_tsAfProfileDataReqstructure (see Section 8.2.3.4).

The data is sent in an Application Protocol Data Unit (APDU) instance. This instance can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, this function call fails (and returns ZPS_E_ADSU_TOO_LONG). To send large APDUs, use the function ZPS_eAplAfUnicastAckDataReq(), which automatically implements data fragmentation (if required).

Once the sent data has reached the first hop node in the route to its destination, a ZPS_EVENT_APS_DATA_CONFIRM event is generated on the local node.

Parent topic:ZPS_eAplAfApsdeDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent.
*psProfileDataReq: Pointer to structure containing the details for the transmission (see Section 8.2.3.4).
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL.

Parent topic:ZPS_eAplAfApsdeDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfApsdeDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfUnicastDataReq

ZPS\_teStatus ZPS\_eAplAfUnicastDataReq\(
        PDUM\_thAPduInstance hAPduInst,
        uint16 u16ClusterId,
        uint8 u8SrcEndpoint,
        uint8 u8DstEndpoint,
        uint16 u16DestAddr,
        ZPS\_teAplAfSecurityMode eSecurityMode,
        uint8 u8Radius,
        uint8 *pu8SeqNum);

Description

This function submits a request to send data to a remote node (unicast), using the remote node’s network address. You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint), as well as the network address of the remote node and the destination endpoint on the node.

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, this function call will fail (and return ZPS_E_ADSU_TOO_LONG). To send large APDUs, use the function ZPS_eAplAfUnicastAckDataReq(), which automatically implements data fragmentation (if required).

Once the sent data has reached the first hop node in the route to its destination, a ZPS_EVENT_APS_DATA_CONFIRM event will be generated on the local node.

If data is sent using this function to a destination for which a route has not already been established, the data will not be sent and a route discovery will be performed instead. In this case, the function will return ZPS_NWK_ENUM_ROUTE_ERROR and must later be re-called to send the data (see Note under Section 6.5.1.1, “Unicast”).

Security (encryption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfUnicastDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
u8DstEndpoint: Destination endpoint number (1-240) on remote node
u16DstAddr: Network address of destination node
eSecurityMode: Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE (Application-level security using link key and network key)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_SECURE | ZPS_E_APL_AF_EXT_NONCE (Application-level security using link key and network key with the extended NONCE included in the frame)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL

Parent topic:ZPS_eAplAfUnicastDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfUnicastDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfUnicastIeeeDataReq

ZPS\_teStatus ZPS\_eAplAfUnicastIeeeDataReq(
        PDUM\_thAPduInstance hAPduInst,
        uint16 u16ClusterId,
        uint8 u8SrcEndpoint,
        uint8 u8DstEndpoint,
        uint64 u64DestAddr,
        ZPS\_teAplAfSecurityMode eSecurityMode,
        uint8 u8Radius,
        uint8 *pu8SeqNum);

Description

This function submits a request to send data to a remote node (unicast), using the remote node’s IEEE (MAC) address. You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint), as well as the IEEE address of the remote node and the destination endpoint on the node.

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, this function call will fail (and return ZPS_E_ADSU_TOO_LONG). To send large APDUs, use the function ZPS_eAplAfUnicastIeeeAckDataReq(), which automatically implements data fragmentation (if required).

Once the sent data has reached the first hop node in the route to its destination, a ZPS_EVENT_APS_DATA_CONFIRM event is generated on the local node.

If users try to send data using this function to a destination for which a route has not already been established, the data is not sent. Instead, a route discovery is performed. In this case, the function returns ZPS_NWK_ENUM_ROUTE_ERROR and must later be re-called to send the data (see Note under Section 6.5.1.1, “Unicast”).

Security (encryption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfUnicastIeeeDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
u8DstEndpoint: Destination endpoint number (1-240) on remote node
u64DestAddr: IEEE (MAC) address of destination node
eSecurityMode: Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE (Application-level security using link key and network key)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_SECURE | ZPS_E_APL_AF_EXT_NONCE (Application-level security using link key and network key with the extended NONCE included in the frame)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL

Parent topic:ZPS_eAplAfUnicastIeeeDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfUnicastIeeeDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfUnicastAckDataReq

ZPS\_teStatus ZPS\_eAplAfUnicastAckDataReq(
                PDUM\_thAPduInstance hAPduInst,
                uint16 u16ClusterId,
                uint8 u8SrcEndpoint,
                uint8 u8DstEndpoint,
                uint16 u16DestAddr,
                ZPS\_teAplAfSecurityMode eSecurityMode,
                uint8 u8Radius,
                uint8 *pu8SeqNum);

Description

This function submits a request to send data to a remote node (unicast), using the remote node’s network address, and requires an acknowledgment to be returned by the remote node once the data reaches its destination. You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint), as well as the network address of the remote node and the destination endpoint on the node.

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, the APDU is broken up into fragments (NPDUs) for transmission. For this to happen, users should enable fragmentation by setting the ZigBee network parameter Maximum Number of Transmitted Simultaneous Fragmented Messages to a non-zero value.

If data is sent using this function to a destination for which a route has not already been established, the data fails to send and a route discovery is performed instead. In this case, the function returns ZPS_NWK_ENUM_ROUTE_ERROR and must later be re-called to send the data (see Note under Section 6.5.1.1, “Unicast”).

Once the sent data has reached the first hop node in the route to its destination, a ZPS_EVENT_APS_DATA_CONFIRM event is generated on the local node. Then, once an acknowledgment has been received from the destination node, a ZPS_EVENT_APS_DATA_ACK is generated on the sending node.

Security (encyption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfUnicastAckDataReq

Parameters

hAPduInst Handle of APDU instance to be sent
u16ClusterId Identifier of relevant output cluster on source endpoint
u8SrcEndpoint Source endpoint number (1-240) on local node
u8DstEndpoint Destination endpoint number (1-240) on remote node
u16DstAddr Network address of destination node
eSecurityMode Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE (Application-level security using link key and network key)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_SECURE | ZPS_E_APL_AF_EXT_NONCE (Application-level security using link key and network key with the extended NONCE included in the frame)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used).
*pu8SeqNum Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL.

Parent topic:ZPS_eAplAfUnicastAckDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfUnicastAckDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfUnicastIeeeAckDataReq

ZPS\_teStatus ZPS\_eAplAfUnicastIeeeAckDataReq\(
          PDUM\_thAPduInstance hAPduInst,
         uint16 u16ClusterId,
         uint8 u8SrcEndpoint,
         uint8 u8DstEndpoint,
         uint64 u64DestAddr,
         ZPS\_teAplAfSecurityMode eSecurityMode,
         uint8 u8Radius,
         uint8 *pu8SeqNum);

Description

This function submits a request to send data to a remote node (unicast), using the remote node’s IEEE (MAC) address. The function also requires an acknowledgment to be returned by the remote node once the data reaches its destination. You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint), as well as the IEEE address of the remote node and the destination endpoint on the node.

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, the APDU can be broken up into fragments (NPDUs) for transmission. To enable this fragmentation, users should set the ZigBee network parameter Maximum Number of Transmitted Simultaneous Fragmented Messagesto a non-zero value.

If data is sent using this function to a destination for which a route has not already been established, the data is not sent and a route discovery is performed instead. In this case, the function returns ZPS_NWK_ENUM_ROUTE_ERROR and must later be re-called to send the data (see Note under Section 6.5.1.1, “Unicast”).

Once the sent data has reached the first hop node in the route to its destination, a ZPS_EVENT_APS_DATA_CONFIRM event will be generated on the local node. Then, once an acknowledgment has been received from the destination node, a ZPS_EVENT_APS_DATA_ACK is generated on the sending node.

Security (encyption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfUnicastIeeeAckDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
u8DstEndpoint: Destination endpoint number (1-240) on remote node
u64DestAddr: IEEE (MAC) address of destination node
eSecurityMode: Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE (Application-level security using link key and network key)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_SECURE | ZPS_E_APL_AF_EXT_NONCE (Application-level security using link key and network key with the extended NONCE included in the frame)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used).
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL.

Parent topic:ZPS_eAplAfUnicastIeeeAckDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfUnicastIeeeAckDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfGroupDataReq

ZPS\_teStatus ZPS\_eAplAfGroupDataReq\(
        PDUM\_thAPduInstance hAPduInst,
        uint16 u16ClusterId,
        uint8 u8SrcEndpoint,
        uint16 u16DstGroupAddr,
        ZPS\_teAplAfSecurityMode eSecurityMode,
        uint8 u8Radius,
        uint8 *pu8SeqNum);

Description

This function submits a request to send data to a group of endpoints located on one or more nodes (group multicast). Users must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint) as well as the ‘group address’ of the group of destination endpoints. A group is set up using the function ZPS_eAplZdoGroupEndpointAdd(). The data is actually broadcast to all network nodes and each recipient node assesses whether it has endpoints in the specified group.

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, this function call fails (and returns ZPS_E_ADSU_TOO_LONG). Once the data is transmitted, a ZPS_EVENT_APS_DATA_CONFIRM event is generated on the local node.

Security (encyption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfGroupDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
u16DstGroupAddr: Group address of destination endpoints
eSecurityMode: Security mode for data transfer, one of:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL.

Parent topic:ZPS_eAplAfGroupDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfGroupDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfBroadcastDataReq

ZPS\_teStatus ZPS\_eAplAfBroadcastDataReq\(
      PDUM\_thAPduInstance hAPduInst,
      uint16 u16ClusterId,
      uint8 u8SrcEndpoint,
      uint8 u8DstEndpoint,
      ZPS\_teAplAfBroadcastMode eBroadcastMode,
      ZPS\_teAplAfSecurityMode eSecurityMode,
      uint8 u8Radius,
      uint8 *pu8SeqNum);

Description

This function submits a request to send data to all network nodes that conform to the specified broadcast mode. You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint), as well as the destination endpoint(s) on the remote nodes.

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, this function call fails (and return ZPS_E_ADSU_TOO_LONG).

Following this function call, the APDU may be broadcast up to four times by the source node (in addition, the APDU may be subsequently re-broadcast up to four times by each intermediate routing node). If the transmission is successful, the event ZPS_EVENT_APS_DATA_CONFIRM is generated on the local node.

Security (encyption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfBroadcastDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
u8DstEndpoint: Destination endpoint number (1-240) on remote node, or 255 for all endpoints on node
eBroadcastMode: Type of broadcast, one of:
- ZPS_E_BROADCAST_ALL (all nodes)
- ZPS_E_BROADCAST_ALL RX_ON (all nodes with radio receiver permanently enabled)
- ZPS_E_BROADCAST_ZC_ZR (all Routers and Coordinator)
eSecurityMode: Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL

Parent topic:ZPS_eAplAfBroadcastDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfBroadcastDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfBoundDataReq

ZPS\_teStatus ZPS\_eAplAfBoundDataReq\(
        PDUM\_thAPduInstance hAPduInst,
        uint16 u16ClusterId,
        uint8 u8SrcEndpoint,
        ZPS\_teAplAfSecurityMode eSecurityMode,
        uint8 u8Radius,
        uint8 *pu8SeqNum);

Description

This function submits a request to send data to all nodes/endpoints to which the source node/endpoint has been previously bound (using the binding functions, described in Section 9.1.3). You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint).

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, this function call fails (and return ZPS_E_ADSU_TOO_LONG).

Once the sent data has reached the first hop node in the route to its destination(s), a ZPS_EVENT_BIND_REQUEST_SERVER event is generated on the local node. This event reports the status of the bound transmission, including the number of bound endpoints for which the transmission has failed.

Security (encyption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfBoundDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
eSecurityMode: Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE (Application-level security using link key and network key)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_SECURE | ZPS_E_APL_AF_EXT_NONCE (Application-level security using link key and network key with the extended NONCE included in the frame)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL.

Parent topic:ZPS_eAplAfBoundDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfBoundDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfBoundAckDataReq

 ZPS\_teStatus ZPS\_eAplAfBoundAckDataReq(
               PDUM\_thAPduInstance hAPduInst,
               uint16 u16ClusterId,
               uint8 u8SrcEndpoint,
               ZPS\_teAplAfSecurityMode eSecurityMode,
               uint8 u8Radius,
               uint8 *pu8SeqNum);

Description

This function submits a request to send data to all nodes/endpoints to which the source node/endpoint has been previously bound (using the binding functions, described in Section 9.1.3) and requires an acknowledgment to be returned by the remote node(s) once the data reaches its destination(s). You must specify the local endpoint and output cluster from which the data originates (the cluster must be in the Simple descriptor for the endpoint).

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the network, the APDU can be broken up into fragments (NPDUs) for transmission. To enable this fragmentation, set the ZigBee network parameter Maximum Number of Transmitted Simultaneous Fragmented Messages to a non-zero value.

Once the sent data reaches its final destination node(s), a ZPS_EVENT_BIND_REQUEST_SERVER event is generated on the local node. This event reports the status of the bound transmission, including the number of bound endpoints for which the transmission has failed.

Security (encyption/decryption) can be applied to the APDU, where this security can be implemented at the Application layer or the network (ZigBee) layer, or both.

Parent topic:ZPS_eAplAfBoundAckDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of relevant output cluster on source endpoint
u8SrcEndpoint: Source endpoint number (1-240) on local node
eSecurityMode: Security mode for data transfer:
- ZPS_E_APL_AF_UNSECURE (no security enabled)
- ZPS_E_APL_AF_SECURE (Application-level security using link key and network key)
- ZPS_E_APL_AF_SECURE_NWK (Network-level security using network key)
- ZPS_E_APL_AF_SECURE | ZPS_E_APL_AF_EXT_NONCE (Application-level security using link key and network key with the extended NONCE included in the frame)
- ZPS_E_APL_AF_WILD_PROFILE (May be combined with above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor)
u8Radius: Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
*pu8SeqNum: Pointer to location to receive sequence number assigned to data transfer request. If not required, set to NULL.

Parent topic:ZPS_eAplAfBoundAckDataReq

Returns

ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4

Parent topic:ZPS_eAplAfBoundAckDataReq

Parent topic:Data Transfer functions

ZPS_eAplAfInterPanDataReq

ZPS\_teStatus ZPS\_eAplAfInterPanDataReq\(
                     PDUM\_thAPduInstance hAPduInst,
                     uint16 u16ClusterId,
                     uint16 u16ProfileId,
                     ZPS\_tsInterPanAddress *psDstAddr,
                     uint8 u8Handle);

Description

This function submits a request to send data to one or more nodes in another ZigBee PRO network - that is, to implement an inter-PAN transmission. The destination for the data is specified in a structure (detailed in Section 8.2.3.3) which contains:

PAN ID of destination network (a broadcast to all reachable ZigBee PRO networks can also be configured)
Address of destination node (this can be an IEEE/MAC or network address for a single node, a group address for multiple nodes or a broadcast address for all nodes).

The data is sent in an Application Protocol Data Unit (APDU) instance, which can be allocated using the PDUM function PDUM_hAPduAllocateAPduInstance() and then written to using PDUM_u16APduInstanceWriteNBO().

If the APDU size is larger than the maximum packet size allowed on the local network, this function call fails (and returns ZPS_E_ADSU_TOO_LONG).

Once the sent data reaches the first hop node in the route to its destination, a ZPS_EVENT_APS_INTERPAN_DATA_CONFIRM event is generated on the local node. In case of a broadcast or group multicast, this event is simply generated once the data has been sent from the local node.

Security (encyption/decryption) cannot be applied to inter-PAN transmissions.

Parent topic:ZPS_eAplAfInterPanDataReq

Parameters

hAPduInst: Handle of APDU instance to be sent
u16ClusterId: Identifier of cluster for which data is intended at destination (must be a cluster of the application profile specified below)
u16ProfileId: Identifier of application profile for which data is intended at destination
psDstAddr: Pointer to structure containing destination PAN ID and address (see Section 8.2.3.3)
u8Handle: Handle for internal use (set to any value)

Parent topic:ZPS_eAplAfInterPanDataReq

Returns

ZPS_E_SUCCESS.
ZPS_APL_APS_E_ILLEGAL_REQUEST.
MAC return codes, listed and described in Section 11.2.4.

Parent topic:ZPS_eAplAfInterPanDataReq

Parent topic:Data Transfer functions

ZPS_u8AplGetMaxPayloadSize

uint8 ZPS_u8AplGetMaxPayloadSize(void *pvApl,
                               uint16 u16Addr);

Description

This function obtains the effective payload size, in bytes, within an IEEE802.15.4 data frame to be sent to the node with the specified network address. The handle of the relevant Application layer instance must also be specified, which can be obtained using ZPS_pvAplZdoGetAplHandle().

An IEEE802.15.4 data frame contains 127 bytes, but the effective payload is reduced by the various IEEE802.15.4 and ZigBee headers. The function returns the size of the payload available for data but does not take into account bytes needed for ZCL cluster headers (so may not reflect the exact amount of space available for data).

Parent topic:ZPS_u8AplGetMaxPayloadSize

Parameters

pvApl: Handle of handle for the Application layer instance
u16Addr: 16-bit network address of node to which data is to be sent

Parent topic:ZPS_u8AplGetMaxPayloadSize

Returns

Number of data frame payload bytes available for data (ignoring ZCL headers).

Parent topic:ZPS_u8AplGetMaxPayloadSize

Parent topic:Data Transfer functions

Parent topic:AF API functions