DS18B20 数字温度传感器

2026-10-04候选说明：稳定ROM选择与受控转换等待已进入本轮开发，软件测试及统一门禁待完成；尚未刷写或进行实物验收，实物状态为 NOT_RUN。下例默认禁用，按实际板卡确认GPIO、探头身份和接线后再启用。

配置由采集规则驱动

建议使用 ONE_WIRE（type 44）声明DQ引脚，再以动作 19（读取传感器）选择 ds18b20。仅新增外设不会自动持续测温。

旧版示例中的type38是通用传感器容器，params.sensorType=5不是当前DS18B20采集命令，params.sampleInterval也不会创建采集定时器。实际采集节奏来自规则触发器；动作的 actionValue必须为包含 periphId和 sensorCategory等字段的JSON字符串，不能留空。

三线接线

探头端	ESP32连接	要点
VCC/VDD	3.3V	本页只给出三线3.3V供电方案
GND	GND	与ESP32共地
DQ/DATA	一个经板卡资源预检允许的GPIO	通过4.7kΩ外接电阻上拉到3.3V

示例使用GPIO4，不能直接推定每块板都可用。先核对该脚没有被显示、Flash、串口或其它外设占用。DQ上拉端不得接5V；部分模块板载上拉已接供电端，应先确认实际电路。内部上拉不能替代外接电阻。本候选没有寄生供电、固定长线距离或多探头最大数量的实物保证，不依据旧文档“100m”说法部署。

Web设置与ROM选择

在外设配置中新增OneWire外设，选择DQ引脚，先保持禁用。
在外设执行中新增采集规则，使用间隔定时；下例配置1秒，实际执行仍受调度、内存保护及总线可用性影响。
动作选择“读取传感器”、目标 ds18b20_01、类别“DS18B20 温度”，数据字段 temperature，单位 °C。
“设备索引”为0～15整数，默认0；可选“ROM地址”用于固定物理探头身份。
确认配置和接线后再单独启用外设与规则，并查看执行结果及数据质量。

ROM填写完整8字节，即16位十六进制字符，大小写均可，必须以 28开头，末字节CRC必须正确。Web检查格式，设备保存/导入与实际读取入口检查family和CRC。ROM字段可留空，此时沿用索引；CRC本身不能省略。索引表示当次枚举位置，设备增减或顺序改变可能指向另一探头，固定安装应登记实际探头ROM。

设置ROM后直接按该地址读取，探头移除或断线时不会回退到 deviceIndex而读另一支探头。失败或旧缓存不能当作新的有效测量；重新接入的恢复和多探头顺序变化仍需实物验收。

可导入的禁用外设示例

下例为外设配置包装对象；导入时保留现有其它外设和网络配置。

json

{
  "peripherals": [
    {
      "id": "ds18b20_01",
      "name": "DS18B20温度",
      "type": 44,
      "enabled": false,
      "pins": [
        4
      ],
      "params": {}
    }
  ]
}

可保存的禁用采集规则示例

下例是一条规则对象，可按现有规则导入流程加入配置。采集动作参数在 actionValue内序列化为字符串；deviceAddress空值仅适用于按索引选取，固定安装应替换成已确认的实际ROM。

json

{
  "id": "exec_ds18b20_collect",
  "name": "DS18B20温度采集",
  "enabled": false,
  "execMode": 0,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 1
    }
  ],
  "actions": [
    {
      "targetPeriphId": "ds18b20_01",
      "actionType": 19,
      "actionValue": "{\"periphId\":\"ds18b20_01\",\"sensorCategory\":\"ds18b20\",\"deviceIndex\":0,\"deviceAddress\":\"\",\"dataField\":\"temperature\",\"scaleFactor\":1,\"offset\":0,\"decimalPlaces\":2,\"sensorLabel\":\"温度\",\"unit\":\"°C\"}",
      "useReceivedValue": false,
      "syncDelayMs": 0,
      "execMode": 0
    }
  ],
  "protocolType": 0,
  "scriptContent": "",
  "recordHistory": true,
  "reportAfterExec": true
}

这里的“采集规则”不是新增JSON角色字段。recordHistory要求为有效采样保留历史，reportAfterExec沿用既有上报行为；它们不保证平台收到数据。动作失败可产生空值与失败原因的诊断记录，不应据此当成温度0或成功测量。控制、报警、蜂鸣器或继电器输出应配置在独立规则，并验证数据仍为有效且新鲜后使用；本页不自动配置物理输出。

转换等待与数据质量

DS18B20完成一次转换需要时间。当前候选的公有读取接口先执行一次无等待步骤；若转换尚在进行，会在释放全局传感器总线锁之后让当前任务yield等待剩余转换时间，再重新取得锁读取，单次转换等待预算最多750ms。这不是整个API的最坏响应时长：锁竞争、OneWire事务与任务调度还会增加耗时。转换等待本身不占用全局锁，其它任务可以取得锁处理其它传感器总线；实际总线事务仍受原有互斥约束，“锁外等待”不代表同一条DQ可以被并发读写。

等待前不保留可失效的实例指针。停用、释放或重新初始化会改变不复用的实例代际，等待后的读取须重新查找并核对；旧实例退役时拒绝沿用，不能把替换后的探头结果拼到旧请求中。

成功样本的采样时间取发起转换时刻，不以较晚的读取、显示或MQTT接收时刻刷新。该候选的新鲜年龄上限为1750ms，年龄达到上限即不能作为Good新值。缓存命中可能重复返回同一采样时间，1秒规则不表示每秒必有新的物理转换。晚到的旧转换仍保留旧年龄；公有接口可能等待一轮新转换；若等待、代际复核、读取或后续处理未能留下有效新值，结果保持Unknown/Stale或失败，不伪装Good。不能据此保证任意负载与调度条件下持续得到Good。

本修改保留规则原有失败退避和完成事件语义；没有为“pending”放宽一般失败保护。部署前须通过真实公有读取入口和规则链回归，确认首次转换、慢轮询、同总线多ROM、其它总线并行、停用/重建、断线与时间回退行为。

尚未验收

软件回归、目标板构建及容量、实际任务栈/峰值内存、探头ROM与CRC、断线恢复、不同线长与电源噪声、已标定温度对照均须独立核验。驱动接受范围内的有限数值不等于达到标称精度，历史记录或Web显示成功也不等于实物测量通过。

DS18B20 数字温度传感器 ​

配置由采集规则驱动 ​

三线接线 ​

Web设置与ROM选择 ​

可导入的禁用外设示例 ​

可保存的禁用采集规则示例 ​

转换等待与数据质量 ​

尚未验收 ​