示例18:DS18B20 温度传感器

实验概述

本例使用 ONE_WIRE（type 44）声明数据引脚，再由动作 19（读取传感器）的 ds18b20 类别采集温度。新增OneWire外设本身不会启动定时采集。

2026-10-04候选：稳定ROM选择与受控转换等待已进入开发，统一软件验证待完成；尚未进行本例实物验收，状态为 NOT_RUN。外设与规则示例默认禁用，确认目标板卡、探头身份、接线和当前固件支持后再启用。完整字段说明见DS18B20数字温度传感器。

硬件接线

DS18B20端	ESP32连接	要点
VCC/VDD	3.3V	本例使用独立供电的三线接法
GND	GND	共地
DQ/DATA	示例GPIO4	外接4.7kΩ电阻上拉到3.3V

GPIO4仅作示例，应先通过具体板卡的资源预检，确认没有显示、Flash、串口等占用。DQ不得上拉到5V；若模块自带上拉，先确认上拉实际接到哪一路电源。内部上拉不能替代外接电阻。

本例不提供两线寄生供电或固定布线距离的保证，也不建议只凭线长盲目降低电阻。线缆、电源、探头数量和模块电路需要实物验证；防水与温度精度取决于实际探头及其标定，不能从Web读数或封装外观推定。

禁用外设配置

以下为外设配置包装对象。导入时保留现有其它外设和网络配置；现有 ds18b20_01 应先核对，避免重复ID。

json

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

定时采集温度

本例配置每5秒触发一次采集尝试。触发间隔不等于每5秒必有新的有效样本，实际执行还受调度、内存保护、总线状态和失败退避影响。

在 外设执行 中创建“DS18B20温度采集”规则，先保持禁用。
添加 定时触发，选择 间隔定时，间隔秒数填 5。
添加 读取传感器 动作，目标外设选择 ds18b20_01，传感器类别选择 DS18B20温度，数据字段为 temperature，单位为 °C。
设备索引取0～15整数，默认0；固定安装可填写实际探头完整ROM，避免枚举顺序变化读到另一探头。
根据需要开启记录历史与执行后上报，保存后仍保持禁用。确认接线和配置后，分别启用外设、规则，再查看执行结果和数据质量。

ROM为16位十六进制字符，以 28 开头并包含正确的末字节CRC，大小写均可。空ROM沿用索引；Web检查格式，固件保存/导入和实际读取还会检查family与CRC。固定ROM不存在时不会回退索引读取另一探头。索引只代表当次枚举位置，不能代替固定身份。

禁用采集规则JSON

下面是一条规则对象；actionValue 是动作参数的JSON字符串，不能置空。未填写ROM的示例按索引0读取，固定安装应改为已登记的实际ROM。

json

{
  "id": "exec_ds18b20_collect",
  "name": "DS18B20温度采集",
  "enabled": false,
  "execMode": 0,
  "triggers": [
    {
      "triggerType": 1,
      "timerMode": 0,
      "intervalSec": 5
    }
  ],
  "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
}

recordHistory 与 reportAfterExec 沿用现有记录和上报流程，不保证网络传输或平台接收成功。失败诊断可能包含空值与原因，不应解释为温度0或一次成功测量。

转换等待与结果判断

当前候选的公有读取入口可以在释放全局传感器总线锁后，让当前任务yield等待剩余转换时间，转换等待预算最多750ms。随后重新查找并核对实例代际；等待中停用、释放或重建的旧实例不能继续完成原请求。750ms不是整个API的最坏耗时，锁竞争、总线事务和任务调度还会增加耗时。锁外转换等待允许其它传感器任务取得锁，但同一DQ的实际读写仍不能并发。

采样时间取发起转换时刻，缓存读取、历史显示或MQTT接收不会刷新它。候选新鲜年龄上限为1750ms，达到上限的样本不能作为Good；慢轮询可能等待新一轮转换，不能将旧样本的读取时刻当作新采样时刻。规则失败仍走原有退避和完成事件语义，不把转换或读取失败伪装成成功。

本例每5秒采集，样本不会在两个触发间隔内一直保持新鲜。需要控制或报警时，应按实际采集节奏建立独立规则，并在执行输出前核验当前数据为Good且年龄仍在限内，同时验证断线、无数据和恢复行为。旧版只比较 temperature > 40 就驱动蜂鸣器的步骤没有完整的数据质量和现场验证依据，本例不再提供该自动输出配置。

验收记录

软件回归、目标板构建与容量仍须统一验证。实际ROM/CRC、同总线多探头、断线恢复、任务栈和峰值内存、线缆与电源条件、标定温度对照均保持 NOT_RUN。驱动接受范围内的有限数值不等于探头达到标称精度，页面显示或上报成功也不能替代实物测量验收。

示例18:DS18B20 温度传感器 ​

实验概述 ​

硬件接线 ​

禁用外设配置 ​

定时采集温度 ​

禁用采集规则JSON ​

转换等待与结果判断 ​

验收记录 ​