homebridge-web-boiler

Description

This homebridge plugin exposes a web-based boiler to Apple's HomeKit. Using simple HTTP requests, the plugin allows you to control your central heating as well as your hot water (if enabled in the config.json).

See the examples folder for ready-to-use NodeMCU boiler control scripts, featuring both hysteresis and OpenTherm implementations. Hysteresis maintains the temperature within a set range, while OpenTherm controls temperature more precicely by modulating the boiler's output.

Installation

1. Install homebridge
2. Install this plugin: npm install -g homebridge-web-boiler
3. Update your config.json file

Configuration

"accessories": [
     {
       "accessory": "Boiler",
       "name": "Thermostat",
       "apiroute": "http://myurl.com"
     }
]

Core

Key	Description	Default
accessory	Must be Boiler	N/A
name	Name to appear in the Home app	N/A
apiroute	Root URL of your device	N/A

Optional fields

Key	Description	Default
temperatureDisplayUnits	Whether you want °C (0) or °F (1) as your units	0
currentRelativeHumidity	Whether to include currentRelativeHumidity as a field in /status	false
minStep	Minimum increment value for the temperature selector in the Home app	0.5
chMin	Lower bound for the temperature selector in the Home app	15
chMax	Upper bound for the temperature selector in the Home app	30
dhw	Whether you want to expose hot water control as an extra accessory	false
dhwName	Name for the extra hot water accessory	Hot Water
dhwMin	Lower bound for the hot water in the Home app	40
dhwMax	Upper bound for the hot water in the Home app	50

Additional options

Key	Description	Default
pollInterval	Time (in seconds) between device polls	300
checkupDelay	Time (in milliseconds) after setting HeatingCoolingState to update targetHeatingCoolingState and currentHeatingCoolingState	2000
listener	Whether to start a listener to get real-time changes from the device	false
timeout	Time (in milliseconds) until the accessory will be marked as Not Responding if it is unreachable	3000
port	Port for your HTTP listener (if enabled)	2000
http_method	HTTP method used to communicate with the device	GET
username	Username if HTTP authentication is enabled	N/A
password	Password if HTTP authentication is enabled	N/A
model	Appears under the Model field for the accessory	plugin
serial	Appears under the Serial field for the accessory	apiroute
manufacturer	Appears under the Manufacturer field for the accessory	author
firmware	Appears under the Firmware field for the accessory	version

API Interfacing

Your API should be able to:

1. Return JSON information when it receives /status:

{
    "targetHeatingCoolingState": INT_VALUE,
    "targetTemperature": FLOAT_VALUE,
    "currentHeatingCoolingState": INT_VALUE,
    "currentTemperature": FLOAT_VALUE
}

Note: You must also include the following fields in /status where relevant:

• currentRelativeHumidity (if currentRelativeHumidity is enabled)
• dhwTargetState (if dhw is enabled)
• dhwCurrentState (if dhw is enabled)
• dhwTargetTemperature (if dhw is enabled)
• dhwCurrentTemperature (if dhw is enabled)

2. Set targetHeatingCoolingState when it receives:

/targetHeatingCoolingState?value=INT_VALUE

3. Set targetTemperature when it receives:

/targetTemperature?value=FLOAT_VALUE

4. Set dhwTargetState when it receives: (if dhw is enabled)

/dhwTargetState?value=INT_VALUE

5. Set dhwTargetTemperature when it receives: (if dhw is enabled)

/dhwTargetTemperature?value=FLOAT_VALUE

Optional (if listener is enabled)

1. Update targetHeatingCoolingState following a manual override by messaging the listen server:

/targetHeatingCoolingState?value=INT_VALUE

2. Update targetTemperature following a manual override by messaging the listen server:

/targetTemperature?value=FLOAT_VALUE

3. Update dhwTargetState following a manual override by messaging the listen server: (if dhw is enabled)

/dhwTargetState?value=INT_VALUE

4. Update dhwTargetTemperature following a manual override by messaging the listen server: (if dhw is enabled)

/dhwTargetTemperature?value=FLOAT_VALUE