From ca0523b86ca11cf7eac5bb86c1ff762279371aff Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Sun, 22 Mar 2026 10:16:46 -1000
Subject: [PATCH] [sht4x] Fix heater causing measurement jitter (#15030)

---
 esphome/components/sht4x/sht4x.cpp | 40 ++++++++++++++++--------------
 esphome/components/sht4x/sht4x.h   |  3 ++-
 tests/components/sht4x/common.yaml |  4 +++
 3 files changed, 28 insertions(+), 19 deletions(-)

diff --git a/esphome/components/sht4x/sht4x.cpp b/esphome/components/sht4x/sht4x.cpp
index bf23e42e66..43c2436a56 100644
--- a/esphome/components/sht4x/sht4x.cpp
+++ b/esphome/components/sht4x/sht4x.cpp
@@ -9,14 +9,12 @@ static const char *const TAG = "sht4x";
 static const uint8_t MEASURECOMMANDS[] = {0xFD, 0xF6, 0xE0};
 static const uint8_t SERIAL_NUMBER_COMMAND = 0x89;
 
-void SHT4XComponent::start_heater_() {
-  uint8_t cmd[] = {this->heater_command_};
-
-  ESP_LOGD(TAG, "Heater turning on");
-  if (this->write(cmd, 1) != i2c::ERROR_OK) {
-    this->status_set_error(LOG_STR("Failed to turn on heater"));
-  }
-}
+// Conversion constants from SHT4x datasheet
+static constexpr float TEMPERATURE_OFFSET = -45.0f;
+static constexpr float TEMPERATURE_SPAN = 175.0f;
+static constexpr float HUMIDITY_OFFSET = -6.0f;
+static constexpr float HUMIDITY_SPAN = 125.0f;
+static constexpr float RAW_MAX = 65535.0f;
 
 void SHT4XComponent::read_serial_number_() {
   uint16_t buffer[2];
@@ -39,8 +37,8 @@ void SHT4XComponent::setup() {
   this->read_serial_number_();
 
   if (std::isfinite(this->duty_cycle_) && this->duty_cycle_ > 0.0f) {
-    uint32_t heater_interval = static_cast<uint32_t>(static_cast<uint16_t>(this->heater_time_) / this->duty_cycle_);
-    ESP_LOGD(TAG, "Heater interval: %" PRIu32, heater_interval);
+    this->heater_interval_ = static_cast<uint32_t>(static_cast<uint16_t>(this->heater_time_) / this->duty_cycle_);
+    ESP_LOGD(TAG, "Heater interval: %" PRIu32, this->heater_interval_);
 
     if (this->heater_power_ == SHT4X_HEATERPOWER_HIGH) {
       if (this->heater_time_ == SHT4X_HEATERTIME_LONG) {
@@ -62,8 +60,6 @@ void SHT4XComponent::setup() {
       }
     }
     ESP_LOGD(TAG, "Heater command: %x", this->heater_command_);
-
-    this->set_interval(heater_interval, [this]() { this->start_heater_(); });
   }
 }
 
@@ -106,19 +102,27 @@ void SHT4XComponent::update() {
     // Evaluate and publish measurements
     if (this->temp_sensor_ != nullptr) {
       // Temp is contained in the first result word
-      float sensor_value_temp = buffer[0];
-      float temp = -45 + 175 * sensor_value_temp / 65535;
-
+      float temp = TEMPERATURE_OFFSET + TEMPERATURE_SPAN * static_cast<float>(buffer[0]) / RAW_MAX;
       this->temp_sensor_->publish_state(temp);
     }
 
     if (this->humidity_sensor_ != nullptr) {
       // Relative humidity is in the second result word
-      float sensor_value_rh = buffer[1];
-      float rh = -6 + 125 * sensor_value_rh / 65535;
-
+      float rh = HUMIDITY_OFFSET + HUMIDITY_SPAN * static_cast<float>(buffer[1]) / RAW_MAX;
       this->humidity_sensor_->publish_state(rh);
     }
+
+    // Fire heater after measurement to maximize cooldown time before the next reading.
+    // The heater command produces a measurement that we don't need (datasheet 4.9).
+    if (this->heater_interval_ > 0) {
+      uint32_t now = millis();
+      if (now - this->last_heater_millis_ >= this->heater_interval_) {
+        ESP_LOGD(TAG, "Heater turning on");
+        if (this->write_command(this->heater_command_)) {
+          this->last_heater_millis_ = now;
+        }
+      }
+    }
   });
 }
 
diff --git a/esphome/components/sht4x/sht4x.h b/esphome/components/sht4x/sht4x.h
index aec0f3d7f8..51f473fe3f 100644
--- a/esphome/components/sht4x/sht4x.h
+++ b/esphome/components/sht4x/sht4x.h
@@ -35,9 +35,10 @@ class SHT4XComponent : public PollingComponent, public sensirion_common::Sensiri
   SHT4XHEATERTIME heater_time_;
   float duty_cycle_;
 
-  void start_heater_();
   void read_serial_number_();
   uint8_t heater_command_;
+  uint32_t heater_interval_{0};
+  uint32_t last_heater_millis_{0};
   uint32_t serial_number_;
 
   sensor::Sensor *temp_sensor_{nullptr};
diff --git a/tests/components/sht4x/common.yaml b/tests/components/sht4x/common.yaml
index 50d5ad8ca4..bec192d6db 100644
--- a/tests/components/sht4x/common.yaml
+++ b/tests/components/sht4x/common.yaml
@@ -6,4 +6,8 @@ sensor:
     humidity:
       name: SHT4X Humidity
     address: 0x44
+    precision: High
+    heater_max_duty: 0.02
+    heater_power: High
+    heater_time: Long
     update_interval: 15s