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