esphome 2025.6.2__py3-none-any.whl → 2025.7.0b1__py3-none-any.whl

esphome/components/esp32_touch/esp32_touch_common.cpp

@@ -0,0 +1,162 @@
+#ifdef USE_ESP32
+
+#include "esp32_touch.h"
+#include "esphome/core/log.h"
+#include <cinttypes>
+
+#include "soc/rtc.h"
+
+namespace esphome {
+namespace esp32_touch {
+
+static const char *const TAG = "esp32_touch";
+
+void ESP32TouchComponent::dump_config_base_() {
+  const char *lv_s = get_low_voltage_reference_str(this->low_voltage_reference_);
+  const char *hv_s = get_high_voltage_reference_str(this->high_voltage_reference_);
+  const char *atten_s = get_voltage_attenuation_str(this->voltage_attenuation_);
+
+  ESP_LOGCONFIG(TAG,
+                "Config for ESP32 Touch Hub:\n"
+                "  Meas cycle: %.2fms\n"
+                "  Sleep cycle: %.2fms\n"
+                "  Low Voltage Reference: %s\n"
+                "  High Voltage Reference: %s\n"
+                "  Voltage Attenuation: %s\n"
+                "  Release Timeout: %" PRIu32 "ms\n",
+                this->meas_cycle_ / (8000000.0f / 1000.0f), this->sleep_cycle_ / (150000.0f / 1000.0f), lv_s, hv_s,
+                atten_s, this->release_timeout_ms_);
+}
+
+void ESP32TouchComponent::dump_config_sensors_() {
+  for (auto *child : this->children_) {
+    LOG_BINARY_SENSOR("  ", "Touch Pad", child);
+    ESP_LOGCONFIG(TAG,
+                  "    Pad: T%u\n"
+                  "    Threshold: %" PRIu32 "\n"
+                  "    Benchmark: %" PRIu32,
+                  (unsigned) child->touch_pad_, child->threshold_, child->benchmark_);
+  }
+}
+
+bool ESP32TouchComponent::create_touch_queue_() {
+  // Queue size calculation: children * 4 allows for burst scenarios where ISR
+  // fires multiple times before main loop processes.
+  size_t queue_size = this->children_.size() * 4;
+  if (queue_size < 8)
+    queue_size = 8;
+
+#ifdef USE_ESP32_VARIANT_ESP32
+  this->touch_queue_ = xQueueCreate(queue_size, sizeof(TouchPadEventV1));
+#else
+  this->touch_queue_ = xQueueCreate(queue_size, sizeof(TouchPadEventV2));
+#endif
+
+  if (this->touch_queue_ == nullptr) {
+    ESP_LOGE(TAG, "Failed to create touch event queue of size %" PRIu32, (uint32_t) queue_size);
+    this->mark_failed();
+    return false;
+  }
+  return true;
+}
+
+void ESP32TouchComponent::cleanup_touch_queue_() {
+  if (this->touch_queue_) {
+    vQueueDelete(this->touch_queue_);
+    this->touch_queue_ = nullptr;
+  }
+}
+
+void ESP32TouchComponent::configure_wakeup_pads_() {
+  bool is_wakeup_source = false;
+
+  // Check if any pad is configured for wakeup
+  for (auto *child : this->children_) {
+    if (child->get_wakeup_threshold() != 0) {
+      is_wakeup_source = true;
+
+#ifdef USE_ESP32_VARIANT_ESP32
+      // ESP32 v1: No filter available when using as wake-up source.
+      touch_pad_config(child->get_touch_pad(), child->get_wakeup_threshold());
+#else
+      // ESP32-S2/S3 v2: Set threshold for wakeup
+      touch_pad_set_thresh(child->get_touch_pad(), child->get_wakeup_threshold());
+#endif
+    }
+  }
+
+  if (!is_wakeup_source) {
+    // If no pad is configured for wakeup, deinitialize touch pad
+    touch_pad_deinit();
+  }
+}
+
+void ESP32TouchComponent::process_setup_mode_logging_(uint32_t now) {
+  if (this->setup_mode_ && now - this->setup_mode_last_log_print_ > SETUP_MODE_LOG_INTERVAL_MS) {
+    for (auto *child : this->children_) {
+#ifdef USE_ESP32_VARIANT_ESP32
+      ESP_LOGD(TAG, "Touch Pad '%s' (T%" PRIu32 "): %" PRIu32, child->get_name().c_str(),
+               (uint32_t) child->get_touch_pad(), child->value_);
+#else
+      // Read the value being used for touch detection
+      uint32_t value = this->read_touch_value(child->get_touch_pad());
+      ESP_LOGD(TAG, "Touch Pad '%s' (T%d): %d", child->get_name().c_str(), child->get_touch_pad(), value);
+#endif
+    }
+    this->setup_mode_last_log_print_ = now;
+  }
+}
+
+bool ESP32TouchComponent::should_check_for_releases_(uint32_t now) {
+  if (now - this->last_release_check_ < this->release_check_interval_ms_) {
+    return false;
+  }
+  this->last_release_check_ = now;
+  return true;
+}
+
+void ESP32TouchComponent::publish_initial_state_if_needed_(ESP32TouchBinarySensor *child, uint32_t now) {
+  if (!child->initial_state_published_) {
+    // Check if enough time has passed since startup
+    if (now > this->release_timeout_ms_) {
+      child->publish_initial_state(false);
+      child->initial_state_published_ = true;
+      ESP_LOGV(TAG, "Touch Pad '%s' state: OFF (initial)", child->get_name().c_str());
+    }
+  }
+}
+
+void ESP32TouchComponent::check_and_disable_loop_if_all_released_(size_t pads_off) {
+  // Disable the loop to save CPU cycles when all pads are off and not in setup mode.
+  if (pads_off == this->children_.size() && !this->setup_mode_) {
+    this->disable_loop();
+  }
+}
+
+void ESP32TouchComponent::calculate_release_timeout_() {
+  // Calculate release timeout based on sleep cycle
+  // Design note: Hardware limitation - interrupts only fire reliably on touch (not release)
+  // We must use timeout-based detection for release events
+  // Formula: 3 sleep cycles converted to ms, with MINIMUM_RELEASE_TIME_MS minimum
+  // Per ESP-IDF docs: t_sleep = sleep_cycle / SOC_CLK_RC_SLOW_FREQ_APPROX
+
+  uint32_t rtc_freq = rtc_clk_slow_freq_get_hz();
+
+  // Calculate timeout as 3 sleep cycles
+  this->release_timeout_ms_ = (this->sleep_cycle_ * 1000 * 3) / rtc_freq;
+
+  if (this->release_timeout_ms_ < MINIMUM_RELEASE_TIME_MS) {
+    this->release_timeout_ms_ = MINIMUM_RELEASE_TIME_MS;
+  }
+
+  // Check for releases at 1/4 the timeout interval
+  // Since hardware doesn't generate reliable release interrupts, we must poll
+  // for releases in the main loop. Checking at 1/4 the timeout interval provides
+  // a good balance between responsiveness and efficiency.
+  this->release_check_interval_ms_ = this->release_timeout_ms_ / 4;
+}
+
+}  // namespace esp32_touch
+}  // namespace esphome
+
+#endif  // USE_ESP32

esphome/components/esp32_touch/esp32_touch_v1.cpp

@@ -0,0 +1,238 @@
+#ifdef USE_ESP32_VARIANT_ESP32
+
+#include "esp32_touch.h"
+#include "esphome/core/application.h"
+#include "esphome/core/log.h"
+#include "esphome/core/hal.h"
+
+#include <algorithm>
+#include <cinttypes>
+
+// Include HAL for ISR-safe touch reading
+#include "hal/touch_sensor_ll.h"
+
+namespace esphome {
+namespace esp32_touch {
+
+static const char *const TAG = "esp32_touch";
+
+void ESP32TouchComponent::setup() {
+  // Create queue for touch events
+  // Queue size calculation: children * 4 allows for burst scenarios where ISR
+  // fires multiple times before main loop processes. This is important because
+  // ESP32 v1 scans all pads on each interrupt, potentially sending multiple events.
+  if (!this->create_touch_queue_()) {
+    return;
+  }
+
+  touch_pad_init();
+  touch_pad_set_fsm_mode(TOUCH_FSM_MODE_TIMER);
+
+  // Set up IIR filter if enabled
+  if (this->iir_filter_enabled_()) {
+    touch_pad_filter_start(this->iir_filter_);
+  }
+
+  // Configure measurement parameters
+#if ESP_IDF_VERSION_MAJOR >= 5
+  touch_pad_set_measurement_clock_cycles(this->meas_cycle_);
+  touch_pad_set_measurement_interval(this->sleep_cycle_);
+#else
+  touch_pad_set_meas_time(this->sleep_cycle_, this->meas_cycle_);
+#endif
+  touch_pad_set_voltage(this->high_voltage_reference_, this->low_voltage_reference_, this->voltage_attenuation_);
+
+  // Configure each touch pad
+  for (auto *child : this->children_) {
+    touch_pad_config(child->get_touch_pad(), child->get_threshold());
+  }
+
+  // Register ISR handler
+  esp_err_t err = touch_pad_isr_register(touch_isr_handler, this);
+  if (err != ESP_OK) {
+    ESP_LOGE(TAG, "Failed to register touch ISR: %s", esp_err_to_name(err));
+    this->cleanup_touch_queue_();
+    this->mark_failed();
+    return;
+  }
+
+  // Calculate release timeout based on sleep cycle
+  this->calculate_release_timeout_();
+
+  // Enable touch pad interrupt
+  touch_pad_intr_enable();
+}
+
+void ESP32TouchComponent::dump_config() {
+  this->dump_config_base_();
+
+  if (this->iir_filter_enabled_()) {
+    ESP_LOGCONFIG(TAG, "    IIR Filter: %" PRIu32 "ms", this->iir_filter_);
+  } else {
+    ESP_LOGCONFIG(TAG, "  IIR Filter DISABLED");
+  }
+
+  if (this->setup_mode_) {
+    ESP_LOGCONFIG(TAG, "  Setup Mode ENABLED");
+  }
+
+  this->dump_config_sensors_();
+}
+
+void ESP32TouchComponent::loop() {
+  const uint32_t now = App.get_loop_component_start_time();
+
+  // Print debug info for all pads in setup mode
+  this->process_setup_mode_logging_(now);
+
+  // Process any queued touch events from interrupts
+  // Note: Events are only sent by ISR for pads that were measured in that cycle (value != 0)
+  // This is more efficient than sending all pad states every interrupt
+  TouchPadEventV1 event;
+  while (xQueueReceive(this->touch_queue_, &event, 0) == pdTRUE) {
+    // Find the corresponding sensor - O(n) search is acceptable since events are infrequent
+    for (auto *child : this->children_) {
+      if (child->get_touch_pad() != event.pad) {
+        continue;
+      }
+
+      // Found matching pad - process it
+      child->value_ = event.value;
+
+      // The interrupt gives us the touch state directly
+      bool new_state = event.is_touched;
+
+      // Track when we last saw this pad as touched
+      if (new_state) {
+        child->last_touch_time_ = now;
+      }
+
+      // Only publish if state changed - this filters out repeated events
+      if (new_state != child->last_state_) {
+        child->last_state_ = new_state;
+        child->publish_state(new_state);
+        // Original ESP32: ISR only fires when touched, release is detected by timeout
+        // Note: ESP32 v1 uses inverted logic - touched when value < threshold
+        ESP_LOGV(TAG, "Touch Pad '%s' state: ON (value: %" PRIu32 " < threshold: %" PRIu32 ")",
+                 child->get_name().c_str(), event.value, child->get_threshold());
+      }
+      break;  // Exit inner loop after processing matching pad
+    }
+  }
+
+  // Check for released pads periodically
+  if (!this->should_check_for_releases_(now)) {
+    return;
+  }
+
+  size_t pads_off = 0;
+  for (auto *child : this->children_) {
+    // Handle initial state publication after startup
+    this->publish_initial_state_if_needed_(child, now);
+
+    if (child->last_state_) {
+      // Pad is currently in touched state - check for release timeout
+      // Using subtraction handles 32-bit rollover correctly
+      uint32_t time_diff = now - child->last_touch_time_;
+
+      // Check if we haven't seen this pad recently
+      if (time_diff > this->release_timeout_ms_) {
+        // Haven't seen this pad recently, assume it's released
+        child->last_state_ = false;
+        child->publish_state(false);
+        ESP_LOGV(TAG, "Touch Pad '%s' state: OFF (timeout)", child->get_name().c_str());
+        pads_off++;
+      }
+    } else {
+      // Pad is already off
+      pads_off++;
+    }
+  }
+
+  // Disable the loop to save CPU cycles when all pads are off and not in setup mode.
+  // The loop will be re-enabled by the ISR when any touch pad is touched.
+  // v1 hardware limitations require us to check all pads are off because:
+  // - v1 only generates interrupts on touch events (not releases)
+  // - We must poll for release timeouts in the main loop
+  // - We can only safely disable when no pads need timeout monitoring
+  this->check_and_disable_loop_if_all_released_(pads_off);
+}
+
+void ESP32TouchComponent::on_shutdown() {
+  touch_pad_intr_disable();
+  touch_pad_isr_deregister(touch_isr_handler, this);
+  this->cleanup_touch_queue_();
+
+  if (this->iir_filter_enabled_()) {
+    touch_pad_filter_stop();
+    touch_pad_filter_delete();
+  }
+
+  // Configure wakeup pads if any are set
+  this->configure_wakeup_pads_();
+}
+
+void IRAM_ATTR ESP32TouchComponent::touch_isr_handler(void *arg) {
+  ESP32TouchComponent *component = static_cast<ESP32TouchComponent *>(arg);
+
+  touch_pad_clear_status();
+
+  // INTERRUPT BEHAVIOR: On ESP32 v1 hardware, the interrupt fires when ANY configured
+  // touch pad detects a touch (value goes below threshold). The hardware does NOT
+  // generate interrupts on release - only on touch events.
+  // The interrupt will continue to fire periodically (based on sleep_cycle) as long
+  // as any pad remains touched. This allows us to detect both new touches and
+  // continued touches, but releases must be detected by timeout in the main loop.
+
+  // Process all configured pads to check their current state
+  // Note: ESP32 v1 doesn't tell us which specific pad triggered the interrupt,
+  // so we must scan all configured pads to find which ones were touched
+  for (auto *child : component->children_) {
+    touch_pad_t pad = child->get_touch_pad();
+
+    // Read current value using ISR-safe API
+    uint32_t value;
+    if (component->iir_filter_enabled_()) {
+      uint16_t temp_value = 0;
+      touch_pad_read_filtered(pad, &temp_value);
+      value = temp_value;
+    } else {
+      // Use low-level HAL function when filter is not enabled
+      value = touch_ll_read_raw_data(pad);
+    }
+
+    // Skip pads with 0 value - they haven't been measured in this cycle
+    // This is important: not all pads are measured every interrupt cycle,
+    // only those that the hardware has updated
+    if (value == 0) {
+      continue;
+    }
+
+    // IMPORTANT: ESP32 v1 touch detection logic - INVERTED compared to v2!
+    // ESP32 v1: Touch is detected when capacitance INCREASES, causing the measured value to DECREASE
+    // Therefore: touched = (value < threshold)
+    // This is opposite to ESP32-S2/S3 v2 where touched = (value > threshold)
+    bool is_touched = value < child->get_threshold();
+
+    // Always send the current state - the main loop will filter for changes
+    // We send both touched and untouched states because the ISR doesn't
+    // track previous state (to keep ISR fast and simple)
+    TouchPadEventV1 event;
+    event.pad = pad;
+    event.value = value;
+    event.is_touched = is_touched;
+
+    // Send to queue from ISR - non-blocking, drops if queue full
+    BaseType_t x_higher_priority_task_woken = pdFALSE;
+    xQueueSendFromISR(component->touch_queue_, &event, &x_higher_priority_task_woken);
+    component->enable_loop_soon_any_context();
+    if (x_higher_priority_task_woken) {
+      portYIELD_FROM_ISR();
+    }
+  }
+}
+
+}  // namespace esp32_touch
+}  // namespace esphome
+
+#endif  // USE_ESP32_VARIANT_ESP32