Logo
Developing with ZBOSS for Zigbee
Typedefs | Enumerations | Functions
BDB commissioning start & status
Zigbee stack API » BDB commissioning API

Typedefs

typedef enum zb_bdb_commissioning_mode_mask_e zb_bdb_commissioning_mode_mask_t
 BDB commissioning mode mask bits This bitmask is out of BDB 3.1 spec but will continue to be used internally and as a parameter to the commissioning API. More...
 

Enumerations

enum  zb_bdb_commissioning_mode_mask_e { ZB_BDB_NETWORK_STEERING = 2, ZB_BDB_NETWORK_FORMATION = 4, ZB_BDB_FINDING_N_BINDING = 8 }
 BDB commissioning mode mask bits This bitmask is out of BDB 3.1 spec but will continue to be used internally and as a parameter to the commissioning API. More...
 

Functions

zb_bool_t bdb_start_top_level_commissioning (zb_uint8_t mode_mask)
 Starts the specified device commissioning steps. More...
 
void bdb_cancel_joining (zb_bufid_t buf)
 Cancels Network Steering procedure for a node not on the network. More...
 
void bdb_cancel_formation (zb_bufid_t buf)
 Cancels Network Formation procedure. More...
 
void bdb_set_scan_duration (zb_uint8_t duration)
 Sets scan duration for Energy Detection and Active scan. More...
 
zb_ret_t zb_bdb_close_network (zb_bufid_t buf)
 Closes the network. More...
 
zb_bool_t zb_bdb_is_factory_new (void)
 Checks if the device is factory new. More...
 
void zb_set_bdb_commissioning_mode (zb_uint8_t commissioning_mode)
 Sets BDB commissioning mode. More...
 

Detailed Description

Typedef Documentation

§ zb_bdb_commissioning_mode_mask_t

typedef enum zb_bdb_commissioning_mode_mask_e zb_bdb_commissioning_mode_mask_t

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

BDB commissioning mode mask bits This bitmask is out of BDB 3.1 spec but will continue to be used internally and as a parameter to the commissioning API.

Enumeration Type Documentation

§ zb_bdb_commissioning_mode_mask_e

enum zb_bdb_commissioning_mode_mask_e

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

BDB commissioning mode mask bits This bitmask is out of BDB 3.1 spec but will continue to be used internally and as a parameter to the commissioning API.

Enumerator
ZB_BDB_NETWORK_STEERING 

Network steering: 0 = Do not attempt network steering; 1 = Attempt network steering

ZB_BDB_NETWORK_FORMATION 

Network formation: 0 = Do not attempt to form a network; 1 = Attempt to form a network, according to device type2

ZB_BDB_FINDING_N_BINDING 

Finding and binding: 0 = Do not attempt finding and binding; 1 = Attempt finding and binding

Note
actually this mode does not call finding and binding procedure. Use zb_bdb_finding_binding_target or zb_bdb_finding_binding_initiator.

Function Documentation

§ bdb_cancel_formation()

void bdb_cancel_formation ( zb_bufid_t  buf)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Cancels Network Formation procedure.

Parameters
buf- ZBOSS buffer
Note
The ZBOSS ZB_BDB_SIGNAL_FORMATION_CANCELLED signal with the status of this operation will be raised. Possible statuses:
  • RET_INVALID_STATE (formation is not in progress)
  • RET_PENDING (it is too late to cancel the formation, it will be completed soon)
  • RET_IGNORE (cancellation was already requested)
  • RET_OK (formation is cancelled successfully)
If the formation is cancelled, the ZB_BDB_SIGNAL_FORMATION signal with the ZB_BDB_STATUS_FORMATION status will be raised as well.

§ bdb_cancel_joining()

void bdb_cancel_joining ( zb_bufid_t  buf)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Cancels Network Steering procedure for a node not on the network.

Parameters
[in]buf- ZBOSS buffer
Note
The ZBOSS ZB_BDB_SIGNAL_STEERING_CANCELLED signal with the status of this operation will be raised. Possible statuses:
  • RET_ILLEGAL_REQUEST (device is a ZC)
  • RET_INVALID_STATE (steering for a node not on the network is not in progress)
  • RET_PENDING (it is too late to cancel a steering, it will be completed soon)
  • RET_IGNORE (cancellation was already requested)
  • RET_OK (steering is cancelled successfully)
If the steering is cancelled, the ZB_BDB_SIGNAL_STEERING signal with the ZB_BDB_STATUS_CANCELLED status will be raised as well.

§ bdb_set_scan_duration()

void bdb_set_scan_duration ( zb_uint8_t  duration)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Sets scan duration for Energy Detection and Active scan.

Parameters
[in]duration- scan duration. Scan time is (aBaseSuperframeDuration * ((1<<duration) + 1))

Duration to seconds Table:

Duration Time
8 ~4s
5 ~0.5s
2 ~0.08s
1 ~0.05s (0.046s)
See also
bdbScanDuration 5.3.9 (BDB 3.0.1)

§ bdb_start_top_level_commissioning()

zb_bool_t bdb_start_top_level_commissioning ( zb_uint8_t  mode_mask)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Starts the specified device commissioning steps.

This function performs steering and network formation if it is appropriate for the device type.

Finding and binding is not performed by this function (see note for ZB_BDB_FINDING_N_BINDING).

When the selected commissioning procedure finishes, one of the following ZBOSS signals is generated:

Note
DO NOT call this function from a callback after local leave using zdo_mgmt_leave_req(), because internal contexts will not be cleared correctly in such case! Wait for the ZB_ZDO_SIGNAL_LEAVE signal to restart top level commissioning, if necessary.
Parameters
[in]mode_mask- bitmask of commissioning steps to be performed, see zb_bdb_commissioning_mode_mask_t()
Return values
ZB_TRUE- in case the device starts successfully
ZB_FALSE- in case an error occurred (for example, the device has already been running)
Example
Starting BDB top level commissioning on startup signals:
/* Callback which will be called on startup procedure completion (successful or not). */
void zboss_signal_handler(zb_uint8_t param)
{
zb_zdo_app_signal_hdr_t *sg_p = NULL;
zb_zdo_app_signal_t sig = zb_get_app_signal(param, &sg_p);
if (ZB_GET_APP_SIGNAL_STATUS(param) == 0)
{
switch(sig)
{
#ifdef DEBUG
case ZB_DEBUG_SIGNAL_TCLK_READY:
{
zb_debug_signal_tclk_ready_params_t *params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_debug_signal_tclk_ready_params_t);
zb_debug_broadcast_aps_key(params->long_addr);
}
break;
#endif
case ZB_ZDO_SIGNAL_DEFAULT_START:
case ZB_BDB_SIGNAL_DEVICE_FIRST_START:
/* We run bdb_start_top_level_commissioning() from ZB_BDB_SIGNAL_DEVICE_REBOOT
* as a workaround to open the network right after a device restarted. It's used only for testing.
* DO NOT USE SUCH BEHAVIOR IN PRODUCTION!
*/
case ZB_BDB_SIGNAL_DEVICE_REBOOT:
TRACE_MSG(TRACE_APP1, "Device STARTED OK", (FMT__0));
bdb_start_top_level_commissioning(ZB_BDB_NETWORK_STEERING);
break;
case ZB_BDB_SIGNAL_STEERING:
TRACE_MSG(TRACE_APP1, "Successful steering", (FMT__0));
break;

§ zb_bdb_close_network()

zb_ret_t zb_bdb_close_network ( zb_bufid_t  buf)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Closes the network.

This function implements BDB 3.0.1 - 8.1.1 "Local disabling of Network Steering."

It will broadcast a Mgmt_Permit_Joining_req with PermitDuration of 0.

In case it is a router or a coordinator, the function will also issue NLME-PERMIT-JOINING.request primitive with PermitDuration of 0.

The ZBOSS signal ZB_NWK_SIGNAL_PERMIT_JOIN_STATUS will be raised with zb_zdo_mgmt_permit_joining_req_param_t::permit_duration of 0.

Parameters
[in]buf- ZBOSS buffer; if zero is passed, a new buffer will be allocated.
Return values
RET_OK- broadcast was successful
RET_NO_MEMORY- buffer allocation failed
RET_ERROR- any error occurred
Example
Application closing the network:
static void close_network(zb_uint8_t param)
{
TRACE_MSG(TRACE_APP1, ">> close network", (FMT__0));
zb_bdb_close_network(param);
}

§ zb_bdb_is_factory_new()

zb_bool_t zb_bdb_is_factory_new ( void  )

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Checks if the device is factory new.

Return values
ZB_TRUE- device is factory new
ZB_FALSE- device is not factory new
Example
Starting secure rejoin backoff if the device is not factory new:
if (!zb_bdb_is_factory_new())
{
zb_zdo_rejoin_backoff_start(ZB_FALSE);
}

§ zb_set_bdb_commissioning_mode()

void zb_set_bdb_commissioning_mode ( zb_uint8_t  commissioning_mode)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/zboss_api_zcl.h>

Sets BDB commissioning mode.

This function controls the commissioning procedures to be executed.

Parameters
[in]commissioning_mode- bdbCommissioningMode bitmask of zb_bdb_commissioning_mode_mask_t().
See also
bdbCommissioningMode 5.3.2 (BDB 1.0)
Top level commissioning procedure 5.3.2 (BDB 1.0)
Copyright (c) 2012-2022 DSR Corporation, Golden CO, USA. http://www.dsr-zboss.com http://www.dsr-corporation.com
ZBOSS documentation. Wed Oct 29 2025.