# BACnet HTTP 接口说明

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

## 通用响应

所有接口成功或失败均返回 HTTP `200`，业务结果由响应体 `code` 判断。

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

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

## 设备字段

以下字段用于 `/bacnet/read_points` 和 `/bacnet/search_points`。

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| `ip` | string | 是 | 无 | BACnet/IP 设备地址。 |
| `bacnet_device_id` | integer | 是 | 无 | BACnet 设备对象实例号，范围 `0..4194303`。 |
| `port` | integer | 否 | `47808` | BACnet/IP UDP 端口。 |

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

```json
{
  "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` | 多状态值 |

## 接口一：读取点位

### URL

```http
POST /api/dc-gateway/bacnet/read_points
```

### 请求体

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

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

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `points` | object[] | 是 | 至少 1 个点位。 |
| `points[].object_type` | string | 是 | BACnet 对象类型。 |
| `points[].object_id` | integer | 是 | BACnet 对象实例号，范围 `0..4194303`。 |

### 成功返回

```json
{
  "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
      }
    ]
  }
}
```

## 接口二：搜索点位

### URL

```http
POST /api/dc-gateway/bacnet/search_points
```

### 请求体

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

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

### 成功返回

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

## 测试默认设备

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

| 字段 | 默认值 |
|---|---|
| `BACNET_DEVICE_IP` | `192.168.75.240` |
| `BACNET_DEVICE_ID` | `12345` |
| `BACNET_PORT` | `47808` |

本地 BACnet 客户端绑定地址默认自动推断，可通过以下环境变量覆盖：

| 字段 | 默认值 |
|---|---|
| `BACNET_LOCAL_IP` | 自动按到目标设备的路由推断 |
| `BACNET_LOCAL_MASK` | `24` |
| `BACNET_LOCAL_PORT` | 自动选择空闲 UDP 端口 |