ZigBee Device Object (ZDO) functions available on all platforms. See ZigBee Device Object (ZDO) Information for documentation.

License#

Copyright 2018 Silicon Laboratories Inc. www.silabs.com

The licensor of this software is Silicon Laboratories Inc. Your use of this software is governed by the terms of Silicon Labs Master Software License Agreement (MSLA) available at www.silabs.com/about-us/legal/master-software-license-agreement. This software is distributed to you in Source Code format and is governed by the sections of the MSLA applicable to Source Code.

/***************************************************************************/
#ifndef SILABS_ZIGBEE_DEVICE_COMMON_H
#define SILABS_ZIGBEE_DEVICE_COMMON_H

#define ZDO_MESSAGE_OVERHEAD 1

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberNodeDescriptorRequest(EmberNodeId target,
                                       EmberApsOption options);
#else
// Macroized to save code space.
EmberStatus emberSendZigDevRequestTarget(EmberNodeId target,
                                         uint16_t clusterId,
                                         EmberApsOption options);
#define emberNodeDescriptorRequest(target, opts) \
  (emberSendZigDevRequestTarget((target), NODE_DESCRIPTOR_REQUEST, (opts)))
#endif

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberPowerDescriptorRequest(EmberNodeId target,
                                        EmberApsOption options);
#else
// Macroized to save code space.
#define emberPowerDescriptorRequest(target, opts) \
  (emberSendZigDevRequestTarget((target), POWER_DESCRIPTOR_REQUEST, (opts)))
#endif

EmberStatus emberSimpleDescriptorRequest(EmberNodeId target,
                                         uint8_t targetEndpoint,
                                         EmberApsOption options);

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberActiveEndpointsRequest(EmberNodeId target,
                                        EmberApsOption options);
#else
// Macroized to save code space.
#define emberActiveEndpointsRequest(target, opts) \
  (emberSendZigDevRequestTarget((target), ACTIVE_ENDPOINTS_REQUEST, (opts)))
#endif

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberBindRequest(EmberNodeId target,
                             EmberEUI64 source,
                             uint8_t sourceEndpoint,
                             uint16_t clusterId,
                             uint8_t type,
                             EmberEUI64 destination,
                             EmberMulticastId groupAddress,
                             uint8_t destinationEndpoint,
                             EmberApsOption options);
#else
// Macroized to save code space.
#define emberBindRequest(target,                              \
                         src,                                 \
                         srcEndpt,                            \
                         cluster,                             \
                         type,                                \
                         dest,                                \
                         groupAddress,                        \
                         destEndpt,                           \
                         opts)                                \
                                                              \
  (emberSendZigDevBindRequest((target),                       \
                              BIND_REQUEST,                   \
                              (src), (srcEndpt), (cluster),   \
                              (type), (dest), (groupAddress), \
                              (destEndpt), (opts)))

EmberStatus emberSendZigDevBindRequest(EmberNodeId target,
                                       uint16_t bindClusterId,
                                       EmberEUI64 source,
                                       uint8_t sourceEndpoint,
                                       uint16_t clusterId,
                                       uint8_t type,
                                       EmberEUI64 destination,
                                       EmberMulticastId groupAddress,
                                       uint8_t destinationEndpoint,
                                       EmberApsOption options);
#endif

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberUnbindRequest(EmberNodeId target,
                               EmberEUI64 source,
                               uint8_t sourceEndpoint,
                               uint16_t clusterId,
                               uint8_t type,
                               EmberEUI64 destination,
                               EmberMulticastId groupAddress,
                               uint8_t destinationEndpoint,
                               EmberApsOption options);
#else
// Macroized to save code space.
#define emberUnbindRequest(target,                            \
                           src,                               \
                           srcEndpt,                          \
                           cluster,                           \
                           type,                              \
                           dest,                              \
                           groupAddress,                      \
                           destEndpt,                         \
                           opts)                              \
                                                              \
  (emberSendZigDevBindRequest((target),                       \
                              UNBIND_REQUEST,                 \
                              (src), (srcEndpt), (cluster),   \
                              (type), (dest), (groupAddress), \
                              (destEndpt), (opts)))
#endif

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberLqiTableRequest(EmberNodeId target,
                                 uint8_t startIndex,
                                 EmberApsOption options);
#else
#define emberLqiTableRequest(target, startIndex, options) \
  (emberTableRequest(LQI_TABLE_REQUEST, (target), (startIndex), (options)))

EmberStatus emberTableRequest(uint16_t clusterId,
                              EmberNodeId target,
                              uint8_t startIndex,
                              EmberApsOption options);
#endif

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberRoutingTableRequest(EmberNodeId target,
                                     uint8_t startIndex,
                                     EmberApsOption options);
#else
#define emberRoutingTableRequest(target, startIndex, options) \
  (emberTableRequest(ROUTING_TABLE_REQUEST, (target), (startIndex), (options)))
#endif

#ifdef DOXYGEN_SHOULD_SKIP_THIS
EmberStatus emberBindingTableRequest(EmberNodeId target,
                                     uint8_t startIndex,
                                     EmberApsOption options);
#else
#define emberBindingTableRequest(target, startIndex, options) \
  (emberTableRequest(BINDING_TABLE_REQUEST, (target), (startIndex), (options)))
#endif

EmberStatus emberLeaveRequest(EmberNodeId target,
                              EmberEUI64 deviceAddress,
                              uint8_t leaveRequestFlags,
                              EmberApsOption options);

EmberStatus emberPermitJoiningRequest(EmberNodeId target,
                                      uint8_t duration,
                                      uint8_t authentication,
                                      EmberApsOption options);

#ifdef DOXYGEN_SHOULD_SKIP_THIS

void emberSetZigDevRequestRadius(uint8_t radius);

uint8_t emberGetZigDevRequestRadius(void);
uint8_t emberGetLastZigDevRequestSequence(void);
#else
extern uint8_t zigDevRequestRadius;
#define emberGetZigDevRequestRadius() (zigDevRequestRadius)
#define emberSetZigDevRequestRadius(x)        (zigDevRequestRadius = x)
#define emberGetLastZigDevRequestSequence() \
  (emberGetLastAppZigDevRequestSequence())
#endif

uint8_t emberGetLastAppZigDevRequestSequence(void);

#ifndef DOXYGEN_SHOULD_SKIP_THIS
//------------------------------------------------------------------------------
// Utility functions used by the library code.

EmberStatus emberSendZigDevRequest(EmberNodeId destination,
                                   uint16_t clusterId,
                                   EmberApsOption options,
                                   uint8_t *contents,
                                   uint8_t length);

uint8_t emberNextZigDevRequestSequence(void);

#endif // DOXYGEN_SHOULD_SKIP_THIS

#endif // SILABS_ZIGBEE_DEVICE_COMMON_H

Service Discovery Functions#

emberNodeDescriptorRequest(EmberNodeId target, EmberApsOption options)

Request the specified node to send its node descriptor. The node descriptor contains information about the capabilities of the ZigBee node. It describes logical type, APS flags, frequency band, MAC capabilities flags, manufacturer code and maximum buffer size. It is defined in the ZigBee Application Framework Specification.

emberPowerDescriptorRequest(EmberNodeId target, EmberApsOption options)

Request the specified node to send its power descriptor. The power descriptor gives a dynamic indication of the power status of the node. It describes current power mode, available power sources, current power source and current power source level. It is defined in the ZigBee Application Framework Specification.

emberSimpleDescriptorRequest(EmberNodeId target, uint8_t targetEndpoint, EmberApsOption options)

Request the specified node to send the simple descriptor for the specified endpoint. The simple descriptor contains information specific to a single endpoint. It describes the application profile identifier, application device identifier, application device version, application flags, application input clusters and application output clusters. It is defined in the ZigBee Application Framework Specification.

emberActiveEndpointsRequest(EmberNodeId target, EmberApsOption options)

Request the specified node to send a list of its active endpoints. An active endpoint is one for which a simple descriptor is available.

Binding Manager Functions#

emberBindRequest(EmberNodeId target, EmberEUI64 source, uint8_t sourceEndpoint, uint16_t clusterId, uint8_t type, EmberEUI64 destination, EmberMulticastId groupAddress, uint8_t destinationEndpoint, EmberApsOption options)

Send a request to create a binding entry with the specified contents on the specified node.

emberUnbindRequest(EmberNodeId target, EmberEUI64 source, uint8_t sourceEndpoint, uint16_t clusterId, uint8_t type, EmberEUI64 destination, EmberMulticastId groupAddress, uint8_t destinationEndpoint, EmberApsOption options)

Send a request to remove a binding entry with the specified contents from the specified node.

Node Manager Functions#

emberLqiTableRequest(EmberNodeId target, uint8_t startIndex, EmberApsOption options)

Request the specified node to send its LQI (neighbor) table. The response gives PAN ID, EUI64, node ID and cost for each neighbor. The EUI64 is only available if security is enabled. The other fields in the response are set to zero. The response format is defined in the ZigBee Device Profile Specification.

emberRoutingTableRequest(EmberNodeId target, uint8_t startIndex, EmberApsOption options)

Request the specified node to send its routing table. The response gives destination node ID, status and many-to-one flags, and the next hop node ID. The response format is defined in the ZigBee Device Profile Specification.

emberBindingTableRequest(EmberNodeId target, uint8_t startIndex, EmberApsOption options)

Request the specified node to send its nonvolatile bindings. The response gives source address, source endpoint, cluster ID, destination address and destination endpoint for each binding entry. The response format is defined in the ZigBee Device Profile Specification. Note that bindings that have the Ember-specific UNICAST_MANY_TO_ONE_BINDING type are reported as having the standard UNICAST_BINDING type.

emberLeaveRequest(EmberNodeId target, EmberEUI64 deviceAddress, uint8_t leaveRequestFlags, EmberApsOption options)

Request the specified node to remove the specified device from the network. The device to be removed must be the node to which the request is sent or one of its children.

emberPermitJoiningRequest(EmberNodeId target, uint8_t duration, uint8_t authentication, EmberApsOption options)

Request the specified node to allow or disallow association.

void

Change the default radius for broadcast ZDO requests.

uint8_t

Retrieve the default radius for broadcast ZDO requests.

uint8_t

Provide access to the application ZDO transaction sequence number for last request. This function has been deprecated and replaced by emberGetLastAppZigDevRequestSequence().

uint8_t

Provide access to the application ZDO transaction sequence number for last request.

Macros#

#define

ZDO messages start with a sequence number.

Service Discovery Functions Documentation#

emberNodeDescriptorRequest#

EmberStatus emberNodeDescriptorRequest (EmberNodeId target, EmberApsOption options)

Request the specified node to send its node descriptor. The node descriptor contains information about the capabilities of the ZigBee node. It describes logical type, APS flags, frequency band, MAC capabilities flags, manufacturer code and maximum buffer size. It is defined in the ZigBee Application Framework Specification.

Parameters
N/Atarget

The node whose node descriptor is desired.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 50 of file app/util/zigbee-framework/zigbee-device-common.h

emberPowerDescriptorRequest#

EmberStatus emberPowerDescriptorRequest (EmberNodeId target, EmberApsOption options)

Request the specified node to send its power descriptor. The power descriptor gives a dynamic indication of the power status of the node. It describes current power mode, available power sources, current power source and current power source level. It is defined in the ZigBee Application Framework Specification.

Parameters
N/Atarget

The node whose power descriptor is desired.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 77 of file app/util/zigbee-framework/zigbee-device-common.h

emberSimpleDescriptorRequest#

EmberStatus emberSimpleDescriptorRequest (EmberNodeId target, uint8_t targetEndpoint, EmberApsOption options)

Request the specified node to send the simple descriptor for the specified endpoint. The simple descriptor contains information specific to a single endpoint. It describes the application profile identifier, application device identifier, application device version, application flags, application input clusters and application output clusters. It is defined in the ZigBee Application Framework Specification.

Parameters
N/Atarget

The node of interest.

N/AtargetEndpoint

The endpoint on the target node whose simple descriptor is desired.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 103 of file app/util/zigbee-framework/zigbee-device-common.h

emberActiveEndpointsRequest#

EmberStatus emberActiveEndpointsRequest (EmberNodeId target, EmberApsOption options)

Request the specified node to send a list of its active endpoints. An active endpoint is one for which a simple descriptor is available.

Parameters
N/Atarget

The node whose active endpoints are desired.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 120 of file app/util/zigbee-framework/zigbee-device-common.h

Binding Manager Functions Documentation#

emberBindRequest#

EmberStatus emberBindRequest (EmberNodeId target, EmberEUI64 source, uint8_t sourceEndpoint, uint16_t clusterId, uint8_t type, EmberEUI64 destination, EmberMulticastId groupAddress, uint8_t destinationEndpoint, EmberApsOption options)

Send a request to create a binding entry with the specified contents on the specified node.

Parameters
N/Atarget

The node on which the binding will be created.

N/Asource

The source EUI64 in the binding entry.

N/AsourceEndpoint

The source endpoint in the binding entry.

N/AclusterId

The cluster ID in the binding entry.

N/Atype

The type of binding, either UNICAST_BINDING, MULTICAST_BINDING, or UNICAST_MANY_TO_ONE_BINDING. UNICAST_MANY_TO_ONE_BINDING is an Ember-specific extension and should be used only when the target is an Ember device.

N/Adestination

The destination EUI64 in the binding entry for UNICAST_BINDING or UNICAST_MANY_TO_ONE_BINDING.

N/AgroupAddress

The group address for the MULTICAST_BINDING.

N/AdestinationEndpoint

The destination endpoint in the binding entry for the UNICAST_BINDING or UNICAST_MANY_TO_ONE_BINDING.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 158 of file app/util/zigbee-framework/zigbee-device-common.h

emberUnbindRequest#

EmberStatus emberUnbindRequest (EmberNodeId target, EmberEUI64 source, uint8_t sourceEndpoint, uint16_t clusterId, uint8_t type, EmberEUI64 destination, EmberMulticastId groupAddress, uint8_t destinationEndpoint, EmberApsOption options)

Send a request to remove a binding entry with the specified contents from the specified node.

Parameters
N/Atarget

The node on which the binding will be removed.

N/Asource

The source EUI64 in the binding entry.

N/AsourceEndpoint

The source endpoint in the binding entry.

N/AclusterId

The cluster ID in the binding entry.

N/Atype

The type of binding, either UNICAST_BINDING, MULTICAST_BINDING, or UNICAST_MANY_TO_ONE_BINDING. UNICAST_MANY_TO_ONE_BINDING is an Ember-specific extension and should be used only when the target is an Ember device.

N/Adestination

The destination EUI64 in the binding entry for the UNICAST_BINDING or UNICAST_MANY_TO_ONE_BINDING.

N/AgroupAddress

The group address for the MULTICAST_BINDING.

N/AdestinationEndpoint

The destination endpoint in the binding entry for the UNICAST_BINDING or UNICAST_MANY_TO_ONE_BINDING.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 224 of file app/util/zigbee-framework/zigbee-device-common.h

Node Manager Functions Documentation#

emberLqiTableRequest#

EmberStatus emberLqiTableRequest (EmberNodeId target, uint8_t startIndex, EmberApsOption options)

Request the specified node to send its LQI (neighbor) table. The response gives PAN ID, EUI64, node ID and cost for each neighbor. The EUI64 is only available if security is enabled. The other fields in the response are set to zero. The response format is defined in the ZigBee Device Profile Specification.

Parameters
N/Atarget

The node whose LQI table is desired.

N/AstartIndex

The index of the first neighbor to include in the response.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 275 of file app/util/zigbee-framework/zigbee-device-common.h

emberRoutingTableRequest#

EmberStatus emberRoutingTableRequest (EmberNodeId target, uint8_t startIndex, EmberApsOption options)

Request the specified node to send its routing table. The response gives destination node ID, status and many-to-one flags, and the next hop node ID. The response format is defined in the ZigBee Device Profile Specification.

Parameters
N/Atarget

The node whose routing table is desired.

N/AstartIndex

The index of the first route entry to include in the response.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 305 of file app/util/zigbee-framework/zigbee-device-common.h

emberBindingTableRequest#

EmberStatus emberBindingTableRequest (EmberNodeId target, uint8_t startIndex, EmberApsOption options)

Request the specified node to send its nonvolatile bindings. The response gives source address, source endpoint, cluster ID, destination address and destination endpoint for each binding entry. The response format is defined in the ZigBee Device Profile Specification. Note that bindings that have the Ember-specific UNICAST_MANY_TO_ONE_BINDING type are reported as having the standard UNICAST_BINDING type.

Parameters
N/Atarget

The node whose binding table is desired.

N/AstartIndex

The index of the first binding entry to include in the response.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 331 of file app/util/zigbee-framework/zigbee-device-common.h

emberLeaveRequest#

EmberStatus emberLeaveRequest (EmberNodeId target, EmberEUI64 deviceAddress, uint8_t leaveRequestFlags, EmberApsOption options)

Request the specified node to remove the specified device from the network. The device to be removed must be the node to which the request is sent or one of its children.

Parameters
N/Atarget

The node which will remove the device.

N/AdeviceAddress

All zeros if the target is to remove itself from the network or the EUI64 of a child of the target device to remove that child.

N/AleaveRequestFlags

A bitmask of leave options. Include LEAVE_REQUEST_REMOVE_CHILDREN_FLAG if the target is to remove their children and/or LEAVE_REQUEST_REJOIN_FLAG if the target is to rejoin the network immediately after leaving.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description.

Returns


Definition at line 358 of file app/util/zigbee-framework/zigbee-device-common.h

emberPermitJoiningRequest#

EmberStatus emberPermitJoiningRequest (EmberNodeId target, uint8_t duration, uint8_t authentication, EmberApsOption options)

Request the specified node to allow or disallow association.

Parameters
N/Atarget

The node which will allow or disallow association. The request can be broadcast by using a broadcast address (0xFFFC/0xFFFD/0xFFFF). No response is sent if the request is broadcast.

N/Aduration

A value of 0x00 disables joining. A value of 0xFF enables joining. Any other value enables joining for that number of seconds.

N/Aauthentication

Controls Trust Center authentication behavior.

N/Aoptions

The options to use when sending the request. See emberSendUnicast() for a description. This parameter is ignored if the target is a broadcast address.

Returns


Definition at line 379 of file app/util/zigbee-framework/zigbee-device-common.h

emberSetZigDevRequestRadius#

void emberSetZigDevRequestRadius (uint8_t radius)

Change the default radius for broadcast ZDO requests.

Parameters
N/Aradius

The radius to be used for future ZDO request broadcasts.


Definition at line 390 of file app/util/zigbee-framework/zigbee-device-common.h

emberGetZigDevRequestRadius#

uint8_t emberGetZigDevRequestRadius (void )

Retrieve the default radius for broadcast ZDO requests.

Parameters
N/A

Returns

  • The radius to be used for future ZDO request broadcasts.


Definition at line 397 of file app/util/zigbee-framework/zigbee-device-common.h

emberGetLastZigDevRequestSequence#

uint8_t emberGetLastZigDevRequestSequence (void )

Provide access to the application ZDO transaction sequence number for last request. This function has been deprecated and replaced by emberGetLastAppZigDevRequestSequence().

Parameters
N/A

Returns

  • Last application ZDO transaction sequence number used


Definition at line 405 of file app/util/zigbee-framework/zigbee-device-common.h

emberGetLastAppZigDevRequestSequence#

uint8_t emberGetLastAppZigDevRequestSequence (void )

Provide access to the application ZDO transaction sequence number for last request.

Parameters
N/A

Returns

  • Last application ZDO transaction sequence number used


Definition at line 420 of file app/util/zigbee-framework/zigbee-device-common.h

Macro Definition Documentation#

ZDO_MESSAGE_OVERHEAD#

#define ZDO_MESSAGE_OVERHEAD
Value:
1

ZDO messages start with a sequence number.


Definition at line 29 of file app/util/zigbee-framework/zigbee-device-common.h