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