ZigBee 3.0 Adding cluster on KW41Z

[#1]

This document describes how to add additional cluster to the router application in the AN12061-MKW41Z-AN-Zigbee-3-0-Base-Device Application Note.

The Router application's main endpoint contains Basic, Groups, Identify and OnOff server. The steps below describe how to add two clusters to Router: Temperature Measurement server and OnOff client.

Note that these changes only go as far as making the new clusters added and discoverable, no functionality has been added to these clusters.

Router/app_zcl_cfg.h

The first step is to update the application ZCL Configuration file to add the new clusters (OnOff Client, Temperature Measurement Server) to the Router application endpoint.

The HA profile already contains few clusters but Temperature Measurement cluster was added:

/* Profile 'HA' */
#define HA_ILLUMINANCEMEASUREMENT_CLUSTER_ID (0x0400)
#define HA_DEFAULT_CLUSTER_ID                (0xffff)
#define HA_OTA_CLUSTER_ID                    (0x0019)
#define HA_TEMPMEASUREMENT_CLUSTER_ID        (0x0402)

Router/app_zcl_globals.c

The OnOff client was already present in Router endpoint but made discoverable and the Temperature Measurement cluster was added and made discoverable into Router application endpoint.The clusters are added to the Input cluster list (Server side) and output cluster list (Client side) and made discoverable using DiscFlag only for the cluster list for which it is enabled. So, assuming you need to add OnOff cluster client, you would need to use add the cluster id (0x0006 for OnOff) into input cluster list (Server side of cluster) and output cluster list (Client side of the cluster) and make it discoverable for output cluster list as it is a client cluster. For temperature measurement, you need to make it discoverable for input Cluster list as below:

PRIVATE const uint16 s_au16Endpoint1InputClusterList[6] = { 0x0000, 0x0004, 0x0003, 0x0006, HA_TEMPMEASUREMENT_CLUSTER_ID , 0xffff, };
PRIVATE const PDUM_thAPdu s_ahEndpoint1InputClusterAPdus[6] = { apduZCL, apduZCL, apduZCL, apduZCL, apduZCL, apduZCL, };
PRIVATE uint8 s_au8Endpoint1InputClusterDiscFlags[1] = { 0x1f };

PRIVATE const uint16 s_au16Endpoint1OutputClusterList[5] = { 0x0000, 0x0004, 0x0003, 0x0006, HA_TEMPMEASUREMENT_CLUSTER_ID, };
PRIVATE uint8 s_au8Endpoint1OutputClusterDiscFlags[1] = { 0x08 };

Now update Simple Descriptor structure (see the declaration of zps_tsAplAfSimpleDescCont and ZPS_tsAplAfSimpleDescriptor structures to understand how to correctly fill the various parameters) to reflect the input cluster and output cluster list correctly as below :

PUBLIC zps_tsAplAfSimpleDescCont s_asSimpleDescConts[2] = {
 {
   {
      0x0000,
      0,
      0,
      0,
      84,
      84,
      s_au16Endpoint0InputClusterList,
      s_au16Endpoint0OutputClusterList,
      s_au8Endpoint0InputClusterDiscFlags,
      s_au8Endpoint0OutputClusterDiscFlags,
   },
   s_ahEndpoint0InputClusterAPdus,
   1
},
{
   {
      0x0104,
      0,
      1,
      1,
      6,
      5,
      s_au16Endpoint1InputClusterList,
      s_au16Endpoint1OutputClusterList,
      s_au8Endpoint1InputClusterDiscFlags,
      s_au8Endpoint1OutputClusterDiscFlags,
   },
   s_ahEndpoint1InputClusterAPdus,
   1
},
};

Router/zcl_options.h

This file is used to set the options used by the ZCL.

Enable Clusters

The cluster functionality for the router endpoint was enabled:

/****************************************************************************/
/*                             Enable Cluster                               */
/*                                                                          */
/* Add the following #define's to your zcl_options.h file to enable         */
/* cluster and their client or server instances                             */
/****************************************************************************/
#define CLD_BASIC
#define BASIC_SERVER

#define CLD_IDENTIFY
#define IDENTIFY_SERVER

#define CLD_GROUPS
#define GROUPS_SERVER

#define CLD_ONOFF
#define ONOFF_SERVER
#define ONOFF_CLIENT

#define CLD_TEMPERATURE_MEASUREMENT
#define TEMPERATURE_MEASUREMENT_SERVER

Enable any optional Attributes and Commands for the clusters

/****************************************************************************/
/* Temperature Measurement Cluster - Optional Attributes */
/* */
/* Add the following #define's to your zcl_options.h file to add optional */
/* attributes to the time cluster. */
/****************************************************************************/
#define CLD_TEMPMEAS_ATTR_TOLERANCE

/****************************************************************************/
/* Basic Cluster - Optional Commands */
/* */
/* Add the following #define's to your zcl_options.h file to add optional */
/* commands to the basic cluster. */
/****************************************************************************/
#define CLD_BAS_CMD_RESET_TO_FACTORY_DEFAULTS

/****************************************************************************/
/* OnOff Cluster - Optional Commands */
/* */
/* Add the following #define's to your zcl_options.h file to add optional */
/* commands to the OnOff cluster. */
/****************************************************************************/
#define CLD_ONOFF_CMD_OFF_WITH_EFFECT

 Add the cluster creation and initialization into ZigBee Base device definitions

The cluster functionality for some of the clusters (like OnOff Client) is already present on ZigBee Base Device. For Temperature Measurement cluster the functionality was added into ZigBee Base Device.

<SDK>/middleware/wireless/Zigbee_3_0_6.0.6/core/ZCL/Devices/ZHA/Generic/Include/base_device.h

The first step was including the Temperature Measurement header files into base device header file as shown below: 

#ifdef CLD_TEMPERATURE_MEASUREMENT
#include "TemperatureMeasurement.h"
#endif

The second step was adding cluster instance (tsZHA_BaseDeviceClusterInstances) into base device Instance as shown below:

/* Temperature Measurement Instance */
#if (defined CLD_TEMPERATURE_MEASUREMENT) && (defined TEMPERATURE_MEASUREMENT_SERVER)
 tsZCL_ClusterInstance sTemperatureMeasurementServer;
#endif

The next step was to define the cluster into the base device structure (tsZHA_BaseDevice) as below:

#if (defined CLD_TEMPERATURE_MEASUREMENT) && (defined TEMPERATURE_MEASUREMENT_SERVER)
 tsCLD_TemperatureMeasurement sTemperatureMeasurementServerCluster;
#endif

<SDK>/middleware/wireless/Zigbee_3_0_6.0.6/core/ZCL/Devices/ZHA/Generic/Include/base_device.c

The cluster create function for Temperature Measurement cluster for server was called in ZigBee base device registration function:

#if (defined CLD_TEMPERATURE_MEASUREMENT) && (defined TEMPERATURE_MEASUREMENT_SERVER)
    /* Create an instance of a Temperature Measurement cluster as a server */
    if(eCLD_TemperatureMeasurementCreateTemperatureMeasurement(&psDeviceInfo->sClusterInstance.sTemperatureMeasurementServer,
                                                    TRUE,
                                                    &sCLD_TemperatureMeasurement,
                                                    &psDeviceInfo->sTemperatureMeasurementServerCluster,
                                                    &au8TemperatureMeasurementAttributeControlBits[0]) != E_ZCL_SUCCESS)
   {
       return E_ZCL_FAIL;
    } 
#endif

Router/app_zcl_task.c

Temperature Measurement Server Cluster Data Initialization - APP_vZCL_DeviceSpecific_Init()

The default attribute values for the Temperature Measurement clusters are initialized:

PRIVATE void APP_vZCL_DeviceSpecific_Init(void)
{
    sBaseDevice.sOnOffServerCluster.bOnOff = FALSE;
    FLib_MemCpy(sBaseDevice.sBasicServerCluster.au8ManufacturerName, "NXP", CLD_BAS_MANUF_NAME_SIZE);
    FLib_MemCpy(sBaseDevice.sBasicServerCluster.au8ModelIdentifier, "BDB-Router", CLD_BAS_MODEL_ID_SIZE);
    FLib_MemCpy(sBaseDevice.sBasicServerCluster.au8DateCode, "20150212", CLD_BAS_DATE_SIZE);
    FLib_MemCpy(sBaseDevice.sBasicServerCluster.au8SWBuildID, "1000-0001", CLD_BAS_SW_BUILD_SIZE);
 
    sBaseDevice.sTemperatureMeasurementServerCluster.i16MeasuredValue = 0;
    sBaseDevice.sTemperatureMeasurementServerCluster.i16MinMeasuredValue = 0;
    sBaseDevice.sTemperatureMeasurementServerCluster.i16MaxMeasuredValue = 0;
}