emerald-hws 0.0.9__py3-none-any.whl → 0.0.11__py3-none-any.whl

emerald_hws/emeraldhws.py

@@ -5,6 +5,7 @@ import logging
 import boto3
 import random
 import threading
+import time
 from awsiot import mqtt5_client_builder, mqtt_connection_builder
 from awscrt import mqtt5, http, auth, io
 
@@ -22,11 +23,13 @@ class EmeraldHWS():
     MQTT_HOST = "a13v32g67itvz9-ats.iot.ap-southeast-2.amazonaws.com"
     COGNITO_IDENTITY_POOL_ID = "ap-southeast-2:f5bbb02c-c00e-4f10-acb3-e7d1b05268e8"
 
-    def __init__(self, email, password, update_callback=None):
+    def __init__(self, email, password, update_callback=None, connection_timeout_minutes=720, health_check_minutes=60):
         """ Initialise the API client
         :param email: The email address for logging into the Emerald app
         :param password: The password for the supplied user account
         :param update_callback: Optional callback function to be called when an update is available
+        :param connection_timeout_minutes: Optional timeout in minutes before reconnecting MQTT (default: 720 minutes/12 hours)
+        :param health_check_minutes: Optional interval in minutes to check for message activity (default: 60 minutes/1 hour)
         """
 
         self.email = email
@@ -35,6 +38,22 @@ class EmeraldHWS():
         self.properties = {}
         self.logger = logging.getLogger()
         self.update_callback = update_callback
+        
+        # Convert minutes to seconds for internal use
+        self.connection_timeout = connection_timeout_minutes * 60.0
+        self.health_check_interval = health_check_minutes * 60.0 if health_check_minutes > 0 else 0
+        self.last_message_time = None
+        self.health_check_timer = None
+        
+        # Ensure reasonable minimum values (e.g., at least 5 minutes for connection timeout)
+        if connection_timeout_minutes < 5 and connection_timeout_minutes != 0:
+            self.logger.warning("emeraldhws: Connection timeout too short, setting to minimum of 5 minutes")
+            self.connection_timeout = 5 * 60.0
+        
+        # Ensure reasonable minimum values for health check (e.g., at least 5 minutes)
+        if 0 < health_check_minutes < 5:
+            self.logger.warning("emeraldhws: Health check interval too short, setting to minimum of 5 minutes")
+            self.health_check_interval = 5 * 60.0
 
     def getLoginToken(self):
         """ Performs an API request to get a token from the API
@@ -87,14 +106,41 @@ class EmeraldHWS():
 
         self.update_callback = update_callback
 
-    def reconnectMQTT(self):
+    def reconnectMQTT(self, reason="scheduled"):
         """ Stops an existing MQTT connection and creates a new one
+        :param reason: Reason for reconnection (scheduled, health_check, etc.)
         """
-
-        self.logger.debug("emeraldhws: awsiot: Tearing down and reconnecting to prevent stale connection")
+        self.logger.info(f"emeraldhws: awsiot: Reconnecting MQTT connection (reason: {reason})")
+        
+        # Store current temperature values for comparison after reconnect
+        temp_values = {}
+        for properties in self.properties:
+            heat_pumps = properties.get('heat_pump', [])
+            for heat_pump in heat_pumps:
+                hws_id = heat_pump['id']
+                if 'last_state' in heat_pump and 'temp_current' in heat_pump['last_state']:
+                    temp_values[hws_id] = heat_pump['last_state']['temp_current']
+        
         self.mqttClient.stop()
         self.connectMQTT()
         self.subscribeAllHWS()
+        
+        # After reconnection, check if temperatures have changed
+        def check_temp_changes():
+            for properties in self.properties:
+                heat_pumps = properties.get('heat_pump', [])
+                for heat_pump in heat_pumps:
+                    hws_id = heat_pump['id']
+                    if (hws_id in temp_values and 
+                        'last_state' in heat_pump and 
+                        'temp_current' in heat_pump['last_state']):
+                        old_temp = temp_values[hws_id]
+                        new_temp = heat_pump['last_state']['temp_current']
+                        if old_temp != new_temp:
+                            self.logger.info(f"emeraldhws: Temperature changed after reconnect for {hws_id}: {old_temp} → {new_temp}")
+        
+        # Check for temperature changes after a short delay to allow for updates
+        threading.Timer(10.0, check_temp_changes).start()
 
     def connectMQTT(self):
         """ Establishes a connection to Amazon IOT core's MQTT service
@@ -131,7 +177,16 @@ class EmeraldHWS():
 
         client.start()
         self.mqttClient = client
-        threading.Timer(43200.0, self.reconnectMQTT).start() # 12 hours
+        
+        # Schedule periodic reconnection using configurable timeout
+        if self.connection_timeout > 0:
+            threading.Timer(self.connection_timeout, self.reconnectMQTT).start()
+        
+        # Start health check timer if enabled
+        if self.health_check_interval > 0:
+            self.health_check_timer = threading.Timer(self.health_check_interval, self.check_connection_health)
+            self.health_check_timer.daemon = True
+            self.health_check_timer.start()
 
     def mqttDecodeUpdate(self, topic, payload):
         """ Attempt to decode a received MQTT message and direct appropriately
@@ -153,6 +208,7 @@ class EmeraldHWS():
         publish_packet = publish_packet_data.publish_packet
         assert isinstance(publish_packet, mqtt5.PublishPacket)
         self.logger.debug("emeraldhws: awsiot: Received message from MQTT topic {}: {}".format(publish_packet.topic, publish_packet.payload))
+        self.last_message_time = time.time()  # Update the last message time
         self.mqttDecodeUpdate(publish_packet.topic, publish_packet.payload)
 
     def on_connection_interrupted(self, connection, error, **kwargs):
@@ -194,6 +250,31 @@ class EmeraldHWS():
         """
         self.logger.debug("emeraldhws: awsiot: attempting to connect")
         return
+        
+    def check_connection_health(self):
+        """ Check if we've received any messages recently, reconnect if not
+        """
+        if self.last_message_time is None:
+            # No messages received yet, don't reconnect
+            self.logger.debug("emeraldhws: awsiot: Health check - No messages received yet")
+        else:
+            current_time = time.time()
+            time_since_last_message = current_time - self.last_message_time
+            minutes_since_last = time_since_last_message / 60.0
+            
+            if time_since_last_message > self.health_check_interval:
+                # This is an INFO level log because it's an important event
+                self.logger.info(f"emeraldhws: awsiot: No messages received for {minutes_since_last:.1f} minutes, reconnecting")
+                self.reconnectMQTT(reason="health_check")
+            else:
+                # This is a DEBUG level log to avoid cluttering logs
+                self.logger.debug(f"emeraldhws: awsiot: Health check - Last message received {minutes_since_last:.1f} minutes ago")
+        
+        # Schedule next health check
+        if self.health_check_interval > 0:
+            self.health_check_timer = threading.Timer(self.health_check_interval, self.check_connection_health)
+            self.health_check_timer.daemon = True
+            self.health_check_timer.start()
 
     def updateHWSState(self, id, key, value):
         """ Updates the specified value for the supplied key in the HWS id specified
@@ -311,6 +392,13 @@ class EmeraldHWS():
         switch_status = self.getFullStatus(id).get("last_state").get("switch")
         return (switch_status == 1 or switch_status == "on")
 
+    def isHeating(self, id):
+        """ Returns true if the specified HWS is currently heating
+        :param id: The UUID of the HWS to query
+        """
+        heating_status = self.getFullStatus(id).get("device_operation_status")
+        return (heating_status == 1)
+
     def currentMode(self, id):
         """ Returns an integer specifying the current mode (0==boost, 1==normal, 2==quiet)
         :param id: The UUID of the HWS to query

emerald_hws-0.0.11.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: emerald_hws
+Version: 0.0.11
+Summary: A package to manipulate and monitor Emerald Heat Pump Hot Water Systems
+Author-email: Ross Williamson <ross@inertia.net.nz>
+Project-URL: Homepage, https://github.com/ross-w/emerald_hws_py
+Project-URL: Bug Tracker, https://github.com/ross-w/emerald_hws_py/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: boto3
+Requires-Dist: awsiotsdk
+Dynamic: license-file
+
+# emerald_hws_py
+Python package for controlling Emerald Heat Pump Hot Water Systems
+
+## Overview
+This package provides an interface to control and monitor Emerald Heat Pump Hot Water Systems through their API and MQTT service.
+
+## Installation
+```bash
+pip install emerald_hws
+```
+
+## Usage
+```python
+from emerald_hws.emeraldhws import EmeraldHWS
+
+# Basic usage with default connection settings
+client = EmeraldHWS("your_email@example.com", "your_password")
+client.connect()
+
+# List all hot water systems
+hws_list = client.listHWS()
+print(f"Found {len(hws_list)} hot water systems")
+
+# Get status of first HWS
+hws_id = hws_list[0]
+status = client.getFullStatus(hws_id)
+print(f"Current temperature: {status['last_state'].get('temp_current')}")
+
+# Turn on the hot water system
+client.turnOn(hws_id)
+```
+
+## Configuration Options
+
+### Connection Timeout
+The module will automatically reconnect to the MQTT service periodically to prevent stale connections. You can configure this timeout:
+
+```python
+# Set connection timeout to 6 hours (360 minutes)
+client = EmeraldHWS("your_email@example.com", "your_password", connection_timeout_minutes=360)
+```
+
+### Health Check
+The module can proactively check for message activity and reconnect if no messages have been received for a specified period:
+
+```python
+# Set health check to check every 30 minutes
+client = EmeraldHWS("your_email@example.com", "your_password", health_check_minutes=30)
+
+# Disable health check
+client = EmeraldHWS("your_email@example.com", "your_password", health_check_minutes=0)
+```
+
+## Callback for Updates
+You can register a callback function to be notified when the state of any hot water system changes:
+
+```python
+def my_callback():
+    print("Hot water system state updated!")
+
+client = EmeraldHWS("your_email@example.com", "your_password", update_callback=my_callback)
+```

emerald_hws-0.0.11.dist-info/RECORD

@@ -0,0 +1,8 @@
+emerald_hws/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+emerald_hws/emeraldhws.py,sha256=h8I-bJUq7RFlveWyzNsahjdt5h7zWPdrbmCX3Q99atg,19019
+emerald_hws/__assets__/SFSRootCAG2.pem,sha256=hw9W0AnYrrlbcWsOewAgIl1ULEsoO57Ylu35dCjWcS4,1424
+emerald_hws-0.0.11.dist-info/licenses/LICENSE,sha256=zzMi56JX7OO-epbXNfe_oFW6sfZHSlO7Yxm0Oh0V014,1072
+emerald_hws-0.0.11.dist-info/METADATA,sha256=mezYMqZpFZ1RnAkWj17mQHl6c4_wqRTduE1aU5_SRZk,2472
+emerald_hws-0.0.11.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+emerald_hws-0.0.11.dist-info/top_level.txt,sha256=ZCiUmnBkDr2n4QVkTet1s_AKiGJjuz3heuCR5w5ZqLY,12
+emerald_hws-0.0.11.dist-info/RECORD,,

{emerald_hws-0.0.9.dist-info → emerald_hws-0.0.11.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.43.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

emerald_hws-0.0.9.dist-info/METADATA

@@ -1,18 +0,0 @@
-Metadata-Version: 2.1
-Name: emerald_hws
-Version: 0.0.9
-Summary: A package to manipulate and monitor Emerald Heat Pump Hot Water Systems
-Author-email: Ross Williamson <ross@inertia.net.nz>
-Project-URL: Homepage, https://github.com/ross-w/emerald_hws_py
-Project-URL: Bug Tracker, https://github.com/ross-w/emerald_hws_py/issues
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: boto3
-Requires-Dist: awsiotsdk
-
-# emerald_hws_py
-Python package for controlling Emerald Heat Pump Hot Water Systems

emerald_hws-0.0.9.dist-info/RECORD

@@ -1,8 +0,0 @@
-emerald_hws/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-emerald_hws/emeraldhws.py,sha256=w3gMffHc9g71r7VeA7710cO-s-DwXcGqTKG0KneC2PI,14088
-emerald_hws/__assets__/SFSRootCAG2.pem,sha256=hw9W0AnYrrlbcWsOewAgIl1ULEsoO57Ylu35dCjWcS4,1424
-emerald_hws-0.0.9.dist-info/LICENSE,sha256=zzMi56JX7OO-epbXNfe_oFW6sfZHSlO7Yxm0Oh0V014,1072
-emerald_hws-0.0.9.dist-info/METADATA,sha256=c2Y0d6CM_n2ve-nESs1k1inHnt9kbhFkqCXdaFxl7zs,688
-emerald_hws-0.0.9.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-emerald_hws-0.0.9.dist-info/top_level.txt,sha256=ZCiUmnBkDr2n4QVkTet1s_AKiGJjuz3heuCR5w5ZqLY,12
-emerald_hws-0.0.9.dist-info/RECORD,,