homebridge-emerald-hws

Homebridge plugin for Emerald Heat Pump Hot Water Systems.
Provides monitoring and basic control of the Emerald HWS through Apple HomeKit.

Features

• Turn heating on or off
• View current tank temperature
• View target temperature (read-only)
• Turn Boost Mode on or off
• View water level (exposed as a humidity sensor)
• Report online/offline system status
• Uses the standard HomeKit Heater/Cooler service with additional accessories where appropriate

HomeKit Screenshots

Add your screenshots to the images/ folder and update the paths below.

Main Control Interface

Accessory Tiles

Requirements

Python 3.9 or newer

This plugin relies on the emerald_hws_py Python library, which requires Python to be installed on the system running Homebridge.

Install Python on Debian/Ubuntu (including Raspberry Pi OS)

Update packages and install Python:

sudo apt update
sudo apt install -y python3 python3-pip

Confirm installation:

python3 --version
pip3 --version

Homebridge (hb-service) installations

When Homebridge is installed using hb-service, Python must still be installed system-wide using the commands above.
The library will then be installed under the Homebridge user.

emerald_hws_py Python library

This library must be installed under the Homebridge service user (usually homebridge).
It should not be installed as root.

Install:

sudo -u homebridge pip3 install emerald_hws_py

Verify:

sudo -u homebridge python3 -c "import emerald_hws"

If no output or errors appear, the installation is correct.

Installation

Install the plugin:

sudo npm install -g homebridge-emerald-hws

Configuration

Add the following to your Homebridge config.json:

{
  "platform": "EmeraldHWS",
  "devices": [
    {
      "name": "Emerald HWS",
      "username": "YOUR_EMERALD_EMAIL",
      "password": "YOUR_EMERALD_PASSWORD",
      "pollInterval": 60
    }
  ]
}

Configuration Options

| Key | Description | |----------------|-------------| | name | Accessory display name in HomeKit | | username | Emerald account email | | password | Emerald account password | | pollInterval | Data refresh interval in seconds (default and recommended: 60) |

How It Works

This plugin communicates with the Emerald cloud API through the
emerald_hws_py Python library.

The plugin retrieves:

• Current tank temperature
• Target temperature (read-only)
• Water level
• Heating state
• Boost state
• Online/offline availability

It can also send commands to control heating and Boost Mode.

All data is exposed to HomeKit using standard HomeKit services.
If the system becomes unreachable, the accessory will report "No Response" until the next successful update.

Troubleshooting

emerald_hws_py not found

Install under the Homebridge user:

sudo -u homebridge pip3 install emerald_hws_py

Python not in Homebridge PATH

Edit the service file:

sudo nano /etc/systemd/system/homebridge.service

Add the following line:

Environment=PATH=/usr/bin:/usr/local/bin

Reload:

sudo systemctl daemon-reload
sudo systemctl restart homebridge

Frequent "No Response"

Increase the polling interval:

"pollInterval": 60

Acknowledgements

This plugin relies on the emerald_hws_py Python library created and maintained by
ross-w: https://github.com/ross-w/emerald_hws_py

Without this library, Homebridge integration for Emerald HWS would not be possible.

Changelog

See GitHub releases:
https://github.com/Faisalthe01/homebridge-emerald-hws/releases

License

MIT License