[ultrasonic] Fix timeout issues and deprecate timeout option (#12897)

Co-authored-by: Claude <noreply@anthropic.com>

esphome/components/ultrasonic/sensor.py

@@ -1,3 +1,5 @@
+import logging
+
 from esphome import pins
 import esphome.codegen as cg
 from esphome.components import sensor
@@ -11,6 +13,8 @@ from esphome.const import (
     UNIT_METER,
 )
 
+_LOGGER = logging.getLogger(__name__)
+
 CONF_PULSE_TIME = "pulse_time"
 
 ultrasonic_ns = cg.esphome_ns.namespace("ultrasonic")
@@ -30,7 +34,7 @@ CONFIG_SCHEMA = (
         {
             cv.Required(CONF_TRIGGER_PIN): pins.internal_gpio_output_pin_schema,
             cv.Required(CONF_ECHO_PIN): pins.internal_gpio_input_pin_schema,
-            cv.Optional(CONF_TIMEOUT, default="2m"): cv.distance,
+            cv.Optional(CONF_TIMEOUT): cv.distance,
             cv.Optional(
                 CONF_PULSE_TIME, default="10us"
             ): cv.positive_time_period_microseconds,
@@ -49,5 +53,11 @@ async def to_code(config):
     echo = await cg.gpio_pin_expression(config[CONF_ECHO_PIN])
     cg.add(var.set_echo_pin(echo))
 
-    cg.add(var.set_timeout_us(config[CONF_TIMEOUT] / (0.000343 / 2)))
+    # Remove before 2026.8.0
+    if CONF_TIMEOUT in config:
+        _LOGGER.warning(
+            "'timeout' option is deprecated and will be removed in 2026.8.0. "
+            "The option has no effect and can be safely removed."
+        )
+
     cg.add(var.set_pulse_time_us(config[CONF_PULSE_TIME]))

esphome/components/ultrasonic/ultrasonic_sensor.cpp

@@ -6,8 +6,8 @@ namespace esphome::ultrasonic {
 
 static const char *const TAG = "ultrasonic.sensor";
 
-static constexpr uint32_t DEBOUNCE_US = 50;          // Ignore edges within 50us (noise filtering)
+static constexpr uint32_t DEBOUNCE_US = 50;                // Ignore edges within 50us (noise filtering)
-static constexpr uint32_t TIMEOUT_MARGIN_US = 1000;  // Extra margin for sensor processing time
+static constexpr uint32_t MEASUREMENT_TIMEOUT_US = 80000;  // Maximum time to wait for measurement completion
 
 void IRAM_ATTR UltrasonicSensorStore::gpio_intr(UltrasonicSensorStore *arg) {
   uint32_t now = micros();
@@ -64,12 +64,8 @@ void UltrasonicSensorComponent::loop() {
   }
 
   uint32_t elapsed = micros() - this->measurement_start_us_;
-  if (elapsed >= this->timeout_us_ + TIMEOUT_MARGIN_US) {
+  if (elapsed >= MEASUREMENT_TIMEOUT_US) {
-    ESP_LOGD(TAG,
+    ESP_LOGD(TAG, "'%s' - Measurement timed out after %" PRIu32 "us", this->name_.c_str(), elapsed);
-             "'%s' - Timeout after %" PRIu32 "us (measurement_start=%" PRIu32 ", echo_start=%" PRIu32
-             ", echo_end=%" PRIu32 ")",
-             this->name_.c_str(), elapsed, this->measurement_start_us_, this->store_.echo_start_us,
-             this->store_.echo_end_us);
     this->publish_state(NAN);
     this->measurement_pending_ = false;
   }
@@ -79,10 +75,7 @@ void UltrasonicSensorComponent::dump_config() {
   LOG_SENSOR("", "Ultrasonic Sensor", this);
   LOG_PIN("  Echo Pin: ", this->echo_pin_);
   LOG_PIN("  Trigger Pin: ", this->trigger_pin_);
-  ESP_LOGCONFIG(TAG,
+  ESP_LOGCONFIG(TAG, "  Pulse time: %" PRIu32 " us", this->pulse_time_us_);
-                "  Pulse time: %" PRIu32 " us\n"
-                "  Timeout: %" PRIu32 " us",
-                this->pulse_time_us_, this->timeout_us_);
   LOG_UPDATE_INTERVAL(this);
 }
 

esphome/components/ultrasonic/ultrasonic_sensor.h

@@ -22,9 +22,6 @@ class UltrasonicSensorComponent : public sensor::Sensor, public PollingComponent
   void set_trigger_pin(InternalGPIOPin *trigger_pin) { this->trigger_pin_ = trigger_pin; }
   void set_echo_pin(InternalGPIOPin *echo_pin) { this->echo_pin_ = echo_pin; }
 
-  /// Set the timeout for waiting for the echo in µs.
-  void set_timeout_us(uint32_t timeout_us) { this->timeout_us_ = timeout_us; }
-
   void setup() override;
   void loop() override;
   void dump_config() override;
@@ -44,7 +41,6 @@ class UltrasonicSensorComponent : public sensor::Sensor, public PollingComponent
   ISRInternalGPIOPin trigger_pin_isr_;
   InternalGPIOPin *echo_pin_;
   UltrasonicSensorStore store_;
-  uint32_t timeout_us_{};
   uint32_t pulse_time_us_{};
 
   uint32_t measurement_start_us_{0};