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

返回本页常规视图.

视觉位移计(VDM)

非接触式位移监测设备

视觉位移计是 Inteagle 研发的非接触式位移监测设备，可以实时监测目标结构物的位移变化。

说明：有两种方式：MQTT和modbus. modbus接入方式正在开发中。

快速导航

文档说明
快速入门5 分钟接入 VDM 设备数据
API参考API 列表、错误码、数据格式

产品型号

型号视觉传感器云台类型说明
V1单目无固定式，基础款
V2W双目无固定式，视野加倍
V2K双目无固定式，安装时可自由选择视野角度
O1单目单轴旋转式，仅水平方向可旋转
X1单目双轴旋转式，水平和竖向方向均可旋转
X2W双目双轴旋转式，水平和竖向方向均可旋转，视野加倍

说明：

  1. 旋转式型号具有巡航监测功能
  2. 双目型号有 sensorId 参数

基础知识

  • 单台设备仅可测量二维位移变化，三维位移需要两台设备数据融合计算
  • 单台设备的测量数据坐标系以设备图像为中心（local 坐标系）
  • 两台设备数据融合后可得出全局三维数据（global 坐标系）

1 - 快速入门

VDM 设备快速接入指南

本指南帮助您快速接入 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]
      }
    }
  }
}
字段说明
tUnix 时间戳（秒）
1标靶 ID
dxX 方向累积位移变化（mm）
dyY 方向累积位移变化（mm）

代码示例

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）阈值，设备会自动报警。

类型说明
DISPLACEMENT_EXCEEDED累积位移变化超限告警
TARGET_LOST标靶丢失告警
DEVICE_OFFLINE设备离线告警
LOW_BATTERY低电量告警
STORAGE_NEAR_FULL存储即将满

6. 常见问题

Q: 没有收到数据？

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

Q: 数据频率是多少？

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

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

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

更多信息

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

2 - API参考

VDM 设备接口技术规格

本章节介绍 VDM 设备的完整API参考，包括通信协议、API 列表、错误码等技术细节。

连接参数

参数值
协议MQTT v3.1.1
PayloadJSON

主题结构

主题方向说明
vdm/{deviceId}/rpc/req下行RPC 指令
vdm/{deviceId}/rpc/resp上行RPC 响应
vdm/{deviceId}/telemetry上行遥测数据
vdm/{deviceId}/attributes上行属性上报
vdm/{deviceId}/event上行事件上报
vdm/{deviceId}/3A上行告警上报
vdm/{deviceId}/image上行图片数据

API 支持矩阵

APIV1V2WV2KO1X1X2W
基础 API
getAttr✓✓✓✓✓✓
setAttr✓✓✓✓✓✓
reboot✓✓✓✓✓✓
syncTime✓✓✓✓✓✓
标靶管理
initRefTargets✓✓✓✓✓✓
addTargets✓✓✓✓✓✓
getTargets✓✓✓✓✓✓
setTargets✓✓✓✓✓✓
deleteTargets✓✓✓✓✓✓
测量控制
startMeasurement✓✓✓✓✓✓
stopMeasurement✓✓✓✓✓✓
setLightLevel✓✓✓✓✓✓
getLightLevel✓✓✓✓✓✓
snapshot✓✓✓✓✓✓
存储
getStorageInfo✓✓✓✓✓✓
queryTelemetry✓✓✓✓✓✓
uploadS3✓✓✓✓✓✓
电机控制
setMotorAngle---✓✓✓
getMotorAngle---✓✓✓
setMotorZero---✓✓✓
enableMotor---✓✓✓
disableMotor---✓✓✓
巡航控制
getCruisePaths---✓✓✓
setCruisePoint---✓✓✓
removeCruisePoint---✓✓✓
startPatrol---✓✓✓
stopPatrol---✓✓✓
getPatrolStatus---✓✓✓

错误码

码说明适用型号
0成功全部
1参数无效全部
2缺少必填参数全部
100标靶不存在全部
102标靶初始化失败全部
104标靶丢失全部
200测量未启动全部
201测量已在运行全部
300电机不可用O1, X1, X2W
302电机运动中O1, X1, X2W
303电机到达限位X1, X2W
310垂直电机不可用O1
400巡航功能不可用O1, X1, X2W
403巡航已在运行O1, X1, X2W

图片数据

设备通过 image 主题上报图片。

主题： vdm/{deviceId}/image

Payload 结构：

[Header (8+ 字节)] + [JPEG 二进制数据]

Header 格式

偏移长度字段说明
01version协议版本，当前 0x01
11headerLenHeader 总长度（字节）
21sensorId视觉传感器 ID（单目为 0，双目为 0 或 1）
31type图片类型（见下表）
44timestampUnix 时间戳（uint32, 大端）
8+-imageDataJPEG 二进制数据

图片类型 (type)：

值类型说明
0snapshotRPC 触发的快照
13A告警触发的抓图
2periodic定时抓图

示例

01 08 00 01 67 72 B3 D6 FF D8 FF E0 ...
│  │  │  │  └──────────┴─ timestamp: 1735533526
│  │  │  └─ type: 1 (3A)
│  │  └─ sensorId: 0
│  └─ headerLen: 8
└─ version: 1

图片规格

项目规格
格式JPEG
最大分辨率1280×720 (720p)
典型大小50KB - 200KB

扩展说明

未来版本可在 timestamp 后追加字段，并相应增加 headerLen。解析时根据 headerLen 跳过不识别的字段，保证向后兼容。

3 - VDM-V1

V1 单目固定式视觉位移计 API 参考手册

型号: V1 | 版本: 1.0 | 更新: 2026-01-08

V1 是单目固定式视觉位移计。

1. API 列表

基础 API

方法说明
getAttr获取属性
setAttr设置属性
reboot重启设备
syncTime同步时间

标靶管理 API

方法说明
initRefTargets初始化标靶
addTargets添加标靶
getTargets获取标靶列表
setTargets更新标靶配置
deleteTargets删除标靶

测量控制 API

方法说明
startMeasurement启动测量
stopMeasurement停止测量
setLightLevel设置补光灯发光挡位
getLightLevel获取补光灯发光挡位
snapshot获取快照

存储 API

方法说明
getStorageInfo获取存储信息
queryTelemetry查询历史数据
uploadS3上传数据到 S3

2. API 详情

getAttr

获取设备属性。不带 keys 参数时返回全部属性。

请求：

{"reqId": 1, "method": "getAttr", "params": {}}

或指定属性：

{"reqId": 1, "method": "getAttr", "params": {"keys": ["status", "sampleFreq"]}}

响应：

{
  "reqId": 1,
  "code": 0,
  "data": {
    "deviceId": "XXXXXXXXXXXX",
    "deviceModel": "V1",
    "fwVer": "1.2.3",
    "resolution": "3840x2160",
    "measureStatus": "Idle",
    "sampleFreq": 10,
    "exposure": "Middle",
    "brightnessThr": 225,
    "reportMetrics": ["dx", "dy"]
  }
}

属性列表：

属性类型读写说明
deviceIdStringR设备 ID
deviceModelStringR型号
fwVerStringR固件版本
measureStatusStringR测量状态
sampleFreqFloatRW采样频率 (Hz)
exposureStringRW曝光档位：High/Middle/Low
brightnessThrIntegerRW发光强度阈值 (0-255)
reportMetricsArrayRW上报指标

setAttr

设置设备属性。

请求：

{"reqId": 1, "method": "setAttr", "params": {
  "sampleFreq": 5,
  "reportMetrics": ["dx", "dy"]
}}

响应：

{"reqId": 1, "code": 0}

initRefTargets

初始化参考标靶。会清除已有标靶。

参数：

字段类型必填说明
targetsArray是标靶配置
targets[].targetIdString否标靶 ID（不填则自动生成）
targets[].roiObject是ROI 区域
targets[].distanceFloat是测量距离 (m)

请求：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [{
    "targetId": "1",
    "roi": {"x": 1000, "y": 500, "width": 400, "height": 400},
    "distance": 5.0
  }]
}}

响应：

{"reqId": 1, "code": 0, "data": {"targetIds": ["1"]}}

addTargets

在已有标靶基础上添加新标靶。

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "2", "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["2"]}}

getTargets

获取当前标靶列表。

请求：

{"reqId": 1, "method": "getTargets", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"},
    {"targetId": "2", "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0, "status": "tracking"}
  ]
}}

标靶状态：

状态说明
tracking正常跟踪
lost标靶丢失
idle未启动测量

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [
    {"targetId": "1", "distance": 5.5}
  ]
}}

响应：

{"reqId": 1, "code": 0}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

响应：

{"reqId": 1, "code": 0}

startMeasurement

启动测量。

请求：

{"reqId": 1, "method": "startMeasurement", "params": {}}

响应：

{"reqId": 1, "code": 0}

stopMeasurement

停止测量。

请求：

{"reqId": 1, "method": "stopMeasurement", "params": {}}

响应：

{"reqId": 1, "code": 0}

setLightLevel

设置补光灯发光挡位。

请求：

{"reqId": 1, "method": "setLightLevel", "params": {"level": 1}}

响应：

{"reqId": 1, "code": 0}

getLightLevel

获取补光灯发光挡位。

请求：

{"reqId": 1, "method": "getLightLevel", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {"level": 1}}

3. 遥测数据

测量运行时，设备按采样频率上报位移数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"type": "local","dx":[0.01,0.02,0.03],"dy":[0.00,0.01,0.01]}}}}
字段单位说明
t秒Unix 时间戳
d-标靶数据字典
type-数据的坐标系是全局还是局部。
dxmmX 方向位移变化
dymmY 方向位移变化

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别名称说明
0-恢复
1alert预警
2alarm报警
3action行动

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "measurementStarted",
  "ts": 1734567890,
  "data": {}
}

事件类型：

事件说明data 内容
measurementStarted测量开始{}
measurementStopped测量停止{}
TARGET_LOST标靶丢失{"targetId": "1"}
targetRecovered标靶恢复{"targetId": "1"}

6. 错误码

码说明
0成功
1参数无效
2缺少必填参数
100标靶不存在
102标靶初始化失败
104标靶丢失
200测量未启动
201测量已在运行

7. 快速开始

1. 订阅设备主题

订阅: vdm/{deviceId}/rpc/resp
订阅: vdm/{deviceId}/telemetry
订阅: vdm/{deviceId}/attributes
订阅: vdm/{deviceId}/event
订阅: vdm/{deviceId}/3A
订阅: vdm/{deviceId}/image

2. 初始化标靶

发布到 vdm/{deviceId}/rpc/req:

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [{"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}]
}}

3. 启动测量

{"reqId": 2, "method": "startMeasurement", "params": {}}

4. 接收位移数据

从 vdm/{deviceId}/telemetry 接收:

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

4 - VDM-V2W

V2W/V2W4M 双目固定式视觉位移计 API 参考手册

型号: V2W / V2W4M | 版本: 1.0 | 更新: 2026-01-08

V2W 系列是双目固定式视觉位移计，支持双视觉传感器同步测量。配合另一台设备可实现 3D 空间位移融合计算。

1. API 列表

基础 API

方法说明
getAttr获取属性
setAttr设置属性
reboot重启设备
syncTime同步时间

标靶管理 API

方法说明
initRefTargets初始化标靶
addTargets添加标靶
getTargets获取标靶列表
setTargets更新标靶配置
deleteTargets删除标靶

测量控制 API

方法说明
startMeasurement启动测量
stopMeasurement停止测量
setLightLevel设置补光灯发光挡位
getLightLevel获取补光灯发光挡位
snapshot获取快照

存储 API

方法说明
getStorageInfo获取存储信息
queryTelemetry查询历史数据
uploadS3上传数据到 S3

2. API 详情

initRefTargets

双目设备需要指定 sensorId 参数。

参数：

字段类型必填说明
targetsArray是标靶配置
targets[].targetIdString否标靶 ID
targets[].sensorIdInteger是视觉传感器 ID (0 或 1)
targets[].roiObject是ROI 区域
targets[].distanceFloat是测量距离 (m)

请求（V2W）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1200, "y": 600, "width": 400, "height": 400}, "distance": 5.0}
  ]
}}

请求（V2W4M）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 500, "y": 300, "width": 200, "height": 200}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 600, "y": 350, "width": 200, "height": 200}, "distance": 5.0}
  ]
}}

注意： V2W4M 分辨率为 2560×1440，ROI 坐标需相应调整。

addTargets

在已有标靶基础上添加新标靶。

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "3", "sensorId": 0, "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["3"]}}

getTargets

获取当前标靶列表。

请求：

{"reqId": 1, "method": "getTargets", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1200, "y": 600, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"}
  ]
}}

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [
    {"targetId": "1", "distance": 5.5}
  ]
}}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

setLightLevel

设置补光灯发光挡位。V2W 为双目设备，有两个补光灯。

请求（批量设置不同发光强度）：

{"reqId": 1, "method": "setLightLevel", "params": {
  "lights": [
    {"id": 0, "brightness": 5000},
    {"id": 1, "brightness": 8000}
  ]
}}

请求（全部相同发光强度）：

{"reqId": 1, "method": "setLightLevel", "params": {"brightness": 5000}}

setAttr

支持配置 3D 融合上报指标。

请求：

{"reqId": 1, "method": "setAttr", "params": {
  "reportMetrics": ["dx", "dy", "dz","tilt"]
}}

3. 遥测数据

测量运行时，设备按采样频率上报位移数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"dx":[0.01,0.02],"dy":[0.00,0.01],"dz":[0.01,0.02],"tilt":[0.00,0.01]}}}}
字段单位说明
t秒Unix 时间戳
dxmmX 方向累积位移变化
dymmY 方向累积位移变化
dzmmZ 方向累积位移变化
tilt倾斜角″（角秒）

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别名称说明
0-恢复
1alert预警
2alarm告警
3action行动

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "measurementStarted",
  "ts": 1734567890,
  "data": {}
}

事件类型：

事件说明data 内容
measurementStarted测量开始{}
measurementStopped测量停止{}
TARGET_LOST标靶丢失{"targetId": "1"}
targetRecovered标靶恢复{"targetId": "1"}

6. 错误码

码说明
0成功
1参数无效
2缺少必填参数
100标靶不存在
102标靶初始化失败
104标靶丢失
200测量未启动
201测量已在运行

7. 快速开始

1. 双视觉传感器初始化标靶

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}
  ]
}}

2. 启用 3D 融合上报

{"reqId": 2, "method": "setAttr", "params": {"reportMetrics": ["dx", "dy", "sx", "sy", "sz"]}}

3. 启动测量

{"reqId": 3, "method": "startMeasurement", "params": {}}

5 - VDM-V2K

V2K 双目自由角度视觉位移计 API 参考手册

型号: V2K | 版本: 1.0 | 更新: 2026-01-08

V2K 是双目固定式视觉位移计，双视觉传感器可独立调整角度，适用于需要灵活监测角度的场景。

与 V2W 的区别： V2K 双视觉传感器可朝向不同方向，因此各标靶距离可能不同。

1. API 列表

基础 API

方法说明
getAttr获取属性
setAttr设置属性
reboot重启设备
syncTime同步时间

标靶管理 API

方法说明
initRefTargets初始化标靶
addTargets添加标靶
getTargets获取标靶列表
setTargets更新标靶配置
deleteTargets删除标靶

测量控制 API

方法说明
startMeasurement启动测量
stopMeasurement停止测量
setLightLevel设置补光灯发光挡位
getLightLevel获取补光灯发光挡位
snapshot获取快照

存储 API

方法说明
getStorageInfo获取存储信息
queryTelemetry查询历史数据
uploadS3上传数据到 S3

2. API 详情

initRefTargets

双视觉传感器可独立配置不同距离。

参数：

字段类型必填说明
targetsArray是标靶配置
targets[].targetIdString否标靶 ID
targets[].sensorIdInteger是视觉传感器 ID (0 或 1)
targets[].roiObject是ROI 区域
targets[].distanceFloat是测量距离 (m)

请求（不同距离）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 800, "y": 600, "width": 400, "height": 400}, "distance": 8.0}
  ]
}}

V2K 双视觉传感器可朝向不同方向，因此各标靶距离可能不同。

addTargets

在已有标靶基础上添加新标靶。

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "3", "sensorId": 0, "roi": {"x": 600, "y": 400, "width": 400, "height": 400}, "distance": 5.5}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["3"]}}

getTargets

获取当前标靶列表。

请求：

{"reqId": 1, "method": "getTargets", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 800, "y": 600, "width": 400, "height": 400}, "distance": 8.0, "status": "tracking"}
  ]
}}

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [
    {"targetId": "1", "distance": 5.5}
  ]
}}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

setAttr

支持配置 3D 融合上报指标。

请求：

{"reqId": 1, "method": "setAttr", "params": {
  "reportMetrics": ["dx", "dy", "sx", "sy", "sz"]
}}
指标说明
dx, dy2D 位移
sx, sy, sz3D 空间位移（双设备融合）

3. 遥测数据

测量运行时，设备按采样频率上报累积位移变化数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"dx":[0.01,0.02],"dy":[0.00,0.01],"sx":[0.01,0.02],"sy":[0.00,0.01],"sz":[0.00,0.00]}}}}
字段单位说明
t秒Unix 时间戳
dx, dymm2D 位移
sx, sy, szmm3D 空间位移（双设备融合）

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别名称说明
0-恢复
1alert预警
2alarm告警
3action紧急

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "measurementStarted",
  "ts": 1734567890,
  "data": {}
}

事件类型：

事件说明data 内容
measurementStarted测量开始{}
measurementStopped测量停止{}
TARGET_LOST标靶丢失{"targetId": "1"}
targetRecovered标靶恢复{"targetId": "1"}

6. 错误码

码说明
0成功
1参数无效
2缺少必填参数
100标靶不存在
102标靶初始化失败
104标靶丢失
200测量未启动
201测量已在运行

7. 快速开始

1. 双视觉传感器初始化标靶（不同距离）

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 800, "y": 600, "width": 400, "height": 400}, "distance": 8.0}
  ]
}}

2. 启用 3D 融合上报

{"reqId": 2, "method": "setAttr", "params": {"reportMetrics": ["dx", "dy", "sx", "sy", "sz"]}}

3. 启动测量

{"reqId": 3, "method": "startMeasurement", "params": {}}

6 - VDM-O1

O1 单目单轴旋转式视觉位移计 API 参考手册

型号: O1 | 版本: 1.0 | 更新: 2026-01-08

O1 是单目单轴旋转式视觉位移计，支持水平方向云台控制和巡航。

1. API 列表

基础 API

方法说明
getAttr获取属性
setAttr设置属性
reboot重启设备
syncTime同步时间

标靶管理 API

方法说明
initRefTargets初始化标靶
addTargets添加标靶
getTargets获取标靶列表
setTargets更新标靶配置
deleteTargets删除标靶

测量控制 API

方法说明
startMeasurement启动测量
stopMeasurement停止测量
setLightLevel设置补光灯发光挡位
getLightLevel获取补光灯发光挡位
snapshot获取快照

存储 API

方法说明
getStorageInfo获取存储信息
queryTelemetry查询历史数据
uploadS3上传数据到 S3

电机控制 API（仅水平）

方法说明
setMotorAngle设置电机角度（仅 pan）
getMotorAngle获取电机角度
setMotorZero设置电机零点
enableMotor启用电机
disableMotor禁用电机

巡航控制 API

方法说明
getCruisePaths获取巡航路径
setCruisePoint设置巡航点
removeCruisePoint移除巡航点
startPatrol启动巡航
stopPatrol停止巡航
getPatrolStatus获取巡航状态

2. API 详情

initRefTargets

初始化参考标靶。

请求：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [{"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}]
}}

addTargets

在已有标靶基础上添加新标靶。

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "2", "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["2"]}}

getTargets

获取当前标靶列表。

请求：

{"reqId": 1, "method": "getTargets", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"}
  ]
}}

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [{"targetId": "1", "distance": 5.5}]
}}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

setMotorAngle

设置电机角度。

注意： O1 仅支持水平 (pan) 方向，不支持 tilt 参数。

参数：

字段类型范围说明
panFloat-180 ~ 180水平角度 (°)
speedInteger1-100转动速度 (%)

请求：

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 45.0, "speed": 50}}

getMotorAngle

获取当前电机角度。

请求：

{"reqId": 1, "method": "getMotorAngle", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {"pan": 45.0}}

setCruisePoint

设置巡航点。

注意： O1 巡航点仅支持 pan 角度。

参数：

字段类型必填说明
pathIdInteger是路径 ID
pointIdInteger是巡航点 ID
panFloat是水平角度
targetsArray是标靶 ID 列表
dwellTimeInteger否停留时间 (秒)

请求：

{"reqId": 1, "method": "setCruisePoint", "params": {
  "pathId": 1,
  "pointId": 1,
  "pan": 45.0,
  "targets": ["1"],
  "dwellTime": 60
}}

startPatrol

启动巡航。

请求：

{"reqId": 1, "method": "startPatrol", "params": {"pathId": 1}}

stopPatrol

停止巡航。

请求：

{"reqId": 1, "method": "stopPatrol", "params": {}}

3. 遥测数据

测量运行时，设备按采样频率上报位移数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"dx":[0.01,0.02,0.03],"dy":[0.00,0.01,0.01]}}}}
字段单位说明
t秒Unix 时间戳
dxmmX 方向位移
dymmY 方向位移

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别名称说明
0-恢复
1alert预警
2alarm告警
3action紧急

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "cruisePointReached",
  "ts": 1734567890,
  "data": {"pathId": 1, "pointId": 1}
}

事件类型：

事件说明data 内容
measurementStarted测量开始{}
measurementStopped测量停止{}
TARGET_LOST标靶丢失{"targetId": "1"}
targetRecovered标靶恢复{"targetId": "1"}
motorMoved电机移动完成{"pan": 45.0}
cruisePointReached到达巡航点{"pathId": 1, "pointId": 1}

6. 错误码

码说明
0成功
1参数无效
2缺少必填参数
100标靶不存在
102标靶初始化失败
104标靶丢失
200测量未启动
201测量已在运行
300电机不可用
302电机运动中
310垂直电机不可用（O1 不支持）
400巡航功能不可用
403巡航已在运行

7. 快速开始

1. 移动到位置

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 0}}

2. 初始化标靶

{"reqId": 2, "method": "initRefTargets", "params": {
  "targets": [{"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}]
}}

3. 设置巡航点

{"reqId": 3, "method": "setCruisePoint", "params": {
  "pathId": 1, "pointId": 1, "pan": 0, "targets": ["1"], "dwellTime": 60
}}

4. 启动测量

{"reqId": 4, "method": "startMeasurement", "params": {}}

7 - VDM-X1

X1 单目双轴旋转式视觉位移计 API 参考手册

型号: X1 | 版本: 1.0 | 更新: 2026-01-08

X1 是单目双轴旋转式视觉位移计，支持水平和垂直云台控制及自动巡航。

1. API 列表

基础 API

方法说明
getAttr获取属性
setAttr设置属性
reboot重启设备
syncTime同步时间

标靶管理 API

方法说明
initRefTargets初始化标靶
addTargets添加标靶
getTargets获取标靶列表
setTargets更新标靶配置
deleteTargets删除标靶

测量控制 API

方法说明
startMeasurement启动测量
stopMeasurement停止测量
setLightLevel设置补光灯发光挡位
getLightLevel获取补光灯发光挡位
snapshot获取快照

存储 API

方法说明
getStorageInfo获取存储信息
queryTelemetry查询历史数据
uploadS3上传数据到 S3

电机控制 API

方法说明
setMotorAngle设置电机角度
getMotorAngle获取电机角度
setMotorZero设置电机零点
enableMotor启用电机
disableMotor禁用电机

巡航控制 API

方法说明
getCruisePaths获取巡航路径
setCruisePoint设置巡航点
removeCruisePoint移除巡航点
startPatrol启动巡航
stopPatrol停止巡航
getPatrolStatus获取巡航状态

2. API 详情

initRefTargets

初始化参考标靶。

请求：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [{"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}]
}}

addTargets

在已有标靶基础上添加新标靶。

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "2", "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["2"]}}

getTargets

获取当前标靶列表。

请求：

{"reqId": 1, "method": "getTargets", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"}
  ]
}}

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [{"targetId": "1", "distance": 5.5}]
}}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

setMotorAngle

设置电机角度。

参数：

字段类型范围说明
panFloat-180 ~ 180水平角度 (°)
tiltFloat-90 ~ 90垂直角度 (°)
speedInteger1-100转动速度 (%)

请求：

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 45.0, "tilt": -10.0, "speed": 50}}

getMotorAngle

获取当前电机角度。

请求：

{"reqId": 1, "method": "getMotorAngle", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {"pan": 45.0, "tilt": -10.0}}

setCruisePoint

设置巡航点。

参数：

字段类型必填说明
pathIdInteger是路径 ID
pointIdInteger是巡航点 ID
panFloat是水平角度
tiltFloat是垂直角度
targetsArray是标靶 ID 列表
dwellTimeInteger否停留时间 (秒)

请求：

{"reqId": 1, "method": "setCruisePoint", "params": {
  "pathId": 1,
  "pointId": 1,
  "pan": 45.0,
  "tilt": -10.0,
  "targets": ["1"],
  "dwellTime": 60
}}

startPatrol

启动巡航。

请求：

{"reqId": 1, "method": "startPatrol", "params": {"pathId": 1}}

stopPatrol

停止巡航。

请求：

{"reqId": 1, "method": "stopPatrol", "params": {}}

3. 遥测数据

测量运行时，设备按采样频率上报位移数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"dx":[0.01,0.02,0.03],"dy":[0.00,0.01,0.01]}}}}
字段单位说明
t秒Unix 时间戳
dxmmX 方向位移
dymmY 方向位移

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别名称说明
0-恢复
1alert预警
2alarm告警
3action紧急

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "cruisePointReached",
  "ts": 1734567890,
  "data": {"pathId": 1, "pointId": 1}
}

事件类型：

事件说明data 内容
measurementStarted测量开始{}
measurementStopped测量停止{}
TARGET_LOST标靶丢失{"targetId": "1"}
targetRecovered标靶恢复{"targetId": "1"}
motorMoved电机移动完成{"pan": 45.0, "tilt": -10.0}
cruisePointReached到达巡航点{"pathId": 1, "pointId": 1}

6. 错误码

码说明
0成功
1参数无效
2缺少必填参数
100标靶不存在
102标靶初始化失败
104标靶丢失
200测量未启动
201测量已在运行
300电机不可用
302电机运动中
303电机到达限位
400巡航功能不可用
403巡航已在运行

7. 快速开始

1. 移动到位置

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 0, "tilt": 0}}

2. 初始化标靶

{"reqId": 2, "method": "initRefTargets", "params": {
  "targets": [{"targetId": "1", "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}]
}}

3. 设置巡航点

{"reqId": 3, "method": "setCruisePoint", "params": {
  "pathId": 1, "pointId": 1, "pan": 0, "tilt": 0, "targets": ["1"], "dwellTime": 60
}}

4. 启动测量

{"reqId": 4, "method": "startMeasurement", "params": {}}

8 - VDM-X2W

X2W/X2W4M 双目旋转式视觉位移计 API 参考手册

型号: X2W / X2W4M | 版本: 1.0 | 更新: 2026-01-08

X2W 系列是双目旋转式视觉位移计，支持双轴云台和自动巡航，适用于多点巡航监测场景。

1. API 列表

基础 API

方法说明
getAttr获取属性
setAttr设置属性
reboot重启设备
syncTime同步时间

标靶管理 API

方法说明
initRefTargets初始化标靶
addTargets添加标靶
getTargets获取标靶列表
setTargets更新标靶配置
deleteTargets删除标靶

测量控制 API

方法说明
startMeasurement启动测量
stopMeasurement停止测量
setLightLevel设置补光灯发光挡位
getLightLevel获取补光灯发光挡位
snapshot获取快照

存储 API

方法说明
getStorageInfo获取存储信息
queryTelemetry查询历史数据
uploadS3上传数据到 S3

电机控制 API

方法说明
setMotorAngle设置电机角度
getMotorAngle获取电机角度
setMotorZero设置电机零点
enableMotor启用电机
disableMotor禁用电机

巡航控制 API

方法说明
getCruisePaths获取巡航路径
setCruisePoint设置巡航点
removeCruisePoint移除巡航点
startPatrol启动巡航
stopPatrol停止巡航
getPatrolStatus获取巡航状态

2. API 详情

initRefTargets

双目设备需要指定 sensorId 参数。

参数：

字段类型必填说明
targetsArray是标靶配置
targets[].targetIdString否标靶 ID
targets[].sensorIdInteger是视觉传感器 ID (0 或 1)
targets[].roiObject是ROI 区域
targets[].distanceFloat是测量距离 (m)

请求（X2W）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1200, "y": 600, "width": 400, "height": 400}, "distance": 5.0}
  ]
}}

请求（X2W4M）：

{"reqId": 1, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 500, "y": 300, "width": 200, "height": 200}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 600, "y": 350, "width": 200, "height": 200}, "distance": 5.0}
  ]
}}

注意： X2W4M 分辨率为 2560×1440，ROI 坐标需相应调整。

addTargets

在已有标靶基础上添加新标靶。

请求：

{"reqId": 1, "method": "addTargets", "params": {
  "targets": [
    {"targetId": "3", "sensorId": 0, "roi": {"x": 800, "y": 400, "width": 400, "height": 400}, "distance": 6.0}
  ]
}}

响应：

{"reqId": 1, "code": 0, "data": {"addedIds": ["3"]}}

getTargets

获取当前标靶列表。

请求：

{"reqId": 1, "method": "getTargets", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1200, "y": 600, "width": 400, "height": 400}, "distance": 5.0, "status": "tracking"}
  ]
}}

setTargets

更新已有标靶的配置。

请求：

{"reqId": 1, "method": "setTargets", "params": {
  "targets": [{"targetId": "1", "distance": 5.5}]
}}

deleteTargets

删除指定标靶。

请求：

{"reqId": 1, "method": "deleteTargets", "params": {
  "targetIds": ["2"]
}}

setMotorAngle

设置电机角度。

参数：

字段类型范围说明
panFloat-180 ~ 180水平角度 (°)
tiltFloat-90 ~ 90垂直角度 (°)
speedInteger1-100转动速度 (%)

请求：

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 45.0, "tilt": -10.0, "speed": 50}}

getMotorAngle

获取当前电机角度。

请求：

{"reqId": 1, "method": "getMotorAngle", "params": {}}

响应：

{"reqId": 1, "code": 0, "data": {"pan": 45.0, "tilt": -10.0}}

setCruisePoint

设置巡航点。

参数：

字段类型必填说明
pathIdInteger是路径 ID
pointIdInteger是巡航点 ID
panFloat是水平角度
tiltFloat是垂直角度
targetsArray是标靶 ID 列表
dwellTimeInteger否停留时间 (秒)

请求：

{"reqId": 1, "method": "setCruisePoint", "params": {
  "pathId": 1,
  "pointId": 1,
  "pan": 45.0,
  "tilt": -10.0,
  "targets": ["1", "2"],
  "dwellTime": 60
}}

setAttr

支持配置 3D 融合上报指标。

请求：

{"reqId": 1, "method": "setAttr", "params": {
  "reportMetrics": ["dx", "dy", "dz", "tilt"]
}}
指标说明
dxX方向累积位移变化
dyY方向累积位移变化
dzZ方向累积位移变化
tilt倾斜角度变化

3. 遥测数据

测量运行时，设备按采样频率上报位移数据。

主题： vdm/{deviceId}/telemetry

{"disp":{"t":1734567890,"d":{"1":{"dx":[0.01,0.02],"dy":[0.00,0.01],"dz":[0.01,0.02],"tilt": 0.01}}}}
字段单位说明
t秒Unix 时间戳
dxmmX方向累积位移变化
dymmY方向累积位移变化
dzmmZ方向累积位移变化
tilt″（角秒）倾斜角度变化

4. 告警数据

位移超限时通过 3A 主题上报。

主题： vdm/{deviceId}/3A

{
  "3A": "DISPLACEMENT_EXCEEDED",
  "level": 2,
  "targetId": "1",
  "value": 12.5,
  "threshold": 10.0,
  "ts": 1734567890
}

告警级别：

级别名称说明
0-恢复
1alert预警
2alarm告警
3action紧急

5. 事件数据

设备状态变化时通过 event 主题上报。

主题： vdm/{deviceId}/event

{
  "event": "cruisePointReached",
  "ts": 1734567890,
  "data": {"pathId": 1, "pointId": 1}
}

事件类型：

事件说明data 内容
measurementStarted测量开始{}
measurementStopped测量停止{}
TARGET_LOST标靶丢失{"targetId": "1"}
targetRecovered标靶恢复{"targetId": "1"}
motorMoved电机移动完成{"pan": 45.0, "tilt": -10.0}
cruisePointReached到达巡航点{"pathId": 1, "pointId": 1}

6. 错误码

码说明
0成功
1参数无效
2缺少必填参数
100标靶不存在
102标靶初始化失败
104标靶丢失
200测量未启动
201测量已在运行
300电机不可用
302电机运动中
303电机到达限位
400巡航功能不可用
403巡航已在运行

7. 典型工作流程

多点巡航监测

1. 设置巡航点 1 (pan=0, tilt=0)
   └─ 初始化标靶 1, 2

2. 设置巡航点 2 (pan=45, tilt=-10)
   └─ 初始化标靶 3

3. 启动巡航
   └─ 设备自动在各点之间循环
   └─ 每个点停留 dwellTime 秒进行测量

4. 接收遥测数据
   └─ 位移数据包含当前巡航点的标靶

8. 快速开始

1. 移动到位置

{"reqId": 1, "method": "setMotorAngle", "params": {"pan": 0, "tilt": 0}}

2. 初始化标靶

{"reqId": 2, "method": "initRefTargets", "params": {
  "targets": [
    {"targetId": "1", "sensorId": 0, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0},
    {"targetId": "2", "sensorId": 1, "roi": {"x": 1000, "y": 500, "width": 400, "height": 400}, "distance": 5.0}
  ]
}}

3. 设置巡航点

{"reqId": 3, "method": "setCruisePoint", "params": {
  "pathId": 1, "pointId": 1, "pan": 0, "tilt": 0, "targets": ["1", "2"], "dwellTime": 60
}}

4. 启动测量

{"reqId": 4, "method": "startMeasurement", "params": {}}