Cluster の変更点

• 追加された行はこの色です。
• 削除された行はこの色です。
• ++EmberZnet++Cluster へ行く。
• ++EmberZnet++Cluster の差分を削除

#author("2022-11-22T14:21:09+08:00","default:Admin","Admin")
#author("2022-11-22T14:49:43+08:00","default:Admin","Admin")
[[+Zigbee30+EmberZnet]]

&color(red){※This article is based on EmberZnet SDK 6.7.5.0 and EFR32MG Series};

#contents

* 概要 [#d5506ace]

ZCL(ZigBee Cluster Library)

其中包括
- Cluster
- Attribute
- Command

ZCL式样大全

ZigBee Cluster Library Specification

https://zigbeealliance.org/wp-content/uploads/2019/12/07-5123-06-zigbee-cluster-library-specification.pdf


* Cluster [#y63ae244]

扩展Cluster的两种场景： - 扩展标准Cluster上的属性或命令 - 创建全新的自定义Cluster

请注意，在这两种情况下，基于自定义Cluster的功能只能与具有这些自定义Cluster的产品进行交互操作，这意味着您的产品只能与您自己的产品进行交互操作。我们建议您仅在必须使用自定义Cluster时才使用。


根据 ZCL 规范的描述, 一部分Cluster ID是预留给厂商自行定义的：

|Cluster ID|描述|
|0x0000 – 0x7fff|标准 Cluster|
|0xfc00 – 0xffff|厂商自定义 cluster|
|其他值|保留|

Zibgee Clusters 在 EmberZnet SDK 中是以xml文件的形式来定义的. 这些xml文件可以在SDK下面的app\zcl 目录中找到。

例如：

 C:\SiliconLabs\SimplicityStudio\v4\developer\sdks\gecko_sdk_suite\v2.7\app\zcl

你可以查看其中的xml文件内容来尝试去理解这些格式。

例如，general.xml 这个文件定义了一些通用类别的Cluster，比如Basic、Identify、Groups、Scenes、On/Off等等。


有关于Cluster和Attribute的信息在xxx_endpoint_config.h这个文件中

** 自定义 ZCL clusters [#i4c3426e]

Github 参考文档

 https://github.com/MarkDing/IoT-Developer-Boot-Camp/wiki/Zigbee-Custom-Clusters-CN

将自定义的 xml 文件放入项目文件夹，然后转向 Zigbee Stack 标签，在底部有一个 Custom ZCL additions 的区域。单击按钮"Add"，然后选择 xml 文件将其添加到项目中。

&ref(Emberznet_stackzcladditions.png);

XML文件的格式

#codeprettify{{
<configurator>
  <domain name="Test" />

  <cluster manufacturerCode="0x1002">
    <name>Hello World</name>
    <domain>Ember</domain>
    <description>This cluster provides an example of how the Application 
      Framework can be extended to include manufacturer specific clusters.
      </description>
    <!-- Cluster Id must be within the mfg spec range 0xfc00 - 0xffff -->
    <code>0xFC10</code> 
    <define>SAMPLE_MFG_SPECIFIC_HELLOWORLD_CLUSTER</define>
    <client init="false" tick="false">true</client>
    <server init="false" tick="false">true</server>
    <attribute side="server" code="0x0000" define="ATTRIBUTE_ONE" 
      type="CHAR_STRING"  min="0x00"   max="0xFF"   writable="true"  
      default="" optional="true">ember sample attribute</attribute>
    <command source="client" code="0x00" 
      name="CommandOne" 
      optional="true">
      <description>
        A sample manufacturer specific command within the sample manufacturer specific
        cluster.
      </description>
      <arg name="argOne" type="CHAR_STRING" />
    </command>
  </cluster>

</configurator>
}}

参考：

 https://zhuanlan.zhihu.com/p/339586860

* Attribute [#m4d01241]

底层的数字基石是Attribute,它即容易理解，也是构建ZigBee标准体系的重要元素

官方定义：

 Attribute: A data entity which represents a physical quantity or state. This data is communicated to other devices using commands.
 属性： 一个代表物理量或者状态的数据。它通过指令来通信。


ZigBee联盟还定义了许多的属性（Attribute）,都记载于文档 “zigbee-cluster-specification.pdf”，文档可以在联盟下载。

属性是可以用来反映状态，比如说当前灯是开关的，或者是关着的，这样一个状态，在设备意外断电或者复位时，假如设备重新通电时，需要恢复为断电前的状态，这样的应用场景就需要开发者将变化后的状态记录下来，每次发生变化时记录，或者定时去记录都可行，具体看变化的频度，一般频度低的可以用变化时记录，频度高的可以用定时记录，或者记录关键变化，当用于记录较低频度的变化时，就可以直接使用EmberZNet协议栈中的storage attribute， 当然高频变化也可以用，不过受另外一个原因影响，&color(red){EFR32芯片使用FLASH作为存储器，频繁地改写会导致FLASH寿命缩短，所以不建议高频变化时使用storage attribute。};
** ZCL attribute types [#xcd916fc]

#codeprettify{{
// ZCL attribute types
enum {
  ZCL_NO_DATA_ATTRIBUTE_TYPE                        = 0x00, // No data
  ZCL_DATA8_ATTRIBUTE_TYPE                          = 0x08, // 8-bit data
  ZCL_DATA16_ATTRIBUTE_TYPE                         = 0x09, // 16-bit data
  ZCL_DATA24_ATTRIBUTE_TYPE                         = 0x0A, // 24-bit data
  ZCL_DATA32_ATTRIBUTE_TYPE                         = 0x0B, // 32-bit data
  ZCL_DATA40_ATTRIBUTE_TYPE                         = 0x0C, // 40-bit data
  ZCL_DATA48_ATTRIBUTE_TYPE                         = 0x0D, // 48-bit data
  ZCL_DATA56_ATTRIBUTE_TYPE                         = 0x0E, // 56-bit data
  ZCL_DATA64_ATTRIBUTE_TYPE                         = 0x0F, // 64-bit data
  ZCL_BOOLEAN_ATTRIBUTE_TYPE                        = 0x10, // Boolean
  ZCL_BITMAP8_ATTRIBUTE_TYPE                        = 0x18, // 8-bit bitmap
  ZCL_BITMAP16_ATTRIBUTE_TYPE                       = 0x19, // 16-bit bitmap
  ZCL_BITMAP24_ATTRIBUTE_TYPE                       = 0x1A, // 24-bit bitmap
  ZCL_BITMAP32_ATTRIBUTE_TYPE                       = 0x1B, // 32-bit bitmap
  ZCL_BITMAP40_ATTRIBUTE_TYPE                       = 0x1C, // 40-bit bitmap
  ZCL_BITMAP48_ATTRIBUTE_TYPE                       = 0x1D, // 48-bit bitmap
  ZCL_BITMAP56_ATTRIBUTE_TYPE                       = 0x1E, // 56-bit bitmap
  ZCL_BITMAP64_ATTRIBUTE_TYPE                       = 0x1F, // 64-bit bitmap
  ZCL_INT8U_ATTRIBUTE_TYPE                          = 0x20, // Unsigned 8-bit integer
  ZCL_INT16U_ATTRIBUTE_TYPE                         = 0x21, // Unsigned 16-bit integer
  ZCL_INT24U_ATTRIBUTE_TYPE                         = 0x22, // Unsigned 24-bit integer
  ZCL_INT32U_ATTRIBUTE_TYPE                         = 0x23, // Unsigned 32-bit integer
  ZCL_INT40U_ATTRIBUTE_TYPE                         = 0x24, // Unsigned 40-bit integer
  ZCL_INT48U_ATTRIBUTE_TYPE                         = 0x25, // Unsigned 48-bit integer
  ZCL_INT56U_ATTRIBUTE_TYPE                         = 0x26, // Unsigned 56-bit integer
  ZCL_INT64U_ATTRIBUTE_TYPE                         = 0x27, // Unsigned 64-bit integer
  ZCL_INT8S_ATTRIBUTE_TYPE                          = 0x28, // Signed 8-bit integer
  ZCL_INT16S_ATTRIBUTE_TYPE                         = 0x29, // Signed 16-bit integer
  ZCL_INT24S_ATTRIBUTE_TYPE                         = 0x2A, // Signed 24-bit integer
  ZCL_INT32S_ATTRIBUTE_TYPE                         = 0x2B, // Signed 32-bit integer
  ZCL_INT40S_ATTRIBUTE_TYPE                         = 0x2C, // Signed 40-bit integer
  ZCL_INT48S_ATTRIBUTE_TYPE                         = 0x2D, // Signed 48-bit integer
  ZCL_INT56S_ATTRIBUTE_TYPE                         = 0x2E, // Signed 56-bit integer
  ZCL_INT64S_ATTRIBUTE_TYPE                         = 0x2F, // Signed 64-bit integer
  ZCL_ENUM8_ATTRIBUTE_TYPE                          = 0x30, // 8-bit enumeration
  ZCL_ENUM16_ATTRIBUTE_TYPE                         = 0x31, // 16-bit enumeration
  ZCL_FLOAT_SEMI_ATTRIBUTE_TYPE                     = 0x38, // Semi-precision
  ZCL_FLOAT_SINGLE_ATTRIBUTE_TYPE                   = 0x39, // Single precision
  ZCL_FLOAT_DOUBLE_ATTRIBUTE_TYPE                   = 0x3A, // Double precision
  ZCL_OCTET_STRING_ATTRIBUTE_TYPE                   = 0x41, // Octet string
  ZCL_CHAR_STRING_ATTRIBUTE_TYPE                    = 0x42, // Character string
  ZCL_LONG_OCTET_STRING_ATTRIBUTE_TYPE              = 0x43, // Long octet string
  ZCL_LONG_CHAR_STRING_ATTRIBUTE_TYPE               = 0x44, // Long character string
  ZCL_ARRAY_ATTRIBUTE_TYPE                          = 0x48, // Array
  ZCL_STRUCT_ATTRIBUTE_TYPE                         = 0x4C, // Structure
  ZCL_SET_ATTRIBUTE_TYPE                            = 0x50, // Set
  ZCL_BAG_ATTRIBUTE_TYPE                            = 0x51, // Bag
  ZCL_TIME_OF_DAY_ATTRIBUTE_TYPE                    = 0xE0, // Time of day
  ZCL_DATE_ATTRIBUTE_TYPE                           = 0xE1, // Date
  ZCL_UTC_TIME_ATTRIBUTE_TYPE                       = 0xE2, // UTC Time
  ZCL_CLUSTER_ID_ATTRIBUTE_TYPE                     = 0xE8, // Cluster ID
  ZCL_ATTRIBUTE_ID_ATTRIBUTE_TYPE                   = 0xE9, // Attribute ID
  ZCL_BACNET_OID_ATTRIBUTE_TYPE                     = 0xEA, // BACnet OID
  ZCL_IEEE_ADDRESS_ATTRIBUTE_TYPE                   = 0xF0, // IEEE address
  ZCL_SECURITY_KEY_ATTRIBUTE_TYPE                   = 0xF1, // 128-bit security key
  ZCL_UNKNOWN_ATTRIBUTE_TYPE                        = 0xFF // Unknown

};
#endif // SILABS_EMBER_AF_ATTRIBUTE_TYPES
}}


** API [#d87ad22e]

 工程目录下/zcl-framework-core/attribute-table.c 文件里面提供了一些API

#codeprettify{{
EmberAfStatus emberAfReadAttribute(uint8_t endpoint,
                                   EmberAfClusterId cluster,
                                   EmberAfAttributeId attributeID,
                                   uint8_t mask,
                                   uint8_t *dataPtr,
                                   uint8_t readLength,
                                   EmberAfAttributeType *dataType);
}}


If you look at emAfWriteAttribute() in attribute-table.c and emAfReadOrWriteAttribute() in attribute-storage.c, you can see that the data is simply copied as bytes from the buffer to the location of the attribute.




#hr();
Comment：
#comment_kcaptcha