# 温度传感器

[English]

## 简介

ESP32-C5 内置传感器，用于测量芯片内部的温度。该温度传感器模组包含一个 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 模式）对温度传感器造成的影响。

- IRAM 安全 - 介绍在禁用 cache 时如何提高温度传感器的性能。

- 线程安全 - 介绍如何使驱动程序具备线程安全性。

### 资源分配

ESP32-C5 只有一个内置温度传感器硬件。`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`：所测量温度范围的最大值。

- `allow_pd` 配置驱动程序是否允许系统在睡眠模式下关闭外设电源。在进入睡眠之前，系统将备份温度传感器寄存器上下文，当系统退出睡眠模式时，这些上下文将被恢复。关闭外设可以节省更多功耗，但代价是消耗更多内存来保存寄存器上下文。你需要在功耗和内存消耗之间做权衡。此配置选项依赖于特定的硬件功能，如果在不支持的芯片上启用它，你将看到类似 `not able to power down in light sleep` 的错误消息。

设置好温度范围后，将配置结构体传递给 `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));

### 启用及禁用温度传感器

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

2. 调用 `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));

### 安装温度阈值回调函数

ESP32-C5 支持自动触发温度传感器，持续监测内部温度，内部温度达到给定阈值时将触发中断。因此，可以安装中断回调函数执行所需操作，如报警、重启等。下文介绍了如何准备阈值回调函数。

- 函数 `temperature_sensor_event_callbacks_t::on_threshold` 在中断服务程序 (ISR) 的上下文中调用，请确保该函数不会涉及 block 操作。为此，可以检查调用 API 的后缀，确保仅从函数内调用具有 `ISR` 后缀的 FreeRTOS API 等。函数原型在 `temperature_thres_cb_t` 中声明。

通过参数 `user_arg` 可以将自定义上下文保存到 `temperature_sensor_register_callbacks()` 中，用户数据将直接传递给回调函数。

    IRAM_ATTR static bool temp_sensor_monitor_cbs(temperature_sensor_handle_t tsens, const temperature_sensor_threshold_event_data_t *edata, void *user_data)
    {
        ESP_DRAM_LOGI("tsens", "Temperature value is higher or lower than threshold, value is %d\n...\n\n", edata->celsius_value);
        return false;
    }

    // 配置回调函数
    temperature_sensor_abs_threshold_config_t threshold_cfg = {
        .high_threshold = 50,
        .low_threshold = -10,
    };
    // 设置监控阈值
    temperature_sensor_set_absolute_threshold(temp_sensor, &threshold_cfg);
    // 注册中断回调函数
    temperature_sensor_event_callbacks_t cbs = {
        .on_threshold = temp_sensor_monitor_cbs,
    };
    // 安装温度回调函数
    temperature_sensor_register_callbacks(temp_sensor, &cbs, NULL);

### 电源管理

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

### IRAM 安全

默认情况下，禁用 cache 时，写入/擦除 flash 等原因将导致温度传感器中断延迟，事件回调函数也将延迟执行。在实时应用程序中，应避免此类情况。

因此，可以启用 Kconfig 选项 CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE，该选项：

1. 支持在禁用 cache 时启用所需中断

2. 支持将 ISR 使用的所有函数存放在 IRAM 中

启用该选项可以保证 cache 禁用时的中断运行，但会占用更多的 IRAM。

### 线程安全

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

## 意外情况

1. 从芯片获取的温度值通常与环境温度不同，因为温度传感器内置于芯片，从某种程度来说，温度传感器测量的是芯片内的温度。

2. 安装温度传感器失败时，如果驱动程序打印的错误信息为 `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 演示了如何使用内置温度传感器，并展示了 DAC 电平和偏移量不同时的测量范围和误差。

- peripherals/temperature_sensor/temp_sensor_monitor 演示了如何使用温度传感器连续自动监测温度值，当温度达到特定值或或两个连续的采样之间的变化大于/小于设置时，触发中断。

## 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 on `esp_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).

esp_err_t temperature_sensor_set_absolute_threshold(temperature_sensor_handle_t tsens, const temperature_sensor_abs_threshold_config_t *abs_cfg)

  Set temperature sensor absolute mode automatic monitor.

  备注

  This function should not be called with `temperature_sensor_set_delta_threshold`.

  参数:

    - tsens -- The handle created by `temperature_sensor_install()`.

    - abs_cfg -- Configuration of temperature sensor absolute mode interrupt, see `temperature_sensor_abs_threshold_config_t`.

  返回:

    - ESP_OK: Set absolute threshold successfully.

    - ESP_ERR_INVALID_STATE: Set absolute threshold failed because of wrong state.

    - ESP_ERR_INVALID_ARG: Set absolute threshold failed because of invalid argument.

esp_err_t temperature_sensor_set_delta_threshold(temperature_sensor_handle_t tsens, const temperature_sensor_delta_threshold_config_t *delta_cfg)

  Set temperature sensor differential mode automatic monitor.

  备注

  This function should not be called with `temperature_sensor_set_absolute_threshold`

  参数:

    - tsens -- The handle created by `temperature_sensor_install()`.

    - delta_cfg -- Configuration of temperature sensor delta mode interrupt, see `temperature_sensor_delta_threshold_config_t`.

  返回:

    - ESP_OK: Set differential value threshold successfully.

    - ESP_ERR_INVALID_STATE: Set absolute threshold failed because of wrong state.

    - ESP_ERR_INVALID_ARG: Set differential value threshold failed because of invalid argument.

esp_err_t temperature_sensor_register_callbacks(temperature_sensor_handle_t tsens, const temperature_sensor_event_callbacks_t *cbs, void *user_arg)

  Install temperature sensor interrupt callback. Temperature sensor interrupt will be enabled at same time.

  参数:

    - tsens -- The handle created by `temperature_sensor_install()`.

    - cbs -- Pointer to the group of temperature sensor interrupt callbacks.

    - user_arg -- Callback argument.

  返回:

    - ESP_OK: Set event callbacks successfully

    - ESP_ERR_INVALID_ARG: Set event callbacks failed because of invalid argument

    - ESP_FAIL: Set event callbacks failed because of other error

### 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.

  uint32_t allow_pd

    If set, the driver will backup/restore the temperature sensor registers before/after entering/exist sleep mode. By this approach, the system can power off temperature sensor's power domain. This can save power, but at the expense of more RAM being consumed

  struct temperature_sensor_config_t flags

    Temperature sensor config flags

struct temperature_sensor_threshold_event_data_t

  Temperature sensor event data.

  Public Members

  int celsius_value

    Celsius value in interrupt callback.

  temperature_val_intr_condition_t intr_condition

    Can be used to judge temperature sensor interrupts in which reason

struct temperature_sensor_event_callbacks_t

  Group of temperature sensor callback functions, all of them will be run in ISR.

  Public Members

  temperature_thres_cb_t on_threshold

    Temperature value interrupt callback

struct temperature_sensor_abs_threshold_config_t

  Config options for temperature value absolute interrupt.

  Public Members

  float high_threshold

    High threshold value(Celsius). Interrupt will be triggered if temperature value is higher than this value

  float low_threshold

    Low threshold value(Celsius). Interrupt will be triggered if temperature value is lower than this value

struct temperature_sensor_delta_threshold_config_t

  Config options for temperature value delta interrupt.

  Public Members

  float increase_delta

    Interrupt will be triggered if the temperature increment of two consecutive samplings if larger than `increase_delta`

  float decrease_delta

    Interrupt will be triggered if the temperature decrement of two consecutive samplings if smaller than `decrease_delta`

### 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.

typedef bool (*temperature_thres_cb_t)(temperature_sensor_handle_t tsens, const temperature_sensor_threshold_event_data_t *edata, void *user_data)

  Callback for temperature sensor threshold interrupt.

  Param tsens:

    [in] The handle created by `temperature_sensor_install()`.

  Param edata:

    [in] temperature sensor event data, fed by driver.

  Param user_data:

    [in] User data, set in `temperature_sensor_register_callbacks()`.

  Return:

    Whether a high priority task has been waken up by this function.

### Enumerations

enum temperature_val_intr_condition_t

  Enum for temperature sensor interrupt condition.

  Values:

  enumerator TEMPERATURE_VAL_HIGHER_THAN_HIGH_THRESHOLD

    temperature sensor value is higher than high threshold

  enumerator TEMPERATURE_VAL_LOWER_THAN_LOW_THRESHOLD

    temperature sensor value is lower than low threshold

### Header File

- components/hal/include/hal/temperature_sensor_types.h

- 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

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

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。