AF API functions

The AF API functions are divided into the following categories:

• initializationfunctions, described in Section 8.1.1.

• Data Transferfunctions, described in Section 8.1.2.

• Endpointfunctions, described in Section 8.1.3.

• Descriptorfunctions, described in Section 8.1.4.

initialization functions

The AF API contains the below initialization functions.

The functions are listed below.

1. ZPS_eAplAfInit

2. ZPS_vAplAfSetMacCapability

3. ZPS_eAplAibSetApsUseExtendedPanId

4. ZPS_vExtendedStatusSetCallback

5. ZPS_bAppAddBeaconFilter

6. ZPS_eAplFormDistributedNetworkRouter

7. ZPS_eAplInitEndDeviceDistributed

8. ZPS_vAplAfEnableMcpsFilter

9. ZPS_vNwkLinkCostCallbackRegister

Note: The function ZPS_eAplAfInit() is mandatory and must be the first network function called in your application.

ZPS_eAplAfInit

ZPS_teStatus ZPS_eAplAfInit(void);

Description

This function initializes the Application Framework and must be the first network function called in your application code. The function first requests a reset of the Network (NWK) layer of the ZigBee PRO stack. It then initializes certain network parameters with values that have been pre-configured using the ZPS Configuration Editor (see Chapter 13, ZPS Configuration Editor). These parameters include the node type and the Extended PAN ID of the network.

The device is started as the pre-configured node type. If this is a Coordinator, the Extended PAN ID of the node is set to the pre-configured value. Note that if a zero value is specified, the Coordinator uses its own IEEE/MAC address for the Extended PAN ID.

Parent topic:ZPS_eAplAfInit

Parameters

None.

Parent topic:ZPS_eAplAfInit

Returns

• ZPS_E_SUCCESS (AF successfully initialized).

• 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_eAplAfInit

Parent topic:initialization functions

ZPS_vAplAfSetMacCapability

void ZPS_vAplAfSetMacCapability(uint8 u8MacCapability);

Description

This function can be used on a Router or End Device to configure the IEEE 802.15.4 MAC capabilities in the Node descriptor. The MAC capabilities are specified in an 8-bit bitmap, detailed in the table below.

MAC capabilities bitmap

Bits	Description
0	Coordinator capability: 1: Node able to act as Coordinator 0: Node not able to act as Coordinator
1	Device type: 1: Full-Function Device (FFD) 0: Reduced-Function Device (RFD) An FFD can act as any node type while an RFD cannot act as the network Coordinator.
2	Power source: 1: Node is mains-powered 0: Node is not mains-powered
3	Receiver on when idle: 1: Receiver enabled during idle periods 0: Receiver disabled during idle periods to conserve power
4-5	Reserved
6	Security capability: 1: High security 0: Standard security
7	Allocate address: 1: Network address should be allocated to node 0: Network address need not be allocated to node

Parent topic:ZPS_vAplAfSetMacCapability

Parameters

• u8MacCapability Bitmap containing the MAC capabilities to be configured (see table above).

Parent topic:ZPS_vAplAfSetMacCapability

Returns

None.

Parent topic:ZPS_vAplAfSetMacCapability

Parent topic:initialization functions

ZPS_eAplAibSetApsUseExtendedPanId

ZPS_teStatus ZPS_eAplAibSetApsUseExtendedPanId
                            (uint64 u64UseExtPanId);

Description

This function can be used to create an application record of the Extended PAN ID (EPID) of the network to which the local device belongs.

• The only use of this function for a Coordinator is described in Section 6.1.1.

• The function should only be called on a Router or End Device in the manner described in Section 6.1.2.

Parent topic:ZPS_eAplAibSetApsUseExtendedPanId

Parameters

u64UseExtPanId Extended PAN ID of network to which device belongs.

Parent topic:ZPS_eAplAibSetApsUseExtendedPanId

Returns

• ZPS_E_SUCCESS (Extended PAN ID record successfully created).

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

• APS return codes, listed and described in Section 11.2.2.

Parent topic:ZPS_eAplAibSetApsUseExtendedPanId

Parent topic:initialization functions

ZPS_vExtendedStatusSetCallback

void ZPS_vExtendedStatusSetCallback(
   tpfExtendedStatusCallBack pfExtendedStatusCallBack);

Description

This function can be used to register a callback function for extended error handling (see (Section 6.7)

The prototype of the callback function is:

ZPS_teExtendedStatus vExtendedStatusCb();

The registered callback function is invoked if a subsequent API function call results in one of the following errors:

• 0xA3: ZPS_APL_APS_E_ILLEGAL_REQUEST

• 0xA6: ZPS_APL_APS_E_INVALID_PARAMETER

• 0xC2: ZPS_NWK_ENUM_INVALID_REQUEST

The callback function returns another error code (from those listed and described in Section 11.2.5), which provides a more specific reason for the error.

Parent topic:ZPS_vExtendedStatusSetCallback

Parameters

pfExtendedStatusCallBackPointer to extended error handling callback function to be registered.

Parent topic:ZPS_vExtendedStatusSetCallback

Returns

None.

Parent topic:ZPS_vExtendedStatusSetCallback

Parent topic:ZPS_vAplAfEnableMcpsFilter

Parent topic:initialization functions

ZPS_bAppAddBeaconFilter

void ZPS_bAppAddBeaconFilter(tsBeaconFilterType *psAppBeaconStruct);

Description

This function can be used to introduce a filter that will be used for filtering beacons in network searches (on a Router or End Device). Beacons can be filtered on the basis of PAN ID, Extended PAN ID, LQI value and device joining status/capacity. The filter details are provided in a tsBeaconFilterTypestructure (see Section 8.2.3.5).

If required, this function should be called immediately before ZPS_eAplZdoDiscoverNetworks(), ZPS_eAplZdoRejoinNetwork() or ZPS_eAplZdoStartStack().

Note: A filter should NOT be implemented unless attempting a join, as this would prevent some stack operations from working correctly.

Once the join or discovery has completed, the filter is automatically removed and needs to be re-instated if a retry is required.

Guidelines on the implementation of beacon filters are provided in , Appendix B.4, “Beacon filtering guidelines”.

Parent topic:ZPS_bAppAddBeaconFilter

Parameters

• * psAppBeaconStruct Pointer to a structure containing the beacon filter details. (see Section 8.2.3.5).

Parent topic:ZPS_bAppAddBeaconFilter

Returns

None.

Parent topic:ZPS_bAppAddBeaconFilter

Parent topic:initialization functions

ZPS_eAplFormDistributedNetworkRouter

ZPS_teStatus ZPS_eAplFormDistributedNetworkRouter(
        ZPS_tsAftsStartParamsDistributed *psStartParms,
        bool_t bSendDeviceAnnce);

Description

This function can be used on a Router node to introduce the node into a distributed security network (see Section 6.10.2). The function must be called on the Router node that creates the distributed security network, therefore, the first node of the new network.

Subsequent Router nodes may be introduced using this function, but could be introduced using other commissioning methods, such as Touchlink.

Parent topic:ZPS_eAplFormDistributedNetworkRouter

Parameters

• psStartParms Pointer to structure containing the start parameter values for the Router- see Section 8.2.3.7.

• bSendDeviceAnnce Boolean indicating whether a device announcement message is to be sent:

  • TRUE - send device announcement

  • FALSE - do not send device announcement

Parent topic:ZPS_eAplFormDistributedNetworkRouter

Returns

• ZPS_E_SUCCESS (network successfully created).

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

• APS return codes, listed and described in Section 11.2.2.

Parent topic:ZPS_eAplFormDistributedNetworkRouter

Parent topic:initialization functions

ZPS_eAplInitEndDeviceDistributed

ZPS_teStatus ZPS_eAplInitEndDeviceDistributed(
            ZPS_tsAftsStartParamsDistributed *psStartParms);

Description

This function can be used on an End Device node to introduce the node into a distributed security network (see Section 6.10.2). This network must have already been created by a Router using the ZPS_eAplFormDistributedNetworkRouter() function. End Device nodes may be introduced into the network in this way or using other commissioning methods, such as Touchlink.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parameters

psStartParms Pointer to structure containing the start parameter values for the End Device - see Section 8.2.3.7, ZPS_tsAftsStartParamsDistributed.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parent topic:ZPS_vAplAfEnableMcpsFilter

Returns

• ZPS_E_SUCCESS (network successfully created).

• NWK return codes, listed and described in Section 11.2.3.

• MAC return codes, listed and described in Section 11.2.4.

• APS return codes, listed and described in Section 11.2.2.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parent topic:initialization functions

ZPS_vAplAfEnableMcpsFilter

void ZPS_vAplAfEnableMcpsFilter(
                    bool bEnableFilter,
                    uint8 u8LinkCostThreshold);

Description

This function allows packet filtering based on ‘link cost’ to be enabled/disabled, as well as some basic configuration of the filtering. Packet filtering is disabled by default.

The default ‘link cost threshold’ is 5. This means that when packet filtering is enabled, received packets with a link cost of 5 or less are discarded by the stack and not queued for processing. The link cost threshold can be modified (from the default value of 5) using this function.

If required, this function can be called at any time after ZPS_eAplAfInit().

For more information on packet filtering and link costs, refer to Section 6.10.3, Filtering packets on LQI Value/Link cost.

Parent topic:ZPS_vAplAfEnableMcpsFilter

Parameters

psStartParms Pointer to structure containing the start parameter values for the End Device - see Section 8.2.3.7, ZPS_tsAftsStartParamsDistributed.

Parent topic:ZPS_eAplInitEndDeviceDistributed

Parent topic:ZPS_vAplAfEnableMcpsFilter

Returns

None.

Parent topic:ZPS_vExtendedStatusSetCallback

Parent topic:ZPS_vAplAfEnableMcpsFilter

Parent topic:initialization functions

ZPS_vNwkLinkCostCallbackRegister

void ZPS_vNwkLinkCostCallbackRegister(void *pvFn);

Description

This function can be used to register a user-defined callback function that defines custom mappings between LQI values and link costs that are to be used in packet filtering, based on link cost. When packet filtering is enabled, the stack uses a default set of mappings, detailed in Section 6.10.3.1. The callback function is only needed if custom mappings are to be used that will over-ride the default mappings. If required, this registration function must be called before ZPS_eAplAfInit(), and on both cold and warm starts.

The user-defined callback function to be registered has the following prototype:

uint8 APP_u8LinkCost(uint8 u8Lqi);

This callback function translates a measured LQI value (u8Lqi) into a link cost value. An example function is given in Section 6.10.3.3.

For more information on packet filtering and link costs, refer to Section 6.10.3.

Parent topic:ZPS_vNwkLinkCostCallbackRegister

Parameters

pvFn Pointer to user-defined callback function to be registered.

Parent topic:ZPS_vNwkLinkCostCallbackRegister

Returns

None.

Parent topic:ZPS_vNwkLinkCostCallbackRegister

Parent topic:initialization functions

Parent topic:AF API functions

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.

1. ZPS_eAplAfApsdeDataReq

2. ZPS_eAplAfUnicastDataReq

3. ZPS_eAplAfUnicastIeeeDataReq

4. ZPS_eAplAfUnicastAckDataReq

5. ZPS_eAplAfUnicastIeeeAckDataReq

6. ZPS_eAplAfGroupDataReq

7. ZPS_eAplAfBroadcastDataReq

8. ZPS_eAplAfBoundDataReq

9. ZPS_eAplAfBoundAckDataReq

10. ZPS_eAplAfInterPanDataReq

11. ZPS_u8AplGetMaxPayloadSize

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

Endpoint functions

The AF Endpoint functions are used to control and monitor the states of endpoints on the local node.

The functions are listed below.

1. ZPS_vAplAfSetEndpointState

2. ZPS_eAplAfGetEndpointState

3. ZPS_eAplAfSetEndpointDiscovery

4. ZPS_eAplAfGetEndpointDiscovery

ZPS_vAplAfSetEndpointState

ZPS\_teStatus ZPS\_eAplAfSetEndpointState\(
                                      uint8 u8Endpoint,
                                      bool bEnabled);

Description

This function puts the specified endpoint on the local node into the specified state (enabled or disabled).

Parent topic:ZPS_vAplAfSetEndpointState

Parameters

• u8Endpoint: Endpoint number (on local node)

• bEnabled: State in which to put endpoint, one of:

  • TRUE: enable endpoint

  • FALSE: disable endpoint

Parent topic:ZPS_vAplAfSetEndpointState

Returns

• ZPS_E_SUCCESS (endpoint state successfully set)

• 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_vAplAfSetEndpointState

Parent topic:Endpoint functions

ZPS_eAplAfGetEndpointState

ZPS\_teStatus ZPS\_eAplAfGetEndpointState\(
                                  uint8 u8Endpoint,
                                  bool *pbEnabled);

Description

This function obtains the current state (enabled or disabled) of the specified endpoint on the local node.

Parent topic:ZPS_eAplAfGetEndpointState

Parameters

• u8Endpoint: Endpoint number (on local node)

• *pbEnabled: Pointer to location to receive endpoint state. The returned state is one of:

  • TRUE: endpoint enabled

  • FALSE: endpoint disabled

Parent topic:ZPS_eAplAfGetEndpointState

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_eAplAfGetEndpointState

Parent topic:Endpoint functions

ZPS_eAplAfSetEndpointDiscovery

ZPS\_teStatus ZPS\_eAplAfSetEndpointDiscovery\(
                                    uint8 u8Endpoint,
                                    uint16 u16ClusterId,
                                    bool bOutput,
                                    bool bDiscoverable);

Description

This function sets the discoverable state of the specified cluster of the specified endpoint on the local node - that is, whether the cluster/endpoint will be included in ‘device discoveries’ initiated on the network.

If the cluster/endpoint is discoverable, it appears in the Simple descriptor of the local node and is also included in match results requested using the function ZPS_eAplZdpMatchDescRequest().

The initial discoverable state of the cluster/endpoint is pre-set using the ZPS Configuration Editor (see Chapter 13).

Parent topic:ZPS_eAplAfSetEndpointDiscovery

Parameters

• u8Endpoint: Endpoint number (on local node)

• u16ClusterId: Cluster ID

• bOutput: Type of cluster (output or input), one of:

  • TRUE: Output cluster

  • FALSE: Input cluster

• bDiscoverable: Discoverable state to set, one of:

  • TRUE: Discoverable

  • FALSE: Not discoverable

Parent topic:ZPS_eAplAfSetEndpointDiscovery

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_eAplAfSetEndpointDiscovery

Parent topic:Endpoint functions

ZPS_eAplAfGetEndpointDiscovery

ZPS\_teStatus ZPS\_eAplAfGetEndpointDiscovery\(
                                  uint8 u8Endpoint,
                                  uint16 u16ClusterId,
                                  bool bOutput,
                                  bool\_t *pbDiscoverable);

Description

This function obtains the discoverable state of the specified cluster of the specified endpoint on the local node - that is, whether the cluster/endpoint will be included in ‘device discoveries’ initiated on the network.

If the cluster/endpoint is discoverable, it appears in the Simple descriptor of the local node and is also included in match results requested using the function ZPS_eAplZdpMatchDescRequest().

The initial discoverable state of the cluster/endpoint is pre-set using the ZPS Configuration Editor (see Chapter 13). The state can subsequently be changed at runtime using the function ZPS_eAplAfSetEndpointDiscovery().

Parent topic:ZPS_eAplAfGetEndpointDiscovery

Parameters

• u8Endpoint: Endpoint number (on local node)

• u16ClusterId: Cluster ID

• bOutput: Type of cluster (output or input), one of:

  • TRUE: Output cluster

  • FALSE: Input cluster

• *pbDiscoverable: Pointer to location to receive discoverable state, which is one of the below:

  • TRUE: Discoverable

  • FALSE: Not discoverable

Parent topic:ZPS_eAplAfGetEndpointDiscovery

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_eAplAfGetEndpointDiscovery

Parent topic:Endpoint functions

Parent topic:AF API functions

Descriptor functions

The AF Descriptor functions allow ZigBee descriptors for the local node to be copied to and from the context area of the ZigBee PRO stack. The functions are listed below.

1. ZPS_eAplAfGetNodeDescriptor

2. ZPS_eAplAfGetNodePowerDescriptor

3. ZPS_eAplAfGetSimpleDescriptor

ZPS_eAplAfGetNodeDescriptor

ZPS\_teStatus ZPS\_eAplAfGetNodeDescriptor\(
            ZPS\_tsAplAfNodeDescriptor *psDesc);

Description

This function copies the Node descriptor (for the local node) from the context area of the stack to the specified structure (the descriptor is returned through the function’s parameter).

Parent topic:ZPS_eAplAfGetNodeDescriptor

Parameters

* psDesc: Pointer to structure (see Section 8.2.1.1) to receive Node descriptor.

Parent topic:ZPS_eAplAfGetNodeDescriptor

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_eAplAfGetNodeDescriptor

Parent topic:Descriptor functions

ZPS_eAplAfGetNodePowerDescriptor

ZPS\_teStatus ZPS\_eAplAfGetNodePowerDescriptor\(
            ZPS\_tsAplAfNodePowerDescriptor *psDesc);

Description

This function copies the Node Power descriptor (for the local node) from the context area of the stack to the specified structure (the descriptor is returned through the function’s parameter).

Parent topic:ZPS_eAplAfGetNodePowerDescriptor

Parameters

* psDesc Pointer to structure (see Section 8.2.1.2) to receive Node Power descriptor

Parent topic:ZPS_eAplAfGetNodePowerDescriptor

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_eAplAfGetNodePowerDescriptor

Parent topic:Descriptor functions

ZPS_eAplAfGetSimpleDescriptor

ZPS\_teStatus ZPS\_eAplAfGetSimpleDescriptor\(
        uint8 u8Endpoint,
        ZPS\_tsAplAfSimpleDescriptor *psDesc);

Description

This function copies the Simple descriptor for the specified endpoint (on the local node) from the context area of the stack to the specified structure (the descriptor is returned through the function’s parameter).

Parent topic:ZPS_eAplAfGetSimpleDescriptor

Parameters

* psDesc Pointer to structure (see Section 8.2.1.3) to receive Simple descriptor

Parent topic:ZPS_eAplAfGetSimpleDescriptor

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_eAplAfGetSimpleDescriptor

Parent topic:Descriptor functions

Parent topic:AF API functions

Other functions

This section described other functions in the AF API. These functions are listed below:

• ZPS_vSaveAllZpsRecords

• ZPS_bAplAfSetEndDeviceTimeout

• ZPS_eAplAfSendKeepAlive

ZPS_vSaveAllZpsRecords

void ZPS\_vSaveAllZpsRecords\(void\);

Description

This function saves to Non-Volatile Memory (NVM) all the NVM records related to the ZigBee PRO stack. This function must be used in conjunction with the Non-Volatile Memory Manager (NVM), which is described in the JN51xx Core Utilities User Guide (JNUG3133).

Parent topic:ZPS_vSaveAllZpsRecords

Parameters

None

Parent topic:ZPS_vSaveAllZpsRecords

Returns

None

Parent topic:ZPS_vSaveAllZpsRecords

Parent topic:Other functions

ZPS_bAplAfSetEndDeviceTimeout

bool ZPS\_bAplAfSetEndDeviceTimeout
                \(teZedTimeout eZedTimeout);

Description

This function can be used on an End Device to configure a timeout period for the End Device Aging mechanism, which is described in Section 6.10.1.

The End Device communicates this timeout period to its parent on joining the network. The parent applies this timeout to the ‘keep-alive’ packets sent from the End Device child using the function ZPS_eAplAfSendKeepAlive(). If the parent does not receive a keep-alive packet from the End Device before the timeout expires, then the parent assumes the End Device is no longer active and discards it.

Parent topic:ZPS_bAplAfSetEndDeviceTimeout

Parameters

eZedTimeout Enumeration indicating timeout period to be set - one of the below:

• ZED_TIMEOUT_10_SEC (10 seconds)

• ZED_TIMEOUT_2_MIN (2 minutes)

• ZED_TIMEOUT_4_MIN (4 minutes)

• ZED_TIMEOUT_8_MIN (8 minutes)

• ZED_TIMEOUT_16_MIN (16 minutes)

• ZED_TIMEOUT_32_MIN (32 minutes)

• ZED_TIMEOUT_64_MIN (64 minutes)

• ZED_TIMEOUT_128_MIN (128 minutes)

• ZED_TIMEOUT_256_MIN (256 minutes)

• ZED_TIMEOUT_512_MIN (512 minutes)

• ZED_TIMEOUT_1024_MIN (1024 minutes)

• ZED_TIMEOUT_2048_MIN (2048 minutes)

• ZED_TIMEOUT_4096_MIN (4096 minutes)

• ZED_TIMEOUT_8192_MIN (8192 minutes)

• ZED_TIMEOUT_16384_MIN (16384 minutes)

Parent topic:ZPS_bAplAfSetEndDeviceTimeout

Returns

• TRUE - timeout successfully set

• FALSE - timeout not set

Parent topic:ZPS_bAplAfSetEndDeviceTimeout

Parent topic:Other functions

ZPS_eAplAfSendKeepAlive

ZPS\_teStatus ZPS\_eAplAfSendKeepAlive\(void\);

Description

This function can be used on an End Device to send a ‘keep-alive’ packet to its parent as part of the End Device Aging mechanism, which is described in Section 6.10.1. This packet informs the parent that the End Device is still active, so that the parent does not discard the child.

The parent must receive at least one keep-alive packet from the End Device within the timeout period defined using the function ZPS_bAplAfSetEndDeviceTimeout(). Otherwise, the parent assumes that the child is no longer active and discard the child. It is recommended that at least three keep-alive packets are sent within the timeout period to ensure that the End Device child is not accidentally discarded due to missed keep-alive packets.

A keep-alive packet can take the form of a MAC Data Poll or an End Device Timeout Request, as required by the parent - the keep-alive packet type is configured in the NIB on the parent but, by default, both packets types are configured to be acceptable in the NXP software. This function automatically sends the appropriate keep-alive packet type but when both packet types are acceptable, a Data Poll is sent. Both packet types have the effect of re-starting the timeout for the End Device on the parent. When a Data Poll packet is used, the parent may also return pending data to the End Device, indicated by a ZPS_EVENT_AF_DATA_INDICATION event on the End Device.

Parent topic:ZPS_eAplAfSendKeepAlive

Parameters

None

Parent topic:ZPS_eAplAfSendKeepAlive

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_eAplAfSendKeepAlive

Parent topic:Other functions

Parent topic:AF API functions

Parent topic:Application Framework (AF) API