1. 采集网关接口说明

当前采集网关接口支持通过 HTTP 调用 Modbus TCP 和 Siemens S7 TCP 设备。Modbus RTU、S7 串口或其他协议设备不属于采集网关当前 HTTP 直连范围。

采集网关服务器请求地址

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/S7 通信失败时，通常仍返回 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` 等价，建议优先使用下划线版本。
原始 S7 读取	`POST`	`/api/dc-gateway/s7/read`	读取一段 S7 地址数据，只返回语义化 `communication`。
S7 点位读取并转换	`POST`	`/api/dc-gateway/s7/read_points`	按点位定义读取 S7 数据，并返回转换后的业务值和 `communication`。
S7 连接扫描	`POST`	`/api/dc-gateway/s7/connect_scan`	只传 IP，扫描可用的 `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`，返回常见点位对象信息和值。
BACnet BBMD Who-Is	`POST`	`/api/dc-gateway/bacnet/bbmd/whois`	通过 BBMD 分发 `Who-Is`，返回收到的 `I-Am` 设备列表。

网关接口目录

部分	内容
通用部分	请求格式、返回格式、HTTP 状态码、健康检查。
Modbus 网关接口	Modbus TCP 通用设备字段、地址规则、功能码、原始读取、点位读取并转换。
S7 网关接口	S7 TCP 通用设备字段、地址字段、语义化通信记录、原始读取、点位读取并转换、连接扫描。
BACnet 网关接口	BACnet/IP 通用设备字段、对象类型、点位读取、点位搜索、BBMD Who-Is。

Modbus 通用设备字段

以下字段用于描述要连接的 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 网关接口说明

接口：原始 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
    }
  }'

接口：modbus点位读取并转换

基本信息

项	值
方法	`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"
      }
    ]
  }'

S7 网关接口说明

S7 网关目标

S7 网关接口通过 HTTP 连接 Siemens S7 TCP 设备，支持连接组合扫描、原始字节读取、点位读取并转换。

当前 S7 接口使用 python-snap7 实现。返回的 communication 是语义化通信记录，用于说明本次连接、读取和断开过程；它不是 Wireshark 中的 TPKT + COTP + S7Comm 原始网络帧。

S7 通用设备字段

以下字段用于 /api/dc-gateway/s7/read 和 /api/dc-gateway/s7/read_points 请求体顶层。

字段	类型	必填	默认值	允许值或范围	含义
`device_type`	string	否	`S7-1200`	`S7-1200`,`S7-Smart200`	设备协议类型。
`ip`	string	是	无	合法 IPv4 或 IPv6 地址	S7 设备 IP 地址。
`port`	integer	否	`102`	`1..65535`	S7 TCP 端口，通常固定为 `102`。
`rock`	integer	是	无	`0..31`	PLC 机架号。字段名沿用汇采 S7 设备接口。
`slot`	integer	是	无	`0..31`	PLC 槽号。
`tsap_conn_type`	string	否	`PG`	`PG`、`OP`、`BASIC`	Snap7 连接类型。大小写不敏感，服务内部统一转为大写。

约定：未传 tsap_conn_type 时统一使用 PG。如果请求中显式传入 tsap_conn_type，以请求值为准；只有现场测试或扫描确认需要 OP/BASIC 时才显式传。

连接类型映射：

`tsap_conn_type`	Snap7 值
`PG`	`0x01`
`OP`	`0x02`
`BASIC`	`0x03`

S7 地址字段

字段	适用位置	必填	默认值	允许值或范围	含义
`area`	`read`、`points[]`	是	无	`DB`、`M`、`I`、`Q`、`V(S7-Smart200)`	读取区域。
`db`	`read`、`points[]`	`area=DB` 时必填	`0`	`>=0`	DB 块号。`area=DB` 时必须大于 `0`。
`start`	`read`、`points[]`	是	无	`>=0`	起始字节偏移。
`size`	`read`	是	无	`1..65535`	原始读取的字节数。
`type`	`points[]`	是	无	见 S7 点位类型表	点位数据类型。
`bit`	`points[]`	否	`null`	`0..7`	仅 `type=bool` 支持，用于读取指定 bit。

区域说明：

`area`	含义
`DB`	数据块 Data Block。
`M`	Merker 标志位区。
`I`	输入区 Inputs。
`Q`	输出区 Outputs。
`V`	V 存储区，仅 `S7-Smart200` 支持。

S7 communication 格式

communication 是字符串数组，记录连接、读取和断开过程。

示例：

Tx:S7_CONNECT ip=192.168.1.10 port=102 rock=0 slot=1 tsap_conn_type=PG
Rx:S7_CONNECTED pdu_length=480
Tx:S7_READ area=DB db=1 start=0 size=4
Rx:11 22 33 44
Tx:S7_DISCONNECT
Rx:S7_DISCONNECTED

说明：

片段	含义
`Tx:S7_CONNECT`	网关准备发起 S7 连接，包含 IP、端口、机架号、槽号和 TSAP 连接类型。
`Rx:S7_CONNECTED`	S7 连接成功，可能包含协商后的 `pdu_length`。
`Tx:S7_READ`	网关准备读取指定区域、DB、起始偏移和字节数。
`Rx:11 22 33 44`	读取返回的原始数据字节，十六进制大写，空格分隔。
`Tx:S7_DISCONNECT`	网关准备断开连接。
`Rx:S7_DISCONNECTED`	连接已断开。
`Rx:S7_ERROR`	连接或读取失败，后面带错误消息。

接口：原始 S7 读取

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/s7/read`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/s7/read`
Content-Type	`application/json`
用途	向 S7 TCP 设备读取一段地址数据，只返回语义化 `communication` 和原始十六进制字节，不返回解析后的业务值。

请求体结构

{
  "device_type": "S7-1200",
  "ip": "192.168.1.10",
  "port": 102,
  "rock": 0,
  "slot": 1,
  "tsap_conn_type": "PG",
  "read": {
    "area": "DB",
    "db": 1,
    "start": 0,
    "size": 4
  }
}

顶层字段说明见“S7 通用设备字段”。read 字段说明见“S7 地址字段”。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "S7-1200",
      "ip": "192.168.1.10",
      "port": 102,
      "rock": 0,
      "slot": 1,
      "tsap_conn_type": "PG"
    },
    "communication": [
      "Tx:S7_CONNECT ip=192.168.1.10 port=102 rock=0 slot=1 tsap_conn_type=PG",
      "Rx:S7_CONNECTED pdu_length=480",
      "Tx:S7_READ area=DB db=1 start=0 size=4",
      "Rx:11 22 33 44",
      "Tx:S7_DISCONNECT",
      "Rx:S7_DISCONNECTED"
    ]
  }
}

失败返回示例

{
  "code": 1,
  "msg": "TCP : Unreachable peer",
  "data": {
    "device": {
      "device_type": "S7-1200",
      "ip": "192.168.1.10",
      "port": 102,
      "rock": 0,
      "slot": 1,
      "tsap_conn_type": "PG"
    },
    "communication": [
      "Tx:S7_CONNECT ip=192.168.1.10 port=102 rock=0 slot=1 tsap_conn_type=PG",
      "Rx:S7_ERROR message=TCP : Unreachable peer"
    ]
  }
}

调用示例

curl -X POST http://127.0.0.1:8000/api/dc-gateway/s7/read \
  -H "Content-Type: application/json" \
  -d '{
    "device_type": "S7-1200",
    "ip": "192.168.1.10",
    "port": 102,
    "rock": 0,
    "slot": 1,
    "tsap_conn_type": "PG",
    "read": {
      "area": "DB",
      "db": 1,
      "start": 0,
      "size": 4
    }
  }'

接口：S7 点位读取并转换

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/s7/read_points`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/s7/read_points`
Content-Type	`application/json`
用途	按点位定义逐个读取 S7 数据，并把原始字节转换为 `bool`、`int16`、`float32` 等业务值。

请求体结构

{
  "device_type": "S7-1200",
  "ip": "192.168.1.10",
  "port": 102,
  "rock": 0,
  "slot": 1,
  "tsap_conn_type": "PG",
  "points": [
    {
      "area": "DB",
      "db": 1,
      "start": 0,
      "type": "float32"
    },
    {
      "area": "DB",
      "db": 1,
      "start": 4,
      "type": "bool",
      "bit": 0
    }
  ]
}

顶层字段说明见“S7 通用设备字段”。points[] 字段说明见“S7 地址字段”。

支持的数据类型

`type`	读取长度	返回 JSON 类型	含义
`bool`	1 byte	boolean	布尔值。传 `bit` 时读取指定 bit；不传 `bit` 时整个字节非 0 为 `true`。
`byte`	1 byte	integer	无符号 8 位整数。
`int8`	1 byte	integer	有符号 8 位整数。
`int16`	2 bytes	integer	有符号 16 位整数。
`uint16`	2 bytes	integer	无符号 16 位整数。
`int32`	4 bytes	integer	有符号 32 位整数。
`uint32`	4 bytes	integer	无符号 32 位整数。
`float32`	4 bytes	number	IEEE 754 单精度浮点数。
`int64`	8 bytes	integer	有符号 64 位整数。
`uint64`	8 bytes	integer	无符号 64 位整数。
`float64`	8 bytes	number	IEEE 754 双精度浮点数。

S7 多字节数值按大端字节序解析。

点位校验规则

规则	说明
`area` 必须合法	支持 `DB`、`M`、`I`、`Q`，`S7-Smart200` 还支持 `V`，输入会转为大写。
DB 区必须传有效 DB 号	当 `area=DB` 时，`db` 必须大于 `0`。
`type` 必须合法	只能使用上表列出的 S7 网关点位类型。
`bit` 只支持布尔点	`type=bool` 时可传 `bit`，非布尔点传 `bit` 会校验失败。
不允许额外字段	请求对象中出现未定义字段会校验失败。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "S7-1200",
      "ip": "192.168.1.10",
      "port": 102,
      "rock": 0,
      "slot": 1,
      "tsap_conn_type": "PG"
    },
    "points": [
      {
        "area": "DB",
        "db": 1,
        "start": 0,
        "type": "float32",
        "value": 12.34
      },
      {
        "area": "DB",
        "db": 1,
        "start": 4,
        "type": "bool",
        "value": true,
        "bit": 0
      }
    ]
  }
}

成功返回字段说明：

字段	类型	含义
`code`	integer	`0` 表示所有点位读取和转换成功。
`msg`	string	成功时为 `success`。
`data.device`	object	本次请求实际使用的设备连接参数。
`data.points`	object[]	点位读取结果数组，顺序与请求体 `points` 一致。
`data.points[].area`	string	点位读取区域。
`data.points[].db`	integer	DB 块号；非 DB 区通常为 `0`。
`data.points[].start`	integer	起始字节偏移。
`data.points[].type`	string	点位类型，返回为小写。
`data.points[].bit`	integer	仅当请求点位传入 `bit` 时返回。
`data.points[].value`	boolean、integer 或 number	转换后的点位值。具体 JSON 类型由 `type` 决定。

失败返回说明

失败时 code=1，msg 为连接失败、读取失败或字段校验错误原因。若读取部分点位后失败，data.points 中会保留失败前已成功读取的点位，data.communication 中会包含失败前的语义化记录。

调用示例

curl -X POST http://127.0.0.1:8000/api/dc-gateway/s7/read_points \
  -H "Content-Type: application/json" \
  -d '{
    "device_type": "S7-1200",
    "ip": "192.168.1.10",
    "port": 102,
    "rock": 0,
    "slot": 1,
    "tsap_conn_type": "PG",
    "points": [
      {
        "area": "DB",
        "db": 1,
        "start": 0,
        "type": "float32"
      },
      {
        "area": "DB",
        "db": 1,
        "start": 4,
        "type": "bool",
        "bit": 0
      }
    ]
  }'

接口：S7 连接扫描

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/s7/connect_scan`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/s7/connect_scan`
Content-Type	`application/json`
用途	只传设备 IP，扫描可连接成功的 `rock`、`slot`、`tsap_conn_type` 组合。

请求体结构

{
  "ip": "192.168.1.10"
}

端口固定使用 S7 TCP 默认端口 102。

扫描范围

字段	扫描值
`rock`	`0`、`1`、`2`
`slot`	`0`、`1`、`2`
`tsap_conn_type`	`PG`、`OP`、`BASIC`

总计扫描 27 种组合。接口只返回可以连接成功的组合。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "S7-1200",
      "ip": "192.168.1.10",
      "port": 102
    },
    "available": [
      {
        "rock": 0,
        "slot": 1,
        "tsap_conn_type": "PG"
      },
      {
        "rock": 0,
        "slot": 1,
        "tsap_conn_type": "OP"
      }
    ]
  }
}

如果没有任何组合可连接，available 为空数组：

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "S7-1200",
      "ip": "192.168.1.10",
      "port": 102
    },
    "available": []
  }
}

调用示例

curl -X POST http://127.0.0.1:8000/api/dc-gateway/s7/connect_scan \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.1.10"
  }'

BACnet 网关接口说明

BACnet 网关目标

BACnet 网关用于通过 HTTP 直连 BACnet/IP 设备，当前支持点位读取、点位搜索和通过 BBMD 执行 Who-Is 设备发现。点位读取和点位搜索底层使用 BAC0，读取点位时固定读取对象的 present-value；BBMD Who-Is 设备发现通过 BACnet/IP BVLC 报文实现。

BACnet 通用设备字段

以下字段用于描述要连接的 BACnet/IP 设备，出现在 /bacnet/read_points 和 /bacnet/search_points 请求体的顶层。

字段	类型	必填	默认值	允许值或范围	含义
`ip`	string	是	无	合法 IPv4 或 IPv6 地址	BACnet/IP 设备地址。
`bacnet_device_id`	integer	是	无	`0..4194303`	BACnet 设备对象实例号。
`port`	integer	否	`47808`	`1..65535`	BACnet/IP UDP 端口。

响应中的设备信息固定包含：

{
  "device_type": "BACnet/IP",
  "ip": "192.168.75.240",
  "port": 47808,
  "bacnet_device_id": 12345
}

BACnet 对象类型

MCP/网关请求中的 object_type 支持常见写法，例如 AnalogInput、analogInput、analog-input；调用底层 BACnet 读取前会统一规范为 AnalogInput 这类格式，避免把 analog-input 原样传给底层导致采集不到数据。响应也统一返回 AnalogInput 这类格式。

常见点位对象类型：

响应值	BACnet 含义
`AnalogInput`	模拟输入
`AnalogOutput`	模拟输出
`AnalogValue`	模拟值
`BinaryInput`	二进制输入
`BinaryOutput`	二进制输出
`BinaryValue`	二进制值
`MultiStateInput`	多状态输入
`MultiStateOutput`	多状态输出
`MultiStateValue`	多状态值

接口：BACnet 点位读取

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/bacnet/read_points`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/bacnet/read_points`
Content-Type	`application/json`
用途	按 BACnet 对象读取 `present-value`。

MCP 工具 bacnet.point_collect_test 会调用该接口并透传响应。

请求体结构

{
  "ip": "192.168.75.240",
  "bacnet_device_id": 12345,
  "port": 47808,
  "points": [
    {
      "object_type": "AnalogInput",
      "object_id": 1
    }
  ]
}

points 字段说明：

字段	类型	必填	默认值	允许值或范围	含义
`points`	object[]	是	无	至少 1 个点位	BACnet 点位对象列表。
`points[].object_type`	string	是	无	合法 BACnet 对象类型写法	BACnet 对象类型；如 `analog-input` 会先规范为 `AnalogInput`。
`points[].object_id`	integer	是	无	`0..4194303`	BACnet 对象实例号。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": [
      {
        "object_type": "AnalogInput",
        "object_id": 1,
        "present_value": 12.3
      }
    ]
  }
}

失败返回示例

{
  "code": 1,
  "msg": "No response from BACnet device",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": []
  }
}

接口：BACnet 点位搜索

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/bacnet/search_points`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/bacnet/search_points`
Content-Type	`application/json`
用途	读取设备 `object-list`，返回常见点位对象基础信息和值。

MCP 工具 bacnet.point_search 会调用该接口并透传响应。未知 object_type 和 object_id 时，建议先调用该工具搜索点位，再调用 bacnet.point_collect_test 读取目标点位。

请求体结构

{
  "ip": "192.168.75.240",
  "bacnet_device_id": 12345,
  "port": 47808
}

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "device": {
      "device_type": "BACnet/IP",
      "ip": "192.168.75.240",
      "port": 47808,
      "bacnet_device_id": 12345
    },
    "points": [
      {
        "name": "Zone Temperature",
        "description": "Room temperature",
        "object_type": "AnalogInput",
        "object_id": 1,
        "present_value": 24.5
      }
    ]
  }
}

搜索每个点位时读取以下属性：

返回字段	BACnet 属性
`name`	`object-name`
`description`	`description`
`present_value`	`present-value`

单个点位的 description 或 present_value 读取失败时，该字段返回 null，不会中断整个搜索。设备连接或 object-list 读取失败时，接口返回 code=1。

调用示例

curl -X POST http://127.0.0.1:8000/api/dc-gateway/bacnet/search_points \
  -H "Content-Type: application/json" \
  -d '{
    "ip": "192.168.75.240",
    "bacnet_device_id": 12345,
    "port": 47808
  }'

接口：BACnet BBMD Who-Is 设备发现

基本信息

项	值
方法	`POST`
路径	`/api/dc-gateway/bacnet/bbmd/whois`
完整地址	`http://127.0.0.1:8000/api/dc-gateway/bacnet/bbmd/whois`
Content-Type	不需要请求体
用途	注册 BBMD Foreign Device，通过 BBMD 分发 `Who-Is`，收集 `I-Am` 响应并返回 BACnet 设备列表。

MCP 工具 bacnet.bbmd_whois 会调用该接口并透传响应。该工具只需要传 project_key，不发送请求体；BBMD 地址、端口、TTL、Who-Is 等待超时、设备号范围、本机绑定地址等参数由采集网关环境变量配置。

请求体结构

不需要请求体，直接 POST 即可：

curl -X POST http://127.0.0.1:8000/api/dc-gateway/bacnet/bbmd/whois

采集网关环境变量

环境变量	是否必填	默认值	说明
`BACNET_BBMD_IP`	是	无	BBMD 地址。
`BACNET_BBMD_PORT`	否	`47808`	BBMD UDP 端口。
`BACNET_BBMD_TTL`	否	`60`	Foreign Device 注册 TTL，单位秒。
`BACNET_BBMD_WHOIS_TIMEOUT`	否	`5`	收集 `I-Am` 的等待时间，单位秒。
`BACNET_BBMD_LOW_LIMIT`	否	`0`	Who-Is 设备号下限。
`BACNET_BBMD_HIGH_LIMIT`	否	`4194303`	Who-Is 设备号上限。
`BACNET_BBMD_LOCAL_DEVICE_ID`	否	无	若收到同设备号的 `I-Am`，会作为本机设备忽略。
`BACNET_LOCAL_IP`	否	自动按到 BBMD 的路由推断	本机 BACnet 源地址。
`BACNET_LOCAL_PORT`	否	自动选择空闲端口	本机 UDP 绑定端口。

成功返回示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "bbmd": {
      "bbmd_ip": "192.168.1.1",
      "bbmd_port": 47808,
      "ttl": 60,
      "timeout": 5,
      "low_limit": 0,
      "high_limit": 4194303
    },
    "devices": [
      {
        "bacnet_device_id": 12345,
        "ip": "192.168.10.20",
        "port": 47808,
        "max_apdu": 1476,
        "segmentation": "noSegmentation",
        "vendor_id": 842
      }
    ]
  }
}

失败返回示例

{
  "code": 1,
  "msg": "BBMD foreign device registration timeout",
  "data": {
    "bbmd": {
      "bbmd_ip": "192.168.1.1",
      "bbmd_port": 47808,
      "ttl": 60,
      "timeout": 5,
      "low_limit": 0,
      "high_limit": 4194303
    },
    "devices": []
  }
}

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`，自动按类型转换。
需要查看 S7 语义化连接和原始字节	`POST /api/dc-gateway/s7/read`	返回 S7 连接、读取、断开的 `communication`，不解析为业务值。
需要得到 S7 点位业务值	`POST /api/dc-gateway/s7/read_points`	返回 `points[].value`，自动按 S7 类型转换。
不确定 S7 连接参数	`POST /api/dc-gateway/s7/connect_scan`	扫描可用的 `rock`、`slot`、`tsap_conn_type` 组合。
需要搜索 BACnet 设备点位	`POST /api/dc-gateway/bacnet/search_points`	读取设备 `object-list`，返回常见点位对象。
需要读取 BACnet 点位当前值	`POST /api/dc-gateway/bacnet/read_points`	固定读取 BACnet 对象的 `present-value`。
需要跨网段发现 BACnet 设备	`POST /api/dc-gateway/bacnet/bbmd/whois`	通过采集网关环境变量配置的 BBMD 分发 `Who-Is`，返回 `I-Am` 设备列表。

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

地址	字段或配置	含义
网关服务器地址	`http://127.0.0.1:8000`	HTTP API 服务地址，用于拼接请求 URL。
Modbus 设备地址	请求体 `ip` 和 `port`	实际被读取的 Modbus TCP 设备地址。
S7 设备地址	请求体 `ip`、`port`、`rock`、`slot`、`tsap_conn_type`	实际被读取的 S7 TCP 设备连接参数。
BACnet 设备地址	请求体 `ip`、`port`、`bacnet_device_id`	实际被读取的 BACnet/IP 设备参数。
BACnet BBMD 地址	采集网关环境变量 `BACNET_BBMD_IP`、`BACNET_BBMD_PORT`	`bacnet.bbmd_whois` 使用的 BBMD 目标地址，不通过 MCP 入参传递。

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

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

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

先确定 device_type，默认使用 S7-1200；如果是 S7-Smart200，传 device_type=S7-Smart200，tsap_conn_type 未传时默认 PG。
如果不确定 S7 连接参数，先调用 /s7/connect_scan 获取可用的 rock、slot、tsap_conn_type。
根据设备点表选择 area，DB 区传 area=DB 且填写大于 0 的 db；S7-Smart200 的 V 区传 area=V。
将 S7 地址换算为字节偏移，填入 start。
根据点位数据类型设置 type，S7 网关类型与汇采 S7 点位类型不完全一致：网关 8 位无符号类型为 byte，汇采创建点位常用 uint8。
如果读取布尔位，设置 type=bool 并填写 bit=0..7；非布尔点不要传 bit。
发送请求后检查响应体 code，不要只检查 HTTP 状态码。

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

如果不知道点位对象，先调用 /bacnet/search_points 或 MCP 工具 bacnet.point_search 获取 object_type 和 object_id。
设置设备字段 ip、bacnet_device_id，port 不传时默认为 47808。
在 points 中填入 object_type 和 object_id，object_type 可使用 AnalogInput、analogInput、analog-input 等写法，MCP/网关会统一规范为 AnalogInput 这类格式后再读取。
发送请求后检查响应体 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。创建设备和创建点位时接口会写入初始状态，调用方通常不需要传；查询设备列表、连接设备、查询点位列表等接口会返回这些状态字段。

设备 status 表示设备连接状态：

值	英文状态	含义	典型场景
`1`	`disconnected`	未连接	设备未执行连接、已断开，或连接失败后回到未连接状态。
`2`	`connected`	已连接	设备连接成功。注意这不等同于正在采集。
`3`	`error`	连接异常	设备连接过程或连接状态异常。

设备 running_status 表示采集状态，不表示 TCP/串口等底层连接是否成功：

值	英文状态	含义	典型场景
`0`	`idle`	未采集	设备尚未开始采集、已停止采集，或刚连接但没有采集任务运行。
`1`	`running`	采集中	设备正在执行采集任务。
`2`	`error`	采集异常	采集过程中发生异常，例如读取点位失败、通信异常或采集任务报错。

设备 connect_status 表示最近一次连接/通信检测状态：

值	英文状态	含义	典型场景
`0`	`idle`	未检测或空闲	尚未进行连接检测，或设备当前处于空闲状态。
`1`	`normal`	连接正常	最近一次连接或通信状态正常。
`2`	`abnormal`	连接异常	最近一次连接或通信状态异常。

点位 status 表示点位采集状态：

值	英文状态	含义	典型场景
`0`	`idle`	未采集	点位尚未采集或设备未运行采集任务。
`1`	`working`	采集正常	点位最近一次采集正常。
`2`	`error`	采集异常	点位最近一次采集失败或转换失败。

状态字段关系说明：

字段	表示对象	说明
`status`	设备连接状态	判断设备是否已连接。
`running_status`	设备采集状态	判断设备是否正在采集或采集是否异常。
`connect_status`	最近连接/通信检测状态	判断最近一次连接或通信是否正常。
点位 `status`	单个点位采集状态	判断某个点位最近一次采集是否正常。

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 取某一位。

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`	采集周期。

MCP 工具 collector.modbus_device_create 接收 devices 数组并逐个调用本接口。MCP 默认值包括 serial_port=""、timeout=3、is_persistent=false、baud_rate=0、data_bit=0、parity=0、stop_bit=0、mode=0、retry_times=0、group_id=0、alarm_interval=90、collect_interval=5；address_base 会转换为本接口的 address_offset。全部创建设备调用完成后，MCP 会调用设备列表接口匹配 device_id，匹配到多个时选择最大 id。

请求示例：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/device/edit
方法：POST
处理函数：EditModbusDevice
请求结构：ReqEditModbusDevice
主要用途：编辑已存在的 Modbus 设备连接参数、采集周期、设备分组和持久化配置。

重要说明

该接口是 Modbus 专用旧接口，和通用创建设备接口 /api/collector/device 的字段名不完全一致。
该接口是全量更新语义，未传字段会按 Go 零值写入，例如 timeout 变为 0、is_persistent 变为 false、address_offset 变为 0。编辑前建议先查询设备详情或设备列表，基于原配置修改后整包提交。
编辑前设备不能处于已连接状态。若设备 status=2，接口返回 先停止设备采集，再编辑设备。应先调用连接/断开设备接口将设备断开。
请求字段 type 在本接口中表示 Modbus 连接类型，取值与前文 Modbus 设备连接类型枚举一致；不是通用创建设备接口里的协议字符串 type="modbus"。
编辑成功后接口会移除内存中的旧设备并重新加载设备对象，设备状态会回到未连接状态。

请求字段

字段	类型	必填	默认/行为	含义
`ori_id`	int	是	缺失或为 `0` 返回 `设备不存在`	要编辑的原设备 ID。
`type`	int	是	缺失时为 `0`，后续连接可能因连接类型无效失败	Modbus 连接类型。`1` TCP，`2` RTU，`3` UDP，`4` RTU OVER TCP，`5` RTU OVER UDP。
`name`	string	是	绑定时必填；保存前会 `strings.TrimSpace`	设备名称。
`ip`	string	TCP/UDP 类连接必填	会 `strings.TrimSpace`	设备 IP。`type` 不为 `2` 时为空会返回 `选择Modbus TCP类型时，IP不能为空`。
`port`	int	TCP/UDP 类连接必填	缺失时为 `0`	设备端口。`type` 为 `1`、`3`、`4`、`5` 时用于组装连接 URL。
`slave_id`	int	是	Go binding 的 `required` 对数字零值敏感，缺失或为 `0` 会绑定失败	Modbus 从站 ID/Unit ID。
`serial_port`	string	RTU 必填	会 `strings.TrimSpace`	串口名。`type=2` 时为空会返回 `选择Modbus RTU类型时，串口不能为空`。
`timeout`	int	建议必填	缺失时会写入 `0`，编辑接口不自动补 `3`	超时时间，单位秒。
`byte_order`	int	建议必填	缺失时会写入 `0`	字节序，见 `byte_order` 枚举。
`word_order`	int	建议必填	缺失时会写入 `0`	字序，见 `word_order` 枚举。
`is_persistent`	bool	否	缺失时会写入 `false`	是否持久化设备。
`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`	模式字段，当前主要保存配置。
`address_offset`	int	否	缺失时会写入 `0`	地址偏移。实际读点时使用 `点位 address - 设备 address_offset`。
`retry_times`	int	否	缺失时会写入 `0`	读取失败重试次数。
`device_group_id`	int	否	缺失时会写入 `0`	父设备分组 ID。`0` 表示顶层设备。
`alarm_interval`	int	否	缺失时会写入 `0`	告警间隔。
`collect_interval`	int	否	缺失时会写入 `0`	采集周期。

请求示例：编辑 Modbus TCP 设备

{
  "ori_id": 1,
  "type": 1,
  "name": "modbus_tcp_1_edited",
  "ip": "127.0.0.1",
  "port": 5502,
  "slave_id": 1,
  "timeout": 3,
  "byte_order": 1,
  "word_order": 1,
  "is_persistent": true,
  "device_group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 5,
  "address_offset": 0,
  "retry_times": 0,
  "mode": 0
}

请求示例：编辑 Modbus RTU 设备

{
  "ori_id": 1,
  "type": 2,
  "name": "modbus_rtu_1_edited",
  "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,
  "device_group_id": 0,
  "alarm_interval": 0,
  "collect_interval": 5,
  "address_offset": 0,
  "retry_times": 0,
  "mode": 0
}

成功响应

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

主要失败响应

场景	响应
JSON 绑定失败、`name` 缺失、`slave_id` 缺失或为零等	`{"state":2,"state_info":"无效参数"}`
`ori_id` 缺失或为 `0`	`{"state":2,"state_info":"设备不存在"}`
RTU 设备未传 `serial_port`	`{"state":2,"state_info":"选择Modbus RTU类型时，串口不能为空"}`
TCP/UDP 类设备未传 `ip`	`{"state":2,"state_info":"选择Modbus TCP类型时，IP不能为空"}`
查询原设备失败	`{"state":2,"state_info":"检测设备状态失败"}`
原设备不存在	`{"state":2,"state_info":"设备ID不合法"}`
设备仍处于已连接状态	`{"state":2,"state_info":"先停止设备采集，再编辑设备"}`
数据库更新失败	`{"state":2,"state_info":"编辑失败"}`

3. 创建采集点位

基本信息

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`。

MCP 工具 collector.modbus_point_create 接收 points 数组并逐个调用本接口。每个点位必须自带 device_id；MCP 默认值包括 point_id=""、scale_ratio=1、value_offset=0、group_id=0、invalid_values=""、valid_range_start=null、valid_range_end=null、bit=0。可传 register_type，MCP 会转换为本接口的 func_code。

请求示例：保持寄存器 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":"新增失败"}`

4. 编辑采集点位

基本信息

URL：/api/collector/modbus/point/edit_collect_point
方法：POST
处理函数：modbusPointEdit
请求结构：ReqModbusPointEdit
主要用途：编辑已存在的 Modbus 采集点位，包括点位名称、point_id、地址、功能码、数据类型、缩放和合法值范围。

重要说明

该接口是全量更新语义，除 ori_id 外的点位配置应按完整点位对象提交。未传字段会按 Go 零值写入，例如 group_id=0、value_offset=0、bit=0、invalid_values=""。
ori_id 是要编辑的采集点位内部 ID，对应查询设备点位列表返回的 data.point[].id。
编辑点位不会迁移点位所属设备。请求结构虽然继承了 device_id 字段，但处理逻辑会从原点位读取 DeviceID，并继续保存到原设备下。
point_id 允许为空字符串；非空时会检查同一设备下是否重复，检查时会排除当前 ori_id 对应的原点位。
编辑成功后会更新数据库、设备内存点位缓存和通用点位缓存。点位状态会重置为未采集状态。

请求字段

字段	类型	必填	默认/行为	含义
`ori_id`	int	是	无默认值	要编辑的原采集点位 ID。
`name`	string	是	绑定时必填；保存前会 `strings.TrimSpace`	点位名称。
`point_id`	string	否	空字符串允许	外部点位标识。非空时，同一设备下不能重复。
`device_id`	int	否	编辑逻辑不使用该字段	请求结构继承字段。编辑时点位仍归属原设备，不会按该字段迁移。
`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	否，但采集必须有效	无显式默认值	点位数据类型，见数据类型枚举。
`address`	int	是	Go 零值 `0`	Modbus 地址。实际读取地址为 `address - 设备 address_offset`。
`func_code`	int	是	Go 零值 `0` 会导致后续采集功能码无效	Modbus 功能码，见 `func_code` 枚举。
`group_id`	int	否	Go 零值 `0`	点位分组 ID。
`bit`	int	`type=bool` 且读寄存器时需要	Go 零值 `0`	位下标。`func_code=3/4` 且 `type=bool` 时，从寄存器值中取 `(value >> bit) & 1`。建议范围 `0` 到 `15`。

请求示例：编辑保持寄存器 uint16 点位

{
  "ori_id": 101,
  "name": "holding_register_uint16_edited",
  "point_id": "HR_UINT16_EDITED",
  "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

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

成功响应

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

主要失败响应

场景	响应
JSON 绑定失败、`ori_id` 缺失、`name` 缺失、`scale_ratio` 缺失或为零等	`{"state":2,"state_info":"无效参数"}`
`invalid_values` 中存在非数字项	`{"state":2,"state_info":"无效参数"}`
原点位不存在或查询失败	`{"state":2,"state_info":"校验失败"}`
同一设备下 `point_id` 重复	`{"state":2,"state_info":"point_id 重复, point_id: {point_id}"}`
数据库更新失败	`{"state":2,"state_info":"编辑失败"}`

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

枚举汇总

S7 设备类型 device_type

值	含义
`1`	S7-1200
`2`	S7-1500
`3`	S7-Smart200

S7 TSAP 连接类型 tsap_conn_type

值	含义
`PG`	PG 连接，未识别值在底层连接库中也会按 PG 处理。
`OP`	OP 连接。
`BASIC`	Basic 连接。

S7 点位寄存器区域 register_type

值	区域	含义
`1`	`I`	输入区。
`2`	`Q`	输出区。
`3`	`M`	位存储区。
`4`	`DB`	数据块区。
`5`	`V`	V 区，底层按 DB1 访问。
`6`	`AI`	模拟输入区。

S7 点位数据类型 data_type

值	含义	读取字节数
`bool`	布尔值	1
`uint8`	8 位无符号整数	1
`int8`	8 位有符号整数	1
`uint16`	16 位无符号整数	2
`int16`	16 位有符号整数	2
`uint32`	32 位无符号整数	4
`int32`	32 位有符号整数	4
`float32`	32 位浮点数	4
`float64`	64 位浮点数	8

S7 地址格式

S7 点位 address 是字符串，不是纯数字。采集时会按 register_type 和 data_type 解析：

区域	非 bool 地址格式	bool 地址格式	示例
`I`、`Q`、`M`	`byte`	`byte.bit`	`10`、`10.2`
`DB`	`db.byte`	`db.byte.bit`	`1.10`、`1.10.2`
`V`	`byte`	`byte.bit`	`10`、`10.2`
`AI`	`byte`	不建议使用 bool	`10`

bool 点位位下标范围为 0..7。DB 区必须包含 DB 号；例如 DB1 的第 10 字节第 2 位写为 1.10.2。

常见 S7 CSV/点表字段转换到 MCP 创建入参时，使用汇采创建格式，不要直接使用网关读取格式 area/start/bit：

CSV 区域	`register_area`	地址转换
`I`	`I`	BOOL 合并地址列和位地址列为 `byte.bit`；非 BOOL 使用字节地址。
`Q`、`QD`	`Q`	BOOL 使用 `byte.bit`；非 BOOL 使用字节地址。
`M`、`MD`	`M`	BOOL 使用 `byte.bit`；非 BOOL 使用字节地址。
`VD`、`VW`	`V`	BOOL 使用 `byte.bit`；非 BOOL 使用字节地址。
`DB`、`DBD`、`DBW`、`DBX`	`DB`	BOOL 使用 `db.byte.bit`；非 BOOL 使用 `db.byte`。

常见点表类型映射：BOOL=>bool、FLOAT/REAL=>float32、SHORT/INT=>int16、WORD=>uint16、DWORD=>uint32、DINT/LONG=>int32、DOUBLE/LREAL=>float64。

1. 创建 S7 设备

基本信息

URL：/api/collector/device
方法：POST
处理函数：AddS7Device
请求结构：ReqAddS7Device

说明：S7 创建设备在 MCP 中与 Modbus 创建设备共用 /api/collector/device 地址，但请求体固定带 type=s7，其余字段仍使用 S7 入参。

请求字段

字段	类型	必填	默认/行为	含义
`type`	string	MCP 自动补齐	固定为 `s7`	协议类型，用于在共用创建设备接口中区分 S7 设备。
`name`	string	是	会 `strings.TrimSpace`；trim 后为空返回 `名称不能为空`	设备名称。
`ip`	string	是	会 `strings.TrimSpace`；为空返回 `IP地址不能为空`	S7 PLC IP 地址。
`port`	int	建议传	保存到设备配置；底层 gos7 连接实际使用 `ip` 中端口或默认 `102`	端口，常用 `102`。
`device_type`	int	建议传	缺失时为 `0`	S7 设备类型，见枚举。
`rock`	int/null	是	nil 返回 `轨道号或槽号不能为空`	机架号。字段名沿用实现中的 `rock`。常见 S7-1200/1500 为 `0`。
`slot`	int/null	是	nil 返回 `轨道号或槽号不能为空`	槽号。常见 S7-1200/1500 为 `1`。
`tsap_conn_type`	string	否	底层未识别值按 PG 处理	TSAP 连接类型，可传 `PG`、`OP`、`BASIC`。
`is_persistent`	bool	否	Go 零值 `false`	是否持久化写入点位数据。
`device_group_id`	int	否	Go 零值 `0`	父设备分组 ID。`0` 表示顶层设备。
`timeout`	int	否	创建接口请求结构包含该字段，但当前创建逻辑未写入内部配置	超时时间，单位秒。

MCP 工具 collector.s7_device_create 接收 devices 数组并逐个调用本接口。MCP 默认值包括 port=102、device_type=1、tsap_conn_type=PG、is_persistent=false、device_group_id=0、timeout=3、alarm_interval=90、collect_interval=5；tsap_conn_type 不传或为 null 时统一使用 PG。只有现场测试或扫描确认需要 OP/BASIC 时才显式传。全部创建设备调用完成后，MCP 会调用设备列表接口匹配 device_id，匹配到多个时选择最大 id。

请求示例

{
  "type": "s7",
  "name": "s7_1200_1",
  "ip": "127.0.0.1",
  "port": 102,
  "device_type": 1,
  "rock": 0,
  "slot": 1,
  "tsap_conn_type": "PG",
  "is_persistent": true,
  "device_group_id": 0,
  "timeout": 3
}

成功响应

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

主要失败响应

场景	响应
JSON 绑定失败、`name` 缺失等	`{"state":2,"state_info":"无效参数"}`
`ip` 为空	`{"state":2,"state_info":"IP地址不能为空"}`
`rock` 或 `slot` 为 null/缺失	`{"state":2,"state_info":"轨道号或槽号不能为空"}`
`name` trim 后为空	`{"state":2,"state_info":"名称不能为空"}`
名称或 IP 已存在	`{"state":101,"state_info":"名称或IP已被占用"}`
数据库插入失败	`{"state":2,"state_info":"新增失败"}`

2. 编辑 S7 设备

基本信息

URL：/api/collector/s7/device/update
方法：POST
处理函数：UpdateS7Device
请求结构：ReqUpdateS7Device

重要说明

该接口是全量更新语义，未传字段会按 Go 零值写入，例如 port=0、is_persistent=false、alarm_interval=0、collect_interval=0。
编辑前设备不能处于已连接或采集状态。若状态不允许编辑，会返回设备需先停止相关错误。
编辑成功后会同步更新内存设备对象和数据库配置。

请求字段

字段	类型	必填	默认/行为	含义
`id`	int	是	绑定时必填	要编辑的 S7 设备 ID。
`name`	string	是	保存前 trim；为空返回 `名称不能为空`	设备名称。
`ip`	string	是	trim 后为空返回 `IP地址不能为空`	S7 PLC IP 地址。
`port`	int	建议传	缺失时写入 `0`	设备端口，常用 `102`。
`device_type`	int	建议传	缺失时写入 `0`	S7 设备类型。
`rock`	int/null	是	nil 返回 `轨道号或槽号不能为空`	机架号。
`slot`	int/null	是	nil 返回 `轨道号或槽号不能为空`	槽号。
`tsap_conn_type`	string	否	空字符串会保存，底层连接按 PG 默认处理	TSAP 连接类型。
`is_persistent`	bool	否	缺失时写入 `false`	是否持久化。
`device_group_id`	int	否	缺失时写入 `0`	父设备分组 ID。
`alarm_interval`	int	否	缺失时写入 `0`	告警间隔。
`collect_interval`	int	否	缺失时写入 `0`	采集周期。
`timeout`	int	否	缺失时写入 `0`	超时时间，单位秒。

请求示例

{
  "id": 1,
  "name": "s7_1200_1_edited",
  "ip": "127.0.0.1",
  "port": 102,
  "device_type": 1,
  "rock": 0,
  "slot": 1,
  "tsap_conn_type": "PG",
  "is_persistent": true,
  "device_group_id": 0,
  "alarm_interval": 90,
  "collect_interval": 5,
  "timeout": 3
}

成功响应

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

主要失败响应

场景	响应
JSON 绑定失败、`id` 缺失等	`{"state":2,"state_info":"无效参数"}`
`ip` 为空	`{"state":2,"state_info":"IP地址不能为空"}`
`rock` 或 `slot` 为 null/缺失	`{"state":2,"state_info":"轨道号或槽号不能为空"}`
`name` trim 后为空	`{"state":2,"state_info":"名称不能为空"}`
设备不存在或数据库查询失败	通常返回设备不存在或未知错误响应
设备名称已存在	`{"state":2,"state_info":"设备名称已存在"}`
数据库更新失败	`{"state":2,"state_info":"编辑失败"}`

3. 创建 S7 采集点位

基本信息

URL：/api/collector/s7/point/add
方法：POST
处理函数：AddS7CollectPoint
请求结构：ReqAddS7CollectPoint

请求字段

字段	类型	必填	默认/行为	含义
`device_id`	int	是	缺失时通常因找不到设备返回 `检测设备ID失败`	所属 S7 设备 ID。
`name`	string	是	trim 后为空返回 `名称不能为空`	点位名称。
`point_id`	string	否	空字符串允许	外部点位标识。非空时，同一设备下不能重复。
`register_type`	int	是	缺失时为 `0`，后续采集校验会失败	S7 寄存器区域，见枚举。
`data_type`	string	是	无显式默认值，后续采集校验会检查合法性	S7 数据类型，见枚举。
`address`	string	是	binding 必填	S7 地址字符串，见地址格式。
`scale_ratio`	float64	否	Go 零值 `0`，采集/写值时缩放系数为 0 会导致异常；建议传 `1`	缩放系数。
`value_offset`	float64	否	Go 零值 `0`	值偏移。
`describe`	string	否	空字符串	点位描述。
`group_Id`	int	否	Go 零值 `0`	点位分组 ID。注意当前请求 JSON 字段名是 `group_Id`。
`invalid_values`	string	否	空字符串解析为空数组	无效值列表，逗号分隔。
`valid_range_start`	number/null	否	`null`	合法范围最小值。
`valid_range_end`	number/null	否	`null`	合法范围最大值。

MCP 工具 collector.s7_point_create 接收 points 数组并逐个调用本接口。每个点位必须自带 device_id；MCP 默认值包括 point_id=""、scale_ratio=1、value_offset=0、group_Id=0、invalid_values=""、valid_range_start=null、valid_range_end=null。调用 MCP 时可传 group_id，MCP 会转换为接口字段 group_Id；可传 register_area，MCP 会转换为本接口的 register_type。注意本工具使用汇采创建格式，不接受网关读取格式 area/start/bit。

请求示例：DB 区 float32

{
  "device_id": 1,
  "name": "db1_real_10",
  "point_id": "DB1_REAL_10",
  "register_type": 4,
  "data_type": "float32",
  "address": "1.10",
  "scale_ratio": 1,
  "value_offset": 0,
  "describe": "DB1.DBD10 real 示例",
  "group_Id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}

请求示例：M 区 bool

{
  "device_id": 1,
  "name": "m10_2",
  "point_id": "M10_2",
  "register_type": 3,
  "data_type": "bool",
  "address": "10.2",
  "scale_ratio": 1,
  "value_offset": 0,
  "group_Id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}

成功响应

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

主要失败响应

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

4. 编辑 S7 采集点位

基本信息

URL：/api/collector/s7/point/update
方法：POST
处理函数：s7PointEdit
请求结构：ReqUpdateS7Point

重要说明

该接口是全量更新语义，除 id 外的点位配置应按完整点位对象提交。
id 是要编辑的采集点位内部 ID，对应查询设备点位列表返回的 data.point[].id。
请求结构包含 device_id，编辑逻辑不会迁移点位所属设备，但会用请求中的 device_id 做重复 point_id 校验并刷新内存点位，因此应传原所属设备 ID。

请求字段

字段	类型	必填	默认/行为	含义
`id`	int	是	binding 必填	要编辑的原采集点位 ID。
`device_id`	int	建议必填	缺失时可能导致重复校验和内存刷新异常	所属 S7 设备 ID。
`name`	string	是	trim 后为空返回 `名称不能为空`	点位名称。
`point_id`	string	否	空字符串允许	外部点位标识。
`register_type`	int	是	缺失时写入 `0`	S7 寄存器区域。
`data_type`	string	是	缺失时写入空字符串	S7 数据类型。
`address`	string	是	缺失时绑定失败	S7 地址字符串。
`scale_ratio`	float64	否	缺失时写入 `0`，建议传 `1`	缩放系数。
`value_offset`	float64	否	缺失时写入 `0`	值偏移。
`describe`	string	否	空字符串	点位描述。
`group_Id`	int	否	缺失时写入 `0`	点位分组 ID。
`invalid_values`	string	否	空字符串解析为空数组	无效值列表。
`valid_range_start`	number/null	否	`null`	合法范围最小值。
`valid_range_end`	number/null	否	`null`	合法范围最大值。

请求示例

{
  "id": 101,
  "device_id": 1,
  "name": "db1_real_10_edited",
  "point_id": "DB1_REAL_10_EDITED",
  "register_type": 4,
  "data_type": "float32",
  "address": "1.10",
  "scale_ratio": 1,
  "value_offset": 0,
  "describe": "编辑后的 DB1.DBD10 real 示例",
  "group_Id": 0,
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}

成功响应

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

主要失败响应

场景	响应
JSON 绑定失败、`id` 缺失、`address` 缺失等	`{"state":2,"state_info":"无效参数"}`
`invalid_values` 中存在非数字项	`{"state":2,"state_info":"无效参数"}`
`name` trim 后为空	`{"state":2,"state_info":"名称不能为空"}`
原点位查询失败	`{"state":2,"state_info":"查询点位失败"}`
原点位不存在	`{"state":2,"state_info":"当前设备不存在该点位"}`
同一设备下 `point_id` 重复	`{"state":2,"state_info":"point_id 重复, point_id: {point_id}"}`
数据库更新失败	`{"state":2,"state_info":"点位更新失败"}`

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

1. 创建 BACnet 设备

基本信息

URL：/api/collector/device
方法：POST
处理函数：DeviceHandler.POST
请求结构：handler.DeviceOrGroup

MCP 工具 collector.bacnet_device_create 接收 devices 数组并逐个调用本接口。MCP 固定传 type=bacnet、device_type=1，其中 device_type=1 表示 BACnet ASP 设备。全部创建设备调用完成后，MCP 会调用设备列表接口匹配 device_id，匹配到多个时选择最大 id。

请求字段

字段	类型	必填	默认/行为	含义
`type`	string	是	MCP 固定 `bacnet`	设备协议类型。
`device_type`	int	是	MCP 固定 `1`	BACnet 设备类型，`1=ASP`。
`name`	string	是	空字符串会导致创建失败	设备名称。
`ip`	string	是	空字符串会导致创建失败	BACnet/IP 设备地址。
`port`	int	否	MCP 默认 `47808`	BACnet/IP UDP 端口。
`bacnet_device_id`	int	是	`0..4194303`	BACnet 设备对象实例号。
`bacnet_net`	int	否	MCP 默认 `0`	BACnet 网络号。ASP 设备通常为 `0`。
`asp_ip`	string	否	MCP 默认空字符串	RP 设备关联 ASP 地址；MCP 当前固定 ASP 设备，通常为空。
`group_id`	int	否	MCP 默认 `0`	设备分组 ID。
`timeout`	int	否	MCP 默认 `3`	超时时间。
`is_persistent`	bool	否	MCP 默认 `false`	是否持久化。
`alarm_interval`	int	否	MCP 默认 `90`	告警间隔。
`collect_interval`	int	否	MCP 默认 `5`	采集周期。

请求示例

{
  "type": "bacnet",
  "device_type": 1,
  "name": "bacnet_1",
  "ip": "192.168.75.240",
  "port": 47808,
  "bacnet_device_id": 12345,
  "bacnet_net": 0,
  "asp_ip": "",
  "group_id": 0,
  "timeout": 3,
  "is_persistent": false,
  "alarm_interval": 90,
  "collect_interval": 5
}

成功响应

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

2. 编辑 BACnet 设备

基本信息

URL：/api/collector/bacnet/device/edit
方法：POST
处理函数：bacnetDeviceEdit
请求结构：ReqEditDevice

MCP 工具 collector.bacnet_device_edit 会把入参 bacnet_device_id 映射为该旧接口的 device_id 字符串，并固定 type=1。编辑前设备不能处于已连接状态；若已连接，请先调用 collector.device_disconnect，并传 device_type=bacnet。

请求字段

字段	类型	必填	默认/行为	含义
`ori_id`	int	是	binding 必填	原设备 ID。
`type`	int	是	MCP 固定 `1`	BACnet 设备类型，`1=ASP`。
`name`	string	是	空字符串会导致编辑失败	设备名称。
`ip`	string	是	空字符串会导致编辑失败	BACnet/IP 设备地址。
`device_id`	string	是	MCP 由 `bacnet_device_id` 转换	BACnet 设备对象实例号。
`port`	int	否	MCP 默认 `47808`	BACnet/IP UDP 端口。
`net`	int	否	MCP 默认 `0`	BACnet 网络号。
`asp_ip`	string	否	MCP 默认空字符串	RP 设备关联 ASP 地址。
`device_group_id`	int	否	MCP 默认 `0`	设备分组 ID。
`timeout`	int	否	MCP 默认 `3`	超时时间。
`is_persistent`	bool	否	MCP 默认 `false`	是否持久化。
`alarm_interval`	int	否	MCP 默认 `90`	告警间隔。
`collect_interval`	int	否	MCP 默认 `5`	采集周期。

请求示例

{
  "ori_id": 1,
  "type": 1,
  "name": "bacnet_edited",
  "ip": "192.168.75.241",
  "device_id": "12345",
  "port": 47808,
  "net": 0,
  "asp_ip": "",
  "device_group_id": 0,
  "timeout": 3,
  "is_persistent": false,
  "alarm_interval": 90,
  "collect_interval": 5
}

成功响应

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

3. 创建 BACnet 采集点位

基本信息

URL：/api/collector/bacnet/point/add_collect_point
方法：POST
处理函数：bacnetPointAddBatch
请求结构：ReqBacnetPointsAddBatch

MCP 工具 collector.bacnet_point_create 接收扁平 points 数组并逐个调用本接口。每个 MCP 点位必须自带 device_id，MCP 会包装为 {device_id, points:[...]}。MCP 入参可使用 AnalogInput、analogInput、analog-input 等常见写法，但调用汇采接口前会统一转换为 AnalogInput 这类格式；直调汇采接口时应使用转换后的格式。

请求字段

字段	类型	必填	默认/行为	含义
`device_id`	int	是	设备不存在返回失败	所属 BACnet 设备 ID。
`points`	object[]	是	至少 1 个点位	要创建的点位数组。
`points[].object_type`	string	是	MCP 会规范为 `AnalogInput` 这类格式	BACnet 对象类型，如 `AnalogInput`；不要把 `analog-input` 原样传给汇采。
`points[].object_id`	int	是	`0..4194303`	BACnet 对象实例号。
`points[].name`	string	建议传	MCP 可用 `object_name` 补齐	点位名称。
`points[].object_name`	string	是	MCP 可用 `name` 补齐	BACnet 对象名。
`points[].point_id`	string	否	MCP 默认空字符串	外部点位标识。
`points[].priority`	int/null	否	MCP 默认 `null`	写值优先级。
`points[].units`	string	否	MCP 默认空字符串	单位。
`points[].value_type`	int	否	MCP 默认 `0`	BACnet PresentValue 类型。常见值：`1=Boolean`、`2=Unsigned`、`3=Signed`、`4=Real`、`5=Double`、`6=Enumerated`。
`points[].group_id`	int	否	MCP 默认 `0`	点位分组 ID。
`points[].scale_ratio`	float64	否	MCP 默认 `1`	缩放系数。
`points[].value_offset`	float64	否	MCP 默认 `0`	值偏移。
`points[].describe`	string	否	MCP 默认空字符串	点位描述。

请求示例

{
  "device_id": 1,
  "points": [
    {
      "object_type": "AnalogInput",
      "object_id": 1,
      "name": "zone_temperature",
      "object_name": "zone_temperature",
      "point_id": "AI_TEMP",
      "priority": null,
      "units": "degC",
      "value_type": 4,
      "group_id": 0,
      "scale_ratio": 1,
      "value_offset": 0,
      "describe": "Zone temperature"
    }
  ]
}

成功响应

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

4. 编辑 BACnet 采集点位

基本信息

URL：/api/collector/bacnet/point/edit
方法：POST
处理函数：bacnetPointEdit
请求结构：ReqBacnetPointEdit

MCP 工具 collector.bacnet_point_edit 使用 ori_id 表示原点位 ID，并映射为该接口的 id 字段。ori_id 对应 collector.device_points 返回的 data.point[].id。MCP 会将 analog-input、analogInput 等常见写法统一转换为 AnalogInput 这类格式后再调用汇采接口。

请求字段

字段	类型	必填	默认/行为	含义
`id`	int	是	binding 必填	要编辑的原采集点位 ID。
`object_type`	string	是	MCP 会规范为 `AnalogInput` 这类格式	BACnet 对象类型；不要把 `analog-input` 原样传给汇采。
`object_id`	int	是	`0..4194303`	BACnet 对象实例号。
`name`	string	建议传	MCP 可用 `object_name` 补齐	点位名称。
`object_name`	string	是	MCP 可用 `name` 补齐	BACnet 对象名。
`point_id`	string	否	MCP 默认空字符串	外部点位标识。
`priority`	int/null	否	MCP 默认 `null`	写值优先级。
`units`	string	否	MCP 默认空字符串	单位。
`value_type`	int	否	MCP 默认 `0`	BACnet PresentValue 类型。
`group_id`	int	否	MCP 默认 `0`	点位分组 ID。
`scale_ratio`	float64	否	MCP 默认 `1`	缩放系数。
`value_offset`	float64	否	MCP 默认 `0`	值偏移。
`describe`	string	否	MCP 默认空字符串	点位描述。
`invalid_values`	string	否	MCP 默认空字符串	无效值列表，多个值用逗号分隔。
`valid_range_start`	number/null	否	MCP 默认 `null`	合法范围最小值。
`valid_range_end`	number/null	否	MCP 默认 `null`	合法范围最大值。

请求示例

{
  "id": 101,
  "object_type": "AnalogInput",
  "object_id": 1,
  "name": "zone_temperature_edited",
  "object_name": "zone_temperature_edited",
  "point_id": "AI_TEMP_EDITED",
  "priority": null,
  "units": "degC",
  "value_type": 4,
  "group_id": 0,
  "scale_ratio": 1,
  "value_offset": 0,
  "describe": "Edited zone temperature",
  "invalid_values": "",
  "valid_range_start": null,
  "valid_range_end": null
}

成功响应

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

连接/断开设备接口

基本信息

URL：/api/collector/common/device/set_connect_status
方法：POST
请求体：application/json
普通响应类型：JSON
主要用途：连接或断开指定采集设备。该接口是通用设备接口，Modbus 设备调用时 type 传 modbus。

请求字段

字段	类型	必填	默认/行为	含义
`id`	int	是	Go 零值 `0`	设备 ID。接口会从采集器内存中按 ID 查找设备。
`status`	int	是	Go 零值 `0` 会进入非法状态逻辑	要设置的设备连接状态。`1` 表示断开，`2` 表示连接。
`type`	string	建议传	当前处理逻辑不直接使用该字段	设备协议类型。Modbus 设备传 `modbus`，其他可传 `s7`、`bacnet`、`ethernet-ip`、`opc-ua`、`opc-da`、`snmp`、`iec104`。

status 取值

值	含义	接口行为
`1`	disconnected，断开连接	调用设备断开逻辑，成功后设备 `status` 通常为 `1`，`running_status` 通常为 `0`。
`2`	connected，连接设备	调用设备连接逻辑，成功后设备 `status` 通常为 `2`，`running_status` 取决于设备采集状态。
其他	非法状态	返回失败响应，通常为 `{"state":2,"state_info":"操作设备失败"}`。

请求示例：连接 Modbus 设备

{
  "id": 1,
  "type": "modbus",
  "status": 2
}

请求示例：断开 Modbus 设备

{
  "id": 1,
  "type": "modbus",
  "status": 1
}

成功响应

{
  "state": 0,
  "state_info": "",
  "data": {
    "status": 2,
    "running_status": 0,
    "msg": ""
  }
}

成功响应字段说明

字段	类型	含义
`state`	int	业务状态码。成功时为 `0`。
`state_info`	string	状态描述。该接口成功时通常为空字符串。
`data.status`	int	操作后的设备连接状态，见设备 `status` 枚举。
`data.running_status`	int	操作后的设备运行状态，见 `running_status` 枚举。
`data.msg`	string	连接失败时可能返回底层错误消息；成功时通常为空字符串。

失败响应示例

请求体无法绑定或字段类型错误：

{
  "state": 2,
  "state_info": "无效参数",
  "data": null
}

设备不存在或不在当前采集器内存中：

{
  "state": 2,
  "state_info": "查询详情失败",
  "data": null
}

连接设备时发现点位标识与其他运行设备重复：

{
  "state": 2,
  "state_info": "point_id: AI_TEMP_01 在运行的设备中已存在",
  "data": null
}

设备连接或断开失败：

{
  "state": 2,
  "state_info": "操作设备失败",
  "data": {
    "status": 1,
    "running_status": 0,
    "msg": ""
  }
}

查询设备点位列表接口

基本信息

URL：/api/collector/common/device/get_collect_point
方法：POST
请求体：application/json
普通响应类型：JSON
主要用途：查询指定设备当前内存中的采集点位列表。该接口是通用设备点位接口，Modbus 设备调用时 type 传 modbus。

请求字段

字段	类型	必填	默认/行为	含义
`id`	int	是	Go 零值 `0`	设备 ID。
`type`	string	是	空字符串会返回无效参数	设备协议类型。查询 Modbus 点位固定传 `modbus`。
`group_id`	int	否	`0`	点位分组 ID。为 `0` 时返回该设备下全部点位；非 `0` 时只返回该分组下点位。

type 取值

值	含义
`modbus`	Modbus 设备点位。
`s7`	S7 设备点位。
`bacnet`	BACnet 设备点位。
`ethernet-ip`	EtherNet/IP 设备点位。
`opc-ua`	OPC UA 设备点位。
`opc-da`	OPC DA 设备点位。
`snmp`	SNMP 设备点位。
`iec104`	IEC104 设备点位。

请求示例：查询 Modbus 设备全部点位

{
  "id": 1,
  "type": "modbus",
  "group_id": 0
}

请求示例：查询指定点位分组

{
  "id": 1,
  "type": "modbus",
  "group_id": 100
}

Modbus 成功响应示例

{
  "state": 0,
  "state_info": "",
  "data": {
    "point": [
      {
        "id": 101,
        "point_id": "HR_UINT16",
        "name": "holding_register_uint16",
        "address": 10,
        "type": "uint16",
        "device_id": 1,
        "status": 1,
        "describe": "保持寄存器 uint16 示例",
        "function_code": 3,
        "present_value": 123,
        "scale_ratio": 1,
        "value_offset": 0,
        "group_id": 0,
        "bit": 0,
        "update_time": "2026-06-16T10:03:00+08:00",
        "invalid_values": "",
        "valid_range_start": null,
        "valid_range_end": null
      }
    ],
    "total": 1
  }
}

Modbus 成功响应字段说明

字段	类型	含义
`state`	int	业务状态码。成功时为 `0`。
`state_info`	string	状态描述。该接口成功时通常为空字符串。
`data.point`	object[]	点位列表。
`data.total`	int	本次返回的点位数量。传 `group_id` 过滤时为过滤后的数量。
`data.point[].id`	int	采集点位内部 ID。
`data.point[].point_id`	string	外部点位标识。创建点位时未传则可能为空字符串。
`data.point[].name`	string	点位名称。
`data.point[].address`	int	Modbus 点位地址，采集时实际读取地址为 `address - 设备 address_offset`。
`data.point[].type`	string	Modbus 点位数据类型，例如 `bool`、`uint16`、`float32`。
`data.point[].device_id`	int	所属设备 ID。
`data.point[].status`	int	点位采集状态，见点位 `status` 枚举。
`data.point[].describe`	string	点位描述。
`data.point[].function_code`	int	Modbus 功能码，见 `func_code` 枚举。
`data.point[].present_value`	number	当前内存中的点位最新值。设备未采集或未刷新时可能为 `0`。
`data.point[].scale_ratio`	number	缩放系数。
`data.point[].value_offset`	number	值偏移。
`data.point[].group_id`	int	点位分组 ID。
`data.point[].bit`	int	位下标。寄存器布尔点位使用；非位点通常为 `0`。
`data.point[].update_time`	string	点位更新时间，Go JSON time/RFC3339 格式。
`data.point[].invalid_values`	string	无效值列表字符串，多个值用逗号分隔；没有配置时为空字符串。
`data.point[].valid_range_start`	number/null	合法范围最小值。
`data.point[].valid_range_end`	number/null	合法范围最大值。

失败响应示例

请求体无法绑定或 type 不支持：

{
  "state": 2,
  "state_info": "无效参数",
  "data": null
}

设备不存在或不在当前采集器内存中：

{
  "state": 2,
  "state_info": "设备ID不合法",
  "data": null
}

注意事项

该接口返回的是设备内存对象中的点位，不是每次直接查询数据库。
Modbus 点位响应字段中的 function_code 对应创建点位接口请求字段 func_code。
Modbus 点位响应字段中的 type 对应创建点位接口请求字段 type，底层内部字段名为 data_type。
present_value 是当前内存最新值；如果设备未连接、未采集或点位未刷新，不能仅凭该字段判断设备实时可用性。

查询设备列表接口

基本信息

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 103 KB Előzmények Nyers

1. 采集网关接口说明

采集网关服务器请求地址

通用约定

请求格式

返回格式

HTTP 状态码说明

接口列表

网关接口目录

Modbus 通用设备字段

地址规则

word_byte_order 说明

Modbus 功能码

communication 字段格式

接口：健康检查

基本信息

成功返回

调用示例

Modbus 网关接口说明

接口：原始 Modbus 读取

基本信息

请求体结构

成功返回示例

失败返回示例

调用示例

接口：modbus点位读取并转换

基本信息

请求体结构

点位类型和读取长度

点位校验规则

成功返回示例

失败返回示例

调用示例

S7 网关接口说明

S7 网关目标

S7 通用设备字段

S7 地址字段

S7 communication 格式

接口：原始 S7 读取

基本信息

请求体结构

成功返回示例

失败返回示例

调用示例

接口：S7 点位读取并转换

基本信息

请求体结构

支持的数据类型

点位校验规则

成功返回示例

失败返回说明

调用示例

接口：S7 连接扫描

基本信息

请求体结构

扫描范围

成功返回示例

调用示例

BACnet 网关接口说明

BACnet 网关目标

BACnet 通用设备字段

BACnet 对象类型

接口：BACnet 点位读取

基本信息

请求体结构

成功返回示例

失败返回示例

接口：BACnet 点位搜索

基本信息

请求体结构

成功返回示例

调用示例

接口：BACnet BBMD Who-Is 设备发现

基本信息

请求体结构

采集网关环境变量

成功返回示例

失败返回示例

AI 调用决策指南

2. 模方登录接口

接口汇总.md 103 KB

Előzmények Nyers