DHT11/DHT22 Temperature and Humidity Sensor Configuration

1. Overview

DHT11 and DHT22 (AM2302) are commonly used digital temperature and humidity sensors that communicate with ESP32 via single-bus protocol. FastBee implements automatic initialization, cached reading, and asynchronous collection through the SensorDriver driver.

Sensor Comparison

Parameter	DHT11	DHT22/AM2302
Temperature Range	0~50°C	-40~80°C
Temperature Accuracy	±2°C	±0.5°C
Humidity Range	20~80% RH	0~100% RH
Humidity Accuracy	±5%	±2~5%
Sampling Period	≥1s	≥2s
Operating Voltage	3.3~5.5V	3.3~5.5V

Working Principle

• Single-bus digital signal output, no ADC needed
• Auto-initialization on first read (lazy initialization)
• Built-in 2-second minimum read interval cache to prevent data errors from frequent reads
• Returns old cached values within 10 seconds on read failure (graceful degradation)

DHT readings are first written to the sensor cache, then available for peripheral execution events, display actions, or MQTT reporting; when troubleshooting, first confirm the peripheral page can read values, then check rules and platform-side data.

2. Wiring Instructions

DHT11/DHT22 Module        ESP32
┌─────────────┐
│  VCC (1)    │───────── 3.3V or 5V
│  DATA (2)   │───────── GPIO (e.g., GPIO4)
│  GND (3/4)  │───────── GND
└─────────────┘

Note: Some modules have built-in 10K pull-up resistor;
      If using bare sensors, connect 4.7K~10K pull-up between DATA and VCC.

Recommended Pins (ESP32): GPIO4, GPIO5, GPIO13, GPIO14, GPIO15, GPIO25, GPIO26, GPIO27

3. Configuration

Method 1: Web Interface Configuration (Recommended)

Before saving DHT sensor configuration, verify DATA pin, sensor model, and sampling interval.

Step 1: Navigate to Peripheral Management Page

1. Open a browser and navigate to the ESP32 IP address
2. After logging in, click Peripheral Configuration in the left menu

Step 2: Add DHT Sensor Peripheral

1. Click the Add Peripheral button

2. Fill in the configuration:

   Field	Value	Description
   Peripheral ID	dht11_01 or dht22_01	Unique identifier
   Name	DHT11 Temp & Humidity or DHT22 Temp & Humidity	Display name
   Peripheral Type	Generic Sensor (type: 38)	DHT driver
   Pin Configuration	4	DATA pin
   Sensor Category	DHT	DHT series
   Sensor Model	DHT11 or DHT22	Based on actual model
   Sampling Interval	5000	5 seconds (≥2000ms)

3. Click Save

Step 3: Verify Configuration

1. Find the newly added peripheral in the peripheral list
2. Click the Enable toggle
3. Wait 5 seconds and check temperature and humidity data

💡 Tip: DHT22 has higher accuracy (±0.5°C), recommended for precision measurements

---

Method 2: JSON Configuration File Import

Add the following configuration to the peripherals array in data/config/peripherals.json:

DHT sensors use SENSOR (type ID=38) type in peripheral configuration, with params.sensor.sensorType to distinguish DHT11(3) and DHT22(4).

DHT11 Configuration Example

{
  "id": "dht11_01",
  "name": "DHT11 Temp & Humidity",
  "type": 38,
  "enabled": false,
  "pinCount": 1,
  "pins": [4, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "sensor": {
      "sensorType": 3,
      "sampleInterval": 5000
    }
  }
}

DHT22 Configuration Example

{
  "id": "dht22_01",
  "name": "DHT22 Temp & Humidity",
  "type": 38,
  "enabled": false,
  "pinCount": 1,
  "pins": [4, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "sensor": {
      "sensorType": 4,
      "sampleInterval": 5000
    }
  }
}

Field Description

Field	Meaning	Values
type	Peripheral type	38 (SENSOR)
pins[0]	Data pin	Valid GPIO number
params.sensor.sensorType	Sensor category	3=DHT11, 4=DHT22
params.sensor.sampleInterval	Sampling interval (ms)	≥2000

4. Peripheral Execution Integration

DHT sensor data is collected via the ACTION_SENSOR_READ (actionType=19) action in peripheral execution rules; collected data is cached as a data source and can be used by other rules as an event trigger source.

Web Interface Configuration Steps

Create Timed Collection Rule

1. Switch to the Peripheral Execution Management tab
2. Click the Add Rule button
3. Configure timer trigger:
   • Trigger Type: Timer Trigger
   • Execution Interval: 30 seconds
4. Add actions:
   • Action 1: Read temperature
     • Action Type: Sensor Read
     • Target Peripheral: dht11_01
     • Data Field: temperature
   • Action 2: Read humidity
     • Action Type: Sensor Read
     • Target Peripheral: dht11_01
     • Data Field: humidity
5. Enable Report Data After Execution
6. Click Save

Create Temperature Threshold Alarm Rule

1. Create a new rule
2. Configure event trigger:
   • Trigger Type: Event Trigger
   • Event ID: ds:dht11_01_temperature
   • Comparison: Greater Than
   • Comparison Value: 35
3. Add action:
   • Action Type: High Level
   • Target Peripheral: relay_01 (fan relay)
4. Click Save

💡 Tip: Event ID format is ds:{peripheralID}_{fieldName}

---

JSON Configuration Example

Sensor Collection Rule Configuration

{
  "id": "exec_dht_read",
  "name": "DHT11 Timed Collection",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 30
    }
  ],
  "actions": [
    {
      "targetPeriphId": "dht11_01",
      "actionType": 19,
      "actionValue": "temperature"
    },
    {
      "targetPeriphId": "dht11_01",
      "actionType": 19,
      "actionValue": "humidity"
    }
  ],
  "reportAfterExec": true
}

Temperature Threshold Alarm Rule

{
  "id": "exec_dht_alarm",
  "name": "Temperature Threshold Alarm",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:dht11_01_temperature",
      "operatorType": 2,
      "compareValue": "35"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "relay_01",
      "actionType": 0,
      "actionValue": ""
    }
  ],
  "reportAfterExec": true
}

5. Notes

1. Minimum Read Interval: DHT11/DHT22 hardware limits minimum 2 seconds; configure sampleInterval ≥2000ms
2. Pin Selection: Avoid GPIO6-11 (Flash pins), GPIO34-39 (input only, no internal pull-up)
3. Pull-up Resistor: Bare sensors require external 4.7K~10K pull-up resistor; module versions usually have built-in
4. Data Line Length: Recommend ≤20m; when exceeded, increase pull-up resistance value or use shielded cable
5. First Read Delay: Sensor needs 1~2 seconds stabilization after power-on; first read may return NAN
6. Flash Usage: DHT library is approximately 3KB, controlled via FASTBEE_ENABLE_SENSOR_DRIVER=1 compile switch

6. FAQ

Q: Readings always return NAN?

• Check wiring is correct (VCC/GND/DATA)
• Confirm pull-up resistor is present
• Confirm pin number is configured correctly
• Wait 2 seconds after sensor power-on before first read

Q: Data fluctuates significantly?

• DHT11 accuracy is ±2°C, normal fluctuation
• Recommend using DHT22 for higher accuracy
• Can configure multiple sample averaging in peripheral execution

Q: How to configure multiple DHT sensors?

• Use different pins for each sensor, configure different IDs (e.g., dht11_01, dht11_02)
• SensorDriver internally caches instances by pin, no interference