Zigbee Gateway Controller (ZGC) Protocol

One of Two Ways!

The ZGC processing either:

1. Processes attrbutes directly into variables or
2. Processes attributes into structures that can then be serialized and passed over the zhci interface.

Standard processing ot time attributes is an example of straight to variable whilst processing of scene attributes is an example of process to structure then serialize.

Time Processing from the bottom up

• There are no example of using the time attributes in the Telink ZigBee SDK.
• 10 attributes are defined in zcl_time.h.
• Refer to the ZigBee Cluster Library, section 3.12, Time.
  • Attributes are defined in 3.12.2.2, Attributes.

Since time only has attributes and no commands, it appears that the processing used by scene is not required as only a single attribute is ever requested or received.

It is not clear how we might be expected to pass this information over the zbhci.

Scheme Processing from the bottom up

zbhciTx sends the serialized scene information to the zbhci client over a serial port.

• zbhciTx(ZBHCI_CMD_ZCL_SCENE_REMOVE_ALL_RSP, pBuf - array, array);
  • sampleGW_zclRemoveAllSceneRspCmdHandler
    • status_t sampleGW_sceneCb
      • g_sampleGwClusterList[]
        • ZCL_CLUSTER_GEN_SCENES, = 0x0005
          MANUFACTURER_CODE_NONE, = 0
          0, NULL, zcl_scene_register, sampleGW_sceneCb
        • zcl_register(
          SAMPLE_GW_ENDPOINT,
          SAMPLE_GW_CB_CLUSTER_NUM, g_sampleGwClusterList);

Registering ZigBee Clusters and Decoding

• zcl_register() called from user_app_init()
• zcl_register() passed list of cluster definition structures of type zcl_specClusterInfo_t

Using Time as an Example...

This works differently to Scenes - why

• time_attrTbl[] defines time attributes and the location of storage variables
  • Type is zclAttrInfo_t
• zcl_time_attrNum defines the number of time attributes

There appears to be no references to these variables!

But see g_sampleGwClusterList[] which seems to use one, or the other, ways of relating to the attributes. Compare Time to Scene.

• zcl_specClusterInfo_t
  • Uses either of:
    • zclAttrInfo_t *attrTbl, table of attributes (Time uses this)
    • cluster_forAppCb_t clusterAppCb, cluster processing commands (Scene uses this)

If we want CloudSMETS to send the UTC time (and BST?) to the ESP32-C3 then we probably want to use a cluster_forAppCb_t instead of the attribute table.

Using Scenes as an Example...

This works differently to Time - why?

Note that much of this appears to be available for SMETS via zcl_metering.c already.

• zcl_scene_register() is passed
  • zcl_scene_register() is defined in zcl_scene.c and registers the Cluster Identifier (ZigBee Cluster Library, 3.7.1.3), the zcl_scene_cmdHandler,
  • zcl_scene_cmdHandler() is a method in zcl_scene.c and splits command processing between directions e.g. is this a response to a request sent from Service-to-Client or a request being received from Client-to-Server
• if zcl_scene_register() succeeds in registering the cluster, it calls zcl_scene_updateSceneCntAttr() which appears to reach current scene attributes.

Does this mean that the sampleGW_sceneCb doesn't need to check for direction?

• sampleGW_sceneCb is passed

  • sampleGW_sceneCb is a handler for the Scenes command/cluster
  • A cmdId distinguishes how to decode each incoming message
  • Filtering:
    • is this for the gateway (at least in the `sampleGateway`` example)
    • is this in the Client-to-Server direction?
  • cmdIDs have defined values in zcl_scene.h
  • cmdIDs match the Commands Received definitions in the ZigBee Cluster Library, section 3.7.2.4 and responses are the same IDs are requests.

• Incoming requesrts are passed to handlers such as zcl_addScenePrc() whch calls parsers such as zcl_addSceneParse()

• zcl_addSceneParse() parses the request into a structure

• Then stuff happens and we send a response.

But what about the attribute to field references that we elsewhere? Are there two different ways to handle data?

Over UART...

Packet format

• 0x55
• Type (16 bits)
• Length (16 bits)
• CRC (8 bits)
• Data (n bytes)
• 0xAA

Data Format

• Source address (16 bits)
• Source endpoint (8 bits)
• Destination endpoint (8 bits)
• Sequence number (8 bits)
• Message data (variable)

Can we just relay the Message data to Azure? Sghouold be OK providing we teach Azure about the structure of the data that we are sending it.

We will also need to make sure that we send a length field and some sort of identifier. See the UART thing above so perhaps we forward the entire packet?

Message Data

• Seems to be a representation of the data received over ZigBee but might not precisely match an attribute.
• Not clear how this works other than for a gateway!
• Not clear how notifications might work; but perhaps we can replicate this for a gateway?

Message Data Format: Scene Table as an Example

• ZigBee Cluster Library, 3.7.2.3, defines Scene Table
• Telink ZigBee SDK defines a viewSceneRsp_t structure in zcl_scene.h that mirrors the definition of the Scene Table
• Telink ZigBee SDK sampleGW_zclViewSceneRspCmdHandler method in zcl_sampleGatewayCb.c, creates the message data from the viewSceneRsp_t structure, allowing for zero-length data.

[ESP-C3]: ??? insert ref here ???

• The sample applications register callbacks for the clusters that they use
• The callbacks can refer to commands or to simple read/write attributes and the parameters given when registering the callbacks differ for each
• For command based stuff, the structures for the requests and/or responses match the definitions in the ZigBee specifications but not all attributes are always read out so the structure might be incomplete but the registration effectively says which attributes to extract and which to ignore
• The ZigBee documentation that I have been referring to is this: https://zigbeealliance.org/wp-content/uploads/2019/12/07-5123-06-zigbee-cluster-library-specification.pdf
• I will copy my notes into another reply but they are very sparse and MAY BE WRONG!

Good luck and do share what you find out. Maybe we can all produce some useful documentation on this when we are finished :-).