设备事件

在 ThingsCloud 平台中，设备事件是设备向云平台发送的通知或请求消息，适用于上报设备运行中的一次性状态变化。与属性持续记录设备状态不同，事件通常用于报告某个特定时刻发生的状况，如故障告警、自检完成、系统异常等。

本节将详细介绍设备事件的概念、消息格式、上报方法，以及在控制台中的查看方式，帮助您全面理解并在实际项目中使用设备事件功能。

什么是设备事件？

设备事件是设备向云端报告的一种消息类型，用于通知平台发生了某些需要关注的事情。与属性持续记录设备状态不同，事件是一次性的、瞬时的消息上报，适用于以下场景：

• 故障告警：设备检测到异常情况时，及时上报故障信息。例如传感器检测到温度过高、电压异常、设备启动失败等。
• 状态通知：设备运行中发生的特定状态变化。例如设备自检完成、系统启动完成、网络连接恢复等。
• 任务进度：长时间运行任务的阶段性报告。例如 OTA 升级进度、批量数据处理完成等。
• 交互事件：用户与设备交互产生的消息。例如按钮按下、刷卡成功、人体感应触发等。

举几个实际的例子来说明：

• 智能门锁在密码验证失败时，上报 "闯入尝试" 事件，包含尝试次数、时间等信息。
• 工业设备检测到轴承温度超过阈值时，上报 "高温预警" 事件，包含当前温度、超出值等信息。
• 环境监测站检测到空气质量严重超标时，上报 "空气污染告警" 事件，包含 PM2.5、PM10、CO2 等检测值。
• 智能水表检测到管道漏水时，上报 "漏水检测" 事件，包含漏水位置、流量异常值等信息。

与属性相比，事件有以下显著特点：

事件消息结构

设备事件消息采用 JSON 格式，包含以下核心字段：

{
    "method": "{event_identifier}",
    "params": {
        "key1": "{value1}",
        "key2": "{value2}",
        ...
    }
}

字段说明

事件标识符

事件标识符是事件的唯一标识符，类似于函数名，用于区分不同类型的事件。在事件消息中，method 字段的值即为事件标识符。

事件标识符中只能包含：英文大小写字母、数字、下划线、横线。例如：alarm、fault、status、taskComplete 等。

事件参数

事件参数是可选的，用于携带事件相关的具体信息。参数是一个键值对集合，可以包含任意类型的数据。

典型事件消息示例

为了帮助您更好地理解事件的应用场景，以下列举了几种常见的事件消息示例，涵盖了从告警、故障到业务通知的多种场景。

示例 1：故障事件（传感器故障）

当设备内部组件发生故障时上报，通常携带错误码，便于运维人员快速定位问题。

场景：环境监测站的 PM2.5 传感器发生通讯故障。

{
    "method": "sensor_fault",
    "params": {
        "component": "pm25_sensor",
        "error_code": 1004,
        "error_msg": "Communication timeout",
        "retry_count": 3
    }
}

示例 2：业务通知（智能门锁开门）

记录设备运行过程中的关键业务动作，这类数据通常需要永久存储用于审计或查询。

场景：智能门锁通过指纹成功开锁。

{
    "method": "unlock_record",
    "params": {
        "user_id": 108,
        "user_name": "张三",
        "mode": "fingerprint",
        "battery_level": 85
    }
}

示例 3：AI 识别事件（车牌识别）

对于具备边缘计算能力的设备，可以将识别结果作为事件上报，通常包含识别出的对象信息和置信度。

场景：停车道闸摄像头识别到车辆驶入。

{
    "method": "plate_identified",
    "params": {
        "plate_num": "京A88888",
        "color": "blue",
        "confidence": 0.98,
        "image_url": "http://oss.example.com/capture/20231027/123.jpg"
    }
}

示例 4：生命周期事件（设备启动）

设备每次上电或重启后上报，用于平台掌握设备重启频率和当前运行环境。

场景：设备重启完成，上报当前固件版本和网络状态。

{
    "method": "device_startup",
    "params": {
        "firmware_version": "v2.1.0",
        "boot_reason": "power_on",
        "ip_address": "192.168.1.100",
        "rssi": -65
    }
}

设备如何上报事件

ThingsCloud 支持通过 MQTT 和 HTTP 两种协议上报设备事件。

MQTT 协议上报

设备通过 MQTT 协议即可上报事件，平台会返回对应的响应消息。

HTTP 协议上报

设备也可以通过 HTTP POST 请求上报事件。

在控制台查看设备事件

事件列表页面

在控制台中，进入任意设备的详情页，点击「事件」标签页，即可查看该设备的所有事件记录。

事件列表显示了以下信息：

事件详情

点击任意一条事件记录，可以查看事件的详细信息，包括完整的参数内容、接收时间等。

事件统计

在设备详情页的概览中，可以查看设备事件消息的相关统计数据，如下图：

在看板中查看设备事件（即将推出）

ThingsCloud 即将支持在可视化看板组件中直接展示设备事件列表。这意味着您可以将设备的运行记录、告警历史等关键信息通过看板直接呈现给管理人员，无需自行开发前端界面。

在用户应用中查看（即将推出）

ThingsCloud 即将支持在用户应用 ThingsX 中内置设备事件查看功能。这意味着您可以将设备的运行记录、告警历史等关键信息直接呈现给最终用户，方便用户随时随地了解设备状况。

事件相关消息规则

ThingsCloud 提供了事件上报规则，用于对设备上报的事件进行自定义处理和流转。当云平台接收到设备上报的事件消息后，会触发相应的事件上报规则。

事件上报规则支持以下操作：

应用端如何接收事件

应用端可以通过以下方式接收设备事件：

• MQTT 应用端订阅：通过 MQTT 协议订阅设备事件，实现实时接收和处理。
• HTTP API 查询：通过 HTTP API 查询设备的历史事件记录。
• 消息规则流转：通过消息规则的推送操作，将事件转发到指定目标。

相关文档

• MQTT 设备接入
• 功能定义
• 事件上报规则
• 设备消息
• 告警规则
• MQTT 应用端订阅
• ThingsCloud API