1. 采集网关接口说明

当前接口仅支持通过 HTTP 调用 Modbus TCP 设备，暂不支持 Modbus RTU 或其他设备类型

采集网关服务器请求地址

http://127.0.0.1:8000

接口完整请求地址拼接规则：

完整请求地址 = 服务器请求地址 + 接口路径

示例：

http://127.0.0.1:8000/api/dc-gateway/modbus/read

通用约定

请求格式

所有 POST 接口都使用 JSON 请求体，并且请求头必须包含：

Content-Type: application/json

返回格式

除健康检查外，业务接口统一返回以下 JSON 结构：

{
  "code": 0,
  "msg": "success",
  "data": {}
}

字段说明：

字段	类型	必定返回	含义
`code`	integer	是	业务状态码。`0` 表示成功，`1` 表示失败。调用方应优先用该字段判断业务是否成功。
`msg`	string	是	业务消息。成功时通常为 `success`，失败时为错误原因。
`data`	object	是	业务数据对象。不同接口的字段不同。

HTTP 状态码说明

接口校验失败、设备连接失败、Modbus 通信失败时，通常仍返回 HTTP 200，业务是否成功由响应体中的 code 判断。

AI 调用接口时应按以下规则判断结果：

HTTP 请求失败或超时：认为网关服务不可达。
HTTP 返回成功但 JSON 中 code = 0：认为业务调用成功。
HTTP 返回成功但 JSON 中 code != 0：认为业务调用失败，失败原因读取 msg。

接口列表

接口	方法	路径	用途
健康检查	`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` 等价，建议优先使用下划线版本。

通用设备字段

以下字段用于描述要连接的 Modbus TCP 设备，出现在 /modbus/read 和 /modbus/read_points 请求体的顶层。

字段	类型	必填	默认值	允许值或范围	含义
`device_type`	string	否	`ModbusTCP`	只能是 `ModbusTCP`	设备协议类型。当前仅支持 Modbus TCP。
`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`。
`slave_id`	integer	是	无	`0..247`	Modbus 从站 ID，也称 Unit ID、Device ID 或 Slave Address。

地址规则

请求体中的 address 是调用方传入的逻辑地址。网关实际发送给 Modbus 协议的地址计算方式如下：

protocol_address = address + address_base

如果设备文档给出的地址已经是从 0 开始的协议地址，则使用：

"address_base": 0

如果设备文档用 40001 表示第一个保持寄存器，调用方需要先换算为协议地址 0，再请求接口。不要直接把 40001 当作 address 传入，除非明确需要这种偏移行为。

word_byte_order 说明

word_byte_order 用于寄存器型多字节数据的转换。每个 Modbus 寄存器为 2 字节。

值	含义
`ABCD`	默认顺序。寄存器内字节不反转，寄存器顺序不反转。
`BADC`	每个寄存器内的两个字节反转，寄存器顺序不反转。
`CDAB`	寄存器顺序反转，寄存器内字节不反转。
`DCBA`	每个寄存器内字节反转，同时寄存器顺序反转。

Modbus 功能码

`function_code`	Modbus 名称	读取对象	返回原始类型	点位类型限制
`1`	Read Coils	线圈	bit/boolean	`/read_points` 中只能使用 `bool`。
`2`	Read Discrete Inputs	离散输入	bit/boolean	`/read_points` 中只能使用 `bool`。
`3`	Read Holding Registers	保持寄存器	16 位 register	可使用寄存器型数据类型，也可使用 `bool` 读取寄存器整体或指定位。
`4`	Read Input Registers	输入寄存器	16 位 register	可使用寄存器型数据类型，也可使用 `bool` 读取寄存器整体或指定位。

communication 字段格式

communication 只在 /api/dc-gateway/modbus/read 返回，用于记录本次 HTTP 请求期间网关与 Modbus 设备之间的原始通信报文。

示例：

Tx:001-00 00 33 00 00 00 06 01 03 00 00 00 04
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 报文。
`001`、`002`	当前 HTTP 请求内的报文序号，从 `001` 开始递增。
`-` 后内容	大写十六进制字节，字节之间使用空格分隔。

补充说明：

规则	说明
trace 隔离	每个 HTTP 请求都有独立的 trace，并发请求不会互相清空或串包。
重试报文	如果底层 Modbus 客户端发生重试，`communication` 中可能出现多组 `Tx` 或 `Rx`。
失败场景	如果设备无响应，可能只有 `Tx` 没有 `Rx`。

接口：健康检查

基本信息

项	值
方法	`GET`
路径	`/api/dc-gateway/health`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/health`
请求体	无
用途	判断 Data Collector Gateway HTTP 服务是否启动。

成功返回

{
  "status": "ok"
}

返回字段说明：

字段	类型	含义
`status`	string	服务状态。`ok` 表示 HTTP 服务存活。

调用示例

curl http://127.0.0.1:8000/api/dc-gateway/health

接口：原始 Modbus 读取

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/modbus/read`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/modbus/read`
Content-Type	`application/json`
用途	向 Modbus TCP 设备发起一次读取请求，只返回通信报文，不返回解析后的业务值。

请求体结构

{
  "device_type": "ModbusTCP",
  "ip": "192.168.75.240",
  "port": 505,
  "word_byte_order": "ABCD",
  "address_base": 0,
  "slave_id": 1,
  "read": {
    "function_code": 3,
    "address": 0,
    "quantity": 4
  }
}

顶层字段说明见“通用设备字段”。

read 字段说明：

字段	类型	必填	默认值	允许值或范围	含义
`read`	object	是	无	对象	本次读取的参数对象。
`read.function_code`	integer	是	无	`1`、`2`、`3`、`4`	Modbus 功能码，决定读取线圈、离散输入、保持寄存器或输入寄存器。
`read.address`	integer	是	无	`>= 0`	起始地址。实际协议地址为 `read.address + address_base`。
`read.quantity`	integer	是	无	`1..125`	读取数量。功能码 `1`、`2` 表示读取 bit 数量；功能码 `3`、`4` 表示读取 register 数量。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "communication": [
      "Tx:001-00 00 33 00 00 00 06 01 03 00 00 00 04",
      "Rx:002-00 00 33 00 00 00 0B 01 03 08 00 01 42 A8 00 00 40 F8"
    ]
  }
}

成功返回字段说明：

字段	类型	含义
`code`	integer	`0` 表示读取成功。
`msg`	string	成功时为 `success`。
`data.device`	object	本次请求实际使用的设备连接参数。
`data.device.device_type`	string	设备类型，当前固定为 `ModbusTCP`。
`data.device.ip`	string	目标 Modbus 设备 IP。
`data.device.port`	integer	目标 Modbus 设备端口。
`data.device.word_byte_order`	string	本次请求使用的字节序设置。原始读取不解析值，但仍会回显该参数。
`data.device.address_base`	integer	本次请求使用的地址偏移。
`data.device.slave_id`	integer	本次请求使用的 Modbus 从站 ID。
`data.communication`	string[]	本次 Modbus TCP 原始 Tx/Rx 报文列表。

失败返回示例

设备无响应或通信失败：

{
  "code": 1,
  "msg": "Modbus Error: [Input/Output] No response received after 3 retries, continue with next request",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "communication": [
      "Tx:001-00 00 33 00 00 00 06 01 03 00 00 00 04"
    ]
  }
}

请求字段校验失败：

{
  "code": 1,
  "msg": "read.quantity: Input should be less than or equal to 125",
  "data": {
    "communication": []
  }
}

失败返回字段说明：

字段	类型	含义
`code`	integer	`1` 表示失败。
`msg`	string	失败原因，可能是连接失败、Modbus 错误或请求字段校验错误。
`data.device`	object	如果请求已经通过基础校验，通常会回显设备参数。
`data.communication`	string[]	失败前已经捕获到的通信报文。字段校验失败时通常为空数组。

调用示例

curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read \
  -H "Content-Type: application/json" \
  -d '{
    "device_type": "ModbusTCP",
    "ip": "192.168.75.240",
    "port": 505,
    "word_byte_order": "ABCD",
    "address_base": 0,
    "slave_id": 1,
    "read": {
      "function_code": 3,
      "address": 0,
      "quantity": 4
    }
  }'

接口：点位读取并转换

基本信息

项	值
方法	`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`
Content-Type	`application/json`
用途	按点位定义逐个读取 Modbus 数据，并把原始 bit/register 转换为 `bool`、`int16`、`float32` 等业务值。

请求体结构

{
  "device_type": "ModbusTCP",
  "ip": "192.168.75.240",
  "port": 505,
  "word_byte_order": "ABCD",
  "address_base": 0,
  "slave_id": 1,
  "points": [
    {
      "function_code": 3,
      "address": 7,
      "type": "int16"
    },
    {
      "function_code": 3,
      "address": 1,
      "type": "float32"
    },
    {
      "function_code": 3,
      "address": 10,
      "type": "bool",
      "bit": 2
    },
    {
      "function_code": 1,
      "address": 0,
      "type": "bool"
    }
  ]
}

顶层字段说明见“通用设备字段”。

points 字段说明：

字段	类型	必填	默认值	允许值或范围	含义
`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`	当前点位的数据类型。接口会按该类型决定读取寄存器数量和转换方式。输入会被转换为小写。
`points[].bit`	integer 或 null	否	`null`	`0..15`	仅寄存器点位支持。用于从一个 16 位寄存器中取某一位并返回布尔值。功能码 `1`、`2` 不允许传 `bit`。

点位类型和读取长度

`type`	读取长度	可用功能码	返回 JSON 类型	含义
`bool`	功能码 `1`、`2` 为 1 bit；功能码 `3`、`4` 为 1 register	`1`、`2`、`3`、`4`	boolean	布尔值。寄存器点位未传 `bit` 时，寄存器值非 `0` 返回 `true`；传 `bit` 时读取指定位。
`int16`	1 register	`3`、`4`	integer	有符号 16 位整数。
`uint16`	1 register	`3`、`4`	integer	无符号 16 位整数。
`int32`	2 registers	`3`、`4`	integer	有符号 32 位整数。
`uint32`	2 registers	`3`、`4`	integer	无符号 32 位整数。
`float32`	2 registers	`3`、`4`	number	IEEE 754 单精度浮点数。
`int64`	4 registers	`3`、`4`	integer	有符号 64 位整数。
`uint64`	4 registers	`3`、`4`	integer	无符号 64 位整数。
`float64`	4 registers	`3`、`4`	number	IEEE 754 双精度浮点数。

点位校验规则

规则	说明
`function_code` 必须合法	只能是 `1`、`2`、`3`、`4`。
线圈和离散输入只能读布尔值	当 `function_code` 为 `1` 或 `2` 时，`type` 必须是 `bool`。
线圈和离散输入不能使用 `bit`	当 `function_code` 为 `1` 或 `2` 时，不能传 `bit`。
寄存器点位可以使用 `bit`	当 `function_code` 为 `3` 或 `4` 且 `type` 为 `bool` 时，可用 `bit` 读取寄存器指定位。
不允许额外字段	请求对象中出现未定义字段会校验失败。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "points": [
      {
        "function_code": 3,
        "address": 7,
        "type": "int16",
        "value": -321
      },
      {
        "function_code": 3,
        "address": 10,
        "type": "bool",
        "bit": 2,
        "value": true
      }
    ]
  }
}

成功返回字段说明：

字段	类型	含义
`code`	integer	`0` 表示所有点位读取和转换成功。
`msg`	string	成功时为 `success`。
`data.device`	object	本次请求实际使用的设备连接参数。
`data.points`	object[]	点位读取结果数组，顺序与请求体 `points` 一致。
`data.points[].function_code`	integer	该点位使用的 Modbus 功能码。
`data.points[].address`	integer	该点位请求中的逻辑地址，不包含 `address_base` 偏移。
`data.points[].type`	string	该点位的数据类型，返回为小写。
`data.points[].bit`	integer	仅当请求点位传入 `bit` 时返回。
`data.points[].value`	boolean、integer 或 number	转换后的点位值。具体 JSON 类型由 `type` 决定。

失败返回示例

设备连接失败：

{
  "code": 1,
  "msg": "failed to connect to 192.168.75.240:505",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "points": []
  }
}

读取部分点位后失败：

{
  "code": 1,
  "msg": "Modbus Error: [Input/Output] No response received after 3 retries, continue with next request",
  "data": {
    "device": {
      "device_type": "ModbusTCP",
      "ip": "192.168.75.240",
      "port": 505,
      "word_byte_order": "ABCD",
      "address_base": 0,
      "slave_id": 1
    },
    "points": [
      {
        "function_code": 3,
        "address": 7,
        "type": "int16",
        "value": -321
      }
    ]
  }
}

失败返回字段说明：

字段	类型	含义
`code`	integer	`1` 表示失败。
`msg`	string	失败原因，可能是连接失败、Modbus 错误或请求字段校验错误。
`data.device`	object	如果请求已经通过基础校验，通常会回显设备参数。
`data.points`	object[]	失败前已成功读取的点位。字段校验失败或连接失败时通常为空数组。

调用示例

curl -X POST http://127.0.0.1:8000/api/dc-gateway/modbus/read_points \
  -H "Content-Type: application/json" \
  -d '{
    "device_type": "ModbusTCP",
    "ip": "192.168.75.240",
    "port": 505,
    "word_byte_order": "ABCD",
    "address_base": 0,
    "slave_id": 1,
    "points": [
      {
        "function_code": 3,
        "address": 7,
        "type": "int16"
      },
      {
        "function_code": 3,
        "address": 1,
        "type": "float32"
      },
      {
        "function_code": 1,
        "address": 0,
        "type": "bool"
      }
    ]
  }'

AI 调用决策指南

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`，自动按类型转换。

AI 构造请求时必须区分两个地址：

地址	字段或配置	含义
网关服务器地址	`http://127.0.0.1:8000`	HTTP API 服务地址，用于拼接请求 URL。
Modbus 设备地址	请求体 `ip` 和 `port`	实际被读取的 Modbus TCP 设备地址。

AI 构造 /modbus/read_points 点位时应按以下步骤：

根据设备点表选择 function_code。
将设备点表地址换算为从 0 开始的 Modbus 协议地址，填入 address。
如果需要统一偏移，再设置 address_base，否则保持 0。
根据点位数据类型设置 type。
如果读取保持寄存器或输入寄存器中的某一位，设置 type 为 bool 并填写 bit。
发送请求后检查响应体 code，不要只检查 HTTP 状态码。

2. 模方登录接口

登录接口请求地址

http://192.168.75.110:32080/api/ai/auth/password_login

请求入参

{
"username":"dataturing",
"password":"123456"
}

响应格式

{
"errcode": 0,
"msg": "成功",
"token": "MTc4MTU3NjM4NDsxNzgxNTgzNTg0OzY7ZThLU2hySEFnbTtkZTY0OWI2YzNjMmYyOTNj",
"token_expire_time": 1781583584,
"user_id": 6,
"name": "Dataturing",
"username": "dataturing",
"permissions": [
		...
]
}

3. 汇采接口

前置说明

服务器地址

http://192.168.75.110:32080

通用约定

请求方式：POST
请求体：application/json
成功响应通常使用 HTTP 200，并通过 JSON 中的 state 判断业务结果。
创建设备成功响应：{"state":0,"state_info":"成功"}；创建点位接口成功时返回 {"state":0,"state_info":"成功"}。
通用参数错误：{"state":2,"state_info":"无效参数"}。

注意

在调用汇采接口前请先调用模方登录接口获取token，获取token后放入请求头Header的Authorization字段

示例
```
header = {
	"Authorization": "TOKEN"
}
```

Modbus 创建设备与创建点位接口文档

枚举汇总

Modbus 设备连接类型 device_type

device_type 是通用创建设备接口中 Modbus 连接类型的 JSON 字段名。

值	含义	连接 URL 形态	必填关联字段
1	TCP	`tcp://{ip}:{port}`	`ip`、`port`
2	RTU	`rtu://{serial_port}`	`serial_port`
3	UDP	`udp://{ip}:{port}`	`ip`、`port`
4	RTU OVER TCP	`rtuovertcp://{ip}:{port}`	`ip`、`port`
5	RTU OVER UDP	`rtuoverudp://{ip}:{port}`	`ip`、`port`

说明：当前创建 Modbus 设备应使用通用 POST /api/collector/device。其中 type 传协议字符串 modbus，device_type 传上表的连接类型。传 device_type=0 会导致创建设备失败。

串口校验位 parity

值	含义	代码常量
1	Even，偶校验	`ModbusDeviceParityEven`
2	None，无校验	`ModbusDeviceParityNone`
3	Odd，奇校验	`ModbusDeviceParityOdd`

说明：当前 Parity() 转换函数中，除 2、3 外都会按 Even 处理；即 0 也会被当作 Even 传给底层 Modbus 客户端。

字节序 byte_order

值	含义	代码常量
1	Big Endian，大端字节序	`ModbusDeviceByteOrderBigEndian`
2	Small Endian，小端字节序	`ModbusDeviceByteOrderSmallEndian`

字序 word_order

值	含义	代码常量
1	Big Endian，大端字序	`ModbusDeviceWordOrderBigEndian`
2	Small Endian，小端字序	`ModbusDeviceWordOrderSmallEndian`

数据位 data_bit

值	含义
5	5 个数据位
6	6 个数据位
7	7 个数据位
8	8 个数据位，常用值

停止位 stop_bit

值	含义
1	1 个停止位
2	2 个停止位

Modbus 功能码 func_code

值	含义	读操作	数据区
1	Coil	Read Coils	线圈
2	Discrete Input	Read Discrete Inputs	离散输入
3	Holding Register	Read Holding Registers	保持寄存器
4	Input Register	Read Input Registers	输入寄存器

点位数据类型 type

创建点位接口中的 type 是字符串，表示点位数据类型。

值	含义	占用寄存器数量
`bool`	布尔值	1
`int16`	16 位有符号整数	1
`uint16`	16 位无符号整数	1
`int32`	32 位有符号整数	2
`uint32`	32 位无符号整数	2
`float32`	32 位浮点数	2
`int64`	64 位有符号整数	4
`uint64`	64 位无符号整数	4
`float64`	64 位浮点数	4

说明：func_code 为 1 或 2 时采集结果按布尔/0-1 处理；func_code 为 3 或 4 且 type=bool 时会从寄存器中按 bit 取某一位。

状态枚举

接口创建时会写入初始状态，调用方通常不需要传。

字段	值	含义
设备 `status`	1	disconnected，未连接
设备 `status`	2	connected，已连接
设备 `status`	3	error，异常
设备 `running_status`	0	idle，未采集
设备 `running_status`	1	running，采集中
设备 `running_status`	2	error，运行异常
点位 `status`	0	idle，未采集
点位 `status`	1	working，采集正常
点位 `status`	2	error，采集异常

1. 创建设备

基本信息

URL：/api/collector/device
方法：POST

请求字段

字段	类型	必填	默认/行为	含义
`type`	string	是	无默认值	设备协议类型。创建 Modbus 设备固定传 `"modbus"`。缺失会在转换设备对象时失败。
`name`	string	是	未显式 trim	设备名称。
`device_type`	int	是	缺失时为 `0`，会导致创建失败	Modbus 连接类型，见 `device_type` 枚举。
`ip`	string	TCP/UDP 类连接必填	缺失时为空字符串	设备 IP。`device_type` 为 1、3、4、5 时用于组装连接 URL。
`port`	int	TCP/UDP 类连接必填	缺失时为 `0`	设备端口。`device_type` 为 1、3、4、5 时用于组装连接 URL。
`slave_id`	int	建议必填	缺失时为 `0`	Modbus 从站 ID/Unit ID。采集时会设置到底层客户端，通常取值 `0` 到 `255`。
`serial_port`	string	RTU 必填	缺失时为空字符串	串口名。`device_type=2` 时用于组装 `rtu://{serial_port}`。
`timeout`	int	否	缺失时为 `3`	超时时间，单位秒。
`byte_order`	int	建议必填	缺失时为 `0`，底层编码设置可能失败	字节序，见 `byte_order` 枚举；创建时会调用底层 `SetEncoding`。
`word_order`	int	建议必填	缺失时为 `0`，底层编码设置可能失败	字序，见 `word_order` 枚举；创建时会调用底层 `SetEncoding`。
`is_persistent`	bool	否	缺失时为 `false`	是否持久化/持久设备标记，写入设备 `is_persistent`。
`baud_rate`	int	RTU 建议必填	缺失时为 `0`	串口波特率，例如 `9600`。
`data_bit`	int	RTU 建议必填	缺失时为 `0`	串口数据位，见 `data_bit` 枚举。
`parity`	int	RTU 建议必填	传 `0` 会按 Even 转换	串口校验位，见 `parity` 枚举。
`stop_bit`	int	RTU 建议必填	缺失时为 `0`	串口停止位，见 `stop_bit` 枚举。
`mode`	int	否	缺失时为 `0`	模式字段。当前创建、连接和采集逻辑只保存该字段，未参与连接 URL 生成和读写。
`address_offset`	int	否	缺失时为 `0`	地址偏移。实际读点时使用 `点位 address - address_offset` 作为 Modbus 读取地址。
`retry_times`	int	否	缺失时为 `0`	读取失败重试次数。小于 0 时部分流程会按 0 处理。
`group_id`	int	否	缺失时为 `0`	父设备分组 ID。`0` 表示顶层设备。
`sort_index`	int	否	缺失时为 `0`	设备排序序号。
`alarm_interval`	int	否	缺失时为 `0`	告警间隔。
`collect_interval`	int	否	缺失时为 `0`	采集周期。

请求示例：Modbus TCP

{
  "name": "modbus_tcp_1",
  "type": "modbus",
  "device_type": 1,
  "ip": "127.0.0.1",
  "port": 5502,
  "slave_id": 1,
  "timeout": 3,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 0,
  "address_offset": 0,
  "retry_times": 0
}

请求示例：Modbus RTU

{
  "name": "modbus_rtu_1",
  "type": "modbus",
  "device_type": 2,
  "serial_port": "COM3",
  "slave_id": 1,
  "timeout": 3,
  "baud_rate": 9600,
  "data_bit": 8,
  "parity": 2,
  "stop_bit": 1,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 0,
  "address_offset": 0,
  "retry_times": 0
}

成功响应

{
  "state": 0,
  "state_info": "成功"
}

主要失败响应

场景	响应
Query 绑定失败、JSON 绑定失败、`type` 缺失、连接类型无效、底层客户端初始化失败、数据库写入失败等	`{"state":2,"state_info":"失败"}`

2. 创建采集点位

基本信息

URL：/api/collector/modbus/point/add_collect_point
方法：POST
处理函数：modbusPointAdd
请求结构：ReqModbusPointAdd

请求字段

字段	类型	必填	默认/行为	含义
`name`	string	是	会 `strings.TrimSpace`；trim 后为空会返回 `名称不能为空`	点位名称。
`point_id`	string	否	空字符串允许	外部点位标识。非空时，同一设备下不能重复。采集写入 `PointData.PointId` 使用该字段。
`device_id`	int	是	无默认值	所属 Modbus 设备 ID。接口会查询设备是否存在，找不到返回 `设备ID不合法`。
`scale_ratio`	float64	是	无默认值	缩放系数。寄存器数值采集时先乘以该系数。Go binding 的 `required` 对数字零值敏感，建议传非 0，常用 `1`。
`value_offset`	float64	否	Go 零值 `0`	值偏移。寄存器采集结果乘 `scale_ratio` 后再加该偏移。
`describe`	string	否	空字符串	点位描述，保存到 `description`。
`invalid_values`	string	否	空字符串解析为空数组	无效值列表，逗号分隔，例如 `"-9999,9999"`。接口会逐项解析为 float64，无法解析则返回无效参数。
`valid_range_start`	number/null	否	`null`	合法范围最小值。采集值小于该值时跳过写入。
`valid_range_end`	number/null	否	`null`	合法范围最大值。采集值大于该值时跳过写入。
`type`	string	否，但采集必须有效	无显式默认值	点位数据类型，见数据类型枚举。字段名与创建设备的 `type` 不同语义。
`address`	int	是	Go 零值 `0`	Modbus 地址。实际读取地址为 `address - 设备 address_offset`。
`func_code`	int	是	Go 零值 `0` 会导致后续采集功能码无效	Modbus 功能码，见 `func_code` 枚举。
`group_id`	int	否	Go 零值 `0`	点位分组 ID；`0` 表示不归属具体分组或默认分组。
`bit`	int	`type=bool` 且读寄存器时需要	Go 零值 `0`	位下标。`func_code=3/4` 且 `type=bool` 时，从寄存器值中取 `(value >> bit) & 1`。建议范围 `0` 到 `15`。

请求示例：保持寄存器 uint16

{
  "device_id": 1,
  "name": "holding_register_uint16",
  "point_id": "HR_UINT16",
  "describe": "保持寄存器 uint16 示例",
  "func_code": 3,
  "address": 10,
  "type": "uint16",
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null,
  "bit": 0
}

请求示例：寄存器位点 bool

{
  "device_id": 1,
  "name": "alarm_bit_3",
  "point_id": "ALARM_BIT_3",
  "describe": "保持寄存器第 3 位报警",
  "func_code": 3,
  "address": 20,
  "type": "bool",
  "bit": 3,
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}

请求示例：线圈点位

{
  "device_id": 1,
  "name": "coil_1",
  "point_id": "COIL_1",
  "describe": "线圈 1",
  "func_code": 1,
  "address": 1,
  "type": "bool",
  "scale_ratio": 1,
  "value_offset": 0,
  "group_id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null,
  "bit": 0
}

成功响应

{
  "state": 0,
  "state_info": "成功",
  "data": null
}

主要失败响应

场景	响应
JSON 绑定失败、`scale_ratio` 缺失或为零等	`{"state":2,"state_info":"无效参数"}`
`invalid_values` 中存在非数字项	`{"state":2,"state_info":"无效参数"}`
查询设备失败	`{"state":2,"state_info":"检测设备ID失败"}`
设备不存在	`{"state":2,"state_info":"设备ID不合法"}`
`name` trim 后为空	`{"state":2,"state_info":"名称不能为空"}`
同一设备下 `point_id` 重复	`{"state":2,"state_info":"point_id 重复, point_id: {point_id}"}`
数据库插入失败	`{"state":2,"state_info":"新增失败"}`

查询设备列表接口

基本信息

URL：/api/collector/device
方法：`GET
请求参数位置：Query String
普通响应类型：JSON
主要用途：查询当前采集器内存中的设备列表，并按设备分组、点位分组组织成树形结构。

请求参数

参数	类型	必填	默认值	含义
`num_points`	bool	否	`false`	是否统计设备或点位分组下的点位数量。为 `true` 时返回对象中的 `num_points` 有实际统计值。
`format`	string	否	空	返回格式。普通 JSON 列表不传；传 `xlsx` 时进入导出逻辑，返回 zip/xlsx 文件流。
`id`	int[]	否	空数组	仅 `format=xlsx` 时使用，指定要导出的设备 ID。可重复传参：`id=1&id=2`。普通 JSON 列表模式不使用。
`group_id`	int[]	否	空数组	仅 `format=xlsx` 时使用，指定要导出的设备分组 ID。可重复传参：`group_id=10&group_id=11`。普通 JSON 列表模式不使用。
`bacnet_lan`	bool	否	`false`	为 `true` 时执行 BACnet Who-Is 扫描并返回扫描到的 BACnet 设备，不走普通设备树列表逻辑。
`batch`	bool	否	`false`	当前 GET 普通列表逻辑未使用该参数。
`buffer`	bool	否	`false`	当前 GET 普通列表逻辑未使用该参数；POST 导入场景使用。

请求示例

查询普通设备树

GET /api/collector/device

查询设备树并统计点位数量

GET /api/collector/device?num_points=true

响应示例

{
  "state": 0,
  "state_info": "",
  "devices": [
    {
      "id": 10,
      "name": "现场设备分组",
      "type": "devicegroup",
      "created_time": "2026-06-16T10:00:00+08:00",
      "updated_time": "2026-06-16T10:00:00+08:00",
      "sort_index": 0,
      "group_id": 0,
      "num_points": 0,
      "groups": [
        {
          "id": 1,
          "name": "modbus_tcp_1",
          "type": "modbus",
          "created_time": "2026-06-16T10:01:00+08:00",
          "updated_time": "2026-06-16T10:01:00+08:00",
          "sort_index": 0,
          "group_id": 10,
          "alarm_interval": 0,
          "collect_interval": 0,
          "status": 1,
          "running_status": 0,
          "connect_status": 0,
          "is_persistent": true,
          "device_type": 1,
          "ip": "127.0.0.1",
          "port": 5502,
          "slave_id": 1,
          "byte_order": 1,
          "word_order": 1,
          "timeout": 3,
          "address_offset": 0,
          "retry_times": 0,
          "num_points": 3,
          "groups": [
            {
              "id": 100,
              "name": "默认点位分组",
              "type": "pointgroup",
              "created_time": "2026-06-16T10:02:00+08:00",
              "sort_index": 0,
              "group_collect": false,
              "num_points": 3
            }
          ]
        }
      ]
    }
  ],
  "refresh_msg": ""
}

响应字段说明

字段	类型	含义
`state`	int	业务状态码。成功时为 `0`；绑定 query 失败时返回失败响应。
`state_info`	string	状态描述。普通成功列表当前为空字符串。
`devices`	array	顶层设备或设备分组列表。只包含 `group_id=0` 的顶层对象，其子节点在 `groups` 内。
`refresh_msg`	string	刷新消息字段，当前普通列表逻辑通常为空字符串。

失败响应示例：

{
  "state": 500,
  "state_info": "失败"
}

devices[] / groups[] 对象通用字段

返回对象使用同一个结构 DeviceOrGroup 表示设备、设备分组和点位分组。不同 type 会返回不同字段；带 omitempty 的字段在无值时可能不出现。

字段	类型	适用对象	含义
`id`	int	全部	对象 ID。设备/设备分组来自设备表 ID；点位分组来自点位分组 ID。
`name`	string	全部	名称。
`type`	string	全部	对象类型或协议类型，见设备类型枚举。
`created_time`	string	全部	创建时间，RFC3339/Go JSON time 格式。
`updated_time`	string	设备/设备分组	更新时间。点位分组一般不返回。
`sort_index`	int	全部	排序序号，数值越小越靠前。
`group_id`	int	设备/设备分组	父设备分组 ID。顶层对象为 `0`。点位分组对象通常不返回该字段。
`alarm_interval`	int	设备	告警间隔，来自设备内部配置。
`collect_interval`	int	设备	采集周期，来自设备内部配置。
`operation_time`	string/null	设备	最近一次设备操作时间，例如连接、采集、断开。
`operation_flag`	string	设备	最近一次设备操作标记，见操作标记枚举。
`buffer_id`	string	导入缓冲对象/设备	导入缓冲 ID。普通已保存设备通常为空字符串但可能仍返回。
`group_collect`	bool	点位分组	点位分组是否按组采集。设备对象该字段通常为 `false`。
`num_points`	int	设备/点位分组	点位数量。受 `num_points` query 参数影响。
`status`	int	设备	设备连接状态，见设备 `status` 枚举。
`running_status`	int	设备	设备运行/采集状态，见 `running_status` 枚举。
`connect_status`	int	设备	最近连接状态，见 `connect_status` 枚举。
`is_persistent`	bool	设备	是否持久化设备。
`next_reconnect_time`	string	设备	下次重连时间。
`groups`	array	设备/设备分组	子节点列表，包含点位分组和子设备/子设备分组。

注意事项

该接口普通 JSON 模式不支持分页、关键字搜索或按协议过滤。
返回数据来自运行时内存中的设备集合，不是每次直接查询数据库。
groups 字段同时承载设备分组子设备和点位分组，需要通过子节点 type 区分。
format=xlsx 时响应不是 JSON，而是 application/octet-stream 文件下载。
bacnet_lan=true 时响应是 BACnet Who-Is 扫描结果，不包含普通设备树中的点位分组结构。
当前普通列表可能返回 password、auth_pwd、priv_pwd 等敏感字段，调用方展示或日志记录时需要注意脱敏。

接口汇总.md 37 KB История Исходник

1. 采集网关接口说明

采集网关服务器请求地址

通用约定

请求格式

返回格式

HTTP 状态码说明

接口列表

通用设备字段

地址规则

word_byte_order 说明

Modbus 功能码

communication 字段格式

接口：健康检查

基本信息

成功返回

调用示例

接口：原始 Modbus 读取

基本信息

请求体结构

成功返回示例

失败返回示例

调用示例

接口：点位读取并转换

基本信息

请求体结构

点位类型和读取长度

点位校验规则

成功返回示例

失败返回示例

调用示例

AI 调用决策指南

2. 模方登录接口

3. 汇采接口

前置说明

服务器地址

通用约定

注意

Modbus 创建设备与创建点位接口文档

枚举汇总

1. 创建设备

基本信息

请求字段

请求示例：Modbus TCP

请求示例：Modbus RTU

成功响应

主要失败响应

2. 创建采集点位

基本信息

请求字段

请求示例：保持寄存器 uint16

请求示例：寄存器位点 bool

请求示例：线圈点位

成功响应

主要失败响应

查询设备列表接口

基本信息

请求参数

请求示例

响应示例

注意事项

接口汇总.md 37 KB

История Исходник