Merge pull request #85 from sirkirby/device-triggers

sirkirby · web-flow · commit 818a44d80d06 · 2025-07-28T13:56:21.000-04:00
diff --git a/.cursor/rules/unr-rules.mdc b/.cursor/rules/unr-rules.mdc
@@ -1,5 +1,5 @@
 ---
-description: Purpose of this custom home assistant integration along with general coding practics and scope guidance
+description: Purpose of this custom home assistant integration along with general coding practices and scope guidance
 globs: custom_components/**/*.py
 alwaysApply: true
 ---
@@ -8,12 +8,12 @@ alwaysApply: true
 
 - Always keep the code DRY for testability and separation of concerns
 - Prefer modern idiomatic Python 3.13 and open source conventions, Leverage type hints, use CONST over hard coded strings
-- Prioritize native Home Assistant libraries, like aiounifi, and other core capabilities to respect available resources and to avoid building duplicate fuctionality. Leverage the latest Home Assistant documentation.
+- Prioritize native Home Assistant libraries, like aiounifi, and other core capabilities to respect available resources and to avoid building duplicate functionality. Leverage the latest Home Assistant documentation.
 - Diagnostics enabled for observability and debugging should be targeted, respecting the resources of the system
-- All data retrived and stored from the API should be typed, if not supplied by aiounifi, then a custom type should be created
+- All data retrieved and stored from the API should be typed, if not supplied by aiounifi, then a custom type should be created
 - When designing a new feature, prefer elegant solutions using established best practices and patterns.
-- When fixing a problem or bug, avoid treating the symptop, look for the root cause.
-- Details matter, ensure to always preserve existing functionlity unless otherwise instructed.
+- When fixing a problem or bug, avoid treating the symptom, look for the root cause.
+- Details matter, ensure to always preserve existing functionality unless otherwise instructed.
 - KISS
 
 ## Notes
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -0,0 +1,35 @@
+# Project Overview
+
+This project is a custom home assistant integration to manage UniFi Network policies and rules. It is designed to provide a seamless and efficient way to manage and automate your home network policies and rules within home assistant.
+
+## Project Structure
+
+The project is organized into the following directories:
+
+- `custom_components/unifi_network_rules`: The custom home assistant integration
+- - `udm`: Code for interacting with the Unifi Network API
+- - `models`: data models
+- - `services`: custom services
+- - `helpers`: helper functions
+- - `utils`: utility functions
+- - `manifest.json`: The manifest for the integration.
+- `tests`: The test suite.
+- `docs`: The documentation.
+
+## Libraries and Frameworks
+
+- `aiounifi`: The library for interacting with the Unifi Network API
+- `homeassistant`: The library for interacting with the Home Assistant API
+- python 3.13
+
+## Coding Standards
+
+- Always keep the code DRY for testability and separation of concerns
+- Prefer modern idiomatic Python 3.13 and open source conventions, Leverage type hints, use CONST over hard coded strings
+- Prioritize native Home Assistant libraries, like aiounifi, and other core capabilities to respect available resources and to avoid building duplicate functionality. Leverage the latest Home Assistant documentation.
+- Diagnostics enabled for observability and debugging should be targeted, respecting the resources of the system
+- All data retrieved and stored from the API should be typed, if not supplied by aiounifi, then a custom type should be created
+- When designing a new feature, prefer elegant solutions using established best practices and patterns.
+- When fixing a problem or bug, avoid treating the symptom, look for the root cause.
+- Details matter, ensure to always preserve existing functionality unless otherwise instructed.
+- KISS
diff --git a/custom_components/unifi_network_rules/coordinator.py b/custom_components/unifi_network_rules/coordinator.py
@@ -22,7 +22,7 @@
 from aiounifi.models.wlan import Wlan
 from aiounifi.models.device import Device
 
-from .const import DOMAIN, LOGGER, CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL, DEBUG_WEBSOCKET
+from .const import DOMAIN, LOGGER, CONF_UPDATE_INTERVAL, DEFAULT_UPDATE_INTERVAL, DEBUG_WEBSOCKET, LOG_TRIGGERS
 from .udm import UDMAPI
 from .websocket import SIGNAL_WEBSOCKET_MESSAGE, UnifiRuleWebsocket
 from .helpers.rule import get_rule_id, get_rule_name, get_rule_enabled, get_child_unique_id
@@ -169,6 +169,145 @@ def check_and_consume_ha_initiated_operation(self, rule_id: str) -> bool:
             return True
         return False
 
+    def fire_device_trigger_via_dispatcher(self, device_id: str, device_name: str, change_type: str, old_state: Any = None, new_state: Any = None) -> None:
+        """Fire device_changed triggers using Home Assistant's dispatcher pattern.
+        
+        This method dispatches device change events that trigger instances can listen for.
+        Uses the same dispatcher pattern as other coordinator events for consistency.
+        
+        Args:
+            device_id: The ID of the device that changed (e.g., MAC address)
+            device_name: Human-readable name of the device
+            change_type: Type of change (e.g., "led_toggled", "reboot")
+            old_state: Previous state of the device property
+            new_state: New state of the device property
+        """
+        if LOG_TRIGGERS:
+            LOGGER.info("🔥 COORDINATOR: Dispatching device trigger for %s (%s): %s", 
+                       device_name, device_id, change_type)
+        
+        # Prepare trigger data
+        trigger_data = {
+            "device_id": device_id,
+            "device_name": device_name,
+            "change_type": change_type,
+            "old_state": old_state,
+            "new_state": new_state,
+            "trigger_type": "device_changed"
+        }
+        
+        # Dispatch via Home Assistant's dispatcher system
+        try:
+            # Get entry_id for this coordinator
+            entry_id = self.config_entry.entry_id if self.config_entry else "unknown"
+            signal_name = f"{DOMAIN}_device_trigger_{entry_id}"
+            
+            async_dispatcher_send(self.hass, signal_name, trigger_data)
+            
+            if LOG_TRIGGERS:
+                LOGGER.info("✅ COORDINATOR: Dispatched device trigger signal: %s", signal_name)
+                
+        except Exception as err:
+            LOGGER.error("Error dispatching device trigger: %s", err)
+
+    def _check_for_device_state_changes(self, previous_data: Dict[str, List[Any]], new_data: Dict[str, List[Any]]) -> None:
+        """Check for device state changes and fire device triggers accordingly.
+        
+        This provides eventual consistency by detecting device changes during regular 
+        coordinator polling cycles, in case websocket events are not received.
+        
+        Args:
+            previous_data: The previous coordinator data
+            new_data: The current coordinator data
+        """
+        if not previous_data or not new_data:
+            LOGGER.debug("Skipping device state change detection - no previous or new data")
+            return
+            
+        previous_devices = previous_data.get("devices", [])
+        new_devices = new_data.get("devices", [])
+        
+        if not previous_devices and not new_devices:
+            return  # No devices to compare
+            
+        # Create lookup dictionaries by device MAC for efficient comparison
+        previous_device_states = {}
+        for device in previous_devices:
+            try:
+                device_id = getattr(device, 'mac', getattr(device, 'id', None))
+                if device_id:
+                    previous_device_states[device_id] = {
+                        'led_override': getattr(device, 'led_override', None),
+                        'name': getattr(device, 'name', f"Device {device_id}"),
+                        'state': getattr(device, 'state', 1)  # Connection state
+                    }
+            except Exception as err:
+                LOGGER.warning("Error processing previous device state: %s", err)
+                
+        new_device_states = {}
+        for device in new_devices:
+            try:
+                device_id = getattr(device, 'mac', getattr(device, 'id', None))
+                if device_id:
+                    new_device_states[device_id] = {
+                        'led_override': getattr(device, 'led_override', None),
+                        'name': getattr(device, 'name', f"Device {device_id}"),
+                        'state': getattr(device, 'state', 1)  # Connection state
+                    }
+            except Exception as err:
+                LOGGER.warning("Error processing new device state: %s", err)
+        
+        # Compare device states and fire triggers for changes
+        all_device_ids = set(previous_device_states.keys()) | set(new_device_states.keys())
+        
+        for device_id in all_device_ids:
+            previous_state = previous_device_states.get(device_id)
+            new_state = new_device_states.get(device_id)
+            
+            # Skip if device was just added or removed (handled elsewhere)
+            if not previous_state or not new_state:
+                continue
+                
+            # Check for LED state changes
+            prev_led = previous_state.get('led_override')
+            new_led = new_state.get('led_override')
+            
+            if prev_led != new_led:
+                device_name = new_state.get('name', f"Device {device_id}")
+                
+                if LOG_TRIGGERS:
+                    LOGGER.info("🔍 DEVICE STATE CHANGE DETECTED: %s (%s) LED: %s → %s", 
+                               device_name, device_id, prev_led, new_led)
+                
+                # Fire device trigger via dispatcher
+                self.fire_device_trigger_via_dispatcher(
+                    device_id=device_id,
+                    device_name=device_name,
+                    change_type="led_toggled",
+                    old_state=prev_led,
+                    new_state=new_led
+                )
+            
+            # Check for connection state changes
+            prev_connection = previous_state.get('state')
+            new_connection = new_state.get('state')
+            
+            if prev_connection != new_connection:
+                device_name = new_state.get('name', f"Device {device_id}")
+                
+                if LOG_TRIGGERS:
+                    LOGGER.info("🔍 DEVICE CONNECTION CHANGE DETECTED: %s (%s) State: %s → %s", 
+                               device_name, device_id, prev_connection, new_connection)
+                
+                # Fire device trigger via dispatcher
+                self.fire_device_trigger_via_dispatcher(
+                    device_id=device_id,
+                    device_name=device_name,
+                    change_type="connection_changed",
+                    old_state=prev_connection,
+                    new_state=new_connection
+                )
+
     async def _async_update_data(self) -> Dict[str, List[Any]]:
         """Fetch data from API endpoint."""
         # Use a lock to prevent concurrent updates, especially during authentication
@@ -417,6 +556,9 @@ async def _async_update_data(self) -> Dict[str, List[Any]]:
                         # --- Check for DELETED Entities ---
                         self._check_for_deleted_rules(rules_data)
 
+                        # --- Check for Device State Changes ---
+                        self._check_for_device_state_changes(previous_data, rules_data)
+
                         # --- Discover and Add NEW Entities --- 
                         await self._discover_and_add_new_entities(rules_data)
 
diff --git a/custom_components/unifi_network_rules/manifest.json b/custom_components/unifi_network_rules/manifest.json
@@ -15,5 +15,5 @@
         "aiounifi>=82.0.0",
         "orjson>=3.8.0"
     ],
-    "version": "3.1.0"
+    "version": "3.2.0"
 }
diff --git a/custom_components/unifi_network_rules/switch.py b/custom_components/unifi_network_rules/switch.py
@@ -30,7 +30,7 @@
 from aiounifi.models.wlan import Wlan
 from aiounifi.models.device import Device  # For LED toggle
 
-from .const import DOMAIN, MANUFACTURER, SWITCH_DELAYED_VERIFICATION_SLEEP_SECONDS
+from .const import DOMAIN, MANUFACTURER, SWITCH_DELAYED_VERIFICATION_SLEEP_SECONDS, LOG_TRIGGERS
 from .helpers.rule import sanitize_entity_id
 from .coordinator import UnifiRuleUpdateCoordinator
 from .helpers.rule import (
@@ -743,7 +743,9 @@ async def delayed_verification():
                             # The flag was already consumed, so the trigger worked correctly.
                             LOGGER.debug("Delayed verification: Trigger confirmed change for %s. No refresh needed.", self._rule_id)
                     
-                    self.hass.async_create_task(delayed_verification())
+                    # Skip delayed verification for device LED toggles since we use immediate trigger + polling detection
+                    if self._rule_type != "devices":
+                        self.hass.async_create_task(delayed_verification())
                 
             except Exception as err:
                 # Check if this is an auth error
@@ -1579,6 +1581,35 @@ def _handle_coordinator_update(self) -> None:
         # Call parent update (handles optimistic state and availability)
         super()._handle_coordinator_update()
 
+    async def _async_toggle_rule(self, enable: bool) -> None:
+        """Override toggle for LED devices to add immediate trigger firing."""
+        # Fire immediate device trigger for optimistic response
+        try:
+            device_name = getattr(self._device, 'name', f"Device {self._rule_id}")
+            device_id = getattr(self._device, 'mac', self._rule_id)
+            
+            # Use existing CQRS pattern to track this HA-initiated operation
+            self.coordinator.register_ha_initiated_operation(device_id)
+            
+            if LOG_TRIGGERS:
+                LOGGER.info("🔥 LED IMMEDIATE TRIGGER: Firing device trigger for %s (%s): %s → %s", 
+                           device_name, device_id, not enable, enable)
+            
+            # Fire immediate device trigger via dispatcher
+            self.coordinator.fire_device_trigger_via_dispatcher(
+                device_id=device_id,
+                device_name=device_name,
+                change_type="led_toggled",
+                old_state=not enable,
+                new_state=enable
+            )
+            
+        except Exception as trigger_err:
+            LOGGER.error("Error firing immediate device trigger for LED toggle: %s", trigger_err)
+        
+        # Call parent toggle method to handle the actual API operation
+        await super()._async_toggle_rule(enable)
+
     @property
     def extra_state_attributes(self) -> Dict[str, Any]:
         """Return entity specific state attributes."""
diff --git a/custom_components/unifi_network_rules/trigger.py b/custom_components/unifi_network_rules/trigger.py
diff --git a/custom_components/unifi_network_rules/triggers.yaml b/custom_components/unifi_network_rules/triggers.yaml

Original file line number	Diff line number	Diff line change
`@@ -15,5 +15,5 @@`
`15`	`15`	`"aiounifi>=82.0.0",`
`16`	`16`	`"orjson>=3.8.0"`
`17`	`17`	`],`
`18`		`- "version": "3.1.0"`
	`18`	`+ "version": "3.2.0"`
`19`	`19`	`}`