文档

• 1: 引言
• 2: 平台端 API
• 2.1: 核心概念
• 2.2: 快速入门
• 2.3: MQTT 数据订阅
• 2.3.1: 项目与监测点数据
• 2.3.2: 设备数据格式
• 2.3.2.1: VDM 视觉位移计
• 2.4: 数据字典
• 2.5: 故障排查
• 3: 设备 API
• 3.1: 视觉位移计(VDM)
• 3.1.1: 快速入门
• 3.1.2: API 参考
• 3.1.3: V1 Lite
• 3.1.4: V1
• 3.1.5: V1 Pro
• 3.1.6: V2-H
• 3.1.7: V2-W
• 3.1.8: V2-K
• 3.1.9: O1
• 3.1.10: O2-H
• 3.1.11: X1
• 3.1.12: X2-H
• 3.2: INT705 倾角振动传感器
• 3.2.1: 协议规格
• 3.3: 接入设备
• 3.3.1: 应变读数仪
• 3.3.1.1: 协议规格
• 4: 名词解释

1 - 引言

本文档介绍如何对接 Inteagle 监测设备。

API 对接方式

Inteagle 提供两种数据对接方式，客户可根据业务需求和开发能力选择不同的接入方式。

说明：

• 建议不熟悉设备的客户前期采用平台对接方式获取数据和控制设备，接入更简单便捷，成本更低。
• 对设备的使用已经比较熟悉或者有更高需求的客户请联系鹰腾工作人员开通设备直连权限。
• 有数据保密要求的客户请联系鹰腾工作人员开通设备直连权限。

平台对接

适用于通过 Inteagle 结构健康监测平台获取设备数据的场景。

• 平台托管，无需维护基础设施
• 提供数据存储、告警、可视化等增值服务
• 客户通过 SDK 查询数据和控制设备

查看平台端 API →

设备直连

适用于客户搭建自有 MQTT Broker 平台，由设备直接上报数据的场景。

• 设备直接连接客户 MQTT Broker，减少中间转发
• 需要自行管理 MQTT Broker、设备连接和数据存储
• 参考各设备类型的 MQTT 协议文档

查看设备 API →

支持的设备类型

更多设备类型持续更新中…

2 - 平台端 API

本章节介绍如何将您的系统与 Inteagle 结构健康监测平台对接。

推荐方式：使用 SDK

强烈推荐使用官方 Java SDK 进行开发，SDK 封装了认证、API 调用、数据解析等功能，简化开发流程。

// Maven 依赖
<dependency>
    <groupId>com.inteagle</groupId>
    <artifactId>shm-sdk</artifactId>
    <version>0.3.1</version>
</dependency>

// 快速使用
InteagleClient client = InteagleClient.builder()
    .apiEndpoint("https://api.shm.inteagle.com")
    .credentials(accessKey, secretKey)
    .build();

// 查询项目
List<Project> projects = client.projects().list();

Go SDK 即将推出，敬请期待。

详见 SDK 仓库 和 快速入门

对接方式

文档导航

2.1 - 核心概念

理解平台的核心概念有助于更高效地使用SDK和API。

数据模型

Inteagle 结构健康监测平台采用三层数据模型：

graph TD
    subgraph L1["第一层 - 租户层"]
        A[客户 Customer]
    end

    subgraph L2["第二层 - 项目层"]
        B[项目 Project]
    end

    subgraph L3["第三层 - 数据采集层"]
        C1[监测点<br/>Monitoring Point<br/>业务视角]
        C2[设备<br/>Device<br/>物理设备]
    end

    subgraph DATA["数据层"]
        D1[监测点数据<br/>dx dy tilt]
        D2[设备原始数据<br/>标靶坐标]
    end

    A -->|1:N 包含| B
    B -->|1:N 包含| C1
    B -->|1:N 包含| C2
    C1 -->|1:N 产生| D1
    C2 -->|1:N 上报| D2
    C1 <-.->|N:M 多对多映射| C2

    style A fill:#e1f5ff,stroke:#01579b,stroke-width:3px
    style B fill:#fff4e1,stroke:#e65100,stroke-width:3px
    style C1 fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style C2 fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style D1 fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px
    style D2 fill:#e8f5e9,stroke:#1b5e20,stroke-width:1px

核心特点：

1. 第一层（租户层）：客户级数据隔离
2. 第二层（项目层）：一个项目对应一个监测工程
3. 第三层（数据采集层）：
   • 监测点：业务视角，反映监测需求
   • 设备：物理设备，采集原始数据
   • 关键：监测点 ↔ 设备 是多对多映射关系

层级关系

核心实体

项目 (Project)

监测工程的顶层容器，对应一个实际的工程项目（如桥梁监测、边坡监测）。

属性：

• 项目名称、编号
• 监测类型（桥梁/隧道/边坡/环境等）
• 地理位置
• 起止日期

包含：

• 多个监测点（类型取决于监测场景）
• 多个设备

典型项目场景：

场景 1：桥梁监测项目

graph TD
    P1[桥梁监测项目]
    P1 --> PT1["位移监测点 x10"]
    P1 --> PT2["倾斜监测点 x4"]
    P1 --> PT3["应变监测点 x8"]
    P1 --> PT4["环境监测点 x2"]
    P1 --> D1["设备: V2K x6, X1 x4, O1 x8"]

    style P1 fill:#fff4e1
    style PT1 fill:#f3e5f5
    style PT2 fill:#f3e5f5
    style PT3 fill:#f3e5f5
    style PT4 fill:#f3e5f5
    style D1 fill:#e1f5ff

场景 2：隧道监测项目

graph TD
    P2[隧道监测项目]
    P2 --> PT1["收敛监测点 x15"]
    P2 --> PT2["沉降监测点 x20"]
    P2 --> D2["设备: V2K x10, X1 x5"]

    style P2 fill:#e3f2fd
    style PT1 fill:#f3e5f5
    style PT2 fill:#f3e5f5
    style D2 fill:#e1f5ff

场景 3：环境监测项目

graph TD
    P3[环境监测项目]
    P3 --> PT1["环境监测点 x5"]
    P3 --> D3["环境传感器 x5"]

    style P3 fill:#e8f5e9
    style PT1 fill:#f3e5f5
    style D3 fill:#e1f5ff

监测点 (Monitoring Point)

业务视角的测量点，聚合了来自设备的监测指标。

特点：

• 业务导向：反映实际的监测需求（如"3号桥墩位移"）
• 指标聚合：可从多个设备/通道汇总数据
• 多对多关系：
  • 一个监测点可以从多个设备的数据组合而成
  • 一个设备可以为多个监测点提供数据（如视觉位移计设备可为多个监测点提供数据）
• 场景化配置：不同监测场景下，监测点关注的指标类型不同

监测点类型与场景：

详细监测点类型参见 数据字典 - 监测点类型

示例 1：多设备融合 → 一个监测点（3D 空间位移）

典型应用：通过两台视觉位移计的三角测量，融合计算出 3D 空间位移。

graph TD
    PT[监测点<br/>桥墩A-3D位移监测点<br/>输出: dx, dy, dz]
    D1[设备1 V2W<br/>标靶1]
    D2[设备2 V2W<br/>标靶1]
    L1[local坐标<br/>dx1, dy1]
    L2[local坐标<br/>dx2, dy2]
    FUSION[三维融合算法]

    D1 -->|测量| L1
    D2 -->|测量| L2
    L1 --> FUSION
    L2 --> FUSION
    FUSION -->|计算| PT

    style PT fill:#fff4e1,stroke:#e65100,stroke-width:3px
    style D1 fill:#e1f5ff
    style D2 fill:#e1f5ff
    style FUSION fill:#ffe0b2,stroke:#f57c00,stroke-width:2px

两台设备各自测量标靶在自己 local 坐标系下的 dx, dy，通过三维融合算法（空间几何计算）得到 global 坐标系下的完整 3D 位移（dx, dy, dz）。

示例 2：一个设备 → 多个监测点

graph TD
    D[设备 dev_001<br/>V2K 2靶位移计]
    T1[标靶1]
    T2[标靶2]
    PT1[监测点A<br/>桥墩A位移]
    PT2[监测点B<br/>桥墩B位移]

    D --> T1
    D --> T2
    T1 --> PT1
    T2 --> PT2

    style D fill:#e1f5ff
    style PT1 fill:#fff4e1
    style PT2 fill:#fff4e1

设备 (Device)

物理传感器/采集设备，上报原始测量数据。

VDM 视觉位移计系列：

所有 视觉位移计设备均基于视觉测量原理，可测量多个标靶。不同型号在视觉传感器数量（单目/双目）、云台功能（固定式/旋转式）、连接方式（有线/无线）上有所差异。

型号分类：

• 固定式：V1（单目）、V2K（双目）、V2W（双目） - 安装角度固定或可手动调整
• 旋转式：O1（单目单轴）、X1（单目双轴）、X2W（双目双轴） - 支持云台控制和自动巡航

详细型号规格参见 数据字典 - 设备类型

遥测数据 (Telemetry)

遥测数据是设备上报的时序监测数据，是平台的核心数据类型。

HTTP API 响应格式

通过 HTTP API 查询历史遥测数据时，返回按指标分组的时间序列：

示例：

{
  "dx": [
    { "ts": 1735560000000, "value": 0.05 },
    { "ts": 1735563600000, "value": 0.06 }
  ],
  "dy": [
    { "ts": 1735560000000, "value": 0.02 },
    { "ts": 1735563600000, "value": 0.03 }
  ]
}

注意：MQTT 实时推送格式不同，详见 MQTT 数据订阅。

时间戳约定

时间转换示例：

UTC 时间戳: 1735560000000
UTC 时间:   2024-12-30T12:00:00Z
北京时间:   2024-12-30 20:00:00 (UTC+8)

告警系统 (Alarm)

告警系统采用四态状态模型，支持完整的告警生命周期管理。

告警生命周期

stateDiagram-v2
    [*] --> ACTIVE_UNACK: 触发告警
    ACTIVE_UNACK --> ACTIVE_ACK: 确认
    ACTIVE_UNACK --> CLEARED_UNACK: 自动清除
    ACTIVE_ACK --> CLEARED_ACK: 自动清除
    CLEARED_UNACK --> CLEARED_ACK: 确认
    CLEARED_ACK --> [*]: 归档

告警状态说明

告警级别 (3A 体系)

平台采用 3A 告警级别体系：

详细告警定义参见 数据字典 - 告警级别

告警触发流程

sequenceDiagram
    participant D as 设备
    participant I as Inteagle平台
    participant C as 第三方云平台

    D->>I: 上报遥测数据
    I->>I: 检查告警规则
    alt 超过阈值
        I->>I: 创建告警 (ACTIVE_UNACK)
        I-->>C: MQTT 推送告警
    end
    alt 恢复正常
        I->>I: 清除告警 (CLEARED_*)
        I-->>C: MQTT 推送清除
    end

数据访问方式

Inteagle 提供 SDK，集成了 HTTP 和 MQTT 两种通道，配合使用获取完整的数据能力。

SDK 集成的两种通道

典型使用流程

1. 初始化：通过 HTTP 查询项目、监测点列表
2. 加载历史：通过 HTTP 查询历史遥测数据
3. 实时更新：通过 MQTT 订阅接收实时数据推送

下一步

根据您的需求选择阅读路径：

2.2 - 快速入门

本指南帮助您快速使用 SDK 对接 Inteagle 结构健康监测平台。

前置条件

• 已获取 Access Key 和 Secret Key（联系销售获取）

SDK 安装

SDK 仓库：https://github.com/inteagle-vision/shm-sdk

Java SDK

• Maven
• Gradle

<dependency>
    <groupId>com.inteagle</groupId>
    <artifactId>shm-sdk</artifactId>
    <version>0.3.1</version>
</dependency>

dependencies {
    implementation 'com.inteagle:shm-sdk:0.3.1'
}

Go SDK

Go SDK 即将推出，敬请期待。

快速开始

1. 创建客户端

import com.inteagle.shm.InteagleClient;

InteagleClient client = InteagleClient.builder()
    .apiEndpoint("https://api.shm.inteagle.com")
    .credentials("your-access-key", "your-secret-key")
    .build();

2. 查询项目

// 查询项目列表
List<Project> projects = client.projects().list();

for (Project project : projects) {
    System.out.println("项目: " + project.getName());
    System.out.println("ID: " + project.getId());
}

// 查询项目详情
Project project = client.projects().get("project-id");

3. 查询监测点

// 查询项目下的监测点
List<MonitoringPoint> points = client.points().listByProject("project-id");

for (MonitoringPoint point : points) {
    System.out.println("监测点: " + point.getName());
}

// 查询监测点详情
MonitoringPoint point = client.points().get("point-id");

4. 查询设备

// 查询项目下的设备
List<Device> devices = client.devices().listByProject("project-id");

// 查询设备详情
Device device = client.devices().get("device-id");
System.out.println("设备状态: " + (device.isOnline() ? "在线" : "离线"));

5. 查询遥测数据

// 查询监测点最新数据
TelemetryResult latest = client.telemetry()
    .entity("POINT", "point-id")
    .latest();

System.out.println("dx: " + latest.getValue("dx"));
System.out.println("dy: " + latest.getValue("dy"));

// 查询历史数据
long endTs = System.currentTimeMillis();
long startTs = endTs - 24 * 60 * 60 * 1000; // 最近24小时

TelemetryResult history = client.telemetry()
    .entity("POINT", "point-id")
    .timeRange(startTs, endTs)
    .metrics("dx", "dy")
    .query();

6. 查询告警

// 查询活动告警
List<Alarm> alarms = client.alarms()
    .projectId("project-id")
    .status("ACTIVE")
    .list();

for (Alarm alarm : alarms) {
    System.out.println("告警: " + alarm.getType());
    System.out.println("级别: " + alarm.getSeverity());
}

7. 查询告警规则

// 查询项目的告警规则
List<AlarmRule> rules = client.alarmRules()
    .projectId("project-id")
    .list();

for (AlarmRule rule : rules) {
    System.out.println("规则: " + rule.getName());
    System.out.println("启用: " + rule.isEnabled());
}

命令行工具

SDK 提供命令行工具 shm-cli，方便调试和测试：

# 配置凭证
shm-cli config --access-key YOUR_KEY --secret-key YOUR_SECRET

# 查询项目
shm-cli projects list

# 查询监测点
shm-cli points list --project PROJECT_ID

# 查询遥测数据
shm-cli telemetry latest --entity-type POINT --entity-id POINT_ID

# 查询告警规则
shm-cli alarm-rules list --project PROJECT_ID

下一步

• 核心概念 - 理解数据模型
• MQTT 订阅 - 实时数据推送
• 数据字典 - 字段与枚举定义
• SDK 仓库 - 完整文档和示例

2.3 - MQTT 数据订阅

Inteagle 结构健康监测平台提供 MQTT 实时数据推送服务。

连接信息

认证

Topic 结构

inteagle/{customerId}/p/{projectId}              # 项目所有数据
inteagle/{customerId}/p/{projectId}/mp/{pointId} # 监测点数据
inteagle/{customerId}/p/{projectId}/d/{deviceId} # 设备数据

订阅示例：

# 项目所有数据
inteagle/cust_abc123/p/proj_abc/#

# 所有监测点
inteagle/cust_abc123/p/proj_abc/mp/+

# 单个设备
inteagle/cust_abc123/p/proj_abc/d/dev_001

消息格式

所有消息包含 type 字段区分数据类型：

遥测数据

{
  "type": "telemetry",
  "ts": 1735560000000,
  "payload": {
    "pointId": "point_001",
    "data": {"dx": 0.05, "dy": 0.02}
  }
}

告警

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_001",
    "severity": "alert",
    "status": "ACTIVE_UNACK",
    "originator": {"entityType": "POINT", "id": "point_001"},
    "detail": {"metric": "dx", "value": 12.5, "threshold": 10.0}
  }
}

代码示例

import paho.mqtt.client as mqtt
import json

def on_connect(client, userdata, flags, rc):
    print(f"Connected: {rc}")
    client.subscribe("inteagle/cust_abc123/p/proj_abc/#")

def on_message(client, userdata, msg):
    data = json.loads(msg.payload.decode())
    if data['type'] == 'telemetry':
        print(f"遥测: {data['payload']}")
    elif data['type'] == '3A':
        print(f"告警: {data['payload']['severity']}")

client = mqtt.Client()
client.username_pw_set("cust_abc123", "your_token")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.shm.inteagle.com", 8883)
client.loop_forever()

QoS 建议

2.3.1 - 项目与监测点数据

项目和监测点数据是面向业务的数据视图。

Topic 结构

inteagle/{customerId}/p/{projectId}              # 项目所有数据
inteagle/{customerId}/p/{projectId}/mp/{pointId} # 监测点数据

订阅示例

# 某项目所有数据
inteagle/cust_abc123/p/proj_abc/#

# 某监测点所有数据
inteagle/cust_abc123/p/proj_abc/mp/point_001

# 项目下所有监测点数据
inteagle/cust_abc123/p/proj_abc/mp/+

监测点数据

Topic: inteagle/{customerId}/p/{projectId}/mp/{pointId}

遥测数据

{
  "type": "telemetry",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "POINT",
      "id": "point_001"
    },
    "disp": {
      "dx": 0.05,
      "dy": 0.02,
      "dz": 0.01
    },
    "tilt": 0.5
  }
}

payload 字段说明

注意：监测点名称、项目名称等元数据通过 HTTP API 获取。

常见指标

注意：监测点指标是按需配置的，不同监测点可能包含不同的指标组合。有些数据需要从 设备实体 订阅（如视觉位移计的图片）。

告警数据

告警格式参见 告警消息。

监测点告警示例：

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_20251230_001",
    "alarmType": "DISPLACEMENT_EXCEEDED",
    "severity": "alert",
    "status": "ACTIVE_UNACK",
    "originator": {
      "type": "POINT",
      "id": "point_001"
    },
    "detail": {
      "metric": "dx",
      "value": 12.5,
      "threshold": 10.0,
      "message": "X方向位移超限"
    }
  }
}

设备数据

如需订阅设备原始数据（环境、图像等），请参见 设备数据格式。

2.3.2 - 设备数据格式

设备数据通过 Topic inteagle/{customerId}/p/{projectId}/d/{deviceId} 推送。

通用消息结构

所有 MQTT 消息采用统一的包装结构：

{
  "type": "telemetry | 3A | event | image | attributes",
  "ts": 1735560000000,
  "payload": {
    ...
  }
}

开发者可以统一解析：

const { type, ts, payload } = message;
switch(type) {
  case 'telemetry': handleTelemetry(payload); break;
  case '3A':        handleAlarm(payload); break;
  case 'event':     handleEvent(payload); break;
  case 'image':     handleImage(payload); break;
  case 'attributes': handleAttributes(payload); break;
}

消息类型

告警消息 (3A)

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_20251230_001",
    "alarmType": "LOW_BATTERY",
    "severity": "alarm",
    "status": "ACTIVE_UNACK",
    "originator": {
      "entityType": "DEVICE",
      "id": "dev_001"
    },
    "detail": {
      "metric": "pwr.battery",
      "value": 3.2,
      "threshold": 3.5,
      "message": "电池电压低"
    }
  }
}

payload 字段说明

告警级别 (severity)

告警状态 (status)

事件消息 (event)

事件分为通用事件（所有设备）和设备事件（取决于设备能力）。

{
  "type": "event",
  "ts": 1735560000000,
  "payload": {
    "deviceId": "dev_001",
    "eventType": "DEVICE_ONLINE",
    "data": {}
  }
}

payload 字段说明

通用事件类型

通用事件由平台根据设备连接状态生成，不是设备主动上报的事件。

设备特有事件参见各设备文档。

属性变更消息 (attributes)

{
  "type": "attributes",
  "ts": 1735560000000,
  "payload": {
    "deviceId": "dev_001",
    "data": {
      "firmwareVersion": "2.1.0"
    }
  }
}

2.3.2.1 - VDM 视觉位移计

VDM（Visual Displacement Meter）视觉位移计是 Inteagle 核心监测设备，支持多标靶位移测量。

遥测数据

视觉位移计设备遥测数据包含位移、环境、状态信息：

{
  "type": "telemetry",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "disp": {
      "1": {
        "dx": 0.05,
        "dy": 0.02,
        "dz": 0.01,
        "tilt": 0.05
      },
      "2": {
        "dx": 0.03,
        "dy": 0.01
      }
    },
    "env": {
      "t": 1781686005,
      "temperature": 38.57,
      "humidity": 25.86,
      "pressure": 1002.8
    },
    "status": {
      "signal": {
        "type": "4G",
        "rssi": -75
      },
      "pwr": {
        "battery": 3.7,
        "inputDC": 12.1
      },
      "storage": {
        "percent": 45
      }
    }
  }
}

位移数据 (disp)

环境数据 (env)

部分 VDM 型号支持环境数据采集：

状态数据 (status)

告警

设备告警格式参见 告警消息。

视觉位移计设备告警示例

{
  "type": "3A",
  "ts": 1735560000000,
  "payload": {
    "id": "alm_20251230_001",
    "alarmType": "TARGET_LOST",
    "severity": "alarm",
    "status": "ACTIVE_UNACK",
    "originator": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "detail": {
      "metric": "target_1_status",
      "message": "标靶1丢失"
    }
  }
}

VDM 常见告警类型

事件

事件分为通用事件（所有设备）和设备事件（取决于设备能力）。

通用事件

平台根据设备连接状态为所有设备生成在线/离线状态推送。该事件不是 VDM 设备通过设备直连 MQTT 协议主动上报的消息。

{
  "type": "event",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "eventType": "DEVICE_ONLINE",
    "data": {}
  }
}

视觉位移计设备事件

VDM 特有的事件类型：

{
  "type": "event",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "eventType": "TARGET_LOST",
    "data": {
      "targetId": "1"
    }
  }
}

图像

VDM 支持图像采集，图片分辨率为 640x480：

{
  "type": "image",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "sensorId": 0,
    "trigger": "snapshot",
    "url": "https://storage.inteagle.com/images/...",
    "ttl": 86400
  }
}

触发类型

属性变更

{
  "type": "attributes",
  "ts": 1735560000000,
  "payload": {
    "entity": {
      "type": "DEVICE",
      "id": "dev_001"
    },
    "measureFrequency": 10,
    "irLightEnabled": true
  }
}

VDM 常见属性

2.4 - 数据字典

监测指标

位移类

角度类

环境类

实体类型

告警级别

告警状态

告警类型

监测点告警

设备告警

阈值运算符

时间格式

2.5 - 故障排查

SDK 常见问题

认证失败

可能原因：

• Access Key 或 Secret Key 错误
• 凭证已过期

解决： 确认凭证正确，联系管理员重新获取。

资源不存在 (NotFoundException)

诊断：

// 使用 CLI 验证资源是否存在
shm-cli projects list
shm-cli points list --project PROJECT_ID

请求过频 (RateLimitException)

解决：

try {
    client.telemetry().query(query);
} catch (RateLimitException e) {
    Thread.sleep(e.getRetryAfterMs());
    // 重试
}

MQTT 连接问题

连接失败

诊断：

# 测试端口连通性
openssl s_client -connect broker.shm.inteagle.com:8883

订阅后收不到数据

检查：

1. Topic 格式是否正确：inteagle/{customerId}/p/{projectId}/#
2. 设备是否在线并上报数据
3. 使用通配符 # 测试是否有任何消息

频繁断线

解决：

• Keep Alive 设为 60 秒
• 使用唯一 Client ID
• 实现自动重连逻辑

数据问题

时间戳转换

API 返回毫秒时间戳，转换时需除以 1000：

Instant instant = Instant.ofEpochMilli(ts);
LocalDateTime dateTime = LocalDateTime.ofInstant(instant, ZoneId.systemDefault());

查询不到历史数据

检查：

• 时间范围：endTs > startTs
• 数据点数量限制：单次最多 1000 点
• 监测点是否有数据：先查询最新数据确认

需要帮助？

请联系技术支持。

3 - 设备 API

本章节介绍 Inteagle 支持的设备类型及其技术参数。

设备列表

3.1 - 视觉位移计(VDM)

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

设备连接系统集成商 MQTT Broker，支持 Protobuf（推荐）和 JSON。

快速导航

产品型号

说明：

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

基础知识

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

3.1.1 - 快速入门

本页按“准备设备 → 启动接收端 → 配置设备连接 → 验证数据 → 调用 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

选择数据格式并启动：

• Protobuf（推荐）
• JSON

export VDM_PAYLOAD_FORMAT=protobuf
./run_demo.sh protobuf

export VDM_PAYLOAD_FORMAT=json
./run_demo.sh json

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

3. 让设备连接 Broker

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

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

4. 确认收到位移数据

查看接收程序的输出：

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

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

• Protobuf（推荐）
• JSON

{
  "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、型号、固件版本和测量状态：

看到 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 表示设备已接受确认。完整代码、保存位置与补传方法见 抓拍接入说明。

联调排查

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

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

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

3.1.2 - API 参考

本文按“连接与消息格式 → 主题 → RPC → 遥测 → 告警与抓拍 → 错误码”的顺序组织。接入时先阅读连接参数、RPC 格式和主题结构，再按需要查阅具体接口。

连接参数

快速入门 · 型号支持范围 · GitHub 示例

RPC 格式

RPC 请求发布到 vdm/{deviceId}/rpc/req，响应从 vdm/{deviceId}/rpc/resp 接收。

请求结构：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=1)
request.get_targets.SetInParent()
payload = request.SerializeToString(deterministic=True)

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

调用限制：

• 单个 RPC payload 最大 64 KiB。
• 总 RPC 请求支持短时突发，持续高频请求会返回限流错误。
• 标靶增删改、初始化、启动/停止测量、抓图、重启、补光灯/电机写操作使用更严格限流。
• 集成方收到限流码 4 时，应退避重试，不要立即循环重发。

响应结构：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

response = pb.RpcResponse()
response.ParseFromString(response_payload)  # rpc/resp 收到的 Payload
assert response.schema_version == 1
assert response.req_id == 1
assert response.code == 0
targets = response.get_targets.targets

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

失败响应不携带方法数据；成功且无返回数据时，JSON 省略 data。错误说明见错误码。

请求和响应通过 req_id 关联。同一连接中，尚未收到响应的请求不得复用 req_id；重复 ID 会被拒绝。

主题结构

Protobuf Schema

声明 schema_version 的 V1 根消息必须设置为 1。Python 项目可以直接使用已生成的 pb2 文件 和 package 文件。

完整代码见 GitHub SDK；告警配置运行步骤见 告警接入示例。

公共字段约束

role 枚举含义：

role 使用建议：

• MP 是默认和最常用角色。需要持续输出位移的被测位置，例如梁体、塔体、边坡或结构构件上的监测标靶，通常设置为 MP。
• RP 用作基准点。只有同一视野内存在相对稳定、不随被测体移动的标靶时，才建议设置为 RP；如果现场没有可靠稳定参考点，不要强行设置 RP。
• CP 用作控制点或校核点。通常布置在稳定位置，用来观察安装稳定性、温漂、整体漂移或测量质量；它不是默认的主测点。
• 简单接入或不确定角色时，新增标靶可以不传 role，设备按 MP 处理。

target_id 未设置时，支持自动生成 ID 的接口会由设备生成 UUID；JSON 对应字段为 targetId。

targetModel 枚举含义：

标靶管理 RPC 字段

initRefTargets

对指定标靶执行参考位置初始化/标定。设备会根据保存的标靶配置采集图像并计算初始参考位置；请求中也可以提供 ROI、测量距离、视觉传感器或标靶型号作为本次初始化的覆盖值。调用前应保证 ROI 已对准标靶，且设备没有正在进行其它测量或初始化流程。

标靶增删改请使用 addTargets、setTargets 或 deleteTargets。角色和跳过测量状态使用 addTargets 或 setTargets 配置。

最简请求与带覆盖值的请求：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

minimal = pb.RpcRequest(schema_version=1, req_id=1)
minimal.init_ref_targets.targets.add(target_id="1")
minimal_payload = minimal.SerializeToString(deterministic=True)

request = pb.RpcRequest(schema_version=1, req_id=2)
request.init_ref_targets.targets.add(
    target_id="1",
    sensor_id=0,
    roi=pb.Roi(x=1000, y=500, width=400, height=400),
    distance_m=5.0,
    target_model=pb.TARGET_MODEL_T100,
)
payload = request.SerializeToString(deterministic=True)

{
  "reqId": 1,
  "method": "initRefTargets",
  "params": {
    "targets": [
      {
        "targetId": "1"
      }
    ]
  }
}

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

成功时，RpcResponse.code == 0 且 response.HasField("init_ref_targets")。

成功响应表示设备已启动参考位置初始化任务；最终结果通过 event 主题上报。若至少一个标靶初始化成功，设备会同时通过 attributes 主题上报当前 target_list 摘要，initialized_at_s 为 Unix 秒时间戳。

addTargets

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

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=3)
request.add_targets.targets.add(
    target_id="2",
    sensor_id=0,
    roi=pb.Roi(x=800, y=400, width=400, height=400),
    distance_m=6.0,
    role=pb.TARGET_ROLE_MP,
    target_model=pb.TARGET_MODEL_T100,
    skip_measurement=False,
)
payload = request.SerializeToString(deterministic=True)

# 解析成功响应后读取新增标靶 ID
response = pb.RpcResponse.FromString(response_payload)
added_ids = list(response.add_targets.added_target_ids)

{
  "reqId": 3,
  "method": "addTargets",
  "params": {
    "targets": [
      {
        "targetId": "2",
        "sensorId": 0,
        "roi": {
          "x": 800,
          "y": 400,
          "width": 400,
          "height": 400
        },
        "distance": 6.0,
        "role": "MP",
        "targetModel": "T100",
        "skipMeasurement": false
      }
    ]
  }
}

getTargets

获取当前标靶列表。请求使用 Empty，成功响应返回强类型 TargetInfo：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=4)
request.get_targets.SetInParent()
payload = request.SerializeToString(deterministic=True)

response = pb.RpcResponse.FromString(response_payload)
for target in response.get_targets.targets:
    initialized_at = target.initialized_at_s if target.HasField("initialized_at_s") else None
    print(target.target_id, target.distance_m, target.role, initialized_at)

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

setTargets

按 target_id 修改已有标靶。每个元素除 target_id 外，至少设置 sensor_id、roi、distance_m、role、target_model、skip_measurement 中的一个更新字段。

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=5)
request.set_targets.targets.add(
    target_id="2",
    distance_m=6.5,
    role=pb.TARGET_ROLE_CP,
    target_model=pb.TARGET_MODEL_T200,
    skip_measurement=True,
)
payload = request.SerializeToString(deterministic=True)

{
  "reqId": 5,
  "method": "setTargets",
  "params": {
    "targets": [
      {
        "targetId": "2",
        "distance": 6.5,
        "role": "CP",
        "targetModel": "T200",
        "skipMeasurement": true
      }
    ]
  }
}

成功响应必须设置 response.set_targets；未出现在请求中的 optional 字段不会被修改。

deleteTargets

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=6)
request.delete_targets.target_ids.append("2")
payload = request.SerializeToString(deterministic=True)

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

成功响应必须设置 response.delete_targets。

基础 RPC 字段

getAttr

status 是 measureStatus 的兼容别名。 deviceStatus 是设备整体工作状态，独立于 measureStatus（测量状态）。设备进入低功耗前，JSON 属性上报 "deviceStatus":"Sleeping"；Protobuf 使用 Attributes.device_status = DEVICE_STATUS_SLEEPING。设备唤醒启动后会上报 Idle。deviceStatus 只读，不能通过 setAttr 设置。

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=7)
request.get_attr.keys.extend([
    "deviceId", "deviceStatus", "measureStatus", "sampleFreq", "showROI", "showTs", "showSensorId",
])
payload = request.SerializeToString(deterministic=True)

response = pb.RpcResponse.FromString(response_payload)
attrs = response.get_attr.attributes
print(attrs.device_id, attrs.device_status, attrs.measurement_status, attrs.sample_frequency_hz)

{
  "reqId": 7,
  "method": "getAttr",
  "params": {
    "keys": [
      "deviceId",
      "deviceStatus",
      "measureStatus",
      "sampleFreq",
      "showROI",
      "showTs",
      "showSensorId"
    ]
  }
}

setAttr

target_list 会在标靶配置变化时通过 attributes 主题上报，也可以通过 getTargets 查询；getAttr 不主动返回标靶列表。JSON 对应字段为 targets。

SetAttributesRequest 必须至少设置一个可写字段。设备 ID、型号、固件版本、分辨率、测量状态和标靶列表为只读字段，不能通过 setAttr 修改。

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=8)
request.set_attr.sample_frequency_hz = 5
request.set_attr.report_metrics.values.extend([pb.REPORT_METRIC_DX, pb.REPORT_METRIC_DY])
request.set_attr.show_roi = True
request.set_attr.show_timestamp = True
request.set_attr.show_sensor_id = True
payload = request.SerializeToString(deterministic=True)

{
  "reqId": 8,
  "method": "setAttr",
  "params": {
    "sampleFreq": 5,
    "reportMetrics": [
      "dx",
      "dy"
    ],
    "showROI": true,
    "showTs": true,
    "showSensorId": true
  }
}

syncTime

使用 NTP 同步设备系统时间。同步成功后，设备会保存本次使用的 NTP 服务器配置。

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

default_ntp = pb.RpcRequest(schema_version=1, req_id=9)
default_ntp.sync_time.SetInParent()

request = pb.RpcRequest(schema_version=1, req_id=10)
request.sync_time.ntp_server = "ntp.aliyun.com"
payload = request.SerializeToString(deterministic=True)

{
  "reqId": 9,
  "method": "syncTime",
  "params": {}
}

{
  "reqId": 10,
  "method": "syncTime",
  "params": {
    "ntpServer": "ntp.aliyun.com"
  }
}

如果 NTP 服务器不可达、地址格式不合法或同步失败，设备返回非 0 code。该接口会触发网络同步和本地配置保存，属于受限流保护的写操作。

reboot / startMeasurement / stopMeasurement

这些接口使用 Empty 请求消息：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

start = pb.RpcRequest(schema_version=1, req_id=11)
start.start_measurement.SetInParent()

stop = pb.RpcRequest(schema_version=1, req_id=12)
stop.stop_measurement.SetInParent()

reboot = pb.RpcRequest(schema_version=1, req_id=13)
reboot.reboot.SetInParent()

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

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

{
  "reqId": 13,
  "method": "reboot",
  "params": {}
}

startMeasurement 和 stopMeasurement 会触发 attributes 主题上报 measurement_status；JSON 对应字段为 measureStatus。低功耗休眠前上报独立的 device_status；JSON 对应 deviceStatus。设备断电前的上报是有界尽力发送，没有逐条云端确认；设备离线并不单独证明其处于休眠。reboot 成功后设备会断开并重新连接 MQTT，调用方应等待设备重新上线。

测量控制 RPC 字段

setLightLevel

单灯或所有灯使用统一亮度：

双目设备需要分别设置多路补光灯时，也可以传 lights：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

all_lights = pb.RpcRequest(schema_version=1, req_id=14)
all_lights.set_light_level.all_lights_level = 4

per_light = pb.RpcRequest(schema_version=1, req_id=15)
per_light.set_light_level.per_light.lights.add(light_id=0, level=3)
per_light.set_light_level.per_light.lights.add(light_id=1, level=6)

{
  "reqId": 14,
  "method": "setLightLevel",
  "params": {
    "level": 4
  }
}

{
  "reqId": 15,
  "method": "setLightLevel",
  "params": {
    "lights": [
      {
        "id": 0,
        "level": 3
      },
      {
        "id": 1,
        "level": 6
      }
    ]
  }
}

getLightLevel 使用 Empty 请求；响应通过 WhichOneof("selection") 判断返回统一亮度还是逐灯数组：

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=16)
request.get_light_level.SetInParent()

response = pb.RpcResponse.FromString(response_payload)
selection = response.get_light_level.WhichOneof("selection")

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

snapshot

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

request = pb.RpcRequest(schema_version=1, req_id=17)
request.snapshot.sensor_id = 0
payload = request.SerializeToString(deterministic=True)

{
  "reqId": 17,
  "method": "snapshot",
  "params": {
    "sensorId": 0
  }
}

snapshot RPC 成功响应只表示已触发抓图；JPEG 二进制图片通过 vdm/{deviceId}/image 主题上报。当前标准快照图片由设备侧处理为 640x480。

showROI、showTs 和 showSensorId 控制告警抓拍图像的叠加内容，不影响 snapshot 普通快照。

型号专用 RPC

电机参数见 O1、O2-H、X1和 X2-H；ISP 参数见 X1。

ispCtl

支持 getStatus、setConfig 和 setExposurePreset 三个 action。

setConfig 的曝光时间、增益和旋转角度必须满足型号页面声明的范围；旋转角度只能为 0、90、180 或 270，单相机增益范围为 1024..16384。

ispCtl 成功时只由外层 code=0 表示成功，不重复返回 data.success。按 action 和设备能力，data 只可能包含 vdmModeEnabled、exposureLocked、exposureMode、nrLevel、enable3dnr、maxGain、 exposurePreset、exposureInfo、cameraCount、flip、mirror、rotation、frameWidth 和 frameHeight；exposureInfo 只包含 iso、expTime、aGain、dGain、ispDGain 和 aveLum。操作失败统一通过外层非零 code 返回，不携带 data。

getCruisePaths

getCruisePaths 成功时，JSON data 与 Protobuf get_cruise_paths.data 表示相同的数组结构：

[
  {
    "id": 1,
    "enabled": true,
    "order": 10,
    "cruisePoints": [
      {"id": 1, "targets": ["T01"], "xAngle": 45.0, "yAngle": -5.0}
    ]
  }
]

路径只返回 id、enabled、order、cruisePoints；巡航点只返回 id、targets、 xAngle 和 yAngle。

告警抓拍图像 RPC 字段

仅配置一个已启用的系统集成商 MQTT 连接，且未另行指定或关闭抓拍上传时，设备默认向该连接发送告警抓拍。规则须配置 SNAPSHOT 动作；多个系统集成商 MQTT 连接时需指定接收目标。系统集成商平台校验并保存图像包后调用 ackEvidencePackage 确认。

查看 GitHub 抓拍接收示例 · 查看告警配置示例

告警抓拍图像操作使用对应告警的 eventId。

getEvidenceStatus / retryEvidence

getEvidenceStatus 查询该次告警抓拍图像的处理结果；retryEvidence 请求设备重新发送对应图像包。两者都返回 EvidenceStatusResponse：found=false 表示未找到，found=true 时通过协议字段 evidence 返回 AlarmEvidence。

• Protobuf（推荐）
• JSON

from generated import inteagle_vdm_mqtt_v1_pb2 as pb

status_request = pb.RpcRequest(schema_version=1, req_id=80)
status_request.get_evidence_status.event_id = 9001
status_request.get_evidence_status.kind = pb.EVIDENCE_KIND_SNAPSHOT

retry_request = pb.RpcRequest(schema_version=1, req_id=81)
retry_request.retry_evidence.event_id = 9001
retry_request.retry_evidence.kind = pb.EVIDENCE_KIND_SNAPSHOT

{
  "reqId": 80,
  "method": "getEvidenceStatus",
  "params": {
    "eventId": "9001",
    "kind": "SNAPSHOT"
  }
}

{
  "reqId": 81,
  "method": "retryEvidence",
  "params": {
    "eventId": "9001",
    "kind": "SNAPSHOT"
  }
}

ackEvidencePackage