15. Zigbee应用程序框架开发指南 - 应用程序框架插件

1 Zigbee应用程序框架开发指南 - 概述

2 Zigbee应用程序框架开发指南 - 应用程序框架结构

3 Zigbee应用程序框架开发指南 - 应用程序框架目录结构

4 Zigbee应用程序框架开发指南 - 生成应用程序配置文件

5 Zigbee应用程序框架开发指南 - 应用程序框架API

6 Zigbee应用程序框架开发指南 - 应用程序框架Callback接口

7 Zigbee应用程序框架开发指南 - 时间处理

8 Zigbee应用程序框架开发指南 - 事件

9 Zigbee应用程序框架开发指南 - 属性管理

10 Zigbee应用程序框架开发指南 - 命令处理和生成

11 Zigbee应用程序框架开发指南 - 命令行接口（CLI）

12 Zigbee应用程序框架开发指南 - 调试打印接口

13 Zigbee应用程序框架开发指南 - 多网络支持

14 Zigbee应用程序框架开发指南 - 睡眠设备

15 Zigbee应用程序框架开发指南 - 应用程序框架插件

16 Zigbee应用程序框架开发指南 - 扩展ZigBee Cluster Library (ZCL)

17 Zigbee应用程序框架开发指南 - 使用Ember AppBuilder设计应用程序

18 Zigbee应用程序框架开发指南 - 应用框架V6

15 应用程序框架插件

15.1 介绍

Zigbee应用程序框架包含对plugins的支持。plugins是通过框架的回调接口在框架内实现的一项功能。Zigbee应用程序框架附带了许多Cluster的默认实现，比如秘钥建立和price等。本章记录了Zigbee应用程序框架附带的一些plugins。

15.2 创建你自己的plugins

Plugins是回调接口的封装实现。如果一个特定的插件不能满足你的需要，你有两个选择。

1. 直接在应用程序中实现关联的回调
   1. 禁用插件并实现应用程序所需的回调。
   2. 这将把回调添加到application_callbacks.c文件中。
2. 创建您自己的插件从原来的
   1. 转到位于app/framework/plugin的stack install位置中的plugin目录。
   2. 将插件内容复制到app/framework/plugin内的新目录中。
      3.每个插件都包含一个名为plugin.properties的配置文件。AppBuilder使用这个文件来显示配置面板中的插件并管理框架中的依赖项。至少，您必须在插件中更改插件的名称。属性文件，以便您可以在AppBuilder中识别它。
   3. 完成此操作后，必须重新启动AppBuilder，以便在AppBuilder扫描stack安装目录时获取新plugin。

15.3 OTA升级插件

Over-the-air Bootload cluster是Smart Energy 1.1规范中的一项重要功能。它涉及到许多模块，以便支持所有Ember平台上的软件实现，以及客户端和服务器端。
本

节详细介绍了每个不同的部分，并描述了它们在Zigbee应用程序框架中的功能。

15.3.1 架构

本节解释Cluster的体系结构以及开发人员代码在Zigbee应用程序框架中的位置。

ZigBee Over-the-air Bootload (OTA) cluster 为所有设备提供了一种通用的方式，使其具有独立于制造商的方法来升级该领域的设备。ZigBee OTA cluster只支持应用程序引导加载程序，其中设备能够下载并将整个映像存储在外部存储器中，同时仍在ZigBee网络中运行。

ZigBee OTA Cluster定义了客户端设备查询新的升级映像和下载数据的协议，以及服务器设备如何管理下载和确定设备下载映像后何时升级。

Silicon Labs为客户端和服务器提供了所有Cluster代码，以正确处理和响应所有ZigBee OTA消息。此外，它还提供了用于管理存储的映像和引导加载目标芯片的代码。

关于升级的体系结构和如何处理它，必须做出许多决定。下面是几个需要回答的关键问题。

1. OTA升级image将使用什么外部存储设备?

   1. Silicon Labs提供了一些EEPROM驱动程序实现以及一个POSIX文件系统(仅适用于UART主机)。
   2. 如果需要不同的驱动程序或方法，则必须提供此代码。

2. 客户端设备是否需要多个升级文件才能引导加载?

   1. 如果是这样，多个升级文件可以被同时定位到通过无线传输的ZigBee OTA文件中。但是，这需要一个能够同时保存所有升级文件的存储设备。
   2. ZigBee OTA Cluster还支持请求多个文件，但是客户端必须对此进行管理。

3. 升级文件将如何标记?
   每个OTA文件都有一个制造商ID、一个图像类型ID和一个版本号。制造商ID的值由ZigBee分配，但是制造商控制另外两个值，可以将它们设置为任意值。选择使用什么值取决于开发人员使用的版本控制方案，以及如何区分来自同一制造商的产品。

4. 客户端设备将使用image signing 和verification 吗?

   1. 虽然支持ZigBee OTA Cluster对于Smart Energy 设备来说是可选的，但是如果设备确实支持该Cluster，那么制造商必须对升级image进行数字签名，并且他们的设备必须验证这些image的真实性和完整性。
   2. 使用image签名的制造商必须获得签名证书，并将允许的签名者的EUI64s嵌入到软件中，以便对下载的image进行验证。

5. 客户端将如何处理引导加载?
   引导加载是特定于设备的，尽管Silicon Labs提供了引导加载SOC和NCP芯片的示例代码。但开发人员可能需要提供额外的特定代码来支持他们自己的设备。

6. 服务器如何接收要发送给客户机的映像?
   Zigbee实现提供了一个POSIX服务器，它可以提供驻留在文件系统中的OTA文件。如果服务器是基于EEPROM的系统，那么必须创建一些其他机制来将images传输到服务器，以便将这些inages提供给ZigBee OTA客户端。

15.3.1.1 生成Zigbee OTA images

Silicon Labs提供了一个名为image-builder的工具，可以生成正确格式的ZigBee OTA images。该工具接收引导装载程序文件(例如EBL文件)，并根据命令行输入生成正确的格式，如图5所示。该工具还可以使用ZigBee OTA Cluster规范规定的ECDSA签名算法对images进行签名。
有关使用此工具的更多信息，请参阅文档AN716，使用images生成器的说明。

图5 OTA image生成

15.3.1.2 Image签名

ZigBeeSmart Energy Profile要求OTA文件由制造商签署。下载的文件必须在安装之前经过OTA客户端验证。当image被签名时，签名者的证书将自动作为标记包含在文件中，签名标记将作为文件中的最后一个标记添加。

授权签名证书的EUI必须嵌入到客户端当前的软件image中，以便验证只有属于设备制造商的证书才能对更新image进行签名。

对于希望使用签名和OTA image的开发和测试部署，可以使用来自Certicom测试CA的测试证书对image进行签名。image-builder工具中嵌入了一个用于此目的的测试证书，默认情况下， AppBuilder将该测试证书的EUI作为授权签名者包括在内。

注意:对于要发送到部署设备的生产image的生成，强烈建议制造商使用自己从认证生产CA颁发的证书对image进行签名，并且只指定这些EUIs作为授权签名者。

用于签名的证书和私钥与Smart Energy设备使用的证书和私钥类型相同。但是，应该以不同的方式处理它们的使用和存储。区别如下:

1. 用于签名的证书和私钥应该只用于签名。它们不应该作为特定于设备的证书和密钥放在设备上。无论设备是测试设备还是生产设备，这都是正确的。
2. 用于签署证书的EUI不应用于任何其他设备或任何其他目的。该EUI不应该是用于生产设备的通用EUIs池的一部分。
3. 建议使用三个不同的EUIs生成至少三个带有私钥的签名证书。多个签名证书允许弃用过期或泄漏的私钥。
4. 设备应设置为接受所有这些EUIs作为image的授权签名者。如果单个密钥或证书受到破坏，可以通过软件更新来弃用它，设备将不接受由该实体签名的image。在这种情况下，应该创建一个新的签名证书，以取代受影响的证书，随后的软件版本应该将其设置为授权签名者。在此期间，可以使用另外两个备选签名证书中的一个对软件更新进行签名。
5. 签名者私钥应该存储在访问权限有限的安全位置。

最后，应该注意的是，将生产设备证书与测试证书签名者(反之亦然)混在一起是行不通的。换句话说，如果一个设备拥有来自Certicom production CA的生产证书，那么它只能验证使用生产证书签名的image。类似地，具有测试证书的设备只能接受具有从认证测试CA颁发的证书的签名者。

15.3.2 Plugin架构

OTA插件的架构图如图6所示。

图6 OTA插件的架构

15.3.3 ZCL核心

这段代码由核心的Zigbee应用程序框架提供，并使用Zigbee Cluster Library执行传入和传出消息的基本解析和验证。

15.3.4 OTA Bootload Cluster Common Code Plugin

此插件为OTA客户端和服务器Cluster插件提供公共代码。如果启用了OTA Bootload Cluster Server Plugin或OTA Bootload Cluster Client Plugin，则必须启用它。

这个插件没有可配置的选项。

15.3.5 OTA Bootload Cluster Server Plugin

OTA服务器Cluster执行发送到服务器的无线引导加载Cluster客户端命令的消息解析，并生成发送到客户端的服务器命令。它不处理OTA文件的存储，而是依赖于外部模块的支持。它的作用只是验证传入的消息，并根据其自身支持的功能和OTA规范生成正确的回复。
Silicon Labs提供了一个Zigbee应用程序框架插件，用于实现服务器Cluster。

选项	说明
Page Request Support	OTA Server Cluster plugin可以支持ZigBee OTA Cluster的可选页面请求特性。如果启用此选项，服务器将响应页面请求并将下载image的多个块发送回客户端。

15.3.6 OTA Bootload Cluster Server Policy Plugin

此模块定义OTA服务器在接收来自客户端的特定请求时的响应方式。服务器cluster代码调用此模块，询问应该如何处理某些操作。例如，当客户端完成下载文件时，它向服务器发送一个升级结束请求，询问何时可以升级到新image。服务器cluster代码解析消息，然后调用服务器策略代码来确定答案。

此模块处理的其他策略示例包括如何在接收到下一个要下载的OTA image的查询时响应，以及如何在接收到image块请求时响应。

这个插件没有可配置的选项。

15.3.7 OTA Bootload Cluster Client Plugin

OTA客户端cluster执行发送到客户端的无线引导加载cluster服务器命令的消息解析，并生成发送到服务器的客户端命令。它不处理OTA文件的存储，而是依赖于外部模块来提供支持。它的作用只是验证传入的消息，并根据它自己支持的功能生成正确的回复。

Silicon Labs提供了一个Zigbee应用程序框架plugin，用于实现客户端cluster。该插件可选支持签名验证特性。当启用时，它将在生成发送回服务器的升级结束消息之前检查接收到的OTA文件上的ECDSA签名。

选项	说明
Query OTA Server Delay (minutes)	客户端多久向OTA服务器查询一次新的升级映像。
Download Error Threshold	导致下载中止的顺序错误数。
Upgrade Wait Threshold	无论如何，有多少对升级结束请求的连续的、丢失的响应导致下载被应用。
Server Discovery Delay (minutes)	当客户端未能成功发现OTA服务器时，它在网络中查找OTA服务器的频率。一旦客户端发现服务器，它就会记住该服务器，直到它重新启动。
Run Upgrade Delay Request (minutes)	当服务器之前告诉客户端等待时，客户端请求服务器应用之前下载的升级的频率。
Page Request Size	要从服务器请求的页面的大小。
Page Request Timeout (seconds)	等待页面请求传入的所有块的时间长度。在此时间过期之后，将使用image块请求单独请求丢失的包。
Signature Verification Support	这要求使用ECDSA签名对所有接收的image进行签名，并在下载完成后验证签名。如果一个image验证失败，它将被丢弃。此验证发生在可能验证内容的任何自定义验证之前。
Verification Delay (ms)	这控制了正在进行的验证过程的执行频率。当启用签名验证时，这将控制执行摘要计算的频率。对于OTA图像来说，摘要计算可能需要相当长的时间。系统的其他处理可能被认为更重要，因此我们在计算之间添加了延迟。这还控制了应用程序开发人员编写的自定义验证的执行频率。值0表示计算运行到完成。
Image Signer EUI64 0	授权为该客户端签署OTA image的设备的大端EUI64地址。忽略所有0的值。
Image Signer EUI64 1	授权为该客户端签署OTA image的设备的大端EUI64地址。忽略所有0的值。
Image Signer EUI64 2	授权为该客户端签署OTA image的设备的大端EUI64地址。忽略所有0的值。

注意: Image Signer EUI64 0选项的默认值是嵌入到Silicon Labs提供的Image
-builder工具中的测试证书的EUI64。使用此默认值将允许客户在从Certicom获得生产签名证书之前测试image签名和验证。

15.3.8 OTA Bootload Cluster Client Policy Plugin

此模块控制OTA Cluster客户端的行为。它指定在查询中使用的image信息、设备对image进行的自定义验证，以及当客户端收到升级到新image的命令时会发生什么。

Silicon Labs提供了一个插件，它提供了OTA客户端策略的简单实现。

注意:制造商ID不是在这个插件中设置的，而是在AppBuilder的“ZCL Clusters”选项卡中设置的。 选项 说明

选项	说明
Image Type ID	设备的OTA image标识符，用于查询OTA服务器关于要用于升级的下一个image。
Firmware Version	设备当前的固件版本，用于查询OTA服务器关于升级使用的下一个image。
Hardware Version	设备可能有一个硬件版本，限制了它们可以使用的图像。OTA image可以配置支持它们的最小和最大硬件版本。如果设备不受硬件版本的限制，那么这个值应该是0xFFFF
Perform EBL Verification (SOC only)	这将使用应用程序引导装载程序在签名验证通过后验证EBL image。

15.3.9 OTA存储Plugins

over-the-air cluster需要一个存储设备，用于存储OTA客户端接收的文件或OTA服务器提供的文件。这种存储根据设备的硬件和设计而变化。因此，此功能与核心cluster代码分离，并通过一组api进行访问。该接口支持管理多个文件、从文件中检索任意数据块以及对文件格式执行基本验证。

Silicon Labs目前提供了实现OTA存储模块的两个主要插件: OTA Storage POSIX Filesystem Plugin和OTA Simple Storage Plugin。

15.3.9.1 OTA Storage POSIX File System Plugin

该实现使用POSIX文件系统作为存储模块来存储和检索OTA文件的数据。它可以处理任意数量的文件。此插件与基于ezsp的Ember平台(EM35xx NCP)一起使用，其中主机通过UART连接到NCP。

这个插件没有可配置的选项。

15.3.9.2 OTA Simple Storage Plugin

这个实现提供了一个简单的存储模块，它只存储一个文件。它使用OTA存储驱动程序在OTA Cluster代码可访问的硬件或软件设备中执行数据的实际存储。当启用时，开发人员还必须选择OTA Simple Storage RAM Driver Plugin或OTA Simple Storage EEPROM Driver Plugin。

这个插件可以被一个EZSP-or一个基于SOC的平台使用。

这个插件没有可配置的选项。

15.3.9.3 OTA Simple Storage RAM Driver Plugin

这个驱动程序提供了一个用于存储文件的RAM存储设备。它只打算作为一个测试实现的发展余烬开发工具包;它不是为生产准备的代码。在将外部存储硬件集成到设备之前，此驱动程序可用于检查OTA Cluster的基本行为。存储设备已经有一个预先构建的OTA image，可以用来下载，但实际上并不执行升级。

这个插件没有可配置的选项。

15.3.9.4 OTA Simple Storage EEPROM Driver Plugin

这个驱动程序使用HAL例程从EEPROM读取和写入数据。

对于SOC平台，此模块处理重新映射image的细节，以便引导加载程序能够读取image。现有的引导加载程序要求EBL头是存储设备顶部的第一个字节，因此代码必须将OTA头重新定位到另一个位置，同时为以线性方式访问OTA文件的存储代码提供一个接口。

图7演示了磁盘上OTA image的更改。

图7 OTA image改变

选项	说明
SOC Bootloading Support	此选项启用SOC设备的引导加载支持。当启用时，它将重新映射OTA image文件，以便EBL数据位于EEPROM的顶部，因此可以被所有现有的Ember引导加载程序访问。它要求图像的EBL部分是文件中的第一个标记。启用此功能时，OTA存储的起始偏移量应为0。
EM35x SOC Only: Enable 4.2 Application Bootloader Compatibility Mode	运行EmberZNet PRO 4.2应用程序引导加载程序的EM35x SOC芯片的应用程序必须启用这种兼容模式，并包括一个新的EEPROM驱动程序(EmberZNet PRO 4.3或更高版本)的副本。通常，EM35x能够使用应用程序和引导加载程序共享的EEPROM驱动程序代码。但是，这个EEPROM驱动程序必须支持任意的页面写操作。EmberZNet PRO 4.2 EM35xx应用程序引导加载程序中包含的Ember驱动程序没有这种支持。因此这个插件不能使用它们，必须在应用程序中添加驱动程序的副本。
Frequency for Saving Download Offset to EEPROM (bytes)	当前下载偏移量以字节为单位存储到EEPROM的频率。如果设置为0，它将始终被写入到EEPROM。
OTA Storage Start Offset	EEPROM中OTA image存储位置的起始偏移量。
OTA Storage End Offset	EEPROM中OTA image存储位置的最后偏移量。
EEPROM Device Read-modify-write Support	此复选框指示底层EEPROM存储驱动程序是否支持读-修改-写，即可以重写flash页面的一部分而不擦除整个页面。如果驱动程序要求在写入任何数据之前清除页面，则不应选中此框。在EmberZNet 4.6.2之前，底层flash驱动程序需要读写支持。EmberZNet 4.6.2引入了在需要页面擦除的地方使用部件的能力。当为Ember开发板设计软件时，这个复选框应该保持选中状态，因为EEPROM部件需要读-修改-写支持。对于客户设计中使用的其他受支持的EEPROM部件，请参考表5，“受支持的串行Dataflash/EEPROM远程内存部件”，在文档UG103.6中，Ember应用程序开发基础:引导加载。

15.3.9.5 OTA Bootload Cluster Storage Common Code Plugin

这个插件提供了所有OTA存储插件的通用代码，并且必须在其中一个插件被启用时启用。
这个插件没有可配置的选项。

15.3.10 OTA Cluster Platform Bootloader Plugin

当客户端下载了一个完整的文件并准备好升级时，它等待来自服务器的命令来应用升级。收到升级命令后，OTA客户端集群代码将调用OTA客户端策略代码，以执行接下来的步骤来应用升级。

Silicon Labs提供了一个处理引导加载的插件。行为的不同取决于所使用的平台。OTA客户端策略插件调用这个插件来执行实际的引导加载。

对于SOC，引导加载代码只是调用HAL例程来执行应用程序引导加载程序。然后，应用程序引导加载程序从外部EEPROM中读取数据，将数据复制到芯片的内部闪存中，然后重新引导。

对于NCP, Silicon Labs提供了一个通过串行UART或SPI总线引导加载NCP的实现。这个实现只适用于作为EZSP NCP固件交付的一部分提供的Ember NCP引导加载程序。该实现在NCP上执行引导加载程序，通过xmodem将文件从主机上的存储设备传输到NCP，然后重新启动NCP。

对于主机，开发人员需要编写自己的代码来引导加载连接到NCP的主机系统。

15.3.11 OTA Cluster命令行接口

15.3.11.1 客户端命令

表15-1. OTA Cluster 客户端命令

命令	说明
zcl ota client printImages	打印OTA存储模块中存储的所有image及其索引
zcl ota client info	打印制造商ID、image类型ID和版本信息，当客户端向服务器发送下一个image时将使用这些信息。
zcl ota client status	打印OTA客户端下载的当前状态信息。
zcl ota client verify	在指定索引处对image执行签名验证。
zcl ota client bootload	通过调用OTA bootload回调函数，引导在指定索引处加载image。
zcl ota client delete	从OTA存储设备中删除指定索引处的image。
zcl ota client start	启动OTA客户端状态机。状态机发现OTA服务器，查询新image，下载image，并等待服务器命令升级。
zcl ota client stop	停止OTA客户端状态机。
zcl ota client page-request	如果客户端启用了Ember AppBuilder中的支持，则动态启用或禁用页请求的使用。默认情况下，如果客户端在Ember AppBuilder中启用了页面请求支持，那么客户端在下载文件时使用页面请求命令。
zcl ota client block-test	测试工具的命令。发送一个无效的块请求到客户端之前发现的OTA服务器，以验证服务器发送回正确的命令。

15.3.11.2 服务端命令

表15-2. OTA Cluster 服务端命令

命令	说明
zcl ota server printImages	打印OTA存储模块中存储的所有image及其索引
zcl ota server policy print	打印OTA服务器策略插件使用的策略。
zcl ota server delete	从OTA存储设备中删除指定索引处的图像
zcl ota server policy query	设置OTA Server策略插件在从客户端接收查询请求时使用的policy。Policy的值如下: 0:如果服务器更新(默认)则升级 1:降级如果服务器有旧的2:如果服务器有相同的重新安装 3:没有下一个版本(没有下一个图像可供下载)
zcl ota server policy blockRequest	设置OTA Server策略插件在接收到图像块请求时使用的策略。政策价值如下: 0:发送块(默认) 1:延迟下载一次，2分钟 2:总是在第一个块后中止下载
zcl ota server policy upgrade	设置OTA服务器策略插件在收到升级结束请求时使用的策略。政策价值如下: 0:立即升级(默认) 1: 2分钟内升级 2:以后请我升级
zcl ota server notify	此命令将OTA图像通知消息发送到指定的目的地，指示图像的新版本可供下载。有效载荷类型字段值为: 0:只包含抖动字段 1:包括jitter和manuf-id 2:包括jitter、manuf-id和device-id 3:包括抖动、手动id、设备id和版本 必须指定CLI命令中的所有字段。但是，如果负载类型小于3，这些值将被忽略，并且不包含在消息中。
zcl ota server page-req-miss	测试工具的命令。设置模块的值，该值告诉OTA服务器人为跳过响应图像页面请求时发送的某些图像块响应。这模拟了客户端稍后在页面请求完成后必须请求的遗漏块。如果服务器发送的块的数量是模数的倍数，那么它将被跳过。

15.3.12 OTA客户端状态机

下图展示了OTA引导加载集群客户端插件代码从开始到结束的运行方式

OTA Bootload Cluster Client Plugin Behavior

15.3.13 客户端和服务器设置示例

一个单独的应用说明(文档AN728，Zigbee Over-the-Air Bootload Cluster Client and Server Setup)描述了使用这些插件和EM35x开发工具包完成的客户端和服务器设置

15.4 报告Plugin

当报告设备需要定期发送报告时，可以在报告设备上设置报告。这个插件依赖于绑定。当本地ZCL属性发生更改时，每个报告都是从报告设备发送到绑定表中相应条目的异步消息。发送报告的节点、接收报告的节点或其他第三方配置设备都可以在报告节点上创建绑定表条目。这个插件既支持从另一个设备请求报告，也支持在设备被配置为这样做时发送属性报告。如果应用程序将从多个源接收报告，则应该将设备配置为集中器。

15.4.1 报告命令行接口（CLI）

该框架提供了CLI命令，用于直接在设备上创建和管理报告表表项、从另一个设备请求报告表以及配置设备以从另一个设备发送报告表。

1. 本地命令

* plugin reporting print 
Print the report table. 
* plugin reporting clear 
Print the report table. 
* plugin reporting remove [index:1] 
Remove an entry from the report table. 
* index – the index of the report to be removed (1 byte). 
* plugin reporting add [endpoint:1] [clusterId:2] [attributeId:2] [mask:1] [type:1] [minInterval:2] [maxInterval:2] [reportableChange:4] 
Add a new entry to the report table. 
* - endpoint – The local endpoint from which the attribute is reported (1 byte). 
* - clusterId – The cluster where the attribute is located (2 bytes). 
* - attributeId – The id of the attribute being reported (2 bytes). 
* - mask – 0 for client-side attributes or 1 for server-side attributes (1 byte). 
* - type – The type of the attribute being reported (1 byte). 
* - minInterval – The minimum reporting interval, measured in seconds (2 bytes). 
* - maxInterval – The maximum reporting interval, measured in seconds (2 bytes). 
* - reportableChange – The minimum change to the attribute that will result in a report being sent (4 bytes).

2. 远程命令

* zcl global report [endpoint:1] [clusterId:2] [attributeId:2] [direction:1] 
Creates a report with the specified cluster, attribute and server/client direction. 
* endpoint – src endpoint id to read from (2 bytes). 
* clusterId – cluster id to read from (2 bytes). 
* attributeId – the attribute id to read from (2 bytes). 
* direction – 0 for client-to-server, 1 for server-to-client (1 byte). 
* zcl global report-read [cluster:2] [attributeId:2] [direction:1] 
Creates a global read reporting command for the associated cluster, attribute and server/client direction. 
* cluster – cluster id to read from (2 bytes). 
* attributeId – the attribute id to read from (2 bytes). 
* direction – 0 for client-to-server, 1 for server-to-client (1 byte). 
* zcl global send-me-a-report [cluster:2] [attributeId:2] [dataType:1] [minReportTime:2] [maxReportTime:2] [reportableChange:-2147483648] 
Creates a global send me a report command for the associated values. 
* - cluster – The cluster id of the requested report (2 bytes). 
* - attributeId – The attribute id for requested report (2 bytes). 
* - dataType – The two byte ZigBee type value for the requested report (1 byte). 
* - minReportTime – Minimum number of seconds between reports (2 bytes). 
* - maxReportTime – Maximum number of seconds between reports (2 bytes). 
* - reportableChange – Amount of change to trigger a report. 
* zcl global expect-report-from-me [cluster:2] [attributeId:2] [timeout:2] 
Create an expect-report-from-me message with associated values. 
* - cluster – The cluster id of the requested report (2 bytes). 
* - attributeId – The attribute id for requested report (2 bytes). 
* - timeout – Maximum amount of time between reports.

15.4.2 通过CLI设置报告连接

下面的CLI示例对应用程序配置做了如下假设:
报表发送方应用程序应该在endpoint 6上实现基本的cluster。报表接收方应用程序应该在endpoint 1上实现基本的cluster。两个应用程序都应该打开调试消息。还假设这两个设备都以报表发送者节点作为网络的创建者加入了同一个网络。

1. 清除发送方节点上的所有绑定，因为报告是通过绑定发送的。

report_sender_cli> option binding-table clear

2. 通过接收节点向接收节点请求发送方的应用程序版本(cluster 0x0000, attribute 0x0001)的报告。

report_receiver_cli> zcl global send-me-a-report 0x0000 0x0000 0x20 10 20 {00}
report_receiver_cli> send 0 1 6

3.应观察下列产出:

report_sender_cli> CFG_RPT:(Basic) -direction:00, attr:0000 type:20, min:000A, max:0014
change:00
report_receiver_cli> CFG_RPT_RESP:(BASIC) -status: 00

4. 成功发送报告请求(status - 00)后，接收节点可以使用以下命令读取实际报告:

report_receiver_cli> zcl global report-read 0x0000 0x0000 0x00
report_receiver_cli>send 0 1 6

5. 应观察下列产出:

report_receiver_cli> READ_RPT_CFG_RESP: (Basic) - status:00, direction:00, attr:0000 type:20, min:000A, max:0014 change:00

6. 从接收节点查找节点字段ID或IEEEAddr。

report_receiver_cli > info

7. 在发送节点上创建绑定，以开始向接收方发送报告。

report_sender_cli> option binding-table set 0 0x0000 0x06 0x01 {EUI64 node ID from previous
step}

8. 应观察下列输出:

“set bind 0: 0x00”

9. 接收节点开始接收报告如下:

report_receiver_cli> RPT_ATTR: (Basic) - attr:0000 type:20, val:01

10. 取消报告(通过将最大间隔设置为0xFFFF)

report_receiver_cli> zcl global send-me-a-report 0x0000 0x0000 0x20 0x0000 0xFFFF {00}
report_receiver_cli>send 0 1 6

11. 应观察下列产出:

report_sender_cli> CFG_RPT: (Basic) - direction:00, attr:0000 type:20, min:0000, max:FFFF
change:00
report_receiver_cli> CFG_RPT_RESP: (Basic) – status: 00

报告外部属性
每当插件管理的属性发生变化时，框架会自动通知插件。使用外部属性的客户必须在这些属性更改时通知报表插件。没有通知插件将导致不正确的报告行为。任何将要报告外部属性的应用程序必须在外部属性更改时调用emberAfReportingAttributeChangeCallback。

15.5 Tunneling Plugin

在客户端和服务器之间建立通道，使用特定的协议(可能是特定于制造商的)和可选的流控制支持。客户端通过向服务器发送请求隧道命令来打开隧道。如果服务器不支持协议或流控制，它将拒绝通道。隧道插件根本不处理协议。相反，它们依赖于应用程序来解析原始数据，在服务器的情况下，则依赖于应用程序来指示是否支持特定的协议。隧道插件目前不支持流量控制，并自动拒绝请求流量控制的隧道。
隧道一旦建立，任何一方都可以使用传输数据命令发送数据。如果发送方无法访问隧道，则发送传输数据错误命令。如果插件接收到它们所属的隧道的传输数据错误命令，它们就会假设发生了错误，隧道现在已经关闭。
通道可以由客户机或服务器关闭。当客户机想要关闭通道时，它向服务器发送一个关闭通道命令。如果通道在一段时间内处于非活动状态(由close tunnel Timeout属性指定)，服务器可以关闭该通道。如果服务器关闭了不活动的通道，它不会通知客户机，因为在本例中假定客户机处于休眠状态。关闭通道超时属性可由用户通过插件选项进行调整。

15.5.1 Tunneling设置

1. 在AppBuilder中，选择File > New > Silicon Labs AppBuilder Project > Silicon Labs Zigbee > EmberZNet SoC 6.6.0.0 > Z3Light.。
2. 在ZCL Cluster配置选项卡上，将ZCL设备类型更改为任何SE设备。
3. 启用隧道集群客户端和/或服务器。
4. 启用通用隧道Cluster服务器。注意:规范说，隧道客户端必须包括通用隧道客户端，但这是规范中的一个错误。
5. 在Printing和CLI选项卡上，在应用程序特定调试打印部分，通过选中“Compiled in”和“Enabled at startup”旁边的“Tunneling cluster”复选框来启用隧道打印。
6. 通过检查“Debug”旁边的“Compiled in”和“Enabled at startup”复选框来启用打印调试。
7. 在“Stack configuration”选项卡上的“Other settings ”部分中，选择“Use fragmentation”。
8. 在Plugins选项卡上，检查隧道客户端和/或服务器插件是否启用，并调整任何特定于插件的选项。
9. 验证通用隧道客户端插件已启用。
10. 启用通用响应命令插件。
11. 单击Generate生成应用程序。
12. 在生成的application_callback .c文件中，修改emberAfPluginTunnelingServerIsProtocolSupportedCallback存根，以便它对应用程序支持的任何协议返回TRUE。

15.5.2 Tunneling命令行接口

该框架提供了用于打开和关闭通道以及发送数据的CLI命令。

15.5.3 Tunneling客户端命令行

* zcl tunneling request <protocol id:1> <manufacturer code:2> <flow control:1> 
* Protocols 0 through 5 are defined by the spec. 
* Protocols 6 through 199 are reserved for future use. 
* Protocols 200 through 254 are for manufacturer-specific protocols. 
* Protocol 255 is reserved. 
* The manufacturer code is only used when the protocol is 200 through 254. 
* The manufacturer code should be set to 0xFFFF when not used. 
* Flow control should be 0 when not used and 1 when used. 
* zcl tunneling close <tunnel id:2>
* The tunnel id is a unique 16-bit identifier assigned by the server and sent in the Tunnel Request Response command. 
* zcl tunneling transfer-to-server <tunnel id:2> <data> 
* The tunnel id is a unique 16-bit identifier assigned by the server and sent in the Tunnel Request Response command. 
* The data is raw protocol data and is not preceded by a length byte like other string types. 
* zcl tunneling random-to-server <tunnel id:2> <length:2> 
* The tunnel id is a unique 16-bit identifier assigned by the server and sent in the Tunnel Request Response command. 
* The length is the number of bytes of random data to send. 
* The framework and fragmentation library only support messages up to 255 bytes. With the three-byte ZCL header and the two-byte protocol id, only 250 bytes are left for the data.

15.5.4 Tunneling服务端命令行

* zcl tunneling transfer-to-client <tunnel id:2> <data> 
* The tunnel id is a unique 16-bit identifier assigned by the server and sent in the Tunnel Request Response command. 
* The data is raw protocol data and is not preceded by a length byte like other string types. 
* zcl tunneling random-to-client <tunnel id:2> <length:2> 
* The tunnel id is a unique 16-bit identifier assigned by the server and sent in the Tunnel Request Response command. 
* The length is the number of bytes of random data to send. 
* The framework and fragmentation library only support messages up to 255 bytes. With the three-byte ZCL header and the two-byte protocol id, only 250 bytes are left for the data.

15.5.5 Tunneling限制

隧道的两端应该确保只有隧道已建立的伙伴才被授予对它的读/写访问权。该规范提到通过检查发送节点的MAC地址来强制执行。插件目前只检查节点和端点id，而不检查MAC。隧道集群客户端和服务器应该通过从隧道集群客户端或服务器插件中读取最大传入传输大小和最大传出传输大小属性来协商最大传输大小。这些插件设置这些属性，但不从远程节点读取它们来协商传输的最大大小。