Homebridge plugin for Emerald Heat Pump Hot Water Systems.
npm install homebridge-emerald-hws


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


---
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:
``bash`
sudo apt update
sudo apt install -y python3 python3-pip
Confirm installation:
`bash`
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.
---
Install:
`bash`
sudo -u homebridge pip3 install emerald_hws
Verify:
`bash`
sudo -u homebridge python3 -c "import emerald_hws"
If no output or errors appear, the installation is correct.
---
Install the plugin:
`bash`
sudo npm install -g homebridge-emerald-hws
---
Add the following to your Homebridge config.json:
`json`
{
"platform": "EmeraldHWS",
"devices": [
{
"name": "Emerald HWS",
"username": "YOUR_EMERALD_EMAIL",
"password": "YOUR_EMERALD_PASSWORD",
"pollInterval": 60
}
]
}
| 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) |
---
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.
---
`bash`
sudo -u homebridge pip3 install emerald_hws_py
``
sudo nano /etc/systemd/system/homebridge.service
Add the following line:
``
Environment=PATH=/usr/bin:/usr/local/bin
Reload:
`bash`
sudo systemctl daemon-reload
sudo systemctl restart homebridge
`json`
"pollInterval": 60
---
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.
---