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

pip install emerald_hws

Usage

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:

# 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:

# 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:

def my_callback():
    print("Hot water system state updated!")

client = EmeraldHWS("your_email@example.com", "your_password", update_callback=my_callback)

Project links

Data verified by PyPI on Jul 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for ross-w from gravatar.com ross-w

Credits

Author: Ross Williamson

GitHub Statistics

Data verified by PyPI on Jul 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.9

Provides Extra

dev test

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

emerald_hws-0.0.30.tar.gz (51.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

emerald_hws-0.0.30-py3-none-any.whl (17.3 kB view details)

Uploaded Python 3

File details

Details for the file emerald_hws-0.0.30.tar.gz.

File metadata

  • Download URL: emerald_hws-0.0.30.tar.gz
  • Upload date:
  • Size: 51.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for emerald_hws-0.0.30.tar.gz
Algorithm Hash digest
SHA256 d787b728cfd2cb3018a3ed8ed930d513cb6b637abc4ad714f03efad5fd087e4f
MD5 be6c20f97b88b41b7623aef010a3cf61
BLAKE2b-256 9a168577e20cd41ac8f09d35f1298497341a91fd9988683f9255ff488ef8fd45

See more details on using hashes here.

Provenance

The following attestation bundles were made for emerald_hws-0.0.30.tar.gz:

Publisher: publish.yml on ross-w/emerald_hws_py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file emerald_hws-0.0.30-py3-none-any.whl.

File metadata

  • Download URL: emerald_hws-0.0.30-py3-none-any.whl
  • Upload date:
  • Size: 17.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for emerald_hws-0.0.30-py3-none-any.whl
Algorithm Hash digest
SHA256 decef619e2960458ea842d0743397e1b51841a38c249ac5ac96ab64083cca94f
MD5 c3ba6c13aad43b96346cadda6190cf05
BLAKE2b-256 51d17f1a93c0415eda222b611609708509ee865533094d4ad8a9a662fba3948a

See more details on using hashes here.

Provenance

The following attestation bundles were made for emerald_hws-0.0.30-py3-none-any.whl:

Publisher: publish.yml on ross-w/emerald_hws_py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.0.30 This release

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.21

2 files

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page