ESP32驱动DS18B20温度传感器的1-Wire完整实现

1. 项目概述

esp32-ds18b20是一个专为 ESP32 平台设计的 C 语言组件，用于驱动 Maxim Integrated 公司生产的 DS18B20 可编程分辨率单总线（1-Wire）数字温度传感器。该组件并非独立运行的“黑盒”，而是深度依赖并协同底层esp32-owb（ESP32 One-Wire Bus）组件工作，共同构建起一套完整、健壮且可扩展的 1-Wire 设备管理与通信框架。

其核心设计目标是工程实用性与系统鲁棒性的统一：在保证高精度温度测量的同时，严格遵循嵌入式开发的最佳实践——无全局变量、内存模型可选、支持多设备与多总线并发操作。该组件已在 ESP-IDF v2.1、v3.0–v3.3 及 v4.1-beta1 环境下完成充分验证，编译工具链为xtensa-esp32-elf-gcc（5.2.0 版本），确保了与主流 ESP32 开发生态的无缝兼容。

DS18B20 本身是一款高度集成的智能传感器，其关键特性包括：

• 可编程分辨率：用户可在 9-bit（0.5°C）、10-bit（0.25°C）、11-bit（0.125°C）和 12-bit（0.0625°C）四种精度间动态配置，分辨率越高，单次转换耗时越长（典型值：9-bit 为 93.75ms，12-bit 为 750ms）。
• 双供电模式：支持外部 VDD 供电（推荐）与寄生电源（Parasitic Power）供电两种模式，后者仅需数据线（DQ）与地线（GND）即可工作，极大简化布线，但对总线驱动能力提出更高要求。
• 单总线架构：所有通信均通过单一数据线完成，配合严格的时序协议（如复位脉冲、读写时隙），允许多个设备挂载于同一总线上，每个设备拥有全球唯一的 64-bit ROM 地址，实现精准寻址。

esp32-ds18b20组件的价值，正在于它将这些复杂的硬件特性和底层时序细节，封装为一组清晰、安全、可复用的 C API，使开发者能够将精力聚焦于温度数据的应用逻辑，而非总线协议的比特级调试。

2. 系统架构与依赖关系

2.1 分层架构模型

esp32-ds18b20采用经典的分层软件架构，其与底层硬件及上层应用的关系如下图所示（文字描述）：

+---------------------+ | Application Task | ← 用户任务：调用 ds18b20_* API 获取温度 +----------+--------+ | | 调用 ds18b20_* 函数 v +---------------------+ | esp32-ds18b20 | ← 本组件：负责 DS18B20 协议解析、状态管理、 | (DS18B20 Driver) | 温度计算、CRC 校验等设备专属逻辑 +----------+--------+ | | 调用 owb_* 函数 v +---------------------+ | esp32-owb | ← 底层组件：提供 1-Wire 总线的物理层抽象， | (One-Wire Bus) | 包含复位、读写位、搜索 ROM 等基础操作 +----------+--------+ | | GPIO 操作 / 定时器中断 v +---------------------+ | ESP32 Hardware | ← 硬件层：GPIO 引脚、精确延时（通常基于 APB 时钟） +---------------------+

这种分层设计带来了显著的工程优势：

• 关注点分离：esp32-owb专注于解决“如何在一根线上可靠地收发 0 和 1”，而esp32-ds18b20则专注于解决“如何让 DS18B20 这个特定芯片正确地执行温度转换并返回有效数据”。两者职责清晰，互不干扰。
• 可移植性：只要为新的 MCU 平台实现了符合规范的esp32-owb接口（即实现了owb_reset,owb_read_bit,owb_write_bit等函数），esp32-ds18b20组件几乎无需修改即可复用。
• 可测试性：可以为esp32-ds18b20编写单元测试，通过注入一个模拟的owb_bus_t对象来验证其逻辑，而无需真实硬件。

2.2 关键依赖：esp32-owb组件

esp32-ds18b20的运行完全依赖于esp32-owb。后者是整个 1-Wire 生态的基石，其提供的核心 API 如下表所示：

esp32-ds18b20组件内部的所有通信，最终都转化为对上述owb_*函数的调用。因此，在使用本组件前，必须首先在项目中正确集成并初始化esp32-owb。

3. 核心功能与 API 详解

3.1 设备初始化与生命周期管理

esp32-ds18b20支持两种内存模型，以适应不同资源约束的场景。其初始化流程体现了“无全局变量”的设计哲学。

3.1.1 静态（栈/全局）内存模型

适用于已知设备数量且资源充裕的场景。开发者需为每个 DS18B20 设备预先分配一块内存，并显式传递给初始化函数。

#include "ds18b20.h" #include "owb.h" // 1. 声明总线句柄和设备句柄（全局或静态） static owb_bus_t * bus = NULL; static ds18b20_t sensor1; static ds18b20_t sensor2; // 2. 初始化总线（在 app_main 或专用初始化函数中） void init_owb_bus(void) { bus = owb_new_gpio_bus(GPIO_NUM_4); // 使用 GPIO4 作为 1-Wire 数据线 assert(bus != NULL); // 可选：为寄生电源模式配置强上拉 GPIO // owb_use_strong_pullup_gpio(bus, GPIO_NUM_5); } // 3. 初始化单个 DS18B20 设备 void init_ds18b20_sensor(void) { // 为 sensor1 分配 ROM 地址（可通过搜索获得，此处为示例地址） uint64_t rom_code1 = 0x28FFA1B2C3D4E5F6ULL; ds18b20_init(&sensor1, bus, &rom_code1); // 为 sensor2 分配 ROM 地址 uint64_t rom_code2 = 0x28FFA1B2C3D4E5F7ULL; ds18b20_init(&sensor2, bus, &rom_code2); }

3.1.2 动态（堆）内存模型

适用于设备数量未知或需要动态增删的场景。组件内部会调用malloc申请所需内存。

// 1. 初始化总线（同上） // 2. 动态创建设备对象 ds18b20_t * sensor_dynamic = ds18b20_malloc_init(bus, &rom_code); if (sensor_dynamic == NULL) { ESP_LOGE("DS18B20", "Failed to malloc sensor object"); return; } // 3. 使用完毕后，必须手动释放内存 ds18b20_free(sensor_dynamic);

ds18b20_init()和ds18b20_malloc_init()的函数签名如下：

3.2 设备发现与地址管理

在实际部署中，DS18B20 的 ROM 地址通常是未知的。esp32-ds18b20提供了与esp32-owb深度集成的地址发现机制。

3.2.1 单设备总线优化（Solo Mode）

当确认总线上仅有一个 DS18B20 时，应使用owb_search_solo_device()。该函数跳过标准的二叉树搜索算法，直接发送0xF0（Read ROM）命令，效率极高。

uint64_t rom_code; owb_status status = owb_search_solo_device(bus, &rom_code); if (status == OWB_STATUS_OK) { ESP_LOGI("DS18B20", "Found solo device: 0x%016llx", rom_code); ds18b20_init(&sensor, bus, &rom_code); } else { ESP_LOGE("DS18B20", "No solo device found"); }

3.2.2 多设备总线枚举（Search Algorithm）

对于挂载多个传感器的总线，必须使用标准的 ROM 搜索算法。这是一个由owb_search_first()和owb_search_next()构成的迭代过程。

owb_search_state search_state; uint64_t rom_code; owb_status status; // 初始化搜索状态 owb_search_start(&search_state); // 搜索第一个设备 status = owb_search_first(bus, &search_state, &rom_code); while (status == OWB_STATUS_OK) { ESP_LOGI("DS18B20", "Found device: 0x%016llx", rom_code); // 为找到的设备创建 ds18b20_t 对象（此处使用动态模型） ds18b20_t * sensor = ds18b20_malloc_init(bus, &rom_code); if (sensor) { // 将 sensor 添加到你的设备列表中，例如 linked list 或 array add_to_sensor_list(sensor); } // 搜索下一个设备 status = owb_search_next(bus, &search_state, &rom_code); }

3.3 温度测量全流程

DS18B20 的温度测量是一个典型的“启动-等待-读取”三阶段过程。esp32-ds18b20将其拆分为两个独立的 API，以支持多设备并行转换，这是其高性能的关键所在。

3.3.1 启动温度转换（非阻塞）

ds18b20_start_conversion()函数向指定设备发送0x44（Convert T）命令，启动一次温度转换。该函数立即返回，不等待转换完成。

// 启动 sensor1 的转换 ds18b20_status status1 = ds18b20_start_conversion(&sensor1); if (status1 != DS18B20_OK) { ESP_LOGW("DS18B20", "Failed to start conversion for sensor1"); } // 启动 sensor2 的转换（几乎同时） ds18b20_status status2 = ds18b20_start_conversion(&sensor2); if (status2 != DS18B20_OK) { ESP_LOGW("DS18B20", "Failed to start conversion for sensor2"); }

3.3.2 读取温度结果（阻塞）

ds18b20_read_temperature()函数负责从设备的 Scratchpad（暂存器）中读取 16-bit 温度数据，并进行 CRC 校验、符号位处理和单位换算（°C）。此函数是阻塞的，它会根据当前配置的分辨率，自动计算并等待足够的延时（owb_delay()），然后读取数据。

float temperature_c; ds18b20_status status = ds18b20_read_temperature(&sensor1, &temperature_c); if (status == DS18B20_OK) { ESP_LOGI("DS18B20", "Sensor1 Temperature: %.3f °C", temperature_c); } else if (status == DS18B20_ERROR_CRC) { ESP_LOGW("DS18B20", "CRC error on sensor1 data"); } else { ESP_LOGE("DS18B20", "Failed to read temperature from sensor1"); }

3.3.3 分辨率配置

分辨率通过向 DS18B20 的配置寄存器（Configuration Register）写入特定值来设置。esp32-ds18b20提供了便捷的 API：

// 设置为 12-bit 分辨率（最高精度） ds18b20_set_resolution(&sensor1, DS18B20_RESOLUTION_12_BIT); // 设置为 9-bit 分辨率（最快，约 94ms） ds18b20_set_resolution(&sensor2, DS18B20_RESOLUTION_9_BIT);

DS18B20_RESOLUTION_*_BIT是预定义的宏，其值对应于配置寄存器的低 2 位（R1 R0）：

• 9-bit:0x1F(0b00)
• 10-bit:0x3F(0b01)
• 11-bit:0x5F(0b10)
• 12-bit:0x7F(0b11)

3.4 寄生电源（Parasitic Power）模式详解

寄生电源模式是 DS18B20 的一项重要特性，它允许传感器仅通过数据线（DQ）和地线（GND）获取工作所需的全部能量，省去了 VDD 供电线。然而，这给总线驱动带来了严峻挑战。

3.4.1 检测与启用

组件提供了两种方式启用寄生电源模式：

1. 自动检测：调用ds18b20_check_for_parasite_power()，该函数会向总线发送特定命令并分析响应，判断设备是否处于寄生模式。
2. 手动启用：直接调用owb_use_parasitic_power(bus)。

// 方式1：先检测，再启用 if (ds18b20_check_for_parasite_power(&sensor1)) { owb_use_parasitic_power(bus); ESP_LOGI("DS18B20", "Parasitic power mode detected and enabled"); } // 方式2：强制启用（已知硬件配置为寄生模式） owb_use_parasitic_power(bus);

3.4.2 硬件配置方案

官方文档明确指出了两种经过验证的寄生电源硬件方案：

方案一：直接寄生（Simple Parasitic）

• 接线：DS18B20 的 VDD 引脚直接接地（GND），仅保留 DQ 和 GND 连接到 ESP32。
• 原理：在空闲时，总线通过上拉电阻（通常为 4.7kΩ）被拉至 VCC（3.3V），此时电容 C1（DS18B20 内部）被充电；在转换期间，DS18B20 需要大电流，电容 C1 放电为其供电。
• 问题与对策：当转换时间较长（如 12-bit）或设备较多时，电容电量可能耗尽，导致读数错误（常表现为固定在 85°C）。解决方案是减小上拉电阻值，例如更换为 1kΩ，以提高充电电流。

方案二：强上拉（Strong Pullup）

• 接线：在 DQ 线与 VCC 之间接入一个 P-MOSFET（如 BS250）和一个限流电阻（如 270Ω）。MOSFET 的栅极（Gate）连接到 ESP32 的一个 GPIO（如 GPIO5）。
• 原理：在普通通信时，GPIO 为低电平，MOSFET 截止，总线由常规上拉电阻（4.7kΩ）维持；在启动温度转换后，ds18b20_start_conversion()会自动将该 GPIO 拉高，MOSFET 导通，VCC 直接通过 MOSFET 和限流电阻为 DS18B20 提供充足电流。
• 配置：必须在初始化总线后，调用owb_use_strong_pullup_gpio(bus, GPIO_NUM_X)来告知esp32-owb哪个 GPIO 控制强上拉。

// 初始化总线后 owb_use_strong_pullup_gpio(bus, GPIO_NUM_5); // GPIO5 控制 MOSFET 栅极 owb_use_parasitic_power(bus); // 启用寄生模式

3.4.3 时间敏感性警告

在寄生电源模式下，DS18B20无法通过总线信号通知主控“我转换完了”。因此，ds18b20_read_temperature()必须依赖一个预设的、精确的延时来等待转换完成。这个延时值是根据 ESP32 的 APB 时钟频率计算得出的。如果您的 ESP32 系统时钟配置有误（例如，APB 时钟被意外分频），该延时将不准确，可能导致读取到未完成的数据，从而产生错误结果。务必确保CONFIG_ESP32_DEFAULT_CPU_FREQ_MHZ等时钟配置项与硬件实际运行频率一致。

4. 实际工程应用示例

以下是一个完整的app_main()示例，展示了如何在一个 ESP32 项目中集成esp32-ds18b20，并实现对两个 DS18B20 传感器的轮询读取。

#include <stdio.h> #include "freertos/FreeRTOS.h" #include "freertos/task.h" #include "esp_log.h" #include "owb.h" #include "ds18b20.h" static const char * TAG = "DS18B20_EXAMPLE"; static owb_bus_t * bus = NULL; static ds18b20_t sensor1, sensor2; // 从 ROM 搜索中获取的两个设备地址（请替换为您的实际地址） static const uint64_t ROM1 = 0x28FFA1B2C3D4E5F6ULL; static const uint64_t ROM2 = 0x28FFA1B2C3D4E5F7ULL; void ds18b20_task(void * pvParameters) { float temp1, temp2; ds18b20_status status; while(1) { // 1. 启动两个传感器的转换（并行） status = ds18b20_start_conversion(&sensor1); if (status != DS18B20_OK) { ESP_LOGW(TAG, "Start conv1 failed"); } status = ds18b20_start_conversion(&sensor2); if (status != DS18B20_OK) { ESP_LOGW(TAG, "Start conv2 failed"); } // 2. 等待足够时间（最长的转换时间，12-bit 为 750ms） vTaskDelay(pdMS_TO_TICKS(800)); // 3. 读取两个传感器的温度 status = ds18b20_read_temperature(&sensor1, &temp1); if (status == DS18B20_OK) { ESP_LOGI(TAG, "Sensor1: %.3f °C", temp1); } else { ESP_LOGW(TAG, "Read sensor1 failed: %d", status); } status = ds18b20_read_temperature(&sensor2, &temp2); if (status == DS18B20_OK) { ESP_LOGI(TAG, "Sensor2: %.3f °C", temp2); } else { ESP_LOGW(TAG, "Read sensor2 failed: %d", status); } vTaskDelay(pdMS_TO_TICKS(2000)); // 每2秒读取一次 } } void app_main(void) { // 1. 初始化 1-Wire 总线 bus = owb_new_gpio_bus(GPIO_NUM_4); if (!bus) { ESP_LOGE(TAG, "Failed to create 1-Wire bus"); return; } // 2. （可选）配置强上拉 GPIO 用于寄生电源 // owb_use_strong_pullup_gpio(bus, GPIO_NUM_5); // owb_use_parasitic_power(bus); // 3. 初始化 DS18B20 设备 ds18b20_init(&sensor1, bus, &ROM1); ds18b20_init(&sensor2, bus, &ROM2); // 4. （可选）设置分辨率 ds18b20_set_resolution(&sensor1, DS18B20_RESOLUTION_12_BIT); ds18b20_set_resolution(&sensor2, DS18B20_RESOLUTION_12_BIT); // 5. 创建读取任务 xTaskCreate(ds18b20_task, "ds18b20_task", 4096, NULL, 5, NULL); }

此示例清晰地体现了工程实践中的关键考量：

• 错误处理：对每一个ds18b20_*调用都进行了状态检查，并记录日志。
• 时序控制：vTaskDelay(pdMS_TO_TICKS(800))确保了在读取前，有足够的时间让最慢的转换（12-bit）完成。
• 资源管理：总线和设备对象在app_main中集中初始化，生命周期清晰。

5. 故障排查与最佳实践

5.1 常见问题诊断表

5.2 工程最佳实践

• 始终进行 CRC 校验：ds18b20_read_temperature()的返回值是判断数据有效性的唯一权威依据。切勿忽略DS18B20_ERROR_CRC。
• 分辨率与功耗的权衡：在电池供电的应用中，应优先选择 9-bit 或 10-bit 分辨率，以大幅缩短转换时间，降低平均功耗。
• 利用并行转换：当监控多个点位时，务必采用“先全部启动，再统一读取”的模式，这是提升系统吞吐量的最有效手段。
• 寄生电源的终极方案：在可靠性要求极高的工业场景中，强烈推荐使用方案二（强上拉）。它从根本上解决了寄生电源的能量瓶颈，是稳定运行的保障。

esp32-ds18b20组件的源码结构清晰，其ds18b20.c文件中，ds18b20_read_temperature()函数的主体逻辑就是一个精妙的switch语句，根据device->resolution的值，精确调用owb_delay()等待对应毫秒数，随后执行owb_read_bytes()读取 9 字节的 Scratchpad 数据，并调用owb_crc8()进行校验。理解这一核心流程，是驾驭该组件、乃至深入定制其行为的基础。