DHT11/DHT22 温湿度传感器配置

1. 功能说明

DHT11 和 DHT22(AM2302) 是常用的数字温湿度传感器，通过单总线协议与 ESP32 通信。FastBee 通过 SensorDriver 驱动实现自动初始化、缓存读取和异步采集。

传感器对比

参数	DHT11	DHT22/AM2302
温度范围	0~50°C	-40~80°C
温度精度	±2°C	±0.5°C
湿度范围	20~80% RH	0~100% RH
湿度精度	±5%	±2~5%
采样周期	≥1s	≥2s
工作电压	3.3~5.5V	3.3~5.5V

工作原理

单总线数字信号输出，无需 ADC
首次读取时自动初始化（惰性初始化）
内置 2 秒最小读取间隔缓存，避免频繁读取导致数据错误
底层读取失败时可保留最多 10 秒的旧值，但仍标记本次采样失败；动作不会把它作为新温度发布或用于温控

DHT 读数会先写入传感器缓存，再供外设执行事件、显示动作或 MQTT 上报使用；排查时先确认外设页能读数，再检查规则和平台侧数据。

2. 接线说明

DHT11/DHT22 模块        ESP32
┌─────────────┐
│  VCC (1)    │───────── 3.3V 或 5V
│  DATA (2)   │───────── GPIO (如 GPIO4)
│  GND (3/4)  │───────── GND
└─────────────┘

注意：部分模块已内置 10K 上拉电阻；
      若使用裸传感器，DATA 需适当外接上拉；接 ESP32 的上拉端应为 3.3V。5V 供电模块若内置上拉到 5V，须做电平适配。

推荐引脚（ESP32）：GPIO4, GPIO5, GPIO13, GPIO14, GPIO15, GPIO25, GPIO26, GPIO27

3. 配置方式

方式1：Web界面配置（推荐）

DHT 传感器保存前重点核对 DATA 引脚、传感器型号和采集间隔。

步骤1：进入外设管理页面

打开浏览器访问 ESP32 IP 地址
登录后点击左侧菜单 外设配置

步骤2：添加DHT传感器外设

点击 新增外设 按钮

填写配置：

字段	填写内容	说明
外设ID	`dht11_01` 或 `dht22_01`	唯一标识符
名称	`DHT11温湿度` 或 `DHT22温湿度`	显示名称
外设类型	通用传感器 (type: 38)	DHT驱动
引脚配置	`4`	DATA引脚
传感器类型 ID	`0` 或 `1`	分别为DHT11、DHT22，I2C驱动留空
采集间隔	`5000`	毫秒；实际定时采集还须配置读取规则

点击保存

步骤3：验证配置

在外设列表中找到刚添加的外设
点击启用开关
按下节建立已保存、启用的读取规则，再观察温度/湿度、原采样年龄和质量；只启用外设不会自动创建定时采集规则

💡 提示：传感器型号与标称精度以模块规格为准，精度要求需用标准温湿度源验收

方式2：JSON配置文件导入

以下是受管导入文件中 peripherals 数组的条目示例；先预览并确认资源检查，不直接覆盖运行设备的配置文件。示例保持停用，GPIO4仅示意，须按板卡能力和接线选择。

DHT 使用通用传感器容器（类型38），参数直接放在 params 中；sensorType 为 DHT11=0、DHT22=1。读取动作另选 sensorCategory=dht11/dht22，两处型号须一致。不要填入I2C注册驱动名。

DHT11 配置示例

json

{
  "id": "dht11_01",
  "name": "DHT11温湿度",
  "type": 38,
  "enabled": false,
  "pinCount": 1,
  "pins": [4, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "sensorType": 0,
    "sampleInterval": 5000
  }
}

DHT22 配置示例

json

{
  "id": "dht22_01",
  "name": "DHT22温湿度",
  "type": 38,
  "enabled": false,
  "pinCount": 1,
  "pins": [4, 255, 255, 255, 255, 255, 255, 255],
  "params": {
    "sensorType": 1,
    "sampleInterval": 5000
  }
}

字段说明

字段	含义	取值
type	外设类型	38 (SENSOR)
pins[0]	数据引脚	有效 GPIO 号
params.sensorType	本地传感器类型	0=DHT11, 1=DHT22
params.sampleInterval	保存的采样间隔(ms)	示例5000；规则定时与驱动缓存间隔分别生效

4. 外设执行联动

DHT 传感器的数据通过外设执行规则的 ACTION_SENSOR_READ(actionType=19) 动作进行采集，采集后的数据缓存为数据源，可被其他规则作为事件触发源使用。

Web界面配置步骤

创建定时采集规则

点击左侧菜单 外设执行
点击 新增规则 按钮
配置定时触发器：
- 触发类型：定时触发
- 执行间隔：30 秒
添加动作：
- 动作1：读取温度
  - 动作类型：传感器读取
  - 目标外设：dht11_01
  - 传感器类别：DHT11（DHT22模块选DHT22）
  - 数据字段：temperature
  - 单位：°C
- 动作2：读取湿度
  - 动作类型：传感器读取
  - 目标外设：dht11_01
  - 传感器类别：DHT11（DHT22模块选DHT22）
  - 数据字段：humidity
  - 单位：%
开启 执行后上报数据
点击保存

当前开发候选会在DHT温度/湿度字段切换和保存时同步固定单位，保留自定义显示名称。温控仅接受真实温度通道；旧配置中湿度误标摄氏度也会被拒绝。表单和温控来源的本地回归已通过，完整候选仍须统一验证，不能据本文认定现场已经更新。

创建温度超限报警规则

创建新规则
配置事件触发器：
- 触发类型：事件触发
- 事件ID：ds:dht11_01_temperature
- 比较操作：大于
- 比较值：35
添加动作：
- 动作类型：高电平
- 目标外设：relay_01（风扇继电器）
点击保存

💡 提示：事件ID格式为 ds:{外设ID}_{字段名}

JSON配置示例

传感器采集规则配置

json

{
  "id": "exec_dht_read",
  "name": "DHT11定时采集",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 30
    }
  ],
  "actions": [
    {
      "targetPeriphId": "dht11_01",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"dht11_01\",\"sensorCategory\":\"dht11\",\"dataField\":\"temperature\",\"sensorLabel\":\"温度\",\"unit\":\"°C\"}"
    },
    {
      "targetPeriphId": "dht11_01",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"dht11_01\",\"sensorCategory\":\"dht11\",\"dataField\":\"humidity\",\"sensorLabel\":\"湿度\",\"unit\":\"%\"}"
    }
  ],
  "reportAfterExec": true
}

温度超限报警规则

json

{
  "id": "exec_dht_alarm",
  "name": "温度超限报警",
  "enabled": false,
  "triggers": [
    {
      "triggerType": 4,
      "eventId": "ds:dht11_01_temperature",
      "operatorType": 2,
      "compareValue": "35"
    }
  ],
  "actions": [
    {
      "targetPeriphId": "relay_01",
      "actionType": 0,
      "actionValue": ""
    }
  ],
  "reportAfterExec": true
}

5. 注意事项

读取间隔：驱动对DHT采用2秒最小缓存间隔；规则中配置实际轮询秒数，保存sampleInterval不等于创建定时器
引脚选择：避免使用 GPIO6-11（Flash引脚）、GPIO34-39（仅输入，无内部上拉）
上拉电阻：裸传感器需外接 4.7K~10K 上拉电阻，模块版一般已内置
数据线长度：数据线、电容、上拉和电源噪声按实际安装验证；不提供统一20m距离保证
首次读取延迟：传感器上电后需 1~2 秒稳定期，首次读取可能返回 NAN
资源占用：由 FASTBEE_ENABLE_SENSOR_DRIVER 等构建条件决定，实际Flash和运行内存须在目标固件测量，不能按固定3KB估算
并发和失败：DHT与DS18B20的物理读取串行；锁超时返回失败，不访问实例缓存。ESP32使用有界采样，失败保留原时间与失败质量；并发保护不替代接线、时序和持续运行验收

6. 常见问题

Q: 读取始终返回 NAN？

检查接线是否正确（VCC/GND/DATA）
确认上拉电阻是否存在
确认引脚号配置正确
传感器上电后等待 2 秒再首次读取

Q: 数据跳变很大？

DHT11 精度为 ±2°C，正常波动
建议使用 DHT22 获得更高精度
当前DHT读取没有独立的多次采样平均参数；先检查电源、接线和最小采样间隔

Q: 多个 DHT 传感器如何配置？

每个传感器使用不同引脚，配置不同 id（如 dht11_01、dht11_02）
SensorDriver 内部按引脚缓存实例，互不干扰

Q: 多条规则同时读同一个 DHT，设备会重启/卡死？

旧版固件存在此问题：并发读破坏单总线时序，关中断超时触发看门狗复位
当前代码串行化物理读取并有界限制采样；仍须结合固件版本、失败日志、接线和现场负载排查，不能只凭互斥锁认定整机长期稳定

DHT11/DHT22 温湿度传感器配置 ​

1. 功能说明 ​

传感器对比 ​

工作原理 ​

2. 接线说明 ​

3. 配置方式 ​

方式1：Web界面配置（推荐） ​

步骤1：进入外设管理页面 ​

步骤2：添加DHT传感器外设 ​

步骤3：验证配置 ​

方式2：JSON配置文件导入 ​

DHT11 配置示例 ​

DHT22 配置示例 ​

字段说明 ​

4. 外设执行联动 ​

Web界面配置步骤 ​

JSON配置示例 ​

传感器采集规则配置 ​

温度超限报警规则 ​

5. 注意事项 ​

6. 常见问题 ​

DHT11/DHT22 温湿度传感器配置

1. 功能说明

传感器对比

工作原理

2. 接线说明

3. 配置方式

方式1：Web界面配置（推荐）

步骤1：进入外设管理页面

步骤2：添加DHT传感器外设

步骤3：验证配置

方式2：JSON配置文件导入

DHT11 配置示例

DHT22 配置示例

字段说明

4. 外设执行联动

Web界面配置步骤

JSON配置示例

传感器采集规则配置

温度超限报警规则

5. 注意事项

6. 常见问题