# 温度传感器

[English]

## 简介

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`：所测量温度范围的最大值。

- `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));

### 电源管理

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

### 线程安全

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

## 意外情况

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 电平和偏移量不同时的测量范围和误差。

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

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

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

- 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

此文档对您有帮助吗？

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

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