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...
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

enum 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_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:

• ZB_BDB_SIGNAL_STEERING
• ZB_BDB_SIGNAL_FORMATION

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). */
void zboss_signal_handler(zb_uint8_t param)
{
  zb_zdo_app_signal_hdr_t *sg_p = NULL;
  zb_zdo_app_signal_type_t sig = zb_get_app_signal(param, &sg_p);
 
  if (ZB_GET_APP_SIGNAL_STATUS(param) == 0)
  {
    switch(sig)
    {
      case ZB_ZDO_SIGNAL_DEFAULT_START:
      case ZB_BDB_SIGNAL_DEVICE_FIRST_START:
      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, "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_close_network(param);
}

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:

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

)

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