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"]
  }
}

属性列表：

属性	类型	读写	说明
`deviceId`	String	R	设备 ID
`deviceModel`	String	R	型号
`fwVer`	String	R	固件版本
`measureStatus`	String	R	测量状态
`sampleFreq`	Float	RW	采样频率 (Hz)
`exposure`	String	RW	曝光档位：High/Middle/Low
`brightnessThr`	Integer	RW	发光强度阈值 (0-255)
`reportMetrics`	Array	RW	上报指标

setAttr

设置设备属性。

请求：

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

响应：

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

initRefTargets

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

参数：

字段	类型	必填	说明
`targets`	Array	是	标靶配置
`targets[].targetId`	String	否	标靶 ID（不填则自动生成）
`targets[].roi`	Object	是	ROI 区域
`targets[].distance`	Float	是	测量距离 (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`	-	数据的坐标系是全局还是局部。
`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": "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]}}}}