Developing with ZBOSS for Zigbee
BDB commissioning start & status

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.
 

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)
 Start device commissioning procedure specified step. More...
 
void bdb_cancel_joining (zb_bufid_t buf)
 Cancel Steering procedure for a node not on a network started with bdb_start_top_level_commissioning(ZB_BDB_NETWORK_STEERING). The ZBOSS signal ZB_BDB_SIGNAL_STEERING_CANCELLED with the status of this operation will be raised. Possible statuses: More...
 
void bdb_cancel_formation (zb_bufid_t buf)
 Cancel Formation procedure started with bdb_start_top_level_commissioning(ZB_BDB_NETWORK_FORMATION). The ZBOSS signal ZB_BDB_SIGNAL_FORMATION_CANCELLED with the status of the operation will be raised. Possible statuses: More...
 
void bdb_set_scan_duration (zb_uint8_t duration)
 Set scan duration for ED and Active scan. More...
 
zb_ret_t zb_bdb_close_network (zb_bufid_t buf)
 Close the network. More...
 
zb_bool_t zb_bdb_is_factory_new (void)
 
void zb_set_bdb_commissioning_mode (zb_uint8_t commissioning_mode)
 Set commissioning mode. More...
 

Detailed Description

Enumeration Type Documentation

◆ zb_bdb_commissioning_mode_mask_e

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)

Cancel Formation procedure started with bdb_start_top_level_commissioning(ZB_BDB_NETWORK_FORMATION). The ZBOSS signal ZB_BDB_SIGNAL_FORMATION_CANCELLED with the status of the operation will be raised. Possible statuses:

  • RET_INVALID_STATE (formation is not in progress)
  • RET_PENDING (it is too late to cancel a formation, it will be completed soon)
  • RET_IGNORE (cancellation was already requested)
  • RET_OK (formation is cancelled successfully)

If the formation is cancelled the signal ZB_BDB_SIGNAL_FORMATION with the status ZB_BDB_STATUS_FORMATION will be raised as well.

Parameters
buf- a ZBOSS buffer

◆ bdb_cancel_joining()

void bdb_cancel_joining ( zb_bufid_t  buf)

Cancel Steering procedure for a node not on a network started with bdb_start_top_level_commissioning(ZB_BDB_NETWORK_STEERING). The ZBOSS signal ZB_BDB_SIGNAL_STEERING_CANCELLED 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 a 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 signal ZB_BDB_SIGNAL_STEERING with the status ZB_BDB_STATUS_CANCELLED will be raised as well.

Parameters
buf- a ZBOSS buffer

◆ bdb_set_scan_duration()

void bdb_set_scan_duration ( zb_uint8_t  duration)

Set scan duration for ED and Active scan.

Parameters
duration- scan duration. Scan time is (aBaseSuperframeDuration * ((1<<duration) + 1)). In seconds - ((1l << duration) + 1) * 15360 / 1000000.
For duration 8 ~4s
For duration 5 ~0.5s
For duration 2 ~0.08s
For duration 1 ~0.05s (0.046s)

◆ bdb_start_top_level_commissioning()

zb_bool_t bdb_start_top_level_commissioning ( zb_uint8_t  mode_mask)

Start device commissioning procedure specified step.

Performs steering and network formation if appropriate for the device type. Finding and binding is not performed by this function (see note at ZB_BDB_FINDING_N_BINDING)

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

Parameters
mode_mask- bitmask of commissioning steps to perform, see zb_bdb_commissioning_mode_mask_e
Returns
ZB_TRUE - in case the device starts successfully
ZB_FALSE - ZB_FALSE – in case an error occurred (for example: the device has already been running)

Example:

/* Callback which will be called on startup procedure complete (successfull or not). */
{
if (ZB_GET_APP_SIGNAL_STATUS(param) == 0)
{
switch(sig)
{
TRACE_MSG(TRACE_APP1, "Device STARTED OK", (FMT__0));
break;
TRACE_MSG(TRACE_APP1, "Successfull steering", (FMT__0));
break;

◆ zb_bdb_close_network()

zb_ret_t zb_bdb_close_network ( zb_bufid_t  buf)

Close the network.

Implements BDB 3.0.1 - 8.1.1 "Local disabling of Network Steering."

Will broadcast a Mgmt_Permit_Joining_req with PermitDuration of 0

In case it is a router or coordinator it 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
buf- a ZBOSS buffer, if zero is passed, a new buffer will be allocated
Returns
RET_OK if broadcast was successful
RET_NO_MEMORY if buffer allocation failed
RET_ERROR if any error occured
static void close_network(zb_uint8_t param)
{
TRACE_MSG(TRACE_APP1, ">> close network", (FMT__0));
}

◆ zb_bdb_is_factory_new()

zb_bool_t zb_bdb_is_factory_new ( void  )

Check if device is factory new.

Returns
ZB_TRUE if factory new. Example:
{
zb_zdo_rejoin_backoff_start(ZB_FALSE);
}

◆ zb_set_bdb_commissioning_mode()

void zb_set_bdb_commissioning_mode ( zb_uint8_t  commissioning_mode)

Set commissioning mode.

Parameters
commissioning_mode- bitfield with the bdbCommissioningMode attribute. Set 1 to the corresponding bit to enable, 0 to disable. All the possible mask bits are stored in zb_bdb_commissioning_mode_mask_t
zb_uint8_t
unsigned char zb_uint8_t
Project-local 1-byte unsigned int type.
Definition: zb_types.h:153
TRACE_MSG
#define TRACE_MSG(lm, fmts, args)
Put trace output.
Definition: zb_trace.h:359
zb_get_app_signal
zb_zdo_app_signal_type_t zb_get_app_signal(zb_uint8_t param, zb_zdo_app_signal_hdr_t **sg_p)
Unpack application signal buffer in zboss_signal_handler()
ZB_GET_APP_SIGNAL_STATUS
#define ZB_GET_APP_SIGNAL_STATUS(param)
Get status from the application signal.
Definition: zboss_api_zdo.h:1236
ZB_ZDO_SIGNAL_DEFAULT_START
#define ZB_ZDO_SIGNAL_DEFAULT_START
Definition: zboss_api_zdo.h:129
ZB_BDB_SIGNAL_DEVICE_FIRST_START
#define ZB_BDB_SIGNAL_DEVICE_FIRST_START
Definition: zboss_api_zdo.h:213
zb_zdo_app_signal_type_t
zb_uint8_t zb_zdo_app_signal_type_t
Type for signals passed to zboss_signal_handler().
Definition: zboss_api_zdo.h:847
bdb_start_top_level_commissioning
zb_bool_t bdb_start_top_level_commissioning(zb_uint8_t mode_mask)
Start device commissioning procedure specified step.
zb_bdb_close_network
zb_ret_t zb_bdb_close_network(zb_bufid_t buf)
Close the network.
ZB_BDB_SIGNAL_STEERING
#define ZB_BDB_SIGNAL_STEERING
Definition: zboss_api_zdo.h:311
zb_bdb_is_factory_new
zb_bool_t zb_bdb_is_factory_new(void)
zb_zdo_app_signal_hdr_s
Definition: zboss_api_zdo.h:1186
ZB_BDB_NETWORK_STEERING
@ ZB_BDB_NETWORK_STEERING
Definition: zboss_api_zcl.h:2042
zboss_signal_handler
void zboss_signal_handler(zb_uint8_t param)
ZB_FALSE
#define ZB_FALSE
Definition: zb_types.h:374
ZB_BDB_SIGNAL_DEVICE_REBOOT
#define ZB_BDB_SIGNAL_DEVICE_REBOOT
Definition: zboss_api_zdo.h:232