本文将讲述Ember zigbee如何对cluster library进行扩展,添加自定义cluster、command。
(参考文档:UG102-AppFrameworkDevGuide --16 Extending the ZigBee Cluster Library (ZCL))
Silicon Lab开发了一整套zigbee开发工具能够帮助开发者迅速开发产品,但是由于其底层代码并不开源,而且目前在中国技术支持力度不够并且价格相对比较昂贵,导致并没有被太多开发者所了解。本人也从事智能家居的开发使用的就是Silicon Lab的zigbee模块em3xx系列,一边学习,一边与大家分享,希望有了解的大神多多指教。
ember zigbee协议栈本身包含了丰富的cluster和相应的command,能满足大部分应用,而且是符合zigbee联盟制定的协议规范的,所以这部分是可以与其它符合zigbee标准协议的厂商直接对接使用的,但是针对不同公司,需要有自己的特色即产品差异化。那么就需要针对自己产品独特的cluster和command即custom cluster和custom command。ember提供很好的cluster扩展性,以下为步骤:
1、需要定义自己的xml文件,文件格式如下:(可在安装目录/tool/appbuilder找到sample-extensions.xml)
-<configurator>
<domain name="Ember"/>
<!-- 定义一个manufacturer name -->
-<cluster manufacturerCode="0x1002">
<!-- 定义mannufacturer code -->
<name>Sample Mfg Specific Cluster</name>
<!-- 定义cluster 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>0xFC00</code>
<!-- 定义cluster code 范围:0xfc00-0xffff -->
<define>SAMPLE_MFG_SPECIFIC_CLUSTER</define>
<client tick="false" init="false">true</client>
<server tick="false" init="false">true</server>
<!-- 定义是否需要tick,与初始化值 -->
<attribute optional="true" default="0x00" writable="true" max="0xFF" min="0x00" type="INT8U" define="ATTRIBUTE_ONE" code="0x0000" side="server">ember sample attribute</attribute>
<!-- 定义该cluster下的属性是否可选或者强制选择;定义初始化值;是否可写;最大值、最小值范围;属性数据类型;属性名为ember sample attribute;属性ID为0x0000 -->
-<command name="CommandOne" optional="true" code="0x00" source="client">
<!-- 定义属性下的相应的命令,命令名字为CommandOne,该命令非强制性可选择,命令·ID为0x00,该命令是由client端发送的 -->
<description> A sample manufacturer specific command within the sample manufacturer specific cluster. </description>
<arg name="argOne" type="INT8U"/>
<!-- 定义命令参数,参数名为argOne,参数类型为int8u -->
</command>
<!-- 以上为直接定义一新的cluster,并定义它的属性及相应的命令,下面则是在现有的cluster增加属性和命令 -->
</cluster>
<!-- Use the cluster extension Extend the on/off cluster -->
-<clusterExtension code="0x0006">
<!-- 选择要扩展的cluster ID,本例中扩展的是on-off(0x0006)-- >
<attribute manufacturerCode="0x1002" optional="true" default="0x0000" writable="true" max="0xFFFF" min="0x0000" type="INT16U" define="SAMPLE_MFG_SPECIFIC_TRANSITION_TIME" code="0x0000" side="server">Sample Mfg Specific - Transition Time</attribute>
<!-- 自定义的custom attribute都需要定义一个manufacturer ID以便与系统的attribute区分 -->
-<command name="SampleMfgSpecificOffWithTransition" manufacturerCode="0x1002" optional="true" code="0x00" source="client">
<!-- 定义该属性相关的命令,同样需要定义manufacturer id应与attribute保持一致 -->
<description>Client command that turns the device off with a transition given by the transition time in the Ember Sample transition time attribute.</description>
</command>
-<command name="SampleMfgSpecificOnWithTransition" manufacturerCode="0x1002" optional="true" code="0x01" source="client">
<description>Client command that turns the device on with a transition given by the transition time in the Ember Sample transition time attribute.</description>
</command>
-<command name="SampleMfgSpecificToggleWithTransition" manufacturerCode="0x1002" optional="true" code="0x02" source="client">
<description>Client command that toggles the device with a transition given by the transition time in the Ember Sample transition time attribute.</description>
</command>
</clusterExtension>
</configurator>
在上例中,定义了一个叫Ember的自定义cluster类,并自定义了名叫Sample Mfg Specific Cluster自定义cluster。该cluster下有一个叫ember sample attribute属性,与该属性相关的有一条CommandOne命令,该命令只有一个int8u的参数。同时扩展了on-off cluster,自定义了Sample MFG Specific Transition Time属性,并且定义了3条相关的指令SampleMfgSpecificOffWithTransition、SampleMfgSpecificOnWithTransition、SampleMfgSpecificToggleWithTransition。
2、将该文件导入到Appbuilder
打开ember desktop,选择file->preference打开preference选项卡,选择ZCL aplication,选择你正在使用的协议栈,图中选择的是5.6 GA EM35X,勾选Enable custom clusters,点击add按钮将你的xml文件添加进来,如下图所示。
完成以上两步后,再新建一个工程或打开一个工程会发现:
之后使用方法同普通cluster coammd一样,比如在client-command-macro.h中能找到你定义的命令填充macro:
/** @brief Client command that turns the device off with a transition given
by the transition time in the Ember Sample transition time attribute.
*
* Cluster: On/off, Attributes and commands for switching devices between 'On' and 'Off' states.
* Command: SampleMfgSpecificOffWithTransition
*/
#define emberAfFillCommandOnOffClusterSampleMfgSpecificOffWithTransition() \
emberAfFillExternalManufacturerSpecificBuffer((ZCL_CLUSTER_SPECIFIC_COMMAND \
| ZCL_MANUFACTURER_SPECIFIC_MASK \
| ZCL_FRAME_CONTROL_CLIENT_TO_SERVER), \
ZCL_ON_OFF_CLUSTER_ID, \
0x1002, \
ZCL_SAMPLE_MFG_SPECIFIC_OFF_WITH_TRANSITION_COMMAND_ID, \
"");
/** @brief Client command that turns the device on with a transition given
by the transition time in the Ember Sample transition time attribute.
*
* Cluster: On/off, Attributes and commands for switching devices between 'On' and 'Off' states.
* Command: SampleMfgSpecificOnWithTransition
*/
#define emberAfFillCommandOnOffClusterSampleMfgSpecificOnWithTransition() \
emberAfFillExternalManufacturerSpecificBuffer((ZCL_CLUSTER_SPECIFIC_COMMAND \
| ZCL_MANUFACTURER_SPECIFIC_MASK \
| ZCL_FRAME_CONTROL_CLIENT_TO_SERVER), \
ZCL_ON_OFF_CLUSTER_ID, \
0x1002, \
ZCL_SAMPLE_MFG_SPECIFIC_ON_WITH_TRANSITION_COMMAND_ID, \
"");