Skip to content

phenotypic/homebridge-web-boiler

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

homebridge-web-boiler

npm npm

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)
  1. Set targetHeatingCoolingState when it receives:
/targetHeatingCoolingState?value=INT_VALUE
  1. Set targetTemperature when it receives:
/targetTemperature?value=FLOAT_VALUE
  1. Set dhwTargetState when it receives: (if dhw is enabled)
/dhwTargetState?value=INT_VALUE
  1. 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
  1. Update targetTemperature following a manual override by messaging the listen server:
/targetTemperature?value=FLOAT_VALUE
  1. Update dhwTargetState following a manual override by messaging the listen server: (if dhw is enabled)
/dhwTargetState?value=INT_VALUE
  1. Update dhwTargetTemperature following a manual override by messaging the listen server: (if dhw is enabled)
/dhwTargetTemperature?value=FLOAT_VALUE

About

Homebridge plugin for a web-based boiler

Resources

License

Stars

Watchers

Forks