# Temperature Sensor

[中文]

## Introduction

The ESP32-H2 has a built-in sensor used to measure the chip's internal temperature. The temperature sensor module contains an 8-bit Sigma-Delta analog-to-digital converter (ADC) and a digital-to-analog converter (DAC) to compensate for the temperature measurement.

Due to restrictions of hardware, the sensor has predefined measurement ranges with specific measurement errors. See the table below for details.

Predefined Range (°C) | Error (°C)
--- | ---
50 ~ 125 | < 3
20 ~ 100 | < 2
-10 ~ 80 | < 1
-30 ~ 50 | < 2
-40 ~ 20 | < 3

Note

The temperature sensor is designed primarily to measure the temperature changes inside the chip. The internal temperature of a chip is usually higher than the ambient temperature, and is affected by factors such as the microcontroller's clock frequency or I/O load, and the external thermal environment.

## Functional Overview

The description of the temperature sensor functionality is divided into the following sections:

- Resource Allocation - covers which parameters should be set up to get a temperature sensor handle and how to recycle the resources when the temperature sensor finishes working.

- Enable and Disable Temperature Sensor - covers how to enable and disable the temperature sensor.

- Get Temperature Value - covers how to get the real-time temperature value.

- Install Temperature Threshold Callback - describes how to register a temperature threshold callback.

- Power Management - covers how the temperature sensor is affected when changing power mode (e.g., Light-sleep mode).

- IRAM Safe - describes tips on how to make the temperature sensor interrupt work better along with a disabled cache.

- Thread Safety - covers how to make the driver to be thread-safe.

- ETM Event and Task - describes what the events and tasks can be connected to the ETM channel.

### Resource Allocation

The ESP32-H2 has just one built-in temperature sensor hardware. The temperature sensor instance is represented by `temperature_sensor_handle_t`, which is also the bond of the context. By using `temperature_sensor_handle_t`, the temperature sensor properties can be accessed and modified in different function calls to control and manage the temperature sensor. The variable would always be the parameter of the temperature APIs with the information of hardware and configurations, so you can just create a pointer of type `temperature_sensor_handle_t` and passing to APIs as needed.

In order to install a built-in temperature sensor instance, the first thing is to evaluate the temperature range in your detection environment. For example, if the testing environment is in a room, the range you evaluate might be 10 °C ~ 30 °C; if the testing in a lamp bulb, the range you evaluate might be 60 °C ~ 110 °C. Based on that, configuration structure `temperature_sensor_config_t` should be defined in advance:

- `range_min`: The minimum value of the testing range you have evaluated.

- `range_max`: The maximum value of the testing range you have evaluated.

- `allow_pd` configures if the driver allows the system to power down the peripheral in light sleep mode. Before entering sleep, the system will backup the temperature sensor register context, which will be restored later when the system exit the sleep mode. Powering down the peripheral can save more power, but at the cost of more memory consumed to save the register context. It's a tradeoff between power consumption and memory consumption. This configuration option relies on specific hardware feature, if you enable it on an unsupported chip, you will see error message like `not able to power down in light sleep`.

After the ranges are set, the structure could be passed to `temperature_sensor_install()`, which will instantiate the temperature sensor instance and return a handle.

As mentioned above, different measure ranges have different measurement errors. You do not need to care about the measurement error because we have an internal mechanism to choose the minimum error according to the given range.

If the temperature sensor is no longer needed, you need to call `temperature_sensor_uninstall()` to free the temperature sensor resource.

#### Creating a Temperature Sensor Handle

- Step 1: Evaluate the testing range. In this example, the range is 20 °C ~ 50 °C.

- Step 2: Configure the range and obtain a handle.

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

### Enable and Disable Temperature Sensor

1. Enable the temperature sensor by calling `temperature_sensor_enable()`. The internal temperature sensor circuit will start to work. The driver state will transit from init to enable.

2. To Disable the temperature sensor, please call `temperature_sensor_disable()`.

### Get Temperature Value

After the temperature sensor is enabled by `temperature_sensor_enable()`, you can get the current temperature by calling `temperature_sensor_get_celsius()`.

    // Enable temperature sensor
    ESP_ERROR_CHECK(temperature_sensor_enable(temp_handle));
    // Get converted sensor data
    float tsens_out;
    ESP_ERROR_CHECK(temperature_sensor_get_celsius(temp_handle, &tsens_out));
    printf("Temperature in %f °C\n", tsens_out);
    // Disable the temperature sensor if it is not needed and save the power
    ESP_ERROR_CHECK(temperature_sensor_disable(temp_handle));

### Install Temperature Threshold Callback

ESP32-H2 supports automatically triggering to monitor the temperature value continuously. When the temperature value reaches a given threshold, an interrupt will happen. Thus you can install your own interrupt callback functions to do what they want, e.g., alarm, restart, etc. The following information indicates how to prepare a threshold callback.

- `temperature_sensor_event_callbacks_t::on_threshold`: As this function is called within the ISR context, you must ensure that the function does not attempt to block, e.g., by making sure that only FreeRTOS APIs with the `ISR` suffix are called from within the function, etc. The function prototype is declared in `temperature_thres_cb_t`.

You can save your own context to `temperature_sensor_register_callbacks()` as well, via the parameter `user_arg`. The user data will be directly passed to the callback function.

    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;
    }

    // Callback configurations
    temperature_sensor_abs_threshold_config_t threshold_cfg = {
        .high_threshold = 50,
        .low_threshold = -10,
    };
    // Set absolute value monitor threshold.
    temperature_sensor_set_absolute_threshold(temp_sensor, &threshold_cfg);
    // Register interrupt callback
    temperature_sensor_event_callbacks_t cbs = {
        .on_threshold = temp_sensor_monitor_cbs,
    };
    // Install temperature callback.
    temperature_sensor_register_callbacks(temp_sensor, &cbs, NULL);

### Power Management

As the temperature sensor does not use the APB clock, it will keep working no matter if the power management is enabled with `CONFIG_PM_ENABLE`.

### IRAM Safe

By default, the temperature sensor interrupt will be deferred when the cache is disabled for reasons like writing/erasing flash. Thus the event callback functions will not get executed in time, which is not expected in a real-time application.

There is a Kconfig option CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE that will:

1. Enable the interrupt that is being serviced even when the cache is disabled.

2. Place all functions that are used by the ISR into IRAM.

This allows the interrupt to run while the cache is disabled but comes at the cost of increased IRAM consumption.

### Thread Safety

In the temperature sensor driver, we do not add any protection to ensure the thread safety, because typically this driver is only supposed to be used in one task. If you have to use this driver in different tasks, please add extra locks to protect it.

### ETM Event and Task

Temperature Sensor is able to generate events that can interact with the ETM module. The supported events are listed in the `temperature_sensor_etm_event_type_t`. You can call `temperature_sensor_new_etm_event()` to get the corresponding ETM event handle. The supported tasks are listed in the `temperature_sensor_etm_task_type_t`. You can call `temperature_sensor_new_etm_task()` to get the corresponding ETM task handle.

Note

- `TEMPERATURE_SENSOR_EVENT_OVER_LIMIT` for `temperature_sensor_etm_event_type_t::event_type` depends on what kind of threshold you set first. If you set the absolute threshold by `temperature_sensor_set_absolute_threshold()`, then the `TEMPERATURE_SENSOR_EVENT_OVER_LIMIT` refers to absolute threshold. Likewise, if you set the delta threshold by `temperature_sensor_set_delta_threshold()`, then the `TEMPERATURE_SENSOR_EVENT_OVER_LIMIT` refers to delta threshold.

For how to connect the event and task to an ETM channel, please refer to the ETM documentation.

## Unexpected Behaviors

1. The value you get from the chip is usually different from the ambient temperature. It is because the temperature sensor is built inside the chip. To some extent, it measures the temperature of the chip.

2. When installing the temperature sensor, the driver may print `the boundary you gave cannot meet the range of internal temperature sensor`. It is because the built-in temperature sensor has a testing limit. The error comes from the incorrect configuration of `temperature_sensor_config_t` as follow:

   > 1. Totally out of range, like 200 °C ~ 300 °C.

   > 2. Cross the boundary of each predefined measurement. like 40 °C ~ 110 °C.

## Application Examples

- peripherals/temperature_sensor/temp_sensor demonstrates how to use the built-in temperature sensor, showcasing the measurement range and error based on different DAC levels and offsets.

- peripherals/temperature_sensor/temp_sensor_monitor demonstrates how to use the temperature sensor to automatically monitor temperature values continuously, triggering an interrupt when a specific value is reached or when the change between two consecutive samplings is larger/smaller than the settings.

## API Reference

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

  Parameters:

    - tsens_config -- Pointer to config structure.

    - ret_tsens -- Return the pointer of temperature sensor handle.

  Returns:

    - ESP_OK if succeed

esp_err_t temperature_sensor_uninstall(temperature_sensor_handle_t tsens)

  Uninstall the temperature sensor driver.

  Parameters:

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

  Returns:

    - ESP_OK if succeed.

esp_err_t temperature_sensor_enable(temperature_sensor_handle_t tsens)

  Enable the temperature sensor.

  Parameters:

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

  Returns:

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

  Parameters:

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

  Returns:

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

  Note

  Should not be called from interrupt.

  Parameters:

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

    - out_celsius -- The measure output value.

  Returns:

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

  Note

  This function should not be called with `temperature_sensor_set_delta_threshold`.

  Parameters:

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

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

  Returns:

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

  Note

  This function should not be called with `temperature_sensor_set_absolute_threshold`

  Parameters:

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

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

  Returns:

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

  Parameters:

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

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

    - user_arg -- Callback argument.

  Returns:

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

  Note

  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::[anonymous] 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

### Header File

- components/esp_driver_tsens/include/driver/temperature_sensor_etm.h

- This header file can be included with:

  >     #include "driver/temperature_sensor_etm.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_new_etm_event(temperature_sensor_handle_t tsens, const temperature_sensor_etm_event_config_t *config, esp_etm_event_handle_t *out_event)

  Get the ETM event for Temperature Sensor.

  Note

  The created ETM event object can be deleted later by calling `esp_etm_del_event`

  Parameters:

    - tsens -- [in] Temperature Sensor handle, allocated by `temperature_sensor_install()`

    - config -- [in] Temperature Sensor ETM event configuration

    - out_event -- [out] Returned ETM event handle

  Returns:

    - ESP_OK: Get ETM event successfully

    - ESP_ERR_INVALID_ARG: Get ETM event failed because of invalid argument

    - ESP_FAIL: Get ETM event failed because of other error

esp_err_t temperature_sensor_new_etm_task(temperature_sensor_handle_t tsens, const temperature_sensor_etm_task_config_t *config, esp_etm_task_handle_t *out_task)

  Get the ETM task for Temperature Sensor.

  Note

  The created ETM task object can be deleted later by calling `esp_etm_del_task`

  Parameters:

    - tsens -- [in] Temperature Sensor, allocated by `temperature_sensor_install()`

    - config -- [in] Temperature Sensor ETM task configuration

    - out_task -- [out] Returned ETM task handle

  Returns:

    - ESP_OK: Get ETM task successfully

    - ESP_ERR_INVALID_ARG: Get ETM task failed because of invalid argument

    - ESP_FAIL: Get ETM task failed because of other error

### Structures

struct temperature_sensor_etm_event_config_t

  Temperature Sensor ETM event configuration.

  Public Members

  temperature_sensor_etm_event_type_t event_type

    Temperature Sensor ETM event type

struct temperature_sensor_etm_task_config_t

  Temperature Sensor ETM task configuration.

  Public Members

  temperature_sensor_etm_task_type_t task_type

    Temperature Sensor ETM task type

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.