emerald-hws 0.0.10__tar.gz → 0.0.12__tar.gz

emerald_hws-0.0.12/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

emerald_hws-0.0.12/.github/workflows/lint.yml

@@ -0,0 +1,30 @@
+name: "Lint"
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+  workflow_call: # Allow this workflow to be called by other workflows
+
+jobs:
+  ruff:
+    name: "Ruff"
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout the repository"
+        uses: "actions/checkout@v4.2.2"
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v5.6.0
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: "Install requirements"
+        run: python3 -m pip install -e ".[dev]"
+
+      - name: "Run"
+        run: python3 -m ruff check .

emerald_hws-0.0.12/.github/workflows/publish.yml

@@ -0,0 +1,222 @@
+name: "Publish to PyPI"
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: "Publish to Test PyPI instead of PyPI"
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  # Security validation (defense in depth - primary security is OIDC)
+  security-check:
+    name: "Security Validation"
+    runs-on: ubuntu-latest
+    outputs:
+      is-authorized: ${{ steps.check.outputs.authorized }}
+    steps:
+      - name: "Validate repository and context"
+        id: check
+        run: |
+          echo "🔒 Security validation:"
+          echo "Repository: ${{ github.repository }}"
+          echo "Actor: ${{ github.actor }}"
+          echo "Event: ${{ github.event_name }}"
+          echo "Ref: ${{ github.ref }}"
+          echo ""
+
+          # Check repository (defense in depth - OIDC is primary security)
+          if [[ "${{ github.repository }}" == "ross-w/emerald_hws_py" ]]; then
+            echo "✅ Repository validation passed"
+            echo "authorized=true" >> $GITHUB_OUTPUT
+          else
+            echo "❌ Repository validation failed"
+            echo "Expected: ross-w/emerald_hws_py"
+            echo "Actual: ${{ github.repository }}"
+            echo "authorized=false" >> $GITHUB_OUTPUT
+            echo ""
+            echo "ℹ️  Note: Even if this check was bypassed, PyPI trusted publishing"
+            echo "   would reject the upload due to OIDC repository mismatch."
+          fi
+
+  lint:
+    name: "Lint Check"
+    needs: security-check
+    if: needs.security-check.outputs.is-authorized == 'true'
+    uses: ./.github/workflows/lint.yml
+
+  smoke-test:
+    name: "Smoke Test"
+    needs: security-check
+    if: needs.security-check.outputs.is-authorized == 'true'
+    uses: ./.github/workflows/smoke-test.yml
+
+  # Additional publish-specific validation
+  version-check:
+    name: "Version Validation"
+    needs: security-check
+    if: needs.security-check.outputs.is-authorized == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout repository"
+        uses: "actions/checkout@v4"
+        with:
+          # Fetch full history for setuptools-scm version detection
+          fetch-depth: 0
+
+      - name: "Set up Python"
+        uses: "actions/setup-python@v5"
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: "Install package"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e .
+
+      - name: "Verify dynamic versioning for release"
+        run: |
+          python -c "
+          import emerald_hws
+          from importlib.metadata import version
+          pkg_version = version('emerald_hws')
+          print(f'📦 Detected version: {pkg_version}')
+
+          # For releases, ensure we have a proper version
+          if '${{ github.event_name }}' == 'release':
+              if 'dev' in pkg_version or '+' in pkg_version:
+                  print('❌ Development version detected for release')
+                  print('   This suggests the release tag may not be properly formatted')
+                  exit(1)
+              else:
+                  print('✅ Release version detected')
+          else:
+              print('ℹ️  Manual trigger - version validation skipped')
+          "
+
+  # Build package
+  build:
+    name: "Build Package"
+    needs: [security-check, lint, smoke-test, version-check]
+    if: needs.security-check.outputs.is-authorized == 'true'
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Checkout repository"
+        uses: "actions/checkout@v4"
+        with:
+          fetch-depth: 0
+
+      - name: "Set up Python"
+        uses: "actions/setup-python@v5"
+        with:
+          python-version: "3.11"
+          cache: "pip"
+
+      - name: "Install build tools"
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "packaging>=24.2"
+          python -m pip install build twine
+
+      - name: "Build distribution packages"
+        run: python -m build
+
+      - name: "Validate package"
+        run: |
+          echo "📦 Built packages:"
+          ls -la dist/
+          echo ""
+          echo "🔍 Package validation:"
+          python -m twine check dist/*
+          echo ""
+          echo "📋 Package metadata:"
+          python -m pip install pkginfo
+          python -c "
+          import pkginfo
+          import glob
+
+          for wheel in glob.glob('dist/*.whl'):
+              info = pkginfo.get_metadata(wheel)
+              print(f'Name: {info.name}')
+              print(f'Version: {info.version}')
+              print(f'Author: {info.author}')
+              break
+          "
+
+      - name: "Upload build artifacts"
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-packages
+          path: dist/
+          retention-days: 7
+
+  # Publish using PyPI Trusted Publishing (OIDC)
+  publish:
+    name: "Publish to PyPI"
+    needs: [security-check, lint, smoke-test, version-check, build]
+    if: needs.security-check.outputs.is-authorized == 'true'
+    runs-on: ubuntu-latest
+
+    # CRITICAL SECURITY: This environment provides additional protection
+    # beyond OIDC trusted publishing. Forks cannot access this environment.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/emerald-hws
+
+    # CRITICAL SECURITY: These permissions enable OIDC trusted publishing
+    # The id-token is cryptographically tied to this specific repository
+    permissions:
+      id-token: write # Required for PyPI trusted publishing
+      contents: read # Required to download artifacts
+
+    steps:
+      - name: "Download build artifacts"
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-packages
+          path: dist/
+
+      - name: "Final security and package validation"
+        run: |
+          echo "🔒 Final security context:"
+          echo "Repository: ${{ github.repository }}"
+          echo "Environment: pypi"
+          echo "OIDC Token: Will be generated for this specific repository"
+          echo ""
+          echo "📦 Final package validation:"
+          ls -la dist/
+          python -m pip install "packaging>=24.2"
+          python -m pip install twine
+          python -m twine check dist/*
+
+      - name: "Publish to Test PyPI"
+        if: github.event.inputs.test_pypi == 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          print-hash: true
+
+      - name: "Publish to PyPI"
+        if: github.event.inputs.test_pypi != 'true'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true
+
+      - name: "Publication summary"
+        run: |
+          if [[ "${{ github.event.inputs.test_pypi }}" == "true" ]]; then
+            echo "✅ Package successfully published to Test PyPI"
+            echo "🔗 View at: https://test.pypi.org/project/emerald-hws/"
+          else
+            echo "✅ Package successfully published to PyPI"
+            echo "🔗 View at: https://pypi.org/project/emerald-hws/"
+          fi
+          echo "📦 Published from release: ${{ github.ref_name }}"
+          echo "🔒 Security: Verified via PyPI trusted publishing (OIDC)"

emerald_hws-0.0.12/.github/workflows/smoke-test.yml

@@ -0,0 +1,34 @@
+name: "Smoke Test"
+
+on:
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+  workflow_call: # Allow this workflow to be called by other workflows
+
+jobs:
+  smoke-test:
+    name: "Import Test"
+    runs-on: "ubuntu-latest"
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: "Checkout repository"
+        uses: "actions/checkout@v4"
+
+      - name: "Set up Python ${{ matrix.python-version }}"
+        uses: "actions/setup-python@v5"
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: "Install package"
+        run: python -m pip install -e .
+
+      - name: "Test import"
+        run: python -c "import emerald_hws; print('✓ emerald_hws imported successfully')"

emerald_hws-0.0.12/.gitignore

@@ -0,0 +1,160 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

emerald_hws-0.0.12/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,62 @@
+# 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/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["setuptools>=70.0", "setuptools-scm>=8.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "emerald_hws"
+dynamic = ["version"]
+license = "MIT"
+dependencies = [
+    "boto3>=1.40.0,<2.0.0",
+    "awsiotsdk>=1.24.0,<2.0.0",
+    "requests>=2.25.0"
+]
+authors = [{ name = "Ross Williamson", email = "ross@inertia.net.nz" }]
+description = "A package to manipulate and monitor Emerald Heat Pump Hot Water Systems"
+readme = "README.md"
+requires-python = ">=3.7"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.12.0,<1.0.0"
+]
+
+[tool.setuptools]
+include-package-data = true
+license-files = []
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.*"]
+
+[tool.setuptools_scm]
+# Use default version scheme for better compatibility
+
+[project.urls]
+"Homepage" = "https://github.com/ross-w/emerald_hws_py"
+"Bug Tracker" = "https://github.com/ross-w/emerald_hws_py/issues"
+
+[tool.ruff]
+# Exclude a variety of commonly ignored directories.
+exclude = [
+    ".git",
+    ".ruff_cache",
+    "__pypackages__",
+    "build",
+    "dist",
+]
+line-length = 88
+
+[tool.ruff.lint]
+# Enable flake8-bugbear (`B`) rules.
+select = ["E", "F", "B"]
+# Allow unused variables when underscore-prefixed.
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+# Ignore specific rules
+ignore = [
+    "E501",  # Line too long (handled by formatter)
+    "F401",  # Unused imports (some imports are used in commented code)
+]

emerald_hws-0.0.12/requirements.txt

@@ -0,0 +1,8 @@
+# Dependencies are now managed in pyproject.toml
+# Install with: pip install -e .
+# For development: pip install -e ".[dev]"
+#
+# This file is kept for compatibility but pyproject.toml is the source of truth
+boto3>=1.40.0,<2.0.0
+awsiotsdk>=1.24.0,<2.0.0
+requests>=2.25.0

emerald_hws-0.0.12/src/emerald_hws/__init__.py

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

{emerald_hws-0.0.10 → emerald_hws-0.0.12}/src/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/src/emerald_hws.egg-info/PKG-INFO

@@ -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.10 → emerald_hws-0.0.12}/src/emerald_hws.egg-info/SOURCES.txt

@@ -1,6 +1,12 @@
+.gitignore
 LICENSE
 README.md
 pyproject.toml
+requirements.txt
+.github/dependabot.yml
+.github/workflows/lint.yml
+.github/workflows/publish.yml
+.github/workflows/smoke-test.yml
 src/emerald_hws/__init__.py
 src/emerald_hws/emeraldhws.py
 src/emerald_hws.egg-info/PKG-INFO

emerald_hws-0.0.12/src/emerald_hws.egg-info/requires.txt

@@ -0,0 +1,6 @@
+boto3<2.0.0,>=1.40.0
+awsiotsdk<2.0.0,>=1.24.0
+requests>=2.25.0
+
+[dev]
+ruff<1.0.0,>=0.12.0

emerald_hws-0.0.10/PKG-INFO

@@ -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/README.md

@@ -1,2 +0,0 @@
-# emerald_hws_py
-Python package for controlling Emerald Heat Pump Hot Water Systems

emerald_hws-0.0.10/pyproject.toml

@@ -1,30 +0,0 @@
-[build-system]
-requires = ["setuptools>=61.0"]
-build-backend = "setuptools.build_meta"
-
-[project]
-name = "emerald_hws"
-version = "0.0.10"
-dependencies = ["boto3", "awsiotsdk"]
-authors = [{ name = "Ross Williamson", email = "ross@inertia.net.nz" }]
-description = "A package to manipulate and monitor Emerald Heat Pump Hot Water Systems"
-readme = "README.md"
-requires-python = ">=3.7"
-classifiers = [
-    "Programming Language :: Python :: 3",
-    "License :: OSI Approved :: MIT License",
-    "Operating System :: OS Independent",
-]
-
-[tool.setuptools]
-include-package-data = true
-
-[tool.setuptools.packages.find]
-where = ["src"]
-
-[tool.setuptools.package-data]
-"*" = ["*.*"]
-
-[project.urls]
-"Homepage" = "https://github.com/ross-w/emerald_hws_py"
-"Bug Tracker" = "https://github.com/ross-w/emerald_hws_py/issues"

emerald_hws-0.0.10/src/emerald_hws/__init__.py

@@ -1 +0,0 @@
-

emerald_hws-0.0.10/src/emerald_hws.egg-info/PKG-INFO

@@ -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/src/emerald_hws.egg-info/requires.txt

@@ -1,2 +0,0 @@
-boto3
-awsiotsdk