# 外设参考

外设配置保存在 `/config/peripherals.json`。Web 页面负责校验和保存，固件在启动或启用时初始化驱动。新增外设建议先禁用保存，确认接线和引脚后再启用。新配置的开发者模式默认关闭，写配置前使用当前密码在高级设置启用；升级设备保留原有选择。

```mermaid
flowchart LR
  A[确认模块和供电] --> B[选择外设类型]
  B --> C[填写 ID/引脚/参数]
  C --> D[保存为禁用]
  D --> E[接线及资源审核后单独启用]
  E --> F[读写验证后接入规则]
```

## 类型速查

| type | 名称 | 常见用途 | 参考 |
| ---: | --- | --- | --- |
| `11` | GPIO 数字输入 | 按键、门磁、PIR、震动 | [GPIO 输入](https://www.fastbee.cn/doc/device/v2/peripherals/gpio-input.md) |
| `12` | GPIO 数字输出 | LED、继电器、蜂鸣器 | [GPIO 输出](https://www.fastbee.cn/doc/device/v2/peripherals/gpio-output.md) |
| `13/14` | 上拉/下拉输入 | 按键和开关 | [GPIO 输入](https://www.fastbee.cn/doc/device/v2/peripherals/gpio-input.md) |
| `15/26` | GPIO/ADC 模拟输入 | 光敏、土壤、烟雾、电压/电流 | [ADC 输入](https://www.fastbee.cn/doc/device/v2/peripherals/adc-input.md) |
| `17` | PWM 输出 | 调光、调速 | [PWM 输出](https://www.fastbee.cn/doc/device/v2/peripherals/pwm-output.md) |
| `36` | LCD/OLED | SSD1306、SH1106 等 | [OLED](https://www.fastbee.cn/doc/device/v2/peripherals/oled-usage-guide.md) |
| `37` | SD 卡 | SPI 模式文件存储 | [SD 卡](https://www.fastbee.cn/doc/device/v2/peripherals/storage-sd-card.md) |
| `38` | 通用传感器 | DHT、AHT20、SHT31、BH1750、BMP280、MPU6050、超声波等 | [传感器指南](https://www.fastbee.cn/doc/device/v2/peripherals/sensor-guide-complete.md) |
| `41` | 舵机 | SG90、MG996R | [舵机](https://www.fastbee.cn/doc/device/v2/peripherals/servo.md) |
| `42` | 步进电机 | 28BYJ-48 等 | [步进电机](https://www.fastbee.cn/doc/device/v2/peripherals/stepper-motor.md) |
| `43` | 旋转编码器 | AB 相计数，按压另配 GPIO | [编码器](https://www.fastbee.cn/doc/device/v2/peripherals/encoder.md) |
| `44` | OneWire | DS18B20 | [DS18B20](https://www.fastbee.cn/doc/device/v2/peripherals/sensor-ds18b20.md) |
| `45` | NeoPixel | WS2812B 灯带 | [NeoPixel](https://www.fastbee.cn/doc/device/v2/peripherals/neopixel.md) |
| `47` | TM1637 | 四位数码管 | [TM1637](https://www.fastbee.cn/doc/device/v2/peripherals/display-tm1637.md) |
| `48` | 433MHz RF | OOK 收发和学习 | [RF 模块](https://www.fastbee.cn/doc/device/v2/peripherals/rf-module.md) |
| `49` | 雷达输入 | RCWL-0516 | [GPIO 输入](https://www.fastbee.cn/doc/device/v2/peripherals/gpio-input.md) |
| `50` | DS1302 RTC | 三线实时时钟 | [示例](https://www.fastbee.cn/doc/device/v2/examples/17-ds1302-rtc.md) |
| `51` | Modbus 设备 | RS485 从站映射 | [Modbus 设备](https://www.fastbee.cn/doc/device/v2/peripherals/modbus-device.md) |
| `52` | LCD1602 | PCF8574 I2C 字符屏 | [LCD1602](https://www.fastbee.cn/doc/device/v2/peripherals/display-lcd1602.md) |
| `53` | 红外接收 | VS1838B 等 | [红外](https://www.fastbee.cn/doc/device/v2/peripherals/ir-remote.md) |
| `54` | MFRC522 RFID | SPI 读卡 | [RFID](https://www.fastbee.cn/doc/device/v2/peripherals/rfid-mfrc522.md) |
| `55` | I2C IO 扩展器 | 通过共享 I2C 提供逻辑 GPIO | [PCF8574 IO 扩展器](https://www.fastbee.cn/doc/device/v2/peripherals/io-expander-pcf8574.md) |
| `56` | 图形显示设备 | 仅 ESP32-S3；SPI ST7789 / ILI9341（最大 240×320），新增 S3 ST7701 RGB 480×480 测试后端，可选 GT911 | [设备屏幕](https://www.fastbee.cn/doc/device/v2/system/screen-panel.md) |
| `57` | PCA9685 PWM | 共享 I2C、显式 OE 与通道配置 | 见外设配置和运行时能力描述 |
| `60` | 设备事件 | 逻辑事件源，无物理引脚 | [设备事件](https://www.fastbee.cn/doc/device/v2/peripherals/device-event.md) |

`SENSOR_GENERIC`（type `38`）通过 `params.driver` 选择注册 I2C 驱动，或通过数字 `params.sensorType` 选择本地传感器；`sensorCategory` 属于读取动作参数。INA226 电压/电流/功率采集见 [INA226](https://www.fastbee.cn/doc/device/v2/peripherals/sensor-ina226.md)，NTC 热敏电阻测温见 [NTC 热敏电阻](https://www.fastbee.cn/doc/device/v2/peripherals/sensor-ntc.md)。`MODBUS_DEVICE` 和 `DEVICE_EVENT` 不占用 GPIO 引脚。

RGB 的 `st7701_type1` 只支持当前初始化档和 480×480。微雪 Rev4 已完成代码接入，但既有实物记录出现漂移及横向、纵向卷边，物理验收未通过；ESP32-4848S040 等其他 RGB 板仍需核对初始化序列、时序、引脚和复位/背光电路，不能只因尺寸和触摸型号相同就直接套用。CAN 只有类型枚举/占位，没有通用驱动、采集缓存和信号解码链路；设备屏幕只能显示已经进入统一采集结果的数据。

## 配置要点

每个外设至少需要唯一 `id`、显示名称、`type`、引脚数组和 `enabled`：

```json
{
  "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、片选和其他独占资源不能重复占用。不要仅凭相同引脚推断两个驱动能够共享总线。
* 使用“外设配置 → 引脚校验”检查固件已知限制；校验通过不代表接线、电平和电气安全一定正确。

## 配置验证

1. 保存禁用草稿，完成接线和资源审核后单独启用，再查看运行状态。
2. 用“读取”或“写入”接口单独验证，不要直接用复杂规则排错。
3. 查看设备日志，确认驱动初始化成功。
4. 再在“外设执行”中添加触发器和动作。

常用 API：`GET /api/peripherals/types`、`GET /api/peripherals`、`GET /api/peripherals/read`、`POST /api/peripherals/write`、`GET /api/peripherals/validate-pins`。接口详情见 [API 参考](https://www.fastbee.cn/doc/device/v2/dev/api-reference.md)。

## 常见问题

| 问题 | 排查顺序 |
| --- | --- |
| 外设列表没有该类型 | 查看 `/api/system/capabilities` 和“功能配置”，确认编译宏与预算状态 |
| 初始化失败 | 检查供电、引脚、I2C 地址、串口参数和日志 |
| 读数为 0 或异常 | 检查传感器类别、单位、采样间隔和校准参数 |
| 规则动作无效 | 确认外设已启用、目标 ID 正确、动作类型匹配 |
| 启用后设备变慢 | 查看健康监控，关闭暂不用的重型功能或减少轮询/并发 |

更多接线和参数示例见 [示例索引](https://www.fastbee.cn/doc/device/v2/examples.md)。
