Missing documentation and examples for Zigbee 3.0

[IanAber]

Trying very hard to get up to speed on developing Zigbee devices using the new 3.0 release of the Zigbee stack. The documentation is virtually useless as far as I can see. It appears to follow the new methodology whereby documentation is not supplied but instead we are supposed to use largely uncommented example code and 'reverse engineer' it to work out what to do. This only works if the code has at least some helpful comments and is complete. The documentation inside the code is extremely sparse and vague and the majority of the references to source files go nowhere. As an example, the header file zb_ha_on_off_output.h lists a number of macros and functions with no real explanation of their use except for a reference to the sample file 'ha_on_off_output_sample.c' which is NOT included in the download.

If you expect us to be able to use this library you really need to supply these files or a decent documentation system that does not rely on them. In addition, the examples that you do supply should be consistent in their use of the library and fully exploit the macros provided whereas, as far as I can tell, each example, and there are only a hand full provided covering a very small subset of the library, tackles the setup of a device differently.

Where can we obtain the source code examples referred to in this library so we can actually begin to develop usable code a little quicker than simply writing a whole Zigbee library ourselves from scratch?

[AndreasF]

Hi Ian and sorry for the late reply.

I have reported this to our developers.

It is a issue that zb_ha_on_off_output.h refers to ha_on_off_output_sample.c, as this file is a ZBOSS stack file and not open-sourced (it is under licence and written by DSR), so that reference should not be there.

Which particular reference in zb_ha_on_off_output.h to ha_on_off_output_sample.c are you looking for?

Best regards,

Andreas

[IanAber]

This is a very common theme in the ZBoss stack. There is little to no traditional documentation and in lieu of this the files make regular reference to example code which is supposed to show how to use particular functions. Here is a section from the top of the header file zb_ha_on_off_output.h.

/**
 *  @defgroup ha_on_off_output On/Off Output
 *  @addtogroup ha_on_off_output
 *  @ingroup ZB_HA_DEVICES
    @{
    @details
    On Off Output device has 5 clusters (see spec 7.4.3): \n
        - @ref ZB_ZCL_IDENTIFY \n
        - @ref ZB_ZCL_BASIC \n
        - @ref ZB_ZCL_ON_OFF \n
        - @ref ZB_ZCL_SCENES \n
        - @ref ZB_ZCL_GROUPS

    On Off Output device sample

    @par Example
    Declaring clusters
    @snippet ha_on_off_output_sample.c COMMON_DECLARATION
    Registering device list
    @snippet ha_on_off_output_sample.c REGISTER
    Example of command handler
    @snippet ha_on_off_output_sample.c VARIABLE
    @snippet ha_on_off_output_sample.c Send default response
    @par

    See ha/devices_generic sample
*/

There is no explanation given for how this file should be used in an application.

Another example would be the comment at the top of the file zb_zcl_identify.h

/** @addtogroup ZB_ZCL_IDENTIFY
 *  @{
 *    @details
 *    Identify cluster implementation supports Identify command and Identify Query request-response
 *    command pair. All these commands have simple payload. Both Identify and Identify Query
 *    request are being processed, and Identify Query response is being generated in ZCL internals.
 *
 *    @par Example
 *    Identify sending:
 *    @snippet groups_dut_553.c Send Identify command
 *
 *    Identify Query request sending:
 *    @snippet 5.4.2_identify/ha_th.c Send Identify Query request
 *
 *    Identify Query response parsing:
 *    @snippet 5.4.2_identify/ha_th.c Parse Identify Query response
 *    @par
 *
 *    For more information see 5.5.3_groups, 5.4.2_identify samples
 */

If this documentation is only available to those who have paid for access to the DSR stack then what is the cost of entry and how does one gain access? Without it I am finding it extremely frustrating and time consuming to try to guess and reverse engineer what code I can find to get even the simplest project running.

[AndreasF]

Hi again Ian.

It is more detailed explained the content of for example the files listed in zb_zcl_identify.h on Infocenter.

If you look at the Detailed Description for the file zb_zcl_identify.h, you have example for:

Identify sending:

    ZB_ZCL_IDENTIFY_SEND_IDENTIFY_REQ(zcl_cmd_buf, TIME_TO_IDENTIFY,
        DST_ADDR, DST_ADDR_MODE, DST_ENDPOINT, HA_SWITCH_ENDPOINT,
        ZB_AF_HA_PROFILE_ID, ZB_ZCL_ENABLE_DEFAULT_RESPONSE, NULL);

Identify Query request sending:

    ZB_ZCL_IDENTIFY_SEND_IDENTIFY_QUERY_REQ(
        zcl_cmd_buf,
        DST_ADDR,
        DST_ADDR_MODE,
        DST_ENDPOINT,
        HA_SWITCH_ENDPOINT,
        ZB_AF_HA_PROFILE_ID,
        ZB_ZCL_ENABLE_DEFAULT_RESPONSE,
        NULL);

Identify Query response parsing:

              zb_zcl_identify_query_res_t payload;
          zb_zcl_parse_status_t st;
          
              ZB_ZCL_IDENTIFY_GET_IDENTIFY_QUERY_RES(&payload, zcl_cmd_buf, st);

The same applies for zb_ha_on_off_output.h:

On Off Output device has 5 clusters (see spec 7.4.3):

• ZCL Identify cluster
• ZCL Basic cluster
• ZCL On/Off cluster
• ZCL Scenes cluster
• ZCL Groups cluster

On Off Output device sample:

Declaring clusters:

/********************* Declare attributes  **************************/
/* On/Off cluster attributes data */
zb_uint8_t g_attr_on_off  = ZB_FALSE;
ZB_ZCL_DECLARE_ON_OFF_ATTRIB_LIST(on_off_attr_list, &g_attr_on_off);
/* Basic cluster attributes data */
zb_uint8_t g_attr_zcl_version  = ZB_ZCL_BASIC_ZCL_VERSION_DEFAULT_VALUE;
zb_uint8_t g_attr_power_source = ZB_ZCL_BASIC_POWER_SOURCE_DEFAULT_VALUE;
ZB_ZCL_DECLARE_BASIC_ATTRIB_LIST(basic_attr_list, &g_attr_zcl_version, &g_attr_power_source);
/* Identify cluster attributes data */
zb_uint16_t g_attr_identify_time = 0;
ZB_ZCL_DECLARE_IDENTIFY_ATTRIB_LIST(identify_attr_list, &g_attr_identify_time);
/* Groups cluster attributes data */
zb_uint8_t g_attr_name_support = 0;
ZB_ZCL_DECLARE_GROUPS_ATTRIB_LIST(groups_attr_list, &g_attr_name_support);
/* Scenes cluster attribute data */
zb_uint8_t g_attr_scenes_scene_count;
zb_uint8_t g_attr_scenes_current_scene;
zb_uint16_t g_attr_scenes_current_group;
zb_uint8_t g_attr_scenes_scene_valid;
zb_uint8_t g_attr_scenes_name_support;
ZB_ZCL_DECLARE_SCENES_ATTRIB_LIST(scenes_attr_list, &g_attr_scenes_scene_count,
    &g_attr_scenes_current_scene, &g_attr_scenes_current_group,
    &g_attr_scenes_scene_valid, &g_attr_scenes_name_support);
/********************* Declare device **************************/
ZB_HA_DECLARE_ON_OFF_OUTPUT_CLUSTER_LIST(on_off_output_clusters,
    on_off_attr_list, basic_attr_list, identify_attr_list, groups_attr_list,
    scenes_attr_list);
ZB_HA_DECLARE_ON_OFF_OUTPUT_EP(on_off_output_ep, HA_OUTPUT_ENDPOINT, on_off_output_clusters);
ZB_HA_DECLARE_ON_OFF_OUTPUT_CTX(on_off_output_ctx, on_off_output_ep);

Registering device list:

  ZB_AF_REGISTER_DEVICE_CTX(&on_off_output_ctx);
  ZB_AF_SET_ENDPOINT_HANDLER(HA_OUTPUT_ENDPOINT, zcl_custom_cmd_handler);

Example of command handler:

zb_uint8_t zcl_custom_cmd_handler(zb_uint8_t param)
{
  zb_buf_t *zcl_cmd_buf = (zb_buf_t *)ZB_BUF_FROM_REF(param);
  zb_zcl_parsed_hdr_t * cmd_info = ZB_GET_BUF_PARAM(
      zcl_cmd_buf,
      zb_zcl_parsed_hdr_t);
  /* Store some values - cmd_info will be overwritten */
  zb_uint8_t processed = ZB_FALSE;
  zb_uint16_t dst_addr = ZB_ZCL_PARSED_HDR_SHORT_DATA(cmd_info).src_addr;
  zb_uint8_t endpoint = ZB_ZCL_PARSED_HDR_SHORT_DATA(cmd_info).src_endpoint;
  zb_uint8_t seq_num = cmd_info->seq_number;
  
  
  
        ZB_ZCL_SEND_DEFAULT_RESP(
          zcl_cmd_buf,
          dst_addr,
          ZB_APS_ADDR_MODE_16_ENDP_PRESENT,
          endpoint,
          HA_OUTPUT_ENDPOINT,
          ZB_AF_HA_PROFILE_ID,
          ZB_ZCL_CLUSTER_ID_ON_OFF,
          seq_num,
          ZB_ZCL_CMD_ON_OFF_TOGGLE_ID,
          ZB_ZCL_STATUS_UNSUP_CLUST_CMD);

Is this more helpful for you?

Best regards,

Andreas