Sensors and Modules

fastbeeAbout 9 min

Sensors and Modules

This document is the complete reference manual for all sensors, modules, and peripherals supported by the FastBee-Arduino project, covering wiring instructions, configuration parameters, JSON examples, peripheral execution linkage, compile flags, and pin occupation information.

Sensors and modules are first registered as hardware objects in "Peripheral Configuration", then the "Peripheral Execution" rules handle periodic collection, threshold judgment, display, or reporting.

Sensor readings are not directly reported to the platform: they first go through peripheral configuration, driver reading, and data caching, then are consumed by peripheral execution, display, or MQTT reporting.

GPIO, ADC, and PWM modules should verify pin capability, level, power, and default state before integration; modules that drive loads must first be saved as disabled and verified individually.

1. GPIO Basic Modules
2. Display and Lighting Modules
3. Clock Modules
4. Temperature and Humidity Sensors
5. Environmental and Distance Sensors
6. Motion and Posture Sensors
7. Control Modules
8. Communication Modules
9. Environmental Detection Sensors
10. Input Devices
11. Identification and Storage Modules
Appendix A: Compile Flag Reference
Appendix B: Pin Assignment Recommendations
Appendix C: Resource Consumption Reference

1. GPIO Basic Modules

1.1 GPIO Digital Output

Type ID: 12 (GPIO_DIGITAL_OUTPUT)
Applications: LED indicators, relay control, buzzers, DC motor switches
Wiring: GPIO pin → Load → GND (or VCC, depending on circuit)
Configuration: See gpio-output.md

1.2 GPIO Digital Input

Type ID: 11/13/14/18/19/20/21
Supported Types:
- 11: Floating input
- 13: Internal pull-up (common for buttons)
- 14: Internal pull-down (common for PIR)
- 18/19/20: Interrupt input (rising/falling/change edge)
- 21: Touch input (ESP32 specific pins only)
Button Events: Single click, double click, long press 2s/5s/10s, press, release
Configuration: See gpio-input.md

1.3 PWM Output

Type ID: 17 (GPIO_PWM_OUTPUT)
Applications: Breathing LED, motor speed control, servo control, LED dimming
Parameters: pwmChannel(0-15), pwmFrequency(1-40000Hz), pwmResolution(1-20bit)
Configuration: See pwm-output.md

1.4 ADC Analog Input

Type ID: 26 (ADC)
Applications: Potentiometers, light-dependent resistors, sound sensors, flame/smoke sensors
ESP32 Limitation: Only GPIO32-39 support ADC1 (recommended), ADC2 conflicts with WiFi
ESP32-S3: GPIO1-20 support ADC1
Resolution: 9-12bit configurable
Configuration: See adc-input.md

2. Display and Lighting Modules

2.1 NeoPixel RGB LED Strip (WS2812B)

Type ID: 45 (NEO_PIXEL)
Compile Flag: FASTBEE_ENABLE_LED_SCREEN
Flash Usage: ~10KB (RMT lightweight driver)
RAM: 24 × LED count × 4 bytes (default limit 64 LEDs)
Wiring: VCC(5V/3.3V) → DIN → GPIO → GND
Pins: Any GPIO (recommended GPIO2/4/12/13/14/15/25/26/27)
Supported Actions: Set color, set brightness, rainbow effect, turn off
Configuration: See neopixel.md

2.2 TM1637 Four-Digit Seven-Segment Display

Type ID: 47 (SEVEN_SEGMENT_TM1637)
Compile Flag: FASTBEE_ENABLE_SEVEN_SEGMENT
Flash Usage: ~3KB (bit-bang driver, no external library)
RAM: ~32B × instance count
Wiring: VCC → CLK → GPIO1, DIO → GPIO2, GND
Pins: Any 2 GPIOs
Supported Actions: Display number, display text, display decimal point, clear
Configuration: See display-tm1637.md

2.3 OLED Display (SSD1306/SH1106)

Type ID: 36 (LCD)
Compile Flag: FASTBEE_ENABLE_LCD
Flash Usage: ~20KB (U8g2 library)
RAM: 1KB frame buffer + ~200B manager
Interface: I2C (SDA/SCL) or SPI
I2C Wiring: VCC → SDA(GPIO21) → SCL(GPIO22) → GND
Resolution: 128×64 (SSD1306), 128×64/132×64 (SH1106)
Supported Actions: Display text, display numbers, draw graphics, clear
Configuration: See oled-usage-guide.md

3. Clock Modules

3.1 NTP Network Clock (Built-in)

Description: ESP32 automatically syncs time via NTP when connected, no extra hardware needed
Accuracy: ±50ms (depends on network latency)
Use: Timer trigger rules, timestamp recording

3.2 DS1302 RTC Real-Time Clock

Current Status: No built-in driver
Recommendations:
- Use NTP for connected scenarios (recommended)
- Offline scenarios can add bit-bang RTC driver later
- Can connect external I2C RTC module (e.g., DS3231, read via custom script)

4. Temperature and Humidity Sensors

4.1 DHT11 / DHT22

Type ID: 38 (SENSOR), sensorType: 3=DHT11, 4=DHT22
Compile Flag: FASTBEE_ENABLE_SENSOR_DRIVER
Flash Usage: ~3KB (DHT library)
Interface: One-Wire (1 GPIO)
Wiring: VCC → DATA → GPIO → GND (requires 4.7K-10K pull-up)
Read Interval: ≥2000ms (hardware limitation)
Data Fields: temperature, humidity
Comparison:
Parameter DHT11 DHT22
Temp Range 0~50°C -40~80°C
Temp Accuracy ±2°C ±0.5°C
Humidity Range 20~80% 0~100%
Humidity Accuracy ±5% ±2~5%
Configuration: See sensor-dht.md

Parameter	DHT11	DHT22
Temp Range	0~50°C	-40~80°C
Temp Accuracy	±2°C	±0.5°C
Humidity Range	20~80%	0~100%
Humidity Accuracy	±5%	±2~5%

4.2 DS18B20 Temperature Sensor

Type ID: 38 (SENSOR), sensorType: 2
Interface: One-Wire (1 GPIO)
Wiring: VCC → DATA → GPIO → GND (requires 4.7K pull-up)
Features:
- Waterproof probe option available
- Multiple sensors can be connected on the same bus (different ROM addresses)
- Accuracy ±0.5°C, range -55~125°C
Data Fields: temperature
Configuration: See sensor-ds18b20.md

4.3 SHT31 / SHT30

Type ID: 38 (SENSOR), sensorType: 5
Interface: I2C (SDA/SCL)
Address: 0x44 (default) or 0x45 (ADDR pin high)
Accuracy: Temperature ±0.3°C, Humidity ±2%RH
Range: -40~125°C, 0~100%RH
Data Fields: temperature, humidity
Configuration: See sensor-sht31.md

4.4 AHT20 / AHT21

Type ID: 38 (SENSOR), sensorType: 6
Interface: I2C
Address: 0x38
Accuracy: Temperature ±0.3°C, Humidity ±2~3%RH
Features: Cost-effective, fast response
Data Fields: temperature, humidity
Configuration: See sensor-aht20.md

5. Environmental and Distance Sensors

5.1 HC-SR04 Ultrasonic Distance

Type ID: 38 (SENSOR), sensorType: 1
Interface: GPIO (2 pins: Trig/Echo)
Wiring: VCC → Trig → GPIO1, Echo → GPIO2 → GND
Range: 2cm ~ 400cm
Accuracy: ±3mm
Data Fields: distance
Configuration: See sensor-ultrasonic.md

5.2 BH1750 Light Sensor

Type ID: 38 (SENSOR), sensorType: 7
Interface: I2C
Address: 0x23 (ADDR low) or 0x5C (ADDR high)
Range: 1~65535 lux
Accuracy: ±20%
Data Fields: lux
Configuration: See sensor-bh1750.md

5.3 BMP280 Barometric Pressure/Temperature Sensor

Type ID: 38 (SENSOR), sensorType: 8
Compile Flag: FASTBEE_ENABLE_I2C_SENSORS (Standard / Full)
Interface: I2C or SPI
Address: 0x76 (default) or 0x77 (SDO high)
Data Fields: pressure, temperature, altitude
Accuracy: Pressure ±1hPa, Temperature ±1°C, Altitude ±1m
Configuration: See sensor-bmp280.md

6. Motion and Posture Sensors

6.1 MPU6050 Gyroscope Accelerometer

Type ID: 38 (SENSOR), sensorType: 9
Compile Flag: FASTBEE_ENABLE_I2C_SENSORS (Standard / Full)
Interface: I2C
Address: 0x68 (AD0 low) or 0x69 (AD0 high)
Data Fields:
- acc_x, acc_y, acc_z (acceleration m/s²)
- gyro_x, gyro_y, gyro_z (angular velocity °/s)
- temperature (chip temperature)
Range: Accelerometer ±2/4/8/16g, Gyroscope ±250/500/1000/2000°/s
Configuration: See sensor-mpu6050.md

7. Control Modules

7.1 SG90 Servo

Type ID: 43 (PWM_SERVO)
Interface: PWM (1 GPIO)
Wiring: Red wire(VCC 5V) → Signal wire(PWM GPIO) → Brown wire(GND)
Angle Range: 0~180°
Control: actionValue is angle value (0-180)
Note: Requires external 5V power; ESP32 3.3V may cause unstable operation
Configuration: See servo.md

7.2 Stepper Motor (28BYJ-48 + ULN2003)

Type ID: 44 (STEPPER_MOTOR)
Interface: GPIO (4 pins: IN1~IN4)
Wiring: IN1~IN4 → GPIO1~4, VCC → 5V, GND → GND
Parameters: stepsPerRevolution(2048), speed(RPM 1~15)
Supported Actions: Forward, reverse, stop, set angle
Configuration: See stepper-motor.md

7.3 Relay

Type ID: 12 (GPIO_DIGITAL_OUTPUT)
Wiring: VCC → IN → GPIO → GND
Load: Normally open(NO)/normally closed(NC) contacts, max 10A/250VAC
Note: Exercise caution with safety isolation when controlling AC power
Configuration: See gpio-output.md

8. Communication Modules

8.1 UART Serial Communication

Type ID: 1 (UART)
Interface: HardwareSerial (Serial1/Serial2)
Wiring: TX → RX_other, RX ← TX_other, GND common ground
Parameters: baudRate(9600/115200 etc.), dataBits(8), stopBits(1), parity(NONE)
Pins:
- ESP32: Serial1 default GPIO9/10, Serial2 default GPIO16/17
- ESP32-S3: Any multiplexable pins
Data Source Rule: Supports on-demand polling (only polls when rules are listening)
Configuration: See example docs 12-uart-communication.md

8.2 IR Remote Control

Type ID: GPIO_INTERRUPT_CHANGE (20) + IRremoteESP8266 decoding
Compile Flag: FASTBEE_ENABLE_IR_REMOTE (Standard / esp32-F8R4 Full; S3 Full disabled by default)
Interface: GPIO interrupt input
Protocols: NEC/RC5/SONY/SAMSUNG etc.
Wiring: IR receiver OUT → GPIO
Events: Decoded IR code values serve as event trigger sources
Configuration: See ir-remote.md

8.3 Modbus RTU Communication

Type ID: 51 (MODBUS_DEVICE)
Interface: RS485 (UART + DE/RE control)
Function Codes: 03(read register), 06(write single register), 10(write multiple registers)
Devices: Relay boards, thermostats, inverters, soil sensors, etc.
Configuration: See modbus-device.md

9. Environmental Detection Sensors

All environmental detection sensors can be configured as GPIO digital input (type 13/14) or ADC analog input (type 26), depending on whether the module has digital output (DO) and analog output (AO).

9.1 Laser Sensor

Wiring: VCC → DO → GPIO(PULLUP) → GND
Output: Outputs low level when laser detected
Applications: Security beam detection, position detection

9.2 Tilt Sensor

Wiring: VCC → DO → GPIO(PULLUP) → GND
Output: Outputs low level when tilted
Applications: Posture detection, anti-theft alarm

9.3 Vibration Sensor

Wiring: VCC → DO → GPIO(PULLUP) → GND
Output: Outputs low level when vibration detected
Applications: Collision detection, vibration alarm

9.4 Reed Switch Sensor

Wiring: VCC → DO → GPIO(PULLUP) → GND
Output: Outputs low level when magnet is near
Applications: Door/window open-close detection, speed measurement

9.5 Through-Beam Photoelectric Sensor

Wiring: VCC → DO → GPIO(PULLUP) → GND
Output: Outputs low level when beam is blocked
Applications: Counting, position detection, safety light curtain

9.6 Raindrop Sensor

Wiring:
- DO → GPIO(PULLUP) (outputs low level when raindrops detected)
- AO → ADC GPIO (analog voltage 0~3.3V, larger raindrops = lower voltage)
Applications: Weather monitoring, automatic window closing

9.7 Sound Sensor

Wiring:
- DO → GPIO(PULLUP) (outputs low level when sound exceeds threshold)
- AO → ADC GPIO (analog voltage, louder sound = higher voltage)
Applications: Sound-activated switch, noise monitoring

9.8 Light Sensor

Wiring:
- DO → GPIO(PULLUP) (outputs low level in dark environment)
- AO → ADC GPIO (analog voltage, stronger light = higher voltage)
Applications: Automatic night light, illuminance monitoring

9.9 Flame Sensor

Wiring:
- DO → GPIO(PULLUP) (outputs low level when flame detected)
- AO → ADC GPIO (analog voltage, stronger flame = lower voltage)
Wavelength: 760nm~1100nm infrared
Applications: Fire alarm, flame detection

9.10 Smoke Sensor (MQ-2)

Wiring:
- DO → GPIO(PULLUP) (outputs low level when smoke exceeds threshold)
- AO → ADC GPIO (analog voltage, higher concentration = lower voltage)
Applications: Fire warning, air quality monitoring

9.11 Touch Sensor

Wiring: VCC → OUT → GPIO(PULLUP) → GND
Output: Outputs high level when touched
ESP32 Built-in Touch: GPIO 0/2/4/12/13/14/15/27/32/33 (Type ID 21)
Applications: Touch switch, human-machine interaction

9.12 IR Obstacle Avoidance Sensor

Wiring: VCC → DO → GPIO(PULLUP) → GND
Output: Outputs low level when obstacle detected
Range: 2~30cm adjustable
Applications: Robot obstacle avoidance, position detection

10. Input Devices

10.1 Button

Type ID: 13 (GPIO_DIGITAL_INPUT_PULLUP)
Wiring: One end to GPIO, other end to GND
Events: Single click, double click, long press 2s/5s/10s, press, release
Debounce: Software debounce ~50ms
Configuration: See gpio-input.md

10.2 PS2 Joystick

Wiring:
- VRx → ADC GPIO1 (left-right, center approximately 1.65V)
- VRy → ADC GPIO2 (up-down, center approximately 1.65V)
- SW → GPIO(PULLUP) (press button)
Output: Analog voltage 0~3.3V, corresponding to 0~4095 (12-bit ADC)
Applications: Direction control, game controller, gimbal control

10.3 Rotary Encoder

Type ID: 46 (ENCODER) or GPIO_INTERRUPT
Wiring: CLK → GPIO1, DT → GPIO2, SW → GPIO3(PULLUP)
Output: Pulse signal, count direction and steps via interrupt
Applications: Knob adjustment, menu selection, volume control
Configuration: See encoder.md

10.4 PIR Motion Sensor

Type ID: 14 (GPIO_DIGITAL_INPUT_PULLDOWN)
Wiring: VCC → OUT → GPIO → GND
Output: Outputs high level when motion detected (lasts several seconds)
Range: 3~7m, angle <120°
Delay: Outputs 0.5~5s after detection (module adjustable)
Applications: Human detection, automatic lighting, security alarm

11. Identification and Storage Modules

11.1 MFRC522 RFID Card Reader Module

Type ID: Triggered via peripheral execution rules (card swipe event)
Compile Flag: FASTBEE_ENABLE_RFID (Standard / Full)
Interface: SPI (MOSI/MISO/SCK/SDA/SS)

Wiring:

MFRC522    ESP32
SDA   →    GPIO5  (SS)
SCK   →    GPIO18
MOSI  →    GPIO23
MISO  →    GPIO19
IRQ   →    Not connected
GND   →    GND
RST   →    GPIO21
3.3V  →    3.3V

Frequency: 13.56MHz
Supported Cards: MIFARE Classic/Ultralight/DESFire etc.
Functions: Card UID reading, sector read/write
Event Trigger: Triggers rules on card swipe, UID as event data
Flash Usage: ~12KB
Configuration: See rfid-mfrc522.md

11.2 SD Card / TF Card

Type ID: 37 (SDIO)
Interface: SDMMC or SPI mode
Current Status: Config framework ready, runtime mounting and file actions to be improved
Recommendations:
- Full or custom builds can complete SD file actions
- Used for logging, data recording, firmware backup

Wiring (SPI mode):

SD Card Module  ESP32
MOSI  →   GPIO23
MISO  →   GPIO19
CLK   →   GPIO18
CS    →   GPIO5
VCC   →   3.3V/5V (depending on module)
GND   →   GND

Configuration: See storage-sd-card.md

Appendix A: Compile Flag Reference

Feature Module	Compile Flag	ESP32 Standard	C3/C6 Lite	S3 Standard	Full(PSRAM)	Flash Usage
GPIO/ADC/PWM	`FASTBEE_ENABLE_GPIO`	✅	✅	✅	✅	~3KB
DHT/DS18B20	`FASTBEE_ENABLE_SENSOR_DRIVER`	✅	✅	✅	✅	~8KB
Ultrasonic/Current/Voltage	`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 Display	`FASTBEE_ENABLE_SEVEN_SEGMENT`	⚙️	⚙️	⚙️	⚙️	~3KB
BMP280/MPU6050	`FASTBEE_ENABLE_I2C_SENSORS`	✅	❌	✅	✅	~15KB
MFRC522 RFID	`FASTBEE_ENABLE_RFID`	✅	❌	✅	✅	~12KB
IR Remote	`FASTBEE_ENABLE_IR_REMOTE`	✅	❌	✅	⚠️	~8KB
Ethernet W5500	`FASTBEE_ENABLE_ETHERNET`	❌	❌	❌	✅	~8KB
4G Cellular EC801E	`FASTBEE_ENABLE_CELLULAR`	❌	❌	❌	✅	~15KB

Notes: ✅ Enabled by default ❌ Disabled by default ⚙️ Configurable ⚠️ Available on esp32-F8R4, ESP32-S3 Full disabled by default

Appendix B: Pin Assignment Recommendations

ESP32 Recommended Pin Assignment

Function	Recommended Pins	Description
UART1	GPIO9(TX)/GPIO10(RX)	Default Serial1
UART2	GPIO16(TX)/GPIO17(RX)	Default Serial2
I2C	GPIO21(SDA)/GPIO22(SCL)	Default Wire
SPI	GPIO23(MOSI)/GPIO19(MISO)/GPIO18(SCK)/GPIO5(CS)	Default VSPI
ADC1	GPIO32~39	Recommended, no WiFi conflict
DAC1/2	GPIO25/26	ESP32 only
TOUCH	GPIO0/2/4/12/13/14/15/27/32/33	ESP32 only
NeoPixel	GPIO2/4/12/13/14/15/25/26/27	Any GPIO
Servo PWM	GPIO2/4/12/13/14/15/25/26/27	PWM-capable required

Pins to Avoid

Pin	Reason
GPIO6~11	Flash chip pins, not available
GPIO34~39	Input-only, no internal pull-up/pull-down
GPIO0	Boot mode selection, use with caution
GPIO3	Default serial print

ESP32-S3 Pin Differences

ADC1: GPIO1~20 supported
No DAC: DAC output not supported
No TOUCH: Touch function not supported
USB: GPIO19(D-)/GPIO20(D+) for USB OTG

Appendix C: Resource Consumption Reference

Flash Usage Reference (typical values)

Module/Library	Flash Usage	Notes
Core framework	~150KB	Includes network, protocol, web server
DHT library	~3KB	DHT11/DHT22
OneWire+DallasTemperature	~5KB	DS18B20
U8g2 (OLED)	~15KB	Fonts and graphics
NeoPixel RMT driver	~10KB	Lightweight implementation
TM1637 bit-bang	~3KB	Custom driver
BMP280 library	~5KB	I2C sensor
MPU6050 library	~10KB	I2C sensor
MFRC522 library	~12KB	SPI RFID
IRremoteESP8266	~8KB	IR decoding
Modbus library	~20KB	RTU master/slave
MQTT (PubSubClient)	~15KB	Messaging protocol
TinyGSM (4G)	~15KB	Cellular module
Ethernet W5500	~8KB	ESP-IDF driver

RAM Usage Reference (runtime)

Module	RAM Usage	Notes
Core framework	~30KB	Task stacks, buffers
WiFi STA	~15KB	Connection state
Web server	~20KB	Request handling
MQTT client	~5KB	Subscription buffer
Sensor cache	~2KB	Latest readings
Rule engine	~6KB	Rule list, runtime state
NeoPixel send	~24×LED count	Temporary allocation
OLED frame buffer	1KB	128×64 monochrome

JSON Document Allocation

Small documents: StaticJsonDocument<256>~<512> (simple responses)
Medium documents: StaticJsonDocument<1024>~<2048> (config read/write)
Large documents: StaticJsonDocument<4096>~<8192> (full config loading)
Dynamic documents: JsonDocument (ArduinoJson v7 auto-managed)

Quick Configuration Import

All JSON configuration examples in the documentation are set to "enabled": false (disabled state). Usage steps:

Copy JSON configuration to the peripherals array in data/config/peripherals.json
Import via Web interface "Configuration Import/Export" function
Modify pin numbers, enable status, and other parameters in the Web interface
Save configuration and restart device to take effect

Peripheral Execution Linkage

All sensors can be linked with the peripheral execution system:

Timer Trigger: Read sensor data at fixed intervals
Data Source Event: Sensor data changes trigger rules (ds:periphId_field)
Platform Trigger: MQTT message trigger (e.g., cloud sends query command)
Action Execution: Read sensor (ACTION_SENSOR_READ), control GPIO (ACTION_GPIO_WRITE), report data

See Peripheral Execution Documentation

Applicable Firmware: v2.0+ (esp32/esp32s3-F16R8)