Z-Stack Home Developer's Guide—7.EZ-Mode中文翻译【Z-Stack Home 1.2.0的开发文档】

待我称王封你为后i 2022-05-19 07:42 98阅读 0赞

# 7. EZ-Mode #

EZ-Mode提供了两个设备正常交流的能力，无论这个2个设备是否在zigbee网络中。它包括网络控制、网络发现和网络绑定。EZ-Mode有如下特性：

*  网络控制 - 找到第一个开放的网络
 *  发现和绑定 - 找到一个远程节点(在网络的任何地方) 并且初始化合适的绑定基于应用程序提供的有效集群列表
 *  自动关闭 - 为了很多设备的快速绑定
 *  应用程序回调 - 允许应用程序执行用户提供的接口
 *  任何回调函数 - 应用程序在调用EZ-Mode的时候将调用这些函数

举一个简单的例子，EZ-Mode允许电灯开关被绑定到电灯上，或者 温度传感器或加热冷却设备绑定到自动调温器上。

EZ-Mode足够智能，可以知道一个电灯开关不能被绑定到一个温度传感器上，或者不能绑定到另一个光开关上。

在样例程序中，EZ-Mode在应用程序的HandleKeys函数(例如:zclSampleThermostat\_HandleKeys)执行回调函数，对于所有的Home Automation中的样例程序中。

由于zigbee路由器和zigbee终端设备无法自启动，应用程序也能将节点加入到网路中， 此外，如果有合适的，将会绑定到其他的远端设备上。

在zigbee网络中的设备，如果EZ-Mode生效，这些设备将开放这个网络(使其他设备能够加入)。相互绑定的设备，他们一旦终止他们的绑定，EZ-Mode将关闭这个网络。

每个设备只有一个EZ-Mode状态。EZ-Mode调用函数(zcl\_InvokeEZMode)是一个触发函数。  
如果EZ-Mode已经被启动，再次调用将会取消这个设备上的EZ-Mode。

在理解EZ-Mode时，下面这些术语应该被知道：

*  Opener - 已经在网络中的节点并且EZ-Mode已经被调用
 *  Joiner - 没有在网络中的节点并且EZ-Mode已经被调用
 *  Initiator - 发起 加入某个设备功能网络请求的节点(客户端)
 *  Target - 接收到 来自某个设备功能加入网络请求的节点(服务端)
 *  Active clusters - 设备的主要功能

如果要想网络恢复可行，网络配置信息要存储到NV内存(非易失性内存)中。EZ-Mode没有直接删除绑定的方法，除了设备恢复出厂设置。

Home Automation样例程序重置NV内存需要通过Shift-SW5(举例:按住按钮1然后按下操纵杆)，这个功能只在SmartRF05 + CC2530中有效。

SmartRF06 + CC2538中将NV内存重置为工厂默认值，这个设备需要被重新编程。各种各样的OTA在Zigbee调用中尽管显得非常的复杂，但是EZ-Mode为连接在一起的设备提供了一个非常可靠的基础线。

## 7.1 EZ-Mode 接口 ##

EZ-Mode的所有接口可以在zcl\_ezmode.h中找到。EZ-Mode应用程序接口被执行通过3个函数和一个单独的应用程序回调函数：

*  zcl\_RegisterEZMode - 在EZ-Mode被使用前一定会被调用
 *  zcl\_InvokeEZMode - 启动或者取消EZ-Mode
 *  zcl\_EZModeAction - 用于应用程序通知EZ-Mode的各种事件(比如加入网络或者接收身份查询命令)

应用程序必须支持Identify Cluster。EZ-Mode将继续自我识别每隔EZMODE\_TIME时间(默认是3分钟)

## 7.2 EZ-Mode 图解 ##

EZ-Mode在以下状态进行转换：

*  建立/加入网络（如果还没有在网络上）
 *  打开网络（通过允许加入请求）
 *  标识本身
 *  在EZ-Mode中找到一个远程节点
 *  匹配活动集群并绑定它们
 *  在一段时间内自动关闭以允许在两个方向上进行匹配
 *  完成状态码

网络控制、查找和绑定显示在以下两个流程图中。  
![这里写图片描述][70]  
Figure 5 - EZ-Mode 网络控制流程图  
网络控制流程图显示，EZ-Mode是如何形成、连接、打开和关闭网络的。这是假定只有一个开放网络位于HA通道列表的区域内。一个网络的正常状态是关闭的。  
![这里写图片描述][70 1]  
Figure 6 – EZ-Mode 寻找和绑定流程图  
寻找和绑定流程图显示EZ-Mode在网络中如何寻找和匹配另外一个设备。设备能够被许多其他设备相连(在网状网络中)。看HA规格将知道那个设备是发起者，那个设备是目标。

## 7.3 EZ-Mode代码 ##

EZ-Mode的大部分代码都是在zclezmode.c中找到的。  
这包括完整的状态机和用户接口,应用程序必须提供一些功能，使EZ-Mode能够通过各种状态。  
应用程序必须提供：

*  创建/加入网络的通知
 *  设备匹配的通知
 *  进入/退出识别模式
 *  2个事件(1个是状态改变，一个是用于整个EZ-Mode超时)

下面的例子展示了SampleLight应用程序如何通知EZ-Mode整体超时，什么时候处理下一个状态了

#ifdef ZCL_EZMODE
    if ( events & SAMPLELIGHT_EZMODE_NEXTSTATE_EVT )
    {
    zcl_EZModeAction ( EZMODE_ACTION_PROCESS, NULL );
    return ( events ^ SAMPLELIGHT_EZMODE_NEXTSTATE_EVT );
    }
    if ( events & SAMPLELIGHT_EZMODE_TIMEOUT_EVT )
    {
    
    zcl_EZModeAction ( EZMODE_ACTION_TIMED_OUT, NULL ); // EZ-Mode timed out
    return ( events ^ SAMPLELIGHT_EZMODE_TIMEOUT_EVT );
    }
    #endif // ZCL_EZMODE

通过使用ZCL\_EZMODE标志可以启用或禁用EZ-Mode。EZ-Mode需要标识族，所有也要确保使能ZCL\_IDENTIFY。  
如果EZ-Mode不生效，示例应用程序将使用终端设备绑定将应用程序绑定在一起。  
如果EZ-Mode不生效，确保能够实现自启动 通过禁用HOLD\_AUTO\_START标志在编译器的预定义中。或者这个节点不将加入网络。  
![这里写图片描述][70 2]  
Figure 7 – 使用EZ-Mode不生效，让ZCL\_EZMODE和HOLD\_AUTO\_START两个宏都不生效  
对这个不生效的选项，在这个名字前面添加’x’。这种方式，可以通过删除’x’让该选项稍后可以启用。(e.g. xHOLD\_AUTO\_START 意味着 hold auto start 失效的)。

# 英文原文 #

7 EZ-Mode  
EZ-Mode provides an ability to easily bind (connect) two devices together for normal communication, whether the  
devices are currently on a ZigBee network or not. It includes both the ability for network steering, and finding and  
binding. EZ-Mode includes the following features:  
 Network Steering – finds the first open network  
 Finding and Binding – finds a remote node (anywhere in the network) and initiates appropriate bindings  
based on an application supplied active output cluster list.  
 Autoclose - for rapid binding of many pairs of devices  
 Application Callbacks – allows the application to present an appropriate user interface  
 Any Invoke Method – applications can be creative in the method they invoke EZ-Mode  
As an example, EZ-Mode allows light switches to be bound to lights, or a temperature sensor or heating cooling unit  
to a thermostat.  
EZ-Mode is smart enough to know that a light switch cannot be bound to a temperature sensor, or to another light  
switch.  
In the sample applications, the EZ-Mode invoke call is performed in the application HandleKeys function (e.g.  
zclSampleThermostat\_HandleKeys), on switch 2 for all Home Automation Sample Applications. Since  
ZRs and ZEDs do not autostart, this also puts the node on the network, then, if appropriate, will bind to the other  
remote device.  
Devices that are on the network will open up the network (enable joining) while EZ-Mode is in effect. EZ-Mode  
will close the network as soon as both nodes in the pair have found each other and determined their bindings.  
There is only 1 EZ-Mode state machine per device. The EZ-Mode Invoke function (zcl\_InvokeEZMode) is a  
toggle. That is, if EZ-Mode has already been started, invoke will cancel EZ-Mode on that device.  
The following terms should be understood to understand EZ-Mode:  
 Invoke – Initiate EZ-Mode on a device  
 Opener – A node that is already on a network when EZ-Mode is invoked  
 Joiner – A node that is not on a network when EZ-Mode is invoked  
 Initiator – A node that initiates transactions (client) on the active clusters  
 Target – A node that receives transactions (server) from active clusters  
 Active clusters – The main functionality of a device (e.g OnOff for a light switch, or DoorLock for a  
DoorLockController)  
If NV\_RESTORE is enabled, network configuration is stored in NV memory, EZ-Mode has no method for  
removing bindings directly, other than to factory reset a device. The Home Automation sample applications reset  
NV memory on Shift-SW5 (i.e. press and hold Button 1 and then press down the Joystick), this functionality is only  
available in SmartRF05 + CC2530. To reset NV memory to factory defaults in SmartRF06 + CC2538, the device  
should be reprogrammed.  
While more sophisticated commissioning can be performed by various over-the-air ZigBee calls, EZ-Mode provides  
a solid base-line for connecting the appropriate devices together.  
7.1 EZ-Mode Interface  
The EZ-Mode interface can be found in zcl\_ezmode.h. The EZ-Mode application interface is performed through 3  
functions and a single application callback:  
 zcl\_RegisterEZMode – Must be called before EZ-Mode can be used  
Z-Stack Home Developer’s Guide SWRA441 Version 1.0  
21 Copyright © 2013 Texas Instruments, Inc. All rights reserved.  
 zcl\_InvokeEZMode – Used to invoke or cancel EZ-Mode  
 zcl\_EZModeAction – Used by the application to inform EZ-Mode of various events (such as when  
joining the network or receiving and IdentifyQuery command).  
The application must support the Identify Cluster. EZ-Mode will continue to identify itself for EZMODE\_TIME  
(which defaults to 3 minutes).  
7.2 EZ-Mode Diagrams  
EZ-Mode flows through the following states:  
 Forming/Joining the network (if not yet on a network)  
 Opening the network (through Permit Joining Request)  
 Identifying Itself  
 Finding a remote node in EZ-Mode  
 Matching active output clusters and binding them  
 AutoClose after a small period of time to allow Matching in both directions  
 Finish up with status code  
Network steering and Finding and Binding are shown in the following two flowchart diagrams.  
Figure 5 - EZ-Mode Network Steering Flowchart  
The Network Steering Flowchart indicates how EZ-Mode forms, joins, opens and closes the network. It is assumes  
that only 1 open network is in the area on the list of HA channels. A network’s normal state is closed.  
Z-Stack Home Developer’s Guide SWRA441 Version 1.0  
22 Copyright © 2013 Texas Instruments, Inc. All rights reserved.  
Figure 6 – EZ-Mode Finding and Binding Flowchart  
The Finding and Binding Flowchart shows how EZ-Mode finds and matches to another device in the network. The  
devices can be many hops away (using mesh networking). See the HA specification for which devices are initiators  
and which ones are targets.  
7.3 EZ-Mode Code  
The bulk of the code for EZ-Mode is found in zcl\_ezmode.c. This includes the full state machine and the user  
interface. In addition, the Application must supply some functionality to enable EZ-Mode to transition through  
various states.  
The application must supply:  
 Notification of forming/joining  
 Notification of cluster matching  
 Enter/exit identify mode  
 2 Events (one for state changes, one for an overall EZ-Mode timeout)  
The following example shows how the SampleLight application informs EZ-Mode to the overall timeout, and when  
it’s time to process the next state.  
\#ifdef ZCL\_EZMODE  
if ( events & SAMPLELIGHT\_EZMODE\_NEXTSTATE\_EVT )  
\{  
zcl\_EZModeAction ( EZMODE\_ACTION\_PROCESS, NULL );  
return ( events ^ SAMPLELIGHT\_EZMODE\_NEXTSTATE\_EVT );  
\}  
if ( events & SAMPLELIGHT\_EZMODE\_TIMEOUT\_EVT )  
\{  
Z-Stack Home Developer’s Guide SWRA441 Version 1.0  
23 Copyright © 2013 Texas Instruments, Inc. All rights reserved.  
zcl\_EZModeAction ( EZMODE\_ACTION\_TIMED\_OUT, NULL ); // EZ-Mode timed out  
return ( events ^ SAMPLELIGHT\_EZMODE\_TIMEOUT\_EVT );  
\}  
\#endif // ZCL\_EZMODE  
EZ-Mode may be enabled or disabled by the use of the ZCL\_EZMODE flag. EZ-Mode requires the Identify cluster,  
so make sure to also enable ZCL\_IDENTIFY.  
If EZ-Mode is disabled, the sample applications will use End Device Binding to bind applications together. If EZ-  
Mode is disabled, make sure to also enable auto start by disabling the HOLD\_AUTO\_START flag in the Compiler’s  
predefined compile-time flags, or the node won’t join the network.  
Figure 7 – To Disable EZ-Mode, disable both ZCL\_EZMODE and HOLD\_AUTO\_START  
To disable an option, place an ‘x’ in front of the name. This way, the option can later be enabled by removing the  
‘x’. (e.g. xHOLD\_AUTO\_START means hold auto start is disabled).

[70]: /images/20220519/9f20e8b9cb114077ac9963a3f9bda161.png
[70 1]: /images/20220519/e4f746f00ee94145ad02a6befaa9817e.png
[70 2]: /images/20220519/6fa42a571ce343c9b455bb1e5d4e138a.png