data-collector-debugtool/docs/bacnet-http-api.md

BACnet HTTP 接口说明

目标

本服务通过 HTTP 接口连接 BACnet/IP 设备。BACnet 功能使用 BAC0 实现，当前提供点位读取和点位搜索。

当前仅支持 BACnet/IP。

接口列表

• POST /api/dc-gateway/bacnet/read_points：按点位对象读取，固定返回 present-value。
• POST /api/dc-gateway/bacnet/search_points：读取设备 object-list，搜索常见 BACnet 点位对象并返回基础信息和值。
• GET /api/dc-gateway/health：健康检查。

通用返回约定

接口业务结果统一使用 HTTP 200 返回，是否成功由 JSON 中的 code 判断。

成功：

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

失败：

{
  "code": 1,
  "msg": "BACnet communication error",
  "data": {
    "points": []
  }
}

字段说明：

字段	类型	说明
code	integer	0 表示成功，1 表示失败。
msg	string	成功时为 success，失败时为错误信息。
data	object	接口数据。

data 固定为对象。两个 BACnet 接口都会在 data.device 返回设备信息，点位列表返回在 data.points。

设备参数校验

以下字段用于 /bacnet/read_points 和 /bacnet/search_points 请求体顶层。

字段	是否必传	默认值	校验	说明
ip	是	无	必须是合法 IP 地址	BACnet/IP 设备地址。
bacnet_device_id	是	无	0..4194303	BACnet 设备对象实例号。
port	否	47808	1..65535	BACnet/IP UDP 端口。

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

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

对象类型

请求中的 object_type 支持常见写法，例如 AnalogInput、analogInput、analog-input。响应统一返回 AnalogInput 这类格式。

常见点位对象类型：

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

/bacnet/search_points 只返回上表中的常见点位对象类型。/bacnet/read_points 可按对象类型读取 present-value，但目标对象必须支持该属性。

接口一：读取点位

URL

POST /api/dc-gateway/bacnet/read_points

请求体

read_points 固定读取每个对象的 present-value。

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

字段说明：

字段	类型	必填	校验	说明
points	object[]	是	至少 1 个点位	BACnet 点位对象列表。
points[].object_type	string	是	合法 BACnet 对象类型写法	BACnet 对象类型。
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": []
  }
}

请求字段校验失败：

{
  "code": 1,
  "msg": "points: List should have at least 1 item after validation, not 0",
  "data": {
    "points": []
  }
}

接口二：搜索点位

URL

POST /api/dc-gateway/bacnet/search_points

请求体

搜索点位只需要设备信息。服务会读取设备对象的 object-list，并过滤常见点位对象类型。

{
  "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。

失败返回

{
  "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 客户端绑定

网关会为每次 BACnet 请求启动本地 BACnet 客户端，并自动推断到目标设备的本机地址。可通过环境变量覆盖：

字段	默认值	说明
BACNET_LOCAL_IP	自动按到目标设备的路由推断	本地 BACnet 客户端绑定 IP。
BACNET_LOCAL_MASK	24	本地 BACnet 客户端网络掩码位数。
BACNET_LOCAL_PORT	自动选择空闲 UDP 端口	本地 BACnet 客户端绑定 UDP 端口。

测试默认设备

BACnet 集成测试默认设备参数：

字段	默认值
BACNET_DEVICE_IP	192.168.75.240
BACNET_DEVICE_ID	12345
BACNET_PORT	47808