AHT20 温湿度传感器

使用通用传感器（type=38），在外设配置中选择注册驱动 AHT20。运行要求驱动已编入、功能配置中的 i2cSensors 已启用、预算允许且外设已启用。仅保存外设不会创建周期采集规则。

接线与配置

VCC/GND 按具体模块额定电压接入并共地，SDA/SCL 电平需与 ESP32 兼容。GPIO21/22 是经典 ESP32 示例；C3/C6/S3 或专用板须使用其能力和引脚预检允许的组合。设备地址为 0x38，JSON 使用数字地址。共享总线须通过资源检查，地址不能冲突。

下例为 peripherals 数组中的单个条目；通过受管导入预览确认接线和资源后再启用：

{
  "id": "aht20_i2c",
  "name": "AHT20 温湿度传感器",
  "type": 38,
  "enabled": false,
  "pinCount": 2,
  "pins": [
    21,
    22
  ],
  "params": {
    "driver": "AHT20",
    "address": 56,
    "frequency": 100000,
    "sampleInterval": 5000
  }
}

参数	说明
driver	AHT20，与实际传感器匹配
address	数字 I2C 地址；省略时使用该驱动默认地址
frequency	100000 或 400000 Hz，共享客户端须兼容
sampleInterval	ms；允许 100～86400000，0 使用默认 1000；实际最小读取间隔还受驱动下限 1000ms 限制
busPeripheralId	可选已保存的 I2C 主总线 ID；引用时 pins=[]、pinCount=0，不能同时指定两个引脚

sensorCategory 是采集动作参数，外设持久配置使用 driver；采样间隔字段为 sampleInterval。旧 type=2 示例属于 I2C 总线与规则选驱动的兼容方式，新增实体传感器推荐上述 type=38 配置。

周期采集与上报

1. 在外设执行创建间隔定时规则，例如每 5 秒触发。
2. 添加读取传感器动作（19），目标 aht20_i2c，测量通道 humidity。
3. 物模型字段填 roomHumidity，与平台属性 ID 一致；单位使用通道单位。
4. 按需勾选执行后上报、记录数值历史，保存后明确启用规则。

下面是 actions 数组中的动作，actionValue 为 JSON 字符串：

{
  "targetPeriphId": "aht20_i2c",
  "actionType": 19,
  "actionValue": "{\"periphId\":\"aht20_i2c\",\"sensorCategory\":\"AHT20\",\"channelField\":\"humidity\",\"dataField\":\"roomHumidity\",\"decimalPlaces\":2,\"sensorLabel\":\"AHT20 温湿度传感器\",\"unit\":\"%\"}",
  "useReceivedValue": false,
  "syncDelayMs": 0
}

channelField 选择驱动通道，dataField 指定 MQTT 属性 ID。本动作正常上报形如 [{"id":"roomHumidity","value":"数值"}]；多个属性需分别配置采集动作，不会自动拼成包含全部字段的逗号字符串。

本地缓存来源为 aht20_i2c_humidity，数据源事件为 ds:aht20_i2c_humidity，显示模板使用 ${aht20_i2c.humidity}。报警规则先确认来源质量和年龄，再配置比较操作与阈值。

可采集通道

channelField	含义	单位
temperature	温度	°C
humidity	相对湿度	%

驱动等待约 80ms 后检查状态与完整数据；忙状态、未校准或传输失败不会生成新有效样本。

失败、过期或缺失样本不会伪装成有效零，旧缓存不会刷新测量时刻。功能关闭、总线繁忙、地址冲突、初始化失败与接线错误应分别排查。

单项验证

确认接线后启用外设，检查 GET /api/peripherals/read?id=aht20_i2c 的初始化、驱动错误、通道与质量；再执行保存的采集规则，核对结果、数据源和平台属性。实际精度、断线恢复及长期运行须在对应板卡验证。

见外设配置指南和传感器动作。