Sensor and Module Guide
About 13 min
Sensor and Module Guide
Synchronized Device Documentation
This page corresponds to the synchronized Chinese source. Commands, JSON examples, API paths, field names, and screenshots are kept aligned with the Chinese device-side source documentation.
What This Page Covers
- Peripheral capability, supported device types, and wiring constraints.
- Web console configuration fields and recommended parameter values.
- PeriphExec integration, validation steps, and troubleshooting notes.
Source Reference
The detailed operational source is preserved below so implementation details stay exact while the English navigation, titles, and reading path remain available.
传感器与模块完整指南
本文档是 FastBee-Arduino 项目所有支持的传感器、模块和外设的完整参考手册，涵盖接线说明、配置参数、JSON示例、外设执行联动、编译开关和引脚占用等信息。
传感器和模块都先在“外设配置”中登记为硬件对象，再由“外设执行”规则负责周期采集、阈值判断、显示或上报。
传感器读数并不是直接上报平台：它先经过外设配置、驱动读取和数据缓存，再由外设执行、显示屏或 MQTT 上报消费。
GPIO、ADC 和 PWM 类模块接入前先核对引脚能力、电平、供电和默认状态；会驱动负载的模块必须先禁用保存并单项验证。
目录
- 1. GPIO 基础模块
- 2. 显示与灯光模块
- 3. 时钟模块
- 4. 温湿度传感器
- 5. 环境与距离传感器
- 6. 运动与姿态传感器
- 7. 控制模块
- 8. 通信模块
- 9. 环境检测传感器
- 10. 输入设备
- 11. 识别与存储模块
- 附录A：编译开关对照表
- 附录B：引脚分配建议
- 附录C：资源消耗参考
1. GPIO 基础模块
1.1 GPIO 数字输出
- 类型ID: 12 (GPIO_DIGITAL_OUTPUT)
- 应用场景: LED指示灯、继电器控制、蜂鸣器、直流电机开关
- 接线: GPIO引脚 → 负载 → GND（或VCC，视电路而定）
- 配置示例: 详见 gpio-output.md
1.2 GPIO 数字输入
- 类型ID: 11/13/14/18/19/20/21
- 支持类型:
- 11: 浮空输入
- 13: 内部上拉（按键常用）
- 14: 内部下拉（PIR常用）
- 18/19/20: 中断输入（上升沿/下降沿/变化）
- 21: 触摸输入（仅ESP32特定引脚）
- 按键事件: 单击、双击、长按2s/5s/10s、按下、释放
- 配置示例: 详见 gpio-input.md
1.3 PWM 输出
- 类型ID: 17 (GPIO_PWM_OUTPUT)
- 应用场景: 呼吸灯、电机调速、舵机控制、LED调光
- 参数: pwmChannel(0-15), pwmFrequency(1-40000Hz), pwmResolution(1-20bit)
- 配置示例: 详见 pwm-output.md
1.4 ADC 模拟输入
- 类型ID: 26 (ADC)
- 应用场景: 电位器、光敏电阻、声音传感器、火焰/烟雾传感器
- ESP32限制: 仅GPIO32-39支持ADC1（推荐），ADC2与WiFi冲突
- ESP32-S3: GPIO1-20支持ADC1
- 分辨率: 9-12bit可配置
- 配置示例: 详见 adc-input.md
2. 显示与灯光模块
2.1 NeoPixel RGB灯带 (WS2812B)
- 类型ID: 45 (NEO_PIXEL)
- 编译开关:
FASTBEE_ENABLE_LED_SCREEN - Flash占用: ~10KB (RMT轻量驱动)
- RAM: 24 × 灯珠数 × 4字节（默认限制64颗）
- 接线: VCC(5V/3.3V) → DIN → GPIO → GND
- 引脚: 任意GPIO（推荐GPIO2/4/12/13/14/15/25/26/27）
- 支持动作: 设置颜色、设置亮度、彩虹效果、关闭
- 配置示例: 详见 neopixel.md
2.2 TM1637 四位数码管
- 类型ID: 47 (SEVEN_SEGMENT_TM1637)
- 编译开关:
FASTBEE_ENABLE_SEVEN_SEGMENT - Flash占用: ~3KB (bit-bang驱动，无外部库)
- RAM: ~32B × 实例数
- 接线: VCC → CLK → GPIO1, DIO → GPIO2, GND
- 引脚: 任意2个GPIO
- 支持动作: 显示数字、显示文本、显示小数点、清空
- 配置示例: 详见 display-tm1637.md
2.3 OLED 显示屏 (SSD1306/SH1106)
- 类型ID: 36 (LCD)
- 编译开关:
FASTBEE_ENABLE_LCD - Flash占用: ~20KB (U8g2库)
- RAM: 1KB帧缓冲区 + ~200B管理器
- 接口: I2C (SDA/SCL) 或 SPI
- I2C接线: VCC → SDA(GPIO21) → SCL(GPIO22) → GND
- 分辨率: 128×64 (SSD1306), 128×64/132×64 (SH1106)
- 支持动作: 显示文本、显示数字、绘制图形、清空
- 配置示例: 详见 oled-usage-guide.md
3. 时钟模块
3.1 NTP 网络时钟（内置）
- 说明: ESP32联网时自动通过NTP同步时间，无需额外硬件
- 精度: ±50ms（取决于网络延迟）
- 用途: 定时触发规则、时间戳记录
3.2 DS1302 RTC实时时钟
- 当前状态: 未内置驱动
- 建议:
- 联网场景使用NTP（推荐）
- 离线场景后续可补bit-bang RTC驱动
- 可外接I2C RTC模块（如DS3231，通过自定义脚本读取）
4. 温湿度传感器
4.1 DHT11 / DHT22
- 类型ID: 38 (SENSOR), sensorType: 3=DHT11, 4=DHT22
- 编译开关:
FASTBEE_ENABLE_SENSOR_DRIVER - Flash占用: ~3KB (DHT库)
- 接口: 单总线（1个GPIO）
- 接线: VCC → DATA → GPIO → GND（需4.7K-10K上拉）
- 读取间隔: ≥2000ms（硬件限制）
- 数据字段:
temperature,humidity - 对比:
参数 DHT11 DHT22 温度范围 0~50°C -40~80°C 温度精度 ±2°C ±0.5°C 湿度范围 20~80% 0~100% 湿度精度 ±5% ±2~5% - 配置示例: 详见 sensor-dht.md
4.2 DS18B20 温度传感器
- 类型ID: 38 (SENSOR), sensorType: 2
- 接口: 单总线（OneWire，1个GPIO）
- 接线: VCC → DATA → GPIO → GND（需4.7K上拉）
- 特性:
- 防水探头可选
- 总线可挂载多个传感器（不同ROM地址）
- 精度±0.5°C，范围-55~125°C
- 数据字段:
temperature - 配置示例: 详见 sensor-ds18b20.md
4.3 SHT31 / SHT30
- 类型ID: 38 (SENSOR), sensorType: 5
- 接口: I2C（SDA/SCL）
- 地址: 0x44（默认）或0x45（ADDR引脚拉高）
- 精度: 温度±0.3°C，湿度±2%RH
- 范围: -40125°C，0100%RH
- 数据字段:
temperature,humidity - 配置示例: 详见 sensor-sht31.md
4.4 AHT20 / AHT21
- 类型ID: 38 (SENSOR), sensorType: 6
- 接口: I2C
- 地址: 0x38
- 精度: 温度±0.3°C，湿度±2~3%RH
- 特点: 性价比高，响应快
- 数据字段:
temperature,humidity - 配置示例: 详见 sensor-aht20.md
5. 环境与距离传感器
5.1 HC-SR04 超声波测距
- 类型ID: 38 (SENSOR), sensorType: 1
- 接口: GPIO（2个引脚：Trig/Echo）
- 接线: VCC → Trig → GPIO1, Echo → GPIO2 → GND
- 范围: 2cm ~ 400cm
- 精度: ±3mm
- 数据字段:
distance - 配置示例: 详见 sensor-ultrasonic.md
5.2 BH1750 光照传感器
- 类型ID: 38 (SENSOR), sensorType: 7
- 接口: I2C
- 地址: 0x23（ADDR拉低）或0x5C（ADDR拉高）
- 范围: 1~65535 lux
- 精度: ±20%
- 数据字段:
lux - 配置示例: 详见 sensor-bh1750.md
5.3 BMP280 气压/温度传感器
- 类型ID: 38 (SENSOR), sensorType: 8
- 编译开关:
FASTBEE_ENABLE_I2C_SENSORS（仅S3-full） - 接口: I2C或SPI
- 地址: 0x76（默认）或0x77（SDO拉高）
- 数据字段:
pressure,temperature,altitude - 精度: 气压±1hPa，温度±1°C，海拔±1m
- 配置示例: 详见 sensor-bmp280.md
6. 运动与姿态传感器
6.1 MPU6050 陀螺仪加速度计
- 类型ID: 38 (SENSOR), sensorType: 9
- 编译开关:
FASTBEE_ENABLE_I2C_SENSORS（仅S3-full） - 接口: I2C
- 地址: 0x68（AD0拉低）或0x69（AD0拉高）
- 数据字段:
acc_x,acc_y,acc_z(加速度 m/s²)gyro_x,gyro_y,gyro_z(角速度 °/s)temperature(芯片温度)
- 量程: 加速度±2/4/8/16g，陀螺仪±250/500/1000/2000°/s
- 配置示例: 详见 sensor-mpu6050.md
7. 控制模块
7.1 SG90 舵机
- 类型ID: 43 (PWM_SERVO)
- 接口: PWM（1个GPIO）
- 接线: 红线(VCC 5V) → 信号线(PWM GPIO) → 棕线(GND)
- 角度范围: 0~180°
- 控制: actionValue为角度值(0-180)
- 注意: 需外部5V供电，ESP32 3.3V可能驱动不稳
- 配置示例: 详见 servo.md
7.2 步进电机 (28BYJ-48 + ULN2003)
- 类型ID: 44 (STEPPER_MOTOR)
- 接口: GPIO（4个引脚：IN1~IN4）
- 接线: IN1~IN4 → GPIO1~4, VCC → 5V, GND → GND
- 参数: stepsPerRevolution(2048), speed(RPM 1~15)
- 支持动作: 正转、反转、停止、设置角度
- 配置示例: 详见 stepper-motor.md
7.3 继电器
- 类型ID: 12 (GPIO_DIGITAL_OUTPUT)
- 接线: VCC → IN → GPIO → GND
- 负载: 常开(NO)/常闭(NC)触点，最大10A/250VAC
- 注意: 控制交流电时务必注意安全隔离
- 配置示例: 详见 gpio-output.md
8. 通信模块
8.1 UART 串口通信
- 类型ID: 1 (UART)
- 接口: HardwareSerial (Serial1/Serial2)
- 接线: TX → RX_other, RX ← TX_other, GND共地
- 参数: baudRate(9600/115200等), dataBits(8), stopBits(1), parity(NONE)
- 引脚:
- ESP32: Serial1默认GPIO9/10, Serial2默认GPIO16/17
- ESP32-S3: 任意可复用引脚
- 数据源规则: 支持按需轮询（仅当有规则监听时轮询）
- 配置示例: 详见示例文档 12-uart-communication.md
8.2 红外遥控
- 类型ID: GPIO_INTERRUPT_CHANGE (20) + IRremoteESP8266解码
- 编译开关:
FASTBEE_ENABLE_IR_REMOTE（仅S3-full） - 接口: GPIO中断输入
- 协议: NEC/RC5/SONY/SAMSUNG等
- 接线: IR接收头OUT → GPIO
- 事件: 解码后的红外码值作为事件触发源
- 配置示例: 详见 ir-remote.md
8.3 Modbus RTU 通信
- 类型ID: 51 (MODBUS_DEVICE)
- 接口: RS485（UART + DE/RE控制）
- 功能码: 03(读寄存器), 06(写单寄存器), 10(写多寄存器)
- 设备: 继电器板、温控器、变频器、土壤传感器等
- 配置示例: 详见 modbus-device.md
9. 环境检测传感器
所有环境检测传感器均可配置为GPIO数字输入（类型13/14）或ADC模拟输入（类型26），取决于模块是否有数字输出(DO)和模拟输出(AO)。
9.1 激光传感器
- 接线: VCC → DO → GPIO(PULLUP) → GND
- 输出: 检测到激光输出低电平
- 应用: 安防对射、位置检测
9.2 倾斜传感器
- 接线: VCC → DO → GPIO(PULLUP) → GND
- 输出: 倾斜时导通输出低电平
- 应用: 姿态检测、防盗报警
9.3 震动传感器
- 接线: VCC → DO → GPIO(PULLUP) → GND
- 输出: 震动时导通输出低电平
- 应用: 碰撞检测、振动报警
9.4 干簧管传感器
- 接线: VCC → DO → GPIO(PULLUP) → GND
- 输出: 磁铁靠近时导通输出低电平
- 应用: 门窗开合检测、转速测量
9.5 对射光电传感器
- 接线: VCC → DO → GPIO(PULLUP) → GND
- 输出: 光束被遮挡时输出低电平
- 应用: 计数、位置检测、安全光幕
9.6 雨滴传感器
- 接线:
- DO → GPIO(PULLUP)（有雨滴输出低电平）
- AO → ADC GPIO（模拟电压0~3.3V，雨滴越大电压越低）
- 应用: 天气监测、自动关窗
9.7 声音传感器
- 接线:
- DO → GPIO(PULLUP)（声音超过阈值输出低电平）
- AO → ADC GPIO（模拟电压，声音越大电压越高）
- 应用: 声控开关、噪音监测
9.8 光敏传感器
- 接线:
- DO → GPIO(PULLUP)（暗环境输出低电平）
- AO → ADC GPIO（模拟电压，光照越强电压越高）
- 应用: 自动夜灯、光照度监测
9.9 火焰传感器
- 接线:
- DO → GPIO(PULLUP)（检测到火焰输出低电平）
- AO → ADC GPIO（模拟电压，火焰越强电压越低）
- 波长: 760nm~1100nm红外线
- 应用: 火灾报警、火焰探测
9.10 烟雾传感器 (MQ-2)
- 接线:
- DO → GPIO(PULLUP)（烟雾超标输出低电平）
- AO → ADC GPIO（模拟电压，浓度越高电压越低）
- 应用: 火灾预警、空气质量监测
9.11 触摸传感器
- 接线: VCC → OUT → GPIO(PULLUP) → GND
- 输出: 触摸时输出高电平
- ESP32内置触摸: GPIO 0/2/4/12/13/14/15/27/32/33（类型ID 21）
- 应用: 触摸开关、人机交互
9.12 红外避障传感器
- 接线: VCC → DO → GPIO(PULLUP) → GND
- 输出: 检测到障碍物输出低电平
- 范围: 2~30cm可调
- 应用: 小车避障、位置检测
10. 输入设备
10.1 按键
- 类型ID: 13 (GPIO_DIGITAL_INPUT_PULLUP)
- 接线: 一端接GPIO，另一端接GND
- 事件: 单击、双击、长按2s/5s/10s、按下、释放
- 消抖: 软件消抖~50ms
- 配置示例: 详见 gpio-input.md
10.2 PS2 摇杆
- 接线:
- VRx → ADC GPIO1（左右，中间约1.65V）
- VRy → ADC GPIO2（上下，中间约1.65V）
- SW → GPIO(PULLUP)（按下按键）
- 输出: 模拟电压03.3V，对应04095（12bit ADC）
- 应用: 方向控制、游戏手柄、云台控制
10.3 旋转编码器
- 类型ID: 46 (ENCODER) 或 GPIO_INTERRUPT
- 接线: CLK → GPIO1, DT → GPIO2, SW → GPIO3(PULLUP)
- 输出: 脉冲信号，通过中断计数方向和步数
- 应用: 旋钮调节、菜单选择、音量控制
- 配置示例: 详见 encoder.md
10.4 PIR 人体热释电传感器
- 类型ID: 14 (GPIO_DIGITAL_INPUT_PULLDOWN)
- 接线: VCC → OUT → GPIO → GND
- 输出: 检测到人输出高电平（持续数秒）
- 范围: 3~7m，角度<120°
- 延迟: 检测后持续输出0.5~5s（模块可调）
- 应用: 人体检测、自动照明、安防报警
11. 识别与存储模块
11.1 MFRC522 RFID射频卡模块
- 类型ID: 通过外设执行规则触发（刷卡事件）
- 编译开关:
FASTBEE_ENABLE_RFID（仅S3-full） - 接口: SPI（MOSI/MISO/SCK/SDA/SS）
- 接线:
MFRC522 ESP32 SDA → GPIO5 (SS) SCK → GPIO18 MOSI → GPIO23 MISO → GPIO19 IRQ → 不接 GND → GND RST → GPIO21 3.3V → 3.3V - 频率: 13.56MHz
- 支持卡片: MIFARE Classic/Ultralight/DESFire等
- 功能: 卡片UID读取、扇区读写
- 事件触发: 刷卡时触发规则，UID作为事件数据
- Flash占用: ~12KB
- 配置示例: 详见 rfid-mfrc522.md
11.2 SD卡 / TF卡
- 类型ID: 37 (SDIO)
- 接口: SDMMC或SPI模式
- 当前状态: 配置框架就绪，运行时挂载和文件动作待完善
- 建议:
- S3-full可补SD驱动和文件动作
- 用于日志落盘、数据记录、固件备份
- 接线 (SPI模式):
SD卡模块 ESP32 MOSI → GPIO23 MISO → GPIO19 CLK → GPIO18 CS → GPIO5 VCC → 3.3V/5V（视模块） GND → GND - 配置示例: 详见 storage-sd-card.md
附录A：编译开关对照表
| 功能模块 | 编译开关 | ESP32 | ESP32-C3 | ESP32-S3 | S3-full | Flash占用 |
|---|---|---|---|---|---|---|
| GPIO/ADC/PWM | FASTBEE_ENABLE_GPIO | ✅ | ✅ | ✅ | ✅ | ~3KB |
| DHT/DS18B20 | FASTBEE_ENABLE_SENSOR_DRIVER | ✅ | ✅ | ✅ | ✅ | ~8KB |
| 超声波/电流/电压 | FASTBEE_ENABLE_SENSOR_DRIVER | ✅ | ✅ | ✅ | ✅ | ~5KB |
| SHT31/AHT20/BH1750 | FASTBEE_ENABLE_SENSOR_DRIVER | ✅ | ✅ | ✅ | ✅ | ~4KB |
| NeoPixel LED | FASTBEE_ENABLE_LED_SCREEN | ⚙️ | ⚙️ | ⚙️ | ⚙️ | ~10KB |
| OLED/LCD | FASTBEE_ENABLE_LCD | ⚙️ | ⚙️ | ⚙️ | ⚙️ | ~20KB |
| TM1637数码管 | FASTBEE_ENABLE_SEVEN_SEGMENT | ⚙️ | ⚙️ | ⚙️ | ⚙️ | ~3KB |
| BMP280/MPU6050 | FASTBEE_ENABLE_I2C_SENSORS | ❌ | ❌ | ❌ | ✅ | ~15KB |
| MFRC522 RFID | FASTBEE_ENABLE_RFID | ❌ | ❌ | ❌ | ✅ | ~12KB |
| 红外遥控 | FASTBEE_ENABLE_IR_REMOTE | ❌ | ❌ | ❌ | ✅ | ~8KB |
| 以太网W5500 | FASTBEE_ENABLE_ETHERNET | ❌ | ❌ | ❌ | ✅ | ~8KB |
| 4G蜂窝EC801E | FASTBEE_ENABLE_CELLULAR | ❌ | ❌ | ❌ | ✅ | ~15KB |
| LoRa透传 | FASTBEE_ENABLE_LORA | ❌ | ❌ | ❌ | ✅ | ~5KB |
说明: ✅默认启用 ❌默认禁用 ⚙️按需配置
附录B：引脚分配建议
ESP32 推荐引脚分配
| 功能 | 推荐引脚 | 说明 |
|---|---|---|
| UART1 | GPIO9(TX)/GPIO10(RX) | 默认Serial1 |
| UART2 | GPIO16(TX)/GPIO17(RX) | 默认Serial2 |
| I2C | GPIO21(SDA)/GPIO22(SCL) | 默认Wire |
| SPI | GPIO23(MOSI)/GPIO19(MISO)/GPIO18(SCK)/GPIO5(CS) | 默认VSPI |
| ADC1 | GPIO32~39 | 推荐，不与WiFi冲突 |
| DAC1/2 | GPIO25/26 | 仅ESP32支持 |
| TOUCH | GPIO0/2/4/12/13/14/15/27/32/33 | 仅ESP32支持 |
| NeoPixel | GPIO2/4/12/13/14/15/25/26/27 | 任意GPIO |
| 舵机PWM | GPIO2/4/12/13/14/15/25/26/27 | 需支持PWM |
避免使用的引脚
| 引脚 | 原因 |
|---|---|
| GPIO6~11 | Flash芯片引脚，不可用 |
| GPIO34~39 | 仅支持输入，无内部上拉/下拉 |
| GPIO0 | 启动模式选择，慎用 |
| GPIO3 | 默认串口打印 |
ESP32-S3 引脚差异
- ADC1: GPIO1~20支持
- 无DAC: 不支持DAC输出
- 无TOUCH: 不支持触摸功能
- USB: GPIO19(D-)/GPIO20(D+)用于USB OTG
附录C：资源消耗参考
Flash占用参考（典型值）
| 模块/库 | Flash占用 | 备注 |
|---|---|---|
| 核心框架 | ~150KB | 包含网络、协议、Web服务器 |
| DHT库 | ~3KB | DHT11/DHT22 |
| OneWire+DallasTemperature | ~5KB | DS18B20 |
| U8g2 (OLED) | ~15KB | 字体和图形 |
| NeoPixel RMT驱动 | ~10KB | 轻量实现 |
| TM1637 bit-bang | ~3KB | 自写驱动 |
| BMP280库 | ~5KB | I2C传感器 |
| MPU6050库 | ~10KB | I2C传感器 |
| MFRC522库 | ~12KB | SPI RFID |
| IRremoteESP8266 | ~8KB | 红外解码 |
| Modbus库 | ~20KB | RTU主从 |
| MQTT (PubSubClient) | ~15KB | 消息协议 |
| TinyGSM (4G) | ~15KB | 蜂窝模块 |
| Ethernet W5500 | ~8KB | ESP-IDF驱动 |
RAM占用参考（运行时）
| 模块 | RAM占用 | 备注 |
|---|---|---|
| 核心框架 | ~30KB | 任务栈、缓冲区 |
| WiFi STA | ~15KB | 连接状态 |
| Web服务器 | ~20KB | 请求处理 |
| MQTT客户端 | ~5KB | 订阅缓冲 |
| 传感器缓存 | ~2KB | 最近读取值 |
| 规则引擎 | ~6KB | 规则列表、运行状态 |
| NeoPixel发送 | ~24×灯珠数 | 临时分配 |
| OLED帧缓冲 | 1KB | 128×64单色 |
JSON文档分配
- 小型文档: StaticJsonDocument<256>~<512>（简单响应）
- 中型文档: StaticJsonDocument<1024>~<2048>（配置读写）
- 大型文档: StaticJsonDocument<4096>~<8192>（完整配置加载）
- 动态文档: JsonDocument（ArduinoJson v7自动管理）
快速配置导入
所有文档中的JSON配置示例均设置为 "enabled": false（禁用状态），使用步骤：
- 复制JSON配置到
data/config/peripherals.json的peripherals数组中 - 通过Web界面"配置导入/导出"功能导入
- 在Web界面中修改引脚号、启用状态等参数
- 保存配置并重启设备生效
外设执行联动
所有传感器均可与外设执行系统联动：
- 定时触发: 按固定周期读取传感器数据
- 数据源事件: 传感器数据变化触发规则（
ds:periphId_field） - 平台触发: MQTT消息触发（如云端下发查询命令）
- 动作执行: 读取传感器(
ACTION_SENSOR_READ)、控制GPIO(ACTION_GPIO_WRITE)、上报数据
详见 外设执行文档
适用固件: v2.0+ (esp32/esp32s3-full)