boneIO 1.4.0.dev4__py3-none-any.whl → 1.4.0.dev5__py3-none-any.whl

boneio/components/irrigation/controller.py

@@ -75,6 +75,7 @@ class IrrigationController:
         repeat: int = 0,
         auto_advance: bool = True,
         reverse: bool = False,
+        pause_timeout_s: int = 1800,
     ) -> None:
         """Initialize irrigation controller.
 
@@ -95,6 +96,8 @@ class IrrigationController:
             repeat: Number of cycle repeats.
             auto_advance: Automatically advance to next zone.
             reverse: Run zones in reverse order.
+            pause_timeout_s: Auto-shutdown after this many seconds in PAUSED state.
+                Default 1800 (30 minutes). Set 0 to disable.
         """
         self.id = id
         self.name = name
@@ -119,6 +122,8 @@ class IrrigationController:
         self._skip_next_run = False
 
         self._zone_timer_cancel = None
+        self._pause_timer_cancel = None
+        self._pause_timeout_s = max(0, pause_timeout_s)
         self._run_start_utc: datetime | None = None
         self._active_zone_idx: int | None = None
         self._active_zone_remaining_s: int | None = None
@@ -181,6 +186,10 @@ class IrrigationController:
     def _schedule_skip_cmd_topic(self, idx: int) -> str:
         return f"{self._topic_prefix}/cmd/{IRRIGATION}/{self.id}/schedule/{idx}/skip/set"
 
+    def _event_topic(self) -> str:
+        """MQTT topic for HA event entity notifications."""
+        return f"{self._topic_prefix}/{IRRIGATION}/{self.id}/event"
+
     def _state_key(self, suffix: str) -> str:
         return f"{self.id}/{suffix}"
 
@@ -223,6 +232,24 @@ class IrrigationController:
         _LOGGER.debug("Irrigation MQTT publish: topic='%s' payload=%s retain=%s", topic, payload, retain)
         self._message_bus.send_message(topic=topic, payload=payload, retain=retain)
 
+    def _publish_event(self, event_type: str, **attributes: Any) -> None:
+        """Publish an event to the HA event entity topic.
+
+        The payload follows the HA MQTT event entity format:
+        ``{"event_type": "...", ...extra attributes}``.
+
+        Events are NOT retained — they are instantaneous notifications.
+
+        Args:
+            event_type: One of the registered event types
+                (interlock_fault, cycle_complete, standby_blocked).
+            **attributes: Additional key-value pairs included in the event payload.
+        """
+        import json
+
+        payload = {"event_type": event_type, **attributes}
+        self._publish(self._event_topic(), json.dumps(payload), retain=False)
+
     def _ordered_zones(self) -> list[tuple[int, IrrigationZone]]:
         indexed = list(enumerate(self._zones))
         if self._reverse:
@@ -352,6 +379,7 @@ class IrrigationController:
             "".join(traceback.format_stack(limit=5)),
         )
         self.stop_schedules()
+        self._cancel_pause_timer()
         await self._stop_current_zone()
         await self._handle_pump_stop_sequence()
         self._state = ControllerState.IDLE
@@ -370,11 +398,13 @@ class IrrigationController:
         self._cancel_zone_timer()
         await self._stop_current_zone()
         self._state = ControllerState.PAUSED
+        self._arm_pause_timer()
         await self.publish_all_states()
 
     async def resume(self) -> None:
         if self._state != ControllerState.PAUSED or self._active_zone_idx is None:
             return
+        self._cancel_pause_timer()
         remaining = self._active_zone_remaining_s or self._current_zone_duration_seconds()
         await self._start_zone(self._active_zone_idx, override_duration=remaining)
 
@@ -400,6 +430,11 @@ class IrrigationController:
         )
         if self._standby:
             _LOGGER.info("Irrigation %s is in standby mode, not starting", self.id)
+            self._publish_event(
+                "standby_blocked",
+                controller=self.id,
+                message=f"Irrigation '{self.name}' start blocked: standby mode is active",
+            )
             return
 
         if self._state in (ControllerState.RUNNING, ControllerState.PAUSED):
@@ -428,6 +463,12 @@ class IrrigationController:
         )
         if self._standby:
             _LOGGER.info("Irrigation %s is in standby mode, not starting zone", self.id)
+            self._publish_event(
+                "standby_blocked",
+                controller=self.id,
+                zone=zone_id,
+                message=f"Irrigation '{self.name}' zone '{zone_id}' blocked: standby mode is active",
+            )
             return
 
         match_idx = None
@@ -551,6 +592,11 @@ class IrrigationController:
             await self._start_cycle_from_eligible()
             return
 
+        self._publish_event(
+            "cycle_complete",
+            controller=self.id,
+            message=f"Irrigation '{self.name}' cycle completed",
+        )
         await self.shutdown()
 
     def _ordered_zone_indices(self) -> list[int]:
@@ -718,8 +764,10 @@ class IrrigationController:
     async def _handle_interlock_fault(self, zone_id: str, source_id: str | None) -> None:
         """Handle interlock-blocked activation.
 
-        Shuts down the controller and publishes a fault notification via MQTT
-        so that Home Assistant (or other consumers) can alert the user.
+        Shuts down the controller and publishes both a retained fault status
+        message and a non-retained HA event notification via the event entity.
+        Home Assistant automations can listen to the event entity to trigger
+        mobile push notifications, Telegram messages, etc.
 
         Args:
             zone_id: ID of the zone that was being started.
@@ -734,13 +782,15 @@ class IrrigationController:
             source_info,
         )
 
-        # Publish fault notification on MQTT
+        fault_message = f"Irrigation '{self.name}' stopped: output blocked by interlock (zone: {zone_id})"
+
+        # Publish retained fault status on MQTT (legacy topic)
         fault_payload = {
             "fault": "interlock_blocked",
             "controller": self.id,
             "zone": zone_id,
             "source": source_id or "",
-            "message": f"Irrigation '{self.name}' stopped: output blocked by interlock (zone: {zone_id})",
+            "message": fault_message,
         }
         self._publish(
             f"{self._topic_prefix}/{IRRIGATION}/{self.id}/fault",
@@ -748,6 +798,15 @@ class IrrigationController:
             retain=False,
         )
 
+        # Publish HA event entity notification (non-retained, instantaneous)
+        self._publish_event(
+            "interlock_fault",
+            controller=self.id,
+            zone=zone_id,
+            source=source_id or "",
+            message=fault_message,
+        )
+
         await self.shutdown()
         await self.publish_all_states()
 
@@ -799,6 +858,44 @@ class IrrigationController:
     async def _zone_timer_callback(self, _timestamp: datetime) -> None:
         await self._advance_to_next_zone(force=False)
 
+    def _cancel_pause_timer(self) -> None:
+        """Cancel the pause timeout timer if active."""
+        if self._pause_timer_cancel is not None:
+            self._pause_timer_cancel()
+            self._pause_timer_cancel = None
+
+    def _arm_pause_timer(self) -> None:
+        """Arm an auto-shutdown timer for the PAUSED state.
+
+        If pause_timeout_s is 0, no timer is set (pause lasts indefinitely).
+        Otherwise, the controller will auto-shutdown after the configured timeout.
+        """
+        self._cancel_pause_timer()
+        if self._pause_timeout_s <= 0:
+            return
+        point = utcnow() + timedelta(seconds=self._pause_timeout_s)
+        self._pause_timer_cancel = async_track_point_in_time(
+            loop=self._event_bus._loop,
+            job=self._pause_timeout_callback,
+            point_in_time=point,
+        )
+        _LOGGER.info(
+            "Irrigation %s: pause timeout armed for %d seconds",
+            self.id,
+            self._pause_timeout_s,
+        )
+
+    async def _pause_timeout_callback(self, _timestamp: datetime) -> None:
+        """Handle pause timeout — auto-shutdown the controller."""
+        if self._state != ControllerState.PAUSED:
+            return
+        _LOGGER.warning(
+            "Irrigation %s: pause timeout expired after %d seconds, shutting down",
+            self.id,
+            self._pause_timeout_s,
+        )
+        await self.shutdown()
+
     async def handle_main_command(self, payload: str) -> None:
         cmd = payload.strip()
         upper = cmd.upper()

boneio/core/manager/irrigation.py

@@ -11,11 +11,13 @@ from boneio.const import NEXT_VALVE, ON, PAUSE, RESUME
 from boneio.core.utils.timeperiod import parse_time_to_seconds
 from boneio.integration.homeassistant import (
     ha_irrigation_button_message,
+    ha_irrigation_event_message,
     ha_irrigation_main_switch_message,
     ha_irrigation_number_message,
     ha_irrigation_select_message,
     ha_irrigation_switch_message,
     ha_irrigation_timestamp_sensor_message,
+    ha_irrigation_valve_message,
 )
 
 if TYPE_CHECKING:
@@ -90,6 +92,7 @@ class IrrigationManager:
             repeat=int(cfg.get("repeat", 0)),
             auto_advance=bool(cfg.get("auto_advance", True)),
             reverse=bool(cfg.get("reverse", False)),
+            pause_timeout_s=int(parse_time_to_seconds(cfg.get("pause_timeout"), 1800)),
         )
 
     def _build_zone(self, zone_cfg: dict[str, Any]) -> IrrigationZone | None:
@@ -280,9 +283,10 @@ class IrrigationManager:
             (f"{ctrl.id}_next_valve", "button"),
             (f"{ctrl.id}_pause", "button"),
             (f"{ctrl.id}_resume", "button"),
+            (f"{ctrl.id}_event", "event"),
         ]
         for zone in ctrl.zones:
-            discovery_ids.append((f"{ctrl.id}_zone_{zone.id}", "switch"))
+            discovery_ids.append((f"{ctrl.id}_zone_{zone.id}", "valve"))
             discovery_ids.append((f"{ctrl.id}_zone_{zone.id}_enabled", "switch"))
             discovery_ids.append((f"{ctrl.id}_zone_{zone.id}_duration", "number"))
         for idx in range(len(ctrl._schedule)):
@@ -506,10 +510,16 @@ class IrrigationManager:
         )
 
         for zone in ctrl.zones:
+            # Remove stale switch discovery (migration from switch → valve)
             self._manager.publish_ha_discovery(
                 id=f"{ctrl.id}_zone_{zone.id}",
                 ha_type="switch",
-                payload=ha_irrigation_switch_message(
+                payload="",
+            )
+            self._manager.publish_ha_discovery(
+                id=f"{ctrl.id}_zone_{zone.id}",
+                ha_type="valve",
+                payload=ha_irrigation_valve_message(
                     ctrl.id,
                     ctrl.name,
                     suffix=f"zone/{zone.id}",
@@ -584,3 +594,14 @@ class IrrigationManager:
                     config_helper=cfg,
                 ),
             )
+
+        # Event entity — fires on interlock faults, cycle completions, etc.
+        self._manager.publish_ha_discovery(
+            id=f"{ctrl.id}_event",
+            ha_type="event",
+            payload=ha_irrigation_event_message(
+                ctrl.id,
+                ctrl.name,
+                config_helper=cfg,
+            ),
+        )

boneio/core/manager/manager.py

@@ -611,7 +611,7 @@ class Manager:
         self,
         id: str,
         ha_type: str,
-        payload: dict,
+        payload: dict[str, Any] | str,
     ) -> None:
         """Publish a pre-built HA autodiscovery payload.
 

boneio/core/messaging/lox.py

@@ -1,4 +1,11 @@
-"""Lox UDP Client for BoneIO."""
+"""Lox UDP Client for BoneIO.
+
+Implements the Loxone UDP protocol for bidirectional communication
+between BoneIO and a Loxone Miniserver:
+
+- Receiving commands from Miniserver (e.g. "OUT_04=ON")
+- Sending state feedback to Miniserver (e.g. "OUT_04=ON", "cover1=50")
+"""
 
 from __future__ import annotations
 
@@ -16,6 +23,11 @@ if TYPE_CHECKING:
 
 _LOGGER = logging.getLogger(__name__)
 
+# Entity types whose state changes should be forwarded to Loxone
+_LOX_ENTITY_TYPES = frozenset(
+    ("output", "cover", "sensor", "event", "binary_sensor", "input")
+)
+
 
 class LoxUDPProtocol(asyncio.DatagramProtocol):
     """Protocol for handling Lox UDP communication."""
@@ -25,9 +37,14 @@ class LoxUDPProtocol(asyncio.DatagramProtocol):
         self._loop = asyncio.get_running_loop()
 
     def connection_made(self, transport: asyncio.DatagramTransport) -> None:
+        """Handle connection established."""
         self.transport = transport
 
     def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        """Handle incoming datagram.
+
+        Expected message format: "device_id=value" or just "device_id".
+        """
         try:
             message = data.decode("utf-8").strip()
             _LOGGER.debug("Received Lox UDP message: %s from %s", message, addr)
@@ -45,7 +62,20 @@ class LoxUDPProtocol(asyncio.DatagramProtocol):
 
 
 class LoxUDPClient(MessageBus):
-    """Represent a Lox UDP client."""
+    """Represent a Lox UDP client.
+
+    This message bus translates between BoneIO's internal MQTT-style
+    topic/payload model and the simple "key=value" UDP protocol
+    expected by Loxone Miniserver.
+
+    Outgoing (BoneIO → Miniserver):
+        topic "boneio/{serial}/output/relay1" + payload {"state": "ON"}
+        → UDP datagram "relay1=ON" sent to Miniserver
+
+    Incoming (Miniserver → BoneIO):
+        UDP datagram "relay1=ON"
+        → routed to Manager as "boneio/{serial}/cmd/output/relay1/set" = "ON"
+    """
 
     def __init__(
         self,
@@ -54,7 +84,14 @@ class LoxUDPClient(MessageBus):
         send_port: int,
         listen_port: int,
     ) -> None:
-        """Set up client."""
+        """Set up client.
+
+        Args:
+            config_helper: BoneIO configuration helper.
+            host: Loxone Miniserver IP address.
+            send_port: Port on Miniserver to send state feedback to.
+            listen_port: Port BoneIO listens on for commands from Miniserver.
+        """
         self._manager: Manager | None = None
         self._config_helper = config_helper
         self.host = host
@@ -71,64 +108,116 @@ class LoxUDPClient(MessageBus):
         retain: bool = False,
         qos: int = 0,
     ) -> None:
-        """Send a message via UDP.
+        """Send a state update to Loxone Miniserver via UDP.
 
-        Converts MQTT-style messages to simple UDP datagrams.
-        Topic format: boneio/{serial}/{type}/{device_id}
-        Payload: dict {"state": "ON"} or string "ON"
+        Converts BoneIO's MQTT-style topic/payload into a simple UDP
+        datagram in the format "device_id=state_value".
 
-        Sent UDP message format: {device_id}={state_value}
+        Topic format: boneio/{serial}/{entity_type}/{device_id}
+        or:           boneio/{serial}/{entity_type}/{device_id}/state
+        or:           boneio/{serial}/{entity_type}/{device_id}/pos
+
+        Args:
+            topic: MQTT-style topic string.
+            payload: State payload (dict, string, bytes, int, or None).
+            retain: Ignored for UDP.
+            qos: Ignored for UDP.
         """
         if payload is None:
             return
 
-        # Skip HA Discovery messages (they have complex payloads not relevant for Lox)
-        if isinstance(payload, dict) and "config" in str(topic):
-            return
+        topic_str = str(topic)
+        parts = topic_str.split("/")
 
-        # Extract device_id from topic: boneio/{serial}/{type}/{device_id}
-        parts = str(topic).split("/")
+        # Need at least: prefix/serial/entity_type/device_id
         if len(parts) < 4:
             return
 
-        device_id = parts[-1]
-        entity_type = parts[-2] if len(parts) >= 3 else ""
-
-        # Skip command topics (cmd/), availability, and discovery
-        if "cmd" in parts or device_id in ("state", "config", "set"):
+        # Skip HA Discovery messages (homeassistant/*/config topics)
+        if parts[0] == "homeassistant" or topic_str.endswith("/config"):
             return
 
-        # Only send state for outputs, covers, and sensors
-        if entity_type not in ("output", "cover", "sensor"):
+        # Skip command topics — we only send state feedback, not commands
+        if "cmd" in parts:
             return
 
-        # Extract state value from payload
-        if isinstance(payload, dict):
-            # {"state": "ON"} → "ON"
-            state_value = payload.get("state", payload.get("value", ""))
-            if not state_value and payload:
-                # Fallback: use first value
-                state_value = str(next(iter(payload.values()), ""))
-        elif isinstance(payload, bytes):
-            state_value = payload.decode("utf-8")
+        # Determine entity_type and device_id based on topic structure
+        # Standard: boneio/{serial}/{entity_type}/{device_id}
+        # With suffix: boneio/{serial}/{entity_type}/{device_id}/state
+        # With suffix: boneio/{serial}/{entity_type}/{device_id}/pos
+        entity_type = parts[2] if len(parts) >= 3 else ""
+        suffix = parts[-1] if len(parts) >= 5 else ""
+
+        # For topics with suffix (state/pos), device_id is parts[-2]
+        if suffix in ("state", "pos", "set"):
+            device_id = parts[-2]
         else:
-            state_value = str(payload)
+            device_id = parts[-1]
+
+        # Skip non-relevant entity types
+        if entity_type not in _LOX_ENTITY_TYPES:
+            return
 
+        # Skip "set" suffix — those are incoming commands, not state feedback
+        if suffix == "set":
+            return
+
+        # Extract state value from payload
+        state_value = self._extract_state_value(payload)
         if not state_value:
             return
 
+        self._send_udp(device_id, state_value)
+
+    @staticmethod
+    def _extract_state_value(
+        payload: str | int | bytes | dict[str, Any] | HomeAssistantDiscoveryMessage,
+    ) -> str:
+        """Extract a simple state string from various payload formats.
+
+        Args:
+            payload: The message payload in any supported format.
+
+        Returns:
+            State value as string, or empty string if extraction fails.
+        """
+        if isinstance(payload, dict):
+            # Try standard keys: {"state": "ON"}, {"value": "50"}
+            state_value = payload.get("state", payload.get("value", ""))
+            if state_value:
+                return str(state_value)
+            # Fallback: use first value from dict
+            if payload:
+                return str(next(iter(payload.values()), ""))
+            return ""
+        if isinstance(payload, bytes):
+            return payload.decode("utf-8")
+        return str(payload)
+
+    def _send_udp(self, device_id: str, state_value: str) -> None:
+        """Send a UDP datagram to Loxone Miniserver.
+
+        Args:
+            device_id: Entity identifier (e.g. "relay1", "cover1").
+            state_value: State value string (e.g. "ON", "50").
+        """
         try:
             udp_msg = f"{device_id}={state_value}".encode()
-
             if self._transport:
                 self._transport.sendto(udp_msg, (self.host, self.send_port))
                 _LOGGER.debug(
-                    "Sent Lox UDP message: %s to %s:%s", udp_msg.decode("utf-8"), self.host, self.send_port
+                    "Sent Lox UDP message: %s to %s:%s",
+                    udp_msg.decode("utf-8"),
+                    self.host,
+                    self.send_port,
                 )
             else:
-                _LOGGER.debug("Lox UDP transport not ready yet, dropping: %s", udp_msg.decode("utf-8"))
+                _LOGGER.debug(
+                    "Lox UDP transport not ready, dropping: %s",
+                    udp_msg.decode("utf-8"),
+                )
         except Exception as e:
-            _LOGGER.error("Error sending Lox UDP message for topic %s: %s", topic, e)
+            _LOGGER.error("Error sending Lox UDP message: %s", e)
 
     @property
     def state(self) -> bool:
@@ -140,7 +229,8 @@ class LoxUDPClient(MessageBus):
         try:
             loop = asyncio.get_running_loop()
             transport, protocol = await loop.create_datagram_endpoint(
-                lambda: LoxUDPProtocol(self._handle_incoming), local_addr=("0.0.0.0", self.listen_port)
+                lambda: LoxUDPProtocol(self._handle_incoming),
+                local_addr=("0.0.0.0", self.listen_port),
             )
             self._transport = transport
             self._state = True
@@ -167,16 +257,18 @@ class LoxUDPClient(MessageBus):
                 self._transport.close()
 
     def set_manager(self, manager: Manager) -> None:
-        """Set manager."""
+        """Set manager reference for routing incoming commands."""
         self._manager = manager
 
     async def announce_offline(self) -> None:
-        """Announce offline status."""
+        """Announce offline status to Miniserver."""
         if self._transport:
             self._transport.sendto(b"boneio=offline", (self.host, self.send_port))
 
-    async def subscribe_and_listen(self, topic: str, callback: Callable[[str, str], Awaitable[None]]) -> None:
-        """Register a listener."""
+    async def subscribe_and_listen(
+        self, topic: str, callback: Callable[[str, str], Awaitable[None]]
+    ) -> None:
+        """Register a listener for a topic pattern."""
         self._listeners[topic] = callback
 
     async def unsubscribe_and_stop_listen(self, topic: str) -> None:
@@ -185,7 +277,15 @@ class LoxUDPClient(MessageBus):
             del self._listeners[topic]
 
     async def _handle_incoming(self, device: str, payload: str) -> None:
-        """Handle incoming Lox messages and route them to Manager or listeners."""
+        """Handle incoming Lox messages and route them to Manager.
+
+        Resolves the device name to an entity type (output/cover) and
+        forwards the command to the Manager's receive_message method.
+
+        Args:
+            device: Device identifier from UDP message (e.g. "relay1").
+            payload: Command value from UDP message (e.g. "ON").
+        """
         _LOGGER.debug("Lox handle incoming: %s = %s", device, payload)
 
         if not self._manager:
@@ -195,7 +295,9 @@ class LoxUDPClient(MessageBus):
             cmd_prefix = self._config_helper.cmd_topic_prefix
             msg_type = None
 
-            output = self._manager.outputs.get_output(device) or self._manager.outputs.get_output_group(device)
+            output = self._manager.outputs.get_output(
+                device
+            ) or self._manager.outputs.get_output_group(device)
             if output:
                 msg_type = "output"
             else:
@@ -204,7 +306,9 @@ class LoxUDPClient(MessageBus):
                     msg_type = "cover"
 
             if not msg_type:
-                _LOGGER.warning("Lox UDP device %s not found in outputs/covers", device)
+                _LOGGER.warning(
+                    "Lox UDP device %s not found in outputs/covers", device
+                )
                 return
 
             full_topic = f"{cmd_prefix}{msg_type}/{device}/set"
@@ -212,7 +316,8 @@ class LoxUDPClient(MessageBus):
             # Check explicit listeners
             for listen_topic, callback in self._listeners.items():
                 if listen_topic == full_topic or (
-                    listen_topic.endswith("/#") and full_topic.startswith(listen_topic[:-2])
+                    listen_topic.endswith("/#")
+                    and full_topic.startswith(listen_topic[:-2])
                 ):
                     await callback(full_topic, payload)