Z-Wave 700应用程序框架第五章 - Z-Wave 命令类

ZAF的一个基本特性是通过命令类进行通信。 为此目的，每个命令类都有一个C模块，其中处理传入的命令，并传输传出的命令。

1. 命令类通用接口

应用程序通常会在以下两种方式中使用CC:  

• 发送一个主动的命令，或者  

• 响应接收到的命令  

1.1 主动发送命令

请参阅下面的CC API定义示例。 虽然一些CC还没有遵守这个命名方案，但计划是越来越多的CC将遵守ZAF未来的每一个版本。

job_status_t CC_Basic_Set_tx( agi_profile_t * pProfile, uint8_t sourceEndpoint, uint8_t value, void (*pCbFunc)(transmission_result_t * pTransmissionResult));

一个控制设备，例如墙壁开关，可能需要发送一个Basic Set命令。 这就是上面例子中给出的函数的目的。 四个参数中的三个是在所有命令类api中都可以找到的通用参数:pProfile、sourceEndpoint和pCbFunc。 下面详细说明这些论点。 参数bValue是特定于Basic Set命令的。 要找到关于Basic Set或其他应用程序CCs及其命令的更多信息，请参见[11]。

• pProfile：pProfile指向AGI配置文件。 这必须是在应用程序的config_app.h文件的AGI部分中设置的配置文件之一。 

• sourceEndpoint：如果应用程序正在实现端点，则源端点必须设置为ENDPOINT_X，其中X是端点的编号，例如ENDPOINT_1。 如果应用程序没有端点，则源端点必须设置为ENDPOINT_ROOT。ENDPOINT_ROOT和ENDPOINT_X的枚举可以在ZW_TransportEndpoint.h文件中找到。 

• pCbFunc：该参数是一个指向回调函数的指针，该回调函数有一个TRANSMISSION_RESULT类型的参数。 该类型的定义可以在CC_Common.h文件中找到。 对于在关联中找到的每个节点，给定的回调函数将被调用一次。 当最后一个节点的传输完成时，isFinished值将被设置为TRANSMISSION_RESULT_FINISHED。

1.2 响应接收命令

每个CC实现都有一个handleCommandClass…()函数，它为给定的命令类提取接收到的帧。 需要将此函数添加到应用程序的Transport_ApplicationCommandHandlerEx()函数切换情况块中。 通常，帧携带“Set”或“Get”命令，结果调用一个函数来读取或写入数据。 由应用程序来实现CC头文件中作为外部函数提供的这些函数。

在应用程序端，Transport_ApplicationCommandHandlerEx()将找出哪个CC应该处理传入的帧:​​​​​​​

SwitchOnOff.c/* Call command class handlers */switch (pCmd->ZW_Common.cmdClass){ case COMMAND_CLASS_SWITCH_BINARY_V2: frame_status = handleCommandClassBinarySwitch(rxOpt, pCmd, cmdLength); break;

当相应的命令类的处理器被触发时，它将进一步处理接收到的帧: ​​​​​​​

CC_Binary_Switch.cswitch (pCmd->ZW_Common.cmd) { case SWITCH_BINARY_GET: if(FALSE == Check_not_legal_response_job(rxOpt)) { : /* Get the values from the application */ pTxBuf->ZW_SwitchBinaryReportV2Frame.currentValue = appBinarySwitchGetCurrentValue(rxOpt->destNode.endpoint); :

CC处理程序将准备报告框架，然后返回到应用程序获取特定于应用程序的数据: ​​​​​​​

CMD_CLASS_BIN_SW_VALappBinarySwitchGetCurrentValue(uint8_t endpoint){ UNUSED(endpoint); return onOffState;}

1.3  CC版本

CommandClass的版本在每个CC中使用宏设置: 

REGISTER_CC(COMMAND_CLASS, CC_VERSION, CC_handler);

这个宏在一个统一的地方定义CC的版本，不需要在其他地方设置CC版本。

对于BinarySwitch CC，版本定义为:​​​​​​​

REGISTER_CC(COMMAND_CLASS_SWITCH_BINARY, SWITCH_BINARY_VERSION_V2, handleCommandClassBinarySwitch);

1.4  True Status支持

从Z-Wave Plus V2开始，如果CC在[16]中定义的强制命令类列表中，那么它必须支持True StatusEngine(TSE)。 更多关于TSE的信息见第6.4。

2. 实现一个命令类

并不是所有的CC都已经在ZAF中实现。 因此，在某些情况下，必须为应用程序开发所需的命令类。

3. Association Group Information CC

有关AGI CC的一般介绍，请参阅[12]

AGI CC在两个C模块中实现:

• CC_AssociationGroupInfo

• Agi

这些模块一起服务于两个目的:

• 每个关联组的广告能力，和  

• 查找应用程序希望向其发送主动命令的相关设备。 

• API

• CC_AGI_Init()

• CC_AGI_LifeLineGroupSetup()

• CC_AGI_ResourceGroupSetup()

4. Battery CC

Battery CC在模块CC_Battery中实现。 如果需要，还可以向应用程序添加其他功能。 参见SensorPIR.c中的CC_Battery_BatteryGet_handler()作为示例。

5. Indicator CC

自Z-Wave Plus V2以来，Indicator CC是强制性的。 它可以用来识别网络中的设备，通过发送命令，例如，设置LED指示灯在一定时间内为ON。 

Indicator CC在模块CC_Indicator中实现。 

6. Notification CC Version 8

Notification CC通常用于传感器应用程序，因为它支持许多不同的通知/传感器类型。 有关Notification CC的一般信息，见[11]。

从历史上看，这个CC支持推和拉两种模式，而ZAF的实现试图覆盖两种模式。 然而，推和拉模式在CC的版本8中已经分离，ZAF现在只支持和测试推模式，因为同时支持这两种模式会导致认证冲突。 

Notification CC由两个C模块实现:  

• CC_Notification

• Notification

Notification CCAPI由以下函数组成。 关于它们的作用、参数和返回值的信息，请参考notification.h的源头文件。

• InitNofication()

• AddNotification()

• DefaultNotificationStatus()

• NotificationEventTrigger()

• UnsolicitedNotificationAction()

典型的调用顺序如下所示:

1.  通过调用InitNofication()来初始化Notification CC。 

2.  可选地，通过调用DefaultNotificationStatus()为所有可用的通知设置通知状态(受config_app.h中MAX_NOTIFICATIONS定义的限制)。 

3. 根据应用程序实现了多少种不同的通知类型，多次调用AddNotification()。 

4.  通过调用NotificationEventTrigger()来触发事件，并通过调用UnsolicitedNotificationAction()来传输事件。 

5.  如果一个状态被触发与一个事件相反，可以通过调用NotificationEventTrigger()来取消状态，并使用取消参数，然后通过调用UnsolicitedNotificationAction()来传输取消。

7. Supervision CC

关于Supervision CommandClass的定义，请参考[7]。

CC Supervision内置在应用框架中，并在S2封装的帧上处理Supervision通信。Supervision只支持Set和Report命令。 

默认设置是CC Supervision每个Supervision Get命令只支持一个Supervision Report。 在Supervision Get命令中，“more status updates”字段被设置为CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED。 如果默认配置满足应用程序的要求，应用程序不需要初始化CCSupervision。

CC Supervision的初始化:​​​​​​​

voidCommandClassSupervisionInit( cc_supervision_status_updates_t status_updates, void (*pGetReceivedHandler)(SUPERVISION_GET_RECEIVED_HANDLER_ARGS * pArgs), void (*pReportReceivedHandler)(cc_supervision_status_t status, uint8_t duration));

7.1  配置

7.1.1   默认配置

应用程序只能处理一个以上的Supervision报告。 设备收到一个Supervision Get，返回一个Supervision Report，报告内容为CC_SUPERVISION_STATUS_SUCCESS。 不需要调用commandclasssupervise init()进行初始化。

7.1.2  处理更多的Supervision 报告

应用程序能够显示一个目标节点正在处理传输的命令。 一个例子是带有显示器的墙壁控制器，它显示一个工作设备(CC_SUPERVISION_STATUS_WORKING)，直到执行了给定的命令(CC_SUPERVISION_STATUS_SUCCESS)。​​​​​​​

void ApplicationInitSW(..){ CommandClassSupervisionInit( CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED, NULL, ZCB_CommandClassSupervisionReportReceivedHandler);}
void ZCB_CommandClassSupervisionReportReceivedHandler(cc_supervision_status_t status, BYTEduration){ :}

7.1.3   控制Supervision报告

应用程序能够发送多个Supervision report来报告正在进行的活动。 例如，Door Lock Key Pad报告Door Lock Operation何时开始门锁操作和何时完成门锁操作。​​​​​​​

void AppStateManager(..){ CommandClassSupervisionInit( CC_SUPERVISION_STATUS_UPDATES_NOT_SUPPORTED, ZCB_CommandClassSupervisionGetReceived, NULL);}
void ZCB_CommandClassSupervisionGetReceived(SUPERVISION_GET_RECEIVED_HANDLER_ARGS * pArgs){ :}