AF management service

Macros
#define	ZB_AF_IS_EP_REGISTERED(_ep)   ((zb_af_get_endpoint_desc( _ep ) != NULL)?(ZB_TRUE):(ZB_FALSE))
	Check endpoint registration in ZCL. More...
#define	ZB_AF_START_DECLARE_ENDPOINT_LIST(ep_list_name)   zb_af_endpoint_desc_t *ep_list_name[] = {
#define	ZB_AF_DECLARE_ENDPOINT_DESC( ep_name, ep_id, profile_id, reserved_length, reserved_ptr, cluster_number, cluster_list, simple_desc, rep_count, rep_ctx, lev_ctrl_count, lev_ctrl_ctx)
	Initialize endpoint descriptor. More...
#define	ZB_AF_FINISH_DECLARE_ENDPOINT_LIST   }
#define	ZB_AF_SET_ENDPOINT_HANDLER(endpoint, handler)   (zb_af_get_endpoint_desc((endpoint))->device_handler = (handler))
	Allows application to register cluster commands handler for a specific endpoint. More...
#define	ZB_AF_SET_IDENTIFY_NOTIFICATION_HANDLER(endpoint, handler)   (zb_af_get_endpoint_desc((endpoint))->identify_handler = (handler))
	Sets identify notification handler for endpoint. More...
#define	ZB_ZCL_CLUSTER_DESC(cluster_id, attr_count, attr_desc_list, cluster_role_mask, manuf_code)
#define	ZB_AF_DECLARE_DEVICE_CTX(device_ctx_name, ep_list_name, ep_count, reporting_attr_count)
#define	ZB_AF_DECLARE_DEVICE_CTX_NO_REP(device_ctx_name, ep_list_name, ep_count)
#define	ZBOSS_DEVICE_DECLARE_REPORTING_CTX(rep_ctx, rep_count)   zb_zcl_reporting_info_t rep_ctx[rep_count]
#define	ZBOSS_DEVICE_DECLARE_LEVEL_CONTROL_CTX(lev_ctrl_ctx, lev_ctrl_count)   zb_zcl_cvc_alarm_variables_t lev_ctrl_ctx[lev_ctrl_count]
#define	ZBOSS_DECLARE_DEVICE_CTX(device_ctx_name, ep_list_name, ep_count)
#define	ZBOSS_DECLARE_DEVICE_CTX_1_EP(device_ctx_name, ep_name)
#define	ZBOSS_DECLARE_DEVICE_CTX_2_EP(device_ctx_name, ep1_name, ep2_name)
#define	ZBOSS_DECLARE_DEVICE_CTX_3_EP(device_ctx_name, ep1_name, ep2_name, ep3_name)
#define	ZBOSS_DECLARE_DEVICE_CTX_4_EP(device_ctx_name, ep1_name, ep2_name, ep3_name, ep4_name)
#define	ZB_AF_REGISTER_DEVICE_CTX(_device_ctx)   zb_af_register_device_ctx(_device_ctx)
#define	ZB_ZCL_REGISTER_DEVICE_CB(func_ptr)
	Set Device user application callback. The macro sets a callback being called upon to need inform User App about change device attribute or need to execute H/W command. More...

Typedefs
typedef zb_uint8_t(*	zb_device_handler_t) (zb_uint8_t param)
typedef void(*	zb_af_transmission_res_cb_t) (zb_uint8_t status)

Functions
	ZB_DECLARE_SIMPLE_DESC (1, 1)
	ZB_DECLARE_SIMPLE_DESC (8, 9)
zb_af_endpoint_desc_t *	zb_af_get_endpoint_desc (zb_uint8_t ep_id)
	Search for endpoint (device) descriptor by endpoint ID. More...
void	zb_apsde_data_indication_cont (zb_uint8_t param)
void	zb_af_set_data_indication (zb_device_handler_t cb)
	Set up application callback to be called for APS data packets. More...
void	zb_bdb_reset_via_local_action (zb_uint8_t param)
	Perform "Reset with a Local Action" procedure (as described in BDB spec, chapter 9.5). The device will perform the NLME leave and clean all Zigbee persistent data except the outgoing NWK frame counter and application datasets (if any). The reset can be performed at any time once the device is started (see zboss_start). After the reset, the application will receive the ZB_ZDO_SIGNAL_LEAVE signal. More...
void	zb_bdb_initiate_tc_rejoin (zb_uint8_t param)
	Starts TC rejoin procedure. More...

Detailed Description

Macro Definition Documentation

ZB_AF_DECLARE_DEVICE_CTX

#define ZB_AF_DECLARE_DEVICE_CTX	(		device_ctx_name,
			ep_list_name,
			ep_count,
			reporting_attr_count
	)

Value:

  zb_zcl_reporting_info_t reporting_info## device_ctx_name[reporting_attr_count]; \
  zb_af_device_ctx_t device_ctx_name =                                  \
  {                                                                     \
    ep_count,                                                           \
    ep_list_name,                                                       \
    reporting_attr_count,                                               \
    reporting_info## device_ctx_name,                                   \
    0,                                                                  \
    NULL                                                                \
  }

WARNING: This API is deprecated, use ZBOSS_DECLARE_DEVICE_CTX instead.

ZB_AF_DECLARE_DEVICE_CTX_NO_REP

#define ZB_AF_DECLARE_DEVICE_CTX_NO_REP	(		device_ctx_name,
			ep_list_name,
			ep_count
	)

Value:

  zb_af_device_ctx_t device_ctx_name =                                  \
  {                                                                     \
    ep_count,                                                           \
    ep_list_name,                                                       \
    0,                                                                  \
    NULL,                                                               \
    0,                                                                  \
    NULL                                                                \
  }

WARNING: This API is deprecated, use ZBOSS_DECLARE_DEVICE_CTX instead.

ZB_AF_DECLARE_ENDPOINT_DESC

#define ZB_AF_DECLARE_ENDPOINT_DESC	(		ep_name,
			ep_id,
			profile_id,
			reserved_length,
			reserved_ptr,
			cluster_number,
			cluster_list,
			simple_desc,
			rep_count,
			rep_ctx,
			lev_ctrl_count,
			lev_ctrl_ctx
	)

Value:

  zb_af_endpoint_desc_t ep_name =        \
  {                                      \
    ep_id,                               \
    profile_id,                          \
    NULL,                                \
    NULL,                                \
    reserved_length,                     \
    (void*)reserved_ptr,            \
    cluster_number,                      \
    cluster_list,                        \
    simple_desc,                         \
    rep_count,                           \
    rep_ctx,                             \
    lev_ctrl_count,                      \
    lev_ctrl_ctx                         \
  }

Initialize endpoint descriptor.

Parameters

ep_name	- endpoint name
ep_id	- endpoint ID
profile_id	- ID of profile deployed on this endpoint
reserved_length	- unused parameter
reserved_ptr	- unused parameter
cluster_number	- number of clusters deployed on endpoint
cluster_list	- pointer to cluster list
simple_desc	- pointer to simple descriptor
rep_count	- maximum number of attributes that are being reported on a device
rep_ctx	- reporting context variable name (NULL if no reporting context)
lev_ctrl_count	- number of level control attributes
lev_ctrl_ctx	- level control context variable name (NULL if no level control context)

ZB_AF_FINISH_DECLARE_ENDPOINT_LIST

#define ZB_AF_FINISH_DECLARE_ENDPOINT_LIST   }

Finishes endpoint list declaration

ZB_AF_IS_EP_REGISTERED

#define ZB_AF_IS_EP_REGISTERED

(

_ep

)

((zb_af_get_endpoint_desc( _ep ) != NULL)?(ZB_TRUE):(ZB_FALSE))

Check endpoint registration in ZCL.

Parameters

_ep	- identifier of the endpoint under consideration.

Returns

ZB_TRUE if endpoint is registered, ZB_FALSE otherwise.

ZB_AF_REGISTER_DEVICE_CTX

#define ZB_AF_REGISTER_DEVICE_CTX

(

_device_ctx

)

zb_af_register_device_ctx(_device_ctx)

Register device context.

Parameters

_device_ctx

- Pointer to the device context

Example:

 /* Register device ZCL context */
  ZB_AF_REGISTER_DEVICE_CTX(&on_off_output_ctx);

ZB_AF_SET_ENDPOINT_HANDLER

#define ZB_AF_SET_ENDPOINT_HANDLER	(		endpoint,
			handler
	)		(zb_af_get_endpoint_desc((endpoint))->device_handler = (handler))

Allows application to register cluster commands handler for a specific endpoint.

Parameters

endpoint	- Endpoint number
handler	- Pointer to a function, function type zb_device_handler_t

Attention

Endpoint should be registered. ZB_AF_SET_ENDPOINT_HANDLER() should be called after device context is registered, using call to ZB_AF_REGISTER_DEVICE_CTX()

ZB_AF_SET_IDENTIFY_NOTIFICATION_HANDLER

#define ZB_AF_SET_IDENTIFY_NOTIFICATION_HANDLER	(		endpoint,
			handler
	)		(zb_af_get_endpoint_desc((endpoint))->identify_handler = (handler))

Sets identify notification handler for endpoint.

Utilized by ZCL Identify cluster

Parameters

endpoint	number
handler	to set

Attention

Assumes that endpoint already registered

ZB_AF_START_DECLARE_ENDPOINT_LIST

#define ZB_AF_START_DECLARE_ENDPOINT_LIST

(

ep_list_name

)

zb_af_endpoint_desc_t *ep_list_name[] = {

General macro to declare endpoint description list

Parameters

ep_list_name

- name of ep list structure

ZB_ZCL_CLUSTER_DESC

#define ZB_ZCL_CLUSTER_DESC	(		cluster_id,
			attr_count,
			attr_desc_list,
			cluster_role_mask,
			manuf_code
	)

Value:

{                                                                                                          \
  (cluster_id),                                                                                            \
  (attr_count),                                                                                            \
  (attr_desc_list),                                                                                        \
  (cluster_role_mask),                                                                                     \
  (manuf_code),                                                                                            \
  (((cluster_role_mask) == ZB_ZCL_CLUSTER_SERVER_ROLE) ? cluster_id##_SERVER_ROLE_INIT : \
   (((cluster_role_mask) == ZB_ZCL_CLUSTER_CLIENT_ROLE) ? cluster_id##_CLIENT_ROLE_INIT : NULL)) \
}

ZB_ZCL_REGISTER_DEVICE_CB

#define ZB_ZCL_REGISTER_DEVICE_CB

(

func_ptr

)

Set Device user application callback. The macro sets a callback being called upon to need inform User App about change device attribute or need to execute H/W command.

Parameters

func_ptr

- a callback to set (of type zb_callback_t).

Example:

void test_device_interface_cb(zb_uint8_t param)
{
  zb_zcl_device_callback_param_t *device_cb_param =
    ZB_BUF_GET_PARAM(param, zb_zcl_device_callback_param_t);
 
  TRACE_MSG(TRACE_APP1, "> test_device_interface_cb param %hd id %hd", (FMT__H_H,
      param, device_cb_param->device_cb_id));
 
  device_cb_param->status = RET_OK;
 
  switch (device_cb_param->device_cb_id)
  {
    case ZB_ZCL_SET_ATTR_VALUE_CB_ID:
      if (device_cb_param->cb_param.set_attr_value_param.cluster_id == ZB_ZCL_CLUSTER_ID_ON_OFF &&
          device_cb_param->cb_param.set_attr_value_param.attr_id == ZB_ZCL_ATTR_ON_OFF_ON_OFF_ID)
      {
        if (device_cb_param->cb_param.set_attr_value_param.values.data8)
        {
          TRACE_MSG(TRACE_APP1, "set ON", (FMT__0));
#ifdef ZB_USE_BUTTONS
          zb_osif_led_on(0);
#endif
        }
        else
        {
          TRACE_MSG(TRACE_APP1, "set OFF", (FMT__0));
#ifdef ZB_USE_BUTTONS
          zb_osif_led_off(0);
#endif
        }
      }
      break;
 
    default:
      device_cb_param->status = RET_ERROR;
      break;
  }
 
  TRACE_MSG(TRACE_APP1, "< test_device_interface_cb %hd", (FMT__H, device_cb_param->status));
}

Register callback:

  /* Set Device user application callback */
  ZB_ZCL_REGISTER_DEVICE_CB(test_device_interface_cb);

ZBOSS_DECLARE_DEVICE_CTX

#define ZBOSS_DECLARE_DEVICE_CTX	(		device_ctx_name,
			ep_list_name,
			ep_count
	)

Value:

  zb_af_device_ctx_t device_ctx_name =                                  \
  {                                                                     \
    ep_count,                                                           \
    ep_list_name,                                                       \
  }

Declare application's device context

Parameters

device_ctx_name	- device context variable name
ep_list_name	- name of endpoint list
ep_count	- number of supported endpoints

ZBOSS_DECLARE_DEVICE_CTX_1_EP

#define ZBOSS_DECLARE_DEVICE_CTX_1_EP	(		device_ctx_name,
			ep_name
	)

Value:

  ZB_AF_START_DECLARE_ENDPOINT_LIST(ep_list_##device_ctx_name)         \
    &ep_name,                                                          \
  ZB_AF_FINISH_DECLARE_ENDPOINT_LIST;                                  \
  ZBOSS_DECLARE_DEVICE_CTX(device_ctx_name, ep_list_##device_ctx_name, \
                           (ZB_ZCL_ARRAY_SIZE(ep_list_##device_ctx_name, zb_af_endpoint_desc_t*)))

Declare application's device context for single-endpoint device

Note

Device has an additional Green Power endpoint if it is ZC or ZR and GPPB feature is enabled (Mandatory for Zigbee 3.0 ZC/ZR).

Parameters

device_ctx_name	- device context variable name
ep_name	- variable holding endpoint context

ZBOSS_DECLARE_DEVICE_CTX_2_EP

#define ZBOSS_DECLARE_DEVICE_CTX_2_EP	(		device_ctx_name,
			ep1_name,
			ep2_name
	)

Value:

  ZB_AF_START_DECLARE_ENDPOINT_LIST(ep_list_##device_ctx_name)          \
    &ep1_name,                                                          \
    &ep2_name,                                                          \
  ZB_AF_FINISH_DECLARE_ENDPOINT_LIST;                                   \
  ZBOSS_DECLARE_DEVICE_CTX(device_ctx_name, ep_list_##device_ctx_name,  \
                           (ZB_ZCL_ARRAY_SIZE(ep_list_##device_ctx_name, zb_af_endpoint_desc_t*)))

Declare application's device context for two-endpoint device

Note

Device has an additional Green Power endpoint if it is ZC or ZR and GPPB feature (Mandatory for Zigbee 3.0 ZC/ZR) is enabled.

Parameters

device_ctx_name	- device context variable name
ep1_name	- variable holding context for endpoint 1
ep2_name	- variable holding context for endpoint 2

ZBOSS_DECLARE_DEVICE_CTX_3_EP

#define ZBOSS_DECLARE_DEVICE_CTX_3_EP	(		device_ctx_name,
			ep1_name,
			ep2_name,
			ep3_name
	)

Value:

  ZB_AF_START_DECLARE_ENDPOINT_LIST(ep_list_##device_ctx_name)          \
    &ep1_name,                                                          \
    &ep2_name,                                                          \
    &ep3_name,                                                          \
  ZB_AF_FINISH_DECLARE_ENDPOINT_LIST;                                   \
  ZBOSS_DECLARE_DEVICE_CTX(device_ctx_name, ep_list_##device_ctx_name,  \
                           (ZB_ZCL_ARRAY_SIZE(ep_list_##device_ctx_name, zb_af_endpoint_desc_t*)))

Declare application's device context for three-endpoint device

Note

Device has an additional Green Power endpoint if it is ZC or ZR and GPPB feature (Mandatory for Zigbee 3.0 ZC/ZR) is enabled.

Parameters

device_ctx_name	- device context variable name
ep1_name	- variable holding context for endpoint 1
ep2_name	- variable holding context for endpoint 2
ep3_name	- variable holding context for endpoint 3

ZBOSS_DECLARE_DEVICE_CTX_4_EP

#define ZBOSS_DECLARE_DEVICE_CTX_4_EP	(		device_ctx_name,
			ep1_name,
			ep2_name,
			ep3_name,
			ep4_name
	)

Value:

  ZB_AF_START_DECLARE_ENDPOINT_LIST(ep_list_##device_ctx_name)          \
    &ep1_name,                                                          \
    &ep2_name,                                                          \
    &ep3_name,                                                          \
    &ep4_name,                                                          \
  ZB_AF_FINISH_DECLARE_ENDPOINT_LIST;                                   \
  ZBOSS_DECLARE_DEVICE_CTX(device_ctx_name, ep_list_##device_ctx_name,  \
                           (ZB_ZCL_ARRAY_SIZE(ep_list_##device_ctx_name, zb_af_endpoint_desc_t*)))

Declare application's device context for for-endpoint device

Note

Device has an additional Green Power endpoint if it is ZC or ZR and GPPB feature (Mandatory for Zigbee 3.0 ZC/ZR) is enabled.

Parameters

device_ctx_name	- device context variable name
ep1_name	- variable holding context for endpoint 1
ep2_name	- variable holding context for endpoint 2
ep3_name	- variable holding context for endpoint 3
ep4_name	- variable holding context for endpoint 4

ZBOSS_DEVICE_DECLARE_LEVEL_CONTROL_CTX

#define ZBOSS_DEVICE_DECLARE_LEVEL_CONTROL_CTX	(		lev_ctrl_ctx,
			lev_ctrl_count
	)		zb_zcl_cvc_alarm_variables_t lev_ctrl_ctx[lev_ctrl_count]

Declare device level control context

Parameters

lev_ctrl_ctx	- level control context variable name
lev_ctrl_count	- number of level control attributes

ZBOSS_DEVICE_DECLARE_REPORTING_CTX

#define ZBOSS_DEVICE_DECLARE_REPORTING_CTX	(		rep_ctx,
			rep_count
	)		zb_zcl_reporting_info_t rep_ctx[rep_count]

Declare device reporting context

Parameters

rep_ctx	- reporting context variable name
rep_count	- number of reporting attributes

Typedef Documentation

zb_af_transmission_res_cb_t

typedef void(* zb_af_transmission_res_cb_t) (zb_uint8_t status)

Callback for notifying user about status of ZCL/ZDO command transmission

zb_device_handler_t

typedef zb_uint8_t(* zb_device_handler_t) (zb_uint8_t param)

Device command handler

Parameters

param

- index of buffer with ZCL command

Returns

status (see zb_bool_t)

Function Documentation

zb_af_get_endpoint_desc()

zb_af_endpoint_desc_t* zb_af_get_endpoint_desc

(

zb_uint8_t

ep_id

)

Search for endpoint (device) descriptor by endpoint ID.

Parameters

ep_id

- identifier of the endpoint.

Returns

NULL if no endpoint found, or pointer to the endpoint descriptor.

zb_af_set_data_indication()

void zb_af_set_data_indication

(

zb_device_handler_t

cb

)

Set up application callback to be called for APS data packets.

That API call may be useful for tests which uses custom profile id or which needs to send raw data over APS.

Attention

Function is called on receive of APS data frame BEFORE internal processing. Please make sure that this callback does not handle packets on standard ZB profiles - this should be done by the stack.

Parameters

cb	- callback to call when AF got APS packet. zb_apsde_data_indication_t

Example:

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:
        TRACE_MSG(TRACE_APS1, "Device STARTED OK", (FMT__0));
        zb_af_set_data_indication(data_indication);
        break;
      default:
        TRACE_MSG(TRACE_APP1, "Unknown signal", (FMT__0));
        break;
    }
    zb_buf_free(buf);
  }
}
 
zb_uint8_t data_indication(zb_bufid_t param)
{
  zb_ushort_t i;
  zb_uint8_t *ptr;
  zb_apsde_data_indication_t *ind = ZB_GET_BUF_PARAM(param, zb_apsde_data_indication_t);
 
  if (ind->profileid == TEST_CUSTOM_PROFILE_ID)
  {
    ptr = ZB_APS_HDR_CUT(param);
 
    TRACE_MSG(TRACE_APS3, "apsde_data_indication: packet %p len %hd status 0x%hx from %d",
              (FMT__P_D_D_D, param, zb_buf_len(param), zb_buf_get_status(param), ind->src_addr));
 
    for (i = 0 ; i < zb_buf_len(param) ; ++i)
    {
      TRACE_MSG(TRACE_APS3, "%x %c", (FMT__D_C, (int)ptr[i], ptr[i]));
    }
    zb_buf_free(param);
    return ZB_TRUE;
  }
  return ZB_FALSE;
}

zb_apsde_data_indication_cont()

void zb_apsde_data_indication_cont

(

zb_uint8_t

param

)

Continue inconimg packet proicessing after ZG->zdo.af_data_cb returned TRUE

Parameters

param

- incoming packet. Be sure it was initially passed to ZG->zdo.af_data_cb.

zb_bdb_initiate_tc_rejoin()

void zb_bdb_initiate_tc_rejoin

(

zb_uint8_t

param

)

Starts TC rejoin procedure.

If device doesn't have a TCLK and UnsecureTcRejoinEnabled policy is set to ZB_FALSE (this is the default setting), TC rejoin won't be performed and ZB_BDB_SIGNAL_TC_REJOIN_DONE signal with RET_ERROR status will be raised.

Parameters

param

- buffer reference (if 0, buffer will be allocated automatically)

zb_bdb_reset_via_local_action()

void zb_bdb_reset_via_local_action

(

zb_uint8_t

param

)

Perform "Reset with a Local Action" procedure (as described in BDB spec, chapter 9.5). The device will perform the NLME leave and clean all Zigbee persistent data except the outgoing NWK frame counter and application datasets (if any). The reset can be performed at any time once the device is started (see zboss_start). After the reset, the application will receive the ZB_ZDO_SIGNAL_LEAVE signal.

Parameters

param

- buffer reference (if 0, buffer will be allocated automatically)

ZB_DECLARE_SIMPLE_DESC() [1/2]

ZB_DECLARE_SIMPLE_DESC	(	1	,
		1
	)

General descriptor type

ZB_DECLARE_SIMPLE_DESC() [2/2]

ZB_DECLARE_SIMPLE_DESC	(	8	,
		9
	)

ZDO descriptor type