Application Framework (AF) API

The chapter describes the resources of the Application Framework (AF) API. This API is concerned with transmitting data, controlling/monitoring local endpoints, and copying descriptors to/from the context area of the stack. The API is defined in the header file zps_apl_af.h.

In this chapter:

AF API functions

The AF API functions are divided into the following categories:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Parent topic:ZPS_eAplAfSendKeepAlive

Parent topic:Other functions

Parent topic:AF API functions

Parent topic:Application Framework (AF) API

AF structures

This section describes the structures of the Application Framework (AF) API. These include the following categories of structure:

Descriptor structures

These structures are used to represent the following descriptors that contain information about the host node:

  • Node descriptor

  • Node Power descriptor

  • Simple descriptor

The structures are listed below.

  1. ZPS_tsAplAfNodeDescriptor

  2. ZPS_tsAplAfNodePowerDescriptor

  3. ZPS_tsAplAfSimpleDescriptor

ZPS_tsAplAfNodeDescriptor

The AF Node descriptor structure ZPS_tsAplAfNodeDescriptoris shown below.

typedef struct {
    uint32 :                      8;/* padding */
    uint32 eLogicalType :         3;
    uint32 bComplexDescAvail :    1;
    uint32 bUserDescAvail :       1;
    uint32 eReserved :            3; /* reserved */
    uint32 eFrequencyBand :       5;
    uint32 eApsFlags :            3;
    uint32 u8MacFlags :           8;
    uint16 u16ManufacturerCode;
    uint8 u8MaxBufferSize;
    uint16 u16MaxRxSize;
    uint16 u16ServerMask;
    uint16 u16MaxTxSize;
    uint8 u8DescriptorCapability;
} ZPS_tsAplAfNodeDescriptor;

where:

  • eLogicalTypecontains 3 bits (bits 0-2) indicating the ZigBee device type of the node, as follows:

    • 000: Coordinator

    • 001: Router

    • 010: End Device

  • bComplexDescAvailis set to 1 if there is a Complex descriptor available for node.

  • bUserDescAvailis set to 1 if there is a User descriptor available for node.

  • eReservedis reserved.

  • eFrequencyBandcontains 5 bits detailing the frequency bands supported by the node, as follows (a bit is set to 1 if the corresponding band is supported):

    • Bit 0: 868-868.6 MHz

    • Bit 2: 902-928 MHz

    • Bit 3: 2400-2483.5 MHz

    • Bits 1 and 4 are reserved

  • eApsFlagsis not currently supported and set to zero.

  • eMacFlagscontains 8 bits (bits 0-7) indicating the node capabilities, as required by the IEEE 802.15.4 MAC sub-layer. These node capability flags are described in the table: Table.

  • u16ManufacturerCodecontains 16 bits (bits 0-15) indicating the manufacturer code for the node, where this code is allocated to the manufacturer by the ZigBee Alliance.

  • u8MaxBufferSizeis the maximum size, in bytes, of an NPDU (Network Protocol Data Unit).

  • u16MaxRxSizeis the maximum size, in bytes, of an APDU (Application Protocol Data Unit). This value can be greater than the value of u8MaxBufferSize, due to the fragmentation of an APDU into NPDUs.

  • u16ServerMaskcontains 8 bits (bits 0-7) indicating the server status of the node. This server mask is detailed in the table: Table.

  • u16MaxTxSizeis the maximum size, in bytes, of the ASDU (Application Sub-layer Data Unit) in which a message can be sent (the message may actually be transmitted in smaller fragments)

  • u8DescriptorCapabilitycontains 8 bits (bits 0-7) indicating the properties of the node that can be used by other nodes in network discovery, as follows:

Bit description of u8DescriptorCapability

Bit

Description

0

Set to 1 if Extended Active Endpoint List is available on the node, 0 otherwise.

1

Set to 1 if Extended Simple Descriptor List is available on the node, 0 otherwise.

2-7

Reserved

Parent topic:Descriptor structures

ZPS_tsAplAfNodePowerDescriptor

The AF Node Power descriptor structure ZPS_tsAplAfNodePowerDescriptoris shown below.

typedef struct {
    uint32 eCurrentPowerMode         : 4;
    uint32 eAvailablePowerSources    : 4;
    uint32 eCurrentPowerSource       : 4;
    uint32 eCurrentPowerSourceLevel  : 4;
} ZPS_tsAplAfNodePowerDescriptor;

where:

  • eCurrentPowerModecontains 4 bits (bits 0-3) indicating the power mode currently used by the node, as follows:

    • 0000: Receiver configured according to “Receiver on when idle” MAC flag in the Node Descriptor (see Section 8.2.1.1)

    • 0001: Receiver switched on periodically

    • 0010: Receiver switched on when stimulated, for example, by pressing a button

    • All other values are reserved

  • eAvailablePowerSourcescontains 4 bits (bits 0-3) indicating the available power sources for the node, as follows (a bit is set to 1 if the corresponding power source is available):

    • Bit 0: Permanent mains supply

    • Bit 1: Rechargeable battery

    • Bit 2: Disposable battery

    • Bit 4: Reserved

  • eCurrentPowerSourcecontains 4 bits (bits 0-3) indicating the current power source for the node, as detailed for the element above (the bit corresponding to the current power source is set to 1, all other bits are set to 0).

  • eCurrentPowerSourceLevelcontains 4 bits (bit 0-3) indicating the current level of charge of the node’s power source (mainly useful for batteries), as follows:

    • 0000: Critically low

    • 0100: Approximately 33%

    • 1000: Approximately 66%

    • 1100: Approximately 100% (near fully charged)

Parent topic:Descriptor structures

ZPS_tsAplAfSimpleDescriptor

The AF Simple descriptor structure ZPS_tsAplAfSimpleDescriptoris shown below.

typedef struct {
    uint16 u16ApplicationProfileId;
    uint16 u16DeviceId;
    uint8 u8DeviceVersion;
    uint8 u8Endpoint;
    uint8 u8InClusterCount;
    uint8 u8OutClusterCount;
    uint16 *pu16InClusterList;
    uint16 *pu16OutClusterList;
} ZPS_tsAplAfSimpleDescriptor;

where:

  • u16ApplicationProfileIdis the 16-bit identifier of the ZigBee application profile supported by the endpoint. This must be an application profile identifier issued by the ZigBee Alliance (for Lighting and Occupancy devices, it is 0x0104).

  • u16DeviceIdis the 16-bit identifier of the ZigBee device type supported by the endpoint. This must be a device type identifier issued by the ZigBee Alliance.

  • u8DeviceVersioncontains 4 bits (bits 0-3) representing the version of the supported device description (default is 0000, unless set to another value according to the application profile used).

  • u8Endpointis the number, in the range 1-240, of the endpoint to which the Simple descriptor corresponds.

  • u8InClusterCountis an 8-bit count of the number of input clusters, supported on the endpoint, that will appear in the list pointed to by the pu16InClusterListelement.

  • u8OutClusterCountis an 8-bit count of the number of output clusters, supported on the endpoint, that will appear in the pu16OutClusterListelement.

  • *pu16InClusterListis a pointer to the list of input clusters supported by the endpoint (for use during the service discovery and binding procedures). This is a sequence of 16-bit values, representing the cluster numbers (in the range 1-240), where the number of values is equal to count u8InClusterCount. If this count is zero, the pointer can be set to NULL.

  • *pu16OutClusterListis a pointer to the list of output clusters supported by the endpoint (for use during the service discovery and binding procedures). This is a sequence of 16-bit values, representing the cluster numbers (in the range 1-240), where the number of values is equal to count u8OutClusterCount. If this count is zero, the pointer can be set to NULL.

Parent topic:Descriptor structures

Parent topic:AF structures

Event structures

These structures are used to contain events. Event details (type and associated data) are passed to the application in the structure ZPS_tsAfEvent. Data structures for the individual event types are contained in the union ZPS_tuAfEventData.

Enumerations for the event types are provided in the structure ZPS_teAfEventType. This structure and the associated events are detailed in Chapter 11, Event and Status Codes.

The structures are listed below.

  1. ZPS_tsAfEvent

  2. ZPS_tuAfEventData

  3. ZPS_tsAfDataIndEvent

  4. ZPS_tsAfDataConfEvent

  5. ZPS_tsAfDataAckEvent

  6. ZPS_tsAfNwkFormationEvent

  7. ZPS_tsAfNwkJoinedEvent

  8. ZPS_tsAfNwkJoinFailedEvent

  9. ZPS_tsAfNwkDiscoveryEvent

  10. ZPS_tsAfNwkJoinIndEvent

  11. ZPS_tsAfNwkLeaveIndEvent

  12. ZPS_tsAfNwkLeaveConfEvent

  13. ZPS_tsAfNwkStatusIndEvent

  14. ZPS_tsAfNwkRouteDiscoveryConfEvent

  15. ZPS_tsAfPollConfEvent

  16. ZPS_tsAfNwkEdScanConfEvent

  17. ZPS_tsAfErrorEvent

  18. ZPS_tsAfZdoBindEvent

  19. ZPS_tsAfZdoUnbindEvent

  20. ZPS_tsAfZdoLinkKeyEvent

  21. ZPS_tsAfBindRequestServerEvent

  22. ZPS_tsAfInterPanDataIndEvent

  23. ZPS_tsAfInterPanDataConfEvent

  24. ZPS_tsAfTCstatusEvent

  25. ZPS_tsAfZdpEvent

ZPS_tsAfEvent

This structure contains the details of an event. The ZPS_tsAfEventstructure is detailed below.

typedef struct {
    ZPS_teAfEventType eType;
    ZPS_tuAfEventData uEvent;
} ZPS_tsAfEvent;

where

  • eTypeindicates the event type, using the enumerations listed and described in Section 11.1.

  • uEventis a structure containing the event data from the union of structures detailed in Section 8.2.2.2.

Parent topic:Event structures

ZPS_tuAfEventData

This structure is a union of the data structures for the individual events described in Section 8.2.2.3 through to Section 8.2.2.25.

The ZPS_tuAfEventDatastructure is detailed below.

typedef union
{
ZPS_tsAfDataIndEvent                sApsDataIndEvent;
ZPS_tsAfDataConfEvent               sApsDataConfirmEvent;
ZPS_tsAfDataAckEvent                sApsDataAckEvent;
ZPS_tsAfNwkFormationEvent           sNwkFormationEvent;
ZPS_tsAfNwkJoinedEvent              sNwkJoinedEvent;
ZPS_tsAfNwkJoinFailedEvent          sNwkJoinFailedEvent;
ZPS_tsAfNwkDiscoveryEvent           sNwkDiscoveryEvent;
ZPS_tsAfNwkJoinIndEvent             sNwkJoinIndicationEvent;
ZPS_tsAfNwkLeaveIndEvent            sNwkLeaveIndicationEvent;
ZPS_tsAfNwkLeaveConfEvent           sNwkLeaveConfirmEvent;
ZPS_tsAfNwkStatusIndEvent           sNwkStatusIndicationEvent;
ZPS_tsAfNwkRouteDiscoveryConfEvent  sNwkRouteDiscoveryConfirmEvent;
ZPS_tsAfPollConfEvent               sNwkPollConfirmEvent;
ZPS_tsAfNwkEdScanConfEvent          sNwkEdScanConfirmEvent;
ZPS_tsAfErrorEvent                  sAfErrorEvent;
ZPS_tsAfZdoBindEvent                sZdoBindEvent;
ZPS_tsAfZdoUnbindEvent              sZdoUnbindEvent;
ZPS_tsAfZdoLinkKeyEvent             sZdoLinkKeyEvent;
ZPS_tsAfBindRequestServerEvent      sBindRequestServerEvent;
ZPS_tsAfInterPanDataIndEvent        sApsInterPanDataIndEvent;
ZPS_tsAfInterPanDataConfEvent       sApsInterPanDataConfirmEvent;
ZPS_tsAfZdpEvent                    sApsZdpEvent;
} ZPS_tuAfEventData;

Parent topic:Event structures

ZPS_tsAfDataIndEvent

This structure is used in the ZPS_EVENT_APS_DATA_INDICATION event, which indicates the arrival of data on the local node.

The ZPS_tsAfDataIndEventstructure is detailed below.

typedef struct
{
uint8              u8DstAddrMode;
ZPS_tuAddress      uDstAddress;
uint8              u8DstEndpoint;
uint8              u8SrcAddrMode;
ZPS_tuAddress      uSrcAddress;
uint8              u8SrcEndpoint;
uint16             u16ProfileId;
uint16             u16ClusterId;
PDUM_thAPduInstance hAPduInst;
uint8              eStatus;
uint8              eSecurityStatus;
uint8              u8LinkQuality;
uint32             u32RxTime;
} ZPS_tsAfDataIndEvent;

where:

  • u8DstAddrModeindicates the type of destination address specified through the element uDstAddress(see the Table below.)

  • uDstAddressis the address of the destination node for the data packet (the type of address is specified using the element u8DstAddrModeabove).

  • u8DstEndpointis the number of the destination endpoint (in range 0-240).

  • u8SrcAddrModeindicates the type of source address specified through the element uSrcAddress(below) - this can be a 64-bit MAC/IEEE address or a 16-bit network address.

  • uSrcAddressis the address of the source node for the data packet (the type of address is specified using the element u8SrcAddrModeabove).

  • u8SrcEndpointis the number of the source endpoint (in range 1-240).

  • u16ProfileIdis the identifier of the ZigBee device profile of the device which can interpret the data.

  • u16ClusterIdis the identifier of the cluster (which belongs to the device profile specified in u16ProfileId) which is capable of interpreting the data.

  • hAPduInstis the handle of the APDU which contains the data.

  • eStatusis one of the status codes from the NWK layer or MAC layer, detailed in Section 11.2.3 and Section 11.2.4.

  • eSecurityStatusindicates the type of security with which the packet was sent. It can be: unsecured (0xAF), secured with network key (0xAC), or secured with link key (0xAB).

  • u8LinkQualityis a measure of the signal strength of the radio link over which the data packet was sent (for the last hop).

  • u32RxTimeis reserved for future use.

Addressing modes

u8DstAddrMode

Code

Description

0x00

ZPS_E_ADDR_MODE_BOUND

Bound endpoint

0x01

ZPS_E_ADDR_MODE_GROUP

16-bit Group address

0x02

ZPS_E_ADDR_MODE_SHORT

16-bit Network (Short) address

0x03

ZPS_E_ADDR_MODE_IEEE

64-bit IEEE/MAC address

Parent topic:Event structures

ZPS_tsAfDataConfEvent

This structure is used in the ZPS_EVENT_APS_DATA_CONFIRM event, which confirms that a data packet sent by the local node has been successfully passed down the stack to the MAC layer and has made its first hop toward its destination (an acknowledgment has been received from the next hop node).

The ZPS_tsAfDataConfEventstructure is detailed below.

typedef struct {
uint8         u8Status;
uint8         u8SrcEndpoint;
uint8         u8DstEndpoint;
uint8         u8DstAddrMode;
ZPS_tuAddress uDstAddr;
uint8         u8SequenceNum;
} ZPS_tsAfDataConfEvent;

where:

  • u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

  • u8SrcEndpointis the number of the (local) source endpoint for the data transfer (in range 1-240).

  • u8DstEndpointis the number of the destination endpoint for the data transfer (in range 1-240).

  • u8DstAddrModeindicates the type of destination address specified through the element uDstAddr(see Table) - only values 0x02 (group address) and 0x03 (network address) are valid in this structure.

  • uDstAddris the address of the destination node for the data packet (the type of address is specified using the element u8DstAddrModeabove).

  • u8SequenceNumis the sequence number of the request that initiated the data transfer.

Parent topic:Event structures

ZPS_tsAfDataAckEvent

This structure is used in the ZPS_EVENT_APS_DATA_ACK event, which is generated when an end-to-end acknowledgment is received from the destination node during a data transfer in which an acknowledgment was requested.

typedef struct {
  uint8 u8Status;
  uint8 u8SrcEndpoint;
  uint8 u8DstEndpoint;
  uint8 u8DstAddrMode;
  uint16 u16DstAddr;
  uint8 u8SequenceNum;
  uint16 u16ProfileId;
  uint16 u16ClusterId;
} ZPS_tsAfDataAckEvent;

where:

  • u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

  • u8SrcEndpointis the number of the (local) source endpoint for the data transfer (in range 1-240).

  • u8DstEndpointis the number of the destination endpoint for the data transfer (in range 1-240).

  • u8DstAddrModeindicates the type of destination address specified through the element u16DstAddr(see Table) - only values 0x01 (group address) and 0x02 (network address) are valid in this structure.

  • u16DstAddris the 16-bit address of the destination node for the data transfer and therefore of the node that sent the acknowledgment (the type of address is specified using the element u8DstAddrModeabove).

  • u8SequenceNumis the sequence number of the request that initiated the data transfer.

  • u16ProfileIdis the identifier of the ZigBee device profile of the device for which the data transfer was intended.

  • u16ClusterIdis the identifier of the cluster (which belongs to the device profile specified in u16ProfileId) for which the data transfer was intended.

Parent topic:Event structures

ZPS_tsAfNwkFormationEvent

This structure is used in the event ZPS_EVENT_NWK_STARTED, which indicates whether the network has been started (on the Coordinator).

The ZPS_tsAfNwkFormationEventstructure is detailed below.

typedef struct {
    uint8 u8Status;
} ZPS_tsAfNwkFormationEvent;

where is one of the status codes from the lower stack layers, detailed in Section 11.2.

Parent topic:Event structures

ZPS_tsAfNwkJoinedEvent

This structure is used in the events ZPS_EVENT_NWK_JOINED_AS_ROUTER and ZPS_EVENT_NWK_JOINED_AS_ENDDEVICE, which confirm that the local device (Router or End Device) has successfully joined a network.

The ZPS_tsAfNwkJoinedEventstructure reports the network address that the parent has assigned to the new node and is detailed below.

typedef struct
{
    uint16 u16Addr;
    bool_t bRejoin;
} ZPS_tsAfNwkJoinedEvent;

where:

  • u16Addris the 16-bit network address allocated to the joining node.

  • bRejoinindicates whether the join was a rejoin (TRUE) or a new association (FALSE).

Parent topic:Event structures

ZPS_tsAfNwkJoinFailedEvent

This structure is used in the event ZPS_EVENT_NWK_FAILED_TO_JOIN, which indicates that the local device has failed to join a network.

The ZPS_tsAfNwkJoinFailedEventstructure is detailed below.

typedef struct
{
    uint8 u8Status;
    bool_t bRejoin;
} ZPS_tsAfNwkJoinFailedEvent;

where:

  • u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

  • bRejoinindicates whether the join attempt was a rejoin (TRUE) or a new association (FALSE).

Parent topic:Event structures

ZPS_tsAfNwkDiscoveryEvent

This structure is used in the ZPS_EVENT_NWK_DISCOVERY_COMPLETE event, which reports the details of the networks detected in a network discovery initiated by a Router or End Device that needs to join a network.

The ZPS_tsAfNwkDiscoveryEventstructure is detailed below.

typedef struct
{
    uint32        u32UnscannedChannels;
    uint8         eStatus;
    uint8         u8NetworkCount;
    uint8         u8SelectedNetwork;
    ZPS_tsNwkNetworkDescr *psNwkDescriptors;
} ZPS_tsAfNwkDiscoveryEvent;

where:

  • u32UnscannedChannelsis a 32-bit bitmap representing the set of channels from the network discovery that had not yet been scanned when this event was generated. Bits 11 to 26 represent the 2400-MHz channels 11 to 26, where 1 indicates channel scanned and 0 indicates channel not yet scanned.

  • estatusis the status of the network discovery process, returned by the lower layers (see Section 11.2) - MAC_ENUM_SUCCESS, if the discovery was successfully completed.

  • u8NetworkCountis the number of networks that had been discovered when this event was generated.

  • u8SelectedNetworkis the index of the recommended network in the array of reported networks (see below).

  • psNwkDescriptorsis a pointer to the network discovery table in the network NIB. The network discovery table contains an array of data structures, where each structure contains details of a discovered network. Each array element is a structure of the type ZPS_tsNwkNetworkDescr, described in Section 8.2.3.1. The number of array elements is given by u8NetworkCount, described above.

Parent topic:Event structures

ZPS_tsAfNwkJoinIndEvent

This structure is used in the event ZPS_EVENT_NWK_NEW_NODE_HAS_JOINED, which notifies a Router or the Coordinator that a new child node has joined the network.

The ZPS_tsAfNwkJoinIndEventstructure contains information about the new node and is detailed below.

typedef struct
{
  uint64 u64ExtAddr;
  uint16 u16NwkAddr;
  uint8 u8Capability;
  uint8 u8Rejoin;
  uint8 u8SecureRejoin;
} ZPS_tsAfNwkJoinIndEvent;

where:

  • u64ExtAddris the 64-bit IEEE (MAC) address of the joining node.

  • u16NwkAddris the 16-bit network address assigned to the joining node.

  • u8Capabilityis a bitmap indicating the operational capabilities of the joining node. This bitmap is detailed in Table below.

  • u8Rejoinindicates the method used to join the network:

    • 0x00 if joined through association.

    • 0x01 if joined directly or used orphaning.

    • 0x02 if was network rejoin.

  • u8SecureRejoinindicates whether the join was performed in a secure manner.

    • zero represents FALSE.

    • a non-zero value represents TRUE.

Node 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:Event structures

ZPS_tsAfNwkLeaveIndEvent

This structure is used in the ZPS_EVENT_LEAVE_INDICATION event, which indicates that a neighboring node has left the network or a remote node has requested the local node to leave.

The ZPS_tsAfNwkLeaveIndEventstructure is detailed below.

typedef struct {
    uint64 u64ExtAddr;
    uint8 u8Rejoin;
} ZPS_tsAfNwkLeaveIndEvent;

where:

  • u64ExtAddris the 64-bit IEEE (MAC) address of the node that has left the network, or is zero if the local node has been requested to leave the network

  • u8Rejoinindicates whether the leaving node was requested to attempt a subsequent rejoin of the network:

    • zero represents FALSE

    • a non-zero value represents TRUE.

Parent topic:Event structures

ZPS_tsAfNwkLeaveConfEvent

This structure is used in the event ZPS_EVENT_NWK_LEAVE_CONFIRM, which reports the results of a node leave request issued by the local node.

The ZPS_tsAfNwkLeaveConfEventstructure is detailed below.

typedef struct {
    uint64 u64ExtAddr;
    uint8 eStatus;
} ZPS_tsAfNwkLeaveConfEvent;

where:

  • u64ExtAddris the 64-bit IEEE (MAC) address of the leaving node. This value is zero if the local node itself is leaving.

  • eStatusis the leave status returned by the lower layers - ZPS_NWK_ENUM_SUCCESS, if the leave request has been successful.

Parent topic:Event structures

ZPS_tsAfNwkStatusIndEvent

This structure is used in the ZPS_EVENT_NWK_STATUS_INDICATION event, which reports status information from the NWK layer of the stack.

The ZPS_tsAfNwkStatusIndEventstructure is detailed below.

typedef struct {
    uint16 u16NwkAddr;
    uint8 u8Status;
} ZPS_tsAfNwkStatusIndEvent;

where:

  • u16NwkAddris the 16-bit network address of the node associated with the event.

  • u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

Parent topic:Event structures

ZPS_tsAfNwkRouteDiscoveryConfEvent

This structure is used in the ZPS_EVENT_NWK_ROUTE_DISCOVERY_CONFIRM event, which confirms that a route discovery has been performed.

The ZPS_tsAfNwkRouteDiscoveryConfEventstructure is detailed below.

typedef struct {
    uint16 u16DstAddress;
    uint8 u8Status;
    uint8 u8NwkStatus;
} ZPS_tsAfNwkRouteDiscoveryConfEvent;

where:

  • u16DstAddressis the destination address for which the route discovery confirm event was generated.

  • u8Statusis one of the status codes from the MAC layer, detailed in Section11.2.4.

  • u8NwkStatusis one of the status codes from the NWK layer, detailed in Section 11.2.3.

Parent topic:Event structures

ZPS_tsAfPollConfEvent

This structure is used in the ZPS_EVENT_NWK_POLL_CONFIRM event, which reports the completion of a poll request sent from the (local) End Device to its parent.

The ZPS_tsAfPollConfEventstructure is detailed below.

typedef struct {
    uint8 u8Status;
} ZPS_tsAfPollConfEvent;

where u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

Parent topic:Event structures

ZPS_tsAfNwkEdScanConfEvent

This structure is used in the ZPS_EVENT_NWK_ED_SCAN event, which indicates that an ‘energy detect’ scan in the 2.4-GHz radio band is completed.

The ZPS_tsAfNwkEdScanConfEventstructure is defined as:

typedef ZPS_tsNwkNlmeCfmEdScan ZPS_tsAfNwkEdScanConfEvent;

where ZPS_tsNwkNlmeCfmEdScanis described in Section 8.2.3.2.

Parent topic:Event structures

ZPS_tsAfErrorEvent

This structure is used in the ZPS_EVENT_ERROR event, which reports error situations concerning the storage of received messages in APDU instances.

The ZPS_tsAfErrorEventstructure is detailed below.

typedef struct {
    enum {
        ZPS_ERROR_APDU_TOO_SMALL,
        ZPS_ERROR_APDU_INSTANCES_EXHAUSTED,
        ZPS_ERROR_NO_APDU_CONFIGURED,
        ZPS_ERROR_OS_MESSAGE_QUEUE_OVERRUN
    } eError;
   union {
         struct {
            uint16 u16ProfileId;
            uint16 u16ClusterId;
            uint16 u16SrcAddr;
            uint16 u16DataSize;
            PDUM_thAPdu hAPdu;
            uint8 u8SrcEndpoint;
            uint8 u8DstEndpoint;
        }sAfErrorApdu;
        struct {
            OS_thMessage hMessage;
        } sAfErrorOsMessageOverrun;
    } uErrorData;
} ZPS_tsAfErrorEvent;

The member enumerations and structures of the above structure are detailed below.

eError enumerations

The error enumerations which are part of the ZPS_tsAfErrorEventstructure are listed and described below.

eError Enumerations

eError Enumeration

Description

ZPS_ERROR_APDU_TOO_SMALL

Allocated APDU instance is too small to accommodate received message. This error is detailed in the structure sAfErrorApdu, which is described below.

ZPS_ERROR_APDU_INSTANCES_EXHAUSTED

The are no APDU instances available to accommodate the received message. This error is detailed in the structure sAfErrorApdu, which is described below.

ZPS_ERROR_NO_APDU_CONFIGURED

No APDU has been configured to accommodate the received message. This error is detailed in the structure sAfErrorApdu, which is described below.

ZPS_ERROR_OS_MESSAGE_QUEUE_OVERRUN

A message queue is full and can accept no more messages. This error is detailed in the structure sAfErrorOsMessageOverrun, which is described below.

sAfErrorApdu

This structure is used in the following errors:

  • ZPS_ERROR_APDU_TOO_SMALL, which reports that the allocated APDU instance is too small to store a received message.

  • ZPS_ERROR_APDU_INSTANCES_EXHAUSTED, which reports that there are no allocated APDU instances left to store a received message.

  • ZPS_ERROR_NO_APDU_CONFIGURED, which reports that no APDU has been configured to store the received message.

The sAfErrorApdustructure is detailed below.

struct {
    uint16 u16ProfileId;
    uint16 u16ClusterId;
    uint16 u16SrcAddr;
    uint16 u16DataSize;
    PDUM_thAPdu hAPdu;
    uint8 u8SrcEndpoint;
    uint8 u8DstEndpoint;
}sAfErrorApdu;

where:

  • u16ProfileIdis the identifier of the ZigBee application profile associated with the source and destination endpoints for the message.

  • u16ClusterIdis the identifier of the cluster associated with the source and destination endpoints for the message.

  • u16SrcAddris the 16-bit network address of the source node of the message.

  • u16DataSizeis the size of the received message, in bytes.

  • hAPduis the handle of the local APDU pool from which the APDU instance comes.

  • u8SrcEndpointis the number of the source endpoint of the message.

  • u8DstEndpointis the number of the destination endpoint of the message.

Parent topic:ZPS_tsAfErrorEvent

sAfErrorOsMessageOverrun

This structure is used in the ZPS_ERROR_OS_MESSAGE_QUEUE_OVERRUN error, which indicates that a message queue is full and can accept no more messages.

The sAfErrorOsMessageOverrunstructure is detailed below.

struct {
    OS_thMessage hMessage;
} sAfErrorOsMessageOverrun;

where hMessageis the handle of the message type for the queue which is full.

Parent topic:ZPS_tsAfErrorEvent

Parent topic:Event structures

ZPS_tsAfZdoBindEvent

This structure is used in the ZPS_EVENT_ZDO_BIND event, which indicates that the local node has been successfully bound to one or more remote nodes.

The ZPS_tsAfZdoBindEventstructure is detailed below.

typedef struct { ZPS_tuAddress uDstAddr; uint8 u8DstAddrMode; uint8 u8SrcEp; uint8 u8DstEp; } ZPS_tsAfZdoBindEvent;

where

  • uDstAddris the address of the remote node for the binding (the type of address is specified using the element u8DstAddrModeabove).

  • u8DstAddrModeindicates the type of address specified through the element uDstAddr(see Table 1).

  • u8SrcEpis the number of the source endpoint for the binding (in range 1-240).

  • u8DstEpis the number of the destination endpoint for the binding (in range 1-240).

Parent topic:Event structures

ZPS_tsAfZdoUnbindEvent

This structure is used in the ZPS_EVENT_ZDO_UNBIND event, which indicates that the local node has been successfully unbound from one or more remote nodes.

The ZPS_tsAfZdoUnbindEventstructure is defined as:

typedef ZPS_tsAfZdoBindEvent ZPS_tsAfZdoUnbindEvent;

where ZPS_tsAfZdoBindEventis described in Section 8.2.2.18\ (but for this event, the data in the structure relates to unbinding rather than binding).

Parent topic:Event structures

ZPS_tsAfZdoLinkKeyEvent

This structure is used in the ZPS_EVENT_ZDO_LINK_KEY event, which indicates that a new application link key has been received and installed, and is ready for use.

The ZPS_tsAfZdoLinkKeyEventstructure is defined as:

typedef struct {
    uint64 u64IeeeLinkAddr;
} ZPS_tsAfZdoLinkKeyEvent;

where u64IeeeLinkAddris the IEEE/MAC address of the remote device with which the installed link key is valid.

Parent topic:Event structures

ZPS_tsAfBindRequestServerEvent

This structure is used in the ZPS_EVENT_BIND_REQUEST_SERVER event, which reports the status of a data transmission sent from the (local) node to a set of bound endpoints.

The ZPS_tsAfBindRequestServerEventstructure is detailed below.

typedef struct {
    uint8 u8Status;
    uint8 u8SrcEndpoint;
    uint32 u32FailureCount;
} ZPS_tsAfBindRequestServerEvent;

where:

  • u8Statusis the overall status of the bound data transmission:

    • Success (0) indicates that the data packet was successfully transmitted to all bound endpoints

    • Failure (non-zero value) indicates that the data packet was not successfully sent to at least one bound endpoint (see u32FailureCountbelow).

  • u8SrcEndpointis the number of the local endpoint from which the data packet was sent.

  • u32FailureCountis the number of bound endpoints for which the transmission failed.

Parent topic:Event structures

ZPS_tsAfInterPanDataIndEvent

This structure is used in the ZPS_EVENT_APS_INTERPAN_DATA_INDICATION event, which indicates that an inter-PAN data packet has arrived.

The ZPS_tsAfInterPanDataIndEventstructure is detailed below.

typedef struct
{
    ZPS_tsInterPanAddress sDstAddr;
    uint8   u8SrcAddrMode;
    uint16   u16SrcPan;
    uint64   u64SrcAddress;
    uint16   u16ProfileId;
    uint16   u16ClusterId;
    PDUM_thAPduInstance hAPduInst;
    uint8   eStatus;
    uint8   u8DstEndpoint;
    uint8   u8LinkQuality;
} ZPS_tsAfInterPanDataIndEvent;

where

  • sDstAddris a structure of the type ZPS_tsInterPanAddress(see Section8.2.3.3) which contains the PAN ID and address for the destination node(s) of the inter-PAN data packet.

  • u8SrcAddrModeindicates the type of address specified through the element u64SrcAddress (see Table).

  • u16SrcPanis the PAN ID of the network from which the data packet originates.

  • u64SrcAddressis the address of the node which sent the data packet (the type of address is specified using the element u8SrcAddrModeabove).

  • u16ProfileIdis the identifier of the application profile for which the data packet is intended.

  • u16ClusterIdis the identifier of the cluster for which the data packet is intended.

  • hAPduInstis the handle of the APDU instance for the data packet.

  • eStatusis one of the status codes from the lower stack layers, detailed in Section 11.2.

  • u8DstEndpointis the number of the destination endpoint for the data packet (in range 1-240).

  • u8LinkQualityis an LQI value indicating the perceived strength of the radio signal which carried the received data packet.

Parent topic:Event structures

ZPS_tsAfInterPanDataConfEvent

This structure is used in the ZPS_EVENT_APS_INTERPAN_DATA_CONFIRM event, which indicates that an inter-PAN communication has been sent by the local node and an acknowledgment has been received from the first hop node (this acknowledgment is not generated in the case of a broadcast).

The ZPS_tsAfInterPanDataConfEventstructure is detailed below.

typedef struct {
    uint8 u8Status;
    uint8 u8Handle;
} ZPS_tsAfInterPanDataConfEvent;

where

  • u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

  • u8Handleis a handle for internal use.

Parent topic:Event structures

ZPS_tsAfTCstatusEvent

This structure is used in the ZPS_EVENT_TC_STATUS event, which indicates whether negotiations to establish a link key with the Trust Centre have been successful and, if so, which key is the active key.

The ZPS_tsAfTCstatusEventstructure is detailed below.

typedef struct
{
    ZPS_tuTcStatusData  uTcData;
    uint8               u8Status;
}ZPS_tsAfTCstatusEvent;

where:

  • uTcDatais dependent on u8Status(below) and is either a pointer to the link key descriptor in the case of success or the address of the Trust Centre node in the case of failure. ZPS_tuTcStatusDatais a union, detailed below.

  • u8Statusindicates the results of the link key negotiations - one of:

    • ZPS_E_SUCCESS (link key successfully established)

    • ZPS_APL_APS_E_SECURITY_FAIL (link key not established)

The ZPS_tuTcStatusDatastructure is detailed below.

typedef union {
   ZPS_tsAplApsKeyDescriptorEntry *pKeyDesc;
   uint64 u64ExtendedAddress;
} PS_tuTcStatusData;

where:

  • pKeyDescis a pointer to the active link key, if successfully established, which is contained in the structure described in Section 8.2.3.6.

  • u64ExtendedAddressis the IEEE/MAC address of the Trust Centre node with which link key negotiations failed.

Parent topic:Event structures

ZPS_tsAfZdpEvent

This structure is used when a ZPS_EVENT_APS_DATA_INDICATION event is generated containing a response which is destined for the ZDO at endpoint 0. The application can extract the response data from the event using the function ZPS_bAplZdpUnpackResponse() and this structure is used to receive the extracted data.

The ZPS_tsAfZdpEventstructure is detailed below.

typedef struct {
    uint8 u8SequNumber;
    uint16 u16ClusterId;
    union {
        ZPS_tsAplZdpDeviceAnnceReq sDeviceAnnce;
        ZPS_tsAplZdpMgmtNwkUpdateReq sMgmtNwkUpdateReq;
        ZPS_tsAplZdpMgmtPermitJoiningReq sPermitJoiningReq;
        ZPS_tsAplZdpDiscoveryCacheRsp sDiscoveryCacheRsp;
        ZPS_tsAplZdpDiscoveryStoreRsp sDiscoveryStoreRsp;
        ZPS_tsAplZdpNodeDescStoreRsp sNodeDescStoreRsp;
        ZPS_tsAplZdpActiveEpStoreRsp sActiveEpStoreRsp;
        ZPS_tsAplZdpSimpleDescStoreRsp sSimpleDescStoreRsp;
        ZPS_tsAplZdpRemoveNodeCacheRsp sRemoveNodeCacheRsp;
        ZPS_tsAplZdpEndDeviceBindRsp sEndDeviceBindRsp;
        ZPS_tsAplZdpBindRsp sBindRsp;
        ZPS_tsAplZdpUnbindRsp sUnbindRsp;
        ZPS_tsAplZdpReplaceDeviceRsp sReplaceDeviceRsp;
        ZPS_tsAplZdpStoreBkupBindEntryRsp sStoreBkupBindEntryRsp;
        ZPS_tsAplZdpRemoveBkupBindEntryRsp sRemoveBkupBindEntryRsp;
        ZPS_tsAplZdpBackupSourceBindRsp sBackupSourceBindRsp;
        ZPS_tsAplZdpMgmtLeaveRsp sMgmtLeaveRsp;
        ZPS_tsAplZdpMgmtDirectJoinRsp sMgmtDirectJoinRsp;
        ZPS_tsAplZdpMgmtPermitJoiningRsp sPermitJoiningRsp;
        ZPS_tsAplZdpNodeDescRsp sNodeDescRsp;
        ZPS_tsAplZdpPowerDescRsp sPowerDescRsp;
        ZPS_tsAplZdpSimpleDescRsp sSimpleDescRsp;
        ZPS_tsAplZdpNwkAddrRsp sNwkAddrRsp;
        ZPS_tsAplZdpIeeeAddrRsp sIeeeAddrRsp;
        ZPS_tsAplZdpUserDescConf sUserDescConf;
        ZPS_tsAplZdpSystemServerDiscoveryRsp sSystemServerDiscoveryRsp;
        ZPS_tsAplZdpPowerDescStoreRsp sPowerDescStoreRsp;
        ZPS_tsAplZdpUserDescRsp sUserDescRsp;
        ZPS_tsAplZdpActiveEpRsp sActiveEpRsp;
        ZPS_tsAplZdpMatchDescRsp sMatchDescRsp;
        ZPS_tsAplZdpComplexDescRsp sComplexDescRsp;
        ZPS_tsAplZdpFindNodeCacheRsp sFindNodeCacheRsp;
        ZPS_tsAplZdpExtendedSimpleDescRsp sExtendedSimpleDescRsp;
        ZPS_tsAplZdpExtendedActiveEpRsp sExtendedActiveEpRsp;
        ZPS_tsAplZdpBindRegisterRsp sBindRegisterRsp;
        ZPS_tsAplZdpBackupBindTableRsp sBackupBindTableRsp;
        ZPS_tsAplZdpRecoverBindTableRsp sRecoverBindTableRsp;
        ZPS_tsAplZdpRecoverSourceBindRsp sRecoverSourceBindRsp;
        ZPS_tsAplZdpMgmtNwkDiscRsp sMgmtNwkDiscRsp;
        ZPS_tsAplZdpMgmtLqiRsp sMgmtLqiRsp;
        ZPS_tsAplZdpMgmtRtgRsp sRtgRsp;
        ZPS_tsAplZdpMgmtBindRsp sMgmtBindRsp;
        ZPS_tsAplZdpMgmtCacheRsp sMgmtCacheRsp;
        ZPS_tsAplZdpMgmtNwkUpdateNotify sMgmtNwkUpdateNotify;
    }uZdpData;
    union {
        ZPS_tsAplZdpBindingTableEntry asBindingTable[5];
        ZPS_tsAplZdpNetworkDescr asNwkDescTable[5];
        ZPS_tsAplZdpNtListEntry asNtList[2];
        ZPS_tsAplDiscoveryCache aDiscCache[5];
        uint16 au16Data[34];
        uint8 au8Data[77];
        uint64 au64Data[9];
    }uLists;
}ZPS_tsAfZdpEvent;

where:

  • u8SequNumberis the sequence number of the ZDP request/response

  • u16ClusterIdis the ID of the cluster to which the request/response relates

  • uZdpDatais a union of the different ZDP request/response types:

    • sDeviceAnnceis a structure of the type ZPS_tsAplZdpDeviceAnnceReq, described in Section 9.2.2.3

  • sMgmtNwkUpdateReqis a structure of the type ZPS_tsAplZdpMgmtNwkUpdateReq, described in Section 9.2.2.41

  • sPermitJoiningReqis a structure of the type ZPS_tsAplZdpMgmtPermitJoiningReq, described in Section 9.2.3.39

  • sDiscoveryCacheRspis a structure of the type ZPS_tsAplZdpDiscoveryCacheRsp, described in Section 9.2.3.14

  • sDiscoveryStoreRspis a structure of the type ZPS_tsAplZdpDiscoveryStoreRsp, described in Section 9.2.3.15

  • sNodeDescStoreRspis a structure of the type ZPS_tsAplZdpNodeDescStoreRsp, described in Section 9.2.3.16

  • sActiveEpStoreRspis a structure of the type ZPS_tsAplZdpActiveEpStoreRsp, described in Section 9.2.3.19

  • sSimpleDescStoreRspis a structure of the type ZPS_tsAplZdpSimpleDescStoreRsp, described in Section 9.2.3.18

  • sRemoveNodeCacheRspis a structure of the type ZPS_tsAplZdpRemoveNodeCacheRsp, described in Section 9.2.3.21

  • sEndDeviceBindRspis a structure of the type ZPS_tsAplZdpEndDeviceBindRsp, described in Section 9.2.3.22

  • sBindRspis a structure of the type ZPS_tsAplZdpBindRsp, described in Section 9.2.3.23

  • sUnbindRspis a structure of the type ZPS_tsAplZdpUnbindRsp, described in Section 9.2.3.24

  • sReplaceDeviceRspis a structure of the type ZPS_tsAplZdpReplaceDeviceRsp, described in Section 9.2.3.26

  • sStoreBkupBindEntryRspis a structure of the type ZPS_tsAplZdpStoreBkupBindEntryRsp, described in Section9.2.2.27

  • sRemoveBkupBindEntryRspis a structure of the type ZPS_tsAplZdpRemoveBkupBindEntryRsp, described in Section9.2.2.28

  • sBackupSourceBindRspis a structure of the type ZPS_tsAplZdpBackupSourceBindRsp, described in Section 9.2.3.31

  • sMgmtLeaveRspis a structure of the type ZPS_tsAplZdpMgmtLeaveRsp, described in Section 9.2.3.37

  • sMgmtDirectJoinRspis a structure of the type ZPS_tsAplZdpMgmtDirectJoinRsp, described in Section 9.2.3.38

  • sPermitJoiningRspis a structure of the type ZPS_tsAplZdpMgmtPermitJoiningRsp, described in Section 9.2.3.39

  • sNodeDescRspis a structure of the type ZPS_tsAplZdpNodeDescRsp, described in Section 8.2.3.3

  • sPowerDescRspis a structure of the type ZPS_tsAplZdpPowerDescRsp, described in Section 9.2.3.4

  • sSimpleDescRspis a structure of the type ZPS_tsAplZdpSimpleDescRsp, described in Section 9.2.3.5

  • sNwkAddrRspis a structure of the type ZPS_tsAplZdpNwkAddrRsp, described in Section 9.2.3.1

  • sIeeeAddrRspis a structure of the type ZPS_tsAplZdpIeeeAddrRsp, described in Section 9.2.3.2

  • sUserDescConfis a structure of the type ZPS_tsAplZdpUserDescConf, described in Section 9.2.3.12

  • sSystemServerDiscoveryRspis a structure of the type ZPS_tsAplZdpSystemServerDiscoveryRsp, described in Section9.2.3.13

  • sPowerDescStoreRspis a structure of the type ZPS_tsAplZdpPowerDescStoreRsp, described in Section 9.2.3.17

  • sUserDescRspis a structure of the type ZPS_tsAplZdpUserDescRsp, described in Section 9.2.3.8

  • sActiveEpRspis a structure of the type ZPS_tsAplZdpActiveEpRsp, described in Section 9.2.3.10

  • sMatchDescRspis a structure of the type ZPS_tsAplZdpMatchDescRsp, described in Section 9.2.3.9

  • sComplexDescRspis a structure of the type ZPS_tsAplZdpComplexDescRsp, described in Section 9.2.3.7

  • sFindNodeCacheRspis a structure of the type ZPS_tsAplZdpFindNodeCacheRsp, described in Section 9.2.3.20

  • sExtendedSimpleDescRspis a structure of the type ZPS_tsAplZdpExtendedSimpleDescRsp, described in Section 9.2.3.6

  • sExtendedActiveEpRspis a structure of the type ZPS_tsAplZdpExtendedActiveEpRsp, described in Section 9.2.3.11

  • sBindRegisterRspis a structure of the type ZPS_tsAplZdpBindRegisterRsp, described in Section 9.2.3.25

  • sBackupBindTableRspis a structure of the type ZPS_tsAplZdpBackupBindTableRsp, described in Section 9.2.3.29

  • sRecoverBindTableRspis a structure of the type ZPS_tsAplZdpRecoverBindTableRsp, described in Section 9.2.3.30

  • sRecoverSourceBindRspis a structure of the type ZPS_tsAplZdpRecoverSourceBindRsp, described in Section 9.2.3.32

  • sMgmtNwkDiscRspis a structure of the type ZPS_tsAplZdpMgmtNwkDiscRsp, described in Section 9.2.3.33

  • sMgmtLqiRspis a structure of the type ZPS_tsAplZdpMgmtLqiRsp, described in Section 9.2.3.34

  • sRtgRspis a structure of the type ZPS_tsAplZdpMgmtRtgRsp, described in Section 9.2.3.35

  • sMgmtBindRspis a structure of the type ZPS_tsAplZdpMgmtBindRsp, described in Section 9.2.3.36

  • sMgmtCacheRspis a structure of the type ZPS_tsAplZdpMgmtCacheRsp, described in Section 9.2.3.40

  • sMgmtNwkUpdateNotifyis a structure of the type ZPS_tsAplZdpMgmtNwkUpdateNotify, described in Section 9.2.3.41

  • uListsis a union of the different arrays/tables which act as temporary storage for data elements used by the stack (and are therefore for internal use only)

Parent topic:Event structures

Parent topic:AF structures

Other structures

This section describes various structures used by the AF API. The structures are listed below.

  1. ZPS_tsNwkNetworkDescr

  2. ZPS_tsNwkNlmeCfmEdScan

  3. ZPS_tsInterPanAddress

  4. ZPS_tsAplApsKeyDescriptorEntry

  5. ZPS_tsAftsStartParamsDistributed

  6. ZPS_tsAfFlashInfoSet

  7. ZPS_TclkDescriptorEntry

ZPS_tsNwkNetworkDescr

This structure is used in an array element in the structure ZPS_tsAfNwkDiscoveryEvent, which is created as part of the ZPS_EVENT_NWK_DISCOVERY_COMPLETE event. This event reports the networks detected during a network discovery (see Section 8.2.2.9).

The ZPS_tsNwkNetworkDescrstructure contains information on a detected network and is detailed below.

typedef struct
{
    uint64 u64ExtPanId;
    uint8 u8LogicalChan;
    uint8 u8StackProfile;
    uint8 u8ZigBeeVersion;
    uint8 u8PermitJoining;
    uint8 u8RouterCapacity;
    uint8 u8EndDeviceCapacity;
} ZPS_tsNwkNetworkDescr;

where:

  • u64ExtPanIdis the Extended PAN ID of the discovered network.

  • u8LogicalChanis the 2400-MHz channel on which the network was found.

  • u8StackProfileis the Stack Profile of the discovered network:

    • 0 - manufacturer-specific

    • 1 - ZigBee

    • 2 - ZigBee PRO

    • other values reserved, and is fixed at 2 for the NXP stack

  • u8ZigBeeVersionis the ZigBee version of the discovered network.

  • u8PermitJoiningindicates the number of detected nodes with ‘permit joining’ enabled (and therefore allowing nodes to join the network through them).

  • u8RouterCapacityindicates the number of detected nodes that are allowing Routers to join the network through them.

  • u8EndDeviceCapacityindicates the number of detected nodes that are allowing End Devices to join the network through them.

Parent topic:Other structures

ZPS_tsNwkNlmeCfmEdScan

This structure is used by the structure ZPS_tsAfNwkEdScanConfEvent, which is created as part of the ZPS_EVENT_NWK_ED_SCAN event which reports the results of an ‘energy detect’ scan in the 2.4-GHz radio band.

The ZPS_tsNwkNlmeCfmEdScantstructure is detailed below.

typedef struct
{
    uint8 u8Status;
    uint8 u8ResultListSize;
    uint8 au8EnergyDetect[ZPS_NWK_MAX_ED_RESULTS];
} ZPS_tsNwkNlmeCfmEdScan;

where

  • u8Statusis one of the status codes from the lower stack layers, detailed in Section 11.2.

  • u8ResultListSizeis the number of entries in the results list (see below).

  • au8EnergyDetect[]is an array containing the list of results of the energy scan (8-bit values representing the detected energy levels in the channels). There is one array element for each channel scanned, where element 0 is for the first channel scanned, element 1 is for the second channel scanned, etc.

Parent topic:Other structures

ZPS_tsInterPanAddress

This structure is used to specify the destination for an inter-PAN transmission. The ZPS_tsInterPanAddressstructure is detailed below.

typedef struct
{
    enum {
        ZPS_E_AM_INTERPAN_GROUP = 0x01,
        ZPS_E_AM_INTERPAN_SHORT,
        ZPS_E_AM_INTERPAN_IEEE
    }eMode;
    uint16 u16PanId;
    ZPS_tuAddress uAddress;
} ZPS_tsInterPanAddress;

where:

  • eModeis used to specify the type of destination address that will be used in the field uAddressbelow. One of the following enumerations must be specified:

    • ZPS_E_AM_INTERPAN_GROUP indicates that a 16-bit group address will be used to specify multiple target nodes in the destination network (the group address must be valid in the destination network)

    • ZPS_E_AM_INTERPAN_SHORT indicates that a 16-bit network/short address will be used to specify a single target node or a broadcast to all nodes in the destination network

    • ZPS_E_AM_INTERPAN_IEEE indicates that a 64-bit IEEE/MAC address will be used to specify a single target node in the destination network

  • u16PanIdis the PAN ID of the destination network - a value 0xFFFF can be used to specify a broadcast to all reachable ZigBee PRO networks

  • uAddressis the address of the target node(s) in the destination network (the address type must be as specified above in the eModefield) - a value of 0xFFFF can be used to specify a broadcast to all nodes in the destination network(s).

Parent topic:Other structures

ZPS_tsAfProfileDataReq

This structure is used to specify the transmission details for a data transmission submitted using the function ZPS_eAplAfApsdeDataReq().

The ZPS_tsAfProfileDataReqstructure is detailed below.

typedef struct {
    ZPS_tuAddress             uDstAddr;
    uint16                    u16ClusterId;
    uint16                    u16ProfileId;
    uint8                     u8SrcEp;
    ZPS_teAplApsdeAddressMode eDstAddrMode;
    uint8                     u8DstEp;
    ZPS_teAplAfSecurityMode   eSecurityMode;
    uint8                     u8Radius;
}ZPS_tsAfProfileDataReq;

where:

  • uDstAddris the address of the destination node for the transmission request (can be 16- or 64-bit, as specified by eDstAddrMode).

  • u16ClusterIdis the Cluster ID of the destination cluster.

  • u16ProfileIdis the Profile ID of the destination application profile.

  • u8SrcEpis the source endpoint number (1-240) on the local node.

  • eDstAddrModeis the type of destination address, one of (also see the table, Table):

    • ZPS_E_ADDR_MODE_BOUND (no address needed for bound nodes).

    • ZPS_E_ADDR_MODE_GROUP (16-bit group address).

    • ZPS_E_ADDR_MODE_SHORT (16-bit network address).

    • ZPS_E_ADDR_MODE_IEEE (64-bit IEEE/MAC address).

  • u8DstEpis the destination endpoint number (1-240) on the remote node.

  • eSecurityModeis the security mode for the data transfer, one of:

    • 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 the above flags using OR operator. Sends the message using the wildcard profile (0xFFFF) instead of the profile in the associated Simple descriptor).

  • u8Radiusis the maximum number of hops permitted to the destination node (zero value specifies that default maximum is to be used).

Parent topic:Other structures

tsBeaconFilterType

This structure contains the details of a beacon filter that can be introduced using the function ZPS_bAppAddBeaconFilter().

The tsBeaconFilterTypestructure is detailed below.

typedef struct
{
    uint64     *pu64ExtendPanIdList;
    uint16     u16Panid;
    uint16     u16FilterMap;
    uint8      u8ListSize;
    uint8      u8Lqi;
    uint8      u8Depth;
} tsBeaconFilterType;

where:

  • pu64ExtendPanIdListis a pointer to a list of 64-bit Extended PAN IDs (EPIDs) which acts as a blacklist or whitelist of networks, depending on the settings of bits 0 and 1 in the u8FilterMapbitmap:

    • If this is a blacklist, beacons from networks with EPIDs in the list will not be accepted

    • If this is a whitelist, only beacons from networks with EPIDs in the list will be accepted

  • u16Panidis a 16-bit PAN ID on which beacons can be filtered

  • u8ListSizeis the number of Extended PAN IDs in the list pointed to by

pu64ExtendPanIdList

  • u8Lqiis the minimum LQI value (in the range 0 to 255) of an acceptable beacon (any beacon with LQI value less than this minimum will be filtered out) - if required, this field must be enabled through bit 2 in the u8FilterMapbitmap

  • u8Depthis the tree depth of the neighbor device. A value of 0x00 indicates that the device is the ZigBee coordinator for the network.

  • u16FilterMapis an 16-bit bitmap detailing the filtering requirements, as follows:

Bit

Enumeration

Description

0

BF_BITMAP_BLACKLIST(0x1)

If set, field pu64ExtendPanIdListpoints to a blacklist of networks.

1

BF_BITMAP_WHITELIST (0x2)

If set, field pu64ExtendPanIdListpoints to a whitelist of networks.

2

BF_BITMAP_LQI (0x4)

If set, beacons must be filtered according to LQI value using the minimum in field u8Lqi.

3

BF_BITMAP_CAP_ENDDEVICE (0x8)

If set, beacons from nodes with capacity for End Device children can be accepted.

4

BF_BITMAP_CAP_ROUTER (0x10)

If set, beacons from nodes with capacity for Router children can be accepted.

5

BF_BITMAP_PERMIT_JOIN (0x20)

If set, beacons from nodes with ‘permit join- ing’ enabled can be accepted.

6

BF_BITMAP_SHORT_PAN (0x40)

If set, beacons from nodes on a network with the PAN ID in u16Panidcan be accepted.

7

-

Reserved.

8

BF_BITMAP_DEPTH

If set, beacons from nodes on a network with the depth in u8Depth. if it is set to 0xff - filters out any beacon which is not from the coordinator. Any other value of u8Depth, filters out beacons with greater than or equal to u8Depth.

Note: Bits 0 and 1 must not both be set.

Note: After each discovery or rejoin, the flags contained in the u16FilterMap field are cleared, while all other fields of this structure remain intact.

Parent topic:Other structures

ZPS_tsAplApsKeyDescriptorEntry

This structure contains a link key for secured communications with another node.

typedef struct
{
    uint32     u32OutgoingFrameCounter;
    uint16     u16ExtAddrLkup;
    uint8      au8LinkKey[ZPS_SEC_KEY_LENGTH];
} ZPS_tsAplApsKeyDescriptorEntry;

where:

  • u32OutgoingFrameCounteris the outgoing frame counter value which is incremented on each transmission to a destination address below.

  • u16ExtAddrLkupis the index of the local look-up table entry that contains the IEEE/MAC address of either the Trust Centre or the target node.

  • au8LinkKey[]is an array containing the link key.

Parent topic:Other structures

ZPS_tsAftsStartParamsDistributed

This structure contains the start parameter values for a node in a distributed security network.

typedef struct
{
    uint64     u64ExtPanId;
    uint8      *pu8NwkKey;
    uint16     u16PanId;
    uint16     u16NwkAddr;
    uint8      u8KeyIndex;
    uint8      u8LogicalChannel;
    uint8      u8NwkupdateId;
} ZPS_tsAftsStartParamsDistributed;

where:

  • u64ExtPanIdis the Extended PAN ID of the distributed security network.

  • pu8NwkKeyis a pointer to a location to receive the network key.

  • u16PanIdis the PAN ID of the network.

  • u16NwkAddris the network address of the local node.

  • u8KeyIndexis the sequence number required to identify the network key in the security set.

  • u8LogicalChannelis the number of the radio channel on which the network operates.

  • u8NwkupdateIdis a unique byte value which is incremented when the network parameters are updated (and is therefore used to determine whether a receiving node has missed an update).

Parent topic:Other structures

ZPS_tsAfFlashInfoSet

This structure contains information about the devices Flash memory sector used for the persistent storage of unique link keys on the Trust Centre, as enabled by the function ZPS_vTcInitFlash().

typedef struct
{
    uint16   u16SectorSize;
    uint16   u16CredNodesCount;
    uint8    u8SectorSet;
} ZPS_tsAfFlashInfoSet;

where:

  • u16SectorSizeis the size, in bytes, of the Flash memory sector used to store the link keys.

  • u16CredNodesCountis the maximum number of nodes for which link keys can be stored in the Flash memory sector.

  • u8SectorSetis the number of the Flash memory sector used for this storage.

Note: Care should be taken that this sector is set greater than the current flash usage of the image you are running. If this clashes with something else (image or user data), it would lead to flash corruption and the behavior might become non-deterministic.

Parent topic:Other structures

ZPS_TclkDescriptorEntry

This structure is used on the Trust Centre to hold information in RAM about a link key for a node, where this link key is held in persistent storage in devices Flash memory, as enabled by the function ZPS_vTcInitFlash(). If this feature is used, the application must allocate space for an array of these structures in RAM, with one structure for each potential node in the network.

typedef struct
{
    uint16   u16CredOffset;
    uint16   u16TclkRetries;
} ZPS_TclkDescriptorEntry;

where:

  • u16CredOffsetis the offset, in bytes, of the storage location for the node’s link key in the relevant Flash memory sector.

  • u16TclkRetriesis the number of retries that were attempted to negotiate the link key between the Trust Centre and the node.

Parent topic:Other structures

Parent topic:AF structures

Parent topic:Application Framework (AF) API