这是本节的多页打印视图。 点击此处打印.

返回本页常规视图.

MQTT 数据订阅

实时数据推送

Inteagle 结构健康监测平台提供 MQTT 实时数据推送服务。

连接信息

参数值
服务器broker.shm.inteagle.com
端口8883 (TLS)
协议MQTT 3.1.1 / 5.0

认证

参数值
用户名客户 ID
密码Access Token
Client ID自定义（建议：{customerId}_{appName}）

Topic 结构

inteagle/{customerId}/p/{projectId}              # 项目所有数据
inteagle/{customerId}/p/{projectId}/mp/{pointId} # 监测点数据
inteagle/{customerId}/p/{projectId}/d/{deviceId} # 设备数据

订阅示例：

# 项目所有数据
inteagle/cust_abc123/p/proj_abc/#

# 所有监测点
inteagle/cust_abc123/p/proj_abc/mp/+

# 单个设备
inteagle/cust_abc123/p/proj_abc/d/dev_001

消息格式

所有消息包含 type 字段区分数据类型：

遥测数据

{
  "type": "telemetry",
  "ts": 1735560000000,
  "payload": {
    "pointId": "point_001",
    "data": {"dx": 0.05, "dy": 0.02}
  }
}

告警

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_001",
    "severity": "alert",
    "status": "ACTIVE_UNACK",
    "originator": {"entityType": "POINT", "id": "point_001"},
    "detail": {"metric": "dx", "value": 12.5, "threshold": 10.0}
  }
}

代码示例

import paho.mqtt.client as mqtt
import json

def on_connect(client, userdata, flags, rc):
    print(f"Connected: {rc}")
    client.subscribe("inteagle/cust_abc123/p/proj_abc/#")

def on_message(client, userdata, msg):
    data = json.loads(msg.payload.decode())
    if data['type'] == 'telemetry':
        print(f"遥测: {data['payload']}")
    elif data['type'] == '3A':
        print(f"告警: {data['payload']['severity']}")

client = mqtt.Client()
client.username_pw_set("cust_abc123", "your_token")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.shm.inteagle.com", 8883)
client.loop_forever()

QoS 建议

数据类型QoS说明
遥测0允许少量丢失
告警1确保送达

1 - 项目与监测点数据

项目聚合数据与监测点数据格式

项目和监测点数据是面向业务的数据视图。

Topic 结构

inteagle/{customerId}/p/{projectId}              # 项目所有数据
inteagle/{customerId}/p/{projectId}/mp/{pointId} # 监测点数据
参数说明示例
{customerId}客户 IDcust_abc123
{projectId}监测项目 IDproj_abc
{pointId}监测点 IDpoint_001

订阅示例

# 某项目所有数据
inteagle/cust_abc123/p/proj_abc/#

# 某监测点所有数据
inteagle/cust_abc123/p/proj_abc/mp/point_001

# 项目下所有监测点数据
inteagle/cust_abc123/p/proj_abc/mp/+

监测点数据

Topic: inteagle/{customerId}/p/{projectId}/mp/{pointId}

遥测数据

{
  "type": "telemetry",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "POINT",
      "id": "point_001"
    },
    "disp": {
      "dx": 0.05,
      "dy": 0.02,
      "dz": 0.01
    },
    "tilt": 0.5
  }
}

payload 字段说明

字段类型说明
entityEntityRef实体引用（类型 + ID）
disp, tilt, …Object/Number指标数据（按需配置）

注意：监测点名称、项目名称等元数据通过 HTTP API 获取。

常见指标

指标说明单位
dxX 方向累积位移变化mm
dyY 方向累积位移变化mm
dzZ 方向累积位移变化mm
tilt倾斜角″（角秒）
strain应变με

注意：监测点指标是按需配置的，不同监测点可能包含不同的指标组合。有些数据需要从 设备实体 订阅（如视觉位移计的图片）。

告警数据

告警格式参见 告警消息。

监测点告警示例：

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_20251230_001",
    "alarmType": "DISPLACEMENT_EXCEEDED",
    "severity": "alert",
    "status": "ACTIVE_UNACK",
    "originator": {
      "type": "POINT",
      "id": "point_001"
    },
    "detail": {
      "metric": "dx",
      "value": 12.5,
      "threshold": 10.0,
      "message": "X方向位移超限"
    }
  }
}

设备数据

如需订阅设备原始数据（环境、图像等），请参见 设备数据格式。

2 - 设备数据格式

不同设备类型的数据格式

设备数据通过 Topic inteagle/{customerId}/p/{projectId}/d/{deviceId} 推送。

通用消息结构

所有 MQTT 消息采用统一的包装结构：

{
  "type": "telemetry | 3A | event | image | attributes",
  "ts": 1735560000000,
  "payload": {
    ...
  }
}
字段类型说明
typeString消息类型
tsLongUnix 毫秒时间戳
payloadObject具体数据内容

开发者可以统一解析：

const { type, ts, payload } = message;
switch(type) {
  case 'telemetry': handleTelemetry(payload); break;
  case '3A':        handleAlarm(payload); break;
  case 'event':     handleEvent(payload); break;
  case 'image':     handleImage(payload); break;
  case 'attributes': handleAttributes(payload); break;
}

消息类型

type说明payload 内容
telemetry遥测数据位移、环境、状态
3A告警告警详情
event事件事件类型和数据
image图像图片 URL 和元数据
attributes属性变更变更的属性

告警消息 (3A)

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_20251230_001",
    "alarmType": "LOW_BATTERY",
    "severity": "alarm",
    "status": "ACTIVE_UNACK",
    "originator": {
      "entityType": "DEVICE",
      "id": "dev_001"
    },
    "detail": {
      "metric": "pwr.battery",
      "value": 3.2,
      "threshold": 3.5,
      "message": "电池电压低"
    }
  }
}

payload 字段说明

字段类型必填说明
idString是告警唯一标识
alarmTypeString是告警类型（见数据字典）
severityString是告警级别
statusString是告警状态
originator.entityTypeString是实体类型：DEVICE、POINT
originator.idString是实体 ID
detail.metricString是触发告警的指标
detail.valueNumber否触发时的实际值
detail.thresholdNumber否阈值
detail.messageString是告警描述

告警级别 (severity)

值说明
ALERT预警
ALARM报警
ACTION紧急

告警状态 (status)

值说明
ACTIVE_UNACK触发未确认
ACTIVE_ACK触发已确认
CLEARED_UNACK恢复未确认
CLEARED_ACK恢复已确认

事件消息 (event)

事件分为通用事件（所有设备）和设备事件（取决于设备能力）。

{
  "type": "event",
  "ts": 1735560000000,
  "payload": {
    "deviceId": "dev_001",
    "eventType": "DEVICE_ONLINE",
    "data": {}
  }
}

payload 字段说明

字段类型说明
deviceIdString设备 ID
eventTypeString事件类型
dataObject事件相关数据

通用事件类型

eventType说明
DEVICE_ONLINE设备上线
DEVICE_OFFLINE设备离线

设备特有事件参见各设备文档。

属性变更消息 (attributes)

{
  "type": "attributes",
  "ts": 1735560000000,
  "payload": {
    "deviceId": "dev_001",
    "data": {
      "firmwareVersion": "2.1.0"
    }
  }
}

2.1 - VDM 视觉位移计

VDM 视觉位移计设备数据格式

VDM（Visual Displacement Meter）视觉位移计是 Inteagle 核心监测设备，支持多标靶位移测量。

遥测数据

视觉位移计设备遥测数据包含位移、环境、状态信息：

{
  "type": "telemetry",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "disp": {
      "1": {
        "dx": 0.05,
        "dy": 0.02,
        "dz": 0.01,
        "tilt": 0.05
      },
      "2": {
        "dx": 0.03,
        "dy": 0.01
      }
    },
    "env": {
      "temperature": 25.5,
      "humidity": 60.0,
      "pressure": 101.3
    },
    "status": {
      "signal": {
        "type": "4G",
        "rssi": -75
      },
      "pwr": {
        "battery": 3.7,
        "inputDC": 12.1
      },
      "storage": {
        "percent": 45
      }
    }
  }
}

位移数据 (disp)

字段类型说明
dispObject按标靶 ID 组织的位移数据
dx, dy, dzNumber累积位移变化 (mm)
tiltNumber倾斜变化角度（″ 角秒）

环境数据 (env)

部分 VDM 型号支持环境数据采集：

字段类型单位说明
temperatureNumber°C温度
humidityNumber%RH相对湿度
pressureNumberkPa大气压

状态数据 (status)

字段类型说明
signal.typeString网络类型：4G, Ethernet
signal.rssiInteger信号强度 (dBm)
pwr.batteryNumber电池电压 (V)
pwr.inputDCNumberDC 输入电压 (V)
storage.percentInteger存储使用率 (%)

告警

设备告警格式参见 告警消息。

视觉位移计设备告警示例

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_20251230_001",
    "alarmType": "TARGET_LOST",
    "severity": "alarm",
    "status": "ACTIVE_UNACK",
    "originator": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "detail": {
      "metric": "target_1_status",
      "message": "标靶1丢失"
    }
  }
}

VDM 常见告警类型

alarmType说明metric
TARGET_LOST标靶丢失target_{n}_status
LOW_BATTERY电池电压低pwr.battery
LOW_VOLTAGEDC输入电压低pwr.inputDC
STORAGE_FULL存储空间不足storage.percent

事件

事件分为通用事件（所有设备）和设备事件（取决于设备能力）。

通用事件

平台为所有设备提供在线/离线状态推送：

{
  "type": "event",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "eventType": "DEVICE_ONLINE",
    "data": {}
  }
}
eventType说明
DEVICE_ONLINE设备上线
DEVICE_OFFLINE设备离线

视觉位移计设备事件

VDM 特有的事件类型：

{
  "type": "event",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "eventType": "TARGET_LOST",
    "data": {
      "targetId": "1"
    }
  }
}
eventType说明data
TARGET_LOST标靶丢失{"targetId": "1"}
TARGET_RECOVERED标靶恢复{"targetId": "1"}
CALIBRATION_COMPLETE标定完成{"targetId": "1"}
STORAGE_FULL存储空间已满{}

图像

VDM 支持图像采集：

{
  "type": "image",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "sensorId": 0,
    "trigger": "snapshot",
    "url": "https://storage.inteagle.com/images/...",
    "ttl": 86400
  }
}
字段类型说明
entityEntityRef实体引用
sensorIdInteger视觉传感器 ID（0 或 1）
triggerString触发类型
urlString图片下载 URL
ttlIntegerURL 有效期（秒）

触发类型

trigger说明
snapshot手动快照
3A告警触发
periodic定时拍照

属性变更

{
  "type": "attributes",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "measureFrequency": 10,
    "irLightEnabled": true
  }
}

VDM 常见属性

属性类型说明
measureFrequencyInteger测量频率 (Hz)
irLightEnabledBoolean红外补光灯开关
targetCountInteger标靶数量
firmwareVersionString固件版本