设备数据采集与上报协议完整文档

版本：v1.0  更新日期：2025-11-19

1. service.conf 采集项下发（平台 → 设备）

[
    {
        "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）

{
    "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 离线报警示例

{
    "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 恢复在线示例

{
    "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 首次执行采集任务之后上报状态

{
    "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	设备离线、恢复在线、报警等事件