mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
Merge branch 'docs/add_Chinese_translation_for_api-reference/peripherals/temp_sensor.rst_backport_v5.1' into 'release/v5.1'
docs: provide CN translation for api-reference/peripherals/temp_sensor.rst (backport v5.1) See merge request espressif/esp-idf!25821
This commit is contained in:
Krzysztof Budzynski
commit
752a99d3d1
@ -1,66 +1,75 @@
|
||||
Temperature Sensor
|
||||
==================
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
The {IDF_TARGET_NAME} has a built-in sensor used to measure the chip's internal temperature. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a DAC to compensate for the temperature offset.
|
||||
The {IDF_TARGET_NAME} 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 |
|
||||
+------------------------+------------------------+
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - 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 temperature value depends on factors like microcontroller clock frequency or I/O load. Generally, the chip's internal temperature might be higher than the ambient temperature.
|
||||
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:
|
||||
|
||||
.. list::
|
||||
|
||||
- `Resource Allocation <#resource-allocation>`__ - covers which parameters should be set up to get a temperature sensor handle and how to recycle the resources when temperature sensor finishes working.
|
||||
- `Enable and Disable Temperature Sensor <#enable-and-disable-temperature-sensor>`__ - covers how to enable and disable the temperature sensor.
|
||||
- `Get Temperature Value <#get-temperature-value>`__ - covers how to get the real-time temperature value.
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - `Temperature Threshold Interrupt <#install-temperature-threshold-callback>`__ - describes how to register a temperature threshold callback.
|
||||
- `Power Management <#power-management>`__ - covers how temperature sensor is affected when changing power mode (i.e. light sleep).
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - `IRAM Safe <#iram-safe>`__ - describes tips on how to make the temperature sensor interrupt work better along with a disabled cache.
|
||||
- `Thread Safety <#thread-safety>`__ - covers how to make the driver to be thread safe.
|
||||
- :ref:`temp-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.
|
||||
- :ref:`temp-enable-and-disable-temperature-sensor` - covers how to enable and disable the temperature sensor.
|
||||
- :ref:`temp-get-temperature-value` - covers how to get the real-time temperature value.
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - :ref:`temp-install-temperature-threshold-callback` - describes how to register a temperature threshold callback.
|
||||
- :ref:`temp-power-management` - covers how the temperature sensor is affected when changing power mode (e.g., Light-sleep mode).
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - :ref:`temp-iram-safe` - describes tips on how to make the temperature sensor interrupt work better along with a disabled cache.
|
||||
- :ref:`temp-thread-safety` - covers how to make the driver to be thread-safe.
|
||||
|
||||
.. _temp-resource-allocation:
|
||||
|
||||
Resource Allocation
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The {IDF_TARGET_NAME} has just one built-in temperature sensor hardware. The temperature sensor instance is represented by :cpp:type:`temperature_sensor_handle_t`, which is also the bond of the context. It would always be the parameter of the temperature APIs with the information of hardware and configurations, so user can just create a pointer of type :cpp:type:`temperature_sensor_handle_t` and passing to APIs as needed.
|
||||
The {IDF_TARGET_NAME} has just one built-in temperature sensor hardware. The temperature sensor instance is represented by :cpp:type:`temperature_sensor_handle_t`, which is also the bond of the context. By using :cpp:type:`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 :cpp: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, the following configuration structure should be defined in advance:
|
||||
:cpp:type:`temperature_sensor_config_t`:
|
||||
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 :cpp:type:`temperature_sensor_config_t` should be defined in advance:
|
||||
|
||||
- :cpp:member:`range_min`. The minimum value of testing range you have evaluated.
|
||||
- :cpp:member:`range_max`. The maximum value of testing range you have evaluated.
|
||||
- :cpp:member:`range_min`: The minimum value of the testing range you have evaluated.
|
||||
- :cpp:member:`range_max`: The maximum value of the testing range you have evaluated.
|
||||
|
||||
After the ranges are set, the structure could be passed to :cpp:func:`temperature_sensor_install`, which will instantiate the temperature sensor instance and return a handle.
|
||||
|
||||
As mentioned above, different measure ranges have different measurement errors. The user doesn't need to care about the measurement error because we have an internal mechanism to choose the minimum error according to the given range.
|
||||
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 :cpp:func:`temperature_sensor_uninstall` to free the temperature sensor resource.
|
||||
|
||||
Creating a Temperature Sensor Handle
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* Step1: Evaluate the testing range. In this example, the range is 20 °C ~ 50 °C.
|
||||
* Step2: Configure the range and obtain a 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.
|
||||
|
||||
.. code:: c
|
||||
|
||||
@ -71,16 +80,20 @@ Creating a Temperature Sensor Handle
|
||||
};
|
||||
ESP_ERROR_CHECK(temperature_sensor_install(&temp_sensor, &temp_handle));
|
||||
|
||||
.. _temp-enable-and-disable-temperature-sensor:
|
||||
|
||||
Enable and Disable Temperature Sensor
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. Enable the temperature sensor by calling :cpp:func:`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 :cpp:func:`temperature_sensor_disable`.
|
||||
|
||||
.. _temp-get-temperature-value:
|
||||
|
||||
Get Temperature Value
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After the temperature sensor is enabled by :cpp:func:`temperature_sensor_enable`, user can get the current temperature by calling :cpp:func:`temperature_sensor_get_celsius`.
|
||||
After the temperature sensor is enabled by :cpp:func:`temperature_sensor_enable`, you can get the current temperature by calling :cpp:func:`temperature_sensor_get_celsius`.
|
||||
|
||||
.. code:: c
|
||||
|
||||
@ -90,17 +103,20 @@ After the temperature sensor is enabled by :cpp:func:`temperature_sensor_enable`
|
||||
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's not needed and save the power
|
||||
// Disable the temperature sensor if it is not needed and save the power
|
||||
ESP_ERROR_CHECK(temperature_sensor_disable(temp_handle));
|
||||
|
||||
|
||||
.. only:: SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-install-temperature-threshold-callback:
|
||||
|
||||
Install Temperature Threshold Callback
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_NAME} supports automatically triggering to monitor the temperature value continuously. When temperature value reaches a given threshold, an interrupt will happen. Thus users can install their own interrupt callback functions to do what they want. (e.g. alarm, restart, etc.). Following information indicates how to prepare a threshold callback.
|
||||
{IDF_TARGET_NAME} 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.
|
||||
|
||||
- :cpp:member:`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 ``ISR`` suffix are called from within the function, etc.). The function prototype is declared in :cpp:type:`temperature_thres_cb_t`.
|
||||
- :cpp:member:`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 :cpp:type:`temperature_thres_cb_t`.
|
||||
|
||||
You can save your own context to :cpp:func:`temperature_sensor_register_callbacks` as well, via the parameter ``user_arg``. The user data will be directly passed to the callback function.
|
||||
|
||||
@ -126,36 +142,50 @@ After the temperature sensor is enabled by :cpp:func:`temperature_sensor_enable`
|
||||
// Install temperature callback.
|
||||
temperature_sensor_register_callbacks(temp_sensor, &cbs, NULL);
|
||||
|
||||
.. _temp-power-management:
|
||||
|
||||
.. only:: not SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-power-management:
|
||||
|
||||
Power Management
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
When power management is enabled (i.e. ``CONFIG_PM_ENABLE`` is on), temperature sensor will still keep working because it uses XTAL clock (on ESP32-C3) or RTC clock (on ESP32-S2/S3).
|
||||
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``.
|
||||
|
||||
.. only:: SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-iram-safe:
|
||||
|
||||
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.
|
||||
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's a Kconfig option :ref:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE` that will:
|
||||
There is a Kconfig option :ref:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE` that will:
|
||||
|
||||
1. Enable the interrupt being serviced even when cache is disabled.
|
||||
2. Place all functions that used by the ISR into IRAM.
|
||||
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 will allow the interrupt to run while the cache is disabled but will come at the cost of increased IRAM consumption.
|
||||
This allows the interrupt to run while the cache is disabled but comes at the cost of increased IRAM consumption.
|
||||
|
||||
.. _temp-thread-safety:
|
||||
|
||||
.. only:: not SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-thread-safety:
|
||||
|
||||
Thread Safety
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
In temperature sensor we don't add any protection to keep the thread safe. Because from the common usage, temperature sensor should only be called in one task. If you must use this driver in different tasks, please add extra locks to protect it.
|
||||
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.
|
||||
|
||||
Unexpected Behaviors
|
||||
--------------------
|
||||
|
||||
1. The value user gets 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.
|
||||
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 gives a 'the boundary you gave cannot meet the range of internal temperature sensor' error feedback. It is because the built-in temperature sensor has testing limit. The error due to setting :cpp:type:`temperature_sensor_config_t`:
|
||||
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 :cpp:type:`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.
|
||||
@ -166,7 +196,7 @@ Application Example
|
||||
.. list::
|
||||
|
||||
* Temperature sensor reading example: :example:`peripherals/temperature_sensor/temp_sensor`.
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: * Temperature sensor value monitor example: :example:`peripherals/temperature_sensor/temp_sensor`.
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: * Temperature sensor value monitor example: :example:`peripherals/temperature_sensor/temp_sensor_monitor`.
|
||||
|
||||
API Reference
|
||||
----------------------------------
|
||||
|
||||
@ -1 +1,204 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/temp_sensor.rst
|
||||
温度传感器
|
||||
==================
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
简介
|
||||
------------
|
||||
|
||||
{IDF_TARGET_NAME} 内置传感器，用于测量芯片内部的温度。该温度传感器模组包含一个 8 位 Sigma-Delta 模拟-数字转换器 (ADC) 和一个数字-模拟转换器 (DAC)，可以补偿测量结果，减少温度测量的误差。
|
||||
|
||||
由于硬件限制，温度传感器存在预定义的测量范围及其对应误差，详见下表：
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
:widths: 50 50
|
||||
:align: center
|
||||
|
||||
* - 预定义测量范围 (°C)
|
||||
- 测量误差 (°C)
|
||||
* - 50 ~ 125
|
||||
- < 3
|
||||
* - 20 ~ 100
|
||||
- < 2
|
||||
* - -10 ~ 80
|
||||
- < 1
|
||||
* - -30 ~ 50
|
||||
- < 2
|
||||
* - -40 ~ 20
|
||||
- < 3
|
||||
|
||||
.. note::
|
||||
|
||||
温度传感器主要用于测量芯片内部的温度变化。芯片内部温度通常高于环境温度，并且受到微控制器的时钟频率或 I/O 负载、外部散热环境等因素影响。
|
||||
|
||||
功能概述
|
||||
-------------------
|
||||
|
||||
下文将分节概述温度传感器的功能：
|
||||
|
||||
.. list::
|
||||
|
||||
- :ref:`temp-resource-allocation` - 介绍了部分参数，设置这些参数可以获取温度传感器句柄；还介绍了在温度传感器完成工作后如何回收资源。
|
||||
- :ref:`temp-enable-and-disable-temperature-sensor` - 介绍如何启用及禁用温度传感器。
|
||||
- :ref:`temp-get-temperature-value` - 介绍如何获取实时温度值。
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - :ref:`temp-install-temperature-threshold-callback` - 介绍如何注册温度阈值回调函数。
|
||||
- :ref:`temp-power-management` - 介绍更改功耗模式（如 Light-sleep 模式）对温度传感器造成的影响。
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: - :ref:`temp-iram-safe` - 介绍在禁用 cache 时如何提高温度传感器的性能。
|
||||
- :ref:`temp-thread-safety` - 介绍如何使驱动程序具备线程安全性。
|
||||
|
||||
.. _temp-resource-allocation:
|
||||
|
||||
资源分配
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_NAME} 只有一个内置温度传感器硬件。:cpp:type:`temperature_sensor_handle_t` 表示温度传感器模块，该变量也是不同函数之间的纽带。通过使用相同的 :cpp:type:`temperature_sensor_handle_t` 变量，可以在不同的函数调用中访问和修改温度传感器属性，以控制和管理温度传感器。该变量会作为温度 API 的参数，携带有关硬件和配置的信息，你只需创建类型为 :cpp:type:`temperature_sensor_handle_t` 的指针，并将其传递给所需 API。
|
||||
|
||||
请在安装内置温度传感器模块前评估测量环境的温度范围。例如，如果在室内测量，环境温度可能在 10 °C ~ 30 °C；如果在灯泡中测量，环境温度则可能在 60 °C ~ 110 °C。在环境温度范围的基础上，请先根据以下值定义配置结构体 :cpp:type:`temperature_sensor_config_t`，再安装内置温度传感器：
|
||||
|
||||
- :cpp:member:`range_min`：所测量温度范围的最小值。
|
||||
- :cpp:member:`range_max`：所测量温度范围的最大值。
|
||||
|
||||
设置好温度范围后，将配置结构体传递给 :cpp:func:`temperature_sensor_install`，该函数将创建温度传感器模块并返回句柄。
|
||||
|
||||
如前文所述，不同测量范围对应不同测量误差。然而你无需自行比对测量误差，乐鑫提供了一个内部机制，可以根据所给温度范围选择最小误差。
|
||||
|
||||
温度传感器使用完毕后，请调用 :cpp:func:`temperature_sensor_uninstall` 释放相应资源。
|
||||
|
||||
创建温度传感器句柄
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* 第 1 步：评估测量范围。本示例的温度范围为 20 °C ~ 50 °C。
|
||||
* 第 2 步：配置测量范围，获取温度传感器句柄。
|
||||
|
||||
.. code:: c
|
||||
|
||||
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));
|
||||
|
||||
.. _temp-enable-and-disable-temperature-sensor:
|
||||
|
||||
启用及禁用温度传感器
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. 调用 :cpp:func:`temperature_sensor_enable` 启用温度传感器。此时，内部温度传感器回路开始工作，驱动程序从初始化状态转为启用状态。
|
||||
2. 调用 :cpp:func:`temperature_sensor_disable` 禁用温度传感器。
|
||||
|
||||
.. _temp-get-temperature-value:
|
||||
|
||||
获取测量的温度值
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
通过 :cpp:func:`temperature_sensor_enable` 启用温度传感器后，可以调用 :cpp:func:`temperature_sensor_get_celsius` 获取当前测量的温度值。
|
||||
|
||||
.. code:: c
|
||||
|
||||
// 启用温度传感器
|
||||
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));
|
||||
|
||||
|
||||
.. only:: SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-install-temperature-threshold-callback:
|
||||
|
||||
安装温度阈值回调函数
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
{IDF_TARGET_NAME} 支持自动触发温度传感器，持续监测内部温度，内部温度达到给定阈值时将触发中断。因此，可以安装中断回调函数执行所需操作，如报警、重启等。下文介绍了如何准备阈值回调函数。
|
||||
|
||||
- 函数 :cpp:member:`temperature_sensor_event_callbacks_t::on_threshold` 在中断服务程序 (ISR) 的上下文中调用，请确保该函数不会涉及 block 操作。为此，可以检查调用 API 的后缀，确保仅从函数内调用具有 ``ISR`` 后缀的 FreeRTOS API 等。函数原型在 :cpp:type:`temperature_thres_cb_t` 中声明。
|
||||
|
||||
通过参数 ``user_arg`` 可以将自定义上下文保存到 :cpp:func:`temperature_sensor_register_callbacks` 中，用户数据将直接传递给回调函数。
|
||||
|
||||
.. code:: c
|
||||
|
||||
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);
|
||||
|
||||
.. _temp-power-management:
|
||||
|
||||
.. only:: not SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-power-management:
|
||||
|
||||
电源管理
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
由于温度传感器不使用 APB 时钟，无论是否激活 ``CONFIG_PM_ENABLE`` 启用电源管理，温度传感器仍可以继续工作。
|
||||
|
||||
.. only:: SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-iram-safe:
|
||||
|
||||
IRAM 安全
|
||||
^^^^^^^^^
|
||||
|
||||
默认情况下，禁用 cache 时，写入/擦除 flash 等原因将导致温度传感器中断延迟，事件回调函数也将延迟执行。在实时应用程序中，应避免此类情况。
|
||||
|
||||
因此，可以启用 Kconfig 选项 :ref:`CONFIG_TEMP_SENSOR_ISR_IRAM_SAFE`，该选项：
|
||||
|
||||
1. 支持在禁用 cache 时启用所需中断
|
||||
2. 支持将 ISR 使用的所有函数存放在 IRAM 中
|
||||
|
||||
启用该选项可以保证 cache 禁用时的中断运行，但会占用更多的 IRAM。
|
||||
|
||||
.. _temp-thread-safety:
|
||||
|
||||
.. only:: not SOC_TEMPERATURE_SENSOR_INTR_SUPPORT
|
||||
|
||||
.. _temp-thread-safety:
|
||||
|
||||
线程安全
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
温度传感器中并未添加任何确保线程安全的额外保护，因为温度传感器通常只在一个任务中调用。如果要在不同任务中使用该驱动程序，请设置额外的锁进行保护。
|
||||
|
||||
意外情况
|
||||
--------------------
|
||||
|
||||
1. 从芯片获取的温度值通常与环境温度不同，因为温度传感器内置于芯片，从某种程度来说，温度传感器测量的是芯片内的温度。
|
||||
|
||||
2. 安装温度传感器失败时，如果驱动程序打印的错误信息为 ``the boundary you gave cannot meet the range of internal temperature sensor``，说明内置温度传感器温度测量范围的限制影响了安装过程，该错误通常由以下几种不正确的 :cpp:type:`temperature_sensor_config_t` 配置造成：
|
||||
|
||||
(1) 超出温度测量范围，如 200 °C ~ 300 °C。
|
||||
(2) 超过了预定义测量范围的界限，如 40 °C ~ 110 °C。
|
||||
|
||||
应用示例
|
||||
-------------------
|
||||
|
||||
.. list::
|
||||
|
||||
* 读取温度传感器测量值：:example:`peripherals/temperature_sensor/temp_sensor`。
|
||||
:SOC_TEMPERATURE_SENSOR_INTR_SUPPORT: * 监测温度传感器测量值：:example:`peripherals/temperature_sensor/temp_sensor_monitor`。
|
||||
|
||||
API 参考
|
||||
----------------------------------
|
||||
|
||||
.. include-build-file:: inc/temperature_sensor.inc
|
||||
|
||||
Loading…
Reference in New Issue
Block a user