ZDO Common

Zigbee Device Object (ZDO) definition for ESP Zigbee SDK.

API Reference

Header File

Structures

struct esp_zb_app_signal_msg_t

The struct of esp zboss app signal message table.

Public Members

esp_zb_app_signal_type_t signal

The signal type of Zigbee

const char *msg

The string of Zigbee signal

struct esp_zb_zdo_signal_leave_params_s

The payload of ESP_ZB_ZDO_SIGNAL_LEAVE signal.

Public Members

uint8_t leave_type

Leave type, refer to esp_zb_nwk_leave_type_t

struct esp_zb_zdo_signal_leave_indication_params_s

The payload of ESP_ZB_ZDO_SIGNAL_LEAVE_INDICATION signal.

Public Members

uint16_t short_addr

Short address of device requested to leave or leaving device

esp_zb_ieee_addr_t device_addr

Long address of device requested to leave or leaving device

uint8_t rejoin

1 if this was leave with rejoin; 0 - otherwise

struct esp_zb_zdo_signal_can_sleep_params_s

The payload of ESP_ZB_COMMON_SIGNAL_CAN_SLEEP signal.

Public Members

uint32_t sleep_duration

sleep duration in milliseconds

struct esp_zb_zdo_signal_device_annce_params_s

The payload of ESP_ZB_ZDO_SIGNAL_DEVICE_ANNCE signal.

Note

Stack passes this parameter to application when some device joins/rejoins to network.

Public Members

uint16_t device_short_addr

address of device that recently joined to network

esp_zb_ieee_addr_t ieee_addr

The 64-bit (IEEE) address assigned to the device.

uint8_t capability

The capability of the device.

struct esp_zb_zdo_signal_device_update_params_s

@brief The payload of ESP_ZB_ZDO_SIGNAL_DEVICE_UPDATE signal

Public Members

esp_zb_ieee_addr_t long_addr

Long Address of the updated device

uint16_t short_addr

Short Address of the updated device

uint8_t status

Indicates the updated status of the device, refer to esp_zb_zdo_update_dev_status_t

uint8_t tc_action

Trust center action, refer to esp_zb_zdo_update_dev_tc_action_t

uint16_t parent_short

The short address of device’s parent

struct esp_zb_zdo_signal_device_authorized_params_s

The payload of ESP_ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED signal.

Note

The authorization_type as following: 0x00 = Authorization type for legacy devices ( < r21) Status: 0x00: Authorization success 0x01: Authorization failed 0x01 = Authorization type for r21 device through TCLK Status: 0x00: Authorization success 0x01: Authorization timeout 0x02: Authorization failed 0x02 = Authorization type for SE through CBKE Status: 0x00: Authorization success

Public Members

esp_zb_ieee_addr_t long_addr

Long Address of the updated device

uint16_t short_addr

Short Address of the updated device

uint8_t authorization_type

Type of the authorization procedure

uint8_t authorization_status

Status of the authorization procedure which depends on authorization_type

struct esp_zb_zdo_device_unavailable_params_s

The payload of ESP_ZB_ZDO_DEVICE_UNAVAILABLE signal.

Public Members

esp_zb_ieee_addr_t long_addr

Long address of the unavailable device

uint16_t short_addr

Short address of unavailable device

struct esp_zb_bdb_signal_touchlink_nwk_started_params_s

The payload of ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_STARTED signal.

Public Members

esp_zb_ieee_addr_t device_ieee_addr

The ieee address of touchlink target

uint8_t endpoint

The endpoint id on the touchlink target

uint16_t profile_id

The profile id of touchlink profile

struct esp_zb_zdo_signal_nwk_status_indication_params_s

The payload of ESP_ZB_NLME_STATUS_INDICATION signal.

Public Members

uint8_t status

Error code associated with the failure, refer to esp_zb_nwk_command_status_t

uint16_t network_addr

Network device address associated with the status information

uint8_t unknown_command_id

Unknown command ID

struct esp_zb_nwk_signal_device_associated_params_s

The payload of ESP_ZB_NWK_SIGNAL_DEVICE_ASSOCIATED signal.

Public Members

esp_zb_ieee_addr_t device_addr

address of associated device

Type Definitions

typedef struct esp_zb_zdo_signal_leave_params_s esp_zb_zdo_signal_leave_params_t

The payload of ESP_ZB_ZDO_SIGNAL_LEAVE signal.

typedef struct esp_zb_zdo_signal_leave_indication_params_s esp_zb_zdo_signal_leave_indication_params_t

The payload of ESP_ZB_ZDO_SIGNAL_LEAVE_INDICATION signal.

typedef struct esp_zb_zdo_signal_can_sleep_params_s esp_zb_zdo_signal_can_sleep_params_t

The payload of ESP_ZB_COMMON_SIGNAL_CAN_SLEEP signal.

typedef struct esp_zb_zdo_signal_device_annce_params_s esp_zb_zdo_signal_device_annce_params_t

The payload of ESP_ZB_ZDO_SIGNAL_DEVICE_ANNCE signal.

Note

Stack passes this parameter to application when some device joins/rejoins to network.

typedef struct esp_zb_zdo_signal_device_update_params_s esp_zb_zdo_signal_device_update_params_t

@brief The payload of ESP_ZB_ZDO_SIGNAL_DEVICE_UPDATE signal

typedef struct esp_zb_zdo_signal_device_authorized_params_s esp_zb_zdo_signal_device_authorized_params_t

The payload of ESP_ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED signal.

Note

The authorization_type as following: 0x00 = Authorization type for legacy devices ( < r21) Status: 0x00: Authorization success 0x01: Authorization failed 0x01 = Authorization type for r21 device through TCLK Status: 0x00: Authorization success 0x01: Authorization timeout 0x02: Authorization failed 0x02 = Authorization type for SE through CBKE Status: 0x00: Authorization success

typedef struct esp_zb_zdo_device_unavailable_params_s esp_zb_zdo_device_unavailable_params_t

The payload of ESP_ZB_ZDO_DEVICE_UNAVAILABLE signal.

typedef struct esp_zb_bdb_signal_touchlink_nwk_started_params_s esp_zb_bdb_signal_touchlink_nwk_started_params_t

The payload of ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_STARTED signal.

typedef esp_zb_bdb_signal_touchlink_nwk_started_params_t esp_zb_bdb_signal_touchlink_nwk_joined_router_t

The payload of ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_JOINED_ROUTER signal.

typedef esp_zb_bdb_signal_touchlink_nwk_started_params_t esp_zb_bdb_signal_touchlink_nwk_joined_ed_t

The payload of ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_JOINED_ED signal.

typedef struct esp_zb_zdo_signal_nwk_status_indication_params_s esp_zb_zdo_signal_nwk_status_indication_params_t

The payload of ESP_ZB_NLME_STATUS_INDICATION signal.

typedef struct esp_zb_nwk_signal_device_associated_params_s esp_zb_nwk_signal_device_associated_params_t

The payload of ESP_ZB_NWK_SIGNAL_DEVICE_ASSOCIATED signal.

Enumerations

enum esp_zb_nwk_leave_type_t

Values:

enumerator ESP_ZB_NWK_LEAVE_TYPE_RESET

Leave without rejoin

enumerator ESP_ZB_NWK_LEAVE_TYPE_REJOIN

Leave with rejoin

enum esp_zb_zdo_update_dev_tc_action_t

TC action on incoming update device.

Values:

enumerator ESP_ZB_ZDO_TC_ACTION_AUTHORIZE

Authorize device

enumerator ESP_ZB_ZDO_TC_ACTION_DENY

deny authorization, remove it

enumerator ESP_ZB_ZDO_TC_ACTION_IGNORE

ignore Update Device

enum esp_zb_zdo_update_dev_status_t

ZDO update device status.

Values:

enumerator ESP_ZB_ZDO_STANDARD_DEV_SECURED_REJOIN

Standard device secured rejoin

enumerator ESP_ZB_ZDO_STANDARD_DEV_UNSECURED_JOIN

Standard device unsecured join

enumerator ESP_ZB_ZDO_STANDARD_DEV_LEFT

Standard device left

enumerator ESP_ZB_ZDO_STANDARD_DEV_TC_REJOIN

Standard device trust center rejoin

enum esp_zb_zdp_status_t

ZDP status values.

Note

the status feedback for the zdo command

Values:

enumerator ESP_ZB_ZDP_STATUS_SUCCESS

The requested operation or transmission was completed successfully.

enumerator ESP_ZB_ZDP_STATUS_INV_REQUESTTYPE

The supplied request type was invalid.

enumerator ESP_ZB_ZDP_STATUS_DEVICE_NOT_FOUND

The requested device did not exist on a device following a child descriptor request to a parent.

enumerator ESP_ZB_ZDP_STATUS_INVALID_EP

The supplied endpoint was equal to 0x00 or between 0xf1 and 0xff.

enumerator ESP_ZB_ZDP_STATUS_NOT_ACTIVE

The requested endpoint is not described by simple descriptor.

enumerator ESP_ZB_ZDP_STATUS_NOT_SUPPORTED

The requested optional feature is not supported on the target device.

enumerator ESP_ZB_ZDP_STATUS_TIMEOUT

A timeout has occurred with the requested operation.

enumerator ESP_ZB_ZDP_STATUS_NO_MATCH

The end device bind request was unsuccessful due to a failure to match any suitable clusters.

enumerator ESP_ZB_ZDP_STATUS_NO_ENTRY

The unbind request was unsuccessful due to the coordinator or source device not having an entry in its binding table to unbind.

enumerator ESP_ZB_ZDP_STATUS_NO_DESCRIPTOR

A child descriptor was not available following a discovery request to a parent.

enumerator ESP_ZB_ZDP_STATUS_INSUFFICIENT_SPACE

The device does not have storage space to support the requested operation.

enumerator ESP_ZB_ZDP_STATUS_NOT_PERMITTED

The device is not in the proper state to support the requested operation.

enumerator ESP_ZB_ZDP_STATUS_TABLE_FULL

The device does not have table space to support the operation.

enumerator ESP_ZB_ZDP_STATUS_NOT_AUTHORIZED

The permissions configuration table on the target indicates that the request is not authorized from this device.

enumerator ESP_ZB_ZDP_STATUS_BINDING_TABLE_FULL

The device doesn’t have binding table space to support the operation

enumerator ESP_ZB_ZDP_STATUS_INVALID_INDEX

The index in the received command is out of bounds.

enum esp_zb_app_signal_type_t

signal passed to the esp_zb_application_signal_handler

Values:

enumerator ESP_ZB_ZDO_SIGNAL_DEFAULT_START

Overview:

  • The device has started in non-BDB commissioning mode.

When generated:

  • After the device has started and completed non-BDB commissioning.

  • In case of a commissioning error.

Status code:

  • ESP_OK: Device has started and joined the network.

  • ESP_FAIL: Device startup failure.

Payload:

  • None.

enumerator ESP_ZB_ZDO_SIGNAL_SKIP_STARTUP

Overview:

  • Stack framework (scheduler, buffer pool, NVRAM, etc.) startup complete, ready for initializing bdb commissioning.

When generated:

  • When the stack starts using the esp_zb_start(false) method.

Status code:

  • ESP_OK: Stack framework has been initialized.

Payload:

  • None.

enumerator ESP_ZB_ZDO_SIGNAL_DEVICE_ANNCE

Overview:

  • Indicates that a Zigbee device has joined or rejoined the network.

When generated:

  • Upon receiving the device_annce command.

Status code:

  • ESP_OK: device_annce command was received.

Payload:

  • Refer to esp_zb_zdo_signal_device_annce_params_t

enumerator ESP_ZB_ZDO_SIGNAL_LEAVE

Overview:

  • Indicates that the device itself has left the network.

When generated:

  • Upon receiving the Leave command.

Status code:

  • ESP_OK: Leave command was received.

Payload:

  • Refer to esp_zb_zdo_signal_leave_params_t

enumerator ESP_ZB_ZDO_SIGNAL_ERROR

Overview:

  • Indicates corrupted or incorrect signal information.

When generated:

  • When incorrect signal information is detected.

Status code:

  • None

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_DEVICE_FIRST_START

Overview:

  • Indicate the basic network information of factory new device has been initialized, ready for Zigbee commissioning

When generated:

  • Upon the basic device behavior has been initialization

Status code:

  • ESP_OK: Factory new device initialization complete

  • ESP_FAIL: Factory new device commissioning failed

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_DEVICE_REBOOT

Overview:

  • Indicate device joins or rejoins network from the configured network information.

When generated:

  • Upon the device joining or rejoining Zigbee network using configuration network information.

Status code:

  • ESP_OK: Join or rejoin successfully

  • ESP_FAIL: Join or rejoin failed

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_STARTED

Overview:

  • Indicates that the Touchlink initiator has successfully started a network with the target and is ready for rejoining.

When generated:

  • Upon receiving the Network Start response during the Touchlink commissioning procedure.

Status code:

  • ESP_OK: The new network has been started successfully.

Payload:

  • Refer to esp_zb_bdb_signal_touchlink_nwk_started_params_t

enumerator ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_JOINED_ROUTER

Overview:

  • Indicate Touchlink target has join the initiator network.

When generated:

  • Upon Touchlink initiator receives the Network Start response during the Touchlink commissioning procedure.

Status code:

  • ESP_OK: Touchlink target join successfully

Payload:

  • Refer to esp_zb_bdb_signal_touchlink_nwk_joined_router_t

enumerator ESP_ZB_BDB_SIGNAL_TOUCHLINK

Overview:

  • Indicates the result of the Touchlink initiator commissioning process.

When generated:

  • When the Touchlink initiator initiates network commission.

Status code:

  • ESP_OK: Commissioning successful.

  • ESP_FAIL: No valid scan response received.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_STEERING

Overview:

  • Indicates the completion of BDB network steering.

When generated:

  • When the device initiates the network steering commissioning process.

Status code:

  • ESP_OK: Network steering completed successfully.

  • ESP_FAIL: Network steering failed or was canceled.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_FORMATION

Overview:

  • Indicates the completion of BDB network formation.

When generated:

  • When the device initiates the network formation commissioning process.

Status code:

  • ESP_OK: Network formation completed successfully.

  • ESP_FAIL: Network formation failed or was canceled.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_FINDING_AND_BINDING_TARGET_FINISHED

Overview:

  • Indicates the completion of BDB finding and binding (F&B) for a target endpoint.

When generated:

  • When F&B target timeout.

Status code:

  • ESP_OK: F&B target identifying time is expired.

  • ESP_FAIL: F&B target identifying is cancelled.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_FINDING_AND_BINDING_INITIATOR_FINISHED

Overview:

  • Indicates the BDB F&B with a Target succeeded or F&B initiator timeout expired or cancelled.

When generated:

  • When F&B target timeout.

Status code:

  • ESP_OK: On success.

  • ESP_FAIL: Expired or cancelled.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_TOUCHLINK_TARGET

Overview:

  • Indicates that the Touchlink target is preparing to commission with the initiator.

When generated:

  • When the Touchlink procedure starts on the target device.

Status code:

  • ESP_OK: Waiting for the commissioning procedure to proceed.

  • ESP_FAIL: Touchlink procedure failed or was canceled.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK

Overview:

  • Indicates that the Touchlink target network has started.

When generated:

  • When the Touchlink target starts the network upon receiving a start_network, join_router, or join_ed request.

Status code:

  • ESP_OK: Network started successfully.

  • ESP_FAIL: Network start failed or was canceled.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_TOUCHLINK_TARGET_FINISHED

Overview:

  • Indicates that the Touchlink target commissioning procedure has finished.

When generated:

  • When the Touchlink target times out or completes the commissioning procedure.

Status code:

  • ESP_OK: Commissioning procedure completed successfully.

Payload:

  • None

enumerator ESP_ZB_NWK_SIGNAL_DEVICE_ASSOCIATED

Overview:

  • Indicates that a new device has initiated an association procedure.

When generated:

  • When a new device is associated.

Status code:

  • ESP_OK: The new device was successfully associated.

Payload:

  • Refer to esp_zb_nwk_signal_device_associated_params_t

enumerator ESP_ZB_ZDO_SIGNAL_LEAVE_INDICATION

Overview:

  • Indicates that a child device has left the network.

When generated:

  • When the leave command is received from the child device.

Status code:

  • ESP_OK: The child device left the network successfully.

Payload:

  • Refer to esp_zb_zdo_signal_leave_indication_params_t

enumerator ESP_ZB_ZGP_SIGNAL_COMMISSIONING

Overview:

  • Indicates the GPCB (Green Power Combo Basic) commissioning signal.

When generated:

  • When a device is commissioned or decommissioned by the GPCB.

Status code:

  • ESP_OK: Commissioning or decommissioning completed successfully.

Payload:

  • Refer to esp_zb_zgp_signal_commissioning_params_t

enumerator ESP_ZB_COMMON_SIGNAL_CAN_SLEEP

Overview:

  • Indicates the device can enter sleep mode.

When generated:

  • When the stack determines that the device is eligible to enter sleep mode.

Status code:

  • ESP_OK: The device can enter sleep mode.

Payload:

  • Refer to esp_zb_zdo_signal_can_sleep_params_t

enumerator ESP_ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY

Overview:

  • Indicates whether a specific part of the production configuration was found.

When generated:

  • After restoring the production configuration.

Status code:

  • ESP_OK: Production configuration successfully loaded from storage.

  • ESP_FAIL: No production configuration found in storage.

Payload:

  • None

enumerator ESP_ZB_NWK_SIGNAL_NO_ACTIVE_LINKS_LEFT

Overview:

  • Indicates that the Neighbor Table has expired, and no active route links remain.

When generated:

  • When all routes have expired.

Status code:

  • ESP_OK: All routers have expired.

Payload:

  • None

enumerator ESP_ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED

Overview:

  • Indicates that a new device has been authorized by the Trust Center in the network.

When generated:

  • Upon successful authorization.

  • Upon authorization failure.

  • Upon authorization timeout.

Status code:

  • ESP_OK: New device is authorized.

Payload:

  • Refer to esp_zb_zdo_signal_device_authorized_params_t

enumerator ESP_ZB_ZDO_SIGNAL_DEVICE_UPDATE

Overview:

  • Indicates that a device has joined, rejoined, or left the network from the Trust Center or its parents.

When generated:

  • Standard device secured rejoin.

  • Standard device unsecured join.

  • Device left.

  • Standard device trust center rejoin.

Status code:

  • ESP_OK: New device information updated.

Payload:

  • Refer to esp_zb_zdo_signal_device_update_params_t

enumerator ESP_ZB_NWK_SIGNAL_PANID_CONFLICT_DETECTED

Overview:

  • Detects a PAN ID conflict and inquires for a resolution.

When generated:

  • Upon detecting a PAN ID conflict.

Status code:

  • ESP_OK: On success.

Payload:

  • None

enumerator ESP_ZB_NLME_STATUS_INDICATION

Overview:

  • Indicates that a PAN ID conflict has been detected. The application must decide whether to initiate its resolution or not.

When generated:

  • Upon detecting a PAN ID conflict.

Status code:

  • ESP_OK: Resolution initiated successfully.

Payload:

  • Refer to esp_zb_zdo_signal_nwk_status_indication_params_t

enumerator ESP_ZB_BDB_SIGNAL_TC_REJOIN_DONE

Overview:

  • Indicates that the Trust Center rejoin procedure has been completed.

When generated:

  • Upon successful completion of the TC rejoin procedure by the device.

Status code:

  • ESP_OK: TC rejoin completed successfully.

  • ESP_FAIL: Rejoin failed.

Payload:

  • Refer to esp_zb_zdo_signal_nwk_status_indication_params_t

enumerator ESP_ZB_NWK_SIGNAL_PERMIT_JOIN_STATUS

Overview:

  • Indicates the status of the network (open or closed).

When generated:

  • When the network is opened.

  • When the network is closed.

Status code:

  • ESP_OK: On successful operation.

Payload:

  • Refer to esp_zb_zdo_signal_nwk_status_indication_params_t

enumerator ESP_ZB_BDB_SIGNAL_STEERING_CANCELLED

Overview:

  • Indicates the result of cancelling BDB steering.

When generated:

  • When esp_zb_bdb_cancel_steering() is processed.

Status code:

  • ESP_OK: Steering is cancelled successfully.

  • ESP_ERR_INVALID_STATE: Steering is not in progress.

  • ESP_FAIL: Failed to cancel steering.

Payload:

  • None

enumerator ESP_ZB_BDB_SIGNAL_FORMATION_CANCELLED

Overview:

  • Notifies the result of cancelling BDB formation.

When generated:

  • When esp_zb_bdb_cancel_formation() is processed.

Status code:

  • ESP_OK: Formation is cancelled successfully.

  • ESP_ERR_INVALID_STATE: Formation is not in progress.

  • ESP_FAIL: Failed to cancel formation.

Payload:

  • None

enumerator ESP_ZB_ZGP_SIGNAL_MODE_CHANGE

Overview:

  • Indicates a ZGP mode change.

When generated:

  • When a GPCB Sink changes mode between operational mode and commissioning mode.

Status code:

  • ESP_OK: On success.

Payload:

  • None

enumerator ESP_ZB_ZDO_DEVICE_UNAVAILABLE

Overview:

  • Notify that the destination device is unavailable.

When generated:

  • When the stack could not send a packet over NWK or APS, for example:

    • No ACK on the MAC layer;

    • No response to a network address request;

    • No APS-ACK to an APS packet.

Status code:

  • ESP_OK: On success.

Payload:

  • Refer to esp_zb_zdo_device_unavailable_params_t

enumerator ESP_ZB_ZGP_SIGNAL_APPROVE_COMMISSIONING

Overview:

  • ZGP Approve Commissioning.

When generated:

  • When the ZGP subsystem is ready to create a new pairing, but the APP should check if the GPD application functionality matches to continue the pairing.

Status code:

  • ESP_OK: On success.

Payload:

  • Refer to esp_zb_zgp_signal_approve_comm_params_t

enumerator ESP_ZB_SIGNAL_END
enum esp_zb_bdb_commissioning_mode_t

The enum of mode of Base Device Behavior (BDB)

Values:

enumerator ESP_ZB_BDB_MODE_INITIALIZATION
enumerator ESP_ZB_BDB_MODE_NETWORK_STEERING
enumerator ESP_ZB_BDB_MODE_NETWORK_FORMATION
enum esp_zb_zdo_bind_dst_addr_mode_t

The enum of bind request destination address mode.

Values:

enumerator ESP_ZB_ZDO_BIND_DST_ADDR_MODE_16_BIT_GROUP
enumerator ESP_ZB_ZDO_BIND_DST_ADDR_MODE_64_BIT_EXTENDED