python-omnilogic-local 0.4.1__py3-none-any.whl → 0.4.2__py3-none-any.whl

pyomnilogic_local/api.py

@@ -38,6 +38,16 @@ class OmniLogicAPI:
         ...
 
     async def async_send_message(self, message_type: MessageType, message: str | None, need_response: bool = False) -> 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.
+
+        Returns:
+            str | None: The response body sent from the Omni if need_response indicates that a response will be sent
+        """
         loop = asyncio.get_running_loop()
         transport, protocol = await loop.create_datagram_endpoint(OmniLogicProtocol, remote_addr=(self.controller_ip, self.controller_port))
 
@@ -53,6 +63,11 @@ class OmniLogicAPI:
         return resp
 
     async def async_get_alarm_list(self) -> str:
+        """Retrieve a list of alarms from the Omni.
+
+        Returns:
+            str: An XML body indicating any alarms that are present
+        """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
         name_element = ET.SubElement(body_element, "Name")
@@ -64,6 +79,14 @@ class OmniLogicAPI:
 
     @to_pydantic(pydantic_type=MSPConfig)
     async def async_get_config(self) -> str:
+        """Retrieve the MSPConfig from the Omni, optionally parse it into a pydantic model.
+
+        Args:
+            raw (bool): Do not parse the response into a Pydantic model, just return the raw XML. Defaults to False.
+
+        Returns:
+            MSPConfig|str: Either a parsed .models.mspconfig.MSPConfig object or a str depending on arg raw
+        """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
         name_element = ET.SubElement(body_element, "Name")
@@ -75,14 +98,14 @@ class OmniLogicAPI:
 
     @to_pydantic(pydantic_type=FilterDiagnostics)
     async def async_get_filter_diagnostics(self, pool_id: int, equipment_id: int) -> str:
-        """async_get_filter_diagnostics handles sending a GetUIFilterDiagnosticInfo XML API call to the Hayward Omni pool controller
+        """Retrieve filter diagnostics from the Omni, optionally parse it into a pydantic model.
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address
             equipment_id (int): Which equipment_id within that Pool to address
 
         Returns:
-            _type_: _description_
+            FilterDiagnostics|str: Either a parsed .models.mspconfig.FilterDiagnostics object or a str depending on arg raw
         """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
@@ -100,10 +123,20 @@ class OmniLogicAPI:
         return await self.async_send_message(MessageType.GET_FILTER_DIAGNOSTIC_INFO, req_body, True)
 
     async def async_get_log_config(self) -> str:
+        """Retrieve the logging configuration from the Omni.
+
+        Returns:
+            str: An XML body describing the logging configuration
+        """
         return await self.async_send_message(MessageType.REQUEST_LOG_CONFIG, None, True)
 
     @to_pydantic(pydantic_type=Telemetry)
     async def async_get_telemetry(self) -> str:
+        """Retrieve the current telemetry data from the Omni, optionally parse it into a pydantic model.
+
+        Returns:
+            Telemetry|str: Either a parsed .models.telemetry.Telemetry object or a str depending on arg raw
+        """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
         name_element = ET.SubElement(body_element, "Name")
@@ -114,7 +147,7 @@ class OmniLogicAPI:
         return await self.async_send_message(MessageType.GET_TELEMETRY, req_body, True)
 
     async def async_set_heater(self, pool_id: int, equipment_id: int, temperature: int, unit: str) -> None:
-        """async_set_heater handles sending a SetUIHeaterCmd XML API call to the Hayward Omni pool controller
+        """Set the temperature for a heater on the Omni
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address
@@ -123,7 +156,7 @@ class OmniLogicAPI:
             unit (str): The temperature unit to use (either F or C)
 
         Returns:
-            _type_: _description_
+            None
         """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
@@ -143,7 +176,7 @@ class OmniLogicAPI:
         return await self.async_send_message(MessageType.SET_HEATER_COMMAND, req_body, False)
 
     async def async_set_solar_heater(self, pool_id: int, equipment_id: int, temperature: int, unit: str) -> None:
-        """async_set_heater handles sending a SetUIHeaterCmd XML API call to the Hayward Omni pool controller
+        """Set the solar set point for a heater on the Omni.
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address
@@ -152,7 +185,7 @@ class OmniLogicAPI:
             unit (str): The temperature unit to use (either F or C)
 
         Returns:
-            _type_: _description_
+            None
         """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
@@ -172,15 +205,15 @@ class OmniLogicAPI:
         return await self.async_send_message(MessageType.SET_SOLAR_SET_POINT_COMMAND, req_body, False)
 
     async def async_set_heater_mode(self, pool_id: int, equipment_id: int, mode: HeaterMode) -> None:
-        """async_set_heater_enable handles sending a SetHeaterEnable XML API call to the Hayward Omni pool controller
+        """Set what mode (Heat/Cool/Auto) the heater should use.
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address
             equipment_id (int): Which equipment_id within that Pool to address
-            enabled (bool, optional): Turn the heater on (True) or off (False)
+            mode (HeaterMode): What mode should the heater operate under
 
         Returns:
-            _type_: _description_
+            None
         """
         body_element = ET.Element("Request", {"xmlns": "http://nextgen.hayward.com/api"})
 
@@ -240,13 +273,14 @@ class OmniLogicAPI:
         days_active: int = 0,
         recurring: bool = False,
     ) -> None:
-        """async_set_equipment handles sending a SetUIEquipmentCmd XML API call to the Hayward Omni pool controller
+        """Control a piece of equipment, turning it on/off or setting a value (E.g.: filter speed), optionally scheduling it.
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address
             equipment_id (int): Which equipment_id within that Pool to address
             is_on (Union[int,bool]): For most equipment items, True/False to turn on/off.
                 For Variable Speed Pumps, you can optionally provide an int from 0-100 to set the speed percentage with 0 being Off.
+                The interpretation of value depends on the piece of equipment being targeted.
             is_countdown_timer (bool, optional): For potential future use, included to be "API complete". Defaults to False.
             startTimeHours (int, optional): For potential future use, included to be "API complete". Defaults to 0.
             startTimeMinutes (int, optional): For potential future use, included to be "API complete". Defaults to 0.
@@ -265,7 +299,7 @@ class OmniLogicAPI:
         parameter.text = str(pool_id)
         parameter = ET.SubElement(parameters_element, "Parameter", name="equipmentId", dataType="int")
         parameter.text = str(equipment_id)
-        parameter = ET.SubElement(parameters_element, "Parameter", name="isOn", dataType="int")
+        parameter = ET.SubElement(parameters_element, "Parameter", name="isOn", dataType="int", alias="Data")
         parameter.text = str(int(is_on))
         parameter = ET.SubElement(parameters_element, "Parameter", name="IsCountDownTimer", dataType="bool")
         parameter.text = str(int(is_countdown_timer))
@@ -287,7 +321,7 @@ class OmniLogicAPI:
         return await self.async_send_message(MessageType.SET_EQUIPMENT, req_body, False)
 
     async def async_set_filter_speed(self, pool_id: int, equipment_id: int, speed: int) -> None:
-        """async_set_filter_speed handles sending a SetUIFilterSpeedCmd XML API call to the Hayward Omni pool controller
+        """Set the speed for a variable speed filter/pump.
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address
@@ -328,7 +362,7 @@ class OmniLogicAPI:
         days_active: int = 0,
         recurring: bool = False,
     ) -> None:
-        """async_set_light_show handles sending a SetStandAloneLightShow XML API call to the Hayward Omni pool controller
+        """Set the desired light show/speed/brightness for a ColorLogic light.
 
         Args:
             pool_id (int): The Pool/BodyOfWater ID that you want to address

pyomnilogic_local/cli.py

@@ -49,14 +49,14 @@ async def async_main() -> None:
     # b2=chr(diags.get_param_by_name("DisplayFWRevisionB2"))
     # b3=chr(diags.get_param_by_name("DisplayFWRevisionB3"))
     # b4=chr(diags.get_param_by_name("DisplayFWRevisionB4"))
-    # # b5 and b6 are whitespace and a null terminator
-    # # b5=chr(diags.get_param_by_name("DisplayFWRevisionB5"))
-    # # b6=chr(diags.get_param_by_name("DisplayFWRevisionB6"))
+    # b5 and b6 are whitespace and a null terminator
+    # b5=chr(diags.get_param_by_name("DisplayFWRevisionB5"))
+    # b6=chr(diags.get_param_by_name("DisplayFWRevisionB6"))
     # print(f"{b1}{b2}.{b3}.{b4}")
-    # # Decode the filter power consumption (don't do this, it's returned already decoded in the telemetry)
+    # Decode the filter power consumption (don't do this, it's returned already decoded in the telemetry)
     # p1=diags.get_param_by_name("PowerMSB")
     # p2=diags.get_param_by_name("PowerLSB")
-    # # The f-string below converts the bytes to hex and displays them.  Just get this value from the telemetry, it's easier
+    # The f-string below converts the bytes to hex and displays them.  Just get this value from the telemetry, it's easier
     # print(f"{p1:x}{p2:x}")
 
     # Fetch logging configuration

pyomnilogic_local/models/mspconfig.py

@@ -140,7 +140,7 @@ class MSPVirtualHeater(OmniBase):
 class MSPColorLogicLight(OmniBase):
     omni_type: OmniType = OmniType.CL_LIGHT
     type: ColorLogicLightType | str = Field(alias="Type")
-    v2_active: Literal["yes", "no"] = Field(alias="V2-Active")
+    v2_active: Literal["yes", "no"] | None = Field(alias="V2-Active")
 
 
 class MSPBoW(OmniBase):

{python_omnilogic_local-0.4.1.dist-info → python_omnilogic_local-0.4.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-omnilogic-local
-Version: 0.4.1
+Version: 0.4.2
 Summary: A library for local control of Hayward OmniHub/OmniLogic pool controllers using their local API
 Home-page: https://github.com/cryptk/python-omnilogic-local
 License: Apache-2.0

{python_omnilogic_local-0.4.1.dist-info → python_omnilogic_local-0.4.2.dist-info}/RECORD

@@ -1,17 +1,17 @@
 pyomnilogic_local/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pyomnilogic_local/api.py,sha256=UJI4aPLVkcQv8rJsM4i1Tn7TZiJCcAGKdl42V8Fkj1I,20177
-pyomnilogic_local/cli.py,sha256=FixqNzACGS0geow_WLlyE5Ei6iia0CRZpZolbV1MS5M,3931
+pyomnilogic_local/api.py,sha256=j65JAwp6p2Z4jUt2-0wG2-EYiO_IVZrnuB4G29Jj1qg,21535
+pyomnilogic_local/cli.py,sha256=jHAhN_VfjgEVbXlvLsPdgNSab-jY8XntpXoek0I1Vfc,3921
 pyomnilogic_local/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 pyomnilogic_local/models/const.py,sha256=j4HSiPJW5If296yJ-AiIsBI9EdlckF4QkVFIpTLb5C4,51
 pyomnilogic_local/models/filter_diagnostics.py,sha256=N4YWl9aEMKcWZ4QOlqR68WV9H1WjTtxjs0wHrNojAaU,1532
 pyomnilogic_local/models/leadmessage.py,sha256=9r6PbIHHzD0tyeKiFUve3WLcjS8uL2Gj6r_96X7l5H8,407
-pyomnilogic_local/models/mspconfig.py,sha256=n968rd7DOA6Ltxa9t30eb_6TyWELzj-j4dUZbaMTR3A,7864
+pyomnilogic_local/models/mspconfig.py,sha256=fpEAVKoRijZHV_KxdCCnVxNvdhekvkCpiggd8CiOpU8,7871
 pyomnilogic_local/models/telemetry.py,sha256=jqvNQcBxTsDrPfzSYuev5y4ujVVfGKB7319D_WEX8Tg,9619
 pyomnilogic_local/models/util.py,sha256=3Qch98NOl5eO-KIOUBnE9ar86MlzbZ0g2LRApMgj-co,1476
 pyomnilogic_local/protocol.py,sha256=oO05ZPXJWCi3NzJJqfOqegMkkntQbhbDWkOjsPcleLw,9040
 pyomnilogic_local/types.py,sha256=DcrOtDcPH6i0fsdULcFIAGqr2-YL_GzICJ-4KErTYj0,6304
 pyomnilogic_local/util.py,sha256=agbRBKnecrYycC9iUmo1aJDjbVg9VxHyq4QY0D8-bfA,359
-python_omnilogic_local-0.4.1.dist-info/METADATA,sha256=d8zKcti6Fw2JET5_YtETHH7ZzSGWv26YRUJwU16_lqQ,2727
-python_omnilogic_local-0.4.1.dist-info/WHEEL,sha256=WGfLGfLX43Ei_YORXSnT54hxFygu34kMpcQdmgmEwCQ,88
-python_omnilogic_local-0.4.1.dist-info/entry_points.txt,sha256=PUvdumqSijeB0dHH_s5oE2TnWtPWdJSNpSOsn8yTtOo,56
-python_omnilogic_local-0.4.1.dist-info/RECORD,,
+python_omnilogic_local-0.4.2.dist-info/METADATA,sha256=df-i2dL7x9NAHXs3myeD-VdqfxdvxmKH47Jo8TwuM_E,2727
+python_omnilogic_local-0.4.2.dist-info/WHEEL,sha256=Zb28QaM1gQi8f4VCBhsUklF61CTlNYfs9YAZn-TOGFk,88
+python_omnilogic_local-0.4.2.dist-info/entry_points.txt,sha256=PUvdumqSijeB0dHH_s5oE2TnWtPWdJSNpSOsn8yTtOo,56
+python_omnilogic_local-0.4.2.dist-info/RECORD,,

{python_omnilogic_local-0.4.1.dist-info → python_omnilogic_local-0.4.2.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 1.6.0
+Generator: poetry-core 1.6.1
 Root-Is-Purelib: true
 Tag: py3-none-any