ZDO miscellaneous management services

Data Structures
struct	zb_zdo_mgmt_nwk_update_req_hdr_s
	Header of parameters for Mgmt_NWK_Update_req. More...
struct	zb_zdo_mgmt_nwk_update_req_s
	Parameters for Mgmt_NWK_Update_req. More...
struct	zb_zdo_mgmt_nwk_update_notify_hdr_s
	Header parameters for mgmt_nwk_update_notify. More...
struct	zb_zdo_mgmt_nwk_update_notify_param_s
	Parameters for mgmt_nwk_update_notify. More...
struct	zb_zdo_mgmt_lqi_param_s
	Parameters for Mgmt_Lqi_req. More...
struct	zb_zdo_mgmt_lqi_req_s
	Request for Mgmt_Lqi_req. More...
struct	zb_zdo_mgmt_lqi_resp_s
	Response for Mgmt_Lqi_rsp. More...
struct	zb_zdo_neighbor_table_record_s
	NeighborTableList Record Format for Mgmt_Lqi_resp. More...
struct	zb_zdo_routing_table_record_s
	RoutingTableList Record Format for mgmt_rtg_resp. More...
struct	zb_zdo_mgmt_leave_param_s
	Request for Mgmt_Leave_req. More...
struct	zb_zdo_mgmt_leave_req_s
struct	zb_zdo_mgmt_leave_res_s
	Response for Mgmt_Leave_rsp. More...
struct	zb_zdo_mgmt_permit_joining_req_s
	Parameters for Mgmt_Permit_Joining_req. More...
struct	zb_zdo_mgmt_permit_joining_req_param_s
	Parameters for zb_zdo_mgmt_permit_joining_req. More...
struct	zb_zdo_device_annce_s
struct	zb_nlme_leave_indication_s

Macros
#define	ZB_ZDO_RECORD_SET_DEVICE_TYPE(var, type)   ( var &= ~3, var |= type )
#define	ZB_ZDO_RECORD_GET_DEVICE_TYPE(var)   ( var & 3 )
#define	ZB_ZDO_RECORD_SET_RX_ON_WHEN_IDLE(var, type)   ( var &= ~0xC, var |= (type << 2) )
#define	ZB_ZDO_RECORD_GET_RX_ON_WHEN_IDLE(var)   ( (var & 0xC) >> 2 )
#define	ZB_ZDO_RECORD_SET_RELATIONSHIP(var, type)   ( var &= ~0x70, var |= (type << 4) )
#define	ZB_ZDO_RECORD_GET_RELATIONSHIP(var)   ( (var & 0x70) >> 4 )

Typedefs
typedef struct zb_zdo_mgmt_nwk_update_req_hdr_s	zb_zdo_mgmt_nwk_update_req_hdr_t
	Header of parameters for Mgmt_NWK_Update_req.
typedef struct zb_zdo_mgmt_nwk_update_req_s	zb_zdo_mgmt_nwk_update_req_t
	Parameters for Mgmt_NWK_Update_req.
typedef struct zb_zdo_mgmt_nwk_update_notify_hdr_s	zb_zdo_mgmt_nwk_update_notify_hdr_t
	Header parameters for mgmt_nwk_update_notify.
typedef struct zb_zdo_mgmt_nwk_update_notify_param_s	zb_zdo_mgmt_nwk_update_notify_param_t
	Parameters for mgmt_nwk_update_notify.
typedef struct zb_zdo_mgmt_lqi_param_s	zb_zdo_mgmt_lqi_param_t
	Parameters for Mgmt_Lqi_req. More...
typedef struct zb_zdo_mgmt_lqi_req_s	zb_zdo_mgmt_lqi_req_t
	Request for Mgmt_Lqi_req. More...
typedef struct zb_zdo_mgmt_lqi_resp_s	zb_zdo_mgmt_lqi_resp_t
	Response for Mgmt_Lqi_rsp. More...
typedef struct zb_zdo_neighbor_table_record_s	zb_zdo_neighbor_table_record_t
	NeighborTableList Record Format for Mgmt_Lqi_resp.
typedef struct zb_zdo_routing_table_record_s	zb_zdo_routing_table_record_t
	RoutingTableList Record Format for mgmt_rtg_resp.
typedef struct zb_zdo_mgmt_leave_param_s	zb_zdo_mgmt_leave_param_t
	Request for Mgmt_Leave_req. More...
typedef struct zb_zdo_mgmt_leave_req_s	zb_zdo_mgmt_leave_req_t
typedef struct zb_zdo_mgmt_leave_res_s	zb_zdo_mgmt_leave_res_t
	Response for Mgmt_Leave_rsp. More...
typedef struct zb_zdo_mgmt_permit_joining_req_s	zb_zdo_mgmt_permit_joining_req_t
	Parameters for Mgmt_Permit_Joining_req. More...
typedef struct zb_zdo_mgmt_permit_joining_req_param_s	zb_zdo_mgmt_permit_joining_req_param_t
	Parameters for zb_zdo_mgmt_permit_joining_req.
typedef struct zb_zdo_device_annce_s	zb_zdo_device_annce_t
typedef struct zb_nlme_leave_indication_s	zb_nlme_leave_indication_t

Functions
zb_uint8_t	zb_zdo_mgmt_nwk_update_req (zb_uint8_t param, zb_callback_t cb)
	Performs Mgmt_NWK_Update_req request. More...
zb_uint8_t	zb_zdo_mgmt_lqi_req (zb_uint8_t param, zb_callback_t cb)
	Sends Mgmt_Lqi_req (see Zigbee spec 2.4.3.3.2) More...
zb_uint8_t	zdo_mgmt_leave_req (zb_uint8_t param, zb_callback_t cb)
	Sends Mgmt_Leave_req. More...
zb_uint8_t	zb_zdo_mgmt_permit_joining_req (zb_uint8_t param, zb_callback_t cb)
	sends Mgmt_Permit_Joining_req (See Zigbee spec 2.4.3.3.7) More...

Detailed Description

Macro Definition Documentation

ZB_ZDO_RECORD_GET_DEVICE_TYPE

#define ZB_ZDO_RECORD_GET_DEVICE_TYPE

(

var

)

( var & 3 )

Get device type of neighbor table record.

Parameters

var	- neighbor table record type_flags

zb_zdo_neighbor_table_record_s

ZB_ZDO_RECORD_GET_RELATIONSHIP

#define ZB_ZDO_RECORD_GET_RELATIONSHIP

(

var

)

( (var & 0x70) >> 4 )

Get relationship of neighbor table record.

Parameters

var	- neighbor table record type_flags

zb_zdo_neighbor_table_record_s

ZB_ZDO_RECORD_GET_RX_ON_WHEN_IDLE

#define ZB_ZDO_RECORD_GET_RX_ON_WHEN_IDLE

(

var

)

( (var & 0xC) >> 2 )

Get RxOnWhenIdle of neighbor table record.

Parameters

var	- neighbor table record type_flags

zb_zdo_neighbor_table_record_s

ZB_ZDO_RECORD_SET_DEVICE_TYPE

#define ZB_ZDO_RECORD_SET_DEVICE_TYPE	(		var,
			type
	)		( var &= ~3, var |= type )

Set device type of neighbor table record to type 'type': bits 0 - 1, mask 0x3;

Parameters

var	- neighbor table record type_flags
type	- Zigbee device type value

zb_zdo_neighbor_table_record_s

ZB_ZDO_RECORD_SET_RELATIONSHIP

#define ZB_ZDO_RECORD_SET_RELATIONSHIP	(		var,
			type
	)		( var &= ~0x70, var |= (type << 4) )

Set relationship attribute of neighbor table record to type 'type': bits 4 - 6, mask 0x70;

Parameters

var	- neighbor table record type_flags
type	- Zigbee relationship value

zb_zdo_neighbor_table_record_s

ZB_ZDO_RECORD_SET_RX_ON_WHEN_IDLE

#define ZB_ZDO_RECORD_SET_RX_ON_WHEN_IDLE	(		var,
			type
	)		( var &= ~0xC, var |= (type << 2) )

Set RxOnWhenIdle attribute of neighbor table record to type 'type': bits 2 - 3, mask 0xC;

Parameters

var	- neighbor table record type_flags
type	- RxOnWhenIdle value

zb_zdo_neighbor_table_record_s

Typedef Documentation

zb_nlme_leave_indication_t

typedef struct zb_nlme_leave_indication_s zb_nlme_leave_indication_t

Arguments of the NLME-LEAVE.indication routine.

zb_zdo_device_annce_t

typedef struct zb_zdo_device_annce_s zb_zdo_device_annce_t

Parameters of Device_annce primitive.

To be put into buffer as data (means - after space alloc).

zb_zdo_mgmt_leave_param_t

typedef struct zb_zdo_mgmt_leave_param_s zb_zdo_mgmt_leave_param_t

Request for Mgmt_Leave_req.

See also

ZB spec, subclause 2.4.3.3.5.

Problem in the specification: in 2.4.3.3.5 Mgmt_Leave_req only one DeviceAddress exists. But, in such case it is impossible to satisfy 2.4.3.3.5.1: "The Mgmt_Leave_req is generated from a Local Device requesting that a Remote Device leave the network or to request that another device leave the network." Also, in the PRO TC document, 14.2TP/NWK/BV-04 ZR-ZDO-APL RX Join/Leave is following note: "gZC sends Mgmt_Leave.request with DevAddr=all zero, DstAddr=ZR"

zb_zdo_mgmt_leave_req_t

typedef struct zb_zdo_mgmt_leave_req_s zb_zdo_mgmt_leave_req_t

Request for Mgmt_Leave_req.

See also

ZB spec, subclause 2.4.3.3.5.

zb_zdo_mgmt_leave_res_t

typedef struct zb_zdo_mgmt_leave_res_s zb_zdo_mgmt_leave_res_t

Response for Mgmt_Leave_rsp.

See also

ZB spec, subclause 2.4.4.3.5.

zb_zdo_mgmt_lqi_param_t

typedef struct zb_zdo_mgmt_lqi_param_s zb_zdo_mgmt_lqi_param_t

Parameters for Mgmt_Lqi_req.

See also

ZB spec, subclause 2.4.3.3.2.

zb_zdo_mgmt_lqi_req_t

typedef struct zb_zdo_mgmt_lqi_req_s zb_zdo_mgmt_lqi_req_t

Request for Mgmt_Lqi_req.

See also

ZB spec, subclause 2.4.3.3.2.

zb_zdo_mgmt_lqi_resp_t

typedef struct zb_zdo_mgmt_lqi_resp_s zb_zdo_mgmt_lqi_resp_t

Response for Mgmt_Lqi_rsp.

See also

ZB spec, subclause 2.4.4.3.2.

zb_zdo_mgmt_permit_joining_req_t

typedef struct zb_zdo_mgmt_permit_joining_req_s zb_zdo_mgmt_permit_joining_req_t

Parameters for Mgmt_Permit_Joining_req.

See also

ZB spec, subclause 2.4.3.3.7.

Function Documentation

zb_zdo_mgmt_lqi_req()

zb_uint8_t zb_zdo_mgmt_lqi_req	(	zb_uint8_t	param,
		zb_callback_t	cb
	)

Sends Mgmt_Lqi_req (see Zigbee spec 2.4.3.3.2)

Parameters

param	- index of buffer with Lqi request parameters. zb_zdo_mgmt_lqi_param_s
cb	- user's function to call when got response from the remote.

Returns

- ZDP transaction sequence number or 0xFF if operation cannot be performed now (nor enough memory, resources, etc.) zb_zdo_mgmt_lqi_resp_s, zb_zdo_neighbor_table_record_s

Example:

{
  zb_uint8_t tsn;
  zb_zdo_mgmt_lqi_param_t *req_param;

  req_param = ZB_BUF_GET_PARAM(buf, zb_zdo_mgmt_lqi_param_t);
  req_param->start_index = 0;
  req_param->dst_addr = 0; //coord short addr

  tsn = zb_zdo_mgmt_lqi_req(ZB_REF_FROM_BUF(buf), get_lqi_cb);
}


void get_lqi_cb(zb_uint8_t param)
{
  zb_bufid_t buf = ZB_BUF_FROM_REF(param);
  zb_uint8_t *zdp_cmd = zb_buf_begin(buf);
  zb_zdo_mgmt_lqi_resp_t *resp = (zb_zdo_mgmt_lqi_resp_t*)(zdp_cmd);
  zb_zdo_neighbor_table_record_t *record = (zb_zdo_neighbor_table_record_t*)(resp + 1);
  zb_uint_t i;

  TRACE_MSG(TRACE_APS1, "get_lqi_cb status %hd, neighbor_table_entries %hd, start_index %hd, neighbor_table_list_count %d",
            (FMT__H_H_H_H, resp->status, resp->neighbor_table_entries, resp->start_index, resp->neighbor_table_list_count));

  for (i = 0; i < resp->neighbor_table_list_count; i++)
  {
    TRACE_MSG(TRACE_APS1, "#%hd: long addr " TRACE_FORMAT_64 " pan id " TRACE_FORMAT_64,
              (FMT__H_A_A, i, TRACE_ARG_64(record->ext_addr), TRACE_ARG_64(record->ext_pan_id)));

    TRACE_MSG(TRACE_APS1,
      "#%hd: network_addr %d, dev_type %hd, rx_on_wen_idle %hd, relationship %hd, permit_join %hd, depth %hd, lqi %hd",
      (FMT_H_D_H_H_H_H_H_H, i, record->network_addr,
       ZB_ZDO_RECORD_GET_DEVICE_TYPE(record->type_flags),
       ZB_ZDO_RECORD_GET_RX_ON_WHEN_IDLE(record->type_flags),
       ZB_ZDO_RECORD_GET_RELATIONSHIP(record->type_flags),
       record->permit_join, record->depth, record->lqi));

    record++;
  }
}

See zdpo_lqi sample

zb_zdo_mgmt_nwk_update_req()

zb_uint8_t zb_zdo_mgmt_nwk_update_req	(	zb_uint8_t	param,
		zb_callback_t	cb
	)

Performs Mgmt_NWK_Update_req request.

Parameters

param	- index of buffer with call parameters. Parameters mut be put into buffer as parameters. zb_zdo_mgmt_nwk_update_req_s
cb	- user's function to call when got response from the remote. zb_zdo_mgmt_nwk_update_notify_hdr_s

Returns

- ZDP transaction sequence number or 0xFF if operation cannot be performed now (nor enough memory, resources, etc.)

Example:

{
  zb_uint8_t tsn;
  zb_zdo_mgmt_nwk_update_req_t *req;

  req = ZB_BUF_GET_PARAM(buf, zb_zdo_mgmt_nwk_update_req_t);

  req->hdr.scan_channels = ZB_MAC_ALL_CHANNELS_MASK;
  req->hdr.scan_duration = TEST_SCAN_DURATION;
  req->scan_count = TEST_SCAN_COUNT;
  req->update_id = ZB_NIB_UPDATE_ID();

  req->dst_addr = 0;

  tsn = zb_zdo_mgmt_nwk_update_req(param, mgmt_nwk_update_ok_cb);
}


void mgmt_nwk_update_ok_cb(zb_uint8_t param)
{
  zb_bufid_t buf = ZB_BUF_FROM_REF(param);
  zb_uint8_t *zdp_cmd = zb_buf_begin(buf);
  zb_zdo_mgmt_nwk_update_notify_hdr_t *notify_resp = (zb_zdo_mgmt_nwk_update_notify_hdr_t *)zdp_cmd;

  TRACE_MSG(TRACE_APS3,
            "notify_resp status %hd, scanned_channels %x %x, total_transmissions %hd, "
            "transmission_failures %hd, scanned_channels_list_count %hd, buf len %hd",
            (FMT__H_D_D_H_H_H_H, notify_resp->status, (zb_uint16_t)notify_resp->scanned_channels,
             *((zb_uint16_t*)&notify_resp->scanned_channels + 1),
             notify_resp->total_transmissions, notify_resp->transmission_failures,
             notify_resp->scanned_channels_list_count, zb_buf_len(buf)));

  if (notify_resp->status == ZB_ZDP_STATUS_SUCCESS)
  {
    TRACE_MSG(TRACE_APS3, "mgmt_nwk_update_notify received, Ok", (FMT__0));
  }
  else
  {
    TRACE_MSG(TRACE_ERROR, "mgmt_nwk_update_notify received, ERROR incorrect status %x",
              (FMT__D, notify_resp->status));
  }

  zb_free_buf(buf);
}

See TP_PRO_BV-37 sample

zb_zdo_mgmt_permit_joining_req()

zb_uint8_t zb_zdo_mgmt_permit_joining_req	(	zb_uint8_t	param,
		zb_callback_t	cb
	)

sends Mgmt_Permit_Joining_req (See Zigbee spec 2.4.3.3.7)

Parameters

param	- Index of buffer with request
cb	- user's function to call when got response from the remote.

Returns

ZDP transaction sequence number

0xFF if operation cannot be performed now (nor enough memory, resources, etc.)

        /* Example: send permit join request to close network */
        req_param = ZB_BUF_GET_PARAM(buf, zb_zdo_mgmt_permit_joining_req_param_t);

        req_param->dest_addr = 0xfffc;
        req_param->permit_duration = 0;
        req_param->tc_significance = 1;

        zb_zdo_mgmt_permit_joining_req(buf, permit_joining_cb);

See onoff_server sample

zdo_mgmt_leave_req()

zb_uint8_t zdo_mgmt_leave_req	(	zb_uint8_t	param,
		zb_callback_t	cb
	)

Sends Mgmt_Leave_req.

See also

ZB spec, subclause 2.4.3.3.2.

Parameters

param	- index of buffer with Lqi request parameters. zb_zdo_mgmt_leave_param_s
cb	- user's function to call when got response from the remote.

Returns

- transaction sequence number of request or 0xFF if operation not be performed right now (in case if not exist free slot for registering callback)

Example:

{
  zb_bufid_t buf = ZB_BUF_FROM_REF(param);
  zb_zdo_mgmt_leave_param_t *req = NULL;
  zb_ret_t ret = RET_OK;
  zb_uint8_t tsn;

  TRACE_MSG(TRACE_ERROR, "zb_leave_req", (FMT__0));

  req = ZB_BUF_GET_PARAM(buf, zb_zdo_mgmt_leave_param_t);

  ZB_MEMSET(req->device_address, 0, sizeof(zb_ieee_addr_t));
  req->remove_children = ZB_FALSE;
  req->rejoin = ZB_FALSE;
  req->dst_addr = 1;
  tsn = zdo_mgmt_leave_req(param, leave_callback);
}

void leave_callback(zb_uint8_t param)
{
  zb_zdo_mgmt_leave_res_t *resp = (zb_zdo_mgmt_leave_res_t *)zb_buf_begin(ZB_BUF_FROM_REF(param));

  TRACE_MSG(TRACE_ERROR, "LEAVE CALLBACK status %hd", (FMT__H, resp->status));
}

See nwk_leave sample