ZigBee Device Objects (ZDO) API
The chapter describes the resources of the ZigBee Device Objects (ZDO) API. This API is primarily concerned with starting, forming, and modifying a ZigBee PRO network. The API is defined in the header file zps_apl_zdo.h.
In this chapter:
ZDO API functions details the ZDO API functions.
ZDO enumerations details the ZDO API enumerations.
ZDO API functions
The ZDO API functions are divided into the following categories:
Network Deploymentfunctions, described in Network deployment functions.
Securityfunctions, described in Security functions.
Addressingfunctions, described in Addressing functions.
Routingfunctions, described in Routing functions.
Object Handlefunctions, described in Object Handle functions.
Optional Clusterfunction, described in Optional Cluster function.
Network deployment functions
The ZDO Network Deployment functions are used to start the ZigBee PRO stack, and allow devices to join the network and bind to each other, as well as leave the network.
The functions are listed below.
Function page
Note: The ZDO initialization and start stack functions use network parameter values that have been pre-set and saved using the steps described in Chapter 13, ZPS Configuration Editor.
Parent topic:Network deployment functions
ZPS_eAplZdoStartStack
ZPS\_teStatus ZPS\_eAplZdoStartStack\(void\);
Description
This function starts the ZigBee PRO stack. The steps taken depend on the node type:
If the device is the Coordinator, this function starts the network formation process.
If the device is a Router or End Device, this function starts the network discovery process - that is, the device searches for a network to join.
When the stack starts, the 2400 MHz radio channel to be used by the device is selected. The channels (in the range 11 to 26) available to the device should be specified in advance using the ZPS Configuration Editor (see Chapter 13) and can be either of the following:
A fixed channel
A set of channels for a channel scan:
If the device is the Coordinator, this is the set of channels that the device scans to find a suitable operating channel for the network.
If the device is a Router or End Device, this is the set of channels that the device scans to find a network to join.
If this function successfully initiates network formation or discovery, it returns ZPS_E_SUCCESS. Subsequent results from this process are then reported through stack events (see Events for details of these events):
If the Coordinator successfully creates a network, the event ZPS_EVENT_NWK_STARTED is generated. Otherwise, the event ZPS_EVENT_NWK_FAILED_TO_START is generated.
When the network discovery process for a Router or End Device is complete, the subsequent actions depend on the Extended PAN ID (EPID) that is pre-set using the ZPS Configuration Editor:
If a zero EPID value was pre-set, the stack event
ZPS_EVENT_NWK_DISCOVERY_COMPLETEis generated. This includes a list of the detected networks and the index (in the list) of the recommended network to join. You can then call ZPS_eAplZdoJoinNetwork() to join the desired network.If a non-zero EPID value was pre-set, the device automatically attempts to join the network with this EPID, provided that such a network has been discovered. Note that the ‘permit joining’ setting of the potential parent is ignored.
The maximum depth (number of levels below the Coordinator) of the network is 15.
Parameters
None
Parent topic:ZPS_eAplZdoStartStack
Returns
ZPS_E_SUCCESS (stack started and network formation/discovery begun)
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_eAplZdoStartStack
Parent topic:Network deployment functions
ZPS_vDefaultStack
void ZPS\_vDefaultStack\(void\);
Description
This function can be used to reset the ZigBee PRO stack to its default state. It removes previous context data for the stack, but leaves NWK layer frame counters intact.
Note: After calling this function, all security keys must be re-configured.
Parameters None
Returns None
Parent topic:Network deployment functions
ZPS_eAplZdoGetDeviceType
ZPS\_teZdoDeviceType ZPS\_eAplZdoGetDeviceType\(void\);
Description
This function can be used to obtain the ZigBee node type (Coordinator, Router, or End Device) of the local node.
Parameters
None
Returns
ZigBee node type, one of:
ZPS_ZDO_DEVICE_COORD (Coordinator)
ZPS_ZDO_DEVICE_ROUTER (Router)
ZPS_ZDO_DEVICE_ENDDEVICE (End Device)
Parent topic:Network deployment functions
ZPS_eAplZdoDiscoverNetworks
ZPS\_teStatus ZPS\_eAplZdoDiscoverNetworks\(uint32 u32ChannelMask\);
Description
This function can be used by a Router or End Device to initiate a network discovery
that is, to find a network to join.
A network discovery is performed when the stack is started using the function ZPS_eAplZdoStartStack(). The function ZPS_eAplZdoDiscoverNetworks() can be used to perform subsequent network discoveries (for example, if the initial search did not yield any suitable networks).
As part of this function call, you must specify a value which indicates the 2400-MHz radio channels (numbered 11 to 26) to be used in the network search. There are two ways of setting this parameter:
A single value in the range 11 to 26 can be specified, indicating that the corresponding channel (and no other) must be used - for example, 12 indicates use channel 12.
A 32-bit mask can be used to specify a set of channels that the device will scan to find a network - each of bits 11 to 26 represents the corresponding radio channel, where the channel will be included in the scan if the bit is set to 1 (and excluded if cleared to 0). Therefore, the value 0x07FFF800 represents all channels.
Note: If an invalid value is specified for this parameter, the default value of 0x07FFF800 (all channels) will be used.
If this function successfully initiates a network discovery, ZPS_E_SUCCESS will be returned. The network discovery results will then be reported through the event ZPS_EVENT_NWK_DISCOVERY_COMPLETE (for details of this event, refer to Section 7.2.2.9). This includes a list of the detected networks and the index (in the list) of the recommended network to join. You should then call ZPS_eAplZdoJoinNetwork() to join the desired network.
Parameters
u32ChannelMask Radio channel(s) for network discovery (see above)
Returns
ZPS_E_SUCCESS (network discovery started)
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:Network deployment functions
ZPS_eAplZdoJoinNetwork
ZPS\_teStatus ZPS\_eAplZdoJoinNetwork\(ZPS\_tsNwkNetworkDescr \*psNetworkDescr\);
Description
This function can be used by a Router or End Device to send a request to join a particular network, following a network discovery.
The required network is specified using its network descriptor, obtained in a ZPS_EVENT_NWK_DISCOVERY_COMPLETE event which results from a network discovery previously implemented using ZPS_eAplZdoStartStack() or ZPS_eAplZdoDiscoverNetworks(). For details of this event, refer to ZPS_tsAfNwkDiscoveryEvent.
If the join request is successfully sent, the function will return ZPS_E_SUCCESS (note that this does not mean that device has joined the network). The result of the join request will then be reported through a stack event (see Events for details of these events):
If the device successfully joined the network as a Router, the event ZPS_EVENT_NWK_JOINED_AS_ROUTER is generated. The allocated 16-bit network address of the Router is returned as part of this stack event.
If the device successfully joined the network as an End Device, the event ZPS_EVENT_NWK_JOINED_AS_ENDDEVICE is generated. The allocated 16-bit network address of the End Device is returned as part of this stack event.
If the join request was unsuccessful, the event ZPS_EVENT_NWK_FAILED_TO_JOIN is generated.
Note: Note that nodes can join a ZigBee PRO network to a maximum depth of 15 (levels below the Coordinator).
Parameters
*psNetworkDescr Pointer to network descriptor of network to join.
Returns
ZPS_E_SUCCESS (join request successfully sent)
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:Network deployment functions
ZPS_eAplZdoRejoinNetwork
**ZPS\_teStatus ZPS\_eAplZdoRejoinNetwork\(bool\_t bWithDiscovery\);**
This function can be used by an active Router or End Device to send a request to rejoin its previous network. The function should be called if the application detects that it has lost its connection to the network - this is indicated by an excessive number of failed communications (for example, with many missing acknowledgments).
Options are provided to first perform a network discovery to find potential parents to join or simply rejoin the previous parent.
If the rejoin request is successfully sent, the function returns ZPS_E_SUCCESS. Note that this does not mean that device has rejoined the network. The result of the rejoin request is then reported through a stack event (see Section 10.1 for details of these events):
If the device successfully rejoined the network as a Router, the event ZPS_EVENT_NWK_JOINED_AS_ROUTER is generated.
If the device successfully rejoined the network as an End Device, the event ZPS_EVENT_NWK_JOINED_AS_ENDDEVICE is generated.
If the rejoin request was unsuccessful, the event ZPS_EVENT_NWK_FAILED_TO_JOIN is generated.
In the case of a successful rejoin, the node will retain its previously allocated 16-bit network address.
Note that the ‘permit joining’ status of the potential parent is ignored during a rejoin.
Parameters
bWithDiscovery Specifies whether a network discovery is required:
TRUE - perform network discovery before rejoining
FALSE - rejoin previous parent
TRUE - perform network discovery before rejoining
FALSE - rejoin previous parent
ZPS_E_SUCCESS (rejoin request successfully sent)
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:Network deployment functions
ZPS_eAplZdoDirectJoinNetwork
ZPS_teStatus ZPS_eAplZdoDirectJoinNetwork( uint64 u64Addr, uint16 u16Addr, uint8 u8Capability);
Description
This function can be used on a Router and on the Coordinator to pre-determine the child nodes that will directly join it. The function is called to register each child node separately, and the IEEE/MAC and network addresses of the child node must be specified. The function adds the registered node to its Neighbor table (it actually adds the node’s IEEE/MAC address to the MAC Address table and then includes the index of this address in a Neighbor table entry for the node).
The function must be called only when the parent node is fully up and running in the network. Since the child node has not yet joined the network but is in the Neighbor table, it will be perceived by the parent as having been orphaned. Therefore, when the child node attempts to join the network, it must perform a rejoin as an orphan by calling the function ZPS\_eAplZdoOrphanRejoinNetwork\(\).
Note: You should only modify the Neighbor table using this function and never write to it directly.
Parameters
u64Addr IEEE/MAC address of child node to be registered
u16Addr Network address of child node to be registered
u8Capability A bitmap indicating the operational capabilities of the child node - this bitmap is detailed in Table in section ZPS_tsAfNwkJoinIndEvent.
Returns
ZPS_E_SUCCESS(child node successfully registered)ZPS_APL_APS_E_ILLEGAL_REQUEST(address 0x0, address 0xFFFFFFFFFFFFFFFF, own address, ZDO busy)ZPS_NWK_ENUM_ALREADY_PRESENTZPS_NWK_ENUM_NEIGHBOR_TABLE_FULL
Parent topic:Network deployment functions
ZPS_eAplZdoOrphanRejoinNetwork
ZPS_teStatus ZPS_eAplZdoOrphanRejoinNetwork(void);
This function can be used by an orphaned node to attempt to rejoin the network - the orphaned node may be an End Device or a Router. The function should also be used for a first-time join for which the parent has been pre-determined using the function ZPS_eAplZdoDirectJoinNetwork().
The function starts the stack on the node. Therefore, when this function is used, there is no need to explicitly start the stack using ZPS_eAplZdoStartStack().
If the rejoin request is successfully sent, the function will return ZPS_E_SUCCESS (note that this does not mean that device has rejoined the network). The result of the rejoin request will then be reported through a stack event (see Section 10.1 for details of these events):
If the device successfully rejoined the network as a Router, the event
ZPS_EVENT_NWK_JOINED_AS_ROUTERis generated.If the device successfully rejoined the network as an End Device, the event
ZPS_EVENT_NWK_JOINED_AS_ENDDEVICEis generated.If the rejoin request was unsuccessful, the event
ZPS_EVENT_NWK_FAILED_TO_JOINis generated.
In the case of a successful rejoin of a genuinely orphaned node, the node will retain its previously allocated 16-bit network address.
Note: The ‘permit joining’ status of the potential parent is ignored during a rejoin.
Parameters
None
Parent topic:ZPS_eAplZdoOrphanRejoinNetwork
Returns
ZPS_E_SUCCESS(rejoin request successfully sent)ZPS_APL_APS_E_ILLEGAL_REQUEST(missing EPID, called from Coordinator, ZDO busy)
Parent topic:ZPS_eAplZdoOrphanRejoinNetwork
Parent topic:Network deployment functions
ZPS_eAplZdoPermitJoining
ZPS_teStatus ZPS_eAplZdoPermitJoining(
uint8 u8PermitDuration);
Description
This function can be used on a Router or the Coordinator to control whether new child nodes are allowed to join it - that is, to set the node’s ‘permit joining’ status. The function can be used to enable joining permanently or for a fixed duration, or to disable joining (permanently).
The specified parameter value determines the ‘permit joining’ status, as follows:
0: Disables joining1- 254: Enables joining for specified time interval, in seconds255: Enables joining permanently
For example, if the parameter is set to 60, joining is enabled for the next 60 seconds and then automatically disabled.
Note: The ‘permit joining’ setting of a device is ignored during a join attempt in which a non-zero Extended PAN ID is specified on the joining device and during any rejoin attempt.
Parent topic:ZPS_eAplZdoPermitJoining
Parameters
u8PermitDuration Time duration, in seconds, for which joining will be permitted (see above)
Parent topic:ZPS_eAplZdoPermitJoining
Returns
ZPS_E_SUCCESS(‘permit joining’ status 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_eAplZdoPermitJoining
Parent topic:Network deployment functions
ZPS_u16AplZdoGetNetworkPanId
uint16 ZPS_u16AplZdoGetNetworkPanId(void);
Description
This function obtains the 16-bit PAN ID of the ZigBee network to which the local node currently belongs.
Parent topic:ZPS_u16AplZdoGetNetworkPanId
Parameters
None.
Parent topic:ZPS_u16AplZdoGetNetworkPanId
Returns
PAN ID of current network.
Parent topic:ZPS_u16AplZdoGetNetworkPanId
Parent topic:Network deployment functions
ZPS_u64AplZdoGetNetworkExtendedPanId
uint64 ZPS_u64AplZdoGetNetworkExtendedPanId(void)
Description
This function obtains the 64-bit Extended PAN ID (EPID) of the ZigBee PRO network to which the local node currently belongs.
Parent topic:ZPS_u64AplZdoGetNetworkExtendedPanId
Parameters
None
Parent topic:ZPS_u64AplZdoGetNetworkExtendedPanId
Returns
Extended PAN ID of current network.
Parent topic:ZPS_u64AplZdoGetNetworkExtendedPanId
Parent topic:Network deployment functions
ZPS_u8AplZdoGetRadioChannel
uint8 ZPS_u8AplZdoGetRadioChannel(void);
Description
This function obtains the 2400-MHz band channel in which the local node is currently operating. The channel is represented by an integer in the range 11 to 26.
Parent topic:ZPS_u8AplZdoGetRadioChannel
Parameters
None.
Parent topic:ZPS_u8AplZdoGetRadioChannel
Returns
Radio channel number (in range 11-26).
Parent topic:ZPS_u8AplZdoGetRadioChannel
Parent topic:Network deployment functions
ZPS_eAplZdoBind
ZPS_teStatus ZPS_eAplZdoBind(
uint16 u16ClusterId,
uint8 u8SrcEndpoint,
uint16 u16DstAddr,
uint64 u64DstIeeeAddr,
uint8 u8DstEndpoint);
Description
This function requests a binding to be created between an endpoint on the local node and an endpoint on a remote node. The source endpoint and cluster must be specified, as well as the destination node and endpoint. The destination node is specified using both its 64-bit IEEE (MAC) address and its 16-bit network address.
The binding is added to the binding table on the local node.
A binding to multiple remote endpoints (collected into a group) can be created using the function ZPS_eAplZdoBindGroup().
Parent topic:ZPS_eAplZdoBind
Parameters
u16ClusterId Identifier of cluster on source node to be bound u8SrcEndpoint Number of endpoint (1-240) on source node to be bound u16DstAddr 16-bit network address of destination for binding u64DstIeeeAddr 64-bit IEEE (MAC) address of destination for binding u8DstEndpoint Number of endpoint on destination node to be bound
Parent topic:ZPS_eAplZdoBind
Returns
ZPS_E_SUCCESS (binding successfully created)
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_eAplZdoBind
Parent topic:Network deployment functions
ZPS_eAplZdoUnbind
ZPS_teStatus ZPS_eAplZdoUnbind(
uint16 u16ClusterId,
uint8 u8SrcEndpoint,
uint16 u16DstAddr,
uint64 u64DstIeeeAddr,
uint8 u8DstEndpoint);
Description
This function requests an existing binding to be removed between an endpoint on the local node and an endpoint on a remote node, where this binding was created using the function ZPS_eAplZdoBind(). The source endpoint and cluster must be specified, as well as the destination node and endpoint. The destination node is specified using both its 64-bit IEEE (MAC) address and its 16-bit network address.
The binding is removed from the binding table on the local node.
Parent topic:ZPS_eAplZdoUnbind
Parameters
u16ClusterId Identifier of bound cluster on source node u8SrcEndpoint Number of bound endpoint (1-240) on source node u16DstAddr 16-bit network address of destination for binding u64DstIeeeAddr 64-bit IEEE (MAC) address of destination for binding u8DstEndpoint Number of bound endpoint on destination node
Parent topic:ZPS_eAplZdoUnbind
Returns
ZPS_E_SUCCESS (binding successfully removed)
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_eAplZdoUnbind
Parent topic:Network deployment functions
ZPS_eAplZdoBindGroup
ZPS_teStatus ZPS_eAplZdoBindGroup(
uint16 u16ClusterId,
uint8 u8SrcEndpoint,
uint16 u16DstGrpAddr);
Description
This function requests a binding to be created between an endpoint on the local node and multiple endpoints on remote nodes. The source endpoint and cluster must be specified, as well as the destination nodes/endpoints for the binding, which must be specified using a 16-bit group address, previously set up using ZPS_eAplZdoGroupEndpointAdd().
The binding is added to the binding table on the local node.
Parent topic:ZPS_eAplZdoBindGroup
Parameters
u16ClusterId Identifier of cluster on source node to be bound u8SrcEndpoint Number of endpoint (1-240) on source node to be bound u16DstGrpAddr 16-bit group address of destination group for binding
Parent topic:ZPS_eAplZdoBindGroup
Returns
ZPS_E_SUCCESS (binding successfully created)
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_eAplZdoBindGroup
Parent topic:Network deployment functions
ZPS_eAplZdoUnbindGroup
ZPS_teStatus ZPS_eAplZdoUnbindGroup(
uint16 u16ClusterId,
uint8 u8SrcEndpoint,
uint16 u16DstGrpAddr);
Description
This function requests an existing binding to be removed between an endpoint on the local node and a group of endpoints on remote nodes, where this binding was created using the function ZPS_eAplZdoBindGroup(). The source endpoint and cluster must be specified, as well as the destination nodes/endpoints for the binding, which must be specified using a 16-bit group address.
The binding is removed from the binding table on the local node.
Parent topic:ZPS_eAplZdoUnbindGroup
Parameters
u16ClusterId Identifier of bound cluster on source node
u8SrcEndpoint Number of bound endpoint (1-240) on source node
u16DstGrpAddr 16-bit group address of bound destination group
Parent topic:ZPS_eAplZdoUnbindGroup
Returns
ZPS_E_SUCCESS (binding successfully removed)
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_eAplZdoUnbindGroup
Parent topic:Network deployment functions
ZPS_ePurgeBindTable
ZPS_teStatus ZPS_ePurgeBindTable(void);
Description
This function removes all bindings from the binding table on the local node.
Parent topic:ZPS_ePurgeBindTable
Parameters
None
Parent topic:ZPS_ePurgeBindTable
Returns
ZPS_E_SUCCESS (binding successfully removed)
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_ePurgeBindTable
Parent topic:Network deployment functions
ZPS_eAplZdoPoll
ZPS_teStatus ZPS_eAplZdoPoll(void);
Description
This function can be used by an End Device to poll its parent for pending data.
Since an End Device is able to sleep, messages addressed to the End Device are buffered by the parent for delivery when the child is ready. This function requests this buffered data and should normally be called immediately after waking from sleep.
This function call will trigger a confirmation event, ZPS_EVENT_NWK_POLL_CONFIRM, if the poll request is successfully sent to the parent. The subsequent arrival of data from the parent is indicated by a ZPS_EVENT_APS_DATA_INDICATION event. Any messages forwarded from the parent should then be collected using the function ZQ_bZQueueReceive().
Parent topic:ZPS_eAplZdoPoll
Parameters
None
Parent topic:ZPS_eAplZdoPoll
Returns
ZPS_E_SUCCESS
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4
Parent topic:ZPS_eAplZdoPoll
Parent topic:Network deployment functions
ZPS_eAplZdoLeaveNetwork
ZPS_teStatus ZPS_eAplZdoLeaveNetwork(
uint64 u64Addr,
bool bRemoveChildren,
bool bRejoin);
Description
This function can be used to request a node to leave the network. The leaving node can be a child of the requesting node or can be the requesting node itself (excluding the Coordinator).
The node being asked to leave the network is specified by means of its IEEE (MAC) address (or zero, if a node is requesting itself to leave the network). You must also:
Use the parameter bRemoveChildren to specify whether children of the leaving node must leave their parent - if this is the case, the leaving node will automatically call ZPS_eAplZdoLeaveNetwork() for each of its children. This parameter must always be set to FALSE when the function is called on an End Device (as there are no children).
Use the parameter bRejointo specify whether the leaving node must attempt to rejoin the network (probably via another parent) immediately after leaving.
Note: If you wish to move a whole network branch from under the requesting node to a different parent node, set bRemoveChildren to FALSE and bRejoin to TRUE.
If this function successfully initiates the removal of a node, ZPS_E_SUCCESS will be returned. Subsequently, when the removal is complete, the stack event ZPS_EVENT_NWK_LEAVE_CONFIRM is generated. For details of this event, refer to Section 7.2.2.12.
Parent topic:ZPS_eAplZdoLeaveNetwork
Parameters
u64Addr 64-bit IEEE (MAC) address of node to leave network (zero value will cause requesting node to leave network)
bRemoveChildren Boolean value indicating whether children of leaving node must leave their parent:
TRUE: Children to leave FALSE: Children not to leave
bRejoin Boolean value indicating whether leaving node must attempt to rejoin network immediately after leaving:
TRUE: Rejoin network immediately FALSE: Do not rejoin network
Parent topic:ZPS_eAplZdoLeaveNetwork
Returns
ZPS_E_SUCCESS (removal of node successfully started)
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_eAplZdoLeaveNetwork
Parent topic:Network deployment functions
ZPS_vNwkNibSetLeaveAllowed
void ZPS_vNwkNibSetLeaveAllowed(void *pvNwk,
bool bLeave);
Description
This function can be called on a Router or End Device to determine whether the device should leave the network on receiving a leave request. It has no effect on a Coordinator.
If called with bLeave set to TRUE, the device obeys a leave request.
If called with bLeave set to FALSE, the device ignores a leave request.
Parent topic:ZPS_vNwkNibSetLeaveAllowed
Parameters
pvNwk Pointer to NWK layer instance
bLeaveBoolean value indicating whether the device leaves the network when requested or ignores leave request messages:
TRUE - Obey leave request messages.
FALSE - Ignore leave request messages.
Parent topic:ZPS_vNwkNibSetLeaveAllowed
Returns
None
Parent topic:ZPS_vNwkNibSetLeaveAllowed
Parent topic:Network deployment functions
ZPS_vNwkNibSetLeaveRejoin
void ZPS_vNwkNibSetLeaveRejoin(void *pvNwk,
bool bRejoin);
Description
This function can be called on a Router or End Device to configure the device to automatically rejoin after leaving the network, even when a ‘leave without rejoin’ was requested.
If called with bRejoin set to TRUE, the device will rejoin following a leave.
If called with bRejoin set to FALSE, the device will not rejoin following a leave.
Parent topic:ZPS_vNwkNibSetLeaveRejoin
Parameters
pvNwk Pointer to NWK layer instance
bLeave Boolean value indicating whether the device will rejoin the network following a leave:
TRUE - Rejoin the network
FALSE - Do not rejoin the network
Parent topic:ZPS_vNwkNibSetLeaveRejoin
Returns
None
Parent topic:ZPS_vNwkNibSetLeaveRejoin
Parent topic:Network deployment functions
ZPS_vSetTablesClearOnLeaveWithoutRejoin
void ZPS_vSetTablesClearOnLeaveWithoutRejoin(
bool_t bClear);
Description
This function can be called on a Router or End Device to configure whether various tabulated context data must be cleared from the node when it leaves the network without the intention to rejoin.
By default, the Neighbor table, Binding table and Group table are cleared on a Router, and the network key is cleared on a Router and End Device. In addition, other devices remove the node from their Binding tables on detecting the leave request (without the rejoin flag set).
This function can be used to over-ride this behavior in order to preserve this table data. It can also be used to later reinstate the default behavior.
Parent topic:ZPS_vSetTablesClearOnLeaveWithoutRejoin
Parameters
bClear Boolean value indicating whether the node should clear the table data when leaving the network without a future rejoin:
TRUE - Clear table data (default behavior)
FALSE - Do not clear table data
Parent topic:ZPS_vSetTablesClearOnLeaveWithoutRejoin
Returns
None
Parent topic:ZPS_vSetTablesClearOnLeaveWithoutRejoin
Parent topic:Network deployment functions
ZPS_vNtSetUsedStatus
void ZPS_vNtSetUsedStatus(
void *pvNwk,
ZPS_tsNwkActvNtEntry *psActvNtEntry,
bool_t bStatus);
Description
This function can be used to set the status of a local Neighbor Table to either ‘used’ or ‘unused’:
Setting the status of an entry to unused effectively removes the entry from the table.
Setting the status of an entry to used effectively adds an entry to the table.
When adding an entry to the table, it is first necessary for the application to find an entry marked unused. The entry can then be populated with data and marked as used via this function.
Parent topic:ZPS_vNtSetUsedStatus
Parameters
pvNwk Pointer to NWK layer instance
psActvNtEntryPointer to Neighbor Table entry to access (this must be populated with data when adding a new entry to the table)
bStatus Entry status to be set:
TRUE - Set entry status to ‘used’
FALSE - Set entry status to ‘unused’
Parent topic:ZPS_vNtSetUsedStatus
Returns
None
Parent topic:ZPS_vNtSetUsedStatus
Parent topic:Network deployment functions
ZPS_vNwkSendNwkStatusCommand
void ZPS_vNwkSendNwkStatusCommand(
void *pvNwk,
uint16 u16DstAddress,
uint16 u16TargetAddress,
uint8 u8CommandId,
uint8 u8Radius);
Description
This function can be used to send a network status command to another node. For example, it can be used by an End Device to report a routing problem (concerning a remote node) to its parent.
Parent topic:ZPS_vNwkSendNwkStatusCommand
Parameters
pvNwk Pointer to NWK layer instance
u16DstAddress Network address of the remote node to which the status command relates (for example, the node for which a routing problem is being reported)
u16TargetAddress Network address of the node to which the status command is to be sent (for example, the parent of the local node)
u8CommandId Value representing the network status command to be sent (the possible values are provided in the ZigBee PRO specification)
u8Radius Maximum number of hops permitted to target node (zero value specifies that default maximum is to be used)
Parent topic:ZPS_vNwkSendNwkStatusCommand
Returns
None
Parent topic:ZPS_vNwkSendNwkStatusCommand
Parent topic:Network deployment functions
ZPS_eAplZdoRegisterZdoLeaveActionCallback
void ZPS_eAplZdoRegisterZdoLeaveActionCallback(
void *fnPtr);
Description
This function can be used to register a user-defined callback function that will be invoked when a leave request, a management leave request or a remove device request (from a remote node, normally the Trust Centre) is received by the local node. The callback function must determine whether the request must be obeyed or ignored by the stack - this decision may depend on the originator of the request.
The prototype of the callback function is as follows:
bool_t ZPS_bPerformLeaveActionDecider(uint8 u8Value ,
uint64 u64Address, uint8 u8Flags);
where:
u8Value is an enumerated value indicating the type of request - one of: ZPS_LEAVE_ORIGIN_NLME (NLME-LEAVE.request from NWK layer) ZPS_LEAVE_ORIGIN_MGMT_LEAVE (management leave request) ZPS_LEAVE_ORIGIN_REMOVE_DEVICE (remove request from remote node)
u64Address is the IEEE/MAC address of the node that issued the request
u8Flags is a user-defined bitmap containing flagged information
The callback function must return TRUE to allow or FALSE to disallow the requested leave.
Parent topic:ZPS_eAplZdoRegisterZdoLeaveActionCallback
Parameters
fnPtr: Pointer to user-defined callback function to be registered.
Parent topic:ZPS_eAplZdoRegisterZdoLeaveActionCallback
Returns
None
Parent topic:ZPS_eAplZdoRegisterZdoLeaveActionCallback
Parent topic:Network deployment functions
Parent topic:ZDO API functions
Security functions
The ZDO Security functions are used to set up network security (at the ‘standard’ level), including the keys used in the encryption/decryption of network communications.
The functions are listed below.
Function page
Note:
Before using the above functions on a node, security must be enabled on the node via the device parameter
Security Enabledin the ZPS Configuration Editor (security is enabled by default).Enabling security also enables many-to-one routing toward the Trust Centre, which then becomes a network concentrator. You must set the maximum number of nodes to be serviced by the Trust Centre using its network parameter
Route Record Table Sizein the ZPS Configuration Editor (the default number is 4).Many of the security settings and keys that are set up using the above functions can alternatively be pre-configured via the ZPS Configuration Editor.
Parent topic:Security functions
ZPS_vAplSecSetInitialSecurityState
ZPS_teStatus ZPS_vAplSecSetInitialSecurityState(
ZPS_teZdoNwkKeyState eState,
uint8 *pu8Key,
uint8 u8KeySeqNum
ZPS_teApsLinkKeyType eKeyType);
Description
This function is used to configure the initial state of ZigBee security on the local node. This requires a security key to be specified that is used in setting up network-level security.
Note: Before using this function, security must be enabled on the node via the device parameter Security Enabled in the ZPS Configuration Editor.
You must provide a pointer to an initial link key of one of the following types:
Pre-configured global link key
Pre-configured unique link key
These key types are described in Section 6.8.2. The network key randomly generated by the Trust Centre is communicated to the local node in encrypted form using the specified link key.
Parameters
eState: The state of the link key, one of:
ZPS_ZDO_PRECONFIGURED_LINK_KEY
ZPS_ZDO_ZLL_LINK_KEY
pu8Key: Pointer to pre-configured link key
u8KeySeqNum: Not used when specifying a link key - ignore this parameter
eKeyType: Type of link key, one of:
ZPS_APS_UNIQUE_LINK_KEY
ZPS_APS_GLOBAL_LINK_KEY
Parent topic:ZPS_vAplSecSetInitialSecurityState
Returns
ZPS_E_SUCCESS (security state successfully initialized)
APS return codes, listed and described in Section 11.2.2
NWK return codes, listed and described in Section 11.2.3
MAC return codes, listed and described in Section 11.2.4
Parent topic:ZPS_vAplSecSetInitialSecurityState
Parent topic:Security functions
ZPS_eAplZdoTransportNwkKey
ZPS\_teStatus ZPS\_eAplZdoTransportNwkKey\(
uint8 u8DstAddrMode,
ZPS\_tuAddress uDstAddress,
uint8 au8Key[ZPS_SEC_KEY_LENGTH],
uint8 u8KeySeqNum,
bool bUseParent,
uint64 u64ParentAddr);
Description
This function can be used on the Trust Centre to send the network key to one or multiple nodes. On reaching the target node(s), the key is only stored but can be subsequently designated the active network key using the function ZPS_eAplZdoSwitchKeyReq().
The target node can be specified by means of its network address or IEEE/MAC address. A broadcast to multiple nodes in the network can be achieved by specifying a special network address or IEEE/MAC address - see Section 9.3.
If the destination is a single node, it is possible to send the key to the parent of the destination node.
Note: This function also resets the frame counter on the target node(s).
Parent topic:ZPS_eAplZdoTransportNwkKey
Parameters
u8DstAddrMode Type of destination address:
ZPS_E_ADDR_MODE_SHORT - 16-bit network address.
ZPS_E_ADDR_MODE_IEEE - 64-bit IEEE/MAC address.
All other values are reserved.
uDstAddress: Destination address (address type as specified through u8DstAddrMode) - special broadcast addresses are detailed in Section 9.3
au8Key[]: Array containing the network key to be transported. This array has a length equal to ZPS_SEC_KEY_LENGTH
u8KeySeqNum: Sequence number of the specified key
bUseParent: Indicates whether to send key to parent of target node:
TRUE - send to parent
FALSE - do not send to parent
u64ParentAddr: 64-bit IEEE/MAC address of parent (if used).
Parent topic:ZPS_eAplZdoTransportNwkKey
Returns
ZPS_E_SUCCESS (key successfully sent)
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_eAplZdoTransportNwkKey
Parent topic:Security functions
ZPS_eAplZdoSwitchKeyReq
ZPS_teStatus ZPS_eAplZdoSwitchKeyReq(
uint8 u8DstAddrMode,
ZPS_tuAddress uDstAddress,
uint8 u8KeySeqNum);
Description
This function can be used (normally by the Trust Centre) to request one or multiple nodes to switch to a different active network key. The new network key is specified using its unique sequence number and the key must have been pre-loaded into the target node(s) using the function ZPS_eAplZdoTransportNwkKey() or ZPS_eAplZdoRequestKeyReq().
The target node can be specified by means of its network address or IEEE/MAC address. A broadcast to multiple nodes in the network can be achieved by specifying a special network address or IEEE/MAC address - see Section 9.3.
Parent topic:ZPS_eAplZdoSwitchKeyReq
Parameters
u8DstAddrMode Type of destination address:
ZPS_E_ADDR_MODE_SHORT - 16-bit network address.
ZPS_E_ADDR_MODE_IEEE - 64-bit IEEE/MAC address.
All other values are reserved.
uDstAddress Destination address (address type as specified through u8DstAddrMode) - special broadcast addresses are detailed in Section 9.3.
u8KeySeqNum Sequence number of new network key to adopt.
Parent topic:ZPS_eAplZdoSwitchKeyReq
Returns
ZPS_E_SUCCESS (request successfully sent)
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_eAplZdoSwitchKeyReq
Parent topic:Security functions
ZPS_eAplZdoRequestKeyReq
ZPS_teStatus ZPS_eAplZdoRequestKeyReq(
uint8 u8KeyType,
uint64 u64IeeePartnerAddr);
Description
This function can be used to request a link key from the Trust Centre for application-level security. The possible key types that can be requested are:
Application link key: This key is used to encrypt/decrypt communications with another ‘partner node’. The IEEE/MAC address of this partner node must be specified as part of the function call. The Trust Centre responds by sending the application link key to both the local node and the partner node. When it arrives, the stack automatically saves this key. Also, the event ZPS_EVENT_ZDO_LINK_KEY is generated once the link key has been installed and is ready for use.
Trust Centre Link Key (TCLK): This key is used to encrypt/decrypt communications between the Trust Centre and the local node. The Trust Centre responds by sending the TCLK to the requesting node.
While requesting a TCLK, the function parameter u64IeeePartnerAddris ignored.
For more information on requesting link keys, refer to Section 6.8.3.2.
Parent topic:ZPS_eAplZdoRequestKeyReq
Parameters
u8KeyType Type of key to request:
2 - application link key
4 - Trust Centre Link Key (TCLK)
All other values reserved
u64IeeePartnerAddr IEEE/MAC address of partner node (for application link key)
Parent topic:ZPS_eAplZdoRequestKeyReq
Returns
ZPS_E_SUCCESS (request successfully sent)
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_eAplZdoRequestKeyReq
Parent topic:Security functions
ZPS_eAplZdoAddReplaceLinkKey
ZPS_teStatus ZPS_eAplZdoAddReplaceLinkKey(
uint64 u64IeeeAddr,
uint8 au8Key[ZPS_SEC_KEY_LENGTH],
ZPS_teApsLinkKeyType eKeyType);
Description
This function can be used to introduce or replace the application link key on the local node, where this key is used to encrypt and decrypt communications with the specified ‘partner node’. If an application link key already exists, then it is replaced.
The function must be called on both the local node and the partner node. Note that the Trust Centre’s record of the application link key for this pair of nodes remains unchanged.
If the JCU Non-Volatile Memory Manager (NVM) module is enabled, this function also saves the application link key to Non-Volatile Memory. This allows the key to be automatically recovered during a subsequent cold start (for example, following a power failure).
The eKeyType parameter of this function can be used to specify ‘unique’ or ‘global’. This does not relate to the type of key being added or replaced, which is always a unique key.
Setting this parameter to ‘unique’ means that the node only ever uses the unique key.
Setting the parameter to ‘global’ means that the node uses the unique key, where appropriate, and also the pre-configured global link key, where appropriate. For example, the global key would be used when another node joins the network via the local node.
Parent topic:ZPS_eAplZdoAddReplaceLinkKey
Parameters
u64IeeeAddr: 64-bit IEEE/MAC address of partner node for which the specified link key is valid.
au8Key[]: Array containing the link key to be added/replaced. This array has a length equal to ZPS_SEC_KEY_LENGTH.
eKeyType: Type of the key to be used by the node (see above), one of the below:
ZPS_APS_UNIQUE_LINK_KEY, or
ZPS_APS_GLOBAL_LINK_KEY.
Parent topic:ZPS_eAplZdoAddReplaceLinkKey
Returns
ZPS_E_SUCCESS (link key successfully installed)
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_eAplZdoAddReplaceLinkKey
Parent topic:Security functions
ZPS_eAplZdoAddReplaceInstallCodes
ZPS_teStatus ZPS_eAplZdoAddReplaceInstallCodes(
uint64 u64IeeeAddr,
uint8 au8InstallCode[ZPS_INSTALL_CODE_LENGTH],
uint8 u8InstallCodeSize,
ZPS_teApsLinkKeyType eKeyType);
Description
This function can be used on the Trust Centre to generate a pre-configured unique link key from an install code, where this key is used to encrypt and decrypt communications between the Trust Centre and the specified node (install codes are described in the ZigBee Devices User Guide (JNUG3131)). If a pre-configured link key already exists for the node then it will be replaced.
The function must be called on the Trust Centre only. The other node will have the relevant pre-configured unique link key factory-installed.
If the JCU Non-Volatile Memory Manager (NVM) module is enabled, this function also saves the link key to Non-Volatile Memory. This allows the key to be automatically recovered during a subsequent cold start (for example, following a power failure).
The eKeyTypeparameter of this function can be used to specify ‘unique’ or ‘global’. This does not relate to the type of key being added or replaced, which is always a unique key.
Setting this parameter to ‘unique’ means that the Trust Centre only, ever uses the unique key with this node.
Setting the parameter to ‘global’ means that the Trust Centre uses the pre-configured global link key (if available) when there is no unique link key for the node.
Parent topic:ZPS_eAplZdoAddReplaceInstallCodes
Parameters
u64IeeeAddr 64-bit IEEE/MAC address of node for which the generated link key is valid.
au8InstallCode[] Array containing the install code - the array length ZPS_INSTALL_CODE_LENGTH is given below in u8InstallCodeSize.
u8InstallCodeSize Number of characters in the install code - this is the size of the array au8InstallCode[].
eKeyType Type of the key to be used by the node (see above), one of the below:
ZPS_APS_UNIQUE_LINK_KEY
ZPS_APS_GLOBAL_LINK_KEY
Parent topic:ZPS_eAplZdoAddReplaceInstallCodes
Returns
ZPS_E_SUCCESS (permissions successfully obtained)
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_eAplZdoAddReplaceInstallCodes
Parent topic:Security functions
ZPS_eAplZdoRemoveLinkKey
ZPS_teStatus ZPS_eAplZdoRemoveLinkKey(
uint64 u64IeeeAddr);
Description
This function can be used to remove the current application link key that is used to encrypt and decrypt communications between the local node and the specified ‘partner node’.
The function must be called on both the local node and the partner node. Note that the Trust Centre’s record of the application link key for this pair of nodes remains unchanged.
In the absence of an application link key, communications between these nodes is subsequently secured using the network key.
Parent topic:ZPS_eAplZdoRemoveLinkKey
Parameters
u64IeeeAddr: 64-bit IEEE/MAC address of partner node for which the link key is to be removed.
Parent topic:ZPS_eAplZdoRemoveLinkKey
Returns
ZPS_E_SUCCESS (permissions successfully removed)
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_eAplZdoRemoveLinkKey
Parent topic:Security functions
ZPS_eAplZdoRemoveDeviceReq
ZPS_teStatus ZPS_eAplZdoRemoveDeviceReq(
uint64 u64ParentAddr,
uint64 u64ChildAddr);
Description
This function can be used (normally by the Coordinator/Trust Centre) to request another node (such as a Router) to remove one of its children from the network (for example, if the child node does not satisfy security requirements).
The Router receiving this request ignores the request unless it has originated from the Trust Centre or is a request to remove itself. If the request was sent without APS layer encryption, the device ignores the request. If APS layer security is not in use, the alternative function ZPS_eAplZdoLeaveNetwork() should be used.
Parent topic:ZPS_eAplZdoRemoveDeviceReq
Parameters
u64ParentAddr 64-bit IEEE/MAC address of parent to be instructed.
u64ChildAddr 64-bit IEEE/MAC address of child node to be removed.
Parent topic:ZPS_eAplZdoRemoveDeviceReq
Returns
ZPS_E_SUCCESS (request successfully sent)
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_eAplZdoRemoveDeviceReq
Parent topic:Security functions
ZPS_eAplZdoSetDevicePermission
void ZPS_eAplZdoSetDevicePermission(
ZPS_teDevicePermissions u8DevicePermissions);
Description
This function can be used on any device to set the permissions for certain requests from other nodes. The possible settings are:
Allow all requests from all other nodes (ALL_PERMITED)
Do not allow join requests from all other nodes (JOIN_DISALLOWED)
Do not allow data requests from all other nodes (DATA_REQUEST_DISALLOWED)
The function is particularly useful in disabling the generation of APS (end-to-end) acknowledgments, using DATA_REQUEST_DISALLOWED.
Parent topic:ZPS_eAplZdoSetDevicePermission
Parameters
u8DevicePermissions: Bitmap of permissions to be set, constructed using the following enumerations:
ZPS_DEVICE_PERMISSIONS_ALL_PERMITED
ZPS_DEVICE_PERMISSIONS_JOIN_DISALLOWED
ZPS_DEVICE_PERMISSIONS_DATA_REQUEST_DISALLOWED
Parent topic:ZPS_eAplZdoSetDevicePermission
Returns
ZPS_E_SUCCESS (permissions 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_eAplZdoSetDevicePermission
Parent topic:Security functions
ZPS_bAplZdoTrustCenterSetDevicePermissions
ZPS_teStatus
ZPS_bAplZdoTrustCenterSetDevicePermissions(
uint64 u64DeviceAddr,
ZPS_teTCDevicePermissions u8DevicePermissions);
Description
This function can be used by the Trust Centre to set the permissions for certain requests from a particular node. The possible settings are:
Allow all requests from the specified node (ALL_PERMITED)
Do not allow join requests from the specified node (JOIN_DISALLOWED)
Do not allow data requests from the specified node (DATA_REQUEST_DISALLOWED)
Parent topic:ZPS_bAplZdoTrustCenterSetDevicePermissions
Parameters
u64DeviceAddr: 64-bit IEEE/MAC address of node for which permissions are to be set
u8DevicePermissions: Bitmap of permissions to be set, constructed using the following enumerations:
ZPS_TRUST_CENTER_ALL_PERMITED
ZPS_TRUST_CENTER_JOIN_DISALLOWED
ZPS_TRUST_CENTER_DATA_REQUEST_DISALLOWED
Parent topic:ZPS_bAplZdoTrustCenterSetDevicePermissions
Returns
ZPS_E_SUCCESS (permissions 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_bAplZdoTrustCenterSetDevicePermissions
Parent topic:Security functions
ZPS_bAplZdoTrustCenterGetDevicePermissions
ZPS_teStatus
ZPS_bAplZdoTrustCenterGetDevicePermissions(
uint64 u64DeviceAddr,
ZPS_teTCDevicePermissions *pu8DevicePermissions);
Description
This function can be used by the Trust Centre to obtain its own permissions for certain requests from a particular node. The possible settings are:
Allow all requests from the specified node.
Do not allow join requests from the specified node.
Do not allow data requests from the specified node.
Parent topic:ZPS_bAplZdoTrustCenterGetDevicePermissions
Parameters
u64DeviceAddr: 64-bit IEEE/MAC address of node for which permissions are to be obtained.
pu8DevicePermissions: Pointer to bitmap containing permissions obtained, where:
0 indicates all requests allowed.
1 indicates join requests disallowed.
2 indicates data requests disallowed.
3 indicates data and join requests disallowed.
Higher bits are reserved for future use
Parent topic:ZPS_bAplZdoTrustCenterGetDevicePermissions
Returns
ZPS_E_SUCCESS (permissions successfully obtained)
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_bAplZdoTrustCenterGetDevicePermissions
Parent topic:Security functions
ZPS_bAplZdoTrustCenterRemoveDevice
ZPS_teStatus ZPS_bAplZdoTrustCenterRemoveDevice(
uint64 u64DeviceAddr);
Description
This function can be used by the Trust Centre to delete a node in its information base.
Parent topic:ZPS_bAplZdoTrustCenterRemoveDevice
Parameters
u64DeviceAddr : It is the 64-bit IEEE/MAC address of the node to be removed from the list.
Parent topic:ZPS_bAplZdoTrustCenterRemoveDevice
Returns
ZPS_E_SUCCESS (node successfully removed from list)
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_bAplZdoTrustCenterRemoveDevice
Parent topic:Security functions
ZPS_vTcInitFlash
void ZPS_vTcInitFlash(
ZPS_tsAfFlashInfoSet *psFlashInfoSet,
ZPS_TclkDescriptorEntry *psTclkStruct);
Description
This function can be used on the network Coordinator/Trust Centre to enable the persistent storage of the Trust Centre Link Keys (TCLKs) for all nodes in the network.
Each of these keys is a unique application-level link key for a node. The key is used to encrypt/decrypt communications between Trust Centre and the node during the commissioning of the node into the network (and is issued by the Trust Centre to replace the pre-configured unique link key).
The function allows these link keys to be stored in devices Flash memory.
Information about the Flash memory sector to be used to store the link keys is specified in a
ZPS_tsAfFlashInfoSetstructure.Information about an individual link key is stored in RAM in a read-only
ZPS_TclkDescriptorEntrystructure, which is for internal use by the stack. An array of these structures must be allocated in RAM, with one element for each node in the network - for example, if there are up to 250 nodes in the network, the required allocation would be:
ZPS_TclkDescriptorEntry sData[250];
The application can determine at any time whether this feature is enabled by reading the Boolean variable bSetTclkFlashFeature, which reads as TRUE if the feature is enabled and as FALSE if it is disabled.
When a new Trust Centre Link Key has been negotiated for a node, the stack on the Trust Centre notifies the application by means of a ZPS_EVENT_TC_STATUS event. The application can discover the IEEE/MAC address of the corresponding node by calling ZPS_u64GetFlashMappedIeeeAddress() with the value of u16ExtAddrLkupfrom the key descriptor passed in the event.
Please note that when the key table is held in RAM, ZPS_u64NwkNibGetMappedIeeeAddr() would be called instead.
Parent topic:ZPS_vTcInitFlash
Parameters
psFlashInfoSet Pointer to a structure containing information about the Flash memory sector to be used to store the link keys for the network nodes (see Section 8.2.3.8)
psTclkStruct Pointer to a structure in RAM that is used to hold information about the storage of one link key in Flash memory (see Section 8.2.3.9)
Parent topic:ZPS_vTcInitFlash
Returns
None
Parent topic:ZPS_vTcInitFlash
Parent topic:Security functions
ZPS_vSetTCLockDownOverride
void ZPS_vSetTCLockDownOverride(
void* pvApl,
bool_t u8RemoteOverride,
bool_t bDisableAuthentications);
Description
This function can be called on the network Coordinator to disable Trust Centre functionality on the device.
The function provides two configuration options:
Allows remote devices to over-ride the Trust Centre policy.
Disables authentication of network joins (any transport key is also disabled).
Parent topic:ZPS_vSetTCLockDownOverride
Parameters
pvApl: Handle for the relevant Application layer instance.
u8RemoteOverride: Boolean specifying whether remote overrides of Trust Centre policy are to be permitted:
TRUE - Does not allow remote over-rides; stack does not allow the permit join remotely sent to change its local state.
FALSE - Allows remote over-rides; stack accepts permit join requests coming in and obeys them.
bDisableAuthentications: Boolean specifying whether network join authentications are to be disabled:
TRUE - Disable authentications
FALSE - Do not disable authentications
When this flag is set to TRUE, permit join is not accepted remotely and the TC does not transport a key to any joiner.
Parent topic:ZPS_vSetTCLockDownOverride
Returns
None
Parent topic:ZPS_vSetTCLockDownOverride
Parent topic:Security functions
ZPS_psGetActiveKey
ZPS_tsAplApsKeyDescriptorEntry *ZPS_psGetActiveKey(
uint64 u64IeeeAddress,
uint32* pu32Index);
Description
This function can be used on the Trust Centre to obtain the Pre-configured Unique Link Key for the node with the specified IEEE/MAC address. The function searches the local Key Descriptor Table for an entry corresponding to the specified address. If it finds a relevant entry, it returns the entry as well as the index number of the entry in the table. The required key is in the returned table entry.
Parent topic:ZPS_psGetActiveKey
Parameters
u64IeeeAddress: IEEE/MAC address of the node of interest
pu32Index: Pointer to a location to receive the index number of the relevant Key Descriptor Table entry
Parent topic:ZPS_psGetActiveKey
Returns
Pointer to requested Key Descriptor Table entry (for structure, see Section 8.2.3.6).
Parent topic:ZPS_psGetActiveKey
Parent topic:Security functions
ZPS_vTCSetCallback
void ZPS_vTCSetCallback(void *pCallbackFn);
Description
This function can be used to register a user-defined callback function on the Trust Centre, where this callback function allows the application to react to a notification from another network node - for example, to decide whether to permit a node to join that may or may not be known to the Trust Centre application.
The prototype of the user-defined callback function is:
bool bTransportKeyDecider (uint16 u16ShortAddress,
uint64 u64DeviceAddress,
uint64 u64ParentAddress,
uint8 u8Status,
uint16 u16Interface);
where:
u16ShortAddr is the network address of the relevant node.
u64DeviceAddress is the IEEE/MAC address of the relevant node.
u64ParentAddress is the IEEE/MAC address of the parent that sent the notification.
u8Status is the nature of the notification:
0: Secure rejoin
1: Unsecure join (association)
2: Leave
3: Unsecure rejoin
4: Leave with a rejoin
u16Interface is the MAC interface this join has happened on. If it is 2.4 G only the value is always 0. If it is a MultiMAC device 2.4 G interface, it will return value 0 and sub Gig will return value 1.
To disallow the notified action (for example, a join), the callback function should return FALSE.
If the callback function is not registered or returns TRUE, the Trust Centre will allow the notified action. In the case of a join, the Trust Centre will send the network key in a ‘transport key’ command to the node, either:
encrypted with the node’s pre-configured link key, if this key is known to the Trust Centre, or
encrypted with the Trust Centre’s default pre-configured link key otherwise (in this case, the joining node will only be able to decrypt the ‘transport key’ command and complete the join if it also has the Trust Centre’s default pre-configured link key)
Registration of this callback function may be useful in controlling rejoins. A node can initially join a network using its pre-configured link key (which is also known by the Trust Centre), but this key may subsequently be replaced on the Trust Centre by an application link key (shared only by the node and the Trust Centre). If the node later leaves the network and loses its context data (including the application link key), it may attempt to rejoin the network using its pre-configured link key again. The callback function can allow the application to decide whether to permit such a rejoin. If the rejoin is to be allowed, the callback function must replace the stored application link key with the pre-configured link key on the Trust Centre before returning TRUE.
Parent topic:ZPS_vTCSetCallback
Parameters
pCallbackFn Pointer to user-defined callback function.
Parent topic:ZPS_vTCSetCallback
Returns
None
Parent topic:ZPS_vTCSetCallback
Parent topic:Security functions
Parent topic:ZDO API functions
Addressing functions
The ZDO Addressing functions allow node addresses to be stored and obtained. They include the group address functions that allow a group of nodes/endpoints, with an assigned group address, to be created and modified (this group can be used as the destinations for a multicast message).
The functions are listed below.
Function page
Note: Further addressing functions are provided in the ZDP API and are described in Section 9.1.1, “Address Discovery functions”.
Parent topic:Addressing functions
ZPS_u16AplZdoGetNwkAddr
uint16 ZPS_u16AplZdoGetNwkAddr(void);
Description
This function obtains the 16-bit network address of the local node.
Parameters
None
Parent topic:ZPS_u16AplZdoGetNwkAddr
Returns
16-bit network address obtained.
Parent topic:ZPS_u16AplZdoGetNwkAddr
Parent topic:Addressing functions
ZPS_u64AplZdoGetIeeeAddr
uint64 ZPS_u64AplZdoGetIeeeAddr(void);
Description
This function obtains the 64-bit IEEE (MAC) address of the local node.
Parent topic:ZPS_u64AplZdoGetIeeeAddr
Parameters
None
Parent topic:ZPS_u64AplZdoGetIeeeAddr
Returns
64-bit IEEE/MAC address obtained
Parent topic:ZPS_u64AplZdoGetIeeeAddr
Parent topic:Addressing functions
ZPS_eAplZdoAddAddrMapEntry
ZPS_teStatus ZPS_eAplZdoAddAddrMapEntry(
uint16 u16NwkAddr,
uint64 u64ExtAddr);
Description
This function can be used to add the addresses of a remote node to the local Address Map table. Each entry in this table stores a remote node’s 16-bit network address and an index to its 64-bit IEEE (MAC) address in the MAC Address table (see Section3.2.4). Thus, the function adds the IEEE address to the MAC Address table and then the index of this entry to the Address Map table.
Note: You should only modify the Address Map table using the supplied API functions and never write to it directly.
Parent topic:ZPS_eAplZdoAddAddrMapEntry
Parameters
u16NwkAddr: 16-bit network address of node to be added
u64ExtAddr: 64-bit IEEE/MAC address of node to be added
Parent topic:ZPS_eAplZdoAddAddrMapEntry
Returns
ZPS_E_SUCCESS (addresses successfully added to tables)
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_eAplZdoAddAddrMapEntry
Parent topic:Addressing functions
ZPS_vPurgeAddressMap
void ZPS_vPurgeAddressMap(void);
Description
This function removes all entries from the Address Map table on the local node.
Note: You should modify the Address Map table only using the supplied API functions and never write to it directly.
Parent topic:ZPS_vPurgeAddressMap
Parameters
None.
Parent topic:ZPS_vPurgeAddressMap
Returns
None.
Parent topic:ZPS_vPurgeAddressMap
Parent topic:Addressing functions
ZPS_u16AplZdoLookupAddr
uint16 ZPS_u16AplZdoLookupAddr(uint64 u64ExtAddr);
Description
This function can be used to search the local Address Map table for the 16-bit network address of the node with a given 64-bit IEEE (MAC) address.
Parent topic:ZPS_u16AplZdoLookupAddr
Parameters
u64ExtAddr 64-bit IEEE/MAC address of node to be searched for.
Parent topic:ZPS_u16AplZdoLookupAddr
Returns
16-bit network address obtained.
Parent topic:ZPS_u16AplZdoLookupAddr
Parent topic:Addressing functions
ZPS_u64AplZdoLookupIeeeAddr
uint64 ZPS_u64AplZdoLookupIeeeAddr(
uint16 u16NwkAddr);
Description
This function can be used to search the local Address Map table for the 64-bit IEEE (MAC) address of the node with a given 16-bit network address.
Parent topic:ZPS_u64AplZdoLookupIeeeAddr
Parameters
u16NwkAddr 16-bit network address of node to be searched for.
Parent topic:ZPS_u64AplZdoLookupIeeeAddr
Returns
64-bit IEEE/MAC address obtained.
Parent topic:ZPS_u64AplZdoLookupIeeeAddr
Parent topic:Addressing functions
ZPS_u64NwkNibGetMappedIeeeAddr
uint64 ZPS_u64NwkNibGetMappedIeeeAddr(
void *pvNwk,
uint16 u16Location);
Description
This function can be used to obtain the 64-bit IEEE (MAC) address that is stored in a particular entry in the local MAC Address table. The number of the entry must be specified as well as the handle of the relevant network.
Parent topic:ZPS_u64NwkNibGetMappedIeeeAddr
Parameters
pvNwk: Pointer to relevant NWK layer instance
u16Location: Number of entry to access in MAC Address table
Parent topic:ZPS_u64NwkNibGetMappedIeeeAddr
Returns
64-bit IEEE/MAC address obtained.
Parent topic:ZPS_u64NwkNibGetMappedIeeeAddr
Parent topic:Addressing functions
ZPS_u64GetFlashMappedIeeeAddress
uint64 ZPS_u64GetFlashMappedIeeeAddress(
uint16 u16Location);
Description
This function can be used on the Trust Centre to obtain the 64-bit IEEE (MAC) address of the node for which a link key has been persistently stored in the specified location in devices Flash memory. The location is specified as the number of the array element for the node - see the description of ZPS_vTcInitFlash.
Parent topic:ZPS_u64GetFlashMappedIeeeAddress
Parameters
u16Location: Number of the array element for the node
Parent topic:ZPS_u64GetFlashMappedIeeeAddress
Returns
64-bit IEEE/MAC address obtained.
Parent topic:ZPS_u64GetFlashMappedIeeeAddress
Parent topic:Addressing functions
ZPS_bNwkFindAddIeeeAddr
bool_t ZPS_bNwkFindAddIeeeAddr(
void *pvNwk,
uint64 u64IeeeAddr,
uint16 *pu16Location,
bool_t bNeighborTable);
Description
This function can be used to add the 64-bit IEEE (MAC) address of a node to the local MAC Address table. The function first searches the table to determine whether the address already exists in the table. If there is no entry for this address, a new entry for it is added to the table. The number of the entry where the address was found or added is returned in a specified location.
Note: You should modify the MAC Address table only using the supplied API functions and never write to it directly.
Parent topic:ZPS_bNwkFindAddIeeeAddr
Parameters
pvNwk: Pointer to relevant NWK layer instance
u64IeeeAddr: 64-bit IEEE/MAC address to be added
pu16Location: Pointer to location to receive number of entry in MAC Address table where specified address was found or added
bNeighborTable: Always set to FALSE
Parent topic:ZPS_bNwkFindAddIeeeAddr
Returns
Boolean indicating the outcome of the operation:
TRUE - address successfully added to the table
FALSE - address found to already exist in the table
Parent topic:ZPS_bNwkFindAddIeeeAddr
Parent topic:Addressing functions
ZPS_vSetOverrideLocalIeeeAddr
void ZPS_vSetOverrideLocalIeeeAddr(
uint64 *pu64Address);
Description
This function can be used to over-ride the 64-bit IEEE (MAC) address of the device where this address is stored locally in the index sector of Flash memory.
Note: If required, this function must be called before the ZigBee PRO stack is initialized.
Parent topic:ZPS_vSetOverrideLocalIeeeAddr
Parameters
pu64Address Pointer to the 64-bit IEEE MAC address
Note: The stack stores a pointer to pu64Addressand does not take a copy of the address. The memory pointed to by pu64Address must therefore be static or constant, and must not be on the CPU stack.
Parent topic:ZPS_vSetOverrideLocalIeeeAddr
Parent topic:Addressing functions
ZPS_eAplZdoGroupEndpointAdd
ZPS_teStatus ZPS_eAplZdoGroupEndpointAdd(
uint16 u16GroupAddr,
uint8 u8DstEndpoint);
Description
This function requests that the specified endpoint (on the local node) is added to the group with the specified group address. This means that this endpoint will become one of the destinations for messages sent to the given group address.
To form a group comprising endpoints from different nodes, it is necessary to call this function for each endpoint individually, on the endpoint’s local node.
An endpoint can belong to more than one group.
Information on the endpoints in a group can be obtained from the Group Address table in the AIB (which can be accessed using the function ZPS_psAplAibGetAib()).
Note: In order to add an endpoint to a group using this function, a Group Address table must exist on the local node. This table is created using the ZPS Configuration Editor.
Parent topic:ZPS_eAplZdoGroupEndpointAdd
Parameters
u16GroupAddr: 16-bit group address
u8DstEndpoint: Number of destination endpoint (1-240) on local node
Parent topic:ZPS_eAplZdoGroupEndpointAdd
Returns
ZPS_E_SUCCESS (endpoint successfully added to group)
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_eAplZdoGroupEndpointAdd
Parent topic:Addressing functions
ZPS_eAplZdoGroupEndpointRemove
ZPS_teStatus ZPS_eAplZdoGroupEndpointRemove(
uint16 u16GroupAddr,
uint8 u8DstEndpoint);
Description
This function requests that the specified endpoint (on the local node) is removed from the group with the specified group address.
If you wish to remove an endpoint from all groups to which it belongs, use the functionZPS_eAplZdoGroupAllEndpointRemove().
Information on the endpoints in a group can be obtained from the Group Address table in the AIB (which can be accessed using the function ZPS_psAplAibGetAib()).
Parent topic:ZPS_eAplZdoGroupEndpointRemove
Parameters
u16GroupAddr: 16-bit group address
u8DstEndpoint: Number of destination endpoint (1-240) on local node
Parent topic:ZPS_eAplZdoGroupEndpointRemove
Returns
ZPS_E_SUCCESS (endpoint successfully removed from group)
APS return codes, listed and described in Section 111.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_eAplZdoGroupEndpointRemove
Parent topic:Addressing functions
ZPS_eAplZdoGroupAllEndpointRemove
ZPS_teStatus ZPS_eAplZdoGroupAllEndpointRemove(
uint8 u8DstEndpoint);
Description
This function requests that the specified endpoint (on the local node) is removed from all groups to which it currently belongs.
Information on the endpoints in a group can be obtained from the Group Address table in the AIB (which can be accessed using the function ZPS_psAplAibGetAib()).
Parent topic:ZPS_eAplZdoGroupAllEndpointRemove
Parameters
u8DstEndpoint Number of destination endpoint (1-240) on local node
Parent topic:ZPS_eAplZdoGroupAllEndpointRemove
Returns
ZPS_E_SUCCESS (endpoint successfully removed from all groups)
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_eAplZdoGroupAllEndpointRemove
Parent topic:Addressing functions
Parent topic:ZDO API functions
Routing functions
The ZDO Routing functions can be used to make route discovery requests. The functions are listed below.
Function page
Parent topic:Routing functions
ZPS_eAplZdoRouteRequest
ZPS_teStatus ZPS_eAplZdoRouteRequest(
uint16 u16DstAddr,
uint8 u8Radius);
Description
This function requests the discovery of a route to the specified remote node (and that this route is added to the Routing tables in the relevant Router nodes).
Parent topic:ZPS_eAplZdoRouteRequest
Parameters
u16DstAddr 16-bit network address of destination node
u8Radius Maximum number of hops permitted to destination node (zero value specifies that default maximum is to be used)
Parent topic:ZPS_eAplZdoRouteRequest
Returns
ZPS_E_SUCCESS (route discovery request successfully initiated)
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_eAplZdoRouteRequest
Parent topic:Routing functions
ZPS_eAplZdoManyToOneRouteRequest
ZPS_teStatus ZPS_eAplZdoManyToOneRouteRequest(
bool bCacheRoute,
uint8 u8Radius);
Description
This function requests a ‘many-to-one’ route discovery and should be called on a node that will act as a ‘concentrator’ in the network (that is, a node with which many other nodes will need to communicate).
As a result of this function call, a route discovery message is broadcast across the network and Routing table entries (for routes back to the concentrator) are stored in the Router nodes.
The maximum number of hops to be taken by a route discovery message in this broadcast must be specified. There is also an option to store the discovered routes in a Route Record Table on the concentrator (for return communications).
Parent topic:ZPS_eAplZdoManyToOneRouteRequest
Parameters
bCacheRoute: Indicates whether to store routes in Route Record Table:
TRUE - store routes
FALSE - do not store routes
u8Radius: Maximum number of hops of route discovery message (zero value specifies that default maximum is to be used)
Parent topic:ZPS_eAplZdoManyToOneRouteRequest
Returns
ZPS_E_SUCCESS (many-to-one route discovery successfully initiated)
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_eAplZdoManyToOneRouteRequest
Parent topic:Routing functions
Parent topic:ZDO API functions
Object Handle functions
The ZDO Object Handle functions can be used to obtain the handles of various objects. The functions are listed below:
Function page
Parent topic:Object Handle functions
ZPS_pvAplZdoGetAplHandle
void *ZPS_pvAplZdoGetAplHandle(void);
Description
This function obtains a handle for the Application layer instance.
Parameters
None
Parent topic:ZPS_pvAplZdoGetAplHandle
Returns
Pointer to Application layer instance
Parent topic:ZPS_pvAplZdoGetAplHandle
Parent topic:Object Handle functions
ZPS_pvAplZdoGetMacHandle
void *ZPS_pvAplZdoGetMacHandle(void);
Description
This function obtains a handle for the IEEE 802.15.4 MAC layer instance.
Parent topic:ZPS_pvAplZdoGetMacHandle
Parameters
None
Parent topic:ZPS_pvAplZdoGetMacHandle
Returns
Pointer to MAC layer instance
Parent topic:ZPS_pvAplZdoGetMacHandle
Parent topic:Object Handle functions
ZPS_pvAplZdoGetNwkHandle
void *ZPS_pvAplZdoGetNwkHandle(void);
Description
This function obtains a handle for the ZigBee NWK layer instance.
Parent topic:ZPS_pvAplZdoGetNwkHandle
Parameters
None
Parent topic:ZPS_pvAplZdoGetNwkHandle
Returns
Pointer to NWK layer instance
Parent topic:ZPS_pvAplZdoGetNwkHandle
Parent topic:Object Handle functions
ZPS_psNwkNibGetHandle
ZPS_tsNwkNib *ZPS_psNwkNibGetHandle(void *pvNwk);
Description
This function obtains a handle for the NIB (Network Information Base) corresponding to the specified NWK layer instance.
The function should be called after ZPS_pvAplZdoGetNwkHandle(), which is used to obtain a pointer to the NWK layer instance.
The NIB is detailed in the ZigBee Specification (05347) from the ZigBee Alliance. This function is not strictly a ZDO function.
Parent topic:ZPS_psNwkNibGetHandle
Parameters
pvNwk Pointer to NWK layer instance
Parent topic:ZPS_psNwkNibGetHandle
Returns
Pointer to NIB structure
Parent topic:ZPS_psNwkNibGetHandle
Example
void *pvNwk; = ZPS_pvAplZdoGetNwkHandle();
ZPS_tsNwkNib *pNib = ZPS_psNwkNibGetHandle(pvNwk);
Parent topic:ZPS_psNwkNibGetHandle
Parent topic:Object Handle functions
ZPS_psAplAibGetAib
ZPS_tsAplAib *ZPS_psAplAibGetAib(void);
Description
This function obtains a pointer to the AIB (Application Information Base) structure for the application.
Parent topic:ZPS_psAplAibGetAib
Parameters
None
Parent topic:ZPS_psAplAibGetAib
Returns
Pointer to AIB structure
Parent topic:ZPS_psAplAibGetAib
Parent topic:Object Handle functions
ZPS_psAplZdoGetNib
ZPS_tsNwkNib *ZPS_psAplZdoGetNib(void);
Description
This function obtains a pointer to the NIB (Network Information Base) structure. The NIB is detailed in the ZigBee Specification (05347) from the ZigBee Alliance.
Parent topic:ZPS_psAplZdoGetNib
Parameters
None
Parent topic:ZPS_psAplZdoGetNib
Returns
Pointer to NIB structure
Parent topic:ZPS_psAplZdoGetNib
Parent topic:Object Handle functions
ZPS_u64NwkNibGetEpid
uint64 ZPS_u64NwkNibGetEpid(void *pvNwk);
Description
This function can be used to obtain the Extended PAN ID (EPID) from a local NIB (Network Information Base).
The handle of the NWK layer instance that contains the relevant NIB must be specified. This handle can be obtained using ZPS_pvAplZdoGetNwkHandle().
Parent topic:ZPS_u64NwkNibGetEpid
Parameters
pNibHandle Pointer to NWK layer instance that contains the NIB
Parent topic:ZPS_u64NwkNibGetEpid
Returns
64-bit Extended PAN ID from NIB
Parent topic:ZPS_u64NwkNibGetEpid
Parent topic:Object Handle functions
Parent topic:ZDO API functions
Optional Cluster function
The ZDO Optional Cluster function can be used to register a user-defined callback function to handle messages for a ZDO cluster that is not currently supported by the NXP ZigBee PRO stack.
The function is listed below on the function page.
Function page
ZPS_eAplZdoRegisterZdoFilterCallback
Parent topic:Optional Cluster function
ZPS_eAplZdoRegisterZdoFilterCallback
ZPS_teStatus ZPS_eAplZdoRegisterZdoFilterCallback(
void *fnptr);
Description
This function can be used to register a user-defined callback function which handles messages received for an unsupported cluster which resides on the ZDO endpoint (0), such as the cluster for an optional descriptor (for example, a user descriptor).
The prototype of the user-defined callback function is: bool fn(uint16 clusterid );
where clusteridis the ID of the cluster that the function handles.
Normally, a message arriving for an unsupported ZDO cluster is not handled and the stack automatically returns an ‘unsupported’ message to the originating node. If this function is used to register a callback function for an unsupported ZDO cluster then on receiving a message for the cluster, the stack will invoke the callback function. The stack will not respond with an ‘unsupported message’ provided that the callback function returns TRUE, otherwise the normal stack behavior will continue.
The callback function allows the received message to be passed to the application for servicing.
Parent topic:ZPS_eAplZdoRegisterZdoFilterCallback
Parameters
fnptr: Pointer to user-defined callback function
Parent topic:ZPS_eAplZdoRegisterZdoFilterCallback
Returns
ZPS_E_SUCCESS (callback function successfully registered)
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_eAplZdoRegisterZdoFilterCallback
Parent topic:Optional Cluster function
Parent topic:ZDO API functions
Parent topic:ZigBee Device Objects (ZDO) API
ZDO enumerations
This section details the enumerated types used by the ZDO functions. These are all defined in the header file zps_apl_zdo.h.
Security keys (ZPS_teZdoNwkKeyState)
This structure ZPS_teZdoNwkKeyStatecontains the enumerations used to specify a type of security key:
typedef enum
{
ZPS_ZDO_NO_NETWORK_KEY,
ZPS_ZDO_PRECONFIGURED_LINK_KEY,
ZPS_ZDO_DISTRIBUTED_LINK_KEY,
ZPS_ZDO_PRCONFIGURED_INSTALLATION_CODE
} PACK ZPS_teZdoNwkKeyState
These enumerations are described in the table below:
Security Key Enumerations
Enumeration |
Description |
|---|---|
ZPS_ZDO_NO_NETWORK_KEY |
No network key should be used. |
ZPS_ZDO_PRECONFIGURED_LINK_KEY |
A pre-configured link key should be used. This key can be fixed at the time of manufacture. |
ZPS_ZDO_DISTRIBUTED_LINK_KEY |
A pre-configured ZigBee Light Link (ZLL) link key should be used. This key can be fixed at the time of manufacture. A ZLL node contains both a ZPS_ZDO_PRECONFIG- URED_LINK_KEY for Home Automation (HA) compatibility and a ZPS_ZDO_ZLL_LINK_KEY for ZLL networks. |
ZPS_ZDO_PRCONFIGURED_INSTALLATION_CODE |
A preconfigured install code is to be used. This results in a key being generated from the install code. |
Parent topic:ZDO enumerations
Device types (ZPS_teZdoDeviceType)
This structure ZPS_teZdoDeviceTypecontains the enumerations used to specify a ZigBee device type
typedef enum
{
ZPS_ZDO_DEVICE_COORD,
ZPS_ZDO_DEVICE_ROUTER,
ZPS_ZDO_DEVICE_ENDDEVICE
} PACK ZPS_teZdoDeviceType;
These enumerations are described in the table below.
Device Type Enumerations
Enumeration |
Description |
|---|---|
ZPS_ZDO_DEVICE_COORD |
Coordinator |
ZPS_ZDO_DEVICE_ROUTER |
Router |
ZPS_ZDO_DEVICE_ENDDEVICE |
End Device |
Parent topic:ZDO enumerations
Device permissions (ZPS_teDevicePermissions)
This structure ZPS_teDevicePermissions contains the enumerations used on a device to specify the permissions for certain requests from other nodes:
typedef enum
{
ZPS_DEVICE_PERMISSIONS_ALL_PERMITED = 0,
ZPS_DEVICE_PERMISSIONS_JOIN_DISALLOWED = 1,
ZPS_DEVICE_PERMISSIONS_DATA_REQUEST_DISALLOWED = 2,
ZPS_DEVICE_PERMISSIONS_REJOIN_DISALLOWED = 4,
} PACK ZPS_teDevicePermissions;
These enumerations are described in the table below:
Device permissions
Enumeration |
Description |
|---|---|
ZPS_DEVICE_PERMISSIONS_ALL_PERMITED |
Allow all requests from other nodes |
ZPS_DEVICE_PERMISSIONS_JOIN_DISALLOWED |
Do not allow join requests from other nodes |
ZPS_DEVICE_PERMISSIONS_DATA_REQUEST_DISALLOWED |
Do not allow data requests from other nodes and disable end-to-end acknowledgments |
ZPS_DEVICE_PERMISSIONS_REJOIN_DISALLOWED |
Do not allow insecure rejoin. |
Parent topic:ZDO enumerations
Parent topic:ZigBee Device Objects (ZDO) API