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 SetpointRemote Override Room Setpoint | 169 | M Valve Position* | Max Relative Modulation Level | 14 | M Last Updated* | - | - | - Schedule* | Room SetpointRemote Override Room Setpoint | 169 | 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 TemperatureBoiler Water Temperature | 2625 | 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.