emerald-hws 0.0.10__py3-none-any.whl → 0.0.12__py3-none-any.whl

emerald_hws/__init__.py

@@ -1 +1,3 @@
+from .emeraldhws import EmeraldHWS
 
+__all__ = ["EmeraldHWS"]

emerald_hws/emeraldhws.py

@@ -1,12 +1,14 @@
 import json
-import requests
-import os
 import logging
-import boto3
+import os
 import random
 import threading
-from awsiot import mqtt5_client_builder, mqtt_connection_builder
-from awscrt import mqtt5, http, auth, io
+import time
+
+import boto3
+import requests
+from awscrt import mqtt5, auth, io
+from awsiot import mqtt5_client_builder
 
 
 class EmeraldHWS():
@@ -22,11 +24,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 +39,27 @@ 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
+        
+        # Connection state tracking
+        self.connection_state = "initial"  # possible states: initial, connected, failed
+        self.consecutive_failures = 0
+        self.max_backoff_seconds = 60  # Maximum backoff of 1 minute
+        
+        # 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,20 +112,48 @@ 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
         """
 
-        cert_path = os.path.join(os.path.dirname(__file__), '__assets__', 'SFSRootCAG2.pem')
+        # Certificate path is available but not currently used in the connection
+        # os.path.join(os.path.dirname(__file__), '__assets__', 'SFSRootCAG2.pem')
         identityPoolID = self.COGNITO_IDENTITY_POOL_ID
         region = self.MQTT_HOST.split('.')[2]
         cognito_endpoint = "cognito-identity." + region + ".amazonaws.com"
@@ -131,7 +184,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,12 +215,15 @@ 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):
         """ Log error when MQTT is interrupted
         """
-        self.logger.debug("emeraldhws: awsiot: Connection interrupted. error: {}".format(error))
+        error_code = getattr(error, 'code', 'unknown')
+        error_name = getattr(error, 'name', 'unknown')
+        self.logger.info(f"emeraldhws: awsiot: Connection interrupted. Error: {error_name} (code: {error_code}), Message: {error}")
 
     def on_connection_resumed(self, connection, return_code, session_present, **kwargs):
         """ Log message when MQTT is resumed
@@ -169,12 +234,35 @@ class EmeraldHWS():
         """ Log message when connection succeeded
         """
         self.logger.debug("emeraldhws: awsiot: connection succeeded")
+        # Reset failure counter and update connection state
+        self.consecutive_failures = 0
+        self.connection_state = "connected"
         return
 
     def on_lifecycle_connection_failure(self, lifecycle_connection_failure: mqtt5.LifecycleConnectFailureData):
         """ Log message when connection failed
         """
-        self.logger.debug("emeraldhws: awsiot: connection failed")
+        error = lifecycle_connection_failure.error
+        error_code = getattr(error, 'code', 'unknown')
+        error_name = getattr(error, 'name', 'unknown')
+        error_message = str(error)
+        
+        # Update connection state and increment failure counter
+        self.connection_state = "failed"
+        self.consecutive_failures += 1
+        
+        # Log at INFO level since this is important for troubleshooting
+        self.logger.info(f"emeraldhws: awsiot: connection failed - Error: {error_name} (code: {error_code}), Message: {error_message}")
+        
+        # If there's a CONNACK packet available, log its details too
+        if hasattr(lifecycle_connection_failure, 'connack_packet') and lifecycle_connection_failure.connack_packet:
+            connack = lifecycle_connection_failure.connack_packet
+            reason_code = getattr(connack, 'reason_code', 'unknown')
+            reason_string = getattr(connack, 'reason_string', '')
+            if reason_string:
+                self.logger.info(f"emeraldhws: awsiot: MQTT CONNACK reason: {reason_code} - {reason_string}")
+            else:
+                self.logger.info(f"emeraldhws: awsiot: MQTT CONNACK reason code: {reason_code}")
         return
 
     def on_lifecycle_stopped(self, lifecycle_stopped_data: mqtt5.LifecycleStoppedData):
@@ -186,14 +274,56 @@ class EmeraldHWS():
     def on_lifecycle_disconnection(self, lifecycle_disconnect_data: mqtt5.LifecycleDisconnectData):
         """ Log message when disconnected
         """
-        self.logger.debug("emeraldhws: awsiot: disconnected")
+        # Extract disconnect reason if available
+        reason = "unknown reason"
+        if hasattr(lifecycle_disconnect_data, 'disconnect_packet') and lifecycle_disconnect_data.disconnect_packet:
+            reason_code = getattr(lifecycle_disconnect_data.disconnect_packet, 'reason_code', 'unknown')
+            reason_string = getattr(lifecycle_disconnect_data.disconnect_packet, 'reason_string', '')
+            reason = f"reason code: {reason_code}" + (f" - {reason_string}" if reason_string else "")
+        
+        self.logger.info(f"emeraldhws: awsiot: disconnected - {reason}")
         return
 
     def on_lifecycle_attempting_connect(self, lifecycle_attempting_connect_data: mqtt5.LifecycleAttemptingConnectData):
         """ Log message when attempting connect
         """
-        self.logger.debug("emeraldhws: awsiot: attempting to connect")
+        # Include endpoint information if available
+        endpoint = getattr(lifecycle_attempting_connect_data, 'endpoint', 'unknown')
+        self.logger.debug(f"emeraldhws: awsiot: attempting to connect to {endpoint}")
         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")
+                
+                # If we're in a failed state, apply exponential backoff
+                if self.connection_state == "failed" and self.consecutive_failures > 0:
+                    # Calculate backoff time with exponential increase, capped at max_backoff_seconds
+                    backoff_seconds = min(2 ** (self.consecutive_failures - 1), self.max_backoff_seconds)
+                    self.logger.info(f"emeraldhws: awsiot: Connection in failed state, applying backoff of {backoff_seconds} seconds before retry (attempt {self.consecutive_failures})")
+                    time.sleep(backoff_seconds)
+                
+                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
@@ -207,7 +337,7 @@ class EmeraldHWS():
             for heat_pump in heat_pumps:
                 if heat_pump['id'] == id:
                     heat_pump['last_state'][key] = value
-        if self.update_callback != None:
+        if self.update_callback is not None:
             self.update_callback()
 
     def subscribeForUpdates(self, id):
@@ -224,7 +354,8 @@ class EmeraldHWS():
                         topic_filter=mqtt_topic,
                         qos=mqtt5.QoS.AT_LEAST_ONCE)]))
 
-        suback = subscribe_future.result(20)
+        # Wait for subscription to complete
+        subscribe_future.result(20)
 
     def getFullStatus(self, id):
         """ Returns a dict with the full status of the specified HWS

emerald_hws-0.0.12.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: emerald_hws
+Version: 0.0.12
+Summary: A package to manipulate and monitor Emerald Heat Pump Hot Water Systems
+Author-email: Ross Williamson <ross@inertia.net.nz>
+License-Expression: MIT
+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: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: boto3<2.0.0,>=1.40.0
+Requires-Dist: awsiotsdk<2.0.0,>=1.24.0
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: ruff<1.0.0,>=0.12.0; extra == "dev"
+
+# 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.12.dist-info/RECORD

@@ -0,0 +1,7 @@
+emerald_hws/__init__.py,sha256=uukjQ-kiPYKWvGT3jLL6kJA1DCNAxtw4HlLKqPSypXs,61
+emerald_hws/emeraldhws.py,sha256=wfsZXOR_MlL3FEPCrTz3eU2fhY1xFCW9ztODI50hL04,22092
+emerald_hws/__assets__/SFSRootCAG2.pem,sha256=hw9W0AnYrrlbcWsOewAgIl1ULEsoO57Ylu35dCjWcS4,1424
+emerald_hws-0.0.12.dist-info/METADATA,sha256=cKfX2Ye1-KtmUzZFm8o91gazAZ9NNO3HIO61QD9VJv0,2534
+emerald_hws-0.0.12.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+emerald_hws-0.0.12.dist-info/top_level.txt,sha256=ZCiUmnBkDr2n4QVkTet1s_AKiGJjuz3heuCR5w5ZqLY,12
+emerald_hws-0.0.12.dist-info/RECORD,,

{emerald_hws-0.0.10.dist-info → emerald_hws-0.0.12.dist-info}/WHEEL

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

emerald_hws-0.0.10.dist-info/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2024 Ross Williamson
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

emerald_hws-0.0.10.dist-info/METADATA

@@ -1,18 +0,0 @@
-Metadata-Version: 2.2
-Name: emerald_hws
-Version: 0.0.10
-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.10.dist-info/RECORD

@@ -1,8 +0,0 @@
-emerald_hws/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-emerald_hws/emeraldhws.py,sha256=aAH2x5f9c5sw2NBg0BSbPJ0iuzNdLaXWvWMK7h2hYeY,14361
-emerald_hws/__assets__/SFSRootCAG2.pem,sha256=hw9W0AnYrrlbcWsOewAgIl1ULEsoO57Ylu35dCjWcS4,1424
-emerald_hws-0.0.10.dist-info/LICENSE,sha256=zzMi56JX7OO-epbXNfe_oFW6sfZHSlO7Yxm0Oh0V014,1072
-emerald_hws-0.0.10.dist-info/METADATA,sha256=8TYWMzh7CgGm7WBoOAdUwNyKzv0k2--LGRti97PM7DU,689
-emerald_hws-0.0.10.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
-emerald_hws-0.0.10.dist-info/top_level.txt,sha256=ZCiUmnBkDr2n4QVkTet1s_AKiGJjuz3heuCR5w5ZqLY,12
-emerald_hws-0.0.10.dist-info/RECORD,,