Zigbee stack API overview

1. Scope

This wiki describes the implementation of the Exegin ZSDK (Zigbee software design kit) API (application programming interface) for Zigbee on the STM32WBA Series based on V1.5 STM32Cube Firmware release supporting R23_FFD . It describes all APIs used to control the stack. In particular, it covers APIs used to access to the following layers: BDB (base device behavior), APS (applications services), NWK (network layer services) and ZDO (Zigbee device object).

2. Zigbee stack handle

The stack is initialized by calling the function ZbInit(), which returns a stack instance handle of type ZigBeeT *. To the application this is an anonymous pointer, the contents of which are private to the stack. The application should only interact with ZigBeeT * to provide it back to the stack when calling most stack API functions. For this reason, stack API functions follow this format:

ZbFunc(struct ZigBeeT *zb, ...)

3. Status codes

Many functions in the Zigbee stack return a status code as an enumeration. The general status codes are the most common, and are included below as an example of their format.

3.1. General status codes

Value	Status Code
0x00	ZB_STATUS_SUCCESS
0x70	ZB_STATUS_ALLOC_FAIL
0x71	ZB_STATUS_TIMEOUT

3.2. ZDP status codes

Status Value	Status Code
0x00	ZB_ZDP_STATUS_SUCCESS
0x80	ZB_ZDP_STATUS_INV_REQTYPE
0x81	ZB_ZDP_STATUS_DEVNOTFOUND
0x82	ZB_ZDP_STATUS_INVALID_EP
0x83	ZB_ZDP_STATUS_NOT_ACTIVE
0x84	ZB_ZDP_STATUS_NOT_SUPPORTED
0x85	ZB_ZDP_STATUS_TIMEOUT
0x86	ZB_ZDP_STATUS_NO_MATCH
0x88	ZB_ZDP_STATUS_NO_ENTRY
0x89	ZB_ZDP_STATUS_NO_DESCRIPTOR
0x8a	ZB_ZDP_STATUS_INSUFFICIENT_SPACE
0x8b	ZB_ZDP_STATUS_NOT_PERMITTED
0x8c	ZB_ZDP_STATUS_TABLE_FULL
0x8d	ZB_ZDP_STATUS_NOT_AUTHORIZED
0x8e	ZB_ZDP_STATUS_DEVICE_BINDING_TABLE_FULL
0x8f	ZB_ZDP_STATUS_INVALID_INDEX

3.3. APS status codes

Status Value	Status Code
0x00	ZB_APS_STATUS_SUCCESS
0xa0	ZB_APS_STATUS_ASDU_TOO_LONG
0xa1	ZB_APS_STATUS_DEFRAG_DEFERRED
0xa2	ZB_APS_STATUS_DEFRAG_UNSUPPORTED
0xa3	ZB_APS_STATUS_ILLEGAL_REQUEST
0xa4	ZB_APS_STATUS_INVALID_BINDING
0xa5	ZB_APS_STATUS_INVALID_GROUP
0xa6	ZB_APS_STATUS_INVALID_PARAMETER
0xa7	ZB_APS_STATUS_NO_ACK
0xa8	ZB_APS_STATUS_NO_BOUND_DEVICE
0xa9	ZB_APS_STATUS_NO_SHORT_ADDRESS
0xaa	ZB_APS_STATUS_NOT_SUPPORTED
0xab	ZB_APS_STATUS_SECURED_LINK_KEY
0xac	ZB_APS_STATUS_SECURED_NWK_KEY
0xad	ZB_APS_STATUS_SECURITY_FAIL
0xae	ZB_APS_STATUS_TABLE_FULL
0xaf	ZB_APS_STATUS_UNSECURED
0xb0	ZB_APS_STATUS_UNSUPPORTED_ATTRIBUTE

4. Timers

Timers are fundamental to the operation of the stack. The stack uses many different timers internally, and timer operation impacts events such as timeout. Some APIs have been exposed so applications may use the timer.

4.1. ZbTimerAlloc()

A timer is created by calling ZbTimerAlloc() along with a callback function (app_timer_callback). This callback will be invoked when the timer expires.

ZbTimerAlloc() Example

struct ZbTimerT *timer;
timer = ZbTimerAlloc(zb, app_timer_callback, NULL);

4.2. ZbTimerReset()

Once created, the timer must be reset to become active. The following example will reset and start the timer with a delay of 1000 ms or 1 sec, and includes the necessary application callback function.

ZbTimerReset() Prototype

ZbTimerReset(timer, 1000);
static void
app_timer callback(struct ZigBeeT *zb, void *arg)

4.3. ZbTimerStop()

Stop a timer before it expires.

ZbTimerStop() Prototype

ZbTimerStop(timer);

4.4. ZbTimerRemaining()

Returns the time remaining in milliseconds before the timer expires.

ZbTimerRemaining() Prototype

ZbTimerRemaining(timer);

Will return UINT_MAX if the timer is not running.

4.5. ZbTimerFree()

Frees a timer.

ZbTimerFree() Prototype

ZbTimerFree(timer);

4.6. ZbTimerChangeCallback()

Changes the callback function for the specified timer, without the need to free and allocate a new timer.

ZbTimerChangeCallback() Prototype

void ZbTimerChangeCallback(struct ZbTimerT *timer, void (*callback)(struct ZigBeeT
*zb, void *cb_arg), void *arg);

Parameters

• timer – Zigbee timer structure
• zb – Zigbee stack structure
• arg – callback argument

4.7. ZbTimerRunning()

Returns true if the given timer is active.

ZbTimerRunning() Prototype

bool ZbTimerRunning(struct ZbTimerT *timer);

Parameters

• timer – Zigbee timer structure

4.8. ZbUptime()

Retrieves the current uptime in milliseconds. This is typically only used internally by the stack for the timers.

ZbUptime() Prototype

ZbUptimeT ZbUptime(void);

Returns the current uptime in milliseconds. Note that this function will never return 0. Values are from 1 to ZB_UPTIME_MAX.

4.9. ZbTimeoutRemaining()

Used with ZbUptime. This function returns the time difference between expire_time and now, or 0 if the time has expired (now >= expire_time). This function handles the case where the time value has rolled over starting back from 0.

ZbTimeoutRemaining() Prototype

unsigned int ZbTimeoutRemaining(ZbUptimeT now, ZbUptimeT expire_time);

Parameters

• now – current time
• expire_time – The time when the timer was set to expire

5. Packet and message filters

Packet and message filters are primarily used internally by the stack. Typical applications will not need to use packet and message filters. Message filters are so central to stack operation that they afford a mechanism for applications to extend stack functionality. As messages traverse the stack, through the MAC, NWK, APS, ZDO or ZCL layers, filters are used to direct messages to the appropriate destination. A filter is defined with certain criteria. When a message is processed, the filters are checked and matching messages are directed to the requesting filter.

6. MAC initialization

The stack can operate on many different real and virtual MAC interfaces. Physical devices can be connected by SPI, UART, or USB. The MAC and stack can be coresident, or operate on separate MCUs. When on a separate MCU, Exegin SIO, MCP (MAC Control Protocol) or a proprietary protocol may be used.

Device options and configuration are highly variably. The specific API is device-dependent. However. The ultimate goal is for a WpanPublicT *device pointer to be created and passed to the stack, which has no knowledge of the device used.

6.1. Bare Metal device initialization

The device accesses the radio through the use of memory-mapped registers. On powerup, the radio hardware must be initialized. In this case, the PHY is local so that hardware specific PHY device is created, and a MAC instance created which uses this PHY interface.

Bare Metal device initialization example

#include "phy.h"
#include "wpan_mac_init.h"
WpanPublicT *device;
struct phyif phy;
uint64_t ext_addr;
/* initialize radio */
radio_init(&phy);
ext_addr = radio_get_ext_addr(); /* obtain from device */
/* optional callbacks not used for simplicity */
device = WpanMacInit(&phy, ext_addr, NULL, NULL);

7. Network management

ZbStartup executes the standard startup procedure. The startup function handles callbacks from the stack to maintain the network and security processes. For example, these include the handling of APSME-UPDATEDEVICE.indication messages when acting as a coordinator trust center, to handle the authentication procedure described in section 4.6.3.2 of the Zigbee specification document.

The message callback handlers can be overridden by the application by creating message filters using ZbMsgFilterRegister. This function and the entire startup code can be bypassed by the application, and the network layer APIs used directly, if so desired. If security is enabled (nwkSecurityLevel != 0), this function overloads the APSME callback functions and performs the authentication procedure.

This is purely a helper function, and if finer-grained control of startup and authentication is necessary then the application can perform these tasks manually.

8. Stack configuration

Most stack configuration parameters are controlled by the ZbStartupT structure passed to ZbStartup1.

ZbStartupT Structure

struct ZbStartupT config;

There are many configuration settings. Most applications want to first initialize the configuration with the default ZigBee PRO settings, or the default smart energy application settings:

Zigbee Pro startup default configuration

ZbStartupConfigGetProDefaults(&config);

Zigbee Smart Energy startup default configuration

ZbStartupConfigGetProSeDefaults(&config);

These functions do not set the channel list, which must be set manually by the application.

The following shows how to set the available channels (channel mask) to 11 and 15 on channel page 0 (2.4 GHz):

Setting the channel list

config.channelList.list[0].page = 0;
config.channelList.list[0].channelMask = (uint32_t)((1ul << 11) | (1ul << 15));
config.channelList.count = 1;

Each page must have its own mask. The list can contain a total of MAX_CHANNEL_LIST_ENTRIES.

A common configuration is the commissioning mode.

Commissioning mode configuration

config.bdbCommissioningMode |= BDB_COMMISSION_MODE_FIND_BIND;

The Touchlink commissioning mode is used frequently.

Touchlink commissioning mode configuration

config.bdbCommissioningMode |= BDB_COMMISSION_MODE_TOUCHLINK;
config.touchlink.flags = 0;
config.touchlink.zb_info = ZCL_TL_ZBINFO_TYPE_ROUTER;
config.touchlink.zb_info |= ZCL_TL_ZBINFO_RX_ON_IDLE;

9. APS layer

9.1. Functions

9.1.1. ZbApsAddrIsBcast

bool ZbApsAddrIsBcast(const struct ZbApsAddrT *addr);

Check if an address is set to broadcast.

Parameters

addr	Address to check

Return

• Returns true if the address is set to broadcast, false otherwise

9.1.2. ZbApsAddrIsLocal

bool ZbApsAddrIsLocal(struct ZigBeeT *zb, const struct ZbApsAddrT *addr);

Check if an address is that of the provided Zigbee stack structure.

Parameters

zb	Zigbee stack instance
addr	Address to check

Return

• Returns true if the address is local, false otherwise.

9.1.3. ZbApsBindSrcExists

bool ZbApsBindSrcExists(struct ZigBeeT *zb, uint8_t endpoint, uint16_t clusterId);

Returns true if there is a binding entry in the Binding Table that matches the local device as the source address, and a matching source endpoint and cluster Id.

Parameters

zb	Zigbee stack instance
endpoint	Source endpoint
clusterId	Cluster Id

Return

• Returns true if binding exists, false otherwise.

9.1.4. ZbApsCommandSecurityCheck

bool ZbApsCommandSecurityCheck(struct ZigBeeT *zb, enum ZbApsCmdIdT cmdId, uint64_t srcExtAddr, enum ZbSecEncryptT encryptKeyType);

Check if an incoming command has the appropriate security level.

Parameters

zb	Zigbee stack instance
cmdId	Command Id
srcExtAddr	Source extended address
encryptKeyType	Key type

Return

• Returns true if the command is allowed, false otherwise

9.1.5. ZbApsEndpointExists

bool ZbApsEndpointExists(struct ZigBeeT *zb, uint8_t endpoint);

Determine if an endpoint currently exists.

Parameters

zb	Zigbee stack instance
endpoint	endpoint

Return

• Returns true if the endpoint is found, false otherwise

9.1.6. ZbApsEndpointProfile

uint16_t ZbApsEndpointProfile(struct ZigBeeT *zb, uint8_t endpoint);

Retrieve the profile ID of an endpoint.

Parameters

zb	Zigbee stack instance
endpoint	endpoint

Return

• Returns profile ID, or ZCL_PROFILE_WILDCARD (0xffff) on error

9.1.7. ZbApsFilterClusterAdd

struct ZbApsFilterT * ZbApsFilterClusterAdd(struct ZigBeeT *zb, uint8_t endpoint, uint16_t clusterId, uint16_t profileId, 
enum zb_msg_filter_rc (*callback) (struct ZbApsdeDataIndT *dataInd, void *cb_arg), void *arg);

Create an APSDE-DATA.indication filter for a specific endpoint and cluster Id. being filtered. For any incoming APS data packets that match this filter, the provided 'callback' function is called. The filter is freed by calling ZbApsFilterEndpointFree.

Parameters

zb	Zigbee instance
endpoint	Endpoint Id to match with incoming packets
clusterId	Cluster Id to match with incoming packets
profileId	Profile Id to match with incoming packets
callback	APSDE-DATA.indication callback if the filter matches the incoming packet
arg	Application callback argument, which will be passed to callback()

Return

• Filter pointer (handle)

9.1.8. ZbApsFilterEndpointAdd

struct ZbApsFilterT * ZbApsFilterEndpointAdd(struct ZigBeeT *zb, uint8_t endpoint, uint16_t profileId, 
enum zb_msg_filter_rc (*callback) (struct ZbApsdeDataIndT *dataInd, void *cb_arg), void *arg);

Create an APSDE-DATA.indication filter for a specific endpoint, with no specific cluster being filtered. For any incoming APS data packets that match this filter, the provided 'callback' function is called. The filter is freed by calling ZbApsFilterEndpointFree.

Parameters

zb	Zigbee instance
endpoint	Endpoint Id to match with incoming packets
profileId	Profile Id to match with incoming packets
callback	APSDE-DATA.indication callback if the filter matches the incoming packet.
arg	Application callback argument, which will be passed to callback()

Return

• Filter pointer (handle)

9.1.9. ZbApsFilterEndpointFree

Remove and free an APS indication filter.

void ZbApsFilterEndpointFree(struct ZigBeeT *zb, struct ZbApsFilterT *filter);

Parameters

zb	Zigbee instance
filter	Filter handle to remove and free

Return

• Returns void

9.1.10. ZbApsFragDropTxAdd

bool ZbApsFragDropTxAdd(struct ZigBeeT *zb, uint8_t blockNum);

Used by the zbcli application as a DUT during ZCP certification testing (TP/PRO/BV-43 and TP/PRO/BV-44). It causes the stack to drop the next APS fragment to be transmitted matching the block number given by 'blockNum'.

Parameters

zb	Zigbee stack instance
blockNum	APS fragment block number to drop and prevent from being sent.

Return

• True if the block number entry was created, false otherwise.

9.1.11. ZbApsFragDropTxClear

void ZbApsFragDropTxClear(struct ZigBeeT *zb);

Used by the zbcli application as a DUT during ZCP certification testing (TP/PRO/BV-43 and TP/PRO/BV-44). It clears all entries created by ZbApsFragDropTxAdd to drop APS fragments about to be transmitted. No fragments will be purposefully dropped after this point.

Parameters

zb	Zigbee stack instance

Return

• Returns void

9.1.12. ZbApsGetIndex

enum ZbStatusCodeT ZbApsGetIndex(struct ZigBeeT *zb, enum ZbApsmeIbAttrIdT attrId, void *attrPtr, 
unsigned int attrSz, unsigned int attrIndex);

Performs an APSME-GET.request. Retrieve the value of the attribute corresponding to the supplied index.

Parameters

zb	Zigbee stack instance
attrId	Attribute Id
attrPtr	Attribute pointer
attrSz	attribute size

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

9.1.13. ZbApsGroupIsMember

bool ZbApsGroupIsMember(struct ZigBeeT *zb, uint16_t groupAddr, uint8_t endpoint);

Check if the local device is a member of a specified group.

Parameters

zb	Zigbee stack instance
groupAddr	Group address
endpoint	Endpoint of interest, or ZB_ENDPOINT_BCAST to determine if any endpoint is a member of the group

Return

• Returns true if the device is a member, false otherwise

9.1.14. ZbApsGroupsGetCapacity

uint8_t ZbApsGroupsGetCapacity(struct ZigBeeT *zb);

Retrieve the number of free entries in the group table.

Parameters

zb	Zigbee stack instance

Return

• Returns the number of free entries in the group table

9.1.15. ZbApsGroupsGetMembership

uint8_t ZbApsGroupsGetMembership(struct ZigBeeT *zb, uint8_t endpoint, uint16_t *group_list, uint8_t max_len);

Retrieve all group addresses on this endpoint.

Parameters

zb	Zigbee stack instance
endpoint	endpoint
group_list	(OUT) list of groups on this endpoint
max_len	Maximum number of groups to be returned

Return

• Returns a number of group addresses

9.1.16. ZbApsLinkKeyExists

bool ZbApsLinkKeyExists(struct ZigBeeT *zb, uint64_t partner);

Check if a link key exists in the AIB.

Parameters

zb	Zigbee stack instance
Partner	address

Return

• Returns true if the key exists, false otherwise

9.1.17. ZbApsLookupKey

struct ZbApsmeKeyPairT * ZbApsLookupKey(struct ZigBeeT *zb, struct ZbApsmeKeyPairT
*key, uint64_t addr, unsigned int *idx);

Look up an APS key pair descriptor from the apsDeviceKeyPairSet AIB attribute/key table.

Parameters

zb	Zigbee stack instance
key	(OUT) key pair descriptor
addr	Partner addresses
idx	(OUT) index value into Device Key Pair Set Table for the APS key returned, if successful

Return

• Returns key pair on success, or NULL if no such entry was found

9.1.18. ZbApsSetIndex

enum ZbStatusCodeT ZbApsSetIndex(struct ZigBeeT *zb, enum ZbApsmeIbAttrIdT attrId,
const void *attrPtr, unsigned int attrSz, unsigned int attrIndex);

Performs an APSME-SET.request. Set the value of the attribute corresponding to the supplied index.

Parameters

zb	Zigbee stack instance
attrId	Attribute Id
attrPtr	Attribute pointer
attrSz	attribute size

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

9.1.19. ZbApsUnbindAllReq

void ZbApsUnbindAllReq(struct ZigBeeT *zb);

Remove all entries from the binding table.

Parameters

zb	Zigbee stack instance

Return

• Returns void

9.1.20. ZbApsdeDataReqCallback

enum ZbStatusCodeT ZbApsdeDataReqCallback(struct ZigBeeT *zb, struct ZbApsdeDataReqT *req, 
void (*callback)(struct ZbApsdeDataConfT *conf, void *arg), void *arg);

Send an APSDE-DATA.request.

Parameters

zb	Zigbee instance
req	APSDE-DATA.request data structure
callback	Application callback to call for APSDE-DATA.confirm. May be set to NULL
arg	Application callback argument, which will be passed to callback()

Return

• ZCL_STATUS_SUCCESS if the packet was queued, or other ZclStatusCodeT value on error

9.1.21. ZbApsmeAddEndpoint

void ZbApsmeAddEndpoint(struct ZigBeeT *zb, struct ZbApsmeAddEndpointReqT *r, struct ZbApsmeAddEndpointConfT *c);

Register an endpoint with the ZigBee stack. Typically called during initialization. Should be safe to call from an init function.

Parameters

zb	Zigbee stack instance
r	APSME-ADD-ENDPOINT.request
c	APSME-ADD-ENDPOINT.confirm

Return

• Returns void

9.1.22. ZbApsmeAddGroupReq

void ZbApsmeAddGroupReq(struct ZigBeeT *zb, struct ZbApsmeAddGroupReqT *r, struct ZbApsmeAddGroupConfT *c);

Add an entry to the group table.

Parameters

zb	Zigbee stack instance
r	APSME-ADD-GROUP.request
c	APSME-ADD-GROUP.confirm

Return

• Returns void

9.1.23. ZbApsmeAddKeyReq

void ZbApsmeAddKeyReq(struct ZigBeeT *zb, struct ZbApsmeAddKeyReqT *req, struct ZbApsmeAddKeyConfT *conf);

Perform an APSME-ADD-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-ADD-KEY.request
conf	APSME-ADD-KEY.confirm

Return

• Returns void

9.1.24. ZbApsmeBindReq

void ZbApsmeBindReq(struct ZigBeeT *zb, struct ZbApsmeBindReqT *bindReqPtr, struct ZbApsmeBindConfT *bindConfPtr);

Add an entry to the stack binding table. The size of the binding table is determined in the tableSizes parameter to ZbInit(). The binding table is maintained by the stack.

Parameters

zb	Zigbee stack instance
bindReqPtr	APSME-BIND.request
bindConfPtr
APSME-BIND.confirm

Return

• Returns void

9.1.25. ZbApsmeConfirmKeyReq

void ZbApsmeConfirmKeyReq(struct ZigBeeT *zb, struct ZbApsmeConfirmKeyReqT *req,
void (*callback)(struct ZbApsdeDataConfT *conf, void *arg), void *arg);

Perform an APSME-CONFIRM-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-CONFIRM-KEY.request

Return

• Returns void

9.1.26. ZbApsmeEndpointClusterListAppend

bool ZbApsmeEndpointClusterListAppend(struct ZigBeeT *zb, uint8_t endpoint, uint16_t cluster_id, bool is_input);

Add a cluster ID to the input cluster list of an existing endpoint.

Parameters

zb	Zigbee stack instance
endpoint	endpoint
cluster_id	ID of cluster to be added
is_input	true if input cluster, false if output cluster

Return

• Returns true on success, false otherwise

9.1.27. ZbApsmeEndpointClusterListRemove

bool ZbApsmeEndpointClusterListRemove(struct ZigBeeT *zb, uint8_t endpoint, uint16_t cluster_id, bool is_input);

Remove a cluster from an endpoint’s cluster list.

Parameters

zb	Zigbee stack instance
endpoint	endpoint
cluster_id	ID of cluster to be removed
is_input	true if input cluster, false if output cluster

Return

• Returns true on success, false otherwise

9.1.28. ZbApsmeGetKeyReq

void ZbApsmeGetKeyReq(struct ZigBeeT *zb, struct ZbApsmeGetKeyReqT *req, struct ZbApsmeGetKeyConfT *conf);

Perform an APSME-GET-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-GET-KEY.request
conf	APSME-GET-KEY.confirm

Return

• Returns void

9.1.29. ZbApsmeRemoveAllGroupsReq

void ZbApsmeRemoveAllGroupsReq(struct ZigBeeT *zb, struct ZbApsmeRemoveAllGroupsReqT *r, struct ZbApsmeRemoveAllGroupsConfT *c);

Remove all entries from the group table.

Parameters

zb	Zigbee stack instance
r	APSME-REMOVE-ALL-GROUPS.request
c	APSME-REMOVE-ALL-GROUPS.confirm

Return

• Returns void

9.1.30. ZbApsmeRemoveDeviceReq

void ZbApsmeRemoveDeviceReq(struct ZigBeeT *zb, struct ZbApsmeRemoveDeviceReqT *req);

Perform an APSME-REMOVE-DEVICE.request.

Parameters

zb	Zigbee stack instance
req	APSME-REMOVE-DEVICE.request

Return

• Returns void

9.1.31. ZbApsmeRemoveEndpoint

void ZbApsmeRemoveEndpoint(struct ZigBeeT *zb, struct ZbApsmeRemoveEndpointReqT *r, struct ZbApsmeRemoveEndpointConfT *c);

Unregister and remove an endpoint from the APS endpoint table. Typically called when terminating an application.

Parameters

zb	Zigbee stack instance
r	APSME-REMOVE-ENDPOINT.request
c	APSME-REMOVE-ENDPOINT.confirm

Return

• Returns void

9.1.32. ZbApsmeRemoveGroupReq

void ZbApsmeRemoveGroupReq(struct ZigBeeT *zb, struct ZbApsmeRemoveGroupReqT *r, struct ZbApsmeRemoveGroupConfT *c);

Remove an entry from the group table

Parameters

zb	Zigbee stack instance
r	APSME-REMOVE-GROUP.request
c	APSME-REMOVE-GROUP.confirm

Return

• Returns void

9.1.33. ZbApsmeRemoveKeyReq

void ZbApsmeRemoveKeyReq(struct ZigBeeT *zb, struct ZbApsmeRemoveKeyReqT *req,
struct ZbApsmeRemoveKeyConfT *conf);

Perform an APSME-REMOVE-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-REMOVE-KEY.request
conf	APSME-REMOVE-KEY.confirm

Return

• Returns void

9.1.34. ZbApsmeRequestKeyReq

enum ZbStatusCodeT ZbApsmeRequestKeyReq(struct ZigBeeT *zb, struct ZbApsmeRequestKeyReqT *req);

Perform an APSME-REQUEST-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-REQUEST-KEY.request

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

9.1.35. ZbApsmeSwitchKeyReq

void ZbApsmeSwitchKeyReq(struct ZigBeeT *zb, struct ZbApsmeSwitchKeyReqT *req);

Perform an APSME-SWITCH-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-SWITCH-KEY.request

Return

• Returns void

9.1.36. ZbApsmeTransportKeyReq

void ZbApsmeTransportKeyReq(struct ZigBeeT *zb, struct ZbApsmeTransportKeyReqT *req);

Perform an APSME-TRANSPORT-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-TRANSPORT-KEY.request

Return

• Returns void

9.1.37. ZbApsmeUnbindReq

void ZbApsmeUnbindReq(struct ZigBeeT *zb, struct ZbApsmeUnbindReqT *unbindReqPtr, struct ZbApsmeUnbindConfT *unbindConfPtr);

Remove an entry from the binding table.

Parameters

zb	Zigbee stack instance
unbindReqPtr	APSME-UNBIND.request
unbindConfPtr	APSME-UNBIND.confirm

Return

• Returns void

9.1.38. ZbApsmeUpdateDeviceReq

enum ZbSecHdrKeyIdT ZbApsmeUpdateDeviceReq(struct ZigBeeT *zb, struct ZbApsmeUpdateDeviceReqT *req);

Perform an APSME-UPDATE-DEVICE.request.

Parameters

zb	Zigbee stack instance
req	APSME-UPDATE-DEVICE.request

Return

• Returns security key used to send Update Device

9.1.39. ZbApsmeVerifyKeyReq

void ZbApsmeVerifyKeyReq(struct ZigBeeT *zb, struct ZbApsmeVerifyKeyReqT *req);

Perform an APSME-VERIFY-KEY.request.

Parameters

zb	Zigbee stack instance
req	APSME-VERIFY-KEY.request

Return

• Returns void

9.2. Enumerations

9.2.1. ZbApsAddrModeT

APSDE and interpan addressing modes

ZB_APSDE_ADDRMODE_NOTPRESENT	DstAddress and DstEndpoint not present
ZB_APSDE_ADDRMODE_GROUP	16-bit group address for DstAddress; DstEndpoint not present
ZB_APSDE_ADDRMODE_SHORT	16-bit address for DstAddress and DstEndpoint present
ZB_APSDE_ADDRMODE_EXT	64-bit extended address for DstAddress and DstEndpoint present
ZB_APSDE_ADDRMODE_IPGROUP	InterPAN

9.2.2. ZbApsCmdIdT

APS command frame IDs

ZB_APS_CMD_TRANSPORT_KEY	Transport Key
ZB_APS_CMD_UPDATE_DEVICE	Update Device
ZB_APS_CMD_REMOVE_DEVICE	Remove Device
ZB_APS_CMD_REQUEST_KEY	Request Key
ZB_APS_CMD_SWITCH_KEY	Switch Key
ZB_APS_CMD_TUNNEL	Tunnel
ZB_APS_CMD_VERIFY_KEY	Verify Key
ZB_APS_CMD_CONFIRM_KEY	Confirm Key
ZB_APS_CMD_RELAY_DOWNSTREAM	Relay Downstream
ZB_APS_CMD_RELAY_UPSTREAM	Relay Upstream

9.2.3. ZbApsInitialJoinAuthMethodT

Initial join authentication method used with DLK.

ZB_APS_INITIAL_JOIN_AUTH_NONE	Initial join authentication - none.
ZB_APS_INITIAL_JOIN_AUTH_INSTALL_CODE_KEY	Initial join authentication - install code key.
ZB_APS_INITIAL_JOIN_AUTH_ANON_KEY_NEGO	Initial join authentication - anonymous key negotiation.
ZB_APS_INITIAL_JOIN_AUTH_KEY_NEGO_WITH_AUTH	Initial join authentication - authentication key negotiation.

9.2.4. ZbApsPostJoinKeyUpdateMethodT

Post join key update method.

ZB_APS_POST_JOIN_KEY_UPDATE_NONE	Post join key update - none.
ZB_APS_POST_JOIN_KEY_UPDATE_REQUEST_KEY	Post join key update - request key.
ZB_APS_POST_JOIN_KEY_UPDATE_UNAUTH_DLK	Post join key update - anonymous DLK.
ZB_APS_POST_JOIN_KEY_UPDATE_AUTH_DLK	Post join key update - authentication DLK.
ZB_APS_POST_JOIN_KEY_UPDATE_CBKE	Post join key update - CBKE.

9.2.5. ZbApsRequestKeyTypeT

RequestKeyType values

ZB_APS_REQKEY_KEYTYPE_APP_LINK	Application Link Key
ZB_APS_REQKEY_KEYTYPE_TC_LINK	Trust Center Link Key

9.2.6. ZbApsmeDeviceStatusT

Device status values for APSME-UPDATE-DEVICE.request and indication

ZB_APSME_DEV_STD_SECURE_REJOIN	Standard device secured rejoin
ZB_APSME_DEV_STD_INSECURE_JOIN	Standard device unsecured join
ZB_APSME_DEV_LEFT	Device left
ZB_APSME_DEV_STD_INSECURE_REJOIN	Standard device trust center rejoin

9.2.7. ZbApsmeIbAttrIdT

APS IB attributes

ZB_APS_IB_ID_BINDING_TABLE	apsBindingTable (type: struct ZbApsmeBindT, reset: yes, persist: yes)
ZB_APS_IB_ID_DESIGNATED_COORD	apsDesignatedCoordinator (type: uint8_t, reset: yes, persist: yes)
ZB_APS_IB_ID_CHANNEL_MASK	apsChannelMaskList. Converted to a list in R22 (type: struct ZbChannelListT, reset: yes, persist: yes)
ZB_APS_IB_ID_USE_EPID	apsUseExtendedPANID (type: uint64_t, reset: yes, persist: no)
ZB_APS_IB_ID_GROUP_TABLE	apsGroupTable (type: struct ZbApsmeGroupT, reset: yes, persist: yes)
ZB_APS_IB_ID_USE_INSECURE_JOIN	apsUseInsecureJoin (type: uint8_t, reset: yes, persist: yes)
ZB_APS_IB_ID_INTERFRAME_DELAY	apsInterframeDelay (type: uint8_t, reset: no, persist: no)
ZB_APS_IB_ID_LAST_CHANNEL_ENERGY	apsLastChannelEnergy (type: uint8_t, reset: yes, persist: no)
ZB_APS_IB_ID_LAST_CHANNEL_FAILRATE	apsLastChannelFailureRate (type: uint8_t, reset: yes, persist: no)
ZB_APS_IB_ID_CHANNEL_TIMER	apsChannelTimer (type: ZbUptimeT, reset: yes, persist: no)
ZB_APS_IB_ID_MAX_WINDOW_SIZE	apsMaxWindow Size (type: uint8_t, reset: no, persist: no)
ZB_APS_IB_ID_ZDO_RESTRICTED_MODE	R23 (type: uint8_t, reset: yes, persist: no)
ZB_APS_IB_ID_STAT_TABLE	R23 (type: uint8_t, reset: no, persist: no)
ZB_APS_IB_ID_DEVICE_KEY_PAIR_SET	apsDeviceKeyPairSet (type: struct ZbApsmeKeyPairT, reset: yes, persist: yes)
ZB_APS_IB_ID_TRUST_CENTER_ADDRESS	apsTrustCenterAddress (type: uint64_t, reset: yes, persist: yes)
ZB_APS_IB_ID_SECURITY_TIMEOUT_PERIOD	apsSecurityTimeoutPeriod, milliseconds (type: uint16_t, reset: no, persist: no)
ZB_APS_IB_ID_TRUST_CENTER_POLICY	trustCenterPolicies. Trust center policy table bitmask Represents the following AIBs: allowJoins = 0xad, requireInstallCodesOrPresetPassphrase = 0xaf, updateTrustCenterLinkKeysRequired = 0xb3, allowRejoinsWithWellKnownKey = 0xb6, allowTrustCenterLinkKeyRequests = 0xb7, networkKeyUpdateMethod = 0xba, allowApplicationKeyRequests = 0xbb, allowRemoteTcPolicyChange = 0xbd, allowVirtualDevices = 0xbe (type: uint32_t, enum ZbApsmePolicyT, reset: no, persist: no)
ZB_APS_IB_ID_SUPPORTED_KEY_NEGO_METHODS	apsSupportedKeyNegotiationMethods (R23) (type: uint8_t, reset: no, persist: no)
ZB_APS_IB_ID_CHALLENGE_VALUE	apsChallengeValue (R23) (type: uint64_t, reset: no, persist: no)
ZB_APS_IB_ID_CHALLENGE_TARGET_EUI64	apsChallengeTargetEui64 (R23) (type: uint64_t, reset: no, persist: no)
ZB_APS_IB_ID_DEVICE_INTERVIEW_TIMEOUT_PERIOD	apsDeviceInterviewTimeoutPeriod (R23), seconds (type: uint8_t, reset: no, persist: no). The TC will refresh the Device Interview Timeout for each APS Downstream Relay sent to the joining device. The joining device will refresh the Device Interview Timeout for each APS Downstream Relay it receives from the TC.
ZB_APS_IB_ID_SCAN_COUNT	ZDO join parameter. (type: uint8_t, reset: no, persist: yes)
ZB_APS_IB_ID_LEAVE_REMOVE_CHILDREN	ZDO leave parameter (type: uint8_t, reset: yes, persist:yes)
ZB_APS_IB_ID_PRECONFIGURED_LINK_KEY	apsPreconfiguredLinkKey. Preconfigured Trust Center Link Key. (type: array of uint8_t of size ZB_SEC_KEYSIZE, reset: yes, persist: yes)
ZB_APS_IB_ID_DISTRIBUTED_GLOBAL_KEY	apsDistributedGlobalKey (type: array of uint8_t of size ZB_SEC_KEYSIZE, reset: yes, persist: yes)
ZB_APS_IB_ID_KEY_UPDATE_PERIOD	KeyUpdatePeriod. From the trust center policy table. (type: uint32_t, reset: yes, persist: no)
ZB_APS_IB_ID_MANUFACTURER_ID	Manufacturer ID (type: uint16_t, reset: no, persist: no)
ZB_APS_IB_ID_SEND_PKT_COOLDOWN	Send packet cooldown in milliseconds (type: uint16_t, reset: no, persist: no)
ZB_APS_IB_ID_BIND_ADDR_RESOLVE_PERIOD	Bind address resolve period in seconds, 0 = disabled (type: uint16_t, reset: no, persist: no)
ZB_APS_IB_ID_FRAGMENTATION_THRESH	apsFragmentationThresh. Fragmentation Threshold (type: uint8_t, reset: no, persist: no)
ZB_APS_IB_ID_SUPPORTED_PSK_SECRETS	apsSupportedPreSharedSecrets (R23) (type: uint8_t, reset: no, persist: no)
ZB_APS_IB_ID_MAX_IN_QUEUED_PACKETS	The maximum number of incoming packets the APS is allowed to queue. Default is 0, which means there is no limit, other than available memory. A SED may want to set this value between 2 to 4 so it does not get overwhelmed with requests during its wake cycle. (type: uint16_t, reset: no, persist: no)
ZB_APS_IB_ID_SUSPEND_ZCL_APSDE_DATA_REQ	apsSuspendZclApsdeDataReq. When set to true transmission of ASPDE-DATA.requests from ZCL are suspended and will return error right away. (type: uint8_t, reset: yes, persist: yes)
ZB_APS_IB_ID_MAX

9.2.8. ZbApsmePolicyT

Trust center policy flags (ZB_APS_IB_ID_TRUST_CENTER_POLICY)

ZB_APSME_POLICY_ALLOW_JOIN	allowJoins
ZB_APSME_POLICY_WHITELIST	useWhiteList
ZB_APSME_POLICY_IC_MASK	allowInstallCodes
ZB_APSME_POLICY_IC_NOT_SUPPORTED	0x00 - Do not support Install Codes Or Preset Passphrase
ZB_APSME_POLICY_IC_SUPPORTED	0x01 - Support but do not require Install Codes Or Preset Passphrase
ZB_APSME_POLICY_IC_REQUIRED	0x02 - Require the use of Install Codes Or Preset Passphrase)
ZB_APSME_POLICY_TCLK_UPDATE_REQUIRED	updateTrustCenterLinkKeysRequired
ZB_APSME_POLICY_ALLOW_REJOIN	allowRejoins
ZB_APSME_POLICY_TC_KEY_REQ_MASK	allowTrustCenterLinkKeyRequests
ZB_APSME_POLICY_TC_KEY_REQ_ANY	0x01 - Any device may request
ZB_APSME_POLICY_TC_KEY_REQ_PROV	allowApplicationKeyRequests
ZB_APSME_POLICY_APP_KEY_REQ_NEVER	0x00 - Never
ZB_APSME_POLICY_APP_KEY_REQ_ANY	0x01 - Any
ZB_APSME_POLICY_APP_KEY_REQ_PROV	0x02 - Provisional, requires "applicationKeyRequestList" to be implemented
ZB_APSME_POLICY_TC_POLICY_CHANGE	allowRemoteTcPolicyChange
ZB_APSME_POLICY_ALLOW_VIRTUAL_DEVICES	allowVirtualDevices
ZB_APSME_POLICY_DUMMY_KEY

9.3. Structures

9.3.1. ZbApsAddrT

APS address information data structure

Parameters

enum ZbApsAddrModeT mode	Address mode (e.g. short, group, extended)
uint16_t endpoint	Destination endpoint. If set to ZB_ENDPOINT_INTERPAN, then packet is sent as an InterPAN packet
uint16_t panId	Destination PAN Id. This is for InterPAN packets, when the endpoint == ZB_ENDPOINT_INTERPAN
uint16_t nwkAddr	Destination network address when mode == ZB_APSDE_ADDRMODE_SHORT, ZB_APSDE_ADDRMODE_GROUP or ZB_APSDE_ADDRMODE_IPGROUP
uint64_t extAddr	Destination extended address when mode == ZB_APSDE_ADDRMODE_EXT
uint16_t nwkBcastAddr	nwkBcastAddr - This indicates the broadcast address used for groupcast messages (DstAddrMode = 0x01). Valid range: 0xFFFC - 0xFFFF

9.3.2. ZbApsBufT

Buffer descriptor for vectored/scatter-gather API. Used when ZB_APSDE_DATAREQ_TXOPTIONS_VECTOR TX

Options bit is set.

Parameters

const uint8_t *data	Data
unsigned int len	Length

9.3.3. ZbApsRelayInfoT

APS relay information data structure

Parameters

bool relayMsg	If true, APS packet shall be relayed.
uint64_t relayExtAddr	Destination EUI64 for downstream, source EUI64 in case of upstream relay command.
uint64_t relayDstAddr	APS relay command destination address. Address of intermediate router (multi-hop) or unauthorized joiner (single-hop) for downstream. Address of intermediate router (multi-hop) or TC (single-hop) for upstream.

9.3.4. ZbApsdeDataConfT

APSDE-DATA.confirm data structure

Parameters

struct ZbApsAddrT dst	DstAddrMode - Destination address information of the APSDE-DATA.request
uint8_t srcEndpt	SrcEndpoint - Source endpoint of the APSDE-DATA.request
uint32_t asduHandle	The optional handle ID from the APSDE-DATA.request
enum ZbStatusCodeT status	Zigbee Status Code

9.3.5. ZbApsdeDataIndT

APSDE-DATA.indication data structure. These messages are received from the stack after setting up the proper message filter using ZbApsFilterEndpointAdd or ZbApsFilterClusterAdd.

Parameters

struct ZbApsAddrT dst	DstAddress - Destination address information of the incoming APS message
struct ZbApsAddrT src	SrcAddress - Source address information of the incoming APS message
uint16_t profileId	ProfileId - The profile for which this frame is intended
uint16_t clusterId	ClusterId - The object for which this frame is intended
uint8_t *asdu	asdu - The set of octets comprising the ASDU that was received
uint16_t asduLength	asduLength - The number of octets comprising the ASDU
enum ZbStatusCodeT securityStatus	SecurityStatus - The security level used to encrypt the incoming frame. One of: ZB_APS_STATUS_UNSECURED (no decryption necessary), ZB_APS_STATUS_SECURED_NWK_KEY (decrypted with the Network Key), ZB_APS_STATUS_SECURED_LINK_KEY, (decrypted with a Link Key)
uint8_t linkQuality	LinkQuality - The incoming Link Quality value, or set to 0 if not supported by lower layers
int8_t rssi	The incoming RSSI value, or set to PHY_RSSI_INVALID (-128) if not supported by lower layers
uint16_t linkAddr	Exegin Addon for Inter-PAN portability
struct ZbApsRelayInfoT relayInfo	Contains required information to relay the APS packet.

9.3.6. ZbApsdeDataReqT

APSDE-DATA.request data structure

Parameters

struct ZbApsAddrT dst	DstAddress - DstEndpoint Destination address information, including address mode, address and endpoint
uint16_t profileId	ProfileId - ProfileId The profile for which this frame is intended
uint16_t clusterId	ClusterId - The object for which this frame is intended
uint16_t srcEndpt	SrcEndpoint - The source endpoint
const void *asdu	ASDU - The set of octets comprising the ASDU to be transferred
uint16_t asduLength	ASDULength - The number of octets comprising the ASDU
uint32_t asduHandle	An optional handle ID to use to match up with the APSDE-DATA.confirm
uint16_t txOptions	TxOptions -Transmit options bitmask (for example ZB_APSDE_DATAREQ_TXOPTIONS_SECURITY)
bool discoverRoute	discoverRoute - If you perform route discovery separately using ZbNlmeRouteDiscReq(), then you can set discoverRoute to zero, decreasing the length of time an APS data request may take if there is a problem sending the packet to the target
uint8_t radius	Radius - Network radius. If 0, default value is used
uint16_t aliasAddr	AliasSrcAddr - Requires ZB_APSDE_DATAREQ_TXOPTIONS_ALIAS to be enabled
uint8_t aliasSeqnum	AliasSeqNumb - Requires ZB_APSDE_DATAREQ_TXOPTIONS_ALIAS to be enabled
struct ZbApsRelayInfoT relayInfo	Contains required information to relay the APS packet.

9.3.7. ZbApsmeAddEndpointConfT

APSME-ADD-ENDPOINT.confirm - Exegin Custom

Parameters

enum ZbStatusCodeT status

Status

9.3.8. . ZbApsmeAddEndpointReqT

APSME-ADD-ENDPOINT.request - Exegin Custom

Parameters

uint8_t endpoint	Endpoint
uint16_t profileId	Profile Id
uint16_t deviceId	Device Id
uint8_t version	Version
uint8_t inputClusterCount	Supported Server Clusters
const uint16_t *inputClusterList	Pointer to the input cluster list
uint8_t outputClusterCount	Pointer to the output cluster list
uint16_t bdbCommissioningGroupID	e.g. DEFAULT_EP_BDB_COMMISSION_GRP_ID;

9.3.9. ZbApsmeAddGroupConfT

APSME-ADD-GROUP.confirm Parameters

enum ZbStatusCodeT status	Status
uint16_t groupAddr	GroupAddress
uint8_t endpt	Endpoint

9.3.10. ZbApsmeAddGroupReqT

APSME-ADD-GROUP.request

Parameters

uint16_t groupAddr	GroupAddress
uint8_t endpt	Endpoint

9.3.11. ZbApsmeAddKeyConfT

APSME-ADD-KEY.confirm - Exegin custom

Parameters

enum ZbStatusCodeT status

Status

9.3.12. ZbApsmeAddKeyReqT

APSME-ADD-KEY.request - Exegin custom

Parameters

enum ZbSecKeyTypeT keyType	Key type e.g, ZB_SEC_KEYTYPE_STANDARD_NWK.
uint8_t key	Input Key.
uint8_t keyAttribute	Key attribute e.g, ZB_APSME_KEY_ATTR_VERIFIED
uint8_t keySeqNumber	Sequence number of the input key.
uint64_t partnerAddr	Partner address of the key added to APS KeyPair table.
uint32_t outgoingCounter	Post join key update method. (R23+)
enum ZbSelKeyNegoMethodT selKeyNegoMethod	Selected key negotiation method. (R23+)
enum ZbApsKeyNegoStateT keyNegoState	APS key negotiation state. (R23+)
enum ZbApsPreSharedKeyTypeT preSharedKeyType	APS pre-shared key type. (R23+)
uint8_t passphrase	Passphrase to use for authentication DLK. (R23+)
bool passphraseUpdateAllowed	APS passphrase update allowed. (R23+)
bool verifiedFrameCounter	Indicates whether the incoming frame counter value has been verified through a challenge response. Frame counters are implicitly verified after join, i.e, TCLK/DLK etc. However, after reboot FC shall be verified using ZDO Security_Challenge_req/rsp (R23+)
uint8_t capabilities	Link key features and capabilities e.g, ZB_APS_SEC_CAPABILITY_FC_SYNC_SUPPORT.

9.3.13. ZbApsmeBindConfT

APSME-BIND.confirm

Parameters

enum ZbStatusCodeT status	Status
uint64_t srcExtAddr	SrcAddr
uint8_t srcEndpt	SrcEndpoint
uint16_t clusterId	ClusterId
struct ZbApsAddrT dst	APS address information data structure

9.3.14. ZbApsmeBindReqT

APSME-BIND.request

Parameters

uint64_t srcExtAddr	SrcAddr
uint8_t srcEndpt	SrcEndpoint
uint16_t clusterId	ClusterId
struct ZbApsAddrT dst	APS address information data structure

9.3.15. ZbApsmeBindT

APS binding table entry

Parameters

uint64_t srcExtAddr	SrcAddr - if zero, entry is invalid
uint8_t srcEndpt	SrcEndpoint
uint16_t clusterId	ClusterId
struct ZbApsAddrT dst	APS address information data structure

9.3.16. ZbApsmeConfirmKeyIndT

APSME-CONFIRM-KEY.indication

Parameters

enum ZbStatusCodeT status	Status
uint64_t srcExtAddr	SrcAddress
enum ZbSecKeyTypeT keyType	StandardKeyType
enum ZbSecEncryptT encryptKeyType	Contains information required to relay the APS packet.

9.3.17. ZbApsmeConfirmKeyReqT

APSME-CONFIRM-KEY.request

Parameters

enum ZbStatusCodeT status	Status
uint64_t dstExtAddr	DestAddress
enum ZbSecKeyTypeT keyType	StandardKeyType
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet.

9.3.18. ZbApsmeGetKeyReqT

APSME-GET-KEY.request - Exegin custom

Parameters

enum ZbSecKeyTypeT keyType	StandardKeyType
uint8_t keySeqNumber	KeySeqNumber
uint64_t partnerAddr	PartnerAddress

9.3.19. ZbApsmeGroupT

APS group ID table entry

Parameters

uint16_t groupAddr	GroupAddress
uint8_t endpoint	Endpoint

9.3.20. ZbApsmeKeyNegoConfirmT

APSME-KEY-NEGOTIATION.Confirm

Parameters

enum ZbStatusCodeT status	ZDO status.
uint8_t partnerPubPoint	Partner public point data
uint64_t partnerLongAddr	Partner extended address.
bool relayCommand	This indicates whether or not the response was relayed through another router.
uint64_t relayLongAddr	Extended address of intermediate relay device.

9.3.21. ZbApsmeKeyNegoIndT

APSME-KEY-NEGOTIATION.indication (R23)

Parameters

uint64_t partnerLongAddr	Partner extended address.
uint8_t partnerPubPoint	Partner public point data
uint8_t seqnum	ZDO sequence number.
bool relayCommand	This indicates whether or not the response should be relayed through another router.
uint64_t relayLongAddr	Extended address of intermediate relay device.

9.3.22. ZbApsmeRemoveAllGroupsConfT

APSME-REMOVE-ALL-GROUPS.confirm

Parameters

enum ZbStatusCodeT status	Status
uint8_t endpt	Endpoint

9.3.23. ZbApsmeRemoveAllGroupsReqT

APSME-REMOVE-ALL-GROUPS.request

Parameters

uint8_t endpt

Endpoint

9.3.24. ZbApsmeRemoveDeviceIndT

APSME-REMOVE-DEVICE.indication

Parameters

uint64_t srcExtAddr	SrcAddress
uint64_t targetAddr	TargetAddress
enum ZbSecEncryptT encryptKeyType

9.3.25. ZbApsmeRemoveDeviceReqT

APSME-REMOVE-DEVICE.request

Parameters

uint64_t dstExtAddr	ParentAddress
uint64_t targetAddr	TargetAddress

9.3.26. ZbApsmeRemoveEndpointConfT

APSME-REMOVE-ENDPOINT.confirm - Exegin custom

Parameters

enum ZbStatusCodeT status

Status

9.3.27. ZbApsmeRemoveEndpointReqT

APSME-REMOVE-ENDPOINT.request - Exegin custom

Parameters

uint8_t endpoint

Endpoint

9.3.28. ZbApsmeRemoveGroupConfT

APSME-REMOVE-GROUP.confirm

Parameters

enum ZbStatusCodeT status	Status
uint16_t groupAddr	GroupAddress
uint8_t endpt	Endpoint

9.3.29. ZbApsmeRemoveGroupReqT

APSME-REMOVE-GROUP.request

Parameters

uint16_t groupAddr	GroupAddress
uint8_t endpt	Endpoint

9.3.30. ZbApsmeRemoveKeyConfT

APSME-REMOVE-KEY.confirm - Exegin custom

Parameters

enum ZbStatusCodeT status

Status

9.3.31. ZbApsmeRemoveKeyReqT

APSME-REMOVE-KEY.request - Exegin custom

Parameters

enum ZbSecKeyTypeT keyType	StandardKeyType
uint64_t partnerAddr	PartnerAddress

9.3.32. ZbApsmeRequestKeyIndT

APSME-REQUEST-KEY.indication

Parameters

uint64_t srcExtAddr	SrcAddress
enum ZbApsRequestKeyTypeT keyType	RequestKeyType
uint64_t partnerAddr	PartnerAddress
enum ZbSecEncryptT encryptKeyType

9.3.33. ZbApsmeRequestKeyReqT

APSME-REQUEST-KEY.request

Parameters

uint64_t dstExtAddr	DestAddress
enum ZbApsRequestKeyTypeT keyType	RequestKeyType
uint64_t partnerAddr	PartnerAddress - Only used with application keys

9.3.34. ZbApsmeSecChallengeIndT

APSME-SEC-CHALLENGE.indication (R23 - Exegin add-on)

Parameters

uint16_t devShortAddr	Device short address.
uint64_t devExtAddr	Extended address of partner device to perform APS Frame counter synchronization.

9.3.35. ZbApsmeSecChallengeReqT

APSME-SEC-CHALLENGE.request (R23 - Exegin add-on)

Parameters

uint16_t devShortAddr	Device short address.
uint64_t devExtAddr	Extended address of partner device to perform APS Frame counter synchronization.

9.3.36. ZbApsmeSwitchKeyIndT

APSME-SWITCH-KEY.indication

Parameters

uint64_t srcExtAddr	SrcAddress
uint8_t keySeqNum	KeySeqNumber
enum ZbSecEncryptT encryptKeyType

9.3.37. ZbApsmeSwitchKeyReqT

APSME-SWITCH-KEY.request

Parameters

struct ZbApsAddrT dst	APS address information data structure
uint8_t keySeqNum	KeySeqNumber

9.3.38. ZbApsmeTransKeyIndT

APSME-TRANSPORT-KEY.indication

Parameters

uint64_t srcExtAddr	SrcAddress
enum ZbSecKeyTypeT keyType	StandardKeyType
union { struct { uint8_t key	Key
bool capabilities_valid	True, if a valid Link key and features TLV found.
uint8_t capabilities	Link key features and capabilities e.g, ZB_APS_SEC_CAPABILITY_FC_SYNC_SUPPORT. Valid only if 'capabilities_valid' is true.
struct { uint8_t keySeqNumber	KeySeqNumber
uint8_t key	Key
struct { uint64_t partnerAddr	PartnerAddress
bool initiator	Initiator
uint8_t key	Key
bool capabilities_valid	True, if a valid Link key and features TLV found.
uint8_t capabilities	Link key features and capabilities e.g, ZB_APS_SEC_CAPABILITY_FC_SYNC_SUPPORT. Valid only if 'capabilities_valid' is true.
enum ZbSecEncryptT encryptKeyType

9.3.39. ZbApsmeTransportKeyReqT

APSME-TRANSPORT-KEY.request

Parameters

struct ZbApsAddrT dst	APS address information data structure
enum ZbSecKeyTypeT keyType	StandardKeyType
union { struct { uint64_t parentAddr	ParentAddress
uint8_t key	Key
uint8_t capabilities	Link key features and capabilities e.g, ZB_APS_SEC_CAPABILITY_FC_SYNC_SUPPORT.
struct { uint8_t keySeqNumber	KeySeqNumber
uint8_t key	NetworkKey
bool useParent	UseParent
uint64_t parentAddr	ParentAddress
struct { uint64_t partnerAddr	PartnerAddress
bool initiator	Initiator
uint8_t key	Key
uint8_t capabilities	Link key features and capabilities e.g, ZB_APS_SEC_CAPABILITY_FC_SYNC_SUPPORT.

9.3.40. ZbApsmeUnbindConfT

APSME-UNBIND.confirm

Parameters

enum ZbStatusCodeT status	Status
uint64_t srcExtAddr	SrcAddr
uint8_t srcEndpt	SrcEndpoint
uint16_t clusterId	ClusterId
struct ZbApsAddrT dst	APS address information data structure

9.3.41. ZbApsmeUnbindReqT

APSME-UNBIND.request

Parameters

uint64_t srcExtAddr	SrcAddr
uint8_t srcEndpt	SrcEndpoint
uint16_t clusterId	ClusterId
struct ZbApsAddrT dst	APS address information data structure

9.3.41.1. 14.3.42. ZbApsmeUpdateDeviceIndT

APSME-UPDATE-DEVICE.indication

Parameters

uint64_t srcExtAddr	SrcAddress
uint64_t devExtAddr	DeviceAddress
uint16_t devShortAddr	DeviceShortAddress
enum ZbApsmeDeviceStatusT status	Status - Device status values
enum ZbSecEncryptT encryptKeyType	TLVs of the joining device as relayed during Network Commissioning

9.3.41.2. 14.3.43. ZbApsmeUpdateDeviceReqT

APSME-UPDATE-DEVICE.request

Parameters

uint64_t dstExtAddr	DestAddress
uint64_t devExtAddr	DeviceAddress
enum ZbApsmeDeviceStatusT status	Status - Device status values
uint16_t devShortAddr	DeviceShortAddress
struct ZbJoinerTLVsT joinerTLVs	TLVs of the joining device as relayed during Network Commissioning

9.3.41.3. 14.3.44. ZbApsmeVerifyKeyIndT

APSME-VERIFY-KEY.indication

Parameters

uint64_t srcExtAddr	SrcAddress
enum ZbSecKeyTypeT keyType	StandardKeyType
uint8_t hash	ReceivedInitiatorHashValue
enum ZbSecEncryptT encryptKeyType	Contains information required to relay the APS packet.

9.3.41.4. 14.3.45. ZbApsmeVerifyKeyReqT

APSME-VERIFY-KEY.request

Parameters

uint64_t dstExtAddr	DestAddress
enum ZbSecKeyTypeT keyType	StandardKeyType
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet.

9.3.41.5. 14.3.46. ZbMsgApsCommandT

APS Command Indication struct. Used with the message filter Id 'ZB_MSG_FILTER_APS_COMMAND_IND'.

Parameters

enum ZbApsCmdIdT id	The APS Command Id. e.g. ZB_APS_CMD_TRANSPORT_KEY
union { struct ZbApsmeTransKeyIndT trans_key

10. BDB Layer

#include "zigbee.bdb.h"

10.1. Functions

10.1.1. ZbBdbGetEndpointStatus

enum ZbBdbCommissioningStatusT ZbBdbGetEndpointStatus(struct ZigBeeT *zb, uint8_t endpoint);

Get commissioning status for the given endpoint (same for all endpoints?). If endpoint = ZB_ENDPOINT_BCAST, returns the status for the first endpoint found.

Parameters

zb	Zigbee instance
endpoint	Endpoint identifier

Return

• Returns ZB_BDB_COMMISS_STATUS_SUCCESS on success, other BDB status code on failure

10.1.2. ZbBdbGetIndex

enum ZbStatusCodeT ZbBdbGetIndex(struct ZigBeeT *zb, enum ZbBdbAttrIdT attrId, void
*attrPtr, unsigned int attrSz, unsigned int attrIndex);

Read a BDB IB attribute.

Parameters

zb	Zigbee stack instance
attrId	Attribute ID
attrPtr	Pointer to the attribute
attrSz	Attribute size
attrIndex	Index attribute

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

10.1.3. ZbBdbSetIndex

enum ZbStatusCodeT ZbBdbSetIndex(struct ZigBeeT *zb, enum ZbBdbAttrIdT attrId,
const void *attrPtr, unsigned int attrSz, unsigned int attrIndex);

Write a BDB IB attribute.

Parameters

zb	Zigbee stack instance
attrId	Attribute ID
attrPtr	Pointer to the attribute
attrSz	Attribute size
attrIndex	Index attribute

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

10.2. Enumerations

10.2.1. ZbBdbAttrIdT

BDB IB attributes

ZB_BDB_CommissioningMode	bdbCommissioningMode -BDB_COMMISSION_MODE_MASK (type: uint8_t, reset: no, persist: no)
ZB_BDB_JoinUsesInstallCodeKey	bdbJoinUsesInstallCodeKey - Deprecated in BDB 3.1 (type: uint8_t, reset: no, persist: no)
ZB_BDB_NodeCommissioningCapability	bdbNodeCommissioningCapability Deprecated in BDB 3.1 (type: uint8_t, reset: no, persist: no)
ZB_BDB_NodeIsOnANetwork	bdbNodeIsOnANetwork - Checks nwkExtendedPanId if non-zero Deprecated in BDB 3.1 (type: uint8_t, reset: no, persist: no)
ZB_BDB_NodeJoinLinkKeyType	bdbNodeJoinLinkKeyType -BDB_JOINLINK_KEYTYPE_FLAG, Link key with which the node was able to decrypt the network key Deprecated in BDB 3.1 (type: uint8_t, reset: yes, persist:no)
ZB_BDB_PrimaryChannelSet	bdbPrimaryChannelSet (type: uint32_t, reset: no, persist:no)
ZB_BDB_ScanDuration	bdbScanDuration (type: uint8_t, reset: no, persist: no)
ZB_BDB_SecondaryChannelSet	bdbSecondaryChannelSet (type: uint32_t, reset: no, persist: no)
ZB_BDB_TCLK_ExchangeAttempts	bdbTCLinkKeyExchangeAttempts - Deprecated in BDB 3.1, still used as a counter to keep track of number of TCLK exchange attempts made. (type: uint8_t, reset: no, persist: no)
ZB_BDB_TCLK_ExchangeAttemptsMax	bdbTCLKExchangeAttempts (type: uint8_t, reset: no, persist: no)
ZB_BDB_TCLinkKeyExchangeMethod	bdbTCLinkKeyExchangeMethod - Deprecated in BDB 3.1 (type: uint8_t / enum ZbBdbLinkKeyExchMethodT, reset:no, persist: no)
ZB_BDB_TrustCenterNodeJoinTimeout	bdbTrustCenterNodeJoinTimeout - Deprecated in BDB 3.1 (type: uint8_t, reset: no, persist: no)
ZB_BDB_TrustCenterRequiresKeyExchange	bdbTrustCenterRequireKey-Exchange. Modifies ZB_APSME_POLICY_TCLK_UPDATE_REQUIRED bit in ZB_APS_IB_ID_TRUST_CENTER_POLICY - Deprecated in BDB 3.1 (type: uint8_t, reset: no, persist:no)
ZB_BDB_AcceptNewUnsolicitedTCLinkKey	acceptNewUnsolicitedTrustCenterLinkKey (type: uint8_t, reset: no, persist: no)
ZB_BDB_AcceptNewUnsolicitedApplicationLinkKey	acceptNewUnsolicitedApplicationLinkKey (type: uint8_t, reset: no, persist: no)
ZB_BDB_vDoPrimaryScan	Boolean whether to use ZB_BDB_PrimaryChannelSet or ZB_BDB_SecondaryChannelSet (type: uint8_t, reset: no, persist: no)
ZB_BDB_FreeNetAddrBegin	(type: uint16_t, reset: no, persist: no)
ZB_BDB_FreeNetAddrCurrent	(type: uint16_t, reset: no, persist: no)
ZB_BDB_FreeNetAddrEnd	(type: uint16_t, reset: no, persist: no)
ZB_BDB_TLRssiMin	Minimum RSSI threshold for Touchlink commissioning (type: int8_t, reset: no, persist: yes)
ZB_BDB_UpdateDeviceKeyId	E.g. ZB_SEC_KEYID_NETWORK (default) or ZB_SEC_KEYID_LINK. (type: uint8_t / enum ZbSecHdrKeyIdT, reset: no, persist: yes)
ZB_BDB_JoinScanType	ZB_SCAN_TYPE_ACTIVE (default) or ZB_SCAN_TYPE_ENHANCED (type: uint8_t, reset: no, persist: yes)
ZB_BDB_PrevJoinScanType	(type: uint8_t, reset: no, persist: yes)
ZB_BDB_NlmeSyncFailNumBeforeError	Number of consecutive NLME-SYNC failures before reporting ZB_NWK_STATUS_CODE_PARENT_LINK_FAILURE (type: uint8_t, reset: no, persist: yes)
ZB_BDB_ZdoTimeout	ZDO response wait timeout in milliseconds - default is 6000 mS. (type: uint32_t, reset: no, persist: yes)
ZB_BDB_TLStealFlags	Touchlink Stealing Flags (TOUCHLINK_STEAL_xxx defines. (type: uint8_t, reset: no, persist: yes)
ZB_BDB_JoinTclkNodeDescReqDelay	(type: uint16_t, reset: no, persist: yes)
ZB_BDB_JoinTclkRequestKeyDelay	(type: uint16_t, reset: no, persist: yes)
ZB_BDB_TLKey	Touchlink preconfigured link key (type: array of uint8_t, reset: no, persist: yes)
ZB_BDB_TLKeyIndex	Touchlink key encryption algorithm key index (type: uint8_t / enum ZbBdbTouchlinkKeyIndexT, reset: no, persist: yes)
ZB_BDB_ZdoZigbeeProtocolRevision	Default = 23 (R23) (type: uint8_t, reset: no, persist: yes)
ZB_BDB_PersistTimeoutMs	Minimum delay between persistence updates (type: uint32_t, reset: no, persist: yes)
ZB_BDB_JoinAttemptsMax	Maximum number attempts to join a network. If an attempt fails, the EPID is added to a blacklist before the next attempt. (type: uint8_t, reset: no, persist: yes)
ZB_BDB_MaxConcurrentJoiners	Maximum number of concurrent joiners the coordinator supports. (type: uint8_t, reset: no, persist: yes)
ZB_BDB_Uptime	Returns the current stack uptime in milliseconds (ZbUptime). (type: uint32_t, reset: no, persist: no)
ZB_BDB_Flags	e.g. ZB_BDB_FLAG_IGNORE_COST_DURING_JOIN (type: uint32_t, reset: no, persist: no)
ZB_BDB_TC_Supports_ZD	Boolean value that indicates whether TC supports Zigbee Direct. This value is automatically discovered after joining by Match-Desc.request for ZCL_CLUSTER_ZDD. (type: uint8_t, reset: yes, persist: yes)
ZB_BDB_ZVD_SecureSessionRenegotiated	Boolean value that indicates if ZVD successfully renegotiated secure session during network join or rejoin. (type: uint8_t, reset: yes, persist: no)
ZB_BDB_TLIdentifyTime	Touchlink Indetify Time Duration - default is 7 seconds. Setting the IB to zero will disable sending the TL identify request. (type: uint16_t, reset: no, persist: no)
ZB_BDB_AppendBeaconAppendix	Boolean value that determines if the Beacon appendix will be appended to the beacons sent from an R23 device. By default, this is always true. (type: uint8_t, reset: no, persist: yes)
ZB_BDB_StartupLongDelayMs	Configurable delay added to the end of a successful ZbStartup when joining or rejoining a network. This is to give the stack time to send and receive a NWK Link Status command which is necessary for routing. Otherwise, the application may be trying to send packets right away and get failures until the first Link Status commands are exchanged. This delay is not applicable to end-devices or when forming a network. The default value is 17000 mS (17 seconds). (type: uint32_t, reset: no, persist: no)
ZB_BDB_ZclBomdReqWaitTimeoutMs	Timeout value in milliseconds to wait for a ZCL request sent to a BOMD device, via mirroring. Default is 10 minutes. (type: uint32_t, reset: no, persist: no)
ZB_BDB_ZclBomdReqQueueTimeoutMs	Timeout value in milliseconds for the ZCL request to be queued for a BOMD device on the Mirror. If this timeout expires before the BOMD polls for this message, a Default Response with status of ZCL_STATUS_TIMEOUT is returned to the requestor. The default timeout is 10 minutes minus 10 seconds (slightly less than ZB_BDB_ZclBomdReqWaitTimeoutMs). (type: uint32_t, reset: no, persist: no)
ZB_BDB_ZclSequenceNumber	API to get/set the ZCL Sequence number provided by the stack. (type: uint8_t, reset: no, persist: no)
ZB_BDB_KE_Status	Key Establishment status code from CBKE during ZbStartup. The initial value is set to ZCL_KEY_STATUS_NOT_STARTED (Exegin extension to the status codes) at the beginning of ZbStartup. It will be set to the status code returned by the KE process. It’s a uint8_t type, but it’s based on the 'enum ZbZclKeyStatusT' values. (type: uint8_t, reset: no, persist: no)
ZB_BDBC_MaxSameNetworkRetryAttempts	(type: uint8_t, reset: no, persist: no)
ZB_BDBC_MinCommissioningTime	Seconds (type: uint8_t, reset: no, persist: no)
ZB_BDBC_RecSameNetworkRetryAttempts	(type: uint8_t, reset: no, persist: no)
ZB_BDBC_TLInterPANTransIdLifetime	Seconds (type: uint8_t, reset: no, persist: no)
ZB_BDBC_TLMinStartupDelayTime	Seconds (type: uint8_t, reset: no, persist: no)
ZB_BDBC_TLRxWindowDuration	Seconds (type: uint8_t, reset: no, persist: no)
ZB_BDBC_TLScanTimeBaseDuration	Milliseconds (type: uint8_t, reset: no, persist: no)

10.2.2. ZbBdbCommissioningStatusT

bdbCommissioningStatus

ZB_BDB_COMMISS_STATUS_SUCCESS	SUCCESS - The commissioning sub-procedure was successful
ZB_BDB_COMMISS_STATUS_IN_PROGRESS	IN_PROGRESS - One of the commissioning subprocedures has started but is not yet complete
ZB_BDB_COMMISS_STATUS_NOT_AA_CAPABLE	NOT_AA_CAPABLE - The initiator is not address assignment capable during touchlink
ZB_BDB_COMMISS_STATUS_NO_NETWORK	NO_NETWORK - A network has not been found during network steering or touchlink
ZB_BDB_COMMISS_STATUS_TARGET_FAILURE	TARGET_FAILURE - A node has not joined a network when requested during touchlink
ZB_BDB_COMMISS_STATUS_FORMATION_FAILURE	FORMATION_FAILURE - A network could not be formed during network formation
ZB_BDB_COMMISS_STATUS_NO_IDENTIFY_QUERY_RESPONSE	NO_IDENTIFY_QUERY_RESPONSE - No response to an identify query command has been received during finding & binding
ZB_BDB_COMMISS_STATUS_BINDING_TABLE_FULL	BINDING_TABLE_FULL - A binding table entry could not be created due to insufficient space in the binding table during finding & binding
ZB_BDB_COMMISS_STATUS_NO_SCAN_RESPONSE	NO_SCAN_RESPONSE - No response to a scan request inter-PAN command has been received during touchlink
ZB_BDB_COMMISS_STATUS_NOT_PERMITTED	NOT_PERMITTED - A touchlink (steal) attempt was made when a node is already connected to a centralized security network or when end node attempts to form network
ZB_BDB_COMMISS_STATUS_TCLK_EX_FAILURE	TCLK_EX_FAILURE - The Trust Center link key exchange procedure has failed attempting to join a centralized security network
ZB_BDB_COMMISS_STATUS_NOT_ON_A_NETWORK	NOT_ON_A_NETWORK - A commissioning procedure was forbidden since the node was not currently on a network.
ZB_BDB_COMMISS_STATUS_ON_A_NETWORK	ON_A_NETWORK - A commissioning procedure was forbidden since the node was currently on a network.

10.2.3. ZbBdbLinkKeyExchMethodT

bdbTCLinkKeyExchangeMethod

BDB_LINKKEY_EXCHANGE_METHOD_APS	APS Request Key
BDB_LINKKEY_EXCHANGE_METHOD_CBKE	Certificate Based Key Exchange (CBKE)

10.2.4. ZbBdbTouchlinkKeyIndexT

ZbBdbTouchlinkKeyIndex

TOUCHLINK_KEY_INDEX_DEVELOPMENT	Development key
TOUCHLINK_KEY_INDEX_PRODUCTION	Production key
TOUCHLINK_KEY_INDEX_CERTIFICATION	Certification key

11. DLK utilities

#include "zigbee.dlk.h"

11.1. Description

This file defines all the public APIs used as part of ZigBee dynamic link key (DLK) implementation.

11.2. Functions

11.2.1. ZbDlkKeyNegoWithDevice

enum ZbStatusCodeT ZbDlkKeyNegoWithDevice(struct ZigBeeT *zb, uint64_t partnerAddr,
void (*callback)(enum ZbStatusCodeT status, void *arg), void *arg);

Perform dynamic link key negotiation (DLK) with a partner R23 device after the initiator has joined the network. The initiator and the responder devices can be TC or non-TC. In effect, this API can be used to negotiate both trust center and application link key.

Parameters

zb	Zigbee instance
partnerAddr	EUI64 of the responder for DLK.
callback	Callback function pointer.
cbarg	Callback argument.

Return

• ZB status code. If not ZB_STATUS_SUCCESS, then the callback will not be called.

11.3. Enumerations

11.3.1. ZbSelKeyNegoMethodT

Enumeration for selected key negotiation methods.

ZB_SEL_DLK_METHOD_RESERVED	Reserved
ZB_SEL_DLK_METHOD_C25519_AES_MMO_128	ECDHE using Curve25519 with Hash AES-MMO-128
ZB_SEL_DLK_METHOD_C25519_SHA_256	ECDHE using Curve25519 with Hash SHA-256

11.3.2. ZbSelPreSharedSecretT

Enumeration for selected PSK (Pre-shared) secret.

ZB_SEL_PSK_SYMMETRIC_AUTH_TOKEN	Symmetric authentication token negotiated using DLK
ZB_SEL_PSK_IC_KEY	Pre-configured link-key derived from installation code
ZB_SEL_PSK_PASSCODE_PAKE	Variable-length pass code (for PAKE protocols)
ZB_SEL_PSK_BASIC_ACCESS_KEY	Basic Access Key
ZB_SEL_PSK_ADMIN_ACCESS_KEY	Administrative Access Key
ZB_SEL_PSK_ANON_WELL_KNOWN_SECRET	Well-known secret - 'ZigBeeAlliance18'

12. Zigbee message filters

#include "zigbee.filter.h"

12.1. Functions

12.1.1. ZbMsgFilterRegister

struct ZbMsgFilterT * ZbMsgFilterRegister(struct ZigBeeT *zb, uint32_t mask, uint8_t prio,
enum zb_msg_filter_rc (*callback)(struct ZigBeeT *zb, uint32_t id, void *msg, void *cbarg), void *arg);

Register message filter with the stack.

Parameters

zb	Pointer to Zigbee stack instance
mask	Message filter mask flag
prio	Message filter priority
callback	Callback function invoked after message matching filter is received
arg	Callback function argument

Return

• Undocumented

12.1.2. ZbMsgFilterRemove

void ZbMsgFilterRemove(struct ZigBeeT *zb, struct ZbMsgFilterT *filter);

Removes the given message filter from the stack.

Parameters

zb	Pointer to Zigbee stack instance

Return

• Undocumented

12.2. Enumerations

12.2.1. zb_msg_filter_rc

Message filter callback return values. Used for the return codes with the callbacks for ZbMsgFilterRegister, ZbApsFilterEndpointAdd, etc.

ZB_MSG_CONTINUE	Continue processing any further filter callbacks.
ZB_MSG_DISCARD	Stop processing further filter callbacks.

12.3. Structures

12.3.1. ZbMsgStackEventT

A message that is sent if the device is an end-device and it has received an NLME-NETWORK-STATUS.indication with the PARENT_LINK_FAILURE status set. Outside of testing 18.4.* TP/R23/ZDO/APC-*, the application should attempt to rejoin the network using the ZbStartupRejoin() API call at its convenience.

Parameters

enum ZbMsgStackEventTypeT type	Enumeration of different stack event message type, sent to higher layer.
unsigned int val	Depends on message type. E.g. enum ZbStatusCodeT status.

13. Zigbee utilities

#include "zigbee.h"

13.1. Description

This file groups global/external definitions from all the layer specific header files for example, aps, nwk, zdo etc… into a single place, so that one can just include zigbee.h for all the global definitions eliminating the header file inclusion clutter from source files.

13.2. Functions

13.2.1. ZbChangeExtAddr

 void ZbChangeExtAddr(struct ZigBeeT *zb, uint64_t extAddr);

Change extended address of the stack instance

Parameters

zb	Pointer to Zigbee stack instance

Return

• Undocumented

13.2.2. ZbCheckTime

unsigned int ZbCheckTime(struct ZigBeeT *zb);

Returns the length of time (in milliseconds) until the next scheduled timer will elapse, or UINT_MAX if there are no scheduled timers.

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns Length of time on success, 0 on failure

13.2.3. ZbDestroy

void ZbDestroy(struct ZigBeeT *zb);

Deallocates a Zigbee stack instance.

None Return

• Undocumented

13.2.4. ZbDestroyWithCb

enum ZbStatusCodeT ZbDestroyWithCb(struct ZigBeeT *zb, void (*callback)(void *arg), void *arg);

Deallocates a Zigbee stack instance and save callback to application structure

Parameters

zb	Pointer to Zigbee stack instance
callback	Callback function
arg	Callback argument

Return

• Returns ZB_STATUS_SUCCESS on success, other status code on failure

13.2.5. ZbExtendedAddress

uint64_t ZbExtendedAddress(struct ZigBeeT *zb);

Returns the Extended address of the Zigbee stack.

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns extended address

13.2.6. ZbHeapAvailable

unsigned long ZbHeapAvailable(struct ZigBeeT *zb);

Current size of memory available in the zigbee stack heap

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns the amount of memory available in the zigbee stack heap, or 0 if unknown or unbounded

13.2.7. ZbHeapHighWaterMark

unsigned long ZbHeapHighWaterMark(struct ZigBeeT *zb);

Zigbee memory heap high-water mark. Useful during testing to determine maximum amount of memory consumed from total heap size.

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns the worst-case heap usage (high-water mark)

13.2.8. ZbHeapUsed

unsigned long ZbHeapUsed(struct ZigBeeT *zb);

Current size of memory allocated from the zigbee stack heap

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns the memory allocated from the zigbee stack heap

13.3. ZbIfAttach

bool ZbIfAttach(struct ZigBeeT *zb, struct WpanPublicT *dev);

Attaches an IEEE 802.15.4 device driver to the ZigBee stack. Uses the link pointers within the device structure for linking.

zb	Pointer to Zigbee stack instance
dev	Pointer to wpan device

Return

• Returns true on success, false otherwise

13.4. ZbIfDetach

void ZbIfDetach(struct ZigBeeT *zb, struct WpanPublicT *dev);

Detaches an IEEE 802.15.4 device driver from the ZigBee stack.

Parameters

zb	Pointer to Zigbee stack instance

Return

• Undocumented

13.5. ZbInit

struct ZigBeeT * ZbInit(uint64_t extAddr, struct ZbInitTblSizesT *tblSizes, struct
ZbInitSetLoggingT *setLogging);

This is called to create a new Zigbee stack instance. One of the parameters provided is an optional pointer to a struct that defines the sizes of some of the tables within the stack (e.g. NNT, Routing Table, Security Keys Table). This lets the application developer tailor the memory usage depending on the type of device being developed.

Parameters

extAddr	EUI to be assigned to this Zigbee stack instance.
tblSizes	Optional pointer to a struct ZbInitTblSizesT data structure defining some of the table sizes to be allocated.
setLogging	Optional pointer to a struct ZbInitSetLoggingT data structure defining the log mask and callback to call to print log messages.

Return

• Pointer to Zigbee stack instance, or NULL if there was a problem (for example, not enough memory)

13.6. ZbLeaveReq

enum ZbStatusCodeT ZbLeaveReq(struct ZigBeeT *zb, void (*callback)(struct ZbNlmeLeaveConfT *conf, void *arg), void *cbarg);

Send a leave request to the stack

Parameters

zb	Pointer to Zigbee stack instance
callback	Callback function
cbarg	Callback argument

Return

• Returns ZB_STATUS_SUCCESS on success, other status code on failure

13.7. ZbPersistGet

unsigned int ZbPersistGet(struct ZigBeeT *zb, uint8_t *buf, unsigned int maxlen);

Get the stack persistence data and write it to the buffer provided by buf. If buf is NULL and maxlen is zero, this function determines the buffer size required to save the persistence data. Use ZbStartupPersist to restore the persistence data to the stack and restart the zigbee stack.

Parameters

zb	Pointer to Zigbee stack instance
buf	Pointer to memory to write persistence data
maxlen	Max length of persistence data

Return

• Returns length of persistence data

13.8. ZbPersistNotifyRegister

bool ZbPersistNotifyRegister(struct ZigBeeT *zb, void (*callback)(struct ZigBeeT *zb, void *cbarg), void *cbarg);

Configure the persistence callback that tells the application when important stack parameters have changed and should be saved.

zb	Pointer to Zigbee stack instance
callback	Callback function
cbarg	Callback argument

Return

• True if callback was registered, false otherwise.

13.9. ZbPortStackEventFd

int ZbPortStackEventFd(struct ZigBeeT *zb);

Called to get the file descriptor to be used to wake-up the stack thread calling ZbTimerWork if a stack event needs to be processed. This is only required in multi-threaded environments. Without this event, it is possible for a user thread to initiate a stack function which does not activate the MAC layer, which in turn would wake up the stack thread.

Parameters

None Return

• Undocumented

13.10. ZbReset

void ZbReset(struct ZigBeeT *zb);

Helper function to perform an APS and NWK reset

Parameters

None Return

• Undocumented

13.11. ZbShortAddress

uint16_t ZbShortAddress(struct ZigBeeT *zb);

Returns the Short address of the Zigbee stack.

zb	Pointer to Zigbee stack instance

Return

• Returns short address

13.12. ZbShutdown

void ZbShutdown(struct ZigBeeT *zb);

This API moves the stack to shutdown mode, used in case of a sleepy end device to conserve power.

Parameters

None Return

• Undocumented

13.13. ZbStateGet

unsigned int ZbStateGet(struct ZigBeeT *zb, uint8_t *buf, unsigned int maxlen);

Same as ZbPersistGet, but saves additional more dynamic data such as routing tables. Use the same

ZbStartupPersist to restore the persistence data to the stack and to restart the zigbee stack.

Parameters

zb	Pointer to Zigbee stack instance
buf	Pointer to memory to write persistence and additional data
maxlen	Max length of persistence and additional data

Return

• Returns length of persistence and additional data

13.14. ZbTimeoutRemaining

unsigned int ZbTimeoutRemaining(ZbUptimeT now, ZbUptimeT expire_time);

Zigbee timeout remaining function.

now	Current time
expire_time	time of timeout expiry

Return

• Returns 0 if now >= expire_time, difference in milliseconds between now and timeout if now < expire_time.

13.15. ZbTimerAlloc

struct ZbTimerT * ZbTimerAlloc(struct ZigBeeT *zb, void (*callback)(struct ZigBeeT *zb, void *cb_arg), void *arg);

Creates a ZigBee timer structure.

Parameters

zb	Pointer to Zigbee stack instance
callback	Callback function
arg	Callback argument

Return

• Zigbee timer structure

13.16. ZbTimerChangeCallback

void ZbTimerChangeCallback(struct ZbTimerT *timer, void (*callback)(struct ZigBeeT *zb, void *cb_arg), void *arg);

Changes callback function for the specified timer, without the need to free and allocate a new timer.

Parameters

timer	Pointer to Zigbee timer structure
callback	Callback function

Return

• Undocumented

13.17. ZbTimerFree

void ZbTimerFree(struct ZbTimerT *timer);

Free a timer.

Parameters

None Return

• Undocumented

13.18. ZbTimerRemaining

unsigned int ZbTimerRemaining(struct ZbTimerT *timer);

Returns time remaining in ms for a timer.

Parameters

timer

Pointer to Zigbee timer structure

Return

• Time remaining in ms as an unsigned int

13.19. ZbTimerReset

void ZbTimerReset(struct ZbTimerT *timer, unsigned int timeout);

Reset and schedule a ZigBee timer.

Parameters

timer

Pointer to Zigbee timer structure

Return

• Undocumented

13.20. ZbTimerRunning

bool ZbTimerRunning(struct ZbTimerT *timer);

Checks if the specified timer is active.

timer

Callback argument

Return

• True if the specified timer is active

13.21. ZbTimerStop

void ZbTimerStop(struct ZbTimerT *timer);

Stop a timer before it expires.

Parameters

None Return

• Undocumented

13.22. ZbTimerWork

void ZbTimerWork(struct ZigBeeT *zb);

Called periodically to run the stack.

Parameters

None Return

• Undocumented

13.23. ZbWakeupCallbackConfig

void ZbWakeupCallbackConfig(struct ZigBeeT *zb, void (*wakeup_cb)(void));

Configure a callback to activate the application if there is a stack event to process. Not required by all stack ports.

Parameters

zb	Pointer to Zigbee stack instance

Return

• Undocumented

13.24. ZbZclBasicPostAlarm

bool ZbZclBasicPostAlarm(struct ZigBeeT *zb, uint8_t endpoint, uint8_t alarm_code);

Post an alarm code to the Basic Cluster.

Parameters

zb	Pointer to Zigbee stack instance
endpoint	Endpoint of basic cluster
alarm_code	Alarm code

Return

• Returns true on success, false otherwise

13.25. ZbZclBasicReadDirect

enum ZclStatusCodeT ZbZclBasicReadDirect(struct ZigBeeT *zb, uint16_t attrId, void *buf, unsigned int max_len);

Read a Basic Server attribute

Parameters

zb	Zigbee instance
attrId	The attribute Id to read
buf	Pointer to the attribute data, in the ZCL defined format.
len	Maximum length of the attribute data. May exceed the length of the particular attribute.

Return

• ZCL status code

13.26. ZbZclBasicServerConfigDefaults

void ZbZclBasicServerConfigDefaults(struct ZigBeeT *zb, const struct ZbZclBasicServerDefaults *defaults);

Configure the default ZCL Basic Server attribute values. The Basic Server is integral to the stack in order for the attribute values to be made "global" and shared between all Basic Server instances on all endpoints. This should be

called after calling ZbInit and before creating any ZCL endpoints.

Parameters

zb	Zigbee instance

Return

• Undocumented

13.27. ZbZclBasicWriteDirect

enum ZclStatusCodeT ZbZclBasicWriteDirect(struct ZigBeeT *zb, uint16_t attrId, const void *buf, unsigned int max_len);

Write to a Basic Server attribute

Parameters

zb	Zigbee instance
attrId	The attribute Id to write
buf	Pointer to the attribute data, in the ZCL defined format.
len	Maximum length of the attribute data. May exceed the length of the particular attribute.

Return

• ZCL status code

14. Structures

14.1. ZbChannelListEntryT

A single channel list entry. It includes the channel page and channel mask. It is used within struct ZbChannelListT when describing a list of channels masks, or on its own in some cases.

Parameters

uint8_t page	The 802.15.4 Channel Page (e.g. 2.4 GHz O-QPSK = Page 0)
uint32_t channelMask	The 32-bit Channel Mask. The 5 MSB Channel Page bits are not used and should be set to 0. The 27 LSB define the channel(s) supported or to be used during commissioning.

14.2. ZbChannelListT

The Channel list structure. It includes a list of struct ZbChannelListEntryT entries; one for each channel page supported or to be used during commissioning.

Parameters

uint8_t count	Number of channel masks in 'list'. Maximum is ZB_CHANNEL_LIST_NUM_MAX.
struct ZbChannelListEntryT list	The list of Channel Pages and Masks.

14.3. ZbInitSetLoggingT

Same parameters as ZbSetLogging takes. Allows debug log output as stack is being initialized.

Parameters

uint32_t mask	e.g. ZB_LOG_MASK_LEVEL_2
func (callback function pointer)	void (*func)(struct ZigBeeT *zb, uint32_t mask, const char *hdr, const char *fmt, va_list argptr) Callback function to print log messages.

14.4. ZbInitTblSizesT

A pointer to this struct type is passed to ZbInit to define the various ZigBee tables used in the stack. If the pointer to ZbInit is NULL, the default sizes are used.

Parameters

void *heapPtr	Pointer to memory to use for stack’s run-time heap. Size equals heapSz bytes. If heapSz is zero, set this to NULL and the buffer will be allocated using ZbMalloc(). If the stack is built with CONFIG_ZB_ALLOC_STATIC, then heapPtr and heapSz must be non-zero and provided by the application.
unsigned int heapSz	Size of memory buffer provided by heapPtr. If heapSz is zero, then a default value of 32 kB for FFD or 16 kB for RFD is chosen, and memory will be allocated through ZbMalloc(). An FFD vs RFD type of stack is controlled by the CONFIG_ZB_ENDNODE when the stack is built.
unsigned int nwkNeighborTblSz	Network Neighbor Table (NNT) number of entries. Default is 64.
unsigned int nwkRouteTblSz	Default is 32.
unsigned int nwkAddrMapTblSz	Default is 32.
unsigned int nwkBttSz	Default is 32.
unsigned int nwkRReqSz	Default is 16.
unsigned int apsPeerLinkKeyTblSz

14.5. ZbJoinerTLVsT

TLV structure the application can use to include TLVs in certain packet payloads during the commissioning process.

Parameters

uint8_t length	Length of the TLV buffer 'buf'. Maximum length is ZB_JOINER_TLVS_MAX_SIZE.
uint8_t buf	Buffer containing the TLV data. The data is in the format as would appear over-the-air (i.e. binary blob format)

14.6. ZbZclBasicServerDefaults

This data structure is used to configure the default attribute values for the basic server. All values are in ZCL data format (that is to say, strings are prefixed with the length byte)

Parameters

uint8_t app_version	ZCL_BASIC_ATTR_APP_VERSION
uint8_t stack_version	ZCL_BASIC_ATTR_STACK_VERSION
uint8_t hw_version	ZCL_BASIC_ATTR_HARDWARE_VERSION
uint8_t mfr_name	ZCL_BASIC_ATTR_MFR_NAME (First byte length)
uint8_t model_name	ZCL_BASIC_ATTR_MODEL_NAME (First byte length)
uint8_t date_code	ZCL_BASIC_ATTR_DATE_CODE (First byte length)
uint8_t power_source	ZCL_BASIC_ATTR_POWER_SOURCE (e.g. ZCL_BASIC_POWER_UNKNOWN)
uint8_t sw_build_id	ZCL_BASIC_ATTR_SW_BUILD_ID (First byte length)

15. Hash Utilities

#include "zigbee.hash.h"

15.1. Description

This file defines the Exegin specific ZigBee AES Hash structure and also provides the declaration of Hashing APIs. Customers with their own hashing implementation can simply replace this file with their variant. In effect, it helps to plug customer specific hashing implementation into ZSDK stack.

16. NWK Layer

#include "zigbee.nwk.h"

16.1. Functions

16.1.1. ZbNlmeBcnSurveyReq

enum ZbStatusCodeT ZbNlmeBcnSurveyReq(struct ZigBeeT *zb, struct ZbNlmeBcnSurveyReqT *req, void (*callback)(struct ZbNlmeBcnSurveyConfT *conf,
void *cbarg), void *cbarg);

Starts the NLME beacon survey procedure and returns the survey results as part of the NLME-BEACONSURVEY.confirm primitive.

Parameters

zb	ZigBee stack structure.
req	Beacon survey request structure.
callback	Callback function pointer.

Return

• Undocumented

16.1.2. ZbNlmeDirectJoinReq

void ZbNlmeDirectJoinReq(struct ZigBeeT *zb, struct ZbNlmeDirectJoinReqT *directJoinReqPtr, struct ZbNlmeDirectJoinConfT *directJoinConfPtr);

NLME-DIRECT-JOIN.request

Parameters

zb	Pointer to Zigbee stack instance
directJoinReqPtr	Pointer to NLME-DIRECT-JOIN.request data structure

Return

• Undocumented

16.1.3. ZbNlmeEdScanReq

enum ZbStatusCodeT ZbNlmeEdScanReq(struct ZigBeeT *zb, struct ZbNlmeEdScanReqT *req, void (*callback)
(struct ZbNlmeEdScanConfT *scanConf, void *arg), void *cbarg);

NLME-ED-SCAN.request

Parameters

zb	Pointer to Zigbee stack instance
req	Pointer to NLME-ED-SCAN.request data structure
callback	Callback function
cbarg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.4. ZbNlmeGetInterface

void ZbNlmeGetInterface(struct ZigBeeT *zb, struct ZbNlmeGetInterfaceReqT *req, struct ZbNlmeGetInterfaceConfT *conf);

NLME-GET-INTERFACE.request

Parameters

zb	Pointer to Zigbee stack instance
req	Pointer to NLME-GET-INTERFACE.request data structure

Return

• Undocumented

16.1.5. ZbNlmeGetReq

void ZbNlmeGetReq(struct ZigBeeT *zb, struct ZbNlmeGetReqT *getReqPtr, struct ZbNlmeGetConfT *getConfPtr);

NLME-GET.request

Parameters

zb	Pointer to Zigbee stack instance
getReqPtr	Pointer to NLME-GET.request data structure

Return

• Undocumented

16.1.6. ZbNlmeIeeeJoiningListClear

void ZbNlmeIeeeJoiningListClear(struct ZigBeeT *zb);

Clear IEEE joining list

Parameters

None Return

• Undocumented

16.1.7. ZbNlmeIeeeJoiningListRemove

bool ZbNlmeIeeeJoiningListRemove(struct ZigBeeT *zb, uint64_t extAddr);

Remove extended address from IEEE joining list

Parameters

zb	Pointer to Zigbee stack instance
extAddr	Extended address to remove

Return

• Returns true on success, or false otherwise

16.1.8. ZbNlmeJoinPolicyTimeoutRefresh

void ZbNlmeJoinPolicyTimeoutRefresh(struct ZigBeeT *zb);

Refresh join policy timer

Parameters

None Return

• Undocumented

16.1.9. ZbNlmeJoinReq

enum ZbStatusCodeT ZbNlmeJoinReq(struct ZigBeeT *zb, struct ZbNlmeJoinReqT *joinReqPtr, void (*callback)(struct ZbNlmeJoinConfT *joinConf, void *arg),
void *cbarg);

NLME-JOIN.request

Parameters

zb	Pointer to Zigbee stack instance
joinReqPtr	Pointer to NLME-JOIN.request data structure
callback	Callback function
cbarg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.10. ZbNlmeJoiningPolicyConfigure

bool ZbNlmeJoiningPolicyConfigure(struct ZigBeeT *zb, enum WpanJoinPolicyT policy, uint64_t *extAddrList, 
unsigned int numExtAddr, uint8_t *updateIdOverride);

External API to configure the joining policy and IEEE joining list. Should only be called by the Coordinator application. Router and End Devices applications should not be calling this, but rather obtain these parameters from the Coordinator through ZDP commands.

Parameters

zb	Pointer to Zigbee stack instance
policy	New policy value
extAddrList	Pointer to extended address list
numExtAddr	Extended address index
updateIdOverride	Optional update ID to override old value intead of incrementing

Return

• Returns true on success, or false otherwise

16.1.11. ZbNlmeJoiningPolicyGet

enum WpanJoinPolicyT ZbNlmeJoiningPolicyGet(struct ZigBeeT *zb);

Get the value of ZB_NWK_NIB_ID_JoiningPolicy

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns joining policy enumeration value

16.1.12. ZbNlmeLeaveReq

enum ZbStatusCodeT ZbNlmeLeaveReq(struct ZigBeeT *zb, struct ZbNlmeLeaveReqT *leaveReqPtr, void (*callback)
(struct ZbNlmeLeaveConfT *leaveConfPtr, void *arg), void *cbarg);

NLME-LEAVE.request

Parameters

zb	Pointer to Zigbee stack instance
leaveReqPtr	Pointer to NLME-LEAVE.request data structure
callback	Callback function
cbarg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.13. ZbNlmeNetDiscReq

enum ZbStatusCodeT ZbNlmeNetDiscReq(struct ZigBeeT *zb, struct ZbNlmeNetDiscReqT *req, void (*callback)
(struct ZbNlmeNetDiscConfT *conf, void *cbarg), void *cbarg);

NLME-NETWORK-DISCOVERY.request

Parameters

zb	Pointer to Zigbee stack instance
req	Pointer to NLME-NETWORK-DISCOVERY.request data structure
callback	Callback function
cbarg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.14. ZbNlmeNetFormReq

enum ZbStatusCodeT ZbNlmeNetFormReq(struct ZigBeeT *zb, struct ZbNlmeNetFormReqT *req, void (*callback) 
(struct ZbNlmeNetFormConfT *formConf, void *arg),   void *cbarg);

NLME-NETWORK-FORMATION.request

Parameters

zb	Pointer to Zigbee stack instance
req	Pointer to NLME-NETWORK-FORMATION.request data structure
callback	Callback function
cbarg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.15. ZbNlmePanIdUpdateReq

void ZbNlmePanIdUpdateReq(struct ZigBeeT *zb, struct ZbNlmePanIdUpdateReqT *req, struct ZbNlmePanIdUpdateConfT *conf);

Sends a NWK update command to switch the NWK PanId.

Parameters

zb	ZigBee stack structure.
req	PanId update request structure.

Return

• Undocumented

16.1.16. ZbNlmePermitJoinReq

void ZbNlmePermitJoinReq(struct ZigBeeT *zb, struct ZbNlmePermitJoinReqT *permitReq, struct ZbNlmePermitJoinConfT *permitConf);

NLME-PERMIT-JOIN.request

Parameters

zb	Pointer to Zigbee stack instance
permitReq	Pointer to NLME-PERMIT-JOIN.request data structure

Return

• Undocumented

16.1.17. ZbNlmeResetReq

void ZbNlmeResetReq(struct ZigBeeT *zb, struct ZbNlmeResetReqT *resetReqPtr, struct ZbNlmeResetConfT *resetConfPtr);

NLME-RESET.request

Parameters

zb	Pointer to Zigbee stack instance
resetReqPtr	Pointer to NLME-RESET.request data structure

Return

• Undocumented

16.1.18. ZbNlmeRouteDiscReq

enum ZbStatusCodeT ZbNlmeRouteDiscReq(struct ZigBeeT *zb, struct ZbNlmeRouteDiscReqT *routeDiscReqPtr, void (*callback)
(struct ZbNlmeRouteDiscConfT *discConf, void *cbarg), void *arg);

NLME-ROUTE-DISCOVERY.request

Parameters

zb	Pointer to Zigbee stack instance
routeDiscReqPtr	Pointer to NLME-ROUTE-DISCOVERY.request data structure
callback	Callback function
arg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.19. ZbNlmeSetInterface

void ZbNlmeSetInterface(struct ZigBeeT *zb, struct ZbNlmeSetInterfaceReqT *req, struct ZbNlmeSetInterfaceConfT *conf);

NLME-SET-INTERFACE.request

Parameters

zb	Pointer to Zigbee stack instance
req	Pointer to NLME-SET-INTERFACE.request data structure

Return

• Undocumented

16.1.20. ZbNlmeSetReq

void ZbNlmeSetReq(struct ZigBeeT *zb, struct ZbNlmeSetReqT *setReqPtr, struct ZbNlmeSetConfT *setConfPtr);

NLME-SET.request

Parameters

zb	Pointer to Zigbee stack instance
setReqPtr	Pointer to NLME-SET.request data structure

Return

• Undocumented

16.1.21. ZbNlmeStartRouterReq

void ZbNlmeStartRouterReq(struct ZigBeeT *zb, struct ZbNlmeStartRouterReqT *req, struct ZbNlmeStartRouterConfT *conf);

NLME-START-ROUTER.request Parameters

zb	Pointer to Zigbee stack instance
req	Pointer to NLME-START-ROUTER.request data structure

Return

• Undocumented

16.1.22. ZbNlmeSyncReq

enum ZbStatusCodeT ZbNlmeSyncReq(struct ZigBeeT *zb, struct ZbNlmeSyncReqT *syncReqPtr, void (*callback)
(struct ZbNlmeSyncConfT *syncConfPtr, void *arg), void *arg);

NLME-SYNC.request

Parameters

zb	Pointer to Zigbee stack instance
syncReqPtr	Pointer to NLME-SYNC.request data structure
callback	Callback function
arg	Callback function argument

Return

• Returns ZB_NWK_STATUS_SUCCESS on success, or other ZbStatusCodeT on failure

16.1.23. ZbNwkAddrLookupExt

uint64_t ZbNwkAddrLookupExt(struct ZigBeeT *zb, uint16_t nwkAddr);

Look up extended address from network address

Parameters

zb	Zigbee instance
nwkAddr	Network address

Return

• Returns extended address that corresponds to the network address if known, otherwise returns 0.

16.1.24. ZbNwkAddrLookupNwk

uint16_t ZbNwkAddrLookupNwk(struct ZigBeeT *zb, uint64_t extAddr);

Look up network address from extended address

Parameters

zb	Zigbee instance
extAddr	Extended address

Return

• Returns network address that corresponds to the extended address if known, otherwise returns ZB_NWK_ADDR_UNDEFINED.

16.1.25. ZbNwkAddrSetNextChildAddr

void ZbNwkAddrSetNextChildAddr(struct ZigBeeT *zb, uint16_t nextChildAddr);

Set network address of next child to known value rather than stochastically assigned address.

Parameters

zb	Zigbee instance

Return

• Undocumented

16.1.26. ZbNwkAddrStoreMap

bool ZbNwkAddrStoreMap(struct ZigBeeT *zb, uint16_t nwkAddr, uint64_t extAddr, bool resolve_now);

Store new address mapping

Parameters

zb	Zigbee instance
nwkAddr	New network address
extAddr	New extended address
resolve_now	Boolean that determines if address conflict resolution should be done now or after a delay

Return

• Returns true on success, or false otherwise

16.1.27. ZbNwkClearActiveKey

bool ZbNwkClearActiveKey(struct ZigBeeT *zb);

Clear the active key sequence number

Parameters

zb	Zigbee instance

Return

• Returns true on success, or false otherwise

16.1.28. ZbNwkCommissioningConfig

bool ZbNwkCommissioningConfig(struct ZigBeeT *zb, struct ZbNwkCommissioningInfo *commission_info);

Configures the MAC interface to be able to send and receive commissioning InterPAN packets. This API is provided so the stack does not need to expose the MLME-SET API. This should be called before the stack has been started (that is to say ZbStartup).

Parameters

zb	Zigbee instance.
commission_info	Pointer to commissioning configuration data structure.

Return

• True if configuration was successfully applied, false otherwise.

16.1.29. ZbNwkFastPollRelease

bool ZbNwkFastPollRelease(struct ZigBeeT *zb, struct nwk_fastpoll_entry_t *handle);

Release a fast polling request. If this is the last fast polling request, then fast polling is stopped.

Parameters

zb	Zigbee instance
entry	Fast polling entry pointer (handle) returned by ZbNwkFastPollRequest

Return

• True if found and removed, false otherwise.

16.1.30. ZbNwkFastPollRequestWithDesc

struct nwk_fastpoll_entry_t * ZbNwkFastPollRequestWithDesc(struct ZigBeeT *zb, unsigned int delay, unsigned int timeout, const char *desc);

Make the stack begin (or continue) fast polling. Fast polling period is defined by ZB_NWK_NIB_ID_FastPollPeriod.

Parameters

zb	Zigbee instance
delay	Delay in milliseconds before sending the first NLME-SYNC (e.g. ZB_NWK_SYNC_DEFAULT_DELAY_MS)
timeout	Timeout in milliseconds for this fast polling interval. If 0, then interval is indefinite and only stopped by calling ZbNwkFastPollRelease
desc	Debug string indicating where this fast polling instance was started.

Return

• Fast polling entry pointer, to be used as a handle to track this polling request.

16.1.31. ZbNwkFastPollResourceCount

unsigned int ZbNwkFastPollResourceCount(struct ZigBeeT *zb);

Get the current number of fast polling requests to the stack.

Parameters

zb	Zigbee instance

Return

• Number of outstanding fast polling requests.

16.1.32. ZbNwkGet

enum ZbStatusCodeT ZbNwkGet(struct ZigBeeT *zb, enum ZbNwkNibAttrIdT attrId, void *attrPtr, unsigned int attrSz);

Performs an NLME-GET.request for an attribute with fixed length data, usually uint8_t, uint16_t, uint32_t, or uint64_t data types.

Parameters

zb	Zigbee instance
attrId	NWK Attribute Id to get
attrPtr	Pointer to memory to write attribute data
attrSz	Size of the attribute data

Return

• Zigbee status code (e.g. ZB_STATUS_SUCCESS or ZB_NWK_STATUS_INVALID_PARAMETER)

16.1.33. ZbNwkGetActiveKey

bool ZbNwkGetActiveKey(struct ZigBeeT *zb, struct ZbNwkSecMaterialT *active_key);

Searches the nwkSecurityMaterialSet NIB attribute for a valid entry with a sequence number matching the active key sequence number. If found, the key will be copied into the out buffer and out will be returned.

Parameters

zb	Zigbee instance
active_key	Pointer to memory to write security material

Return

• Returns true on success, or false otherwise

16.1.34. ZbNwkGetArray

enum ZbStatusCodeT ZbNwkGetArray(struct ZigBeeT *zb, enum ZbNwkNibAttrIdT attrId, void *attrPtr, unsigned int *attrSz);

Performs an NLME-GET.request for an attribute with variable length data.

Parameters

zb	Zigbee instance
attrId	NWK Attribute Id to get
attrPtr	Pointer to memory to write attribute data
attrSz	Pointer to integer that reprsents maximum size of data that can be written to attrPtr. On function return, it contains the size of data actually written.

Return

• Zigbee status code (for example, ZB_STATUS_SUCCESS or ZB_NWK_STATUS_INVALID_PARAMETER)

16.1.35. ZbNwkGetIndex

enum ZbStatusCodeT ZbNwkGetIndex(struct ZigBeeT *zb, enum ZbNwkNibAttrIdT attrId, void *attrPtr, unsigned int attrSz, unsigned int attrIndex);

Performs an NLME-GET.request for an attribute containing an array of values using an index.

Parameters

zb	Zigbee instance
attrId	NWK Attribute Id to set
attrPtr	Pointer to memory to write attribute data
attrSz	Size of attrPtr
attrIndex	Index of value

Return

• Zigbee status code (for example, ZB_STATUS_SUCCESS or ZB_NWK_STATUS_INVALID_PARAMETER)

16.1.36. ZbNwkGetSecMaterial

bool ZbNwkGetSecMaterial(struct ZigBeeT *zb, uint8_t keySeqno, struct ZbNwkSecMaterialT *material);

Gets a network key for a given sequence number. Will also return the frame counter if requested. If extAddr is 0, then the outgoing frame counter will be written to frameCounterPtr. Otherwise, if extAddr is non-zero, the incoming frame counter corresponding to extAddr will be written to frameCounterPtr;

Parameters

zb	Zigbee instance
keySeqno	Sequence number
material	Pointer to memory to write security material

Return

• Returns true on success, or false otherwise

16.1.37. ZbNwkIeeeJoiningListEnabled

bool ZbNwkIeeeJoiningListEnabled(struct ZigBeeT *zb);

Check if join policy is set to WPAN_JOIN_POLICY_IEEELIST

Parameters

zb	Pointer to Zigbee stack instance

Return

• Returns true on success, or false otherwise

16.1.38. ZbNwkIfGetTxPower

bool ZbNwkIfGetTxPower(struct ZigBeeT *zb, const char *name, int8_t *tx_power);

Gets the transmit power of an interface.

Parameters

zb	ZigBee stack structure
name	Name of the interface
tx_power	Pointer to hold returned tx power value

Return

• Returns true on success, or false otherwise

16.1.39. ZbNwkIfSetTxPower

bool ZbNwkIfSetTxPower(struct ZigBeeT *zb, const char *name, int8_t tx_power);

Sets the transmit power of an interface.

Parameters

zb	ZigBee stack structure
name	Name of the interface
tx_power	New tx power value

Return

• Returns true on success, or false otherwise

16.1.40. ZbNwkNntGetZdExtAddr

uint64_t ZbNwkNntGetZdExtAddr(struct ZigBeeT *zb);

Get the EUI-64 of the connected remote Zigbee Direct device, if applicable and available.

Parameters

zb	Zigbee instance

Return

• EUI-64 of the connected remote Zigbee Direct device, or 0 if none found.

16.1.41. ZbNwkSendEdkaReq

bool ZbNwkSendEdkaReq(struct ZigBeeT *zb, void (*callback)(enum ZbStatusCodeT status, void *arg), void *arg);

Called by the application to manually send the End Device Timeout Request Command.

ZB_NWK_NIB_ID_DisablePeriodicTimers must be first set to 1, to disable the automatic sending of these commands. The application may want the periodic timers to be disabled, so it has more control of when packets are being transmit from the SED, in order to have fine control of battery power usage.

Parameters

zb

ZigBee stack structure.

callback

Callback function pointer. This callback is called after the transmission of the End Device Timeout Request Command, and returns the status code for that transmission. It lets the application know if the command was able to be sent to the parent or not. For instance, a status of ZB_STATUS_SUCCESS (0x00) means command was received by the parent, and a status of ZB_WPAN_STATUS_NO_ACK (0xe9) means the command was not.

Return

• Undocumented

16.1.42. ZbNwkSendLinkPowerDeltaNotify

bool ZbNwkSendLinkPowerDeltaNotify(struct ZigBeeT *zb);

Network Link power delta notify.

Parameters

zb	ZigBee stack structure

Return

• Returns true on success, or false otherwise

16.1.43. ZbNwkSendLinkPowerDeltaReq

bool ZbNwkSendLinkPowerDeltaReq(struct ZigBeeT *zb);

Network Link power delta request.

Parameters

zb	ZigBee stack structure

Return

• Returns true on success, or false otherwise

16.1.44. ZbNwkSet

enum ZbStatusCodeT ZbNwkSet(struct ZigBeeT *zb, enum ZbNwkNibAttrIdT attrId, void *attrPtr, unsigned int attrSz);

Performs an NLME-SET.request for an attribute.

Parameters

zb	Zigbee instance
attrId	NWK Attribute Id to set
attrPtr	Pointer to new attribute data
attrSz	Size of new attribute data

Return

• Zigbee Status Code (for example, ZB_STATUS_SUCCESS or ZB_NWK_STATUS_INVALID_PARAMETER)

16.1.45. ZbNwkSetActiveKey

bool ZbNwkSetActiveKey(struct ZigBeeT *zb, struct ZbNwkSecMaterialT *active_key);

Perform an APSME-ADD-KEY.request and update the active key sequence number

Parameters

zb	Zigbee instance
active_key	Security material used for the request

Return

• Returns true on success, or false otherwise

16.1.46. ZbNwkSetFrameCounter

bool ZbNwkSetFrameCounter(struct ZigBeeT *zb, uint8_t keySeqno, uint64_t srcAddr, uint32_t newFrameCount);

Inserts or updates a frame counter in a given material set. If srcAddr is 0, or our local extended address then this call will update the outgoing frame counter. Otherwise this call will update (or create) an incoming frame counter. This function will compare the new frame counter against the existing one (if found). If the new value of the frame counter is stale then the update will be rejected and this function will return false. Otherwise, the update will always succeed (with a possible LRU eviction if the table is full). However, due to some known buggy devices, frame counter resets have been observed out in the wild. Therefore, stale frame counters will be accepted into the table subject to rate limiting and cooldown policies (controlled by the nwkFrameCounterCooldown NIB attribute).

Parameters

zb	Zigbee instance
keySeqno	Key sequence number
srcAddr	Extended address
newFrameCount	New frame counter

Return

• Returns true on success, or false otherwise

16.1.47. ZbNwkSetIndex

enum ZbStatusCodeT ZbNwkSetIndex(struct ZigBeeT *zb, enum ZbNwkNibAttrIdT attrId, void *attrPtr, unsigned int attrSz, unsigned int attrIndex);

Performs an NLME-SET.request for an attribute containing an array of values using an index.

Parameters

zb	Zigbee instance
attrId	NWK Attribute Id to set
attrPtr	Pointer to new attribute data
attrSz	Size of new attribute data
attrIndex	Index of value to modify

Return

• Zigbee status code (for example, ZB_STATUS_SUCCESS or ZB_NWK_STATUS_INVALID_PARAMETER)

16.1.48. ZbNwkToggleDutyCycle

bool ZbNwkToggleDutyCycle(struct ZigBeeT *zb, bool enable);

Enable or disable Duty Cycle management in the MAC. Disabling duty cycle will also clear the duty cycle history and set the status to MCP_DUTYCYCLE_STATUS_NORMAL. This function would typically be used in conjunction with ZB_NWK_NIB_ID_TxPowerMgmtSupported, which configures TX power control in the NWK and MAC.

Parameters

zb	ZigBee stack structure
enable	New duty cycle setting

Return

• Returns true on success, or false otherwise

16.1.49. ZbNwkZdGenerateBasicKey

bool ZbNwkZdGenerateBasicKey(struct ZigBeeT *zb, uint64_t zvd_eui, uint8_t key[ZB_SEC_KEYSIZE], uint8_t seqno);

Generate the basic key using network key with input seqnuence number and the ZVD EUI. This can used to generate basic key using old network keys as well.

Parameters

zb	Zigbee instance
zvd_eui	ZVD EUI64
key	Output array to store generated basic key.
seqno	Sequence number of network key to use.

Return

• true if basic key is generated successfully, false otherwise.

16.1.50. nwk_mac_filter_add

bool nwk_mac_filter_add(struct ZigBeeT *zb, uint64_t extAddr, uint16_t nwkAddr, uint8_t in_cost);

Add a new address filter. If the in_cost parameter is set to 0, then all matching frames are dropped.

Parameters

zb	Zigbee instance
extAddr	The EUI-64 address to filter, or 0.
nwkAddr	The NWK short address to filter, or ZB_NWK_ADDR_UNDEFINED.
in_cost	The incoming cost (e.g. LQI) to assign to this device. If 0, all frames from this matching device are dropped.

Return

• True if the filter was added, false otherwise.

16.1.51. nwk_mac_filter_debug

void nwk_mac_filter_debug(struct ZigBeeT *zb);

When called, prints the address filtering table to the Zigbee debug log (level = ZB_LOG_MASK_INFO). Used for debugging only.

Parameters

zb	Zigbee instance

Return

• None

16.1.52. nwk_mac_filter_del

bool nwk_mac_filter_del(struct ZigBeeT *zb, uint64_t extAddr, uint16_t nwkAddr);

Removes an address filter matching either of the addresses provided.

Parameters

zb	Zigbee instance
extAddr	The EUI-64 address of the filter to remove, or 0.
nwkAddr	The NWK short address of the filter to remove, or ZB_NWK_ADDR_UNDEFINED.

Return

• True if the filter was removed, false otherwise.

16.2. Enumerations

16.2.1. ZbNwkNetworkStatusCodeT

NLME-NWK-STATUS.indication status codes

ZB_NWK_STATUS_CODE_NO_ROUTE_AVAILABLE	No route available
ZB_NWK_STATUS_CODE_TREE_LINK_FAILURE	Tree link failure
ZB_NWK_STATUS_CODE_NON_TREE_LINK_FAILURE	Non-tree link failure
ZB_NWK_STATUS_CODE_LOW_BATTERY	Low battery level
ZB_NWK_STATUS_CODE_NO_ROUTING_CAPACITY	No routing capacity
ZB_NWK_STATUS_CODE_NO_INDIRECT_CAPACITY	No indirect capacity
ZB_NWK_STATUS_CODE_INDIRECT_EXPIRY	Indirect transaction expiry
ZB_NWK_STATUS_CODE_TARGET_UNAVAILABLE	Target device unavailable
ZB_NWK_STATUS_CODE_TARGET_UNALLOCATED	Target address unallocated
ZB_NWK_STATUS_CODE_PARENT_LINK_FAILURE	Parent link failure
ZB_NWK_STATUS_CODE_VALIDATE_ROUTE	Validate route
ZB_NWK_STATUS_CODE_SOURCE_ROUTE_FAILURE	Source route failure
ZB_NWK_STATUS_CODE_MANY_TO_ONE_FAILURE	Many-to-one route failure
ZB_NWK_STATUS_CODE_ADDRESS_CONFLICT	Address conflict
ZB_NWK_STATUS_CODE_VERIFY_ADDRESS	Verify address
ZB_NWK_STATUS_CODE_PANID_UPDATE	PAN identifier update
ZB_NWK_STATUS_CODE_ADDRESS_UPDATE	Network address update
ZB_NWK_STATUS_CODE_BAD_FRAME_COUNTER	Bad frame counter
ZB_NWK_STATUS_CODE_BAD_KEY_SEQNUM	Bad key sequence number
ZB_NWK_STATUS_CODE_UNKNOWN_COMMAND	Unknown Command
ZB_NWK_STATUS_CODE_PANID_CONFLICT_REPORT	PanId conflict report.
ZB_NWK_STATUS_CODE_INCOMING_FRAME_COUNTER	(Exegin custom) An incoming frame counter is greater than 0x80000000

16.3. Structures

16.3.1. ZbNlmeBcnSurveyConfT

NLME-BEACON-SURVEY.confirm

Parameters

enum ZbStatusCodeT status	status
uint8_t total_beacons	Total number of beacons received during a beacon survey.
uint8_t on_nwk_beacons	The total number of Zigbee Network beacons where the Extended PAN ID matches the local device’s nwkExtendedPanId.
uint8_t potential_parent_beacons	The total number of Zigbee Network beacons where the Extended PAN ID matches and the Zigbee Beacon payload indicates End Device Capacity = TRUE.
uint8_t other_nwk_beacons	The total number of IEEE 802.15.4 beacons from other Zigbee networks or other IEEE 802.15.4 networks. Other Zigbee network beacons are defined as when the Extended PAN ID does not match the local Extended PAN ID.
struct { uint8_t count	Count of potential parents detected.
struct { uint16_t nwkaddr	Network/Short address of potential parent.
uint8_t lqa	LQA for the parent link.
/*< Single potential parent entry. */ } *potential_parent_list	Potential parent list.

16.3.2. ZbNlmeBcnSurveyReqT

NLME-BEACON-SURVEY.request

Parameters

struct ZbChannelListT scan_channels	ScanChannelList structure.
uint8_t scan_duration	Scan duration.
uint8_t scan_type	Scan type: ZB_SCAN_TYPE_ACTIVE or ZB_SCAN_TYPE_ENHANCED

16.3.3. ZbNlmePanIdUpdateConfT

NLME-PANID-UPDATE.confirm

Parameters

enum ZbStatusCodeT status

status

16.3.4. ZbNlmePanIdUpdateReqT

NLME-PANID-UPDATE.request

Parameters

uint16_t new_pan_id

New NWK PanId.

16.3.5. ZbNwkCommissioningInfo

Commissioning configuration.

Parameters

uint8_t ifc_index	NWK interface index. Starts at 0.
uint16_t nwk_addr	Network Address to configure (default is ZB_NWK_ADDR_UNDEFINED)
uint16_t pan_id	PAN Id to configure (default is ZB_NWK_ADDR_UNDEFINED)
uint8_t rx_on	Configures RxOnWhenIdle to MAC
uint8_t page	Channge Page to configure
uint8_t channel	Channel to configure

17. Security utilities

#include "zigbee.security.h"

17.1. Functions

17.1.1. ZbAesMmoHash

bool ZbAesMmoHash(uint8_t const *data, const unsigned int length, uint8_t *digest);

Performs an AES MMO hash on the selected data

Parameters

zb	Zigbee stack instance
data	data to hash
length	length of data to hash
digest	hash must be AES_BLOCK_SIZE in size

Return

• Undocumented

17.1.2. ZbSecAddDeviceLinkKeyByInstallCode

enum ZbStatusCodeT ZbSecAddDeviceLinkKeyByInstallCode(struct ZigBeeT *zb, uint64_t extAddr, uint8_t *ic, unsigned int len);

ZbApsmeAddKeyReq helper function. Adds a device key-pair to the stack as a Trust Center Link Key type. This API is typically only used by a Trust Center to add link keys for devices that need to join the network. On the joiner side, the link key is set to the preconfiguredLinkKey parameter in the ZbStartupT configuration when calling ZbStartup to join the network.

Parameters

zb	Zigbee stack instance
extAddr	The EUI64 address of the device matching the link key
ic	The install code, including the trailing 2-octet CRC
len	Length of the Install Code in bytes

Return

• Zigbee status code

17.1.3. ZbSecAddDeviceLinkKeyByKey

enum ZbStatusCodeT ZbSecAddDeviceLinkKeyByKey(struct ZigBeeT *zb, uint64_t extAddr, uint8_t *key);

ZbApsmeAddKeyReq helper function. Adds a device key-pair to the stack as a Trust Center Link Key type. This API is typically only used by a trust center to add link keys for devices that need to join the network. On the Joiner side, the link key is set to the preconfiguredLinkKey parameter in the ZbStartupT configuration when calling ZbStartup to join the network.

Parameters

zb	Zigbee stack instance
extAddr	The EUI64 address of the device matching the link key
key	The link key, of length ZB_SEC_KEYSIZE, to add

Return

• Zigbee status code

18. Startup

#include "zigbee.startup.h"

18.1. Functions

18.1.1. ZbStartup

enum ZbStatusCodeT ZbStartup(struct ZigBeeT *zb, struct ZbStartupT *configPtr, void
(*callback)(enum ZbStatusCodeT status, void *cb_arg), void *arg);

The startup code also handles callbacks from the stack to maintain the network and security processes. For example, these include the handling of APSME-UPDATE-DEVICE.indication messages when acting as a Coordinator Trust Center, to handle the authentication procedure described in section 4.6.3.2 of Zigbee R22.

The message callback handlers can be overridden by the application by creating message filters using ZbMsgFilterRegister.

This function and the entire startup code can be bypassed by the application, and the network layer APIs used directly, if so desired.

Parameters

zb	Zigbee stack instance
configPtr	Pointer to ZbStartupT configuration structure.
callback	Application callback that is called with the final result of the startup procedure.
arg	Callback argument

Return

• Zigbee status code whether the startup procedure has been started. If ZB_STATUS_SUCCESS, then the callback will be called with the final result.

18.1.2. ZbStartupConfigGetProDefaults

void ZbStartupConfigGetProDefaults(struct ZbStartupT *configPtr);

Get the default configuration for a PRO network.

Parameters

configPtr

Startup configuration to initialize

Return

• None

18.1.3. ZbStartupConfigGetProSeDefaults

void ZbStartupConfigGetProSeDefaults(struct ZbStartupT *configPtr);

Same as ZbStartupConfigGetProDefaults, but clears the preconfigured global link keys.

Parameters

configPtr

Startup configuration to initialize

Return

• None

18.1.4. ZbStartupDeviceInterviewComplete

bool ZbStartupDeviceInterviewComplete(struct ZigBeeT *zb, uint64_t joiner_eui64,
bool success);

The application calls this when it is done with the Device Interview process for a particular Joiner. The Device Interview process starts in the application when the stack calls the device_interview_cb() callback function defined in the 'struct ZbStartupT' startup configuration.

Parameters

zb	Zigbee stack instance
joiner_eui64	The EUI64 address of the Joiner being interviewed.
success	If true, then the stack will send the Transport Key with the Network Key to end the Device Interview and Joining process.

Return

• True if the request was processed successfully (that is to say the joiner is actively being tracked by the stack), or false otherwise.

18.1.5. ZbStartupFindBindStart

enum ZbStatusCodeT ZbStartupFindBindStart(struct ZigBeeT *zb, void (*callback)(enum
ZbStatusCodeT status, void *arg), void *arg);

Manually start Finding & Binding. F&B is also started automatically after joining the network.

Parameters

zb	Zigbee stack instance
callback	Application callback to call after Finding & Binding complete
arg	Application callback argument

Return

• Zigbee status code

18.1.6. ZbStartupFindBindStartEndpoint

enum ZbStatusCodeT ZbStartupFindBindStartEndpoint(struct ZigBeeT *zb, uint8_t endpoint, 
void (*callback)(enum ZbStatusCodeT status, void *arg), void *arg);

Same as ZbStartupFindBindStart, but only for a single endpoint.

Parameters

zb	Zigbee stack instance
endpoint	Endpoint to perform Finding & Binding from.
callback	Application callback to call after Finding & Binding complete
arg	Application callback argument

Return

• Zigbee status code

18.1.7. ZbStartupPersist

enum ZbStatusCodeT ZbStartupPersist(struct ZigBeeT *zb, const void *pdata, unsigned
int plen, struct ZbStartupCbkeT *cbke_config, void (*callback)(enum ZbStatusCodeT
status, void *arg), void *arg);

Try starting stack using persistence data provided. NOTE: In case of a Zigbee virtual device (ZVD) this API only takes care of restoring the stack from persistence data and does not perform secure rejoin. So the ZVD application shall reestablish the secure session over BLE using basic or admin key and then perform the secure rejoin using ZbStartupRejoin() API.

Parameters

zb	Zigbee stack instance
pdata	Pointer to persistent data
plen	Length of persistent data
cbke_config	Optional pointer to CBKE configuration data structure.
callback	Application callback to call after persistence is completed. It is necessary for the application to specify this callback so it knows exactly when it is safe to start transmitting packets to the Zigbee network. If this function returns an error, then no callback will be generated.
arg	Application callback argument

Return

• Zigbee status code

18.1.8. ZbStartupRejoin

enum ZbStatusCodeT ZbStartupRejoin(struct ZigBeeT *zb, void (*callback)(struct
ZbNlmeJoinConfT *conf, void *arg), void *cbarg);

ZbStartupRejoin is a wrapper for ZbNlmeJoinReq(ZB_NWK_REJOIN_TYPE_NWKREJOIN). Use ZbStartupRejoin instead, because the internal startup handler will restart any timers we need to maintain our parent.

Must already be connected to a network. If not on a network and want to rejoin as way to connect, use ZbStartup with ZbStartTypeRejoin.

Parameters

zb	Zigbee stack instance
callback	Application callback to call after rejoin is complete, indicating success or failure.
cbarg	Application callback argument

Return

• Zigbee status code

enum ZbStatusCodeT ZbStartupTclkStart(struct ZigBeeT *zb, void (*callback)(enum
ZbStatusCodeT status, void *arg), void *arg);

18.1.9. ZbStartupTclkStart

enum ZbStatusCodeT ZbStartupTclkStart(struct ZigBeeT *zb, void (*callback)(enum
ZbStatusCodeT status, void *arg), void *arg);

The application can call ZbStartupTclkStart if it wants to update the trust center link key post join using APS-Request Key method. This is usually done under following scenarios,

Note. In case of a Zigbee Direct (ZDD) updating a provisional link key, after it was commissioned via out-of-band commissioning mechanism. 2. To periodically generate a new APS Link Key with the Trust Center. Continual cycling of the TC Link Key is a 'Works With All Hubs (WWAHU)' security recommendation.

Parameters

zb	Zigbee stack instance
callback	Application callback that is called with the final result of the tclk procedure.
arg	Callback argument

Return

• true if the tclk is completed successfuly, false otherwise.

18.1.10. ZbStartupTcsoAbort

bool ZbStartupTcsoAbort(struct ZigBeeT *zb);

Abort a TCSO, if it’s running. This function should not be necessary, but a Sleepy Device application may need it if it wants to go to sleep before ZbStartupTcsoStart has finished.

Parameters

zb	Zigbee stack instance

Return

• True if TCSO was aborted, false otherwise (i.e. wasn’t running).

18.1.11. ZbStartupTcsoStart

bool ZbStartupTcsoStart(struct ZigBeeT *zb, void (*callback)(enum ZbTcsoStatusT
status, void *arg), void *arg);

The Stack with the help of the ZCL Keep Alive cluster will automatically detect the loss of the Trust Center and start the TCSO process. Before the TCSO process starts and the 'tcso_callback' callback is provided in the startup configuration, it is called to check if the application wants to halt the TCSO process from starting or let it continue. Refer to the description for 'tcso_callback' in the startup configuration for more info.

The application can call ZbStartupTcsoStart at any time if it thinks it has lost communication with the Trust Center and to manually begin the TCSO process.

Parameters

zb	Zigbee stack instance
zvd_parent_info	Parent information structure in case of ZVD. This parameter shall be set to NULL if not acting as ZVD.
callback	Application callback that is called after TCSO is complete.
arg	Application callback argument

Return

• True if TCSO was started and to wait for callback to indicate completion. False if TCSO wasn’t started.

18.1.12. ZbStartupTouchlinkTargetStop

enum ZbStatusCodeT ZbStartupTouchlinkTargetStop(struct ZigBeeT *zb);

If Touchlink Target was started with ZbStartup, this API can be used to stop it.

Parameters

zb	Zigbee stack instance

Return

• Zigbee status code whether touchlink was successfully stopped or not.

18.1.13. ZbTrustCenterRejoin

enum ZbStatusCodeT ZbTrustCenterRejoin(struct ZigBeeT *zb, void (*callback)(enum
ZbStatusCodeT status, void *arg), void *cbarg);

Trust Center Rejoin - unsecured rejoin (already joined to network, but missed a NWK key update).

Parameters

zb	Zigbee stack instance
callback	Application callback to call after Trust Center rejoin is complete. If this function returns an error, then no callback will be generated.
cbarg	Application callback argument

Return

• Zigbee status code

18.2. Enumerations

18.2.1. ZbStartType

Startup control-codes as per the ZCL Spec, Commissioning Cluster’s StartupControl attribute in the "Startup Parameters Attribute Set"

ZbStartTypePreconfigured	(0x00) Preconfigured. No explicit form, join or rejoin to be performed.
ZbStartTypeForm	(0x01) Form network
ZbStartTypeRejoin	(0x02) Rejoin network
ZbStartTypeJoin	(0x03) Join network
ZbStartTypeTouchlink	[Internal stack use only] Touchlink
ZbStartTypeFindBind	[Internal stack use only] Finding & Binding
ZbStartTypeNone	[Internal stack use only] None

18.3. Structures

18.3.1. ZbStartupCbkeT

CBKE configuration parameters for ZbStartup. This configuration is only applicable if the 'suite_mask' is non-zero.

Parameters

uint8_t endpoint	Endpoint to assign ZCL Key Exchange cluster. Default is ZB_ENDPOINT_CBKE_DEFAULT (240)
uint16_t deviceId	Device Id to assign to the endpoint created for the ZCL Key Exchange cluster. Default is ZCL_DEVICE_METER
uint16_t suite_mask	The Key Exchange suite bitmask. E.g. ZCL_KEY_SUITE_CBKE2_ECMQV for CBKE version 2 (cbke_v2).
struct ZbZclCbkeInfoT cbke_v1	CBKE version 1 certificate and security keys configuration. Only applicable if ZCL_KEY_SUITE_CBKE_ECMQV is set in suite_mask.
struct ZbZclCbke2InfoT cbke_v2	CBKE version 2 certificate and security keys configuration. Only applicable if ZCL_KEY_SUITE_CBKE2_ECMQV is set in suite_mask.
uint8_t term_wait_time	This is the time in seconds to include in the Wait Time field in the Terminate Key Establishment command. The Wait Time is the time for the CBKE initiator to wait before trying again. The default value is 0xfe (254 seconds).
bool tc_keepalive_server_enable	= 0), this flag determines whether to allocate the Trust Center Keep Alive Server (true) or Client (false). The Trust Center should set this flag to true, and all other joiners should set this flag to false.
uint8_t tc_keepalive_base	Trust Center Keep Alive Server 'Base' attribute value in minutes. If zero, let the stack choose a default value.
uint16_t tc_keepalive_jitter	Trust Center Keep Alive Server 'Jitter' attribute value in seconds. If zero, let the stack choose a default value.
tcso_callback (callback function pointer)	bool (*tcso_callback)(enum ZbTcsoStatusT status, void *arg) Application callback that is called to notify of any Trust Center Swap Out (TCSO) events initiated by the Keep Alive Client cluster. If the status is set to ZB_TCSO_STATUS_DISCOVERY_UNDERWAY, the application can return false to this callback to halt the TCSO process from continuing. This allows the application to dictate when to start TCSO; for example, during the next wake-cycle if the device is sleepy. The Keep Alive Client is also halted in this case, but will restart after the application calls ZbStartupTcsoStart to perform TCSO, or it calls ZbZclKeepAliveClientStart to restart the Keep Alive mechanism. If the application returns true to this callback, then the TCSO process will proceed normally.
void *tcso_arg

18.3.2. ZbStartupT

The set of configuration parameters used to form or join a network using ZbStartup. Should be first initialized using ZbStartupConfigGetProDefaults or ZbStartupConfigGetProSeDefaults.

Parameters

uint16_t shortAddress	Network short address. Only applicable if startupControl is ZbStartTypePreconfigured or ZbStartTypeRejoin
uint16_t panId	Network PAN Id. Only applicable if startupControl is ZbStartTypePreconfigured or ZbStartTypeRejoin
uint16_t networkManagerAddress	Network Manager Address. Only applicable if startupControl is ZbStartTypePreconfigured or ZbStartTypeRejoin
uint64_t extendedPanId	Extended PAN Id. If startupControl is ZbStartTypeForm and extendedPanId is zero, then the device extended address (EUI) is used. If startupControl is ZbStartTypeRejoin a non-zero extendedPanId must be provided. If startupControl is ZbStartTypeJoin, the device only attempts to join a network matching the extendedPanId. If extendedPanId is zero, then the device attempts to join any available network, sorted by LQI. If startupControl is ZbStartTypePreconfigured a non-zero extendedPanId must be provided.
struct ZbChannelListT channelList	Specify the channel mask(s) to use. If no channel masks are specified, ZB_BDB_PrimaryChannelSet and ZB_BDB_SecondaryChannelSet are used instead.
uint8_t stackProfile	Network Stack Profile. If not ZB_NWK_STACK_PROFILE_PRO, application must configure the following NIB parameters before calling ZbStartup: nwkMaxChildren, nwkReportConstantCost, nwkLinkStatusPeriod, nwkTransactionPersistenceTime, nwkPassiveAckTimeout, nwkMaxBroadcastRetries, nwkSecureAllFrames, nwkSecurityLevel
uint8_t bdbCommissioningMode	BDB Commissioning Mode mask. Set to 0 by default. If BDB_COMMISSION_MODE_TOUCHLINK is set, then Touchlink will be used. If BDB_COMMISSION_MODE_FIND_BIND is set, then Finding &Binding will be used after joining.
enum ZbStartType startupControl	Startup Type. Not applicable if BDB_COMMISSION_MODE_TOUCHLINK commissioning mode is set. If startup type is ZbStartTypeJoin, the ZB_APS_IB_ID_SCAN_COUNT attribute is used to control the number of scans to perform while searching for a network to join. Similarily, the ZB_BDB_ScanDuration attribute is used to configure the MAC scan duration to use for scans during network joining and forming.
struct { uint8_t level	Security Level. Default is 0x05.
bool useInsecureRejoin	Configures ZB_APS_IB_ID_USE_INSECURE_JOIN.
uint64_t trustCenterAddress	Configures ZB_APS_IB_ID_TRUST_CENTER_ADDRESS. If forming the network and assuming the role of Trust Center, the device’s extended address will be used instead, unless this parameter has been explicitly set to ZB_DISTRIBUTED_TC_ADDR.
uint8_t preconfiguredLinkKey	Preconfigured Link Key
uint8_t distributedGlobalKey	Preconfigured Distributed Global Link Key
uint8_t networkKey	Configures the Network Key with key type set to ZB_SEC_KEYTYPE_STANDARD_NWK. Only applicable if startupControl is ZbStartTypePreconfigured.
uint8_t networkKeySeqNum	Configures the Network Key Sequence Number for the Network Key. Also sets ZB_NWK_NIB_ID_ActiveKeySeqNumber to this value. Only applicable if startupControl is ZbStartTypePreconfigured.
enum ZbSecKeyTypeT networkKeyType	Deprecated and not used.
struct ZbStartupCbkeT cbke	CBKE certificate configuration
uint8_t zdLinkKeyFlags	APS Link key flags provided as part of commissioning join to ZDD e.g, ZD_TLV_LINK_KEY_FLAG_UNIQUE. NOTE: Only applicable with CONFIG_ZB_ZDD_SUPPORT.
uint8_t nwkUpdateId	ZB_NWK_NIB_ID_UpdateId, only used in case of ZDD (Zigbee Direct Device) Commissioning form/OOB join performed by ZVD (Zigbee Virtual Device). NOTE: Only applicable with CONFIG_ZB_ZDD_SUPPORT.
uint8_t capability	Device capability mask. Default value includes: MCP_ASSOC_CAP_PWR_SRC (mains power), MCP_ASSOC_CAP_RXONIDLE (radio receiver is on, not sleepy), MCP_ASSOC_CAP_ALLOC_ADDR (parent allocates network address), MCP_ASSOC_CAP_DEV_TYPE (full function device)
uint8_t endDeviceTimeout	End-device timeout is only used by end-devices. It configures the time used to periodically update the Parent device so this device is not removed from the Parent’s NWK Neighbor Table. Configures ZB_NWK_NIB_ID_EndDeviceTimeoutDefault. Timeout = (60 * 2^n) seconds for n > 0. If n = 0, timeout = 10 seconds. Setting to ZB_NWK_CONST_ENDDEV_TIMEOUT_DISABLED (0xff) disables end-device timeout.
uint16_t fastPollPeriod	Configures ZB_NWK_NIB_ID_FastPollPeriod.
struct { uint8_t tl_endpoint	Endpoint for the Touchlink Cluster (e.g. )
uint8_t bind_endpoint	Endpoint to use when binding clusters from Initiator to Target.
uint16_t deviceId	e.g. ZCL_DEVICE_ONOFF_SWITCH
uint8_t zb_info	e.g. ZCL_TL_ZBINFO_TYPE_ROUTER
uint8_t flags	e.g. ZCL_TL_FLAGS_IS_TARGET
const void *persist_buf	Pointer to persistence data. Only applicable if ZCL_TL_ZBINFO_USE_PERSIST flag is set in zb_info.
unsigned int persist_len	Length of persistence data.
struct ZbTouchlinkCallbacks callbacks	Callback functions for Touchlink Controller Device Utility commands.
void *cb_arg	Pointer to application data that will be used with Touchlink callbacks.
struct { uint8_t server_ep	Endpoint to assign to Sub-GHz server cluster to perform duty cycle checks.
uint16_t device_id	DeviceId to assign to the endpoint on which Sub-GHz server cluster is created.
uint8_t supp_key_nego_methods	A bitmask of the supported key negotiation methods e.g, ZB_DLK_STATIC_KEY_REQUEST.
uint8_t supp_pre_shared_secrets	A bitmask of the supported pre-shared secrets e.g, ZB_DLK_SUPP_PSK_SYMMETRIC_AUTH_TOKEN.
device_interview_cb (callback function pointer)	void (*device_interview_cb)(struct ZbApsRelayInfoT *relay_info, uint64_t joiner_eui, void *arg) Device Interview callback. This is called for a device acting as the Trust Center when the Device Interview process can start with the Joiner. As packets are sent as Downstream Relays to the Joiner, the security timer is refreshed by the amount given by apsDeviceInterviewTimeoutPeriod. The 'relay_info' parameter includes the information about where to send packets for the interview process so the Joiner can receive them. The 'joiner_eui' parameter is the Extended Address of the Joiner. Once the TC application is done with the interview process, it must call ZbStartupDeviceInterviewComplete. Refer to that function’s description for more information.
void *device_interview_cb_arg	Argument pointer to include in the device interview callback.

19. TLV Utilities

#include "zigbee.tlv.h"

19.1. Description

This file defines all the ZigBee TLV APIs and macros.

19.2. Functions

19.2.1. zb_tlv_decode

int zb_tlv_decode(const uint8_t *buffer, unsigned int buffer_length, struct zb_tlv
*tlv_array, const unsigned int tlv_count);

Given a list of desired TLVs, examine all the TLVs as per the 'General TLV processing rules'. Update the desired TLV list with all matching TLVs found in the buffer. It is expected that the desired TLV list will have the length field populated with the 'minimum known length' for all the entries. Desired TLVs found in the buffer with length < than the 'minimum known length' are considered 'malformed TLVs'. All the unknown TLVs found in the buffer are locally stored to ensure no duplicate TLVs are present.

Parameters

buffer	(IN) input buffer with TLVs.
buffer_length	(IN) input buffer length.
tlv_array	(IN/OUT) the TLVs that we are looking for.
tlv_count	(IN) number of TLVs in the array we are looking for.

Return

• length of buffer decoded on success. ZB_TLV_STATUS_FAILURE, if any of the input parameters were invalid. ZB_TLV_STATUS_DUPLICATE_TLV, if a duplicate TLV is found. ZB_TLV_STATUS_BUFFER_TRUNCATED, if any TLV is found to be malformed.

19.2.2. zb_tlv_decode_check_mandatory

bool zb_tlv_decode_check_mandatory(const struct zb_tlv *tlv_array, const unsigned
int tlv_count);

Check all mandatory TLVs have non-NULL value fields.

Parameters

tlv_array	(IN) TLV array.
tlv_count	(IN) depth of input TLV array.

Return

• true if all mandatory TLVs were found false otherwise

19.2.3. zb_tlv_encode

int zb_tlv_encode(uint8_t *buffer, unsigned int buffer_length, const struct zb_tlv
*tlv_array, const unsigned int tlv_count);

Given a list of TLVs, this API encodes TLV list into input buffer.

Parameters

buffer	(IN) input buffer with TLVs.
buffer_length	(IN) input buffer length.
tlv_array	(IN) array of TLVs to be encoded.
tlv_count	(IN) depth of TLV array.

Return

• length encoded, negative on error

19.2.4. zb_tlv_encode_length

int zb_tlv_encode_length(struct zb_tlv *tlv_array, const unsigned int tlv_count);

Compute the size of buffer required, if the input TLVs were to be encoded.

Parameters

tlv_array	(IN) input TLV array.
tlv_count	(IN) depth of input TLV array.

Return

• size of buffer required to encode input TLVs.

19.2.5. zb_tlv_type_exists

bool zb_tlv_type_exists(uint8_t *buffer, unsigned int buffer_length, enum
zb_tlv_type type);

Check if the TLV type exists in the input buffer. This API will return failure if the TLV does not exist or is found to be truncated.

Parameters

buffer	(IN) input buffer for TLV processing.
buffer_length	(IN) input buffer length.
type	(IN/OUT) TLV type ID being searched.

Return

• true if TLV exists, false otherwise

19.3. Enumerations

19.3.1. zb_tlv_type

ZigBee TLV type ID enumeration. TLV IDs have been split into local and global TLVs based on their usage. Local TLVs are specific to a single message and their tag IDs may overlap with the local TLV IDs of different messages. Range of local TLV tag IDs is 0-63. However, global TLVs have a single format across all messages and layers and are used in 2 or more different messages. Global TLV IDs represent a global state and is not completely ephemeral in nature. Range of global TLV tag IDs is 64-255.

ZB_TLV_CLEAR_ALL_BIND_REQ_EUI64	Clear_All_Bindings_req EUI64 TLV.
ZB_TLV_KEY_NEGO_CURVE25519_PUB	Security_Key_negotiation_req/rsp Curve25519 Public Point TLV.
ZB_TLV_AUTH_TOKEN_ID	Security_Retrieve_authentication_token_req Authentication Token ID TLV.
ZB_TLV_TARGET_IEEE_ADDR	ZDO Security_Get_authentication_level_req Target IEEE Address TLV.
ZB_TLV_DEVICE_AUTH_LEVEL	ZDO Security_Get_authentication_level_rsp Device Authentication Level TLV.
ZB_TLV_PROCESSING_STATUS	ZDO Security_Set_Configuration_rsp Processing Status TLV.
ZB_TLV_KEY_UPDATE_SEL_KEY_NEGO_METHOD	Security_Key_update_req/rsp selected key negotiation method TLV.
ZB_TLV_DEVICE_EUI64_LIST	ZDO Security_Decommission_req Device EUI64 List TLV.
ZB_TLV_APS_FC_CHALLENGE	ZDO Security_Challenge_req APS frame counter challenge TLV.
ZB_TLV_APS_FC_RESPONSE	ZDO Security_Challenge_rsp APS frame counter response TLV.
ZB_TLV_NODE_DESC_RSP_SEL_KEY_NEGO_METHOD	Node_Desc_Rsp selected key negotiation method TLV.
ZB_TLV_BCN_SURVEY_CONFIG	Mgmt_Beacon_Survey_req Configuration TLV.
ZB_TLV_BCN_SURVEY_RESULTS	Mgmt_Beacon_Survey_rsp Results TLV.
ZB_TLV_BCN_SURVEY_POTENTIAL_PARENTS	Mgmt_Beacon_Survey_rsp Potential Parents TLV.
ZB_TLV_RELAY_MSG	APS Relay message TLV.
ZB_TLV_LINK_KEY_FEATURES_CAPABILITIES	Link-Key Features & Capabilities TLV.
ZB_TLV_MFG_SPECIFIC	Manufacturer specific TLV (ID 64 / 0x40)
ZB_TLV_SUPP_KEY_NEGO_METHOD	Supported key negotiation method TLV (ID 65 / 0x41)
ZB_TLV_PANID_CONFLICT_REPORT	PANID conflict report global TLV (ID 66 / 0x42)
ZB_TLV_NEXT_PANID	Next PAN ID TLV (ID 67 / 0x43)
ZB_TLV_NEXT_CHANNEL	Next channel change TLV (ID 68 / 0x44)
ZB_TLV_PASSPHRASE_128	Symmetric passphrase TLV (ID 69 / 0x45)
ZB_TLV_ROUTER_INFO	Router Information TLV (ID 70 / 0x46)
ZB_TLV_FRAG_PARAM	Fragmentation Parameters TLV (ID 71 / 0x47)
ZB_TLV_JOINER_ENCAPSULATION	Joiner Encapsulation TLV (ID 72 / 0x48)
ZB_TLV_BEACON_APPENDIX_ENCAPSULATION	Beacon Appendix Encapsulation TLV (ID 73 / 0x49)
ZB_TLV_CONFIG_PARAM	Configuration params TLV (ID 75 / 0x4b)
ZB_TLV_DEVICE_CAP_EXT_GLOBAL	Device Capability Extension Global TLV (ID 76 / 0x4c)
ZB_TLV_ID_RESERVED	Global TLV ID’s >= this ID are reserved (ID 77 / 0x4d)

19.4. Structures

19.4.1. zb_tlv

ZigBee TLV structure definition.

Parameters

enum zb_tlv_type type	Valid range for length field is 1-256. If the caller of TLV API zb_tlv_encode() provides length field of a TLV as 0 or >256 it is treated as invalid and returned with error ZB_TLV_STATUS_INVALID_LEN.
const uint8_t *value

20. ZDO Layer

#include "zigbee.zdo.h"

20.1. Description

This file provides the declaration of all the public APIs and macros used by the ZDO layer.

20.2. Functions

20.2.1. ZbZdoActiveEpReq ==

enum ZbStatusCodeT ZbZdoActiveEpReq(struct ZigBeeT *zb, struct ZbZdoActiveEpReqT *req, void (*callback)
(struct ZbZdoActiveEpRspT *rsp, void *cb_arg), void *arg);

Retrieve the active endpoint list for a device.

Parameters

zb	Zigbee stack instance
req	Active_ep_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.2. ZbZdoBcnSurveyReq

enum ZbStatusCodeT ZbZdoBcnSurveyReq(struct ZigBeeT *zb, struct ZbZdoBcnSurveyReqT *req, void (*callback)
(struct ZbZdoBcnSurveyRspT *rsp, void *cb_arg), void *arg); Sends ZDO Mgmt_Beacon_Survey_req command.

Parameters

zb	ZigBee stack structure.
req	Beacon survey req struct.
callback	callback function pointer.
arg	argument to response handler function.

Return

• enum ZbStatusCodeT

20.2.3. ZbZdoBindReq

enum ZbStatusCodeT ZbZdoBindReq(struct ZigBeeT *zb, struct ZbZdoBindReqT *req, void
(*callback)(struct ZbZdoBindRspT *rsp, void *cb_arg), void *arg);

Perform a ZDO Bind operation.

Parameters

zb	Zigbee stack instance
req	Bind_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.4. ZbZdoClearAllBindingsReq

enum ZbStatusCodeT ZbZdoClearAllBindingsReq(struct ZigBeeT *zb, struct
ZbZdoClearAllBindingsReqT *req, void (*callback)(struct ZbZdoClearAllBindingsRspT
*rsp, void *cb_arg), void *arg);

Send a ZDO Security Clear all bindings request command.

Parameters

zb	Zigbee stack instance
req	clear all bindings req struct
callback	callback function pointer
arg	argument to response handler function

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.5. ZbZdoDeviceAnnce

void ZbZdoDeviceAnnce(struct ZigBeeT *zb, struct ZbZdoDeviceAnnceT *deviceAnncePtr);

Send a Device_annce message to the network. Automatically called by the stack after joining.

Parameters

zb	Zigbee stack instance
deviceAnncePtr	Pointer to Device_annce structure

Return

• Returns void

20.2.6. ZbZdoDeviceAnnceAlias

void ZbZdoDeviceAnnceAlias(struct ZigBeeT *zb, struct ZbZdoDeviceAnnceT
*deviceAnncePtr);

Send a Device_annce message to the network using aliasing.

Parameters

zb	Zigbee stack instance
deviceAnncePtr	Pointer to Device_annce structure

Return

• Returns void

20.2.7. ZbZdoDeviceAnnceFilterRegister

struct ZbZdoFilterT * ZbZdoDeviceAnnceFilterRegister(struct ZigBeeT *zb, struct ZbZdoFilterT *filter, enum zb_msg_filter_rc 
(*callback)(struct ZigBeeT *zb, struct ZbZdoDeviceAnnceT *annce, uint8_t seqno, void *arg), void *arg);

Register a filter in the ZDO for the application to receive Device_Annce messages.

Parameters

zb	Zigbee stack instance
filter	Optional pointer to a pre-allocated ZbZdoFilterT structure. If NULL, the struct will be allocated via ZbHeapAlloc().
callback	Function to call upon reception of a valid ZDO Device-Annce message. Callback can return ZB_MSG_CONTINUE to process other filters, or ZB_MSG_DISCARD if all processing of this message should stop.
arg	Callback argument

Return

• Pointer to filter structure

20.2.8. ZbZdoGetNextSeqNum

uint8_t ZbZdoGetNextSeqNum(struct ZigBeeT *zb);

Return and increment the next ZDO sequence number.

Parameters

zb	Zigbee stack instance

Return

• Returns ZDO sequence number.

20.2.9. ZbZdoIeeeAddrReq

enum ZbStatusCodeT ZbZdoIeeeAddrReq(struct ZigBeeT *zb, struct ZbZdoIeeeAddrReqT *req, void (*callback)
(struct ZbZdoIeeeAddrRspT *rsp, void *cb_arg), void *arg);

Retrive the 64-bit extended address for a device if given a short network address.

Parameters

zb	Zigbee stack instance
req	IEEE_Addr_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.10. ZbZdoLeaveReq

enum ZbStatusCodeT ZbZdoLeaveReq(struct ZigBeeT *zb, struct ZbZdoLeaveReqT *req,
void (*callback)(struct ZbZdoLeaveRspT *rsp, void *cb_arg), void *arg);

Perform a Mgmt_leave_req command.

Parameters

zb	Zigbee stack instance
req	Mgmt_Leave_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.11. . ZbZdoLqiReq

Perform a Mgmt_Lqi_req command.

enum ZbStatusCodeT ZbZdoLqiReq(struct ZigBeeT *zb, struct ZbZdoLqiReqT *req, void
(*callback)(struct ZbZdoLqiRspT *rsp, void *cb_arg), void *arg);

Parameters

zb	Zigbee stack instance
req	Mgmt_Lqi_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.12. ZbZdoMatchDescMulti

enum ZbStatusCodeT ZbZdoMatchDescMulti(struct ZigBeeT *zb, struct
ZbZdoMatchDescReqT *req, void (*callback)(struct ZbZdoMatchDescRspT *rsp, void
*cb_arg), void *arg);

Send a ZDO Match-Desc request and receive multiple responses. The responses, if any, are received by the callback. Each callback contains the result of a callback from a single device. The callback will be called each time a response is received. After a timeout period, the callback is called with a status of ZB_ZDP_STATUS_TIMEOUT to indicate the internal response filter is removed and any additional responses for this request are not processed.

Parameters

zb	Zigbee stack instance
req	Match_desc_req
callback	Function to call on completion
arg	Callback argument

Return

• ZB_ZDP_STATUS_SUCCESS for received responses, ZB_ZDP_STATUS_TABLE_FULL if there’s a problem starting the request, ZB_ZDP_STATUS_TIMEOUT when the stack decides to stop receiving responses, or other ZclStatusCodeT value on error

20.2.13. ZbZdoMatchDescReq

enum ZbStatusCodeT ZbZdoMatchDescReq(struct ZigBeeT *zb, struct ZbZdoMatchDescReqT *req, void (*callback)
(struct ZbZdoMatchDescRspT *rsp, void *cb_arg), void *arg);

Retrieve the mach descriptor for a device.

Parameters

zb	Zigbee stack instance
req	Match_desc_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.14. ZbZdoMgmtBindReq

enum ZbStatusCodeT ZbZdoMgmtBindReq(struct ZigBeeT *zb, struct ZbZdoMgmtBindReqT *req, void (*callback)
(struct ZbZdoMgmtBindRspT *rsp, void *cb_arg), void *arg); Perform a Mgmt_Bind_req command.

Parameters

zb	Zigbee stack instance
req	Mgmt_bind_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.15. ZbZdoNodeDescReq

enum ZbStatusCodeT ZbZdoNodeDescReq(struct ZigBeeT *zb, struct ZbZdoNodeDescReqT *req, void (*callback)
(struct ZbZdoNodeDescRspT *rsp, void *cb_arg), void *arg);

Retrieve the node descriptor for a device.

Parameters

zb	Zigbee stack instance
req	Node_desc_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.16. ZbZdoNwkAddrReq

enum ZbStatusCodeT ZbZdoNwkAddrReq(struct ZigBeeT *zb, struct ZbZdoNwkAddrReqT *req, void (*callback)
(struct ZbZdoNwkAddrRspT *rsp, void *cb_arg), void *arg);

Retrieve the 16-bit short address for a device if given an extended address.

Parameters

zb	Zigbee stack instance
req	NWK_Addr_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.17. ZbZdoNwkEnhUpdateNotifyFilterRegister

struct ZbZdoFilterT * ZbZdoNwkEnhUpdateNotifyFilterRegister(struct ZigBeeT *zb, struct ZbZdoFilterT *filter, 
enum zb_msg_filter_rc (*callback)(struct ZigBeeT *zb, struct ZbZdoNwkUpdateNotifyT *msg, uint8_t seqno, void *arg), void *arg);

Register a filter in the ZDO for the application to receive Mgmt_Nwk_Enhanced_Update_notify messages.

Parameters

zb	Zigbee stack instance
filter	Optional pointer to a pre-allocated ZbZdoFilterT structure. If NULL, the struct will be allocated via ZbHeapAlloc().
callback	Function to call upon reception of a valid ZDO NWK-Update-Notify message. Callback can return ZB_MSG_CONTINUE to process other filters, or ZB_MSG_DISCARD if all processing of this message should stop.
arg	Callback argument

Return

• Pointer to filter structure

20.2.18. ZbZdoNwkEnhUpdateReq

enum ZbStatusCodeT ZbZdoNwkEnhUpdateReq(struct ZigBeeT *zb, struct ZbZdoNwkEnhUpdateReqT *req, void (*callback)

(struct ZbZdoNwkUpdateNotifyT *reqPtr, void *cb_arg), void *arg); Perform a Mgmt_Nwk_Enhanced_Update_req command.

Parameters

zb	Zigbee stack instance
req	Mgmt_Nwk_Enhanced_Update_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.19. ZbZdoNwkIeeeJoinListBcastAll

unsigned int ZbZdoNwkIeeeJoinListBcastAll(struct ZigBeeT *zb);

Send an IEEE-Joining-List.response broadcast message for all entries in the IEEE Join List. Used primarily by GB868 applications.

Parameters

zb	Zigbee stack instance

Return

• Returns number of entries sent

20.2.20. ZbZdoNwkIeeeJoinListReq

enum ZbStatusCodeT ZbZdoNwkIeeeJoinListReq(struct ZigBeeT *zb, struct ZbZdoNwkIeeeJoinListReqT *req, 
void (*callback)(struct ZbZdoNwkIeeeJoinListRspT *rsp, void *cb_arg), void *arg);

Send an IEEE-Joining-List request.

Parameters

zb	Zigbee stack instance
IEEE-Joining-List.request	Structure
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.21. ZbZdoNwkIeeeJoinListRsp

unsigned int ZbZdoNwkIeeeJoinListRsp(struct ZigBeeT *zb, uint16_t dstNwkAddr, uint8_t startIndex, 
uint8_t seqnum, bool fromRequest);

Send an IEEE-Joining-List.response. Used primarily by GB868 applications.

Parameters

zb	Zigbee stack instance
dstNwkAddr	Destination network address
startIndex	Start index
seqnum	Sequence number
fromRequest	Use start index from request

Return

• Number of entries sent in response

20.2.22. ZbZdoNwkUpdateNotify

enum ZbStatusCodeT ZbZdoNwkUpdateNotify(struct ZigBeeT *zb, struct
ZbZdoNwkUpdateNotifyT *reqPtr);

Send an unsolicited Mgmt_Nwk_Update_notify command to the network manager. Does not wait for any response.

Parameters

zb	Zigbee stack instance
reqPtr	Mgmt_Nwk_Update_notify

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.23. ZbZdoNwkUpdateNotifyFilterRegister

struct ZbZdoFilterT * ZbZdoNwkUpdateNotifyFilterRegister(struct ZigBeeT *zb, struct ZbZdoFilterT *filter, 
enum zb_msg_filter_rc (*callback)(struct ZigBeeT *zb, struct ZbZdoNwkUpdateNotifyT *msg, uint8_t seqno, void *arg), void *arg);

Register a filter in the ZDO for the application to receive Mgmt_Nwk_Update_notify messages.

Parameters

zb	Zigbee stack instance
filter	Optional pointer to a pre-allocated ZbZdoFilterT structure. If NULL, the struct will be allocated via ZbHeapAlloc().
callback	Function to call upon reception of a valid ZDO NWK-Update-Notify message. Callback can return ZB_MSG_CONTINUE to process other filters, or ZB_MSG_DISCARD if all processing of this message should stop.
arg	Callback argument

Return

• Pointer to filter structure

20.2.24. ZbZdoNwkUpdateReq

enum ZbStatusCodeT ZbZdoNwkUpdateReq(struct ZigBeeT *zb, struct ZbZdoNwkUpdateReqT
*req, void (*callback)(struct ZbZdoNwkUpdateNotifyT *reqPtr, void *cb_arg), void *arg);

Perform a Mgmt_Nwk_update_req command.

Parameters

zb	Zigbee stack instance
req	Mgmt_Nwk_update_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.25. ZbZdoPermitJoinReq

enum ZbStatusCodeT ZbZdoPermitJoinReq(struct ZigBeeT *zb, struct ZbZdoPermitJoinReqT *req, 
void (*callback)(struct ZbZdoPermitJoinRspT *rsp, void *cb_arg), void *arg);

Sends a ZDO Mgmt_permit_join_req command.

With R23 and above, there are new fields added to the ZDO Mgmt_permit_join_req command e.g, 'Frame Control' & 'Global Beacon Appendix'

In case of centralized security networks only TC can send this command with TLV_UPDATE bit set to 1 in frame control field. And if a non-TC device invokes this API with TLV_UPDATE bit set, it will be treated as an invalid request.

Parameters

zb	Zigbee stack instance
req	Mgmt_permit_joining_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.26. ZbZdoPowerDescReq

enum ZbStatusCodeT ZbZdoPowerDescReq(struct ZigBeeT *zb, struct ZbZdoPowerDescReqT *req, void (*callback)
(struct ZbZdoPowerDescRspT *rsp, void *cb_arg), void *arg);

Retrieve the power descriptor for a device.

Parameters

zb	Zigbee stack instance
req	Power_desc_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.27. ZbZdoRtgReq

enum ZbStatusCodeT ZbZdoRtgReq(struct ZigBeeT *zb, struct ZbZdoRtgReqT *req, void
(*callback)(struct ZbZdoRtgRspT *rsp, void *cb_arg), void *arg);

Perform a Mgmt_Rtg_req command.

Parameters

zb	Zigbee stack instance
req	Mgmt_Rtg_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.28. ZbZdoSecChallengeReq

enum ZbStatusCodeT ZbZdoSecChallengeReq(struct ZigBeeT *zb, struct ZbZdoSecChallengeReqT *req,
void (*callback)(struct ZbZdoSecChallengeRspT *rsp, void *cb_arg), void *arg);

Sends ZDO Security_Challenge_req command.

Parameters

zb	ZigBee stack structure.
req	challenge req struct.
callback	callback function pointer.
arg	argument to response handler function.

Return

• enum ZbStatusCodeT

20.2.29. ZbZdoSecDecommissionReq

enum ZbStatusCodeT ZbZdoSecDecommissionReq(struct ZigBeeT *zb, struct ZbZdoSecDecommissionReqT *req, void (*callback)
(struct ZbZdoSecDecommissionRspT *rsp, void *cb_arg), void *arg);

Sends ZDO Security_Decommission_req command.

Parameters

zb	ZigBee stack structure.
req	decommission req struct.
callback	callback function pointer.
arg	argument to response handler function.

Return

• enum ZbStatusCodeT

20.2.30. ZbZdoSecGetAuthLevelReq

enum ZbStatusCodeT ZbZdoSecGetAuthLevelReq(struct ZigBeeT *zb, struct ZbZdoSecGetAuthLevelReqT *req, 
void (*callback)(struct ZbZdoSecGetAuthLevelRspT *rsp, void *cb_arg), void *arg);

Send a ZDO Security get authentication level request command.

Parameters

zb	Zigbee stack instance
req	get authentication level req struct
callback	Function to call on completion
arg	argument to response handler function

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.31. ZbZdoSecGetConfigReq

enum ZbStatusCodeT ZbZdoSecGetConfigReq(struct ZigBeeT *zb, struct ZbZdoSecGetConfigReqT *req, 
void (*callback)(struct ZbZdoSecGetConfigRspT *rsp, void *cb_arg), void *arg);

Sends ZDO Security get configuration request command.

Parameters

zb	ZigBee stack structure.
req	get configuration req struct.
callback	callback function pointer.
arg	argument to response handler function.

Return

• enum ZbStatusCodeT

20.2.32. ZbZdoSecKeyUpdateReq

enum ZbStatusCodeT ZbZdoSecKeyUpdateReq(struct ZigBeeT *zb, struct ZbZdoSecKeyUpdateReqT *req, 
void (*callback)(struct ZbZdoSecKeyUpdateRspT *rsp, void *cb_arg), void *arg);

Send a ZDO Security Key Update Request.

Parameters

zb	Zigbee stack instance
req	security key update req struct
callback	Function to call on completion
arg	argument to response handler function

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.33. ZbZdoSecSetConfigReq

enum ZbStatusCodeT ZbZdoSecSetConfigReq(struct ZigBeeT *zb, struct ZbZdoSecSetConfigReqT *req,
void (*callback)(struct ZbZdoSecSetConfigRspT *rsp, void *cb_arg), void *arg);

Send a ZDO Security set configuration request command.

Parameters

zb	Zigbee stack instance
req	set configuration req struct.
callback	Function to call on completion
arg	argument to response handler function

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.34. ZbZdoSimpleDescReq

enum ZbStatusCodeT ZbZdoSimpleDescReq(struct ZigBeeT *zb, struct ZbZdoSimpleDescReqT *req, void (*callback)
(struct ZbZdoSimpleDescRspT *rsp, void *cb_arg), void *arg);

Retrieve the simple descriptor for a device.

Parameters

zb	Zigbee stack instance
req	Simple_desc_req
callback	Function to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.2.35. ZbZdoUnbindReq

enum ZbStatusCodeT ZbZdoUnbindReq(struct ZigBeeT *zb, struct ZbZdoBindReqT *req,
void (*callback)(struct ZbZdoBindRspT *rsp, void *cb_arg), void *arg);

Perform a ZDP Unbind Bind operation.

zb	Zigbee stack instance
req	Unbind_req
Function	to call on completion
arg	Callback argument

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

20.3. Enumerations

20.3.1. ZbZdoAddrReqTypeT

NWK_addr_req / IEEE_addr_req definitions

ZB_ZDO_ADDR_REQ_TYPE_SINGLE	Single address request - Returns the information requested only
ZB_ZDO_ADDR_REQ_TYPE_EXTENDED	Extended address request - Returns the information requested and appends the devices in its network table

20.4. Structures

20.4.1. ZbNodeDescriptorT

ZigBee Node Descriptor

Parameters

uint8_t logicalType	Logical type
uint8_t fragSupported	Fragmentation Supported
uint8_t apsFlags	APS flags
uint8_t freqBands	Frequency band
uint8_t macCapability	MAC capability flags
uint16_t mfrCode	Manufacturer code
uint8_t maxBuffer	Maximum buffer size
uint16_t maxIncomingTransfer	Maximum incoming transfer size
uint16_t serverMask	Server mask
uint16_t maxOutgoingTransfer	Maximum outgoing transfer size
uint8_t descCapability	Descriptor capability field

20.4.2. ZbPowerDescriptorT

ZigBee power descriptor

Parameters

uint8_t currentMode	Current power mode
uint8_t availableSources	Available power sources
uint8_t currentSource	Current power source
uint8_t currentLevel	Current power source level

20.4.3. ZbSimpleDescriptorT

ZigBee simple (application) descriptor.

Parameters

uint8_t endpoint	Endpoint
uint16_t profileId	Application profile identifier
uint16_t deviceId	Application device identifier
uint8_t version	Application device version
uint8_t inputClusterCount	Application input cluster count
uint16_t inputClusterList	Application input cluster list
uint8_t outputClusterCount	Application output cluster count
uint16_t outputClusterList	Application output cluster list

20.4.4. ZbZdoActiveEpReqT

Active_EP_req

uint16_t dstNwkAddr	Destination network address
uint16_t nwkAddrOfInterest	NWKAddrOfInterest
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.5. ZbZdoActiveEpRspT

Active_EP_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t nwkAddr	NWKAddrOfInterest
uint8_t activeEpCount	ActiveEPCount
uint8_t activeEpList	ActiveEPList
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.6. ZbZdoBcnSurveyReqT

Mgmt_Beacon_Survey_Req.

Parameters

uint16_t dest_addr	destination address.
struct ZbChannelListT scan_channels	ScanChannelListStructure.
uint8_t config_bitmask	bit 0: 0 Active Scan 1 Enhanced Active Scan. bit 1 - 7: reserved.

20.4.7. ZbZdoBcnSurveyRspT

Mgmt_Beacon_Survey_Rsp.

Parameters

enum ZbStatusCodeT status	Status.
uint8_t total_beacons	Total number of beacons received during a beacon survey.
uint8_t on_nwk_beacons	The total number of Zigbee Network beacons where the Extended PAN ID matches the local device’s nwkExtendedPanId.
uint8_t potential_parent_beacons	The total number of Zigbee Network beacons where the Extended PAN ID matches and the Zigbee Beacon payload indicates End Device Capacity = TRUE.
uint8_t other_nwk_beacons	The total number of IEEE 802.15.4 beacons from other Zigbee networks or other IEEE 802.15.4 networks. Other Zigbee network beacons are defined as when the Extended PAN ID does not match the local Extended PAN ID.
struct { uint8_t count	Count of potential parents detected.
struct { uint16_t nwkaddr	Network/Short address of potential parent.
uint8_t lqa	LQA for the parent link.
/*< Single potential parent entry. */ } *potential_parent_list	Potential parent list.

20.4.8. ZbZdoBindReqT

Bind_req

Parameters

uint16_t target	Destination for the ZDO Bind Request message
uint64_t srcExtAddr	SrcAddress
uint8_t srcEndpt	SrcEndp
uint16_t clusterId	ClusterID
struct ZbApsAddrT dst	DstAddrMode, DstAddress, DstEndp
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. NOTE: Only required for Golden Unit behaviour and if stack was built with CONFIG_ZB_ENABLE_GU condition enabled, otherwise it’s ignored. (R23+)

20.4.9. ZbZdoBindRspT

Bind_rsp

Parameters

enum ZbStatusCodeT status

Status

20.4.10. ZbZdoBindingDescT

Binding descriptor

uint64_t srcAddr	SrcAddr
uint8_t srcEndpt	SrcEndpoint
uint16_t clusterId	ClusterId
struct ZbApsAddrT dst	DstAddr

20.4.11. ZbZdoClearAllBindingsReqT

Clear_All_Bindings_req

Parameters

uint16_t destAddr	destination address.
uint8_t eui64_count	EUI64count
uint64_t eui64_array	EUI64_array.

20.4.12. ZbZdoDeviceAnnceT

Device_annce (ZB_ZDO_DEVICE_ANNCE)

Parameters

uint16_t nwkAddr	NWKAddr
uint64_t extAddr	IEEEAddr
uint8_t capability	Capability

20.4.13. ZbZdoIeeeAddrReqT

IEEE_addr_req

Parameters

uint16_t dstNwkAddr	Destination network address
uint16_t nwkAddrOfInterest	NWKAddrOfInterest
enum ZbZdoAddrReqTypeT reqType	RequestType
uint8_t startIndex	StartIndex

20.4.14. ZbZdoLeaveReqT

Mgmt_Nwk_Leave_req

Parameters

uint16_t destAddr	Destination address
uint64_t deviceAddr	Device address
uint8_t flags	Remove Children, Rejoin

20.4.15. ZbZdoLeaveRspT

Mgmt_Nwk_Leave_rsp

struct ZbApsRelayInfoT relayInfo

Contains information required to relay the APS packet. (R23+)

Parameters

enum ZbStatusCodeT status

Status

20.4.16. ZbZdoLqiReqT

Mgmt_Lqi_req

Parameters

uint16_t destAddr	Destination address
uint8_t startIndex	StartIndex

20.4.17. ZbZdoLqiRspT

Mgmt_Lqi_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t respAddr	Response address
uint8_t neighborTblSz	NeighborTableEntries
uint8_t startIndex	StartIndex
uint8_t neighborListSz	NeighborTableListCount
struct ZbZdoNeighborDescT neighborList	NeighborTableList

20.4.18. ZbZdoMatchDescReqT

Match_Desc_req

Parameters

uint16_t dstNwkAddr	Destination network address
uint16_t nwkAddrOfInterest	NWKAddrOfInterest
uint16_t profileId	ProfileID
uint8_t numInClusters	NumInClusters
uint16_t inClusterList	InClusterList
uint8_t numOutClusters	NumOutClusters
uint16_t outClusterList	OutClusterList
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.19. ZbZdoMatchDescRspT

Match_Desc_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t nwkAddr	NWKAddrOfInterest
uint8_t matchLength	MatchLength
uint8_t matchList	MatchList
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.20. ZbZdoMgmtBindReqT

Mgmt_Bind_req

Parameters

uint16_t destAddr	Destination address
uint8_t startIndex	StartIndex

20.4.21. ZbZdoMgmtBindRspT

Mgmt_Bind_rsp

Parameters

enum ZbStatusCodeT status	Status
uint8_t bindTblSz	BindingTableEntries
uint8_t startIndex	StartIndex
uint8_t bindListSz	BindingTableListCount
struct ZbZdoBindingDescT bindList	BindingTableList

20.4.22. ZbZdoNeighborDescT

Neighbor Descriptor

Parameters

uint64_t epid	Extended PAN ID
uint64_t extAddr	Extended address
uint16_t nwkAddr	Network address
uint8_t deviceType	Device type
uint8_t rxOnWhenIdle	RxOnWhenIdle
uint8_t relationship	Relationship
uint8_t permitJoin	Permit joining
uint8_t depth	Depth
uint8_t lqi	LQI

20.4.23. ZbZdoNetworkDescT

Network descriptor

Parameters

uint64_t epid	ExtendedPANId
uint8_t logicalChannel	LogicalChannel
uint8_t version	ZigBeeVersion
uint8_t stackProfile	StackProfile
uint8_t superframeOrder	SuperframeOrder
uint8_t beaconOrder	BeaconOrder
uint8_t permitJoin	PermitJoining

20.4.24. ZbZdoNodeDescReqT

Node_Desc_req

Parameters

uint16_t dstNwkAddr	Destination network address.
uint16_t nwkAddrOfInterest	Network address on interest.
uint64_t joinerExtAddr	Extended address of joiner. (R23+)
uint8_t suppKeyNegoMethod	Supported key negotiation method. (R23+)
uint8_t suppPreSharedSecrets	Supported Pre-Shared secrets. (R23+)
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.25. ZbZdoNodeDescRspT

Node_Desc_rsp

Parameters

enum ZbStatusCodeT status	Status.
uint16_t nwkAddr	short address.
struct ZbNodeDescriptorT nodeDesc	Node descriptor structure.
enum ZbSelKeyNegoMethodT selKeyNegoMethod	Selected key negotiation method. (R23+)
enum ZbSelPreSharedSecretT selPreSharedSecret	Selected Pre-Shared secret. (R23+)
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.26. ZbZdoNwkAddrReqT

NWK_addr_req

Parameters

uint16_t dstNwkAddr	Destination network address, not in spec
uint64_t extAddr	IEEEAddr
enum ZbZdoAddrReqTypeT reqType	RequestType
uint8_t startIndex	StartIndex
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.27. ZbZdoNwkAddrRspT

NWK_addr_rsp

Parameters

enum ZbStatusCodeT status	Status
uint64_t extAddr	IEEEAddrRemoteDev
uint16_t nwkAddr	NWKAddrRemoteDev
uint8_t deviceCount	NumAssocDev
uint8_t startIndex	StartIndex
uint16_t deviceList	NWKAddrAssocDevList
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.28. ZbZdoNwkEnhUpdateReqT

Mgmt_Nwk_Enhanced_Update_req

Parameters

uint16_t destAddr	Destination address
struct ZbChannelListT channelList	ScanChannelsListStructure
uint8_t scanDuration	ScanDuration
uint8_t scanCount	ScanCount
uint8_t updateId	nwkUpdateId
uint16_t managerAddr	nwkManagerAddr

20.4.29. ZbZdoNwkIeeeJoinListReqT

Mgmt_Nwk_Ieee_Joining_List_req

Parameters

uint16_t destAddr	Destination address
uint8_t startIndex	StartIndex

20.4.30. ZbZdoNwkIeeeJoinListRspT

Mgmt_Nwk_Ieee_Joining_List_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t respAddr	Response address
uint8_t updateId	IeeeJoiningListUpdateID
enum WpanJoinPolicyT joiningPolicy	JoiningPolicy
uint8_t ieeeJoiningListTotal	IeeeJoiningListTotal
uint8_t startIndex	StartIndex
uint8_t ieeeJoiningListCount	IeeeJoiningCount
uint64_t ieeeJoiningList	IeeeJoiningList

20.4.31. ZbZdoNwkUpdateNotifyT

Mgmt_Nwk_Update_notify

Parameters

enum ZbStatusCodeT status	Status
uint32_t scannedChannels	ScannedChannels
uint16_t txTotal	TotalTransmissions
uint16_t txFails	TransmissionFailures
uint8_t channelListSz	ScannedChannelsListCount
uint8_t channelList	Channel energy list

20.4.32. ZbZdoNwkUpdateReqT

Mgmt_Nwk_Update_req

Parameters

uint16_t destAddr	Destination address
uint32_t channelMask	ScanChannels
uint8_t scanDuration	ScanDuration
uint8_t scanCount	ScanCount
uint8_t updateId	nwkUpdateId
uint16_t managerAddr	nwkManagerAddr

20.4.33. ZbZdoPermitJoinReqT

ZDO Mgmt_Permit_Join_req

Parameters

uint16_t destAddr	Short dst addr
uint8_t duration	Permit join duration
uint8_t tcSignificance	Boolean flag which if TRUE, indicates request to change TC policy.
uint8_t tlvData	Optional TLV data in case of R23 devices. In case of TC, it shall be beacon appendix encapsulation TLV. (R23+)
uint8_t tlvDataLen	Length of TLV data, if present. (R23+)

20.4.34. ZbZdoPermitJoinRspT

ZDO Mgmt_Permit_Join_rsp

Parameters

enum ZbStatusCodeT status

Status

20.4.35. ZbZdoPowerDescReqT

Power_Desc_req

Parameters

uint16_t dstNwkAddr	Destination network address
uint16_t nwkAddrOfInterest	NWKAddrOfInterest
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.36. ZbZdoPowerDescRspT

Power_Desc_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t nwkAddr	NWKAddrOfInterest
struct ZbPowerDescriptorT powerDesc	PowerDescriptor
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.37. ZbZdoRoutingDescT

Routing descriptor

Parameters

uint16_t destAddr	Destination address
uint8_t status	Status
uint8_t constrained	Memory Constrained
uint8_t manyToOne	Many-to-one
uint8_t recordRequired	Route record required
uint16_t nextHopAddr	Next-hop address

20.4.38. ZbZdoRtgReqT

Mgmt_Rtg_req

Parameters

uint16_t destAddr	Destination address
uint8_t startIndex	StartIndex

20.4.39. ZbZdoRtgRspT

Mgmt_Rtg_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t respAddr	Response address
uint8_t routeTblSz	RoutingTableEntries
uint8_t startIndex	StartIndex
uint8_t routeListSz	RoutingTableListCount
struct ZbZdoRoutingDescT routeList	RoutingTableList

20.4.40. ZbZdoSecGetConfigReqT

Security_Get_Configuration_Req.

Parameters

uint16_t destAddr	Short dst addr
uint8_t tlvCount	Number of TLV ID’s present in the TLV list.
uint8_t tlvIdList	Variable length TLV ID list.

20.4.41. ZbZdoSecGetConfigRspT

Security_Get_Configuration_Rsp.

Parameters

enum ZbStatusCodeT status	Status.
uint8_t tlvList	Variable length TLV list.
uint8_t tlvListSize	Size of TLV list.

20.4.42. ZbZdoSecKeyUpdateReqT

Security_Key_Update_Req.

Parameters

uint16_t dstNwkAddr	Destination short address.
enum ZbSelKeyNegoMethodT selKeyNegoMethod	Selected key negotiation method.
enum ZbSelPreSharedSecretT selPreSharedSecret	Selected Pre-Shared secret.
uint16_t nodeId	Node of the device that the subsequent fragmentation parameters apply to.
uint16_t maxInputBufferSize	Maximum Reassembled Input Buffer Size.
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet.

20.4.43. ZbZdoSimpleDescReqT

Simple_Desc_req

Parameters

uint16_t dstNwkAddr	Destination network address
uint16_t nwkAddrOfInterest	NWKAddrOfInterest
uint8_t endpt	Endpoint
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

20.4.44. ZbZdoSimpleDescRspT

Simple_Desc_rsp

Parameters

enum ZbStatusCodeT status	Status
uint16_t nwkAddr	NWKAddrOfInterest
struct ZbSimpleDescriptorT simpleDesc	SimpleDescriptor
struct ZbApsRelayInfoT relayInfo	Contains information required to relay the APS packet. (R23+)

21. Zigbee ZCL Core

#include "zcl/zcl.h"

21.1. Functions

21.1.1. ZbZclAppendHeader

int ZbZclAppendHeader(struct ZbZclHeaderT *zclHdrPtr, uint8_t *data, unsigned int max_len);

Builds and appends a ZCL Header to the end of a buffer. Returns length of data written, or negative value (-1) on error.

Parameters

None Return

• Undocumented

21.1.2. ZbZclAttrEuiRead

uint64_t ZbZclAttrEuiRead(struct ZbZclClusterT *cluster, uint16_t attributeId, enum ZclStatusCodeT *statusPtr);

Helper to ZbZclAttrRead to read an EUI-64 attribute value.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
statusPtr	ZCL Status Code that can be returned to caller if pointer provided.

Return

• The EUI-64 value

21.1.3. ZbZclAttrEuiWrite

enum ZclStatusCodeT ZbZclAttrEuiWrite(struct ZbZclClusterT *cluster, uint16_t attributeId, uint64_t eui);

Helper to ZbZclAttrWrite to write an EUI-64 attribute value.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
eui	The EUI-64 value to write to the attribute.

Return

• ZCL Status Code

21.1.4. ZbZclAttrIntegerIncrement

enum ZclStatusCodeT ZbZclAttrIntegerIncrement(struct ZbZclClusterT *cluster,
uint16_t attributeId, long long value);

Helper to ZbZclAttrWrite to read, increment and write an integer attribute value.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
value	The value to increment the attribute by.

Return

• ZCL status code

21.1.5. ZbZclAttrIntegerRead

long long ZbZclAttrIntegerRead(struct ZbZclClusterT *cluster, uint16_t attributeId,
enum ZclDataTypeT *typePtr, enum ZclStatusCodeT *statusPtr);

Helper to ZbZclAttrRead to read an integer attribute value.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
typePtr	If pointer provided, returns the attribute type.
statusPtr	ZCL Status Code that can be returned to caller if pointer provided.

Return

• Value of attribute

21.1.6. ZbZclAttrIntegerWrite

enum ZclStatusCodeT ZbZclAttrIntegerWrite(struct ZbZclClusterT *cluster, uint16_t attributeId, long long value);

Helper to ZbZclAttrWrite to write an integer attribute value.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
value	The value to write to the attribute.

Return

• ZCL status code

21.1.7. ZbZclAttrRead

enum ZclStatusCodeT ZbZclAttrRead(struct ZbZclClusterT *cluster, uint16_t attrId,
enum ZclDataTypeT *attrType, void *outputBuf, unsigned int max_len, bool isReporting);

Reads a local cluster attribute value. Returns the attribute type if provided as a pointer through 'attrType'.

Parameters

cluster	Cluster instance
attrId	Attribute Id of the attribute to read
attrType	Pointer to the attribute type. If not NULL and this function returns ZCL_STATUS_SUCCESS, the type value of the attribute is returned in this parameter.
outputBuf	Buffer to write attribute value data to.
max_len	Maximum length of 'outputBuf'.
isReporting	If true and this attribute is being read for generating a report, the attribute’s flag is checked for ZCL_ATTR_FLAG_REPORTABLE and if not set, a status of ZCL_STATUS_UNREPORTABLE_ATTRIBUTE is returned.

Return

• ZCL status code

21.1.8. ZbZclAttrReportConfigDefault

enum ZclStatusCodeT ZbZclAttrReportConfigDefault(struct ZbZclClusterT *clusterPtr, uint16_t attrId, 
uint16_t default_min, uint16_t default_max, double *default_change);

Configure an attribute’s default reporting intervals. It will also set the active reporting intervals to these values and reset the reporting timer. The Reportable Change value will also be reset back to defaults (value = 1).

Parameters

clusterPtr	Cluster instance
attrId	Attribute Id of the attribute to modify
default_min	New default minimum reporting interval in seconds.
default_max	New default maximum reporting interval in seconds.
default_change	(Optional) New default reportable change value.

Return

• ZCL status code

21.1.9. ZbZclAttrReportConfigReq

enum ZclStatusCodeT ZbZclAttrReportConfigReq(struct ZbZclClusterT *cluster, struct ZbZclAttrReportConfigT *config,
void (*callback)(struct ZbZclCommandRspT *cmd_rsp, void *arg), void *arg);

Send a Configure Reporting Command. Response is returned in the 'callback' if provided by application.

Parameters

cluster	Cluster instance
config	Attribute reporting configuration destination and records
callback	Callback function to receive Configure Reporting Response Command
arg	Callback argument

Return

• ZCL status code

21.1.10. ZbZclAttrReportReadReq

enum ZclStatusCodeT ZbZclAttrReportReadReq(struct ZbZclClusterT *cluster, struct ZbZclAttrReportReadT *report,
void (*callback)(struct ZbZclCommandRspT *cmd_rsp, void *arg), void *arg);

Send a Read Reporting Configuration Command. Response is returned in the 'callback' if provided by application.

Parameters

cluster	Cluster instance
report	Attribute reporting configuration destination and records to read
callback	Callback function to receive Read Reporting Configuration Response Command
arg	Callback argument

Return

• ZCL status code

21.1.11. ZbZclAttrStringWriteLong

enum ZclStatusCodeT ZbZclAttrStringWriteLong(struct ZbZclClusterT *cluster, uint16_t attributeId, const uint8_t *zcl_str);

Helper to ZbZclAttrWrite to write a string attribute value of type ZCL_DATATYPE_STRING_LONG_OCTET or ZCL_DATATYPE_STRING_LONG_CHARACTER.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
zcl_str	ZCL String. First two bytes is the string length.

Return

• ZCL status code

21.1.12. ZbZclAttrStringWriteShort

enum ZclStatusCodeT ZbZclAttrStringWriteShort(struct ZbZclClusterT *cluster, uint16_t attributeId, const uint8_t *zcl_str);

Helper to ZbZclAttrWrite to write a string attribute value of type ZCL_DATATYPE_STRING_OCTET or ZCL_DATATYPE_STRING_CHARACTER.

Parameters

cluster	Cluster instance
attributeId	The attribute Id
zcl_str	ZCL String. First byte is the string length.

Return

• ZCL status code

21.1.13. ZbZclAttrWrite

enum ZclStatusCodeT ZbZclAttrWrite(struct ZbZclClusterT *cluster, const struct ZbApsAddrT *src, uint16_t attr_id, 
const uint8_t *attr_data, unsigned int max_len, ZclWriteModeT mode);

Writes a local cluster’s attribute value.

Parameters

cluster	Cluster instance
src	Source address of this command. May be NULL if generated locally.
attr_id	Attribute Id of the attribute to write
attr_data	Attribute data in ZCL format (i.e. same as what is sent over-the-air)
max_len	Maximum length of attribute data (attr_data) buffer.
mode	Write mode

Return

• ZCL status code

21.1.14. ZbZclClusterCommandReqWithRspFilter

enum ZclStatusCodeT ZbZclClusterCommandReqWithRspFilter(struct ZbZclClusterT *cluster, struct ZbZclClusterCommandReqT *req, 
uint8_t rspCmd, unsigned int delay, void (*callback)(struct ZbZclCommandRspT *zcl_rsp, void *arg), void *arg);

ZbZclClusterCommandReq is a helper wrapper to ZbZclCommandReq. Information from the cluster is used when sending the command (source addressing, APS TX Options).

Parameters

cluster	Cluster instance
req	Request struct pointer
rspCmd	The Command Id of the response to wait for, which is added to the APS filter. This may be set to ZCL_REQ_CMD_RSP_ID_IGNORE, in which case only the matching ZCL sequence number, direction bit, etc, are used. The ZCL Default Response is always added to the APS filter.
delay	Delay in milliseconds. If non-zero, then a copy of the ASDU must be made, and the message is sent later, after the delay time expires.
callback	Callback function. This may be set to NULL.
arg	Callback argument. Provided to the callback function and used by the application.

Return

• ZCL Status Code. If ZCL_STATUS_SUCCESS, the caller can expect the callback once the command is complete. If something other than ZCL_STATUS_SUCCESS, that indicates an error and the callback is never called in that case.

21.1.15. ZbZclClusterRegisterAlarmResetHandler

enum ZclStatusCodeT ZbZclClusterRegisterAlarmResetHandler(struct ZbZclClusterT *cluster, enum ZclStatusCodeT (*callback)
(struct ZbZclClusterT *cluster, uint8_t alarm_code, uint16_t cluster_id, struct ZbApsdeDataIndT *data_ind,
struct ZbZclHeaderT *hdr));

Register a callback handler for the given cluster to receive Alarm "Reset Alarm" and "Reset all alarms" commands.

Parameters

cluster	Cluster instance
callback	Application callback to handle reset alarm(s) commands.

Return

• ZCL status code

21.1.16. ZbZclClusterReportConfirmCallbackAttach

void ZbZclClusterReportConfirmCallbackAttach(struct ZbZclClusterT *cluster, void
(*callback)(struct ZbZclClusterT *cluster));

Attach a confirm callback function to be called on sending ZCL Attribute Report Commands.

Parameters

cluster	Cluster instance
callback	Application callback to handle Report commands.

Return

• None

21.1.17. ZbZclClusterReportsSend

enum ZclStatusCodeT ZbZclClusterReportsSend(struct ZbZclClusterT *cluster, bool send_all, void (*callback)
(struct ZbZclClusterT *cluster, unsigned int next_timeout, void *arg), void *arg);

If the application disables the automatic attribute reporting mechanism in the stack by setting the NIB 'ZB_NWK_NIB_ID_DisablePeriodicTimers' to 1, then the application will need to manually and periodically send reports by calling this function.

Parameters

cluster	Cluster instance
send_all	If true, send all reportable attributes no matter if they have changed or reporting interval has timed-out. Normally, when used by a sleepy device application to manually drive reporting, this parameter should be set to false.
callback	Callback that is called once all reports have been sent. The 'next_timeout' parameter is the time until the next scheduled report, in milliseconds.
arg	Callback argument

Return

• ZCL Status Code. If not ZCL_STATUS_SUCCESS, then callback will not be called.

21.1.18. ZbZclClusterReverseBind

struct ZbApsFilterT * ZbZclClusterReverseBind(struct ZbZclClusterT *cluster);

ZbZclClusterReverseBind is used by the Alarms Server so it can receive loopback messages sent in the direction of the client (i.e. reverse).

Parameters

cluster

Cluster instance

Return

• Filter pointer (handle)

21.1.19. ZbZclClusterReverseUnbind

void ZbZclClusterReverseUnbind(struct ZbZclClusterT *cluster, struct ZbApsFilterT *filter);

Remove the reverse (loopback) filter and free it.

Parameters

cluster	Cluster instance
filter	Filter to remove and free

Return

• None

21.1.20. ZbZclClusterSendAlarm

void ZbZclClusterSendAlarm(struct ZbZclClusterT *cluster, uint8_t src_endpoint, uint8_t alarm_code);

Send an alarm from a cluster as if it originated from the alarms cluster on the same endpoint. Typically, src_endpoint = cluster¬endpoint. If the cluster appears on multiple endpoints (e.g. Basic Cluster), the src_endpoint is required to know which one to actually send the Alarm Command from. The alarm message is sent via APS binding(s).

Parameters

cluster	Cluster instance
src_endpoint
alarm_code

Return

• None

21.1.21. ZbZclCommandReqWithRspFilter

enum ZclStatusCodeT ZbZclCommandReqWithRspFilter(struct ZigBeeT *zb, struct ZbZclCommandReqT *zclReq, 
uint8_t rspCmd, void (*callback)(struct ZbZclCommandRspT *rsp, void *arg), void *arg);

Send a ZCL command. The callback function is called when the associated ZCL response is received, or there’s an error.

Parameters

zb	Zigbee stack instance
zclreq	ZCL Command Request info
rspCmd	The Command Id of the response to wait for, which is added to the APS filter. This may be set to ZCL_REQ_CMD_RSP_ID_IGNORE, in which case only the matching ZCL sequence number, direction bit, etc, are used. The ZCL Default Response is always added to the APS filter.
callback	Callback function to receive ZCL Response
arg	Callback argument

Return

• ZCL Status Code. ZCL_STATUS_SUCCESS if command was sent and caller can wait for the callback to be called. Otherwise, there was a problem sending the command and the callback is never called in this case.

21.1.22. ZbZclIsDefaultRsp

bool ZbZclIsDefaultRsp(struct ZbZclHeaderT *hdr);

This is a helper function that inspects a ZCL header struct and returns true if it’s for a ZCL Default Response command, or false otherwise.

Parameters

hdr	ZCL Header struct

Return

• True if ZCL header indicates it’s for a ZCL Default Response command, or false otherwise.

21.1.23. ZbZclParseHeader

int ZbZclParseHeader(struct ZbZclHeaderT *zclHdrPtr, const uint8_t *buf, unsigned int len);

Parses a ZCL Header from a received frame. Returns Length of the ZCL header, or negative value (-1) on error.

Parameters

None Return

• Undocumented

21.1.24. ZbZclParseInteger

long long ZbZclParseInteger(enum ZclDataTypeT dataType, const uint8_t *data, enum ZclStatusCodeT *statusPtr);

Parses a integer number from a buffer starting at the given pointer and returns it as a long long integer. Note that the length of the buffer isn’t checked. The caller is assumed to have sanity-checked the buffer length already by a call to ZbZclAttrParseLength or ZbZclAttrTypeLength

Parameters

dataType	ZCL Attribute data type.
data	ZCL attribute data.
statusPtr	ZCL Status Code (OUT)

Return

• The parsed value, if *statusPtr == SUCCESS

21.1.25. ZbZclPrependHeader

int ZbZclPrependHeader(struct ZbZclHeaderT *zclHdrPtr, uint8_t *data, unsigned int len);

Builds and appends a ZCL Header to the start of a buffer. Returns length of data written, or negative value (-1) on error.

Parameters

None Return

• Undocumented

21.1.26. zcl_get_bomd_req_queue_timeout_abs

ZbUptimeT zcl_get_bomd_req_queue_timeout_abs(struct ZigBeeT *zb);

Helper function to return the timeout value, based on the BDB parameter 'ZB_BDB_ZclBomdReqQueueTimeoutMs'

Parameters

zb	Zigbee stack instance

Return

• ZbZclUptime() plus the ZB_BDB_ZclBomdReqQueueTimeoutMs value.

21.1.27. zcl_get_bomd_req_wait_timeout_ms

uint32_t zcl_get_bomd_req_wait_timeout_ms(struct ZigBeeT *zb);

Helper function to return value from BDB parameter 'ZB_BDB_ZclBomdReqWaitTimeoutMs'

Parameters

zb	Zigbee stack instance

Return

• Timeout value in milliseconds

21.1.28. zcl_hexstr_to_bin

int zcl_hexstr_to_bin(const char *str, uint8_t *out, unsigned int maxlen);

This is a helper function to convert an ascii string of hexidecimal characters to an array of binary octets. The input string can have upper or lower case hex characters, and must not contain any delimiters. Since this is a helper function, it may change or be removed in the future.

Parameters

str	Input ascii string to convert, null terminated.
out	Output buffer to write converted binary data to.
maxlen	Maximum length of output buffer. If output length would be longer than the maximum length, then -1 is returned.

Return

• Number of bytes written to 'out' or -1 on error.

21.2. Enumerations

21.2.1. ZbZclAttrCbTypeT

Attribute Callback Types

ZCL_ATTR_CB_TYPE_READ	Read attribute callback. Use to have the application handle the ZCL Read Requests, rather than the cluster.
ZCL_ATTR_CB_TYPE_WRITE	Write attribute callback. Used to have the application handle the ZCL Write Requests, rather than the cluster. If not used, the cluster will handle the incoming requests.

21.3. Structures

21.3.1. ZbZclAttrCbInfoT

Attribute callback information

Parameters

const struct ZbZclAttrT *info	Pointer to the original info struct used to create the attribute
enum ZbZclAttrCbTypeT type	Callback type (read, write, etc)
uint8_t *zcl_data	Incoming or outgoing ZCL attribute payload data. If callback type is ZCL_ATTR_CB_TYPE_WRITE, this is the source of the new value, to be validated and written back to attr_data if applicable. If callback type is ZCL_ATTR_CB_TYPE_READ, this is the destination of the value to return in the ZCL Read Response.
unsigned int zcl_len	Maximum length of 'zcl_data'
ZclWriteModeT write_mode	Write mode (e.g. normal, test, force, persist). Only applicable if type == ZCL_ATTR_CB_TYPE_WRITE.
void *attr_data	Pointer to local attribute storage. Only applicable if type == ZCL_ATTR_CB_TYPE_WRITE. If NULL, then application is maintaining attribute value (i.e. both ZCL_ATTR_FLAG_CB_READ and ZCL_ATTR_FLAG_CB_WRITE were set). If not NULL, current attribute value can be read from here, and updated value from WRITE command to be written here.
const struct ZbApsAddrT *src	Source of the command, if not locally generated. May be NULL.
enum ZbStatusCodeT security_status	security_status - The security level used to decrypt the incoming frame. Only valid if 'src' address parameter is not NULL. If present, it will be one of: ZB_APS_STATUS_UNSECURED (no decryption necessary), ZB_APS_STATUS_SECURED_NWK_KEY (decrypted with the Network Key), ZB_APS_STATUS_SECURED_LINK_KEY, (decrypted with a Link Key)
void *app_cb_arg	Application’s defined callback argument

21.3.2. ZbZclAttrT

The structure used to initialize a ZCL attribute when calling ZbZclAttrAppendList.

Parameters

uint16_t attributeId	The attribute ID
enum ZclDataTypeT dataType	The attribute data type (ZCL_DATATYPE_UNKNOWN if last entry)
ZclAttrFlagT flags	Attribute flags (e.g. writeable, reportable, etc)
unsigned int customValSz	A custom size is required if the data type is one of: ZCL_DATATYPE_STRING_OCTET, ZCL_DATATYPE_STRING_CHARACTER, ZCL_DATATYPE_STRING_LONG_OCTET, ZCL_DATATYPE_STRING_LONG_CHARACTER, ZCL_DATATYPE_ARRAY, ZCL_DATATYPE_STRUCT, ZCL_DATATYPE_SET, ZCL_DATATYPE_BAG A custom size is also required if both customRead and customWrite callbacks are provided and ZCL_ATTR_FLAG_PERSISTABLE is set. The maximum size should not exceed ZB_APS_CONST_MAX_FRAG_SIZE.
callback (callback function pointer)	enum ZclStatusCodeT (*callback)(struct ZbZclClusterT *cluster, struct ZbZclAttrCbInfoT *info) If flags ZCL_ATTR_FLAG_CB_READ or ZCL_ATTR_FLAG_CB_WRITE are set, then this callback is called for attribute read or write commands.
struct { double min	Optional integer attribute value range. If both are set to zero, range checking is disabled.
struct { uint16_t interval_min	Default minimum reporting interval in seconds.
uint16_t interval_max	Default maximum reporting interval in seconds.

22. Touchlink

#include "zcl/zcl.touchlink.h"

22.1. Functions

22.1.1. ZbZclTouchlinkInitiatorGetEpListReq

enum ZclStatusCodeT ZbZclTouchlinkInitiatorGetEpListReq(struct ZigBeeT *zb, struct ZbTlGetEpListReqCmd *cmd, const struct ZbApsAddrT *dst,
void (*callback)(struct ZbTlGetEpListRspCmd *rsp, void *arg), void *arg);

Sends a Touchlink Utility Get Endpoint List Request Command

Parameters

zb	Zigbee stack instance
dst	Destination address
cmd	Get Endpoint List Request Command structure
callback	Callback function that will be invoked when the response is received.
arg	Pointer to application data that will included in the callback when invoked.

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

22.1.2. ZbZclTouchlinkInitiatorGetGrpIdReq

enum ZclStatusCodeT ZbZclTouchlinkInitiatorGetGrpIdReq(struct ZigBeeT *zb, struct ZbTlGetGroupIdsReqCmd *cmd, const struct ZbApsAddrT *dst,
void (*callback)(struct ZbTlGetGroupIdsRspCmd *rsp, void *arg), void *arg);

Sends a Touchlink Utility Get Group Identifiers Request Command

Parameters

zb	Zigbee stack instance
dst	Destination address
cmd	Get Group Identifiers Request structure
callback	Callback function that will be invoked when the response is received.
arg	Pointer to application data that will included in the callback when invoked.

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

22.1.3. ZbZclTouchlinkTargetSendEpInfoCmd

enum ZclStatusCodeT ZbZclTouchlinkTargetSendEpInfoCmd(struct ZigBeeT *zb, uint8_t endpoint, const struct ZbApsAddrT *dst,
void (*callback)(struct ZbZclCommandRspT *zcl_rsp, void *arg), void *arg);

Sends a Touchlink Utility Endpoint Information Command

Parameters

zb	Zigbee stack instance
endpoint	Endpoint identifier. Must match the endpoint already registered with Touchlink through the ZbStartup configuration, otherwise an error is returned.
dst	Destination address
callback	Callback function that will be invoked when the response is received.

Return

• ZCL_STATUS_SUCCESS if successful, or other ZclStatusCodeT value on error

22.2. Structures

22.2.1. ZbTlEndpointList

Endpoint Information Record entry

Parameters

uint16_t nwkAddr	Network address
uint8_t endpoint	Endpoint identifier
uint16_t profileId	Profile identifier
uint16_t deviceId	Device identifier
uint8_t version	Version

22.2.2. ZbTlEpInfoCmd

Endpoint Information command

Parameters

uint64_t ieeeAddr	IEEE address
uint16_t nwkAddr	Network address
uint8_t endpoint	Endpoint identifier
uint16_t profileId	Profile identifier
uint16_t deviceId	Device identifier
uint8_t version	Version

22.2.3. ZbTlGetEpListReqCmd

Get Endpoint List Request command

Parameters

uint8_t startIdx

Start Index

22.2.4. ZbTlGetEpListRspCmd

Get Endpoint List Response command

Parameters

enum ZclStatusCodeT status	ZCL Status code
uint8_t total	Total
uint8_t startIdx	Start index
uint8_t count	Count
struct ZbTlEndpointList endpoint_list	Endpoint Information Record Entry

22.2.5. ZbTlGetGroupIdsReqCmd

Get Group Identifiers Request command

Parameters

uint8_t startIdx

Start Index

22.2.6. ZbTlGetGroupIdsRspCmd

Get Group Identifiers Response command

Parameters

enum ZclStatusCodeT status	ZCL status code
uint8_t total	Total
uint8_t startIdx	Start index
uint8_t count	Count
struct ZbTlGroupRecordList record_list	Group Information Record List

22.2.7. ZbTlGroupRecordList

Group Information Record list

Parameters

uint16_t groupId	Group list
uint8_t groupType	Group type - Must be 0

22.2.8. ZbTouchlinkCallbacks

Zigbee Touchlink callback functions for Touchlink Controller Device Utility commands. These are configured by "struct ZbStartupT" with ZbStartup().

Parameters

ep_info_cb (callback function pointer)

enum ZclStatusCodeT (*ep_info_cb)(struct ZigBeeT *zb, struct ZbTlEpInfoCmd *cmd, struct ZbZclAddrInfoT *srcInfo, void *arg) Endpoint Info callback

23. Key Exchange (CBKE)

#include "zcl/key/zcl.key.h"

23.1. Description

The Certificate-based Key Establishment (CBKE) cluster is handled internally by the stack. When CBKE is enabled, the stack creates an instance of the CBKE cluster. There is no exposed public API to the CBKE cluster itself. CBKE is configured in the security.cbke (struct ZbStartupCbkeT) section of the ZbStartupT startup config. The basic setup procedure is to enable the supported suites in suite_mask and load the corresponding suite configuration and certificates for the enabled suites into the startup config before starting the stack.

CBKE configuration struct for ZbStartup. This is only applicable if the 'suite_mask' is non-zero.

ZbStartupCbkeT

uint8_t endpoint	Endpoint to assign ZCL Key Exchange cluster. Default is ZB_ENDPOINT_CBKE_DEFAULT (240)
uint16_t deviceId	Device Id to assign to the endpoint created for the ZCL Key Exchange cluster. Default is ZCL_DEVICE_METER.
uint16_t suite_mask	The Key Exchange suite bitmask. E.g. ZCL_KEY_SUITE_CBKE2_ECMQV for CBKE version 2 (cbke_v2). If the suite_mask is empty (zero), then no Key Establishment or Keep Alive features are enabled.
struct ZbZclCbkeInfoT cbke_v1	CBKE version 1 certificate and security keys configuration. Only applicable if ZCL_KEY_SUITE_CBKE_ECMQV is set in suite_mask.
struct ZbZclCbke2InfoT cbke_v2	CBKE version 2 certificate and security keys configuration. Only applicable if ZCL_KEY_SUITE_CBKE2_ECMQV is set in suite_mask.
bool tc_keepalive_server_enable	Determines whether to allocate the Keep Alive Server or Client cluster.
uint8_t tc_keepalive_base	Trust Center Keep Alive Server 'Base' attribute value in minutes. If zero, let the stack choose a default value.
uint8_t tc_keepalive_jitter	Trust Center Keep Alive Server 'Jitter' attribute value in seconds. If zero, let the stack choose a default value.
void (*tcso_callback)(enum ZbTcsoStatusT status, void *arg)	Application callback which is called for any Trust Center Swap Out (TCSO) process initiated by the Keep Alive Client cluster. This includes when a TCSO has been started and the final outcome of a TCSO process.
void *tcso_arg	Application callback argument for tcso_callback.

24. Appendix A: Zigbee status codes

24.1. NWK status codes

Status Value	Status Code
0x00	ZB_NWK_STATUS_SUCCESS
0xc1	ZB_NWK_STATUS_INVALID_PARAMETER
0xc2	ZB_NWK_STATUS_INVALID_REQUEST
0xc3	ZB_NWK_STATUS_NOT_PERMITTED
0xc4	ZB_NWK_STATUS_STARTUP_FAILURE
0xc5	ZB_NWK_STATUS_ALREADY_PRESENT
0xc6	ZB_NWK_STATUS_SYNC_FAILURE
0xc7	ZB_NWK_STATUS_TABLE_FULL
0xc8	ZB_NWK_STATUS_UNKNOWN_DEVICE
0xc9	ZB_NWK_STATUS_UNSUPPORTED_ATTRIBUTE
0xca	ZB_NWK_STATUS_NO_NETWORKS
0xcb	ZB_NWK_STATUS_LEAVE_UNCONFIRMED
0xcc	ZB_NWK_STATUS_MAX_FRM_CNTR
0xcd	ZB_NWK_STATUS_NO_KEY
0xce	ZB_NWK_STATUS_BAD_CCM_OUTPUT
0xcf	ZB_NWK_STATUS_NO_ROUTING_CAPACITY
0xd0	ZB_NWK_STATUS_ROUTE_DISCOVERY_FAILED
0xd1	ZB_NWK_STATUS_ROUTE_ERROR
0xd2	ZB_NWK_STATUS_BT_TABLE_FULL
0xd3	ZB_NWK_STATUS_FRAME_NOT_BUFFERED
0xd4	ZB_NWK_STATUS_INVALID_INDEX
0xd5	ZB_NWK_STATUS_INTERNAL_ERR

24.1.1. WPAN Status Codes

Status Value	Status Code
0x00	ZB_WPAN_STATUS_SUCCESS
0xdb	ZB_WPAN_STATUS_COUNTER_ERROR
0xdc	ZB_WPAN_STATUS_IMPROPER_KEY_TYPE
0xdd	ZB_WPAN_STATUS_IMPROPER_SECURITY_LEVEL
0xde	ZB_WPAN_STATUS_UNSUPPORTED_LEGACY
0xdf	ZB_WPAN_STATUS_UNSUPPORTED_SECURITY
0xe0	ZB_WPAN_STATUS_BEACON_LOSS
0xe1	ZB_WPAN_STATUS_CHANNEL_ACCESS_FAILURE
0xe2	ZB_WPAN_STATUS_DENIED
0xe3	ZB_WPAN_STATUS_DISABLE_TRX_FAILURE
0xe4	ZB_WPAN_STATUS_SECURITY_ERROR
0xe5	ZB_WPAN_STATUS_FRAME_TOO_LONG
0xe6	ZB_WPAN_STATUS_INVALID_GTS
0xe7	ZB_WPAN_STATUS_INVALID_HANDLE
0xe8	ZB_WPAN_STATUS_INVALID_PARAMETER
0xe9	ZB_WPAN_STATUS_NO_ACK
0xea	ZB_WPAN_STATUS_NO_BEACON
0xeb	ZB_WPAN_STATUS_NO_DATA
0xec	ZB_WPAN_STATUS_NO_SHORT_ADDRESS
0xed	ZB_WPAN_STATUS_OUT_OF_CAP
0xee	ZB_WPAN_STATUS_PAN_ID_CONFLICT
0xef	ZB_WPAN_STATUS_REALIGNMENT
0xf0	ZB_WPAN_STATUS_TRANSACTION_EXPIRED
0xf1	ZB_WPAN_STATUS_TRANSACTION_OVERFLOW
0xf2	ZB_WPAN_STATUS_TX_ACTIVE
0xf3	ZB_WPAN_STATUS_UNAVAILABLE_KEY
0xf4	ZB_WPAN_STATUS_UNSUPPORTED_ATTRIBUTE
0xf5	ZB_WPAN_STATUS_INVALID_ADDRESS
0xf6	ZB_WPAN_STATUS_ON_TIME_TOO_LONG
0xf7	ZB_WPAN_STATUS_PAST_TIME
0xf8	ZB_WPAN_STATUS_TRACKING_OFF
0xf9	ZB_WPAN_STATUS_INVALID_INDEX
0xfa	ZB_WPAN_STATUS_LIMIT_REACHED
0xfb	ZB_WPAN_STATUS_READ_ONLY
0xfc	ZB_WPAN_STATUS_SCAN_IN_PROGRESS
0xfd	ZB_WPAN_STATUS_SUPERFRAME_OVERLAP
0xfe	ZB_WPAN_STATUS_DRIVER_ERROR
0xff	ZB_WPAN_STATUS_DEVICE_ERROR

24.1.2. ZCL status codes

Status Value	Status Code
0z00	ZCL_STATUS_SUCCESS
0x01	ZCL_STATUS_FAILURE
0x70	ZCL_STATUS_ALLOC_FAIL
0x7e	ZCL_STATUS_NOT_AUTHORIZED
0x80	ZCL_STATUS_MALFORMED_COMMAND
0x81	ZCL_STATUS_UNSUPP_CLUSTER_COMMAND
0x82	ZCL_STATUS_UNSUPP_GENERAL_COMMAND
0x83	ZCL_STATUS_UNSUPP_MFR_CLUSTER_COMMAND
0x84	ZCL_STATUS_UNSUPP_MFR_GENERAL_COMMAND
0x85	ZCL_STATUS_INVALID_FIELD
0x86	ZCL_STATUS_UNSUPP_ATTRIBUTE
0x87	ZCL_STATUS_INVALID_VALUE
0x88	ZCL_STATUS_READ_ONLY
0x89	ZCL_STATUS_INSUFFICIENT_SPACE
0x8a	ZCL_STATUS_DUPLICATE_EXISTS
0x8b	ZCL_STATUS_NOT_FOUND
0x8c	ZCL_STATUS_UNREPORTABLE_ATTRIBUTE
0x8d	ZCL_STATUS_INVALID_DATA_TYPE
0x8e	ZCL_STATUS_INVALID_SELECTOR
0x8f	ZCL_STATUS_WRITE_ONLY
0x90	ZCL_STATUS_INCONSISTENT_STARTUP_STATE
0x91	ZCL_STATUS_DEFINED_OUT_OF_BAND
0x92	ZCL_STATUS_INCONSISTENT
0x93	ZCL_STATUS_ACTION_DENIED
0x94	ZCL_STATUS_TIMEOUT
0x95	ZCL_STATUS_ABORT
0x96	ZCL_STATUS_INVALID_IMAGE
0x97	ZCL_STATUS_WAIT_FOR_DATA
0x98	ZCL_STATUS_NO_IMAGE_AVAILABLE
0x99	ZCL_STATUS_REQUIRE_MORE_IMAGE
0x9A	ZCL_STATUS_NOTIFICATION_PENDING
0xc0	ZCL_STATUS_HARDWARE_FAILURE
0xc1	ZCL_STATUS_SOFTWARE_FAILURE
0xc2	ZCL_STATUS_CALIBRATION_ERROR
0xc3	ZCL_STATUS_UNSUPP_CLUSTER
0xc4	ZCL_STATUS_LIMIT_REACHED

24.1.3. Trust Center Swap Out status codes

Status Value	Status Code
0x00	ZB_TCSO_STATUS_SUCCESS
0x01	ZB_TCSO_STATUS_DISCOVERY_UNDERWAY
0x02	ZB_TCSO_STATUS_REJOIN_PREV
0x03	ZB_TCSO_STATUS_NOT_FOUND
0x04	ZB_TCSO_STATUS_FATAL

24.1.4. Key Establishment status codes

Status Value	Status Code
0x00	ZCL_KEY_STATUS_SUCCESS
0x01	ZCL_KEY_STATUS_UNKNOWN_ISSUER
0x02	ZCL_KEY_STATUS_BAD_KEY_CONFIRM
0x03	ZCL_KEY_STATUS_BAD_MESSAGE
0x04	ZCL_KEY_STATUS_NO_RESOURCES
0x05	ZCL_KEY_STATUS_UNSUPPORTED_SUITE
0x06	ZCL_KEY_STATUS_INVALID_CERTIFICATE
0x07	ZCL_KEY_STATUS_TIMEOUT
0x08	ZCL_KEY_STATUS_MATCH_DESC_FAILED