外设参考
外设配置保存在 /config/peripherals.json。Web 页面负责校验和保存，固件在启动或启用时初始化驱动。新增外设建议先禁用保存，确认接线和引脚后再启用。新配置的开发者模式默认关闭，写配置前使用当前密码在高级设置启用；升级设备保留原有选择。
类型速查
| type | 名称 | 常见用途 | 参考 |
|---|---|---|---|
11 | GPIO 数字输入 | 按键、门磁、PIR、震动 | GPIO 输入 |
12 | GPIO 数字输出 | LED、继电器、蜂鸣器 | GPIO 输出 |
13/14 | 上拉/下拉输入 | 按键和开关 | GPIO 输入 |
15/26 | GPIO/ADC 模拟输入 | 光敏、土壤、烟雾、电压/电流 | ADC 输入 |
17 | PWM 输出 | 调光、调速 | PWM 输出 |
36 | LCD/OLED | SSD1306、SH1106 等 | OLED |
37 | SD 卡 | SPI 模式文件存储 | SD 卡 |
38 | 通用传感器 | DHT、AHT20、SHT31、BH1750、BMP280、MPU6050、超声波等 | 传感器指南 |
41 | 舵机 | SG90、MG996R | 舵机 |
42 | 步进电机 | 28BYJ-48 等 | 步进电机 |
43 | 旋转编码器 | AB 相计数，按压另配 GPIO | 编码器 |
44 | OneWire | DS18B20 | DS18B20 |
45 | NeoPixel | WS2812B 灯带 | NeoPixel |
47 | TM1637 | 四位数码管 | TM1637 |
48 | 433MHz RF | OOK 收发和学习 | RF 模块 |
49 | 雷达输入 | RCWL-0516 | GPIO 输入 |
50 | DS1302 RTC | 三线实时时钟 | 示例 |
51 | Modbus 设备 | RS485 从站映射 | Modbus 设备 |
52 | LCD1602 | PCF8574 I2C 字符屏 | LCD1602 |
53 | 红外接收 | VS1838B 等 | 红外 |
54 | MFRC522 RFID | SPI 读卡 | RFID |
55 | I2C IO 扩展器 | 通过共享 I2C 提供逻辑 GPIO | PCF8574 IO 扩展器 |
56 | 图形显示设备 | 仅 ESP32-S3；SPI ST7789 / ILI9341（最大 240×320），新增 S3 ST7701 RGB 480×480 测试后端，可选 GT911 | 设备屏幕 |
57 | PCA9685 PWM | 共享 I2C、显式 OE 与通道配置 | 见外设配置和运行时能力描述 |
60 | 设备事件 | 逻辑事件源，无物理引脚 | 设备事件 |
SENSOR_GENERIC（type 38）通过 params.driver 选择注册 I2C 驱动，或通过数字 params.sensorType 选择本地传感器；sensorCategory 属于读取动作参数。INA226 电压/电流/功率采集见 INA226，NTC 热敏电阻测温见 NTC 热敏电阻。MODBUS_DEVICE 和 DEVICE_EVENT 不占用 GPIO 引脚。
RGB 的 st7701_type1 只支持当前初始化档和 480×480。微雪 Rev4 已完成代码接入，但既有实物记录出现漂移及横向、纵向卷边，物理验收未通过；ESP32-4848S040 等其他 RGB 板仍需核对初始化序列、时序、引脚和复位/背光电路，不能只因尺寸和触摸型号相同就直接套用。CAN 只有类型枚举/占位，没有通用驱动、采集缓存和信号解码链路；设备屏幕只能显示已经进入统一采集结果的数据。
配置要点
每个外设至少需要唯一 id、显示名称、type、引脚数组和 enabled：
{
"id": "relay_01",
"name": "继电器",
"type": 12,
"enabled": false,
"pinCount": 1,
"pins": [26],
"params": { "initialState": 1 }
}- 引脚按外设类型填写；未使用位置可省略或使用
255。 - I2C 外设要填写 SDA、SCL 和地址；多个设备可共用总线但地址不能冲突。
- DHT 等时序传感器要保持足够采样间隔；ADC 输入不能超过芯片允许电压。
- GPIO 输出的“高/低”是物理电平，继电器模块若低电平有效，请使用反转动作
13/14并按实际电路设置初始物理电平。 - 外部模块使用前确认 3.3V/5V 电平、电源电流、共地和终端电阻。
引脚原则
不同开发板的保留引脚不同，接线前以芯片手册和开发板原理图为准。通用原则：
- 避开连接 Flash/PSRAM 的引脚以及 USB/JTAG、BOOT、串口下载占用的引脚。
- ESP32 经典款的 ADC2 在 WiFi 工作时受限，模拟采集优先使用 ADC1。
- I2C/SPI/UART 引脚可以在 Web 中配置。支持共享的总线须满足驱动、引脚、速率和地址/片选等兼容条件，并通过资源预检；普通 GPIO、片选和其他独占资源不能重复占用。不要仅凭相同引脚推断两个驱动能够共享总线。
- 使用“外设配置 → 引脚校验”检查固件已知限制；校验通过不代表接线、电平和电气安全一定正确。
配置验证
- 保存禁用草稿，完成接线和资源审核后单独启用，再查看运行状态。
- 用“读取”或“写入”接口单独验证，不要直接用复杂规则排错。
- 查看设备日志，确认驱动初始化成功。
- 再在“外设执行”中添加触发器和动作。
常用 API：GET /api/peripherals/types、GET /api/peripherals、GET /api/peripherals/read、POST /api/peripherals/write、GET /api/peripherals/validate-pins。接口详情见 API 参考。
常见问题
| 问题 | 排查顺序 |
|---|---|
| 外设列表没有该类型 | 查看 /api/system/capabilities 和“功能配置”，确认编译宏与预算状态 |
| 初始化失败 | 检查供电、引脚、I2C 地址、串口参数和日志 |
| 读数为 0 或异常 | 检查传感器类别、单位、采样间隔和校准参数 |
| 规则动作无效 | 确认外设已启用、目标 ID 正确、动作类型匹配 |
| 启用后设备变慢 | 查看健康监控，关闭暂不用的重型功能或减少轮询/并发 |
更多接线和参数示例见 示例索引。