设备配置

driver-box 采用 JSON 格式进行设备配置，所有配置文件位于 res/driver/<plugin>/ 目录下。

设备配置的用途

设备配置是 driver-box 的核心组成部分，它实现了设备抽象和协议解耦，使得系统能够：

• 统一设备管理：通过标准化的 JSON 配置描述不同协议的设备，无需修改代码即可接入新设备
• 协议插件化：设备配置与协议插件分离，同一设备模型可通过不同协议插件接入（如 Modbus、MQTT）
• 灵活扩展：通过配置即可定义点位、读写模式、数据转换规则等，满足多样化设备场景
• 云端同步：支持模型 ID 关联云端设备模型，实现配置与云端的一致性

本文档详细介绍配置文件的结构、各层级参数说明、以及完整的配置示例。

快速导航

• 配置文件放置
• 配置层级关系
• 顶层配置
• 设备模型（DeviceModel）
• 设备（Device）
• 点位（Point）
• 连接配置（connections）
• 协议扩展参数
• 配置示例
• 配置验证

配置文件放置

配置文件应放置在对应协议插件的目录下：

res/
├── driver/
│   ├── modbus/
│   │   └── config.json
│   ├── mqtt/
│   │   └── config.json
│   └── bacnet/
│       └── config.json

配置代码结构

配置对应的 Go 结构体定义位于 pkg/config/device_config.go

配置层级关系

graph TD
    A[config.json] --> B[deviceModels]
    A --> C[connections]
    A --> D[protocolName]

    B --> E[DeviceModel]
    E --> F[devicePoints]
    E --> G[devices]

层级说明：

• config.json - 顶层配置文件
• deviceModels - 设备模型数组，定义设备类型和点位
• connections - 连接配置，定义设备通讯参数
• protocolName - 协议插件名称
• DeviceModel - 设备模型，包含点位列表和设备实例
• devicePoints - 点位定义数组
• devices - 设备实例数组

顶层配置

配置结构

配置文件结构

完整的配置文件包含以下结构：

config.json

{
  "deviceModels": [
    {
      "name": "模型名称",
      "description": "模型描述",
      "modelId": "云端模型ID",
      "attributes": {},
      "devicePoints": [],
      "devices": []
    }
  ],
  "connections": {},
  "protocolName": "插件名称"
}

配置参数

顶层配置参数

参数	类型	必填	说明
deviceModels	array	是	设备模型数组
connections	object	是	连接配置对象
protocolName	string	是	协议插件名称（如 modbus、mqtt）

设备模型（DeviceModel）

配置对应的 Go 结构体定义位于 pkg/config/device_config_model.go

设备模型定义了一类设备的数据结构和参数，一个模型可以对应多个设备实例。

结构示例

{
  "name": "温湿度传感器",
  "description": "Modbus温湿度传感器",
  "modelId": "model-001",
  "attributes": {
    "manufacturer": "Example Corp",
    "version": "1.0"
  },
  "devicePoints": [...],
  "devices": [...]
}

参数说明

模型配置参数

参数	类型	必填	说明
name	string	是	模型名称（同一配置内唯一）
description	string	是	模型描述
modelId	string	是	云端模型ID（用于云同步）
attributes	object	否	扩展属性，自定义键值对
devicePoints	array	是	模型点位定义
devices	array	是	该模型下的设备实例

设备（Device）

配置对应的 Go 结构体定义位于 pkg/config/device_config_device.go

设备是设备模型的具体实例，一个模型可以对应多个设备。

结构示例

{
  "id": "device-001",
  "description": "会议室传感器",
  "connectionKey": "modbus-tcp-01",
  "properties": {
    "unitID": "1"
  },
  "driverKey": ""
}

参数说明

设备配置参数

参数	类型	必填	说明
id	string	是	设备唯一标识符（全局唯一）
description	string	是	设备描述
connectionKey	string	是	关联的连接配置键（对应 connections 中的键名）
properties	object	否	设备属性（协议相关，如 Modbus 的 unitID），类型为 map[string]string
driverKey	string	否	设备层驱动引用

点位（Point）

点位是设备模型中的最小数据单元，用于定义采集和控制的参数。

配置对应的 Go 结构体和方法定义位于 pkg/config/device_config_model_point.go

结构示例

{
  "name": "temperature",
  "description": "温度",
  "valueType": "float",
  "readWrite": "R",
  "reportMode": "realTime",
  "scale": 0.1,
  "decimals": 1,
  "units": "℃"
}

参数说明

基础点位参数

参数	类型	必填	说明
name	string	是	点位名称（模型内唯一）
description	string	否	点位描述
valueType	string	是	数据类型：int（整数）、float（浮点数）、string（字符串）。driver-box只支持这三种数据类型，已能够涵盖所有设备场景。
readWrite	string	是	读写权限：R（只读）、W（只写）、RW（读写）
reportMode	string	否	上报模式：realTime（实时上报，读到数据即触发导出）、change（变化上报，与影子中值不一致才触发）
scale	number	否	缩放因子（用于数值转换）
decimals	number	否	小数位数保留
units	string	否	单位
enums	array	否	枚举值数组，用于界面展示和值映射，包含name（枚举名称）、value（枚举值）、icon（枚举图标，可选）

枚举配置示例

{
  "name": "switch",
  "description": "开关状态",
  "valueType": "int",
  "readWrite": "RW",
  "enums": [
    {"name": "关闭", "value": 0, "icon": "off"},
    {"name": "开启", "value": 1, "icon": "on"}
  ]
}

连接配置（connections）

连接配置定义了与设备通讯的参数，具体格式由协议插件决定。多个设备可以共用同一个连接配置。

通用连接结构

{
  "connections": {
    "connection-name": {
      // 协议特定参数
    }
  }
}

各协议插件的连接配置参数请参考对应的插件文档：

• Modbus 插件
• MQTT 插件
• BACnet 插件
• DL/T 645 插件

协议扩展参数

协议插件可以在点位中添加扩展参数，用于定义协议特定的配置。这些扩展参数直接定义在点位对象中，无需嵌套在 properties 字段。

Modbus 扩展示例

{
  "name": "temperature",
  "startAddress": "40001",
  "primaryTable": "HOLDING_REGISTER",
  "rawType": "Float32",
  "duration": "5s",
  "byteSwap": false,
  "wordSwap": false
}

MQTT 扩展示例

{
  "name": "temperature",
  "topic": "device/temperature",
  "qos": 1,
  "retain": false
}

注意：不同协议插件的扩展参数不同，具体请参考对应插件的文档。

配置示例

点击查看完整的配置示例

以下是一个完整的 Modbus 设备配置示例，包含协议特定扩展参数（如 startAddress、primaryTable 等）：

{
  "deviceModels": [
    {
      "name": "温湿度传感器",
      "description": "Modbus温湿度传感器",
      "modelId": "modbus-001",
      "attributes": {
        "manufacturer": "Example",
        "version": "1.0"
      },
      "devicePoints": [
        {
          "name": "temperature",
          "description": "温度",
          "valueType": "float",
          "readWrite": "R",
          "reportMode": "realTime",
          "scale": 0.1,
          "decimals": 1,
          "units": "℃",
          "startAddress": "40001",
          "primaryTable": "HOLDING_REGISTER",
          "rawType": "Float32",
          "duration": "5s"
        },
        {
          "name": "humidity",
          "description": "湿度",
          "valueType": "float",
          "readWrite": "R",
          "scale": 0.1,
          "decimals": 1,
          "units": "%",
          "startAddress": "40002",
          "primaryTable": "HOLDING_REGISTER",
          "rawType": "Float32",
          "duration": "5s"
        }
      ],
      "devices": [
        {
          "id": "sensor-001",
          "description": "会议室传感器",
          "connectionKey": "modbus-tcp-01",
          "properties": {
            "unitID": "1"
          }
        }
      ]
    }
  ],
  "connections": {
    "modbus-tcp-01": {
      "address": "192.168.1.100:502",
      "mode": "tcp",
      "timeout": 5000,
      "retry": 3,
      "minInterval": 100
    }
  },
  "protocolName": "modbus"
}

配置验证

创建配置文件后，建议进行以下检查：

1. JSON 语法验证：使用在线 JSON 验证工具
2. 必需字段检查：确保所有标记为”必填”的字段都已填写
3. 引用完整性：确保 connectionKey 在 connections 中存在
4. 设备 ID 唯一性：确保设备 ID 全局唯一