Merge branch 'refact/cleanup_tempreture_sensor_driver' into 'master'

temp_sensor: Add check to the temp_sensor api

Closes IDF-2532 and IDF-2780

See merge request espressif/esp-idf!13456

components/driver/esp32c3/include/driver/temp_sensor.h

@@ -54,7 +54,7 @@ esp_err_t temp_sensor_get_config(temp_sensor_config_t *tsens);
  * @brief Start temperature sensor measure.
  * @return
  *     - ESP_OK Success
- *     - ESP_ERR_INVALID_ARG
+ *     - ESP_ERR_INVALID_STATE if temperature sensor is started already.
  */
 esp_err_t temp_sensor_start(void);
 
@@ -62,6 +62,7 @@ esp_err_t temp_sensor_start(void);
  * @brief Stop temperature sensor measure.
  * @return
  *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_STATE if temperature sensor is stopped already.
  */
 esp_err_t temp_sensor_stop(void);
 

components/driver/esp32c3/rtc_tempsensor.c

@@ -47,10 +47,22 @@ static const tsens_dac_offset_t dac_offset[TSENS_DAC_MAX] = {
     {TSENS_DAC_L4,    2,    10,   -40,   20,   3},
 };
 
+typedef enum {
+    TSENS_HW_STATE_UNCONFIGURED,
+    TSENS_HW_STATE_CONFIGURED,
+    TSENS_HW_STATE_STARTED,
+} tsens_hw_state_t;
+
+static tsens_hw_state_t tsens_hw_state = TSENS_HW_STATE_UNCONFIGURED;
+
 static float s_deltaT = NAN; // unused number
 
 esp_err_t temp_sensor_set_config(temp_sensor_config_t tsens)
 {
+    if (tsens_hw_state == TSENS_HW_STATE_STARTED) {
+        ESP_LOGE(TAG, "Do not configure the temp sensor when it's running!");
+        return ESP_ERR_INVALID_STATE;
+    }
     REG_SET_BIT(SYSTEM_PERIP_CLK_EN1_REG, SYSTEM_TSENS_CLK_EN);
     CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, ANA_I2C_SAR_FORCE_PD);
     SET_PERI_REG_MASK(ANA_CONFIG2_REG, ANA_I2C_SAR_FORCE_PU);
@@ -62,6 +74,7 @@ esp_err_t temp_sensor_set_config(temp_sensor_config_t tsens)
              dac_offset[tsens.dac_offset].range_min,
              dac_offset[tsens.dac_offset].range_max,
              dac_offset[tsens.dac_offset].error_max);
+    tsens_hw_state = TSENS_HW_STATE_CONFIGURED;
     return ESP_OK;
 }
 
@@ -83,9 +96,14 @@ esp_err_t temp_sensor_get_config(temp_sensor_config_t *tsens)
 
 esp_err_t temp_sensor_start(void)
 {
+    if (tsens_hw_state != TSENS_HW_STATE_CONFIGURED) {
+        ESP_LOGE(TAG, "Temperature sensor is already running or not be configured");
+        return ESP_ERR_INVALID_STATE;
+    }
     REG_SET_BIT(SYSTEM_PERIP_CLK_EN1_REG, SYSTEM_TSENS_CLK_EN);
     APB_SARADC.apb_tsens_ctrl2.tsens_clk_sel = 1;
     APB_SARADC.apb_tsens_ctrl.tsens_pu = 1;
+    tsens_hw_state = TSENS_HW_STATE_STARTED;
     return ESP_OK;
 }
 

components/driver/esp32h2/rtc_tempsensor.c

@@ -47,10 +47,22 @@ static const tsens_dac_offset_t dac_offset[TSENS_DAC_MAX] = {
     {TSENS_DAC_L4,    2,    10,   -40,   20,   3},
 };
 
+typedef enum {
+    TSENS_HW_STATE_UNCONFIGURED,
+    TSENS_HW_STATE_CONFIGURED,
+    TSENS_HW_STATE_STARTED,
+} tsens_hw_state_t;
+
+static tsens_hw_state_t tsens_hw_state = TSENS_HW_STATE_UNCONFIGURED;
+
 static float s_deltaT = NAN; // unused number
 
 esp_err_t temp_sensor_set_config(temp_sensor_config_t tsens)
 {
+    if (tsens_hw_state == TSENS_HW_STATE_STARTED) {
+        ESP_LOGE(TAG, "Do not configure the temp sensor when it's running!");
+        return ESP_ERR_INVALID_STATE;
+    }
     REG_SET_BIT(SYSTEM_PERIP_CLK_EN1_REG, SYSTEM_TSENS_CLK_EN);
     CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, ANA_I2C_SAR_FORCE_PD);
     SET_PERI_REG_MASK(ANA_CONFIG2_REG, ANA_I2C_SAR_FORCE_PU);
@@ -62,6 +74,7 @@ esp_err_t temp_sensor_set_config(temp_sensor_config_t tsens)
              dac_offset[tsens.dac_offset].range_min,
              dac_offset[tsens.dac_offset].range_max,
              dac_offset[tsens.dac_offset].error_max);
+    tsens_hw_state = TSENS_HW_STATE_CONFIGURED;
     return ESP_OK;
 }
 
@@ -83,9 +96,14 @@ esp_err_t temp_sensor_get_config(temp_sensor_config_t *tsens)
 
 esp_err_t temp_sensor_start(void)
 {
+    if (tsens_hw_state != TSENS_HW_STATE_CONFIGURED) {
+        ESP_LOGE(TAG, "Temperature sensor is already running or not be configured");
+        return ESP_ERR_INVALID_STATE;
+    }
     REG_SET_BIT(SYSTEM_PERIP_CLK_EN1_REG, SYSTEM_TSENS_CLK_EN);
     APB_SARADC.apb_tsens_ctrl2.tsens_clk_sel = 1;
     APB_SARADC.apb_tsens_ctrl.tsens_pu = 1;
+    tsens_hw_state = TSENS_HW_STATE_STARTED;
     return ESP_OK;
 }
 

components/driver/esp32s2/rtc_tempsensor.c

@@ -47,12 +47,25 @@ static const tsens_dac_offset_t dac_offset[TSENS_DAC_MAX] = {
     {TSENS_DAC_L4,    2,    10,   -40,   20,   3},
 };
 
+typedef enum {
+    TSENS_HW_STATE_UNCONFIGURED,
+    TSENS_HW_STATE_CONFIGURED,
+    TSENS_HW_STATE_STARTED,
+} tsens_hw_state_t;
+
+static tsens_hw_state_t tsens_hw_state = TSENS_HW_STATE_UNCONFIGURED;
+
 static SemaphoreHandle_t rtc_tsens_mux = NULL;
 
 static float s_deltaT = NAN; // Unused number
 
 esp_err_t temp_sensor_set_config(temp_sensor_config_t tsens)
 {
+    esp_err_t err = ESP_OK;
+    if (tsens_hw_state == TSENS_HW_STATE_STARTED) {
+        ESP_LOGE(TAG, "Do not configure the temp sensor when it's running!");
+        err = ESP_ERR_INVALID_STATE;
+    }
     CLEAR_PERI_REG_MASK(RTC_CNTL_ANA_CONF_REG, RTC_CNTL_SAR_I2C_FORCE_PD_M);
     SET_PERI_REG_MASK(RTC_CNTL_ANA_CONF_REG, RTC_CNTL_SAR_I2C_FORCE_PU_M);
     CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, I2C_SAR_M);
@@ -68,7 +81,8 @@ esp_err_t temp_sensor_set_config(temp_sensor_config_t tsens)
              dac_offset[tsens.dac_offset].range_min,
              dac_offset[tsens.dac_offset].range_max,
              dac_offset[tsens.dac_offset].error_max);
-    return ESP_OK;
+    tsens_hw_state = TSENS_HW_STATE_CONFIGURED;
+    return err;
 }
 
 esp_err_t temp_sensor_get_config(temp_sensor_config_t *tsens)
@@ -91,6 +105,11 @@ esp_err_t temp_sensor_get_config(temp_sensor_config_t *tsens)
 
 esp_err_t temp_sensor_start(void)
 {
+    esp_err_t err = ESP_OK;
+    if (tsens_hw_state != TSENS_HW_STATE_CONFIGURED) {
+        ESP_LOGE(TAG, "Temperature sensor is already running or not be configured");
+        err = ESP_ERR_INVALID_STATE;
+    }
     if (rtc_tsens_mux == NULL) {
         rtc_tsens_mux = xSemaphoreCreateMutex();
     }
@@ -98,7 +117,8 @@ esp_err_t temp_sensor_start(void)
     SENS.sar_tctrl.tsens_dump_out = 0;
     SENS.sar_tctrl2.tsens_clkgate_en = 1;
     SENS.sar_tctrl.tsens_power_up = 1;
-    return ESP_OK;
+    tsens_hw_state = TSENS_HW_STATE_STARTED;
+    return err;
 }
 
 esp_err_t temp_sensor_stop(void)

components/soc/esp32c3/include/soc/soc_caps.h

@@ -13,6 +13,7 @@
 #define SOC_HMAC_SUPPORTED              1
 #define SOC_ASYNC_MEMCPY_SUPPORTED      1
 #define SOC_USB_SERIAL_JTAG_SUPPORTED   1
+#define SOC_TEMP_SENSOR_SUPPORTED       1
 #define SOC_FLASH_ENCRYPTION_XTS_AES      1
 
 /*-------------------------- COMMON CAPS ---------------------------------------*/

components/soc/esp32h2/include/soc/soc_caps.h

@@ -17,6 +17,7 @@
 /*-------------------------- COMMON CAPS ---------------------------------------*/
 #define SOC_SUPPORTS_SECURE_DL_MODE         1
 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS   3
+#define SOC_TEMP_SENSOR_SUPPORTED           1
 
 
 /*-------------------------- AES CAPS -----------------------------------------*/

components/soc/esp32s2/include/soc/soc_caps.h

@@ -54,6 +54,7 @@
 #define SOC_ASYNC_MEMCPY_SUPPORTED      1
 #define SOC_EFUSE_SECURE_BOOT_KEY_DIGESTS 3
 #define SOC_EFUSE_REVOKE_BOOT_KEY_DIGESTS 1
+#define SOC_TEMP_SENSOR_SUPPORTED       1
 #define SOC_CACHE_SUPPORT_WRAP          1
 #define SOC_FLASH_ENCRYPTION_XTS_AES      1
 #define SOC_FLASH_ENCRYPTION_XTS_AES_256 1

docs/conf_common.py

@@ -152,6 +152,8 @@ PCNT_DOCS = ['api-reference/peripherals/pcnt.rst']
 
 DAC_DOCS = ['api-reference/peripherals/dac.rst']
 
+TEMP_SENSOR_DOCS = ['api-reference/peripherals/temp_sensor.rst']
+
 TOUCH_SENSOR_DOCS = ['api-reference/peripherals/touch_pad.rst']
 
 SPIRAM_DOCS = ['api-guides/external-ram.rst']
@@ -197,8 +199,7 @@ ESP32S2_DOCS = ['hw-reference/esp32s2/**',
                 'api-reference/peripherals/spi_slave_hd.rst',
                 'api-reference/peripherals/temp_sensor.rst',
                 'api-reference/system/async_memcpy.rst',
-                'api-reference/peripherals/touch_element.rst',
-                'api-reference/peripherals/dac.rst'] + FTDI_JTAG_DOCS
+                'api-reference/peripherals/touch_element.rst'] + FTDI_JTAG_DOCS
 
 ESP32S3_DOCS = ['hw-reference/esp32s3/**',
                 'api-reference/system/ipc.rst']
@@ -225,6 +226,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
                             'SOC_ASYNC_MEMCPY_SUPPORTED':['api-reference/system/async_memcpy.rst'],
                             'CONFIG_IDF_TARGET_ARCH_XTENSA':XTENSA_DOCS,
                             'CONFIG_IDF_TARGET_ARCH_RISCV':RISCV_DOCS,
+                            'SOC_TEMP_SENSOR_SUPPORTED':TEMP_SENSOR_DOCS,
                             'esp32':ESP32_DOCS,
                             'esp32s2':ESP32S2_DOCS,
                             'esp32s3':ESP32S3_DOCS,

docs/en/api-reference/peripherals/index.rst

@@ -28,7 +28,7 @@ Peripherals API
     SPI Slave <spi_slave>
     :esp32: Secure Element <secure_element>
     :esp32s2: SPI Slave Half Duplex <spi_slave_hd>
-    :esp32s2: Temp sensor <temp_sensor>
+    :SOC_TEMP_SENSOR_SUPPORTED: Temp sensor <temp_sensor>
     :SOC_TOUCH_SENSOR_NUM: Touch Sensor <touch_pad>
     :esp32s2: Touch Element <touch_element>
     TWAI <twai>

docs/en/api-reference/peripherals/temp_sensor.rst

@@ -1,10 +1,10 @@
-ESP32-S2 Temperature Sensor
-===========================
+Temperature Sensor
+==================
 
 Overview
 --------
 
-The ESP32-S2 has a built-in temperature sensor. The temperature sensor module contains an 8-bit Sigma-Delta ADC and a temperature offset DAC.
+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.
 
@@ -22,6 +22,34 @@ The conversion relationship is the first columns of the table below. Among them,
 |    2   |       -40 ~ 20         |           < 3          |
 +--------+------------------------+------------------------+
 
+Driver Usage
+------------
+
+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.
+
+.. code-block:: c
+
+    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'.
+
+.. 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).
+
 Application Example
 -------------------
 

docs/zh_CN/api-reference/peripherals/index.rst

@@ -28,7 +28,7 @@
     SPI Slave <spi_slave>
     :esp32: Secure Element <secure_element>
     :esp32s2: SPI Slave Half Duplex <spi_slave_hd>
-    :esp32s2: Temp sensor <temp_sensor>
+    :SOC_TEMP_SENSOR_SUPPORTED: Temp sensor <temp_sensor>
     :SOC_TOUCH_SENSOR_NUM: 触摸传感器 <touch_pad>
     :esp32s2: Touch Element <touch_element>
     TWAI <twai>