温度传感器
简介
ESP32-C3 内置传感器,用于测量芯片内部的温度。该温度传感器模组包含一个 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-C3 只有一个内置温度传感器硬件。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_config = TEMPERATURE_SENSOR_CONFIG_DEFAULT(20, 50);
ESP_ERROR_CHECK(temperature_sensor_install(&temp_sensor_config, &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
配置造成:超出温度测量范围,如 200 °C ~ 300 °C。
超过了预定义测量范围的界限,如 40 °C ~ 110 °C。
应用示例
peripherals/temperature_sensor/temp_sensor 演示了如何使用内置温度传感器,并展示了 DAC 电平和偏移量不同时的测量范围和误差。
API 参考
Header File
components/esp_driver_tsens/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
esp_driver_tsens
component. To declare that your component depends onesp_driver_tsens
, add the following to your CMakeLists.txt:REQUIRES esp_driver_tsens
or
PRIV_REQUIRES esp_driver_tsens
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 docapi-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.
-
int range_min
Macros
-
TEMPERATURE_SENSOR_CONFIG_DEFAULT(min, max)
temperature_sensor_config_t default constructor
Type Definitions
-
typedef struct temperature_sensor_obj_t *temperature_sensor_handle_t
Type of temperature sensor driver handle.
Header File
This header file can be included with:
#include "hal/temperature_sensor_types.h"
Type Definitions
-
typedef soc_periph_temperature_sensor_clk_src_t temperature_sensor_clk_src_t
temperature sensor clock source
Enumerations
-
enum temperature_sensor_etm_event_type_t
temperature sensor event types enum
Values:
-
enumerator TEMPERATURE_SENSOR_EVENT_OVER_LIMIT
Temperature sensor over limit event
-
enumerator TEMPERATURE_SENSOR_EVENT_MAX
Maximum number of temperature sensor events
-
enumerator TEMPERATURE_SENSOR_EVENT_OVER_LIMIT
-
enum temperature_sensor_etm_task_type_t
temperature sensor task types enum
Values:
-
enumerator TEMPERATURE_SENSOR_TASK_START
Temperature sensor start task
-
enumerator TEMPERATURE_SENSOR_TASK_STOP
Temperature sensor stop task
-
enumerator TEMPERATURE_SENSOR_TASK_MAX
Maximum number of temperature sensor tasks
-
enumerator TEMPERATURE_SENSOR_TASK_START