|
|
@@ -1,8 +1,8 @@
|
|
|
-# Data Collector Gateway HTTP API
|
|
|
+# 汇采调试工具 HTTP API
|
|
|
|
|
|
## 文档用途
|
|
|
|
|
|
-本文档用于说明 Data Collector Gateway 的 HTTP 接口,目标是让 AI 或自动化程序能够根据本文档直接构造请求、理解每个接口的用途、理解每个字段的含义,并正确解析返回结果。
|
|
|
+本文档用于说明汇采调试工具的 HTTP 接口,目标是让 AI 或自动化程序能够根据本文档直接构造请求、理解每个接口的用途、理解每个字段的含义,并正确解析返回结果。
|
|
|
|
|
|
当前接口支持通过 HTTP 调用 Modbus TCP、Siemens S7 TCP 和 BACnet/IP 设备。S7 详细请求和响应约定见 [s7-http-api.md](s7-http-api.md),BACnet 详细请求和响应约定见 [bacnet-http-api.md](bacnet-http-api.md)。
|
|
|
|
|
|
@@ -23,7 +23,7 @@ http://127.0.0.1:8000
|
|
|
示例:
|
|
|
|
|
|
```text
|
|
|
-http://127.0.0.1:8000/api/dc-gateway/modbus/read
|
|
|
+http://127.0.0.1:8000/api/dc-debugtool/modbus/read
|
|
|
```
|
|
|
|
|
|
如果部署到其他服务器,只需要替换服务器请求地址,例如:
|
|
|
@@ -68,7 +68,7 @@ Content-Type: application/json
|
|
|
|
|
|
AI 调用接口时应按以下规则判断结果:
|
|
|
|
|
|
-1. HTTP 请求失败或超时:认为网关服务不可达。
|
|
|
+1. HTTP 请求失败或超时:认为调试工具服务不可达。
|
|
|
2. HTTP 返回成功但 JSON 中 `code = 0`:认为业务调用成功。
|
|
|
3. HTTP 返回成功但 JSON 中 `code != 0`:认为业务调用失败,失败原因读取 `msg`。
|
|
|
|
|
|
@@ -76,15 +76,15 @@ AI 调用接口时应按以下规则判断结果:
|
|
|
|
|
|
| 接口 | 方法 | 路径 | 用途 |
|
|
|
|---|---|---|---|
|
|
|
-| 健康检查 | `GET` | `/api/dc-gateway/health` | 检查网关服务是否存活。 |
|
|
|
-| 原始 Modbus 读取 | `POST` | `/api/dc-gateway/modbus/read` | 读取 Modbus 数据,但不解析为业务值,只返回 Tx/Rx 通信报文。 |
|
|
|
-| 点位读取并转换 | `POST` | `/api/dc-gateway/modbus/read_points` | 按点位定义读取 Modbus 数据,并按数据类型转换为业务值。 |
|
|
|
-| 点位读取并转换别名 | `POST` | `/api/dc-gateway/modbus/read-points` | 与 `/api/dc-gateway/modbus/read_points` 等价,建议优先使用下划线版本。 |
|
|
|
-| 原始 S7 读取 | `POST` | `/api/dc-gateway/s7/read` | 读取 S7 原始字节,只返回语义化 `communication`。 |
|
|
|
-| S7 点位读取并转换 | `POST` | `/api/dc-gateway/s7/read_points` | 按点位定义读取 S7 数据,并按数据类型转换为业务值。 |
|
|
|
-| S7 连接扫描 | `POST` | `/api/dc-gateway/s7/connect_scan` | 传 IP,可选 `device_type`,扫描可用的 `rock`、`slot`、`tsap_conn_type` 组合。 |
|
|
|
-| BACnet 点位读取 | `POST` | `/api/dc-gateway/bacnet/read_points` | 按 BACnet 对象读取 `present-value`。 |
|
|
|
-| BACnet 点位搜索 | `POST` | `/api/dc-gateway/bacnet/search_points` | 读取设备 `object-list`,返回常见点位对象信息和值。 |
|
|
|
+| 健康检查 | `GET` | `/api/dc-debugtool/health` | 检查调试工具服务是否存活。 |
|
|
|
+| 原始 Modbus 读取 | `POST` | `/api/dc-debugtool/modbus/read` | 读取 Modbus 数据,但不解析为业务值,只返回 Tx/Rx 通信报文。 |
|
|
|
+| 点位读取并转换 | `POST` | `/api/dc-debugtool/modbus/read_points` | 按点位定义读取 Modbus 数据,并按数据类型转换为业务值。 |
|
|
|
+| 点位读取并转换别名 | `POST` | `/api/dc-debugtool/modbus/read-points` | 与 `/api/dc-debugtool/modbus/read_points` 等价,建议优先使用下划线版本。 |
|
|
|
+| 原始 S7 读取 | `POST` | `/api/dc-debugtool/s7/read` | 读取 S7 原始字节,只返回语义化 `communication`。 |
|
|
|
+| S7 点位读取并转换 | `POST` | `/api/dc-debugtool/s7/read_points` | 按点位定义读取 S7 数据,并按数据类型转换为业务值。 |
|
|
|
+| S7 连接扫描 | `POST` | `/api/dc-debugtool/s7/connect_scan` | 传 IP,可选 `device_type`,扫描可用的 `rock`、`slot`、`tsap_conn_type` 组合。 |
|
|
|
+| BACnet 点位读取 | `POST` | `/api/dc-debugtool/bacnet/read_points` | 按 BACnet 对象读取 `present-value`。 |
|
|
|
+| BACnet 点位搜索 | `POST` | `/api/dc-debugtool/bacnet/search_points` | 读取设备 `object-list`,返回常见点位对象信息和值。 |
|
|
|
|
|
|
## S7 接口快速说明
|
|
|
|
|
|
@@ -113,7 +113,7 @@ S7 地址字段:
|
|
|
S7 连接扫描接口:
|
|
|
|
|
|
```http
|
|
|
-POST /api/dc-gateway/s7/connect_scan
|
|
|
+POST /api/dc-debugtool/s7/connect_scan
|
|
|
```
|
|
|
|
|
|
请求体:
|
|
|
@@ -193,15 +193,15 @@ BACnet 点位搜索请求示例:
|
|
|
| 字段 | 类型 | 必填 | 默认值 | 允许值或范围 | 含义 |
|
|
|
|---|---|---:|---|---|---|
|
|
|
| `device_type` | string | 否 | `ModbusTCP` | 只能是 `ModbusTCP` | 设备协议类型。当前仅支持 Modbus TCP。 |
|
|
|
-| `ip` | string | 是 | 无 | 合法 IPv4 或 IPv6 地址 | Modbus TCP 设备的 IP 地址,不是网关服务器地址。 |
|
|
|
+| `ip` | string | 是 | 无 | 合法 IPv4 或 IPv6 地址 | Modbus TCP 设备的 IP 地址,不是调试工具服务地址。 |
|
|
|
| `port` | integer | 是 | 无 | `1..65535` | Modbus TCP 设备监听端口。常见端口为 `502`,示例使用 `505`。 |
|
|
|
| `word_byte_order` | string | 否 | `ABCD` | `ABCD`、`BADC`、`CDAB`、`DCBA` | 多寄存器数据的字节序和字序,用于 `int32`、`float32`、`int64`、`float64` 等寄存器值转换。 |
|
|
|
-| `address_base` | integer | 否 | `0` | `>= 0` | 地址偏移量。网关实际发送给 Modbus 协议的地址为 `address + address_base`。通常传 `0`。 |
|
|
|
+| `address_base` | integer | 否 | `0` | `>= 0` | 地址偏移量。调试工具实际发送给 Modbus 协议的地址为 `address + address_base`。通常传 `0`。 |
|
|
|
| `slave_id` | integer | 是 | 无 | `0..247` | Modbus 从站 ID,也称 Unit ID、Device ID 或 Slave Address。 |
|
|
|
|
|
|
### 地址规则
|
|
|
|
|
|
-请求体中的 `address` 是调用方传入的逻辑地址。网关实际发送给 Modbus 协议的地址计算方式如下:
|
|
|
+请求体中的 `address` 是调用方传入的逻辑地址。调试工具实际发送给 Modbus 协议的地址计算方式如下:
|
|
|
|
|
|
```text
|
|
|
protocol_address = address + address_base
|
|
|
@@ -237,7 +237,7 @@ protocol_address = address + address_base
|
|
|
|
|
|
## communication 字段格式
|
|
|
|
|
|
-`communication` 只在 `/api/dc-gateway/modbus/read` 返回,用于记录本次 HTTP 请求期间网关与 Modbus 设备之间的原始通信报文。
|
|
|
+`communication` 只在 `/api/dc-debugtool/modbus/read` 返回,用于记录本次 HTTP 请求期间调试工具与 Modbus 设备之间的原始通信报文。
|
|
|
|
|
|
示例:
|
|
|
|
|
|
@@ -250,8 +250,8 @@ Rx:002-00 00 33 00 00 00 0B 01 03 08 00 01 42 A8 00 00 40 F8
|
|
|
|
|
|
| 片段 | 含义 |
|
|
|
|---|---|
|
|
|
-| `Tx` | 网关发送给 Modbus 设备的 Modbus TCP ADU 报文。 |
|
|
|
-| `Rx` | Modbus 设备返回给网关的 Modbus TCP ADU 报文。 |
|
|
|
+| `Tx` | 调试工具发送给 Modbus 设备的 Modbus TCP ADU 报文。 |
|
|
|
+| `Rx` | Modbus 设备返回给调试工具的 Modbus TCP ADU 报文。 |
|
|
|
| `001`、`002` | 当前 HTTP 请求内的报文序号,从 `001` 开始递增。 |
|
|
|
| `-` 后内容 | 大写十六进制字节,字节之间使用空格分隔。 |
|
|
|
|
|
|
@@ -270,10 +270,10 @@ Rx:002-00 00 33 00 00 00 0B 01 03 08 00 01 42 A8 00 00 40 F8
|
|
|
| 项 | 值 |
|
|
|
|---|---|
|
|
|
| 方法 | `GET` |
|
|
|
-| 路径 | `/api/dc-gateway/health` |
|
|
|
-| 完整地址 | `http://127.0.0.1:8000/api/dc-gateway/health` |
|
|
|
+| 路径 | `/api/dc-debugtool/health` |
|
|
|
+| 完整地址 | `http://127.0.0.1:8000/api/dc-debugtool/health` |
|
|
|
| 请求体 | 无 |
|
|
|
-| 用途 | 判断 Data Collector Gateway HTTP 服务是否启动。 |
|
|
|
+| 用途 | 判断汇采调试工具 HTTP 服务是否启动。 |
|
|
|
|
|
|
### 成功返回
|
|
|
|
|
|
@@ -292,7 +292,7 @@ Rx:002-00 00 33 00 00 00 0B 01 03 08 00 01 42 A8 00 00 40 F8
|
|
|
### 调用示例
|
|
|
|
|
|
```bash
|
|
|
-curl http://127.0.0.1:8000/api/dc-gateway/health
|
|
|
+curl http://127.0.0.1:8000/api/dc-debugtool/health
|
|
|
```
|
|
|
|
|
|
## 接口:原始 Modbus 读取
|
|
|
@@ -302,8 +302,8 @@ curl http://127.0.0.1:8000/api/dc-gateway/health
|
|
|
| 项 | 值 |
|
|
|
|---|---|
|
|
|
| 方法 | `POST` |
|
|
|
-| 路径 | `/api/dc-gateway/modbus/read` |
|
|
|
-| 完整地址 | `http://127.0.0.1:8000/api/dc-gateway/modbus/read` |
|
|
|
+| 路径 | `/api/dc-debugtool/modbus/read` |
|
|
|
+| 完整地址 | `http://127.0.0.1:8000/api/dc-debugtool/modbus/read` |
|
|
|
| Content-Type | `application/json` |
|
|
|
| 用途 | 向 Modbus TCP 设备发起一次读取请求,只返回通信报文,不返回解析后的业务值。 |
|
|
|
|
|
|
@@ -422,7 +422,7 @@ curl http://127.0.0.1:8000/api/dc-gateway/health
|
|
|
### 调用示例
|
|
|
|
|
|
```bash
|
|
|
-curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read \
|
|
|
+curl -X POST http://127.0.0.1:8000/api/dc-debugtool/modbus/read \
|
|
|
-H "Content-Type: application/json" \
|
|
|
-d '{
|
|
|
"device_type": "ModbusTCP",
|
|
|
@@ -446,9 +446,9 @@ curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read \
|
|
|
| 项 | 值 |
|
|
|
|---|---|
|
|
|
| 方法 | `POST` |
|
|
|
-| 推荐路径 | `/api/dc-gateway/modbus/read_points` |
|
|
|
-| 兼容路径 | `/api/dc-gateway/modbus/read-points` |
|
|
|
-| 完整地址 | `http://127.0.0.1:8000/api/dc-gateway/modbus/read_points` |
|
|
|
+| 推荐路径 | `/api/dc-debugtool/modbus/read_points` |
|
|
|
+| 兼容路径 | `/api/dc-debugtool/modbus/read-points` |
|
|
|
+| 完整地址 | `http://127.0.0.1:8000/api/dc-debugtool/modbus/read_points` |
|
|
|
| Content-Type | `application/json` |
|
|
|
| 用途 | 按点位定义逐个读取 Modbus 数据,并把原始 bit/register 转换为 `bool`、`int16`、`float32` 等业务值。 |
|
|
|
|
|
|
@@ -494,7 +494,7 @@ curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read \
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 默认值 | 允许值或范围 | 含义 |
|
|
|
|---|---|---:|---|---|---|
|
|
|
-| `points` | object[] | 是 | 无 | 至少 1 个元素 | 点位读取定义列表。网关会按数组顺序逐个读取。 |
|
|
|
+| `points` | object[] | 是 | 无 | 至少 1 个元素 | 点位读取定义列表。调试工具会按数组顺序逐个读取。 |
|
|
|
| `points[].function_code` | integer | 是 | 无 | `1`、`2`、`3`、`4` | 当前点位使用的 Modbus 功能码。 |
|
|
|
| `points[].address` | integer | 是 | 无 | `>= 0` | 当前点位起始地址。实际协议地址为 `points[].address + address_base`。 |
|
|
|
| `points[].type` | string | 是 | 无 | `bool`、`int16`、`uint16`、`int32`、`uint32`、`int64`、`uint64`、`float32`、`float64` | 当前点位的数据类型。接口会按该类型决定读取寄存器数量和转换方式。输入会被转换为小写。 |
|
|
|
@@ -633,7 +633,7 @@ curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read \
|
|
|
### 调用示例
|
|
|
|
|
|
```bash
|
|
|
-curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read_points \
|
|
|
+curl -X POST http://127.0.0.1:8000/api/dc-debugtool/modbus/read_points \
|
|
|
-H "Content-Type: application/json" \
|
|
|
-d '{
|
|
|
"device_type": "ModbusTCP",
|
|
|
@@ -668,15 +668,15 @@ AI 或自动化程序选择接口时遵循以下规则:
|
|
|
|
|
|
| 目标 | 应调用接口 | 原因 |
|
|
|
|---|---|---|
|
|
|
-| 只想检查网关是否启动 | `GET /api/dc-gateway/health` | 不访问 Modbus 设备,只检查 HTTP 服务。 |
|
|
|
-| 需要查看原始 Modbus Tx/Rx 报文 | `POST /api/dc-gateway/modbus/read` | 返回 `communication`,适合调试通信、对比 Modbus Poll 报文。 |
|
|
|
-| 需要得到点位业务值 | `POST /api/dc-gateway/modbus/read_points` | 返回 `points[].value`,自动按类型转换。 |
|
|
|
+| 只想检查调试工具是否启动 | `GET /api/dc-debugtool/health` | 不访问 Modbus 设备,只检查 HTTP 服务。 |
|
|
|
+| 需要查看原始 Modbus Tx/Rx 报文 | `POST /api/dc-debugtool/modbus/read` | 返回 `communication`,适合调试通信、对比 Modbus Poll 报文。 |
|
|
|
+| 需要得到点位业务值 | `POST /api/dc-debugtool/modbus/read_points` | 返回 `points[].value`,自动按类型转换。 |
|
|
|
|
|
|
AI 构造请求时必须区分两个地址:
|
|
|
|
|
|
| 地址 | 字段或配置 | 含义 |
|
|
|
|---|---|---|
|
|
|
-| 网关服务器地址 | `http://127.0.0.1:8000` | HTTP API 服务地址,用于拼接请求 URL。 |
|
|
|
+| 调试工具服务地址 | `http://127.0.0.1:8000` | HTTP API 服务地址,用于拼接请求 URL。 |
|
|
|
| Modbus 设备地址 | 请求体 `ip` 和 `port` | 实际被读取的 Modbus TCP 设备地址。 |
|
|
|
|
|
|
AI 构造 `/modbus/read_points` 点位时应按以下步骤:
|