mirror of
https://github.com/espressif/esp-idf
synced 2025-03-09 17:19:09 -04:00
Temperature_sensor: update temperature sensor documents
This commit is contained in:
Cao Sen Miao
parent
214e206111
commit
d25feba1bf
@ -1,2 +1,2 @@
|
||||
INPUT += \
|
||||
$(PROJECT_PATH)/components/driver/esp32c3/include/driver/temp_sensor.h
|
||||
$(PROJECT_PATH)/components/driver/include/driver/temperature_sensor.h \
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
INPUT += \
|
||||
$(PROJECT_PATH)/components/driver/esp32c3/include/driver/temp_sensor.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/temperature_sensor.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/soc/esp32c3/esp_ds.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/soc/esp32c3/esp_hmac.h
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
INPUT += \
|
||||
$(PROJECT_PATH)/components/driver/esp32h2/include/driver/temp_sensor.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/temperature_sensor.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/soc/esp32h2/esp_ds.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/soc/esp32h2/esp_hmac.h
|
||||
|
||||
@ -4,7 +4,7 @@ INPUT += \
|
||||
$(PROJECT_PATH)/components/hal/include/hal/pcnt_types.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/pulse_cnt.h \
|
||||
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/rtc_io_channel.h \
|
||||
$(PROJECT_PATH)/components/driver/esp32s2/include/driver/temp_sensor.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/temperature_sensor.h \
|
||||
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
|
||||
$(PROJECT_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/soc/esp32s2/esp_ds.h \
|
||||
|
||||
@ -5,6 +5,7 @@ INPUT += \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/mcpwm.h \
|
||||
$(PROJECT_PATH)/components/hal/include/hal/pcnt_types.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/pulse_cnt.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/temperature_sensor.h \
|
||||
$(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
|
||||
$(PROJECT_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \
|
||||
$(PROJECT_PATH)/components/ulp/ulp_fsm/include/$(IDF_TARGET)/ulp.h \
|
||||
|
||||
@ -1,67 +1,127 @@
|
||||
Temperature Sensor
|
||||
===================
|
||||
==================
|
||||
|
||||
.. only:: esp32s3
|
||||
|
||||
.. warning::
|
||||
|
||||
This feature is not supported in v4.4
|
||||
|
||||
Overview
|
||||
--------
|
||||
|
||||
The {IDF_TARGET_NAME} has a built-in temperature sensor used to measure the chip's internal temperature, and hard to measure the environmental temperature accurately. Being built-in means that the temperature sensor should work on any {IDF_TARGET_NAME} regardless of what board the chip is embedded in. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
|
||||
|
||||
The conversion relationship is the first columns of the table below. Among them, offset = 0 is the main measurement option, and other values are extended measurement options.
|
||||
|
||||
+--------+------------------------+------------------------+
|
||||
| offset | measure range(Celsius) | measure error(Celsius) |
|
||||
+========+========================+========================+
|
||||
| -2 | 50 ~ 125 | < 3 |
|
||||
+--------+------------------------+------------------------+
|
||||
| -1 | 20 ~ 100 | < 2 |
|
||||
+--------+------------------------+------------------------+
|
||||
| 0 | -10 ~ 80 | < 1 |
|
||||
+--------+------------------------+------------------------+
|
||||
| 1 | -30 ~ 50 | < 2 |
|
||||
+--------+------------------------+------------------------+
|
||||
| 2 | -40 ~ 20 | < 3 |
|
||||
+--------+------------------------+------------------------+
|
||||
|
||||
Driver Usage
|
||||
Introduction
|
||||
------------
|
||||
|
||||
1. Initialize the temperature sensor by calling the function :cpp:func:`temp_sensor_set_config` and pass to it a :cpp:type:`temp_sensor_config_t` structure. The :cpp:type:`temp_sensor_config_t` structure should contain all the required parameters. See the example below.
|
||||
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.
|
||||
|
||||
.. code-block:: c
|
||||
Due to restrictions of hardware, the sensor has predefined measurement ranges with specific measurement errors. See the table below for details.
|
||||
|
||||
temp_sensor_config_t temp_sensor = {
|
||||
.dac_offset = TSENS_DAC_L2,
|
||||
.clk_div = 6,
|
||||
};
|
||||
temp_sensor_set_config(temp_sensor);
|
||||
|
||||
2. Start the temp_sensor by calling :cpp:func:'temp_sensor_start'. The temperature sensor will now measure the temperature.
|
||||
|
||||
3. To get the current temperature, take the example below as a reference, the value you get is in Celsius.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
float tsens_out;
|
||||
temp_sensor_read_celsius(&tsens_out);
|
||||
|
||||
4. To stop the temperature sensor, please call :cpp:func:'temp_sensor_stop'.
|
||||
+------------------------+------------------------+
|
||||
| predefined range (°C) | error (°C) |
|
||||
+========================+========================+
|
||||
| 50 ~ 125 | < 3 |
|
||||
+------------------------+------------------------+
|
||||
| 20 ~ 100 | < 2 |
|
||||
+------------------------+------------------------+
|
||||
| -10 ~ 80 | < 1 |
|
||||
+------------------------+------------------------+
|
||||
| -30 ~ 50 | < 2 |
|
||||
+------------------------+------------------------+
|
||||
| -40 ~ 20 | < 3 |
|
||||
+------------------------+------------------------+
|
||||
|
||||
.. note::
|
||||
|
||||
If you want dynamic reconfiguration, you need to stop the sensor first (temp_sensor_stop), set the new configuration (temp_sensor_set_config), then start the sensor again (temp_sensor_start).
|
||||
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.
|
||||
|
||||
Functional Overview
|
||||
-------------------
|
||||
|
||||
- `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.
|
||||
|
||||
- `Start and Stop Temperature <#start-and-stop-temperature>`__ - covers how to start or stop the temperature sensor.
|
||||
|
||||
- `Get Temperature Value <#get-temperature-value>`__ - covers how to get the real-time temperature value.
|
||||
|
||||
- `Power Management <#power-management>`__ - covers how temperature sensor is affected when changing power mode (i.e. light sleep).
|
||||
|
||||
- `Thread Safety <#thread-safety>`__ - covers how to make the driver to be thread safe.
|
||||
|
||||
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.
|
||||
|
||||
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`:
|
||||
|
||||
- :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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
.. 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));
|
||||
|
||||
Start and Stop Temperature
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
1. Start the temperature sensor by calling :cpp:func:`temperature_sensor_start`. The temperature sensor will now measure the temperature.
|
||||
|
||||
2. To stop the temperature sensor, please call :cpp:func:`temperature_sensor_stop`.
|
||||
|
||||
Get Temperature Value
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
After the temperature sensor has been installed, you can get the temperature value by following the steps below.
|
||||
|
||||
1. To get the current temperature, please call :cpp:func:`temperature_sensor_get_celsius`.
|
||||
|
||||
.. code:: c
|
||||
|
||||
ESP_ERROR_CHECK(temperature_sensor_start(temp_handle));
|
||||
printf("Temperature sensor started\n");
|
||||
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_stop(temp_handle));
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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`:
|
||||
|
||||
(1) Totally out of range, like 200 °C ~ 300 °C.
|
||||
(2) Cross the boundary of each predefined measurement. like 40 °C ~ 110 °C.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
Temperature sensor reading example: :example:`peripherals/temp_sensor`.
|
||||
|
||||
API Reference - Normal Temp Sensor
|
||||
API Reference
|
||||
----------------------------------
|
||||
|
||||
.. include-build-file:: inc/temp_sensor.inc
|
||||
.. include-build-file:: inc/temperature_sensor.inc
|
||||
|
||||
@ -104,6 +104,7 @@ The following peripherals work normally even when the APB frequency is changing:
|
||||
- **LEDC**: if REF_TICK is used as a clock source. See :cpp:func:`ledc_timer_config` function.
|
||||
- **RMT**: if REF_TICK or XTAL is used as a clock source. See `flags` member of :cpp:class:`rmt_config_t` and macro `RMT_CHANNEL_FLAGS_AWARE_DFS`.
|
||||
- **GPTimer**: if APB is used as the clock source. See :c:member:`clk_src` member of :c:type:`gptimer_config_t`.
|
||||
- **TSENS**: XTAL or RTC_8M is used as a clock source. So, APB frequency changing will not influence it.
|
||||
|
||||
Currently, the following peripheral drivers are aware of DFS and will use the ``ESP_PM_APB_FREQ_MAX`` lock for the duration of the transaction:
|
||||
|
||||
|
||||
@ -96,3 +96,13 @@ I2C
|
||||
- ``pcnt_filter_enable``, ``pcnt_filter_disable``, and ``pcnt_set_filter_value`` are replaced by :cpp:func:`pcnt_unit_set_glitch_filter`. Meanwhile, ``pcnt_get_filter_value`` has been removed.
|
||||
- ``pcnt_set_mode`` is replaced by :cpp:func:`pcnt_channel_set_edge_action` and :cpp:func:`pcnt_channel_set_level_action`.
|
||||
- ``pcnt_isr_service_install``, ``pcnt_isr_service_uninstall``, ``pcnt_isr_handler_add`` and ``pcnt_isr_handler_remove`` are replaced by :cpp:func:`pcnt_unit_register_event_callbacks`. The default ISR handler is lazy installed in the new driver.
|
||||
|
||||
.. only:: SOC_TEMP_SENSOR_SUPPORTED
|
||||
|
||||
Temperature Sensor Driver
|
||||
-------------------------
|
||||
|
||||
1. Old API header ``temp_sensor.h`` has been redesigned as ``temperature_sensor.h``, it is recommended to use the new driver and the old driver is not allowed to be used at the same time.
|
||||
2. Although it's recommended to use the new driver APIs, the legacy driver is still available in the previous include path ``driver/temp_sensor.h``. However, by default, including ``driver/temp_sensor.h`` will bring a build warning like "legacy temperature sensor driver is deprecated, please migrate to driver/temperature_sensor.h". The warning can be suppressed by enabling the menuconfig option :ref:`CONFIG_TEMP_SENSOR_SUPPRESS_DEPRECATE_WARN`.
|
||||
3. Configuration contents has been changed. In old version, user need to configure the ``clk_div`` and ``dac_offset``. While in new version, user only need to choose ``tsens_range``
|
||||
4. The process of using temperature sensor has been changed. In old version, user can use ``config->start->read_celsius`` to get value. In the new version, user must install the temperature sensor driver firstly, by ``temperature_sensor_install`` and uninstall it when finished. For more information, you can refer to :doc:`Temperature Sensor <../api-reference/peripherals/temp_sensor>` .
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user