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

设置电机角度。

参数：

字段	类型	范围	说明
`pan`	Float	-180 ~ 180	水平角度 (°)
`tilt`	Float	-90 ~ 90	垂直角度 (°)
`speed`	Integer	1-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

设置巡航点。

参数：

字段	类型	必填	说明
`pathId`	Integer	是	路径 ID
`pointId`	Integer	是	巡航点 ID
`pan`	Float	是	水平角度
`tilt`	Float	是	垂直角度
`targets`	Array	是	标靶 ID 列表
`dwellTime`	Integer	否	停留时间 (秒)

请求：

{"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 时间戳
`dx`	mm	X 方向位移
`dy`	mm	Y 方向位移

4. 告警数据

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

主题： vdm/{deviceId}/3A

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

告警级别：

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

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": {}}