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 27, 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:
Newer release available (0.0.30)

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 27, 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.29.tar.gz (46.5 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.29-py3-none-any.whl (16.0 kB view details)

Uploaded Python 3

File details

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

File metadata

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

File hashes

Hashes for emerald_hws-0.0.29.tar.gz
Algorithm Hash digest
SHA256 a3ddcf993df0ca7e396fba0c6d439be95055607171c3c41ad2fde6969ae0b1ec
MD5 60511178cda14fbaa7466f77f472d995
BLAKE2b-256 9ac1c7b03844b5aebf03db9acdd346758078bd1f92b02f0e549e79ddbf6e4053

See more details on using hashes here.

Provenance

The following attestation bundles were made for emerald_hws-0.0.29.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.29-py3-none-any.whl.

File metadata

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

File hashes

Hashes for emerald_hws-0.0.29-py3-none-any.whl
Algorithm Hash digest
SHA256 da4d7346a3e36433ae1526c07124dd4836bd05b1266420336f03578176aefb7f
MD5 d396395fab004d80eed88da22ceb5bb7
BLAKE2b-256 bdd5b4be0c5d085c378025ba002841e78c7eae377703693476de780e32c28b84

See more details on using hashes here.

Provenance

The following attestation bundles were made for emerald_hws-0.0.29-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

0.0.30

2 files

This release

0.0.29 This release

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