[pcf8574][pca9554] Add optional interrupt pin to eliminate polling (#15444)

esphome/components/gpio_expander/cached_gpio.h

@@ -28,7 +28,10 @@ namespace esphome::gpio_expander {
 template<typename T, uint16_t N, typename P = typename std::conditional<(N > 256), uint16_t, uint8_t>::type>
 class CachedGpioExpander {
  public:
-  /// @brief Read the state of the given pin. This will invalidate the cache for the given pin number.
+  /// @brief Read the state of the given pin.
+  /// By default, each read invalidates the pin's cache entry so the next read
+  /// of the same pin triggers a fresh hardware read. When invalidate_on_read
+  /// is disabled, the cache stays valid until explicitly cleared via reset_pin_cache_().
   /// @param pin Pin number to read
   /// @return Pin state
   bool digital_read(P pin) {
@@ -36,14 +39,17 @@ class CachedGpioExpander {
     const T pin_mask = (1 << (pin % BANK_SIZE));
     // Check if specific pin cache is valid
     if (this->read_cache_valid_[bank] & pin_mask) {
-      // Invalidate pin
+      if (this->invalidate_on_read_) {
+        // Invalidate pin so next read triggers hardware read
         this->read_cache_valid_[bank] &= ~pin_mask;
+      }
     } else {
       // Read whole bank from hardware
       if (!this->digital_read_hw(pin))
         return false;
       // Mark bank cache as valid except the pin that is being returned now
-      this->read_cache_valid_[bank] = std::numeric_limits<T>::max() & ~pin_mask;
+      // (when not invalidating on read, mark all pins including this one as valid)
+      this->read_cache_valid_[bank] = std::numeric_limits<T>::max() & ~(this->invalidate_on_read_ ? pin_mask : 0);
     }
     return this->digital_read_cache(pin);
   }
@@ -71,12 +77,18 @@ class CachedGpioExpander {
   /// @brief Invalidate cache. This function should be called in component loop().
   void reset_pin_cache_() { memset(this->read_cache_valid_, 0x00, CACHE_SIZE_BYTES); }
 
+  /// @brief Control whether digital_read() invalidates the pin's cache entry after reading.
+  /// When enabled (default), each read self-invalidates so the next read triggers a hardware read.
+  /// When disabled, cache stays valid until reset_pin_cache_() is explicitly called.
+  void set_invalidate_on_read_(bool invalidate) { this->invalidate_on_read_ = invalidate; }
+
   static constexpr uint16_t BITS_PER_BYTE = 8;
   static constexpr uint16_t BANK_SIZE = sizeof(T) * BITS_PER_BYTE;
   static constexpr size_t BANKS = N / BANK_SIZE;
   static constexpr size_t CACHE_SIZE_BYTES = BANKS * sizeof(T);
 
   T read_cache_valid_[BANKS]{0};
+  bool invalidate_on_read_{true};
 };
 
 }  // namespace esphome::gpio_expander

esphome/components/pca9554/__init__.py

@@ -5,6 +5,7 @@ import esphome.config_validation as cv
 from esphome.const import (
     CONF_ID,
     CONF_INPUT,
+    CONF_INTERRUPT_PIN,
     CONF_INVERTED,
     CONF_MODE,
     CONF_NUMBER,
@@ -29,6 +30,7 @@ CONFIG_SCHEMA = (
         {
             cv.Required(CONF_ID): cv.declare_id(PCA9554Component),
             cv.Optional(CONF_PIN_COUNT, default=8): cv.one_of(4, 8, 16),
+            cv.Optional(CONF_INTERRUPT_PIN): pins.internal_gpio_input_pin_schema,
         }
     )
     .extend(cv.COMPONENT_SCHEMA)
@@ -43,6 +45,8 @@ async def to_code(config):
     cg.add(var.set_pin_count(config[CONF_PIN_COUNT]))
     await cg.register_component(var, config)
     await i2c.register_i2c_device(var, config)
+    if interrupt_pin := config.get(CONF_INTERRUPT_PIN):
+        cg.add(var.set_interrupt_pin(await cg.gpio_pin_expression(interrupt_pin)))
 
 
 def validate_mode(value):

esphome/components/pca9554/pca9554.cpp

@@ -34,12 +34,24 @@ void PCA9554Component::setup() {
   this->read_inputs_();
   ESP_LOGD(TAG, "Initialization complete. Warning: %d, Error: %d", this->status_has_warning(),
            this->status_has_error());
-}
 
+  if (this->interrupt_pin_ != nullptr) {
+    this->interrupt_pin_->setup();
+    this->interrupt_pin_->attach_interrupt(&PCA9554Component::gpio_intr, this, gpio::INTERRUPT_FALLING_EDGE);
+    // Don't invalidate cache on read — only invalidate when interrupt fires
+    this->set_invalidate_on_read_(false);
+    // With interrupt pin, only run loop when interrupt fires
+    this->disable_loop();
+  }
+}
+void IRAM_ATTR PCA9554Component::gpio_intr(PCA9554Component *arg) { arg->enable_loop_soon_any_context(); }
 void PCA9554Component::loop() {
-  // Invalidate the cache at the start of each loop.
-  // The actual read will happen on demand when digital_read() is called
+  // Invalidate the cache so the next digital_read() triggers a fresh I2C read
   this->reset_pin_cache_();
+  if (this->interrupt_pin_ != nullptr) {
+    // Interrupt-driven: disable loop until next interrupt fires
+    this->disable_loop();
+  }
 }
 
 void PCA9554Component::dump_config() {
@@ -47,6 +59,7 @@ void PCA9554Component::dump_config() {
                 "PCA9554:\n"
                 "  I/O Pins: %d",
                 this->pin_count_);
+  LOG_PIN("  Interrupt Pin: ", this->interrupt_pin_);
   LOG_I2C_DEVICE(this)
   if (this->is_failed()) {
     ESP_LOGE(TAG, ESP_LOG_MSG_COMM_FAIL);

esphome/components/pca9554/pca9554.h

@@ -16,7 +16,6 @@ class PCA9554Component : public Component,
 
   /// Check i2c availability and setup masks
   void setup() override;
-  /// Invalidate cache at start of each loop
   void loop() override;
   /// Helper function to set the pin mode of a pin.
   void pin_mode(uint8_t pin, gpio::Flags flags);
@@ -26,8 +25,11 @@ class PCA9554Component : public Component,
   void dump_config() override;
 
   void set_pin_count(size_t pin_count) { this->pin_count_ = pin_count; }
+  void set_interrupt_pin(InternalGPIOPin *pin) { this->interrupt_pin_ = pin; }
 
  protected:
+  static void IRAM_ATTR gpio_intr(PCA9554Component *arg);
+
   bool read_inputs_();
   bool write_register_(uint8_t reg, uint16_t value);
 
@@ -48,6 +50,7 @@ class PCA9554Component : public Component,
   uint16_t input_mask_{0x00};
   /// Storage for last I2C error seen
   esphome::i2c::ErrorCode last_error_;
+  InternalGPIOPin *interrupt_pin_{nullptr};
 };
 
 /// Helper class to expose a PCA9554 pin as an internal input GPIO pin.

esphome/components/pcf8574/__init__.py

@@ -5,6 +5,7 @@ import esphome.config_validation as cv
 from esphome.const import (
     CONF_ID,
     CONF_INPUT,
+    CONF_INTERRUPT_PIN,
     CONF_INVERTED,
     CONF_MODE,
     CONF_NUMBER,
@@ -27,6 +28,7 @@ CONFIG_SCHEMA = (
         {
             cv.Required(CONF_ID): cv.declare_id(PCF8574Component),
             cv.Optional(CONF_PCF8575, default=False): cv.boolean,
+            cv.Optional(CONF_INTERRUPT_PIN): pins.internal_gpio_input_pin_schema,
         }
     )
     .extend(cv.COMPONENT_SCHEMA)
@@ -39,6 +41,8 @@ async def to_code(config):
     await cg.register_component(var, config)
     await i2c.register_i2c_device(var, config)
     cg.add(var.set_pcf8575(config[CONF_PCF8575]))
+    if interrupt_pin := config.get(CONF_INTERRUPT_PIN):
+        cg.add(var.set_interrupt_pin(await cg.gpio_pin_expression(interrupt_pin)))
 
 
 def validate_mode(value):

esphome/components/pcf8574/pcf8574.cpp

@@ -15,16 +15,31 @@ void PCF8574Component::setup() {
 
   this->write_gpio_();
   this->read_gpio_();
+
+  if (this->interrupt_pin_ != nullptr) {
+    this->interrupt_pin_->setup();
+    this->interrupt_pin_->attach_interrupt(&PCF8574Component::gpio_intr, this, gpio::INTERRUPT_FALLING_EDGE);
+    // Don't invalidate cache on read — only invalidate when interrupt fires
+    this->set_invalidate_on_read_(false);
+    // With interrupt pin, only run loop when interrupt fires
+    this->disable_loop();
   }
+}
+void IRAM_ATTR PCF8574Component::gpio_intr(PCF8574Component *arg) { arg->enable_loop_soon_any_context(); }
 void PCF8574Component::loop() {
-  // Invalidate the cache at the start of each loop
+  // Invalidate the cache so the next digital_read() triggers a fresh I2C read
   this->reset_pin_cache_();
+  if (this->interrupt_pin_ != nullptr) {
+    // Interrupt-driven: disable loop until next interrupt fires
+    this->disable_loop();
+  }
 }
 void PCF8574Component::dump_config() {
   ESP_LOGCONFIG(TAG,
                 "PCF8574:\n"
                 "  Is PCF8575: %s",
                 YESNO(this->pcf8575_));
+  LOG_PIN("  Interrupt Pin: ", this->interrupt_pin_);
   LOG_I2C_DEVICE(this)
   if (this->is_failed()) {
     ESP_LOGE(TAG, ESP_LOG_MSG_COMM_FAIL);

esphome/components/pcf8574/pcf8574.h

@@ -17,10 +17,10 @@ class PCF8574Component : public Component,
   PCF8574Component() = default;
 
   void set_pcf8575(bool pcf8575) { pcf8575_ = pcf8575; }
+  void set_interrupt_pin(InternalGPIOPin *pin) { this->interrupt_pin_ = pin; }
 
   /// Check i2c availability and setup masks
   void setup() override;
-  /// Invalidate cache at start of each loop
   void loop() override;
   /// Helper function to set the pin mode of a pin.
   void pin_mode(uint8_t pin, gpio::Flags flags);
@@ -30,6 +30,8 @@ class PCF8574Component : public Component,
   void dump_config() override;
 
  protected:
+  static void IRAM_ATTR gpio_intr(PCF8574Component *arg);
+
   bool digital_read_hw(uint8_t pin) override;
   bool digital_read_cache(uint8_t pin) override;
   void digital_write_hw(uint8_t pin, bool value) override;
@@ -44,6 +46,7 @@ class PCF8574Component : public Component,
   /// The state read in read_gpio_ - 1 means HIGH, 0 means LOW
   uint16_t input_mask_{0x00};
   bool pcf8575_;  ///< TRUE->16-channel PCF8575, FALSE->8-channel PCF8574
+  InternalGPIOPin *interrupt_pin_{nullptr};
 };
 
 /// Helper class to expose a PCF8574 pin as an internal input GPIO pin.

tests/components/pca9554/common.yaml

@@ -3,6 +3,11 @@ pca9554:
     i2c_id: i2c_bus
     pin_count: 8
     address: 0x3F
+  - id: pca9554_hub_int
+    i2c_id: i2c_bus
+    pin_count: 8
+    address: 0x3E
+    interrupt_pin: ${interrupt_pin}
 
 binary_sensor:
   - platform: gpio

tests/components/pca9554/test.esp32-idf.yaml

@@ -1,3 +1,6 @@
+substitutions:
+  interrupt_pin: GPIO15
+
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp32-idf.yaml
 

tests/components/pca9554/test.esp8266-ard.yaml

@@ -1,3 +1,6 @@
+substitutions:
+  interrupt_pin: GPIO15
+
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp8266-ard.yaml
 

tests/components/pca9554/test.rp2040-ard.yaml

@@ -1,3 +1,6 @@
+substitutions:
+  interrupt_pin: GPIO2
+
 packages:
   i2c: !include ../../test_build_components/common/i2c/rp2040-ard.yaml
 

tests/components/pcf8574/common.yaml

@@ -3,6 +3,11 @@ pcf8574:
     i2c_id: i2c_bus
     address: 0x21
     pcf8575: false
+  - id: pcf8574_hub_int
+    i2c_id: i2c_bus
+    address: 0x22
+    pcf8575: false
+    interrupt_pin: ${interrupt_pin}
 
 binary_sensor:
   - platform: gpio

tests/components/pcf8574/test.esp32-idf.yaml

@@ -1,3 +1,6 @@
+substitutions:
+  interrupt_pin: GPIO15
+
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp32-idf.yaml
 

tests/components/pcf8574/test.esp8266-ard.yaml

@@ -1,3 +1,6 @@
+substitutions:
+  interrupt_pin: GPIO15
+
 packages:
   i2c: !include ../../test_build_components/common/i2c/esp8266-ard.yaml
 

tests/components/pcf8574/test.rp2040-ard.yaml

@@ -1,3 +1,6 @@
+substitutions:
+  interrupt_pin: GPIO2
+
 packages:
   i2c: !include ../../test_build_components/common/i2c/rp2040-ard.yaml