python-omnilogic-local 0.4.0__tar.gz → 0.4.2__tar.gz

{python_omnilogic_local-0.4.0 → python_omnilogic_local-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: python-omnilogic-local
-Version: 0.4.0
+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.0 → python_omnilogic_local-0.4.2}/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

{python_omnilogic_local-0.4.0 → python_omnilogic_local-0.4.2}/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

{python_omnilogic_local-0.4.0 → python_omnilogic_local-0.4.2}/pyomnilogic_local/models/mspconfig.py

@@ -67,13 +67,13 @@ class MSPSystem(BaseModel):
 
 class MSPSensor(OmniBase):
     omni_type: OmniType = OmniType.SENSOR
-    type: SensorType = Field(alias="Type")
-    units: SensorUnits = Field(alias="Units")
+    type: SensorType | str = Field(alias="Type")
+    units: SensorUnits | str = Field(alias="Units")
 
 
 class MSPFilter(OmniBase):
     omni_type: OmniType = OmniType.FILTER
-    type: FilterType = Field(alias="Filter-Type")
+    type: FilterType | str = Field(alias="Filter-Type")
     max_percent: int = Field(alias="Max-Pump-Speed")
     min_percent: int = Field(alias="Min-Pump-Speed")
     max_rpm: int = Field(alias="Max-Pump-RPM")
@@ -87,8 +87,8 @@ class MSPFilter(OmniBase):
 
 class MSPPump(OmniBase):
     omni_type: OmniType = OmniType.PUMP
-    type: PumpType = Field(alias="Type")
-    function: PumpFunction = Field(alias="Function")
+    type: PumpType | str = Field(alias="Type")
+    function: PumpFunction | str = Field(alias="Function")
     max_percent: int = Field(alias="Max-Pump-Speed")
     min_percent: int = Field(alias="Min-Pump-Speed")
     max_rpm: int = Field(alias="Max-Pump-RPM")
@@ -102,14 +102,14 @@ class MSPPump(OmniBase):
 
 class MSPRelay(OmniBase):
     omni_type: OmniType = OmniType.RELAY
-    type: RelayType = Field(alias="Type")
-    function: RelayFunction = Field(alias="Function")
+    type: RelayType | str = Field(alias="Type")
+    function: RelayFunction | str = Field(alias="Function")
 
 
 class MSPHeaterEquip(OmniBase):
     omni_type: OmniType = OmniType.HEATER_EQUIP
     type: Literal["PET_HEATER"] = Field(alias="Type")
-    heater_type: HeaterType = Field(alias="Heater-Type")
+    heater_type: HeaterType | str = Field(alias="Heater-Type")
     enabled: Literal["yes", "no"] = Field(alias="Enabled")
     min_filter_speed: int = Field(alias="Min-Speed-For-Operation")
     sensor_id: int = Field(alias="Sensor-System-Id")
@@ -139,15 +139,15 @@ class MSPVirtualHeater(OmniBase):
 
 class MSPColorLogicLight(OmniBase):
     omni_type: OmniType = OmniType.CL_LIGHT
-    type: ColorLogicLightType = Field(alias="Type")
-    v2_active: Literal["yes", "no"] = Field(alias="V2-Active")
+    type: ColorLogicLightType | str = Field(alias="Type")
+    v2_active: Literal["yes", "no"] | None = Field(alias="V2-Active")
 
 
 class MSPBoW(OmniBase):
     _sub_devices = {"filter", "relay", "heater", "sensor", "colorlogic_light"}
 
     omni_type: OmniType = OmniType.BOW
-    type: BodyOfWaterType = Field(alias="Type")
+    type: BodyOfWaterType | str = Field(alias="Type")
     filter: list[MSPFilter] | None = Field(alias="Filter")
     relay: list[MSPRelay] | None = Field(alias="Relay")
     heater: MSPVirtualHeater | None = Field(alias="Heater")

{python_omnilogic_local-0.4.0 → python_omnilogic_local-0.4.2}/pyomnilogic_local/models/telemetry.py

@@ -45,7 +45,7 @@ class TelemetryBackyard(BaseModel):
     system_id: int = Field(alias="@systemId")
     status_version: int = Field(alias="@statusVersion")
     air_temp: int = Field(alias="@airTemp")
-    state: BackyardState = Field(alias="@state")
+    state: BackyardState | int = Field(alias="@state")
     config_checksum: int = Field(alias="@ConfigChksum")
     msp_version: str = Field(alias="@mspVersion")
 
@@ -68,27 +68,27 @@ class TelemetryChlorinator(BaseModel):
     sc_mode: int = Field(alias="@scMode")
     operating_state: int = Field(alias="@operatingState")
     timed_percent: int = Field(alias="@Timed-Percent")
-    operating_mode: ChlorinatorOperatingMode = Field(alias="@operatingMode")
+    operating_mode: ChlorinatorOperatingMode | int = Field(alias="@operatingMode")
     enable: bool = Field(alias="@enable")
 
 
 class TelemetryColorLogicLight(BaseModel):
     omni_type: OmniType = OmniType.CL_LIGHT
     system_id: int = Field(alias="@systemId")
-    state: ColorLogicPowerState = Field(alias="@lightState")
-    show: ColorLogicShow = Field(alias="@currentShow")
-    speed: ColorLogicSpeed = Field(alias="@speed")
-    brightness: ColorLogicBrightness = Field(alias="@brightness")
+    state: ColorLogicPowerState | int = Field(alias="@lightState")
+    show: ColorLogicShow | int = Field(alias="@currentShow")
+    speed: ColorLogicSpeed | int = Field(alias="@speed")
+    brightness: ColorLogicBrightness | int = Field(alias="@brightness")
     special_effect: int = Field(alias="@specialEffect")
 
 
 class TelemetryFilter(BaseModel):
     omni_type: OmniType = OmniType.FILTER
     system_id: int = Field(alias="@systemId")
-    state: FilterState = Field(alias="@filterState")
+    state: FilterState | int = Field(alias="@filterState")
     speed: int = Field(alias="@filterSpeed")
-    valve_position: FilterValvePosition = Field(alias="@valvePosition")
-    why_on: FilterWhyOn = Field(alias="@whyFilterIsOn")
+    valve_position: FilterValvePosition | int = Field(alias="@valvePosition")
+    why_on: FilterWhyOn | int = Field(alias="@whyFilterIsOn")
     reported_speed: int = Field(alias="@reportedFilterSpeed")
     power: int = Field(alias="@power")
     last_speed: int = Field(alias="@lastSpeed")
@@ -103,7 +103,7 @@ class TelemetryGroup(BaseModel):
 class TelemetryHeater(BaseModel):
     omni_type: OmniType = OmniType.HEATER
     system_id: int = Field(alias="@systemId")
-    state: HeaterState = Field(alias="@heaterState")
+    state: HeaterState | int = Field(alias="@heaterState")
     temp: int = Field(alias="@temp")
     enabled: bool = Field(alias="@enable")
     priority: int = Field(alias="@priority")
@@ -113,7 +113,7 @@ class TelemetryHeater(BaseModel):
 class TelemetryPump(BaseModel):
     omni_type: OmniType = OmniType.PUMP
     system_id: int = Field(alias="@systemId")
-    state: PumpState = Field(alias="@pumpState")
+    state: PumpState | int = Field(alias="@pumpState")
     speed: int = Field(alias="@pummpSpeed")
     last_speed: int = Field(alias="@lastSpeed")
     why_on: int = Field(alias="@whyOn")
@@ -122,14 +122,14 @@ class TelemetryPump(BaseModel):
 class TelemetryRelay(BaseModel):
     omni_type: OmniType = OmniType.RELAY
     system_id: int = Field(alias="@systemId")
-    state: RelayState = Field(alias="@relayState")
+    state: RelayState | int = Field(alias="@relayState")
     why_on: int = Field(alias="@whyOn")
 
 
 class TelemetryValveActuator(BaseModel):
     omni_type: OmniType = OmniType.VALVE_ACTUATOR
     system_id: int = Field(alias="@systemId")
-    state: ValveActuatorState = Field(alias="@valveActuatorState")
+    state: ValveActuatorState | int = Field(alias="@valveActuatorState")
     why_on: int = Field(alias="@whyOn")
 
 
@@ -139,7 +139,7 @@ class TelemetryVirtualHeater(BaseModel):
     current_set_point: int = Field(alias="@Current-Set-Point")
     enabled: bool = Field(alias="@enable")
     solar_set_point: int = Field(alias="@SolarSetPoint")
-    mode: HeaterMode = Field(alias="@Mode")
+    mode: HeaterMode | int = Field(alias="@Mode")
     silent_mode: int = Field(alias="@SilentMode")
     why_on: int = Field(alias="@whyHeaterIsOn")
 

{python_omnilogic_local-0.4.0 → python_omnilogic_local-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "python-omnilogic-local"
-version = "0.4.0"
+version = "0.4.2"
 description = "A library for local control of Hayward OmniHub/OmniLogic pool controllers using their local API"
 authors = ["cryptk <cryptk@users.noreply.github.com>", "djtimca", "garionphx"]
 license = "Apache-2.0"