API参考

VDM 设备接口技术规格

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

连接参数

参数	值
协议	MQTT v3.1.1
Payload	JSON

主题结构

主题	方向	说明
`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 支持矩阵

API	V1	V2W	V2K	O1	X1	X2W
基础 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 二进制数据]

偏移	长度	字段	说明
0	1	version	协议版本，当前 `0x01`
1	1	headerLen	Header 总长度（字节）
2	1	sensorId	视觉传感器 ID（单目为 0，双目为 0 或 1）
3	1	type	图片类型（见下表）
4	4	timestamp	Unix 时间戳（uint32, 大端）
8+	-	imageData	JPEG 二进制数据

图片类型 (type)：

值	类型	说明
0	snapshot	RPC 触发的快照
1	3A	告警触发的抓图
2	periodic	定时抓图

示例

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 跳过不识别的字段，保证向后兼容。