diff --git a/components/driver/esp32c3/include/driver/temp_sensor.h b/components/driver/esp32c3/include/driver/temp_sensor.h index 9e227c71d6..d5d3ee3dd2 100644 --- a/components/driver/esp32c3/include/driver/temp_sensor.h +++ b/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); diff --git a/components/driver/esp32c3/rtc_tempsensor.c b/components/driver/esp32c3/rtc_tempsensor.c index 09ff0b0050..d77b75e902 100644 --- a/components/driver/esp32c3/rtc_tempsensor.c +++ b/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; } diff --git a/components/driver/esp32h2/rtc_tempsensor.c b/components/driver/esp32h2/rtc_tempsensor.c index 86ea9fe5ff..e447ebaa99 100644 --- a/components/driver/esp32h2/rtc_tempsensor.c +++ b/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; } diff --git a/components/driver/esp32s2/rtc_tempsensor.c b/components/driver/esp32s2/rtc_tempsensor.c index b67c795954..7e74817904 100644 --- a/components/driver/esp32s2/rtc_tempsensor.c +++ b/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) diff --git a/components/soc/esp32c3/include/soc/soc_caps.h b/components/soc/esp32c3/include/soc/soc_caps.h index 5b54f55865..1411fa158d 100644 --- a/components/soc/esp32c3/include/soc/soc_caps.h +++ b/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 ---------------------------------------*/ diff --git a/components/soc/esp32h2/include/soc/soc_caps.h b/components/soc/esp32h2/include/soc/soc_caps.h index cfda89c29f..64fa8dd3b9 100644 --- a/components/soc/esp32h2/include/soc/soc_caps.h +++ b/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 -----------------------------------------*/ diff --git a/components/soc/esp32s2/include/soc/soc_caps.h b/components/soc/esp32s2/include/soc/soc_caps.h index 09ee25646b..63326b098a 100644 --- a/components/soc/esp32s2/include/soc/soc_caps.h +++ b/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 diff --git a/docs/conf_common.py b/docs/conf_common.py index 018ce10484..322b3198f2 100644 --- a/docs/conf_common.py +++ b/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, diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst index 0ae242eb11..889d273945 100644 --- a/docs/en/api-reference/peripherals/index.rst +++ b/docs/en/api-reference/peripherals/index.rst @@ -28,7 +28,7 @@ Peripherals API SPI Slave :esp32: Secure Element :esp32s2: SPI Slave Half Duplex - :esp32s2: Temp sensor + :SOC_TEMP_SENSOR_SUPPORTED: Temp sensor :SOC_TOUCH_SENSOR_NUM: Touch Sensor :esp32s2: Touch Element TWAI diff --git a/docs/en/api-reference/peripherals/temp_sensor.rst b/docs/en/api-reference/peripherals/temp_sensor.rst index 9fa4a977cf..c77de66b57 100644 --- a/docs/en/api-reference/peripherals/temp_sensor.rst +++ b/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 ------------------- diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst index 802d6ebc7c..8aca2ff658 100644 --- a/docs/zh_CN/api-reference/peripherals/index.rst +++ b/docs/zh_CN/api-reference/peripherals/index.rst @@ -28,7 +28,7 @@ SPI Slave :esp32: Secure Element :esp32s2: SPI Slave Half Duplex - :esp32s2: Temp sensor + :SOC_TEMP_SENSOR_SUPPORTED: Temp sensor :SOC_TOUCH_SENSOR_NUM: 触摸传感器 :esp32s2: Touch Element TWAI