ZigBee ZCL Alarms集群：物联网设备告警机制与工程实践详解

1. ZigBee ZCL Alarms集群：物联网设备告警机制深度解析

在物联网和智能家居系统的开发中，设备间的可靠通信与状态监控是决定系统稳定性和用户体验的关键。我们常常需要让一个设备在发生异常时，能够及时通知网络中的其他设备，比如烟雾传感器检测到火情时触发声光报警器，或者温湿度传感器在数值超标时向网关发送一条告警信息。ZigBee协议栈作为低功耗、自组网领域的成熟方案，其应用层标准——ZigBee Cluster Library（ZCL）——为我们定义了实现这类功能的标准“语言”。今天，我们就来深入聊聊ZCL中专门负责处理这类“异常事件”的Alarms集群（Cluster ID: 0x0009）。

这个集群的核心价值在于，它为分布式物联网节点提供了一套标准化的告警管理框架。想象一下，如果没有这套标准，每个厂商的传感器告警格式都不同，网关和报警器就需要为每个设备编写特定的解析逻辑，系统集成将变得异常复杂且脆弱。Alarms集群的出现，正是为了解决这个互操作性的痛点。它规定了告警如何产生、如何发送、如何记录日志以及如何被远程控制，让不同厂商、不同类型的设备能够用同一种“方言”来沟通紧急事件。在智能安防、环境监测、工业设备状态监控等对实时性和可靠性要求极高的场景中，这套机制是构建健壮系统的基石。

2. Alarms集群的核心架构与工作原理

要理解Alarms集群，首先要抛开它只是一个简单“报警器”的刻板印象。它是一个完整的、基于客户端-服务器（Client-Server）模型的通信与服务框架。在这个模型里，服务器（Server）是告警的“生产者”和“记录者”，通常部署在传感器或执行器这类终端设备上。当设备上的某个功能集群（比如温度传感器所属的Temperature Measurement集群）检测到越界等异常条件时，它会触发Alarms集群服务器。客户端（Client）则是告警的“消费者”和“响应者”，通常部署在网关、协调器或具有用户界面的控制设备上，负责接收、显示告警，并可能向用户提供复位等控制接口。

2.1 告警的生命周期与数据流

一个完整的告警生命周期，可以清晰地分为几个阶段，理解这个流程对正确使用API至关重要。

第一阶段：告警的触发与生成告警并非由Alarms集群自身凭空产生。它依赖于设备上其他“功能集群”。例如，一个门窗传感器（Door Lock集群）在非法开锁时，会生成一个特定的“告警代码（Alarm Code）”，比如0x01表示非法闯入。这个告警代码和产生告警的集群ID（Cluster ID）一起，构成了告警的核心身份信息。此时，应用程序需要调用eCLD_AlarmsSignalAlarm()函数。这个函数做了两件关键事情：第一，它将这条告警记录到设备本地的“告警日志表（Alarms Table）”中；第二，它向网络中指定的Alarms集群客户端发送一条“告警通知（Alarm Notification）”命令。

第二阶段：告警的传输与接收告警通知通过ZigBee网络层进行单播、组播或广播。当客户端设备收到这条命令后，其ZCL层会生成一个E_CLD_ALARMS_CMD_ALARM事件，并携带告警代码和集群ID。客户端的应用程序通过预先注册的回调函数捕获这个事件，从而知道“哪个设备”、“哪个功能”出了“什么问题”。此时，客户端可以执行预设动作，比如点亮LED、发出蜂鸣、或者在APP上推送一条消息。

第三阶段：告警的处置与管理告警产生后，其状态需要被管理。这里有几个关键操作：

• 清除（Clear）：由服务器端主动发起。当告警条件消失后（比如温度恢复正常），服务器应用程序可以调用eCLD_AlarmsClearAlarm()函数，向客户端发送“清除告警”命令，通知客户端停止告警指示（如关闭蜂鸣器）。客户端会收到E_CLD_ALARMS_CMD_CLEAR_ALARM事件。
• 复位（Reset）：由客户端主动发起。用户通过客户端界面（如一个复位按钮）确认处理了某个告警后，客户端可以调用eCLD_AlarmsCommandResetAlarmCommandSend()函数，向服务器发送“复位告警”命令。服务器收到后会产生E_CLD_ALARMS_CMD_RESET_ALARM事件，应用程序可以据此将对应的告警日志条目标记为“已处理”或直接删除。eCLD_AlarmsCommandResetAllAlarmsCommandSend()则用于一次性复位所有告警。
• 查询（Get）与日志管理：客户端可以调用eCLD_AlarmsCommandGetAlarmCommandSend()向服务器查询告警日志中时间最早的一条记录，服务器在返回响应后会删除该条目。服务器端也可以通过eCLD_AlarmsGetAlarmFromLog()主动读取日志，或通过eCLD_AlarmsResetAlarmLog()清空整个日志表。

2.2 告警日志表：系统的“黑匣子”

Alarms集群服务器内部维护着一个“告警日志表”，这是实现可靠告警管理的关键。每一条告警记录都包含三个核心字段：

1. 告警代码（Alarm Code）：一个8位无符号整数，用于标识具体的告警类型。这里有一个至关重要的设计：告警代码的含义是由产生告警的“源集群”定义的，而不是Alarms集群本身。例如，对于温度集群，0x01可能代表“温度过高”，而对于门锁集群，0x01可能代表“非法开锁”。这意味着开发者在实现时，必须查阅相应功能集群的规范来定义和理解告警代码。
2. 集群ID（Cluster ID）：一个16位无符号整数，明确指出是哪个功能集群触发了此告警（例如，温度测量集群的ID是0x0402）。结合告警代码，才能唯一确定告警的具体含义。
3. 时间戳（Time-stamp）：一个32位的UTC时间戳，记录告警发生的精确时间。这里有一个重要的依赖：如果设备需要记录带时间的告警，它必须同时实现并正确同步ZCL的Time集群（Cluster ID: 0x000A），否则时间戳字段可能无效（例如被设置为0xFFFFFFFF）。

日志表有最大容量限制，通常在编译时通过配置项设定。当表满时，新的告警条目可能会覆盖最旧的条目，具体策略取决于实现。这个日志表相当于设备的“黑匣子”，为事后故障诊断和历史状态回溯提供了宝贵数据。

3. 工程实现：从初始化到告警处理全流程

理解了原理，我们来看如何在实际的嵌入式C代码中实现它。这里以NXP（原Jennic）的ZigBee PRO协议栈为例，其API设计具有代表性。

3.1 环境配置与集群初始化

在开始编码前，必须在工程配置中启用Alarms集群。这通常在zcl_options.h文件中完成：

// 在 zcl_options.h 中启用 Alarms 集群 #define CLD_ALARMS // 根据设备角色，启用客户端或服务器端功能（或两者） #define ALARMS_CLIENT // 如果设备需要接收和处理告警 #define ALARMS_SERVER // 如果设备需要产生和发送告警

如果你的设备需要告警时间戳功能，务必确保Time集群也已正确配置和同步。

集群的初始化发生在设备启动阶段。对于自定义端点（非标准ZigBee设备模板），你需要显式调用创建函数：

// 定义告警集群的自定义数据结构，用于内部状态管理 tsCLD_AlarmsCustomDataStructure sAlarmsCustomData; // 定义属性存储结构 tsCLD_Alarms sAlarmsClusterAttributes; // 定义属性控制位数组（用于控制属性是否可读/可写等） uint8 au8AlarmsAttributeControlBits[1]; // 根据实际属性数量定义数组大小 // 创建Alarms集群实例（以服务器为例） teZCL_Status eStatus = eCLD_AlarmsCreateAlarms( &sClusterInstance, // 指向集群实例结构体的指针 TRUE, // bIsServer: TRUE表示创建服务器，FALSE表示客户端 &sCLD_Alarms, // 指向集群定义结构体的指针（通常使用库提供的sCLD_Alarms） &sAlarmsClusterAttributes, // 指向属性存储结构的指针 au8AlarmsAttributeControlBits, // 属性控制位数组 &sAlarmsCustomData // 指向自定义数据结构的指针 ); if (eStatus != E_ZCL_SUCCESS) { // 处理初始化失败错误 }

注意：对于标准ZigBee设备类型（如HA标准的On/Off Light），通常使用设备注册函数（如eHA_RegisterOnOffLight）来一次性注册所有必需集群，其中可能已包含Alarms集群，无需单独调用eCLD_AlarmsCreateAlarms。务必查阅设备类型的实现文档。

3.2 告警的触发与发送（服务器端）

当你的应用逻辑（例如，读取传感器值并判断越界）检测到需要告警的条件时，就需要触发告警。以下是典型流程：

void vSensorCheckTask(void) { int16 i16Temperature = i16ReadTemperatureSensor(); // 假设温度超过35摄氏度触发高温告警 if (i16Temperature > 3500) { // 温度属性通常以0.01°C为单位 tsZCL_Address sDestinationAddress; uint8 u8TSN; // 1. 设置目标地址（例如，发送到网关） sDestinationAddress.eAddressType = E_ZCL_AM_SHORT; // 使用短地址 sDestinationAddress.uAddress.u16DestinationAddress = 0x0000; // 网关短地址 // 2. 发送告警通知并记录日志 teZCL_Status eStatus = eCLD_AlarmsSignalAlarm( APP_SOURCE_ENDPOINT, // 本设备端点号 GATEWAY_DEST_ENDPOINT, // 目标设备端点号 &sDestinationAddress, // 目标地址 &u8TSN, // 事务序列号（用于匹配请求与响应） 0x01, // 告警代码：根据温度集群规范定义，例如0x01为高温 0x0402 // 集群ID：Temperature Measurement Cluster ); if (eStatus != E_ZCL_SUCCESS) { DBG_vPrintf(TRUE, “Alarm signal failed: %d\n”, eStatus); // 可以考虑重试机制或本地缓存告警 } // 3. （可选）标记本地状态，防止短时间内重复发送相同告警 bHighTempAlarmActive = TRUE; } // 当温度恢复正常时，可以发送清除命令 else if (bHighTempAlarmActive && i16Temperature <= 3000) { // 调用 eCLD_AlarmsClearAlarm(...) 发送清除告警命令 bHighTempAlarmActive = FALSE; } }

关键点解析：

• eCLD_AlarmsSignalAlarm函数是一个“一站式”服务，它内部既调用了eCLD_AlarmsAddAlarmToLog来记录日志，又构造并发送了告警通知命令。这保证了日志和通知的原子性。
• 事务序列号（TSN）是一个重要的网络概念。它由协议栈自动生成（通过传入的&u8TSN参数返回），并包含在发送的命令中。当对方回复响应时，会携带相同的TSN，这样应用程序就能将响应与之前的请求正确关联起来，在处理多个并发请求时非常有用。
• 目标地址类型eAddressType可以是短地址（E_ZCL_AM_SHORT）、长地址（E_ZCL_AM_IEEE）、组播（E_ZCL_AM_GROUP）或广播（E_ZCL_AM_BROADCAST）。在智能家居中，向网关单播是最常见的方式，而组播则适用于向一组同类设备（如所有卧室的声光报警器）同时发送告警。

3.3 告警的接收与处理（客户端端）

在客户端设备（如网关）上，你需要为端点注册一个回调函数，用于处理所有集群的事件，包括Alarms集群的事件。

// 应用层事件回调函数 PRIVATE teZCL_Status eAppZclEventHandler( tsZCL_CallBackEvent *psEvent ) { switch (psEvent->eEventType) { case E_ZCL_CBET_CLUSTER_CUSTOM: // 处理自定义集群命令事件 if (psEvent->uMessage.sClusterCustomMessage.u16ClusterId == GENERAL_CLUSTER_ID_ALARMS) { // 获取Alarms集群特定的回调消息结构 tsCLD_AlarmsCallBackMessage *psAlarmMsg = (tsCLD_AlarmsCallBackMessage*)psEvent->uMessage.sClusterCustomMessage.pvCustomData; switch (psAlarmMsg->u8CommandId) { case E_CLD_ALARMS_CMD_ALARM: // 收到告警通知！ DBG_vPrintf(TRUE, “Alarm Received! Cluster: 0x%04X, Code: %d\n”, psAlarmMsg->uMessage.psAlarmCommandPayload->u16ClusterId, psAlarmMsg->uMessage.psAlarmCommandPayload->u8AlarmCode); // 根据集群ID和告警代码，执行相应动作 vHandleAlarm(psAlarmMsg->uMessage.psAlarmCommandPayload->u16ClusterId, psAlarmMsg->uMessage.psAlarmCommandPayload->u8AlarmCode); break; case E_CLD_ALARMS_CMD_CLEAR_ALARM: // 收到清除告警命令 DBG_vPrintf(TRUE, “Alarm Cleared. Cluster: 0x%04X, Code: %d\n”, psAlarmMsg->uMessage.psAlarmCommandPayload->u16ClusterId, psAlarmMsg->uMessage.psAlarmCommandPayload->u8AlarmCode); vStopAlarmIndicator(psAlarmMsg->uMessage.psAlarmCommandPayload->u16ClusterId, psAlarmMsg->uMessage.psAlarmCommandPayload->u8AlarmCode); break; // ... 处理其他命令，如 GET_ALARM_RESPONSE default: break; } } break; // ... 处理其他类型事件 } return E_ZCL_SUCCESS; } // 在初始化时注册回调函数 eZCL_RegisterEndpoint(APP_SOURCE_ENDPOINT, &sEndpointDefinition, &eAppZclEventHandler, FALSE);

回调机制详解：ZCL采用统一的事件回调模型。所有集群的自定义命令（包括Alarms集群的告警、清除、复位等命令）都会汇聚到端点注册的回调函数中，并通过E_ZCL_CBET_CLUSTER_CUSTOM事件类型来标识。开发者需要通过检查psEvent->uMessage.sClusterCustomMessage.u16ClusterId来判断是哪个集群的事件，再通过psAlarmMsg->u8CommandId来区分具体的命令。这种设计使得事件处理逻辑清晰集中。

3.4 告警的查询与复位（客户端发起）

客户端可以主动查询服务器的告警日志，或请求复位告警。例如，在网关的Web界面上点击“查看历史告警”或“一键复位所有告警”按钮时，会触发以下调用：

// 查询最早的一条告警记录 teZCL_Status eStatus = eCLD_AlarmsCommandGetAlarmCommandSend( GATEWAY_ENDPOINT, // 本地端点 SENSOR_ENDPOINT, // 目标传感器端点 &sSensorAddress, // 传感器地址 &u8TSN // 事务序列号 ); // 发送成功后，需要等待并处理 E_CLD_ALARMS_CMD_GET_ALARM_RESPONSE 事件 // 复位特定告警（例如，用户确认处理了高温告警后） tsCLD_AlarmsResetAlarmCommandPayload sPayload; sPayload.u8AlarmCode = 0x01; // 高温告警代码 sPayload.u16ClusterId = 0x0402; // 温度集群ID eStatus = eCLD_AlarmsCommandResetAlarmCommandSend( GATEWAY_ENDPOINT, SENSOR_ENDPOINT, &sSensorAddress, &u8TSN, &sPayload ); // 复位所有告警（例如，设备维护后） eStatus = eCLD_AlarmsCommandResetAllAlarmsCommandSend( GATEWAY_ENDPOINT, SENSOR_ENDPOINT, &sSensorAddress, &u8TSN );

4. 关键数据结构与API函数精讲

仅仅会调用函数还不够，理解背后的数据结构是进行高级调试和定制开发的基础。

4.1 核心数据结构剖析

1. 告警命令载荷（Command Payloads）这是网络传输中实际承载数据的结构。例如，复位单个告警的命令载荷：

typedef struct { uint8 u8AlarmCode; uint16 u16ClusterId; } tsCLD_AlarmsResetAlarmCommandPayload;

它非常简单，仅包含告警的唯一标识（代码+集群ID）。而告警通知（Alarm）和清除告警（Clear Alarm）命令的载荷结构与之相同。Get Alarm响应载荷则额外包含一个时间戳字段u32TimeStamp。

2. 回调消息结构（tsCLD_AlarmsCallBackMessage）这是应用层处理事件时获取具体信息的桥梁。

typedef struct { uint8 u8CommandId; // 命令ID，用于区分是ALARM、CLEAR_ALARM还是RESET_ALARM等 union { tsCLD_AlarmsResetAlarmCommandPayload *psResetAlarmCommandPayload; tsCLD_AlarmsAlarmCommandPayload *psAlarmCommandPayload; // 注意：Alarm和Clear共用此结构 tsCLD_AlarmsGetAlarmResponsePayload *psGetAlarmResponse; } uMessage; } tsCLD_AlarmsCallBackMessage;

这里使用了一个联合体（union），意味着uMessage在同一时刻只指向其中一种载荷结构，具体是哪种由u8CommandId决定。这种设计节省了内存空间，因为一个事件不可能同时是多种命令类型。

3. 自定义数据结构（tsCLD_AlarmsCustomDataStructure）这个结构由协议栈内部使用，用于管理集群实例的状态、回调事件地址等。开发者通常不需要直接操作其字段，但需要在创建集群实例时为其分配内存并传入指针。

4.2 核心API函数详解与实战要点

输入材料中列出了9个核心API，我们将其分为创建、服务器操作、客户端操作三类，并补充实战中的关键细节。

关于错误处理：所有API都返回teZCL_Status类型的状态码。除了检查E_ZCL_SUCCESS，必须重视E_ZCL_ERR_ZTRANSMIT_FAIL这类网络层错误。此时可以调用eZCL_GetLastZpsError()获取底层ZigBee PRO栈的错误码进行深度诊断，例如判断是路由失败、信道访问冲突还是目标设备无响应。

5. 高级应用场景、调试技巧与避坑指南

掌握了基础API调用后，我们来看看如何在实际复杂项目中用好Alarms集群，以及那些手册里不会写的“坑”。

5.1 设计模式与最佳实践

1. 告警代码的规划与管理告警代码是8位整数，范围0x00-0xFF。0x00通常保留，0xFF可能用于“未知告警”或自定义用途。强烈建议为项目建立一个统一的《告警代码定义表》文档。例如：

• 0x01-0x7F：预留给ZCL标准集群或行业规范（如ZigBee Home Automation）已定义的告警。
• 0x80-0xFE：用于厂商自定义告警。 为每个自定义告警明确其含义、触发条件、严重等级（如INFO, WARNING, CRITICAL）和推荐的客户端处理动作。

2. 告警风暴抑制与去抖在边缘场景下，传感器可能因信号抖动在阈值附近频繁触发/恢复告警，导致网络拥塞和客户端刷屏。

• 硬件去抖：在传感器信号输入侧增加滤波电路。
• 软件去抖：在调用eCLD_AlarmsSignalAlarm前增加逻辑。例如，采用“延时确认”机制：当检测到告警条件后，启动一个定时器（如5秒），只有在该条件持续超过定时器时长后才真正发送告警。同时，在告警活跃期间，忽略后续的重复触发条件。

static bool_t bAlarmDebouncing = FALSE; static uint32 u32AlarmTriggerTime = 0; void vCheckAlarmCondition(bool_t bConditionMet) { if (bConditionMet && !bAlarmActive) { if (!bAlarmDebouncing) { // 首次触发，启动去抖计时 bAlarmDebouncing = TRUE; u32AlarmTriggerTime = u32GetSystemTick(); } else { // 已在去抖期内，检查是否持续超时 if ((u32GetSystemTick() - u32AlarmTriggerTime) > DEBOUNCE_TIME_MS) { vTriggerRealAlarm(); // 真正触发告警 bAlarmActive = TRUE; bAlarmDebouncing = FALSE; } } } else if (!bConditionMet) { // 条件不满足，重置去抖状态 bAlarmDebouncing = FALSE; if (bAlarmActive) { vClearAlarm(); // 发送清除告警命令 bAlarmActive = FALSE; } } }

3. 离线与队列处理对于电池供电的终端设备，大部分时间可能处于睡眠状态，无法立即发送告警。此时，应将告警记录到非易失性存储器（如Flash）中，并在设备唤醒联网后，从存储中读取历史告警并按顺序或按优先级发送。这需要应用层实现一个简单的持久化队列。

4. 告警升级与联动简单的点对点告警可能不够。可以设计“告警升级”逻辑：如果一条告警在超时时间内未被客户端确认或复位，服务器可以将其标记为“升级”，并发送给更高优先级的设备或采用更紧急的通信方式（如提高发送功率、缩短重试间隔）。这需要客户端在收到告警后，向服务器发送一个确认回执（可通过自定义命令或Write Attribute实现）。

5.2 常见问题排查与调试技巧

在实际开发中，你可能会遇到以下问题：

问题1：客户端收不到告警通知。

• 排查网络连通性：首先确认两台设备已成功入网，并且路由可达。使用网络抓包工具（如Ubiqua）是终极手段，可以查看Alarms命令是否真的在空口发出。
• 检查端点与集群ID：确认服务器发送和客户端接收时使用的端点号、集群ID（必须是0x0009）是否正确。
• 确认客户端角色：客户端的Alarms集群实例是否以FALSE（客户端模式）创建？属性控制位是否允许接收命令？
• 检查回调函数：客户端的应用层回调函数是否已正确注册到目标端点？是否正确处理了E_ZCL_CBET_CLUSTER_CUSTOM事件并筛选了Alarms集群的ID？

问题2：告警日志表条目丢失或混乱。

• 日志表大小：检查编译配置中告警日志表的最大条目数。如果设置过小，新告警会覆盖旧告警。
• 时间戳问题：如果时间戳全是0xFFFFFFFF，检查设备是否实现了Time集群，并且时间是否已从网络同步（通常从协调器同步）。
• 并发访问：确保在添加（AddAlarmToLog）和读取/删除（GetAlarmFromLog）告警日志时，没有中断或任务切换导致的数据竞争。如果系统是多任务环境，应考虑使用信号量保护对日志表的访问。

问题3：eCLD_AlarmsSignalAlarm返回发送失败。

• 检查目标地址：psDestinationAddress结构体中的地址类型和地址值是否正确？短地址在设备重启或离开重加入后可能会变化，长地址（IEEE地址）更稳定。
• 检查缓冲区：返回E_ZCL_ERR_ZBUFFER_FAIL通常意味着协议栈的APS层数据缓冲区不足。可以尝试增大APDU的缓冲区大小配置，或者优化应用层发送频率，避免短时间内密集发送大量命令。
• 查看底层错误：调用eZCL_GetLastZpsError()获取ZigBee PRO栈的详细错误码，例如ZPS_E_APS_NO_ACK表示未收到MAC层确认，可能是目标设备不在线或信号太差。

问题4：复位告警命令无效。

• 命令方向：ResetAlarm命令是从客户端发往服务器的。确保调用的是eCLD_AlarmsCommandResetAlarmCommandSend（客户端函数），而不是eCLD_AlarmsClearAlarm（服务器函数）。
• 载荷匹配：确保ResetAlarm命令载荷中的u8AlarmCode和u16ClusterId与要复位的告警完全匹配，包括大小写（十六进制）。
• 服务器端处理：服务器端是否在E_CLD_ALARMS_CMD_RESET_ALARM事件处理函数中，执行了从日志表中删除对应条目的操作？如果只是标记而不删除，下次GetAlarm可能还会查到。

5.3 性能优化与资源考量

在资源受限的嵌入式设备上，需要精细化管理Alarms集群带来的开销。

• 内存占用：告警日志表是主要的内存消耗者。每条记录包含集群ID（2字节）、告警代码（1字节）、时间戳（4字节），加上链表或数组的管理开销。需要根据设备RAM大小和历史记录需求合理设置最大条目数（如5-10条）。
• 网络流量：每条告警通知、清除、复位命令都会产生一个ZCL帧。在电池供电的传感器网络中，频繁告警会显著影响设备寿命。务必实施前述的“告警风暴抑制”策略。
• 处理延迟：在客户端，告警处理回调函数应尽快执行完毕，避免阻塞其他ZCL事件或网络任务。如果需要执行耗时操作（如驱动大型显示屏、访问SD卡日志），应仅在该回调中设置标志位，由专门的任务去执行实际工作。

6. 跨集群集成与真实场景案例

Alarms集群很少孤立工作，它需要与其他功能集群紧密配合。我们以一个“智能温湿度光照三合一传感器”为例，勾勒一个完整的实现方案。

设备角色：该传感器作为Alarms集群服务器，同时实现Temperature Measurement (0x0402)、Relative Humidity Measurement (0x0405)、Illuminance Measurement (0x0400) 三个功能集群。

告警定义：

• 高温告警：温度 > 35°C，触发Temperature集群告警，代码0x01。
• 低温告警：温度 < 5°C，触发Temperature集群告警，代码0x02。
• 高湿告警：湿度 > 80%，触发Humidity集群告警，代码0x01。
• 光照不足告警：照度 < 100 Lux，触发Illuminance集群告警，代码0x01。

应用逻辑伪代码：

void vSensorPeriodicCheck(void) { // 读取各传感器值 int16 i16Temp = i16ReadTemp(); uint16 u16Humidity = u16ReadHumidity(); uint32 u32Lux = u32ReadIlluminance(); // 检查并触发温度告警 if (i16Temp > 3500 && !bTempHighAlarmActive) { // 35.00°C eCLD_AlarmsSignalAlarm(..., 0x01, 0x0402); bTempHighAlarmActive = TRUE; } else if (i16Temp <= 3000 && bTempHighAlarmActive) { // 30.00°C 恢复 eCLD_AlarmsClearAlarm(..., 0x01, 0x0402); bTempHighAlarmActive = FALSE; } // ... 类似逻辑处理低温和湿度告警 // 光照告警（通常只需要单向触发，不需要清除，除非光照恢复） if (u32Lux < 100 && !bLowLightAlarmActive) { eCLD_AlarmsSignalAlarm(..., 0x01, 0x0400); bLowLightAlarmActive = TRUE; } // 注意：光照恢复可能不需要发送Clear，除非业务逻辑要求 }

网关（客户端）处理： 网关在收到告警后，可以根据u16ClusterId和u8AlarmCode，在UI上显示不同的图标和文字（“客厅温度过高”、“卧室湿度过大”），并可以触发联动规则，例如打开空调除湿、开启补光灯，或者向用户的手机APP推送一条紧急通知。

通过这个案例可以看到，Alarms集群提供了一个干净、解耦的接口。传感器端只负责“报告状态”，网关端负责“解释状态并行动”。这种架构使得功能集群（负责测量）与告警管理集群（负责通知）职责分离，符合良好的软件设计原则，也极大地提升了不同厂商设备间的互操作性。