SE commissioning API

Functions
zb_ret_t	zb_se_service_discovery_start (zb_uint8_t endpoint)
	Puts the device into Service Discovery state. More...
void	zb_se_service_discovery_stop ()
	Stops Service Discovery process started with zb_se_service_discovery_start. More...
void	zb_se_service_discovery_set_multiple_commodity_enabled (zb_uint8_t enabled)
	Allows to enable or disable support of multiple commodity network. More...
void	zb_se_service_discovery_bind_req (zb_uint8_t param, zb_ieee_addr_t dst_ieee, zb_uint16_t dst_ep)
	Sends Bind Request to the discovered SE device. More...

Detailed Description

Function Documentation

zb_se_service_discovery_bind_req()

void zb_se_service_discovery_bind_req	(	zb_uint8_t	param,
		zb_ieee_addr_t	dst_ieee,
		zb_uint16_t	dst_ep
	)

Sends Bind Request to the discovered SE device.

Note

This call should be used only after application got signal ZB_SE_SIGNAL_SERVICE_DISCOVERY_DO_BIND.

Parameters

[in]	param	- reference to the buffer which will be used for outgoing Bind Request command
[in]	dst_ieee	- address of the found device
[in]	dst_ep	- device's endpoint

Device info (address, endpoint) should be taken from a signal's parameter. Cluster ID will be taken automatically by stack.

Example

/* Application signal handler. Used for informing application about important ZBOSS
 * events/states (device started first time/rebooted, key establishment completed etc).
 * Application may ignore signals in which it is not interested. */
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);

  TRACE_MSG(TRACE_APP1, ">> zboss_signal_handler: param %hd signal %hd status %hd",
            (FMT__H_H_H, param, sig, ZB_GET_APP_SIGNAL_STATUS(param)));

  if (ZB_GET_APP_SIGNAL_STATUS(param) == 0)
  {
    switch (sig)
    {
      case ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY:
        if (zb_buf_len(param) > sizeof(zb_zdo_app_signal_hdr_t))
        {
          se_app_production_config_t *prod_cfg =
            ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, se_app_production_config_t);

          TRACE_MSG(TRACE_APP1, "Loading application production config", (FMT__0));

          if (prod_cfg->version == SE_APP_PROD_CFG_CURRENT_VERSION)
          {
            zb_set_node_descriptor_manufacturer_code_req(prod_cfg->manuf_code, NULL);
          }
        }
        break;

      case ZB_SE_SIGNAL_SERVICE_DISCOVERY_DO_BIND:
      {
        zb_se_signal_service_discovery_bind_params_t *bind_params =
          ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_se_signal_service_discovery_bind_params_t);
        zb_uint8_t i;

        TRACE_MSG(TRACE_APP1, "can bind cluster 0x%x commodity_type %d remote_dev " TRACE_FORMAT_64,
                  (FMT__D_D_A, bind_params->cluster_id, bind_params->commodity_type,
                   TRACE_ARG_64(bind_params->device_addr)));

        if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_METERING)
        {
#ifdef IHD_DEV_SUPPORT_MULTIPLE_COMMODITY
          if (bind_params->commodity_type == ZB_ZCL_METERING_ELECTRIC_METERING
              || bind_params->commodity_type == ZB_ZCL_METERING_GAS_METERING)
#endif
          {
            i = ihd_dev_add_to_list(bind_params->device_addr,
                                      bind_params->cluster_id,
                                      bind_params->endpoint);

            if (i != 0xFF)
            {
#ifdef IHD_DEV_SUPPORT_MULTIPLE_COMMODITY
              g_dev_ctx.dev.lst[i].u.metering.device_type = bind_params->commodity_type;
#endif
              if(g_dev_ctx.dev.lst[i].pending_cmd == IHD_DEV_NO_CMD)
              {
                g_dev_ctx.dev.lst[i].pending_cmd = IHD_DEV_METERING_DISCOVER_ATTRS;

                ZB_SCHEDULE_APP_CALLBACK(ihd_dev_send_pending_cmd, i);
              }

              zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
              param = 0;
            }
          }
        }
        else if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_PRICE)
        {
#ifdef IHD_DEV_SUPPORT_MULTIPLE_COMMODITY
          if (bind_params->commodity_type == ZB_ZCL_METERING_ELECTRIC_METERING
              || bind_params->commodity_type == ZB_ZCL_METERING_GAS_METERING)
#endif
          {
            i = ihd_dev_add_to_list(bind_params->device_addr,
                                      bind_params->cluster_id,
                                      bind_params->endpoint);

            if (i != 0xFF)
            {
#ifdef IHD_DEV_SUPPORT_MULTIPLE_COMMODITY
              g_dev_ctx.dev.lst[i].u.price.commodity_type = bind_params->commodity_type;
#endif
              if(g_dev_ctx.dev.lst[i].pending_cmd == IHD_DEV_NO_CMD)
              {
                g_dev_ctx.dev.lst[i].pending_cmd = IHD_DEV_PRICE_GET_CURRENT_PRICE;

                ZB_SCHEDULE_APP_CALLBACK(ihd_dev_send_pending_cmd, i);
              }

              zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
              param = 0;

            }
          }
        }
        else if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_DRLC)
        {
          i = ihd_dev_add_to_list(bind_params->device_addr,
                                  bind_params->cluster_id,
                                  bind_params->endpoint);
          if (i != 0xFF)
          {
            if(g_dev_ctx.dev.lst[i].pending_cmd == IHD_DEV_NO_CMD)
            {
              g_dev_ctx.dev.lst[i].pending_cmd = IHD_DEV_DRLC_GET_SCHEDULED_EVENTS;

              ZB_SCHEDULE_APP_CALLBACK(ihd_dev_send_pending_cmd, i);
            }

            zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
            param = 0;
          }
        }
        else if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_MESSAGING)
        {
          i = ihd_dev_add_to_list(bind_params->device_addr,
                                    bind_params->cluster_id,
                                    bind_params->endpoint);
          if (i != 0xFF)
          {
            if(g_dev_ctx.dev.lst[i].pending_cmd == IHD_DEV_NO_CMD)
            {
              g_dev_ctx.dev.lst[i].pending_cmd = IHD_DEV_MESSAGING_GET_LAST_MESSAGE;

              ZB_SCHEDULE_APP_CALLBACK(ihd_dev_send_pending_cmd, i);
            }

            zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
            param = 0;
          }
        }
#if IHD_ENABLE_GET_CALENDAR
        else if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_CALENDAR)
        {
          TRACE_MSG(TRACE_APP1, "Send bind request to Calendar Server", (FMT__0));
          i = ihd_dev_add_to_list(bind_params->device_addr,
                                  bind_params->cluster_id,
                                  bind_params->endpoint);
          if (i != 0xFF)
          {
            if(g_dev_ctx.dev.lst[i].pending_cmd == IHD_DEV_NO_CMD)
            {
              g_dev_ctx.dev.lst[i].pending_cmd = IHD_DEV_CALENDAR_GET_CALENDAR;

              ZB_SCHEDULE_APP_CALLBACK(ihd_dev_send_pending_cmd, i);
            }

            zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
            param = 0;
          }
        }
#endif
        else if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_ENERGY_MANAGEMENT)
        {
          i = ihd_dev_add_to_list(bind_params->device_addr,
                                  bind_params->cluster_id,
                                  bind_params->endpoint);
          if (i != 0xFF)
          {
            TRACE_MSG(TRACE_APP1, "Send bind request to Energy Management cluster", (FMT__0));
            if(g_dev_ctx.dev.lst[i].pending_cmd == IHD_DEV_NO_CMD)
            {
              g_dev_ctx.dev.lst[i].pending_cmd = IHD_DEV_ENERGY_MANAGEMENT_SEND_MANAGE_EVENT;

              ZB_SCHEDULE_APP_CALLBACK(ihd_dev_send_pending_cmd, i);
            }

            zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
            param = 0;
          }
        }
      }
      break;

See also

zb_se_signal_service_discovery_bind_params_t

ZB_SE_SIGNAL_SERVICE_DISCOVERY_DO_BIND

zb_se_service_discovery_set_multiple_commodity_enabled()

void zb_se_service_discovery_set_multiple_commodity_enabled

(

zb_uint8_t

enabled

)

Allows to enable or disable support of multiple commodity network.

Parameters

[in]

enabled

- flag (0|1) that says whether multiple commodity should be enabled or not

In networks that support multiple commodities Service Discovery process will return multiple instances of certain clusters. Multiple commodity feature allows application to distinguish what type of metering/price/etc it has just discovered by analyzing commodity_type attribute. In single-commodity network this attribute is not supported meaning all commodities are of the same type.

Note

Multiple commodity feature is enabled by default in ZBOSS stack.

Example

static void ihd_dev_app_init(zb_uint8_t param)
{
  TRACE_MSG(TRACE_APP1, ">> ihd_dev_app_init", (FMT__0));

// disable multiple commodity
zb_se_service_discovery_set_multiple_commodity_enabled(0);

zb_se_service_discovery_start()

zb_ret_t zb_se_service_discovery_start

(

zb_uint8_t

endpoint

)

Puts the device into Service Discovery state.

Parameters

[in]

endpoint

- source endpoint for service discovery

Return values

RET_OK	on success
RET_INVALID_PARAMETER_1	if specified endpoint is invalid (zero, non-SE, has no client clusters)

Service Discovery mechanism is used to discover other devices on the network that have services that match with the device's. The initiator device will receive series of devices matching the discovery criteria. It should decide whether to bind found device or not depending on cluster_id and commodity_type values. Process stops when no more devices left.

Example

/* Application signal handler. Used for informing application about important ZBOSS
 * events/states (device started first time/rebooted, key establishment completed etc).
 * Application may ignore signals in which it is not interested. */
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);

  TRACE_MSG(TRACE_APP1, ">> zboss_signal_handler: param %hd signal %hd status %hd",
            (FMT__H_H_H, param, sig, ZB_GET_APP_SIGNAL_STATUS(param)));

  if (ZB_GET_APP_SIGNAL_STATUS(param) == 0)
  {
    switch (sig)
    {
      case ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY:
        if (zb_buf_len(param) > sizeof(zb_zdo_app_signal_hdr_t))
        {
          se_app_production_config_t *prod_cfg =
            ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, se_app_production_config_t);

          TRACE_MSG(TRACE_APP1, "Loading application production config", (FMT__0));

          if (prod_cfg->version == SE_APP_PROD_CFG_CURRENT_VERSION)
          {
            zb_set_node_descriptor_manufacturer_code_req(prod_cfg->manuf_code, NULL);
          }
        }
        break;

      case ZB_SE_SIGNAL_SERVICE_DISCOVERY_START:
#if defined ZB_USE_BUTTONS
        if (dev_sd_start_enabled == ZB_FALSE) {
          break;
        }
#endif
        TRACE_MSG(TRACE_APP1, "Start Service Discovery", (FMT__0));
        zb_se_service_discovery_start(IHD_DEV_ENDPOINT);
        zb_se_indicate_service_discovery_started();
        break;

zb_se_service_discovery_stop()

void zb_se_service_discovery_stop

(

)

Stops Service Discovery process started with zb_se_service_discovery_start.

This call allows to terminate receiving of matched devices prematurely without waiting when process finished. It is not mandatory call for stopping Service Discovery but it can be useful if initiator decides to break the discovery for some reason (for example, it doesn't need to bind multiple devices).