SHT31 温湿度传感器

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

接线与配置

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

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

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

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

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

周期采集与上报

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

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

{
  "targetPeriphId": "sht31_i2c",
  "actionType": 19,
  "actionValue": "{\"periphId\":\"sht31_i2c\",\"sensorCategory\":\"SHT31\",\"channelField\":\"temperature\",\"dataField\":\"roomTemperature\",\"decimalPlaces\":2,\"sensorLabel\":\"SHT31 温湿度传感器\",\"unit\":\"°C\"}",
  "useReceivedValue": false,
  "syncDelayMs": 0
}

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

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

可采集通道

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

SHT30 与 SHT31 都已注册，型号选择为 SHT30 时相应修改 driver。驱动分别检查温度和湿度 CRC；失败不发布本轮数据。

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

单项验证

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

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