python-omnilogic-local 1.0.0__tar.gz → 1.1.0__tar.gz

{python_omnilogic_local-1.0.0 → python_omnilogic_local-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-omnilogic-local
-Version: 1.0.0
+Version: 1.1.0
 Summary: A library for local control of Hayward OmniHub/OmniLogic pool controllers using their local API
 Author: Chris Jowett, djtimca, garionphx
 Author-email: Chris Jowett <421501+cryptk@users.noreply.github.com>

python_omnilogic_local-1.1.0/pyomnilogic_local/api/__init__.py

@@ -0,0 +1,36 @@
+"""API module for interacting with Hayward OmniLogic pool controllers.
+
+This module provides the OmniLogicAPI class, which allows for local
+control and monitoring of Hayward OmniLogic and OmniHub pool controllers
+over a local network connection via the UDP XML API.
+"""
+
+from __future__ import annotations
+
+from .api import OmniLogicAPI
+from .exceptions import (
+    OmniCommandError,
+    OmniConnectionError,
+    OmniFragmentationError,
+    OmniLogicError,
+    OmniMessageFormatError,
+    OmniProtocolError,
+    OmniTimeoutError,
+    OmniValidationError,
+)
+from .message import OmniLogicMessage
+from .protocol import OmniLogicProtocol
+
+__all__ = [
+    "OmniCommandError",
+    "OmniConnectionError",
+    "OmniFragmentationError",
+    "OmniLogicAPI",
+    "OmniLogicError",
+    "OmniLogicMessage",
+    "OmniLogicProtocol",
+    "OmniMessageFormatError",
+    "OmniProtocolError",
+    "OmniTimeoutError",
+    "OmniValidationError",
+]

{python_omnilogic_local-1.0.0 → python_omnilogic_local-1.1.0}/pyomnilogic_local/api/api.py

@@ -111,30 +111,39 @@ class OmniLogicAPI:
         self.controller_port = controller_port
         self.response_timeout = response_timeout
 
-    @overload
-    async def async_send_message(self, message_type: MessageType, message: str | None, need_response: Literal[True]) -> str: ...
-    @overload
-    async def async_send_message(self, message_type: MessageType, message: str | None, need_response: Literal[False]) -> None: ...
-    async def async_send_message(self, message_type: MessageType, message: str | None, need_response: bool = False) -> str | None:
+    async def async_send(self, message_type: MessageType, message: str) -> None:
         """Send a message via the Hayward Omni UDP protocol along with properly handling timeouts and responses.
 
         Args:
             message_type (MessageType): A selection from MessageType indicating what type of communication you are sending
-            message (str | None): The XML body of the message to deliver
-            need_response (bool, optional): Should a response be received and returned to the caller. Defaults to False.
+            message (str): The XML body of the message to deliver
+
+        Returns:
+            None
+        """
+        loop = asyncio.get_running_loop()
+        transport, protocol = await loop.create_datagram_endpoint(OmniLogicProtocol, remote_addr=(self.controller_ip, self.controller_port))
+
+        try:
+            await protocol.async_send(message_type, message)
+        finally:
+            transport.close()
+
+    async def async_send_and_receive(self, message_type: MessageType, message: str) -> str:
+        """Convenience method to send a message and receive a response without needing to specify need_response every time.
+
+        Args:
+            message_type (MessageType): A selection from MessageType indicating what type of communication you are sending
+            message (str): The message payload to send.
 
         Returns:
-            str | None: The response body sent from the Omni if need_response indicates that a response will be sent
+            str: The response body sent from the Omni
         """
         loop = asyncio.get_running_loop()
         transport, protocol = await loop.create_datagram_endpoint(OmniLogicProtocol, remote_addr=(self.controller_ip, self.controller_port))
 
-        resp: str | None = None
         try:
-            if need_response:
-                resp = await protocol.send_and_receive(message_type, message, response_timeout=self.response_timeout)
-            else:
-                await protocol.send_message(message_type, message)
+            resp = await protocol.async_send_and_receive(message_type, message)
         finally:
             transport.close()
 
@@ -164,7 +173,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending RequestConfiguration with body: %s", req_body)
 
-        resp = await self.async_send_message(MessageType.REQUEST_CONFIGURATION, req_body, True)
+        resp = await self.async_send_and_receive(MessageType.REQUEST_CONFIGURATION, req_body)
 
         _LOGGER.debug("Received response for RequestConfiguration: %s", resp)
 
@@ -206,7 +215,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending GetUIFilterDiagnosticInfo with body: %s", req_body)
 
-        resp = await self.async_send_message(MessageType.GET_FILTER_DIAGNOSTIC_INFO, req_body, True)
+        resp = await self.async_send_and_receive(MessageType.GET_FILTER_DIAGNOSTIC_INFO, req_body)
 
         _LOGGER.debug("Received response for GetUIFilterDiagnosticInfo: %s", resp)
 
@@ -235,7 +244,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending RequestTelemetryData with body: %s", req_body)
 
-        resp = await self.async_send_message(MessageType.GET_TELEMETRY, req_body, True)
+        resp = await self.async_send_and_receive(MessageType.GET_TELEMETRY, req_body)
 
         _LOGGER.debug("Received response for RequestTelemetryData: %s", resp)
 
@@ -276,7 +285,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUIHeaterCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_HEATER_COMMAND, req_body, False)
+        return await self.async_send(MessageType.SET_HEATER_COMMAND, req_body)
 
     async def async_set_solar_heater(
         self,
@@ -311,7 +320,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUISolarSetPointCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_SOLAR_SET_POINT_COMMAND, req_body, False)
+        return await self.async_send(MessageType.SET_SOLAR_SET_POINT_COMMAND, req_body)
 
     async def async_set_heater_mode(
         self,
@@ -346,7 +355,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUIHeaterModeCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_HEATER_MODE_COMMAND, req_body, False)
+        return await self.async_send(MessageType.SET_HEATER_MODE_COMMAND, req_body)
 
     async def async_set_heater_enable(
         self,
@@ -381,7 +390,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetHeaterEnable with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_HEATER_ENABLED, req_body, False)
+        return await self.async_send(MessageType.SET_HEATER_ENABLED, req_body)
 
     async def async_set_equipment(
         self,
@@ -443,7 +452,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUIEquipmentCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_EQUIPMENT, req_body, False)
+        return await self.async_send(MessageType.SET_EQUIPMENT, req_body)
 
     async def async_set_filter_speed(self, pool_id: int, equipment_id: int, speed: int) -> None:
         """Set the speed for a variable speed filter/pump.
@@ -471,7 +480,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUIFilterSpeedCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_FILTER_SPEED, req_body, False)
+        return await self.async_send(MessageType.SET_FILTER_SPEED, req_body)
 
     async def async_set_light_show(
         self,
@@ -543,7 +552,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetStandAloneLightShow with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_STANDALONE_LIGHT_SHOW, req_body, False)
+        return await self.async_send(MessageType.SET_STANDALONE_LIGHT_SHOW, req_body)
 
     async def async_set_chlorinator_enable(self, pool_id: int, enabled: int | bool) -> None:
         body_element = ET.Element("Request", {"xmlns": XML_NAMESPACE})
@@ -561,7 +570,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetCHLOREnable with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_CHLOR_ENABLED, req_body, False)
+        return await self.async_send(MessageType.SET_CHLOR_ENABLED, req_body)
 
     # This is used to set the ORP target value on a CSAD
     async def async_set_csad_orp_target_level(
@@ -587,7 +596,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUICSADORPTargetLevel with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_CSAD_ORP_TARGET, req_body, False)
+        return await self.async_send(MessageType.SET_CSAD_ORP_TARGET, req_body)
 
     # This is used to set the pH target value on a CSAD
     async def async_set_csad_target_value(
@@ -613,7 +622,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending UISetCSADTargetValue with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_CSAD_TARGET_VALUE, req_body, False)
+        return await self.async_send(MessageType.SET_CSAD_TARGET_VALUE, req_body)
 
     async def async_set_chlorinator_params(
         self,
@@ -656,7 +665,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetCHLORParams with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_CHLOR_PARAMS, req_body, False)
+        return await self.async_send(MessageType.SET_CHLOR_PARAMS, req_body)
 
     async def async_set_chlorinator_superchlorinate(
         self,
@@ -681,7 +690,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUISuperCHLORCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_SUPERCHLORINATE, req_body, False)
+        return await self.async_send(MessageType.SET_SUPERCHLORINATE, req_body)
 
     async def async_restore_idle_state(self) -> None:
         body_element = ET.Element("Request", {"xmlns": XML_NAMESPACE})
@@ -695,7 +704,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending RestoreIdleState with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.RESTORE_IDLE_STATE, req_body, False)
+        return await self.async_send(MessageType.RESTORE_IDLE_STATE, req_body)
 
     async def async_set_spillover(
         self,
@@ -738,7 +747,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending SetUISpilloverCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.SET_SPILLOVER, req_body, False)
+        return await self.async_send(MessageType.SET_SPILLOVER, req_body)
 
     async def async_set_group_enable(
         self,
@@ -781,7 +790,7 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending RunGroupCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.RUN_GROUP_CMD, req_body, False)
+        return await self.async_send(MessageType.RUN_GROUP_CMD, req_body)
 
     async def async_edit_schedule(
         self,
@@ -854,4 +863,4 @@ class OmniLogicAPI:
 
         _LOGGER.debug("Sending EditUIScheduleCmd with body: %s", req_body)
 
-        return await self.async_send_message(MessageType.EDIT_SCHEDULE, req_body, False)
+        return await self.async_send(MessageType.EDIT_SCHEDULE, req_body)

{python_omnilogic_local-1.0.0 → python_omnilogic_local-1.1.0}/pyomnilogic_local/api/constants.py

@@ -11,9 +11,9 @@ PROTOCOL_VERSION = "1.19"  # Current protocol version
 BLOCK_MESSAGE_HEADER_OFFSET = 8  # Offset to skip block message header and get to payload
 
 # Timing Constants (in seconds)
-OMNI_RETRANSMIT_TIME = 2.1  # Time Omni waits before retransmitting a packet
+OMNI_RETRANSMIT_TIME = 2  # Time Omni waits before retransmitting a packet
 OMNI_RETRANSMIT_COUNT = 5  # Number of retransmit attempts (6 total including initial)
-ACK_WAIT_TIMEOUT = 1  # Timeout waiting for ACK response, 0.5 showed to be just a tad too short in some cases.
+ACK_WAIT_TIMEOUT = OMNI_RETRANSMIT_TIME * 2  # Timeout waiting for ACK response, 0.5 showed to be just a tad too short in some cases.
 DEFAULT_RESPONSE_TIMEOUT = OMNI_RETRANSMIT_TIME * OMNI_RETRANSMIT_COUNT  # Default timeout for receiving responses
 
 # Network Constants

python_omnilogic_local-1.1.0/pyomnilogic_local/api/message.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import logging
+import struct
+import time
+from typing import Self
+
+from pyomnilogic_local.omnitypes import ClientType, MessageType
+
+from .constants import (
+    PROTOCOL_HEADER_FORMAT,
+    PROTOCOL_HEADER_SIZE,
+    PROTOCOL_VERSION,
+)
+from .exceptions import OmniMessageFormatError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class OmniLogicMessage:
+    """A protocol message for communication with the OmniLogic controller.
+
+    Handles serialization and deserialization of message headers and payloads.
+    """
+
+    header_format = PROTOCOL_HEADER_FORMAT
+    id: int
+    type: MessageType
+    payload: bytes
+    client_type: ClientType = ClientType.SIMPLE
+    version: str = PROTOCOL_VERSION
+    timestamp: int
+    reserved_1: int = 0
+    compressed: bool = False
+    reserved_2: int = 0
+
+    def __init__(
+        self,
+        msg_id: int,
+        msg_type: MessageType,
+        payload: str | None = None,
+        version: str = PROTOCOL_VERSION,
+        timestamp: int | None = None,
+    ) -> None:
+        """Initialize a new OmniLogicMessage.
+
+        Args:
+            msg_id: Unique message identifier.
+            msg_type: Type of message being sent.
+            payload: Optional string payload (XML or command body).
+            version: Protocol version string.
+            timestamp: Optional timestamp for the message.
+        """
+        self.id = msg_id
+        self.type = msg_type
+        # If we are speaking the XML API, it seems like we need client_type 0, otherwise we need client_type 1
+        self.client_type = ClientType.XML if payload is not None else ClientType.SIMPLE
+        # The Hayward API terminates it's messages with a null character
+        payload = f"{payload}\x00" if payload is not None else ""
+        self.payload = bytes(payload, "utf-8")
+
+        self.version = version
+        self.timestamp = timestamp if timestamp is not None else int(time.time())
+
+    def __bytes__(self) -> bytes:
+        """Serialize the message to bytes for UDP transmission.
+
+        Returns:
+            Byte representation of the message.
+        """
+        header = struct.pack(
+            self.header_format,
+            self.id,  # Msg id
+            self.timestamp,
+            bytes(self.version, "ascii"),  # version string
+            self.type.value,  # OpID/msgType
+            self.client_type.value,  # Client type
+            0,  # reserved
+            self.compressed,  # compressed
+            0,  # reserved
+        )
+        return header + self.payload
+
+    def __repr__(self) -> str:
+        """Return a string representation of the message for debugging."""
+        if self.compressed or self.type is MessageType.MSP_BLOCKMESSAGE:
+            return f"ID: {self.id}, Type: {self.type.name}, Compressed: {self.compressed}, Client: {self.client_type.name}"
+        return (
+            f"ID: {self.id}, Type: {self.type.name}, Compressed: {self.compressed}, Client: {self.client_type.name}, "
+            f"Body: {self.payload[:-1].decode('utf-8')}"
+        )
+
+    @classmethod
+    def from_bytes(cls, data: bytes) -> Self:
+        """Parse a message from its byte representation.
+
+        Args:
+            data: Byte data received from the controller.
+
+        Returns:
+            OmniLogicMessage instance.
+
+        Raises:
+            OmniMessageFormatException: If the message format is invalid.
+        """
+        if len(data) < PROTOCOL_HEADER_SIZE:
+            msg = f"Message too short: {len(data)} bytes, expected at least {PROTOCOL_HEADER_SIZE}"
+            raise OmniMessageFormatError(msg)
+
+        # split the header and data
+        header = data[:PROTOCOL_HEADER_SIZE]
+        rdata: bytes = data[PROTOCOL_HEADER_SIZE:]
+
+        try:
+            (msg_id, tstamp, vers, msg_type, client_type, res1, compressed, res2) = struct.unpack(cls.header_format, header)
+        except struct.error as exc:
+            msg = f"Failed to unpack message header: {exc}"
+            raise OmniMessageFormatError(msg) from exc
+
+        # Validate message type
+        try:
+            message_type_enum = MessageType(msg_type)
+        except ValueError as exc:
+            msg = f"Unknown message type: {msg_type}: {exc}"
+            raise OmniMessageFormatError(msg) from exc
+
+        # Validate client type
+        try:
+            client_type_enum = ClientType(int(client_type))
+        except ValueError as exc:
+            msg = f"Unknown client type: {client_type}: {exc}"
+            raise OmniMessageFormatError(msg) from exc
+
+        message = cls(msg_id=msg_id, msg_type=message_type_enum, version=vers.decode("utf-8"))
+        message.timestamp = tstamp
+        message.client_type = client_type_enum
+        message.reserved_1 = res1
+        # There are some messages that are ALWAYS compressed although they do not return a 1 in their LeadMessage
+        message.compressed = compressed == 1 or message.type in [MessageType.MSP_TELEMETRY_UPDATE]
+        message.reserved_2 = res2
+        message.payload = rdata
+
+        return message