5.2.4. Base Device Behavior (BDB)

This section provides the Base Device Behavior (BDB) related APIs and defines of ESP Zigbee Core.

5.2.4.1. API Reference

5.2.4.1.1. Header File

• components/esp-zigbee-lib/include/ezbee/bdb.h

5.2.4.1.2. Functions

ezb_err_t ezb_bdb_set_primary_channel_set(uint32_t channel_mask)

Set the BDB primary channel mask.

Note

This function should be run AFTER ezb_core_init is called and before ezb_dev_start. These masks define the allowable channels on which the device may attempt to form or join a network on startup. It will scan all channels by default.

Parameters:

channel_mask -- [in] Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)

Returns:

- EZB_ERR_NONE on success

• EZB_ERR_INV_ARG if the channel mask is out of range

uint32_t ezb_bdb_get_primary_channel_set(void)

Get the BDB primary channel mask.

Returns:

A 32-bit channel mask

ezb_err_t ezb_bdb_set_secondary_channel_set(uint32_t channel_mask)

Set the BDB secondary channel mask.

Beacon request will be sent on these channels for the BDB energy scan, if no network found after energy scan on the primary channels.

Parameters:

channel_mask -- [in] Valid channel mask is from 0x00000800 (only channel 11) to 0x07FFF800 (all channels from 11 to 26)

Returns:

- EZB_ERR_NONE on success

• EZB_ERR_INV_ARG if the channel mask is out of range

uint32_t ezb_bdb_get_secondary_channel_set(void)

Get the BDB secondary channel mask.

Returns:

A 32-bit channel mask

void ezb_bdb_set_scan_duration(uint8_t duration)

Set the scan duration time .

Parameters:

duration -- [in] The scan duration time is in beacon intervals, defined as ((1 << duration) + 1) * 15.36 ms

uint8_t ezb_bdb_get_scan_duration(void)

Get the scan duration time.

Returns:

Scan duration, see ezb_bdb_set_scan_duration

bool ezb_bdb_dev_joined(void)

Check if device has joined network or not.

Returns:

• true: device is joined

• false: device is not joined

void ezb_bdb_set_commissioning_mode(ezb_bdb_comm_mode_mask_t commissioning_mode)

Set BDB commissioning mode.

Parameters:

commissioning_mode -- [in] commissioning mode that refer to ezb_bdb_commissioning_mode_mask_t.

ezb_bdb_comm_mode_mask_t ezb_bdb_get_commissioning_mode(void)

Set BDB commissioning mode.

Returns:

commissioning mode, refer to ezb_bdb_commissioning_mode_mask_t

ezb_bdb_comm_status_t ezb_bdb_get_commissioning_status(void)

Get bdb_commissioning_status.

Returns:

commissioning_status refer to ezb_bdb_commissioning_status_t

ezb_err_t ezb_bdb_start_top_level_commissioning(ezb_bdb_comm_mode_mask_t mode_mask)

Start top level commissioning procedure with specified mode mask.

Parameters:

mode_mask -- [in] commissioning modes refer to ezb_bdb_commissioning_mode

Returns:

- EZB_ERR_NONE on success

ezb_err_t ezb_bdb_cancel_steering(void)

Schedule to cancel Steering procedure for a node not on a network.

Returns:

• EZB_ERR_NONE: on success

• EZB_ERR_FAIL: on failed

ezb_err_t ezb_bdb_cancel_formation(void)

Schedule to cancel Formation procedure.

Returns:

• EZB_ERR_NONE: on success

• EZB_ERR_FAIL: on failed

ezb_err_t ezb_bdb_cancel_touchlink_target(void)

Schedule to cancel touchlink target commissioning procedure.

Returns:

• RET_OK: On success

• RET_ERROR: Not in touchlink target procedure

ezb_err_t ezb_bdb_open_network(uint8_t permit_duration)

Open Zigbee network.

Parameters:

permit_duration -- [in] Zigbee network open time

Returns:

• EZB_ERR_NONE: on success

• EZB_ERR_NO_MEM: not memory

• EZB_ERR_FAILED: on failed

ezb_err_t ezb_bdb_close_network(void)

Close Zigbee network.

Returns:

• EZB_ERR_NONE: on success

• EZB_ERR_FAIL: on failure

void ezb_bdb_reset_via_local_action(void)

Perform local reset procedure.

Note

This only takes effect when the device is on a network. The device will leave the current network and clear all Zigbee persistent data, except the outgoing NWK frame counter. It will be in nearly the same state as when it left the factory. A ZB_ZDO_SIGNAL_LEAVE signal with EZB_NWK_LEAVE_TYPE_RESET will be triggered to indicate the end of the procedure.

bool ezb_bdb_is_factory_new(void)

Check if device is factory new.

Returns:

- True factory new.

5.2.4.1.3. Macros

ESP_ZIGBEE_BDB_H

5.2.4.1.4. Type Definitions

typedef enum ezb_bdb_comm_capability_e ezb_bdb_comm_capability_t

Base Device Behavior (BDB) commissioning capability.

typedef enum ezb_bdb_comm_mode_e ezb_bdb_comm_mode_t

Base Device Behavior (BDB) operation mode.

typedef uint8_t ezb_bdb_comm_mode_mask_t

typedef uint8_t ezb_bdb_comm_status_t

5.2.4.1.5. Enumerations

enum ezb_bdb_comm_capability_e

Base Device Behavior (BDB) commissioning capability.

Values:

enumerator EZB_BDB_COMM_CAPABILITY_NONE

No commissioning capability

enumerator EZB_BDB_COMM_CAPABILITY_NETWORK_STEERING

Network steering capability

enumerator EZB_BDB_COMM_CAPABILITY_NETWORK_FORMATION

Network formation capability

enumerator EZB_BDB_COMM_CAPABILITY_FINDING_N_BINDING

Finding & binding capability

enumerator EZB_BDB_COMM_CAPABILITY_TOUCHLINK

Touchlink commissioning capability

enum ezb_bdb_comm_mode_e

Base Device Behavior (BDB) operation mode.

Values:

enumerator EZB_BDB_MODE_INITIALIZATION

BDB initialization mode

enumerator EZB_BDB_MODE_TOUCHLINK_INITIATOR

BDB touchlink initiator mode

enumerator EZB_BDB_MODE_NETWORK_STEERING

BDB network steering mode

enumerator EZB_BDB_MODE_NETWORK_FORMATION

BDB network formation mode

enumerator EZB_BDB_MODE_FINDING_N_BINDING

BDB finding & binding mode

enumerator EZB_BDB_MODE_TOUCHLINK_TARGET

BDB touchlink target mode

enum ezb_bdb_comm_status_e

Base Device Behavior (BDB) commissioning status.

Values:

enumerator EZB_BDB_STATUS_SUCCESS

The commissioning sub-procedure was successful.

enumerator EZB_BDB_STATUS_IN_PROGRESS

One of the commissioning sub-procedures has started but is not yet complete.

enumerator EZB_BDB_STATUS_NOT_AA_CAPABLE

The initiator is not address assignment capable during touchlink.

enumerator EZB_BDB_STATUS_NO_NETWORK

A network has not been found during network steering or touchlink.

enumerator EZB_BDB_STATUS_TARGET_FAILURE

A node has not joined a network when requested during touchlink.

enumerator EZB_BDB_STATUS_FORMATION_FAILURE

A network could not be formed during network formation.

enumerator EZB_BDB_STATUS_NO_IDENTIFY_QUERY_RESPONSE

No response to an identify query command has been received during finding and binding.

enumerator EZB_BDB_STATUS_BINDING_TABLE_FULL

A binding table entry could not be created due to insufficient space in the binding table during finding and binding.

enumerator EZB_BDB_STATUS_NO_SCAN_RESPONSE

No response to a scan request inter-PAN command has been received during touchlink.

enumerator EZB_BDB_STATUS_NOT_PERMITTED

A touchlink (steal) attempt was made when a node is already connected to a centralized security network. A node was instructed to form a network when it did not have a logical type of either Zigbee coordinator or Zigbee router.

enumerator EZB_BDB_STATUS_TCLK_EX_FAILURE

The Trust Center link key exchange procedure has failed attempting to join a centralized security network.

enumerator EZB_BDB_STATUS_NOT_ON_A_NETWORK

A commissioning procedure was forbidden since the node was not currently on a network.

enumerator EZB_BDB_STATUS_ON_A_NETWORK

A commissioning procedure was forbidden since the node was currently on a network.

enumerator EZB_BDB_STATUS_CANCELLED

The current operation (steering or formation) was cancelled by an app

enumerator EZB_BDB_STATUS_DEV_ANNCE_SEND_FAILURE

A device announce sending has been failed (e.g. device announce haven't acked by parent router).