外设与传感器配置总览

本页按当前固件的外设类型和采集动作整理选择方法。类型枚举、编译支持、用户启用、资源准入及初始化成功是不同状态；确认实际固件和功能配置后，再连接硬件并逐项验证。

选择接口和类型

接口/功能	外设配置	读取或控制入口
按键、门磁、数字模块	GPIO11/13/14，边沿中断18/19/20	GPIO/事件触发；数字采集动作19
模拟电压或模块 AO	GPIO15 / ADC26	analog；电压、电流类别另设校准
DHT11/DHT22	type38，sensorType=0/1	动作19，dht11/dht22
HC-SR04	type38，sensorType=3，Trig/Echo两脚	动作19，ultrasonic
DS18B20	type44，DQ一脚	动作19，ds18b20；按索引或ROM选择
AHT20、SHT30/SHT31	type38，driver=注册名称	动作19，temperature/humidity
BH1750	type38，driver=BH1750	illuminance，lx
BMP280	type38，driver=BMP280	temperature、pressure(hPa)、altitude(m)
MPU6050	type38，driver=MPU6050，mode=0/1	模式0加速度(m/s²)，模式1角速度(rad/s)，均含temperature
INA226/ADS1115	type38，driver=注册名称	当前驱动元数据和专用参数；见部署专页
PWM/舵机	type17/41	PWM raw duty；舵机HTTP angle按配置映射
本地四脚步进电机	type42	连续正转、反转、调速、停止，无定步到位接口
编码器	type43，A/B两脚	pulse/frequency类别，count/delta/direction/rpm
OLED/LCD1602/TM1637	type36/52/47	各自显示入口，不能互换动作
MFRC522	type54，五脚SPI+RST	读卡事件；受限Classic数据块操作
SD卡	type37，interface=1，四脚SPI	Web沙箱文件操作，动作38状态、动作40持续记录
红外/RF	type53/48	解码事件和学习；红外只有接收，RF按模式收发
Modbus	UART+协议配置，生成type51虚拟目标	专用采集与控制；FC16即十进制16/十六进制0x10

触摸 type21、CAN 等枚举不表示已实现通用驱动。DS3231、AHT21、EEPROM等不能仅因接口为 I2C 就当作已注册驱动；可用名称以当前固件发布的元数据为准。

持久配置与读取规则

I2C 注册传感器使用 driver、数字 address、frequency、sampleInterval；可选择两脚 SDA/SCL，或选择 busPeripheralId 并清空本地引脚，二者不能同时填写。DHT 使用数字 sensorType；sensorCategory 是读取动作参数，不是外设驱动选择字段。

json

{
  "id": "room_sensor",
  "name": "室内温湿度",
  "type": 38,
  "enabled": false,
  "pinCount": 2,
  "pins": [21, 22],
  "params": {
    "driver": "SHT31",
    "address": 68,
    "frequency": 100000,
    "sampleInterval": 5000
  }
}

GPIO21/22 仅为经典 ESP32 示例。检查目标板卡引脚后启用外设，再配置定时读取规则。动作参数是 JSON 字符串：

json

{
  "targetPeriphId": "room_sensor",
  "actionType": 19,
  "actionValue": "{\"periphId\":\"room_sensor\",\"channelField\":\"temperature\",\"dataField\":\"roomTemperature\",\"decimalPlaces\":2}",
  "useReceivedValue": false
}

channelField 是驱动通道，dataField 是平台属性 ID。缓存源为 room_sensor_temperature，变化事件为 ds:room_sensor_temperature，模板为 ${room_sensor.temperature}。先建立有效采集，再将数据源接入报警、显示、温控或记录规则；平台触发器响应收到的云端指令，不代替本地采集事件。

I2C最小物理采样间隔和可用通道见 AHT20、SHT31、BH1750、BMP280、MPU6050。保存间隔不自动创建周期任务；失败、旧缓存和缺失数据不能冒充新鲜成功读数。

供电、电平与输出

模块 VCC/GND 分别接合适电源和共地，DO 接数字输入，AO 经适当前端接 ADC；不要把“VCC→DO→GPIO→GND”当作串联电源接线。模块型号、跳线和比较器设置决定输出极性，烟雾、光照、火焰等不能统一假设有效电平。

ADC衰减档不保证所有芯片都具有同一3.3V精确量程，GPIO输入不得超过允许电压。5V模块的输出和上拉须电平转换或核对电路。电压分压比和电流零偏/灵敏度按 ADC侧实测标定，交流有效值不能用短窗口均值替代。

数字输出高/低表示物理电平，继电器初始电平须符合实际模块和触点；LED、无源蜂鸣器、PWM调光和舵机使用不同输出语义。舵机动作4是raw duty，不是角度；步进目标RPM受软件调度限制，不提供机械到位保证。资源冲突、SDK写入失败或清理失败应明确保留错误，不能自动重放未知动作。

显示与存储

当前 OLED type36 只开放 I2C、地址0x3C，尺寸及控制器映射见 OLED。LCD1602字符屏通过HTTP的print/clear/backlight入口，不支持TM1637的24～26动作或OLED的27动作。MFRC522的UID字符串事件不是数值采集缓存，不能直接使用 ${rfid.uid}。

SD仅支持SPI挂载，不能通过通用SPI类型3替代type37。SD不自动接管系统日志、MQTT离线队列或任意文件追加动作；动作40是有界单来源记录器，具体限制见 SD卡。

验证范围

配置从禁用草稿开始，核对资源后单独启用、读取或受控写入，再启用规则。开发者模式默认关闭，写配置前用当前密码启用；升级设备保留自己的选择。

主机测试、对应环境构建、设备API/Web、实际接线与物理反馈、长期稳定性分别记录。PSRAM容量不能替代内部DRAM、最大连续块及任务栈预算；本页不提供未经测量的固定Flash/RAM节省数字，也不以一台S3的结果覆盖其他芯片。具体接线与故障边界使用外设参考的专页。

外设与传感器配置总览 ​

选择接口和类型 ​

持久配置与读取规则 ​

供电、电平与输出 ​

显示与存储 ​

验证范围 ​