Homebridge OTGW

Homebridge plugin for OpenTherm Gateway

Copyright © 2019-2024 Erik Baauw. All rights reserved.

This Homebridge plugin exposes the room thermostat and boiler, connected to an OpenTherm Gateway (OTGW), to Apple's HomeKit. It exposes four accessories: Thermostat, Boiler, HotWater, and OutsideTemperature, each with their own Eve history.

1. Room Thermostat

The Thermostat accessory exposes the room thermostat, using a Thermostat service, with the following characteristics:

Characteristic	OpenTherm	ID	M/S
Current Heating Cooling State	Central Heating Mode (in Status)	0	M
Target Heating Cooling State	(Fixed to Heat)	-	-
Current Temperature	Room Temperature	24	M
Target Temperature	Room Setpoint Remote Override Room Setpoint	16 9	M
Valve Position*	Max Relative Modulation Level	14	M
Last Updated*	-	-	-
Schedule*	Room Setpoint Remote Override Room Setpoint	16 9	M

*You need a decent HomeKit app for these, as Home doesn't support custom characteristics. Schedule is visible only in Eve.

Target Temperature can be set from HomeKit to override the thermostat's Room Setpoint. When set, Schedule switches from On to Off. To return control to the thermostat, set Schedule back to On. When the Room Setpoint is changed from the thermostat (typically because the programme resumes), Schedule is set to On.

Effectively, Schedule reflects who set the Room Setpoint: the thermostat (On) or HomeKit (Off). The thermostat doesn't report whether it's running a programme, or a manual override.

2. Boiler - Central Heating

The Boiler accessory exposes the boiler's Central Heating (CH) function, using a Thermostat service, with the following characteristics:

Characteristic	OpenTherm	ID	M/S
Current Heating Cooling State	Flame Status (in Status)	0	S
Target Heating Cooling State	Central Heating Enable (in Status)	0	M
Current Temperature	Boiler Water Temperature	25	S
Target Temperature	Control Setpoint	1	M
Valve Position*	Relative Modulation Level	17	S
Last Updated*	-	-	-
Status Fault	Slave Status Fault (in Status)	0	S
Return Water Temperature*	Return Water Temperature	28	S
Water Pressure*	CH Water Pressure	18	S
Burner Starts*	Burner Starts	116	S
Pump Starts*	CH Pump Starts	117	S
Burner Hours*	Burner Operation Hours	120	S
Pump Hours*	CH Pump Operation Hours	121	S
Schedule*	(Fixed to On)	-	-

*You need a decent HomeKit app for these, as Home doesn't support custom characteristics. Schedule On/Off is visible only in Eve.

The Target Heating Cooling State and Target Temperature are controlled by the modulating Thermostat, so updates from HomeKit are ignored.

3. Boiler - Domestic Hot Water

The HotWater accessory expose the boiler's Domestic Hot Water (DHW) function, using a Thermostat service, with the following characteristics:

Characteristic	OpenTherm	ID	M/S
Current Heating Cooling State	DHW Mode (in Status)	0	S
Target Heating Cooling State	DHW Enable (in Status)	0	M
Current Temperature	DHW Temperature Boiler Water Temperature	26 25	S
Target Temperature	DHW Setpoint	56	M
Valve Position*	DHW Mode (in Status)	0	S
Last Updated*	-	-	-
Burner Starts*	DWH Burner Starts	119	S
Pump Starts*	DHW Pump/Valve Starts	118	S
Burner Hours*	DWH Burner Operation Hours	123	S
Pump Hours*	DHW Pump/Valve Operation Hours	122	S
Schedule On/Off*	(-)	9	M

*) You need a decent HomeKit app for these, as Home doesn't support custom characteristics. Schedule On/Off is visible only in Eve.

The Schedule On/Off reflects who set the DHW mode: On for thermostat controlled, Off for Comfort Mode, and Off for Eco mode. My boiler allows these settings, and my thermostat can turn DHW Mode off automatically during the night and/or on holidays.

My boiler doesn't support DHW Temperature, so Current Temperature is based on Boiler Water Temperature instead.

Because DHW Mode has a boolean value, Valve Position is either 0 or 100.

4. Outside Temperature

The OutsideTemperature accessory exposes the boiler's outside temperature sensor, using a Temperature Sensor service, with the following characteristics:

Characteristic	OpenTherm	ID	M/S
Current Temperature	Outside Temperature	27	S
Last Updated*	-	-	-

*You need a decent HomeKit app for these, as Home doesn't support custom characteristics.

The OpenThem protocol supports an outside temperature sensor, attached to the boiler. Most boilers, including mine, have no outside temperature sensor, but the OpenTherm Gateway supports setting the outside temperature from an external source. Homebridge OTGW includes a small bash script, weather.sh, that sets the outside temperature from OpenWeatherMap. I run this script every 15 minutes from cron.

It would be nicer instead to link to a Temperature Sensor exposed by another Homebridge plugin (like homebridge-ws), but that needs Homebridge v0.5.
Alternatively, expose another characteristic to set the outside temperature through a HomeKit automation.

Ideally I would like to enable/disable CH Comfort mode (or fireplace mode) from HomeKit, so the room thermostat drives the boiler based on the Outside Temperature instead of on the Room Temperature. However, this seems to be a local setting on the room thermostat, not exposed over OpenTherm.

Prerequisites

OpenTherm Gateway

You need an OpenTherm Gateway with firmware 5.1, wired to an OpenTherm compatible boiler and room thermostat.

In December 2021, I had my central heating replaced by a Remeha Avanta Ace 35c boiler and a Remeha iSense wired thermostat. Both support OpenTherm 3.0. I specifically chose the OpenTherm gateway in combination with the iSense, which is a traditional clock thermostat, over the eTwist smart thermostat, because:

• The eTwist is cloud based and doesn't offer a local API;
• The eTwist doesn't even provide a cloud-based API, other than an allegedly buggy IFTTT integration;
• The eTwist uses a proprietary protocol to communicate with the boiler, requiring a separate gateway to connect to OpenTherm boilers. I doubt the Remeha gateway would play nice with the OpenTherm gateway.

Before, I had a Remeha Avanta boiler and a Honeywell Chromotherm Vision Modulation room thermostat.

Please check that your setup works using the OpenTherm Monitor (OTM), before trying Homebridge OTGW. I'm running OTM in a Raspberry Pi, as there's no pre-compiled macOS version.

I bought my OTGW pre-soldered from Nodo Shop, with an optional NodeMCU to connect the OTGW to my WiFi network. See the Assembly Instructions (in Dutch, unfortunately) how to wire the OTGW to the thermostat and boiler and how to configure the NodeMCU as serial server.

Homebridge

You need a server to run Homebridge. This can be anything running Node.js: from a Raspberry Pi, a NAS system, or an always-on PC running Linux, macOS, or Windows. See the Homebridge Wiki for details. I run Homebridge OTGW on a Raspberry Pi 4B.

To interact with HomeKit, you need Siri or a HomeKit app on an iPhone, Apple Watch, iPad, iPod Touch, or Apple TV (4th generation or later). I recommend to use the latest released versions of iOS, watchOS, and tvOS.
Please note that Siri and even Apple's Home app still provide only limited HomeKit support. To use the full features of Homebridge OTGW, you might want to check out some other HomeKit apps, like the Eve app (free) or Matthias Hochgatterer's Home+ app (paid).

As HomeKit uses Bonjour to discover Homebridge, the server running Homebridge must be on the same subnet as your iDevices running HomeKit. For remote access and for HomeKit automations, you need to setup an Apple TV (4th generation or later), HomePod, or iPad as home hub.

Connection

The Homebridge OTGW plugin connects to the web server provided by OTM. For now, the web server needs to be unsecured, i.e. use plain HTTP and no username/password. The advantage of using the OTM web server is that Homebridge OTGW doesn't need to deal with the serial connection to the OTGW. Also, OTM supports multiple simultaneous clients. The disadvantage, obviously, is the use of an additional component.

As a fallback, the Homebridge OTGW plugin can connect to the OTGW when equipped with an optional NodeMCU serial server. Note that this server only entertains a single concurrent connection - when you start OTM, the connection from Homebridge OTGW is closed.

When the fallback is configured, Homebridge OTGW tries to (re-)connect to OTM first, falling back to OTGW's NodeMCU when that fails. This way, Homebridge OTGW continuously interacts with the OTGW, irrespective of whether OTM is running or not.

Installation

To install Homebridge OTGW:

• Follow the instructions on the Homebridge Wiki to install Node.js and Homebridge;
• Install the Homebridge OTGW plugin through Homebridge Config UI X or manually by:

  $ sudo npm -g i homebridge-otgw
  

• Edit config.json and add the OTGW platform provided by Homebridge OTGW, see Configuration.

Configuration

In Homebridge's config.json you need to specify Homebridge OTGW as a platform plugin. Furthermore, you can specify the hostname and port of the OTM web server. When not specified, the default localhost:8080 is used. Optionally, you can specify the hostname and port of the NodeMCU serial server in the OTGW:

  "platforms": [
    {
      "platform": "OTGW",
      "name": "OTGW",
      "host": "192.168.x.x:8080",
      "otgw": "192.168.x.y:6638"
    }
  ]

Caveats

Homebridge OTGW is a hobby project of mine, provided as-is, with no warranty whatsoever. I've been running it successfully at my home for years, but your mileage might vary.

The HomeKit terminology needs some getting used to. An accessory more or less corresponds to a physical device, accessible from your iOS device over WiFi or Bluetooth. A bridge (like Homebridge) is an accessory that provides access to other, bridged, accessories. An accessory might provide multiple services. Each service corresponds to a virtual device (like a lightbulb, switch, motion sensor, ..., but also: a programmable switch button, accessory information, battery status). Siri interacts with services, not with accessories. A service contains one or more characteristics. A characteristic is like a service attribute, which might be read or written by HomeKit apps. You might want to checkout Apple's HomeKit Accessory Simulator, which is distributed as an additional tool for Xcode.