温度传感器

简介

ESP32-S3 内置传感器，用于测量芯片内部的温度。该温度传感器模组包含一个 8 位 Sigma-Delta 模拟-数字转换器 (ADC) 和一个数字-模拟转换器 (DAC)，可以补偿测量结果，减少温度测量的误差。

由于硬件限制，温度传感器存在预定义的测量范围及其对应误差，详见下表：

预定义测量范围 (°C)	测量误差 (°C)
50 ~ 125	< 3
20 ~ 100	< 2
-10 ~ 80	< 1
-30 ~ 50	< 2
-40 ~ 20	< 3

备注

温度传感器主要用于测量芯片内部的温度变化。芯片内部温度通常高于环境温度，并且受到微控制器的时钟频率或 I/O 负载、外部散热环境等因素影响。

功能概述

下文将分节概述温度传感器的功能：

资源分配 - 介绍了部分参数，设置这些参数可以获取温度传感器句柄；还介绍了在温度传感器完成工作后如何回收资源。
启用及禁用温度传感器 - 介绍如何启用及禁用温度传感器。
获取测量的温度值 - 介绍如何获取实时温度值。
电源管理 - 介绍更改功耗模式（如 Light-sleep 模式）对温度传感器造成的影响。
线程安全 - 介绍如何使驱动程序具备线程安全性。

资源分配

ESP32-S3 只有一个内置温度传感器硬件。temperature_sensor_handle_t 表示温度传感器模块，该变量也是不同函数之间的纽带。通过使用相同的 temperature_sensor_handle_t 变量，可以在不同的函数调用中访问和修改温度传感器属性，以控制和管理温度传感器。该变量会作为温度 API 的参数，携带有关硬件和配置的信息，你只需创建类型为 temperature_sensor_handle_t 的指针，并将其传递给所需 API。

请在安装内置温度传感器模块前评估测量环境的温度范围。例如，如果在室内测量，环境温度可能在 10 °C ~ 30 °C；如果在灯泡中测量，环境温度则可能在 60 °C ~ 110 °C。在环境温度范围的基础上，请先根据以下值定义配置结构体 temperature_sensor_config_t，再安装内置温度传感器：

range_min：所测量温度范围的最小值。
range_max：所测量温度范围的最大值。

设置好温度范围后，将配置结构体传递给 temperature_sensor_install()，该函数将创建温度传感器模块并返回句柄。

如前文所述，不同测量范围对应不同测量误差。然而你无需自行比对测量误差，乐鑫提供了一个内部机制，可以根据所给温度范围选择最小误差。

温度传感器使用完毕后，请调用 temperature_sensor_uninstall() 释放相应资源。

创建温度传感器句柄

第 1 步：评估测量范围。本示例的温度范围为 20 °C ~ 50 °C。
第 2 步：配置测量范围，获取温度传感器句柄。

temperature_sensor_handle_t temp_handle = NULL;
temperature_sensor_config_t temp_sensor = {
    .range_min = 20,
    .range_max = 50,
};
ESP_ERROR_CHECK(temperature_sensor_install(&temp_sensor, &temp_handle));

启用及禁用温度传感器

调用 temperature_sensor_enable() 启用温度传感器。此时，内部温度传感器回路开始工作，驱动程序从初始化状态转为启用状态。
调用 temperature_sensor_disable() 禁用温度传感器。

获取测量的温度值

通过 temperature_sensor_enable() 启用温度传感器后，可以调用 temperature_sensor_get_celsius() 获取当前测量的温度值。

// 启用温度传感器
ESP_ERROR_CHECK(temperature_sensor_enable(temp_handle));
// 获取传输的传感器数据
float tsens_out;
ESP_ERROR_CHECK(temperature_sensor_get_celsius(temp_handle, &tsens_out));
printf("Temperature in %f °C\n", tsens_out);
// 温度传感器使用完毕后，禁用温度传感器，节约功耗
ESP_ERROR_CHECK(temperature_sensor_disable(temp_handle));

电源管理

由于温度传感器不使用 APB 时钟，无论是否激活 CONFIG_PM_ENABLE 启用电源管理，温度传感器仍可以继续工作。

线程安全

温度传感器中并未添加任何确保线程安全的额外保护，因为温度传感器通常只在一个任务中调用。如果要在不同任务中使用该驱动程序，请设置额外的锁进行保护。

意外情况

从芯片获取的温度值通常与环境温度不同，因为温度传感器内置于芯片，从某种程度来说，温度传感器测量的是芯片内的温度。
安装温度传感器失败时，如果驱动程序打印的错误信息为 the boundary you gave cannot meet the range of internal temperature sensor，说明内置温度传感器温度测量范围的限制影响了安装过程，该错误通常由以下几种不正确的 temperature_sensor_config_t 配置造成：
1. 超出温度测量范围，如 200 °C ~ 300 °C。
2. 超过了预定义测量范围的界限，如 40 °C ~ 110 °C。

应用示例

读取温度传感器测量值：peripherals/temperature_sensor/temp_sensor。

API 参考

Header File

components/driver/temperature_sensor/include/driver/temperature_sensor.h
This header file can be included with:
#include "driver/temperature_sensor.h"
This header file is a part of the API provided by the driver component. To declare that your component depends on driver, add the following to your CMakeLists.txt:
REQUIRES driver
or
PRIV_REQUIRES driver

Functions

esp_err_t temperature_sensor_install(const temperature_sensor_config_t *tsens_config, temperature_sensor_handle_t *ret_tsens)

Install temperature sensor driver.

参数

tsens_config -- Pointer to config structure.
ret_tsens -- Return the pointer of temperature sensor handle.

返回

ESP_OK if succeed

esp_err_t temperature_sensor_uninstall(temperature_sensor_handle_t tsens)

Uninstall the temperature sensor driver.

参数

tsens -- The handle created by temperature_sensor_install().

返回

ESP_OK if succeed.

esp_err_t temperature_sensor_enable(temperature_sensor_handle_t tsens)

Enable the temperature sensor.

参数

tsens -- The handle created by temperature_sensor_install().

返回

ESP_OK Success
ESP_ERR_INVALID_STATE if temperature sensor is enabled already.

esp_err_t temperature_sensor_disable(temperature_sensor_handle_t tsens)

Disable temperature sensor.

参数

tsens -- The handle created by temperature_sensor_install().

返回

ESP_OK Success
ESP_ERR_INVALID_STATE if temperature sensor is not enabled yet.

esp_err_t temperature_sensor_get_celsius(temperature_sensor_handle_t tsens, float *out_celsius)

Read temperature sensor data that is converted to degrees Celsius.

备注

Should not be called from interrupt.

参数

tsens -- The handle created by temperature_sensor_install().
out_celsius -- The measure output value.

返回

ESP_OK Success
ESP_ERR_INVALID_ARG invalid arguments
ESP_ERR_INVALID_STATE Temperature sensor is not enabled yet.
ESP_FAIL Parse the sensor data into ambient temperature failed (e.g. out of the range).

Structures

struct temperature_sensor_config_t

Configuration of measurement range for the temperature sensor.

备注

If you see the log the boundary you gave cannot meet the range of internal temperature sensor. You may need to refer to predefined range listed doc api-reference/peripherals/Temperature sensor.

Public Members

int range_min: the minimum value of the temperature you want to test

int range_max: the maximum value of the temperature you want to test

temperature_sensor_clk_src_t clk_src: the clock source of the temperature sensor.

Macros

TEMPERATURE_SENSOR_CONFIG_DEFAULT(min, max): temperature_sensor_config_t default constructure

Type Definitions

typedef struct temperature_sensor_obj_t *temperature_sensor_handle_t: Type of temperature sensor driver handle.

提供有关此文档的反馈