外设配置指南
“外设配置”描述硬件资源，保存到 /config/peripherals.json；“外设执行”决定何时读取、控制或上报。保存传感器配置不会自动建立周期采集规则。
操作顺序
- 确认芯片、开发板、模块供电、电平和接线。
- 新建外设并保持禁用，保存 ID、类型、引脚及参数。
- 完成引脚和总线资源检查，再单独启用外设，检查初始化结果。
- 单项读取或受控写入通过后再接入规则。禁用状态不能作为正常读写验证对象。
配置写入及手动输出操作受开发者模式控制。新配置和恢复出厂配置默认关闭；使用当前密码在“设备配置 → 高级设置”启用后再修改。升级设备保留原有设置，不能据此推断所有既有设备的当前状态。
基本字段
下面是低电平有效继电器的禁用草稿；initialState: 1 表示启用时输出高电平。实际是否释放由模块电路决定。
json
{
"id": "relay_01",
"name": "低电平有效继电器",
"type": 12,
"enabled": false,
"pinCount": 1,
"pins": [26],
"params": { "initialState": 1 }
}id 必须唯一，后续动作引用该 ID。pinCount 必须与有效引脚数量匹配；共享 I2C 总线引用和虚拟外设可使用空数组。引脚数字不是跨芯片通用接线方案，示例须按目标板卡调整。
持久参数与动作参数
| 外设 | type | 持久参数示例 |
|---|---|---|
| 数字输入/上拉/下拉 | 11/13/14 | inputMode、invertLogic、debounceMs、reportMode |
| 数字输出 | 12 | initialState；无源蜂鸣器另用 passive 和 PWM 参数 |
| 模拟输入 | 15/26 | attenuation、resolution、sampleCount、工程量转换参数 |
| PWM | 17 | pwmChannel、pwmFrequency、pwmResolution、defaultDuty |
| OLED | 36 | width、height、interface: 2、contrast，当前地址固定 0x3C |
| DHT/超声 | 38 | 数字 sensorType：0=DHT11、1=DHT22、3=超声；sampleInterval |
| 注册 I2C 传感器 | 38 | driver、数字 address、frequency、sampleInterval；可引用 busPeripheralId |
| 舵机/步进/编码器 | 41/42/43 | 见各自专页，不能互换通用 PWM 或角度参数 |
| DS18B20 | 44 | 数据引脚；读取规则选择 DS18B20 类别 |
| NeoPixel | 45 | count、brightness |
| TM1637/LCD1602/RFID | 47/52/54 | 见对应专页 |
| IO 扩展器/PCA9685 | 55/57 | 驱动、父总线与逻辑通道；编译支持和资源准入均须满足 |
| 设备事件 | 60 | 无物理引脚；动作 21 的目标为事件 ID |
sensorCategory 属于读取动作 19 的 JSON 字符串参数，不是通用传感器外设的持久驱动选择字段。channelField 选择驱动通道，dataField 是 MQTT 属性标识，两者用途不同。
初始化、读取与上报
启用成功仅说明资源和驱动初始化通过，不代表有效业务数据已产生。配置定时读取规则后，检查读取结果、质量、时间戳及上报。温度、湿度等通道使用 外设ID_通道名 缓存源，变化事件使用 ds:外设ID_通道名，模板使用 ${外设ID.通道名}。平台触发器响应收到的云端指令，本地采集上报不会自动等价为平台指令。
常用接口及认证要求见 API 参考，类型、接线与功能边界见 外设参考，规则见 外设执行。
迁移与保护
导入前备份当前配置；跨芯片迁移重新核对引脚、总线、Flash/PSRAM、功能编译和运行时预算。不要用公开示例覆盖在线设备配置。输出示例均先禁用保存，按实物反馈验证启用时的安全电平；配置成功、动作入队和物理动作完成分别检查。