180 lines
7.0 KiB
Markdown
180 lines
7.0 KiB
Markdown
# 设备数据采集与上报协议完整文档
|
||
|
||
> 版本：v1.0 更新日期：2025-11-19
|
||
### 1. service.conf 采集项下发（平台 → 设备）
|
||
```json
|
||
[
|
||
{
|
||
"host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
|
||
"device_uuid": "deviceuuid1",
|
||
"task_id": "6588",
|
||
"address": "房间东侧",
|
||
"type": "2",
|
||
"facility": "01"
|
||
},
|
||
{
|
||
"host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
|
||
"device_uuid": "deviceuuid2",
|
||
"task_id": "6589",
|
||
"address": "房间南侧",
|
||
"type": "1",
|
||
"facility": "02"
|
||
},
|
||
{
|
||
"host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
|
||
"device_uuid": "deviceuuid3",
|
||
"task_id": "6590",
|
||
"address": "房间西侧",
|
||
"type": "smog",
|
||
"facility": "03"
|
||
}
|
||
]
|
||
```
|
||
字段名 | 类型 | 必填 | 说明 | 示例值
|
||
-------------|--------|------|------------------------------------|--------------------------------------
|
||
host_uuid | string | 是 | 网关/采集主机唯一ID | qbxmjyzrkpntfgswaevodhluicqzxplkm
|
||
device_uuid | string | 是 | 传感器设备唯一ID | deviceuuid1
|
||
task_id | string | 是 | 平台任务ID，用于追踪和撤销 | 6588
|
||
address | string | 是 | 安装位置描述 | 房间东侧
|
||
type | string | 是 | 传感器类型 | "1"→温湿度，"2"→水浸传感器，"3"→烟雾
|
||
facility | string | 是 | 设施点位编码（固定2位） | 01、02、03
|
||
### 2. 上报数据（metric_data）
|
||
```json
|
||
{
|
||
"method": "metric_data",
|
||
"params": {
|
||
"route_key": "/dthjjc/device/3eeba8usb86c0gs448oktxay41a0rm1v/data",
|
||
"metric": {
|
||
"type": "data",
|
||
"args": [
|
||
{
|
||
"deviceuuid": "deviceuuid1",
|
||
"type": "1",
|
||
"facility": "2",
|
||
"address": "房间东侧",
|
||
"value": { "temp": "25.3", "humidity": "12.5" }
|
||
},
|
||
{
|
||
"deviceuuid": "deviceuuid2",
|
||
"type": "2",
|
||
"facility": "1",
|
||
"address": "房间南侧",
|
||
"value": "0"
|
||
},
|
||
{
|
||
"deviceuuid": "deviceuuid3",
|
||
"type": "3",
|
||
"facility": "3",
|
||
"address": "房间西侧",
|
||
"value": "0"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
层级 | 字段名 | 类型 | 必填 | 说明
|
||
------------------------|---------------|-----------------|------|-----------------------------------------
|
||
根对象 | method | string | 是 | 固定值 "metric_data"
|
||
params | route_key | string | 是 | 格式：/dthjjc/device/{host_uuid}/data
|
||
params.metric | type | string | 是 | 固定值 "data"
|
||
params.metric.args | - | array | 是 | 每项对应一个设备
|
||
args[i] | deviceuuid | string | 是 | 设备唯一ID
|
||
args[i] | type | string | 是 | 传感器类型
|
||
args[i] | facility | string | 是 | 设施编码（两位）
|
||
args[i] | address | string | 是 | 安装位置
|
||
args[i] | value | string/array | 是 | 实际值，格式见下表
|
||
|
||
value 格式对照表
|
||
type | 传感器类型 | value 类型 | 示例值 | 说明
|
||
-------|----------------|----------------|-------------------------------------------|----------------------
|
||
1 | 温湿度传感器 | array[object] | [{"temp":"25.3","humidity":"12.5"}] | 必须包含temp和humidity
|
||
2 | 水浸传感器 | string | "0" 或 "1" | 0=正常 1=报警
|
||
3/smog | 烟雾传感器 | string | "0" 或 "1" | 0=正常 1=报警
|
||
|
||
### 3. 上报事件（event_data）
|
||
|
||
# 3.1 离线报警示例
|
||
```json
|
||
{
|
||
"method": "event_data",
|
||
"params": {
|
||
"route_key": "/dthjjc/device/deviceuuid3/event",
|
||
"metric": {
|
||
"type": "event",
|
||
"args": {
|
||
"description": "The sensor is offline",
|
||
"timestamp": "1763544662",
|
||
"host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
|
||
"device_uuid": "device3",
|
||
"level": "alarm",
|
||
"last_successful_time": "1763544625",
|
||
"sensor_type": "SmokeTransducer(3)",
|
||
"recommendation": "Check device connection and communication line"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
# 3.2 恢复在线示例
|
||
```json
|
||
{
|
||
"method": "event_data",
|
||
"params": {
|
||
"route_key": "/dthjjc/device/deviceuuid3/event",
|
||
"metric": {
|
||
"type": "event",
|
||
"args": {
|
||
"description": "Sensor online",
|
||
"timestamp": "1763544662",
|
||
"host_uuid": "qbxmjyzrkpntfgswaevodhluicqzxplkm",
|
||
"device_uuid": "device3",
|
||
"level": "online",
|
||
"sensor_type": "SmokeTransducer(3)"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
|
||
```
|
||
# 3.3 首次执行采集任务之后上报状态
|
||
```json
|
||
{
|
||
"method": "metric_data",
|
||
"params": {
|
||
"metric": {
|
||
"args": {
|
||
"description": "Environmental detection system started successfully",
|
||
"timestamp": "1763644447",
|
||
"host_uuid": "pemsyszrkpntfgswaevodhluicqzxplkm",
|
||
"level": "system_start",
|
||
"device_count": 3,
|
||
"online_count": 3
|
||
},
|
||
"type": "event"
|
||
},
|
||
"route_key": "/dthjjc/device/pemsyszrkpntfgswaevodhluicqzxplkm/event"
|
||
}
|
||
}
|
||
```
|
||
|
||
event_data 通用字段说明
|
||
字段名 | 类型 | 必填 | 说明
|
||
----------------------|--------|------|-------------------------------------------
|
||
description | string | 是 | 事件描述
|
||
timestamp | string | 是 | UNIX 时间戳（秒）
|
||
host_uuid | string | 是 | 主机UUID
|
||
device_uuid | string | 是 | 设备UUID
|
||
level | string | 是 | alarm / online 等
|
||
last_successful_time | string | 否 | 仅离线时填写
|
||
sensor_type | string | 否 | 传感器类型描述
|
||
recommendation | string | 否 | 处理建议
|
||
device_count | string | 否 | 检测设备数量
|
||
online_count | string | 否 | 当前在线数量
|
||
|
||
### 4. 协议总览
|
||
|
||
上报类型 | method | route_key 后缀 | 说明
|
||
-------------|----------------|----------------|------------------------------------
|
||
普通数据上报 | metric_data | /data | 定时上报温湿度、水浸传感器、烟雾等数值
|
||
事件上报 | event_data | /event | 设备离线、恢复在线、报警等事件 |