快速入门

本指南帮助您快速接入 VDM 位移数据，适用于系统集成开发者。

flowchart LR
    A[1. App 配置<br>MQTT 连接] --> B[2. 订阅<br>设备主题]
    B --> C[3. 设备上线<br>上报属性]
    C --> D[4. 接收<br>位移数据]
    D --> E[5. 接收告警<br>可选]

1. 配置设备连接

通过 App 配置设备连接到您的 MQTT 服务器：

• MQTT 服务器：您的服务器地址
• 端口：您的服务器端口
• 认证：您的服务器凭证（如需要）

配置完成后，从设备标签或 App 获取：

• 设备 ID：XXXXXXXXXXXX

2. 订阅数据主题

vdm/{deviceId}/rpc/resp      # RPC 响应
vdm/{deviceId}/telemetry     # 遥测数据：累积位移变化、温湿度等环境数据、电压等设备状态数据
vdm/{deviceId}/attributes    # 属性上报
vdm/{deviceId}/event         # 事件通知
vdm/{deviceId}/3A            # 预警、告警和行动等3A（Alert, Alarm和Action）通知
vdm/{deviceId}/image         # 图片

示例（设备 ID 为 XXXXXXXXXXXX）：

vdm/XXXXXXXXXXXX/telemetry
vdm/XXXXXXXXXXXX/3A

3. 设备上线

设备连接 MQTT 后，自动上报只读属性到 attributes 主题：

{
  "deviceId": "XXXXXXXXXXXX",
  "deviceModel": "V1",
  "fwVer": "1.2.3",
  "measureStatus": "Idle"
}

收到属性上报表示设备已上线，可据此判断设备连接状态。

4. 接收位移数据

设备测量运行时，自动推送位移数据：

{
  "disp": {
    "t": 1734567890,
    "d": {
      "1": {
        "type": "local",
        "dx": [0.01, 0.02, 0.03],
        "dy": [0.00, 0.01, 0.01]
      }
    }
  }
}

代码示例

• Python
• Node.js

import paho.mqtt.client as mqtt
import json

DEVICE_ID = "XXXXXXXXXXXX"
BROKER = "mqtt.example.com"

def on_message(client, userdata, msg):
    data = json.loads(msg.payload)
    if "disp" in data:
        t = data["disp"]["t"]
        # 遍历所有标靶（动态数量，只包含有数据的标靶）
        for target_id, values in data["disp"]["d"].items():
            dx = values.get("dx", [])
            dy = values.get("dy", [])
            print(f"[{t}] 标靶{target_id}: dx={dx}, dy={dy}")

client = mqtt.Client()
client.on_message = on_message
client.connect(BROKER, 1883)
client.subscribe(f"vdm/{DEVICE_ID}/telemetry")
client.loop_forever()

const mqtt = require('mqtt');

const DEVICE_ID = 'XXXXXXXXXXXX';
const client = mqtt.connect('mqtt://mqtt.example.com');

client.on('connect', () => {
  client.subscribe(`vdm/${DEVICE_ID}/telemetry`);
});

client.on('message', (topic, message) => {
  const data = JSON.parse(message.toString());
  if (data.disp) {
    const { t, d } = data.disp;
    // 遍历所有标靶（动态数量，只包含有数据的标靶）
    for (const [targetId, values] of Object.entries(d)) {
      console.log(`[${t}] 标靶${targetId}:`, values);
    }
  }
});

5. 告警类型

设备监测的标靶如果有累积位移变化超出了预先设置的3A（Alert, Alarm和Action）阈值，设备会自动报警。

6. 常见问题

Q: 没有收到数据？

• 确认设备已开机并联网
• 确认设备已启动测量（通过 App 查看状态）
• 检查 MQTT 连接和主题是否正确

Q: 数据频率是多少？

• 取决于设备配置的采样频率（sampleFreq）
• ≥1Hz 时每秒上报一次，<1Hz 时按周期上报

Q: 如何启动/停止测量？

• 使用厂家提供的 App 操作
• 或参考完整 API 手册进行 RPC 调用

更多信息

详细 API 请参考各型号手册：

• V1 | V2W | V2K | O1 | X1 | X2W