Energy Service Interface (ESI)

Macros
#define	ZB_SE_DEVICE_VER_ENERGY_SERVICE_INTERFACE   0
	ESI device version. More...
#define	ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CLUSTER_LIST(cluster_list_name, basic_attr_list, identify_attr_list, kec_attr_list, price_attr_list, time_attr_list, keep_alive_attr_list, tunneling_attr_list, sub_ghz_attr_list)
	Declare cluster list for ESI device. WARNING: You must add the identify attributes set in case your application uses this MACRO because it has been extended. More...
#define	ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_EP(ep_name, ep_id, cluster_list)
	Declare endpoint for ESI device. More...
#define	ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CTX(device_ctx_name, ep_name)   ZBOSS_DECLARE_DEVICE_CTX_1_EP(device_ctx_name, ep_name)
	Declare ESI device context. More...

Detailed Description

The Energy Service Interface connects the energy supply company communication network to the metering and energy management devices within the home. It routes messages to and from the relevant end points. It may be installed within a meter, thermostat, or In- Home Display, or may be a standalone device, and it will contain another non-Zigbee communication module (e.g. power-line carrier, RF, GPRS, broadband Internet connection).

Supported clusters

ESI Device has X clusters (see SE spec 1.4 subclauses 6.1, 6.3.2.1):

Server roles	Client roles
ZCL Basic cluster	SE Key Establishment Cluster
SE Key Establishment Cluster
ZCL Messaging cluster
ZCL Price cluster
ZCL Demand Response and Load Control (DRLC) cluster
ZCL Time cluster
ZCL Keep Alive Cluster (optional)
SE Calendar cluster (optional)
ZCL Tunneling cluster (optional)
SE MDU Pairing cluster (optional)
ZCL Sub-GHz cluster (optional)

Example

Declare clusters

/**
 * Declaring attributes for each cluster
 */

/* Basic cluster attributes */
ZB_ZCL_DECLARE_BASIC_ATTR_LIST(basic_attr_list, g_dev_ctx.basic_attrs);

/* Identify cluster attributes */
ZB_ZCL_DECLARE_IDENTIFY_ATTR_LIST(idfy_attr_list, g_dev_ctx.idfy_attrs);

/* Key Establishment cluster attributes */
ZB_ZCL_DECLARE_KEC_ATTR_LIST(kec_attr_list, g_dev_ctx.kec_attrs);

/* Price cluster attributes */
#if ESI_USE_ALL_PRICE_CLUSTER_ATTRIBUTES
/* NOTE:
 * 1. There are 998 attributes.
 * 2. (sizeof(price_attr_values) + sizeof(price_attr_list)) == 17304 bytes
 */
zb_zcl_price_attr_values_t price_attr_values = ZB_ZCL_PRICE_ATTR_VALUES_INIT;
ZB_ZCL_DECLARE_PRICE_SRV_ALL_ATTR_LIST(price_attr_list, &price_attr_values);
#else
ZB_ZCL_DECLARE_PRICE_SRV_ATTR_LIST(price_attr_list, &g_dev_ctx.price_attrs.commodity_type);
#endif

/* Time cluster attributes */
ZB_ZCL_DECLARE_TIME_ATTR_LIST(time_attr_list, g_dev_ctx.time_attrs);

/* Keep-Alive cluster attributes */
ZB_ZCL_DECLARE_KEEP_ALIVE_ATTR_LIST(keep_alive_attr_list, g_dev_ctx.keep_alive_attrs);

#if defined ZB_SUBGHZ_BAND_ENABLED && defined ZB_ZCL_SUPPORT_CLUSTER_SUBGHZ
  ZB_ZCL_DECLARE_SUBGHZ_SRV_ATTR_LIST(sub_ghz_attr_list, g_dev_ctx.sub_ghz_attrs);
#else
#define sub_ghz_attr_list 0
#endif

/* Tunneling cluster attributes */
ZB_ZCL_DECLARE_TUNNELING_ATTR_LIST(tunneling_attr_list, g_dev_ctx.tunneling_attrs);

/* Declare SE cluster list for the device */
ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CLUSTER_LIST(esi_dev_clusters,
                                                        basic_attr_list,
                                                        idfy_attr_list,
                                                        kec_attr_list,
                                                        price_attr_list,
                                                        time_attr_list,
                                                        keep_alive_attr_list,
                                                        tunneling_attr_list,
                                                        sub_ghz_attr_list);

/* Declare endpoint */
ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_EP(esi_dev_ep, ESI_DEV_ENDPOINT, esi_dev_clusters);

/* Declare SE application's device context for single-endpoint device */
ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CTX(esi_dev_zcl_ctx, esi_dev_ep);

Register device context

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

Signal handler example

/** [SIGNAL_HANDLER_GET_SIGNAL] */
/** 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 %hd sig %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)
    {
#ifdef DEBUG
      case ZB_DEBUG_SIGNAL_TCLK_READY:
      {
        zb_debug_signal_tclk_ready_params_t *params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_debug_signal_tclk_ready_params_t);
        zb_debug_broadcast_aps_key(params->long_addr);
      }
      break;
#endif
      case ZB_ZDO_SIGNAL_DEVICE_ANNCE:
        ZB_SCHEDULE_APP_CALLBACK(esi_permit_join_after_dev_annce, param);
        param = 0;
        break;

      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;

/** [SIGNAL_HANDLER_GET_SIGNAL] */
      case ZB_ZDO_SIGNAL_SKIP_STARTUP:
        zb_secur_ic_str_add(esi_ic_dev_addr1, default_installcode, NULL);
        zb_secur_ic_str_add(esi_ic_dev_addr2, default_installcode, NULL);
        zb_secur_ic_str_add(esi_ic_dev_addr3, default_installcode, NULL);
        zb_secur_ic_str_add(esi_ic_dev_addr4, default_installcode, NULL);
#ifdef ADDITIONAL_DEV_ADDR
        zb_secur_ic_str_add(add_dev_addr, add_installcode, NULL);
#endif
        zboss_start_continue();
        break;

      case ZB_SIGNAL_DEVICE_FIRST_START:
      case ZB_SIGNAL_DEVICE_REBOOT:
        TRACE_MSG(TRACE_APP1, "Device STARTED OK: first_start %hd",
                  (FMT__H, sig == ZB_SIGNAL_DEVICE_FIRST_START));
#ifdef ZB_USE_BUTTONS
        zb_button_register_handler(BUTTON_LEFT, 0, esi_dev_left_button_handler);
        zb_button_register_handler(BUTTON_RIGHT, 16, esi_dev_right_button_handler);
#else
        esi_dev_left_button_handler(0);
#endif
        zb_se_indicate_default_start();
        break;

/** [SIGNAL_HANDLER_BIND_INDICATION] */
        case ZB_SE_SIGNAL_SERVICE_DISCOVERY_BIND_INDICATION:
        {
          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);

          TRACE_MSG(TRACE_APP1, "Bind indication signal: binded cluster 0x%x endpoint %d device " TRACE_FORMAT_64,
                    (FMT__D_D_A, bind_params->cluster_id, bind_params->endpoint, TRACE_ARG_64(bind_params->device_addr)));
/** [SIGNAL_HANDLER_BIND_INDICATION] */

          if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_DRLC)
          {
            ZB_IEEE_ADDR_COPY(g_dev_ctx.drlc_client_address.addr_long,bind_params->device_addr);
            g_dev_ctx.drlc_client_ep = bind_params->endpoint;
            TRACE_MSG(TRACE_APP1,
              "DRLC device bound to out service: remote addr " TRACE_FORMAT_64 " ep %hd",
               (FMT__A_D, TRACE_ARG_64(g_dev_ctx.drlc_client_address.addr_long),
                g_dev_ctx.drlc_client_ep));

            ZB_SCHEDULE_APP_ALARM_CANCEL(esi_dev_cmd_send_lce_event1, ZB_ALARM_ANY_PARAM);
            ZB_SCHEDULE_APP_CALLBACK(esi_dev_cmd_send_lce_event1, param);
            param = 0;
          }
#if ESI_ENABLE_CALENDAR_CLUSTER
          else if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_CALENDAR)
          {
            /* We send unsolicited command to client, so we store client data*/

            ZB_IEEE_ADDR_COPY(g_dev_ctx.calendar_client_address.addr_long,
                              bind_params->device_addr);
            g_dev_ctx.calendar_client_ep = bind_params->endpoint;

            TRACE_MSG(TRACE_APP1,
                     "Calendar device bound to out service: remote addr " TRACE_FORMAT_64 " ep %hd",
                      (FMT__A_D, TRACE_ARG_64(g_dev_ctx.calendar_client_address.addr_long),
                       g_dev_ctx.calendar_client_ep));

            /* NOTE: APS_KEY_READY is not received */
            ZB_SCHEDULE_APP_ALARM_CANCEL(esi_send_publish_calendar, ZB_ALARM_ANY_PARAM);
            ZB_SCHEDULE_APP_CALLBACK(esi_send_publish_calendar, param);
            param = 0;
          }
#endif /* ESI_ENABLE_CALENDAR_CLUSTER */
        }
        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);

        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)));
/** [SIGNAL_HANDLER_DO_BIND] */

        if (bind_params->cluster_id == ZB_ZCL_CLUSTER_ID_METERING)
        {
          zb_se_service_discovery_bind_req(param, bind_params->device_addr, bind_params->endpoint);
          param = 0;
        }
      }
      break;

/** [SIGNAL_HANDLER_TC_SIGNAL_CHILD_JOIN] */
      case ZB_SE_TC_SIGNAL_CHILD_JOIN_CBKE:
        {
          zb_uint8_t *remote_device_addr = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_uint8_t);
          TRACE_MSG(TRACE_APP1, "Child " TRACE_FORMAT_64 " joined & established TCLK",
                    (FMT__A, TRACE_ARG_64(remote_device_addr)));
/** [SIGNAL_HANDLER_TC_SIGNAL_CHILD_JOIN] */
#ifdef DEBUG
          {
            /* Broadcast APS key to decode packets in Wireshark. Only for debugging */
            zb_debug_signal_tclk_ready_params_t *params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_debug_signal_tclk_ready_params_t);
            (void)zb_debug_broadcast_aps_key(params->long_addr);
            (void)zb_debug_broadcast_nwk_key();
          }
#endif

#if ESI_ENABLE_CALENDAR_CLUSTER
          TRACE_MSG(TRACE_APP1, "Child joined & established TCLK", (FMT__0));
          /* TODO: Do we need to implement the same approach as used in IHD? */
          if (ZB_IEEE_ADDR_CMP(g_dev_ctx.calendar_client_address.addr_long, remote_device_addr))
          {
            TRACE_MSG(TRACE_APP1, "Calendar cluster's partner link initiated", (FMT__0));

            /* NOTE: need to send this command after some intervals */
            ZB_SCHEDULE_APP_ALARM_CANCEL(esi_send_publish_calendar, ZB_ALARM_ANY_PARAM);
            ZB_SCHEDULE_APP_CALLBACK(esi_send_publish_calendar, param);
          }
#endif /* ESI_ENABLE_CALENDAR_CLUSTER */
#if 0
          ZB_SCHEDULE_APP_ALARM(zb_secur_nwk_key_switch_procedure, 0, ZB_TIME_ONE_SECOND * 20);
#endif

#if !defined ZB_USE_BUTTONS
          ZB_SCHEDULE_APP_ALARM(esi_schedule_service_discovery, 0, 7*ZB_TIME_ONE_SECOND);
#endif
        }
        break;
      case ZB_SE_TC_SIGNAL_CHILD_JOIN_NON_CBKE:
      {
        zb_ieee_addr_t *remote_device_addr = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_ieee_addr_t);
        TRACE_MSG(TRACE_APP1, "Child " TRACE_FORMAT_64 " joined & established non-CBKE TCLK",
                  (FMT__A, TRACE_ARG_64(remote_device_addr)));
      }
      break;
      case ZB_SIGNAL_SUBGHZ_SUSPEND:
        TRACE_MSG(TRACE_APP1, "sub-ghz. TX suspended", (FMT__0));
        break;
      case ZB_SIGNAL_SUBGHZ_RESUME:
        TRACE_MSG(TRACE_APP1, "sub-ghz. TX resumed", (FMT__0));
        break;

      case ZB_ZDO_SIGNAL_LEAVE_INDICATION:
      {
        zb_zdo_signal_leave_indication_params_t *leave_ind_params = ZB_ZDO_SIGNAL_GET_PARAMS(sg_p, zb_zdo_signal_leave_indication_params_t);
        TRACE_MSG(TRACE_APP1, "leave indication, device " TRACE_FORMAT_64, (FMT__A, TRACE_ARG_64(leave_ind_params->device_addr)));
      }
      break;

      default:
        TRACE_MSG(TRACE_APP1, "skip signal %hd", (FMT__H, sig));
        break;
    }
  }
  else
  {
    TRACE_MSG(TRACE_ERROR, "Device start FAILED status %d", (FMT__D, ZB_GET_APP_SIGNAL_STATUS(param)));
  }

  SE_APP_AUX_SIGNAL_HANDLER(param);

  if (param)
  {
    zb_buf_free(param);
  }

  TRACE_MSG(TRACE_APP1, "<< zboss_signal_handler", (FMT__0));
}

Macro Definition Documentation

ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CLUSTER_LIST

#define ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CLUSTER_LIST	(		cluster_list_name,
			basic_attr_list,
			identify_attr_list,
			kec_attr_list,
			price_attr_list,
			time_attr_list,
			keep_alive_attr_list,
			tunneling_attr_list,
			sub_ghz_attr_list
	)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/se/zb_se_energy_service_interface.h>

Declare cluster list for ESI device. WARNING: You must add the identify attributes set in case your application uses this MACRO because it has been extended.

Parameters

cluster_list_name	- cluster list variable name
basic_attr_list	- attribute list for Basic cluster
identify_attr_list	- attribute list for Identify cluster
kec_attr_list	- attribute list for Key Establishment cluster
price_attr_list	- attribute list for Price cluster
time_attr_list	- attribute list for Time cluster
keep_alive_attr_list	- attribute list for Keep-Alive cluster
tunneling_attr_list	- attribute list for Tunneling cluster
sub_ghz_attr_list	- attribute list for Sub-GHz cluster

ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CTX

#define ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_CTX	(		device_ctx_name,
			ep_name
	)		ZBOSS_DECLARE_DEVICE_CTX_1_EP(device_ctx_name, ep_name)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/se/zb_se_energy_service_interface.h>

Declare ESI device context.

Parameters

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

ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_EP

#define ZB_SE_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_EP	(		ep_name,
			ep_id,
			cluster_list
	)

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/se/zb_se_energy_service_interface.h>

Value:

ZB_ZCL_DECLARE_ENERGY_SERVICE_INTERFACE_DEV_SIMPLE_DESC(ep_name,                            \
                                          ep_id,                                              \
                                          ZB_SE_ENERGY_SERVICE_INTERFACE_DEV_IN_CLUSTER_NUM,  \
                                          ZB_SE_ENERGY_SERVICE_INTERFACE_DEV_OUT_CLUSTER_NUM, \
                                          SUB_GHZ_CLUSTER_ENABLED_ID);                        \
  ZB_AF_DECLARE_ENDPOINT_DESC(ep_name,                                                        \
                              ep_id,                                                          \
                              ZB_AF_SE_PROFILE_ID,                                            \
                              0,                                                              \
                              NULL,                                                           \
                              ZB_ZCL_ARRAY_SIZE(cluster_list, zb_zcl_cluster_desc_t),         \
                              cluster_list,                                                   \
                              (zb_af_simple_desc_1_1_t*)&simple_desc_##ep_name,               \
                              0, NULL,                                                        \
                              0, NULL)

Declare endpoint for ESI device.

Parameters

ep_name	- endpoint variable name
ep_id	- endpoint ID
cluster_list	- endpoint cluster list

ZB_SE_DEVICE_VER_ENERGY_SERVICE_INTERFACE

#define ZB_SE_DEVICE_VER_ENERGY_SERVICE_INTERFACE   0

#include </conan-data/ti_zigbee/9.14.00.04/library-lprf/ga/build/f6d18801b7b469a709ae7e8290b03ecdc7a7ad4c/zboss_r23/include/se/zb_se_energy_service_interface.h>

ESI device version.