8. 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

8 事件

Zigbee应用程序框架及其相关的cluster代码使用Zigbee stack事件机制来调度SoC和主机上的事件。使用Zigbee事件机制可以节省代码和RAM，并且在休眠设备上工作得更好。

在较高的级别上，事件机制提供了一个中心位置，根据用户输入、无线命令或设备初始化，可以激活和停用设备采取的所有定期操作。事件机制优于它所取代的常量滴答机制，因为它允许Zigbee应用程序框架精确地知道下一个操作何时将在设备上发生。这对于睡眠设备来说是非常重要的，因为这些设备需要准确地知道它们什么时候必须醒来采取一些行动—或者更重要的是，它们不能入睡，因为一些事件正在发生。Zigbee应用程序框架有两种类型的事件:自定义事件和cluster事件。自定义事件由Zigbee应用程序框架用户创建，可用于应用程序中的任何目的。cluster事件与Zigbee应用程序框架插件中的cluster实现特别相关。

8.1 创建一个自定义事件

Zigbee应用程序框架使用Zigbee标准事件机制来控制和运行Zigbee应用程序框架内的“自定义”应用程序事件。Stack的事件机制记录在位于stack/include/event.h的event.h头文件中。

Zigbee应用程序框架和AppBuilder为创建和向应用程序添加定制事件提供了一个有用的接口。要在AppBuilder中创建自定义事件，请打开AppBuilder配置文件中的“include”选项卡。在“Event Configuration”部分单击Add new。这将一个事件添加到将由Zigbee应用程序框架运行的事件列表中，以及AppBuilder生成的“callbacks”文件的自定义事件存根。

8.1.1 事件功能和事件控制

自定义事件由两部分组成:事件函数(在事件触发时调用)和EmberEventControl结构(用于调度事件)。框架的事件机制必须知道这些项的每一个，以便它既可以跟踪下一个事件何时发生，以便睡觉，也可以知道当事件触发时调用哪个函数。在位于stack/include/event.h的event.h头文件中提供了关于创建事件的更多文档。

8.1.2 自定义事件示例

Z3Light示例应用程序使用自定义事件来管理其状态。该事件由两部分组成:EmberEventControl结构体(称为commissioningLedEventControl)和event函数(在每次事件触发时调用该函数)。该事件函数称为commitoningledeventhandler。事件和事件控件包含在示例应用程序附带的z3light_callks .c文件中。当基于此示例场景创建新应用程序时，可以在AppBuilder中的“General”选项卡的描述字段中找到Z3Light应用程序的文档。

8.2 怎样创建Cluster事件

每个Cluster都包括一个服务器和一个客户端“tick”回调。AppBuilder为每个endpoint上的每个Cluster服务器或客户机生成一个事件表，其中包含一个事件。实际的事件表被生成到<DeviceName>_endpoint_config.h报头中，该报头包含在Zigbee应用程序框架的事件代码中，并在app/framework/util/af-event.c中使用。

注意:事件表是在编译时创建的，并且是静态的。因此，事件不能在运行时从事件表中随机添加或删除。事件表条目必须存在，然后代码可以管理其日程安排，使其处于活动状态并等待调用，或者处于停用状态并等待激活和调度。

8.3 如何调度Cluster事件

插件或应用程序代码可以通过使用Zigbee应用程序框架的事件管理API来管理事件表中与Cluster相关的事件。这个API由两个函数组成，emberAfScheduleClusterTick和emberAfDeactivateClusterTick。

tick是事件系统中使用的基本时间单位。tick的持续时间取决于正在使用的平台。使用当前的Zigbee平台，1个tick大约等于

其中，MILLISECOND_TICKS_PER_SECOND是每秒时钟滴答的数量。因此，当调用emberAfScheduleClusterTick时，delayMs参数的值为t，该事件将在不小于

的范围内运行，当然，这个值的实际误差取决于时钟源的可靠性。

8.3.1 emberAfScheduleClusterTick

emberAfScheduleClusterTick使用endpoint,、cluster id和客户机/服务器标识来查找事件表中的关联事件。事件表条目由Ember AppBuilder生成到_endpoint_config.h。如果它找不到事件表条目，emberAfScheduleClusterTick将EmberStatus EMBER_BAD_ARGUMENT返回给调用者。如果找到了事件表条目，那么它就按照调用者请求的毫秒数安排事件的发生，并返回EMBER_SUCCESS。

EmberStatus emberAfScheduleClusterTick( int8u endpoint, int16u clusterId, boolean isClient, int32u timeMs, EmberAfEventSleepControl sleepControl);

EmberAfEventSleepControl参数允许调用者指示当事件在事件表中处于活动状态时设备可能执行的操作。此值仅与休眠设备相关;它对不睡觉的设备没有影响。EmberAfEventSleepControl的可能值在app/framework/include/af-types中枚举。h,如下:

EMBER_AF_OK_TO_HIBERNATE意味着应用程序可能会进入长时间的深度睡眠状态，直到需要调用事件为止。如果调度代码直到调用事件时都不关心设备做什么，则使用此睡眠控制值。
EMBER_AF_OK_TO_NAP意味着设备应该在小睡期间睡眠，并且应该在小睡期间醒来进行轮询，直到调用事件为止。如果调度代码希望设备周期性地轮询，直到调用事件，那么可以使用此睡眠控制值。如果计划的事件是等待来自网络上另一个设备的响应的超时，那么这一点特别有用。如果事件是超时，您不希望设备进入休眠状态，直到调用超时，因为它永远不会听到它正在等待的消息，从而确保将调用超时。
EMBER_AF_STAY_AWAKE表示设备不应该处于睡眠状态，而是应该保持清醒状态，直到调用事件为止。如果您正在安排一个非常频繁的事件，并且不希望设备小睡很短的时间，那么可以使用这个事件，因为设备将在每次醒来时进行轮询。如果设备完全处于休眠状态，它将每秒轮询一次。

8.3.2 emberAfDeactivateClusterTick

Deactivate函数用于关闭事件。在调用调度事件时应调用此函数，以确保事件代码不会继续调用该事件。如果事件不再需要，也可以在调用事件之前调用它。

注意:在Ember应用程序框架中，emberAfDeactivateClusterTick在事件触发之前被自动调用，以确保事件不会在每次触发时都被继续调用。您可以在Ember AppBuilder 2.1.50版本生成的事件表输出中看到对emberAfDeactivateClusterTick的调用。

DeactivateClusterTick类似于ScheduleClusterTick，因为它接受大多数相同的参数，因为它还必须在关闭事件表之前找到clusterTick。

EmberStatus emberAfDeactivateClusterTick(int8u endpoint, int16u clusterId, boolean isClient);