快速入门

连接系统集成商 MQTT Broker，接收位移数据并调用设备接口

本页按“准备设备 → 启动接收端 → 配置设备连接 → 验证数据 → 调用 RPC → 接收告警抓拍”的顺序完成一次接入。

设备和接收端连接的是同一个系统集成商 MQTT Broker。接收端只负责订阅和调用；Broker 地址、端口及认证信息由系统集成商提供。

1. 准备设备和运行环境

在 App 中完成设备的标靶配置和初始化，记下设备 ID。验证位移前，设备必须处于测量状态并能看到有效标靶。

在能够访问 Broker 的电脑或服务器上安装 Git、Docker 和 Docker Compose v2。以下命令在 Bash 终端执行。

2. 配置并启动接收程序

先在接收端所在的电脑或服务器上下载示例，并填写系统集成商提供的 Broker 域名或 IP、端口，以及设备 ID：

git clone https://github.com/inteagle-vision/inteagle-vdm-mqtt-examples.git
cd inteagle-vdm-mqtt-examples
export VDM_DEVICE_ID=YOUR_DEVICE_ID
export MQTT_HOST=YOUR_BROKER_HOST
export MQTT_PORT=1883  # 替换为 Broker 的实际端口

是否需要认证及认证信息由系统集成商指定。需要用户名、密码时，填写分配给接收程序的账号：

export MQTT_USERNAME=YOUR_USERNAME
export MQTT_PASSWORD=YOUR_PASSWORD

选择数据格式并启动：

export VDM_PAYLOAD_FORMAT=protobuf
./run_demo.sh protobuf

export VDM_PAYLOAD_FORMAT=json
./run_demo.sh json

脚本在后台启动接收程序并连接上述 Broker。保持这些服务运行，再配置设备端连接；以下命令均在仓库根目录执行。

3. 让设备连接 Broker

在 App 中添加系统集成商 MQTT 连接：

配置填写内容
Broker 地址系统集成商提供的域名或 IP，公网、内网均可
端口系统集成商指定的 MQTT 端口
用户名、密码按系统集成商为设备分配的认证信息填写；是否需要认证以接入要求为准
Payload第 2 步选择的 Protobuf 或 JSON

保存并启用连接。设备连接成功后，向 vdm/{deviceId}/telemetry 发布位移，接收程序订阅同一设备的主题。设备端 Payload 必须与接收程序选择的格式一致。

4. 确认收到位移数据

查看接收程序的输出：

docker compose logs -f python-data go-data java-data javascript-data

READY 只表示订阅已建立，不代表设备已经上报数据。看到包含标靶 ID 和非空位移数组的 telemetry 行，才表示位移链路已打通。例如：

{
  "schemaVersion": 1,
  "displacement": {
    "sampleFrequencyHz": 2,
    "firstSampleTimestampMs": "1734567890000",
    "targets": [{"targetId": "T01", "dx": [0.01, 0.02], "dy": [0.0, 0.01]}]
  }
}

{
  "disp": {
    "t": 1734567890,
    "f": 2,
    "d": {"T01": {"dx": [0.01, 0.02], "dy": [0.0, 0.01]}}
  }
}

T01 是示例标靶 ID，X / Y 位移单位为 mm；2 Hz 表示数组中相邻样本相隔 0.5 秒。Protobuf 的首个样本时间使用 Unix 毫秒，JSON 使用 Unix 秒。

确认接收程序收到包含标靶 ID 和位移数组的消息。telemetry 还可能包含环境和设备状态，完整字段见 遥测数据。按 Ctrl+C 只退出日志查看，后台接收程序仍会运行。

5. 查询设备属性

位移数据正常后，任选一种语言发送一次 RPC（远程调用），查询设备 ID、型号、固件版本和测量状态：

语言在当前终端执行
Javadocker compose run --rm --no-deps java-data --query-attributes
Godocker compose run --rm --no-deps go-data --query-attributes
Pythondocker compose run --rm --no-deps python-data --query-attributes
JavaScriptdocker compose run --rm --no-deps javascript-data --query-attributes

看到 RESPONSE 且 code=0，说明请求已到达设备并收到成功响应。程序随后继续接收数据；按 Ctrl+C 退出本次运行。

请求发送到 vdm/{deviceId}/rpc/req，响应来自 vdm/{deviceId}/rpc/resp。后续可调用标靶管理接口和测量控制接口，完整格式见 RPC 格式。

6. 接入告警与抓拍

位移和 RPC 接通后，再配置告警。按 告警配置示例查询能力、创建规则，并订阅 vdm/{deviceId}/3A。等级和参数见 告警参考。

需要抓拍时，为规则配置 SNAPSHOT 动作。仅配置一个已启用的系统集成商 MQTT 连接，且未另行指定或关闭抓拍上传时，设备默认向该连接发送；多个连接时需指定接收目标。

启动抓拍接收程序：

./run_demo.sh "$VDM_PAYLOAD_FORMAT" --evidence
docker compose logs -f python-evidence go-evidence java-evidence javascript-evidence

各接收程序独立保存图像包，校验通过后调用 ackEvidencePackage。VERIFIED 表示完整包校验通过，ACKED 表示设备已接受确认。完整代码、保存位置与补传方法见 抓拍接入说明。

联调排查

现象检查项
设备无法连接 Broker设备端填写的 Broker 域名或 IP、端口、认证信息及网络连通性
程序就绪但没有消息App 中连接是否在线、设备 ID 和 Payload 格式是否正确
有环境数据但没有位移设备是否正在测量，标靶是否已初始化并有有效观测
消息解析失败设备与接收程序所选格式是否一致
RPC 超时设备是否在线，是否允许请求 Topic 发布和响应 Topic 订阅

测试结束后执行 docker compose --profile evidence down 停止服务。抓拍文件保留在 Docker 数据卷中。

在本机运行单一语言时，参见 GitHub SDK 与运行步骤。

需要自行搭建联调 Broker 时，参见 NanoMQ 联调环境。