OpenTherm Gateway Plugin for HomeSeer HS4 Manual

Introduction

Thank you for using the OpenTherm Gateway Plugin for HS4! This plugin can be used to communicate with an OpenTherm Gateway (OTGW). OTGW is an open source gateway by Schelte Bron that you can build yourself (or buy from a few webshops) and connect in between your OpenTherm thermostat and boiler or compatible devices. Please see Requirements for more info.

Please note that, despite its name, the OpenTherm protocol is not an open standard. Information about it was gathered from leaked documents and downloads, as well as other projects. It may not be 100% correct, but I'm constantly hunting for more information and will update this plugin accordingly. If you have additional information, please share it with me through the HomeSeer forums.

This plugin will process every known OpenTherm message, unlike scripts or solutions for other home automation platforms. Those are usually based on the (PS=1) summaries, which are read every at certain intervals. In other words, this plugin is realtime. Any delay is caused by thermostat/boiler being busy with other more important messages. The devices page in HS4 also does not update instantly (but every other second or so). Not using PS=1 also means that you can always use the latest OTGW firmware (The summary output changed in version 5.0 and may change again in future).

This is my fourth plugin for HS4. My other plugins are the MiLight Plugin, Volvo Plugin and Horizon Remote Plugin. My main motivation to develop these plugins is to get better and better at C# development, and because I want the functionality for my own system.

I have tested this plugin thoroughly, but if you find bugs anyway, please let me know.

Bernold

Requirements

To use this plugin, you will need the following:

• HomeSeer HS4. The plugin has only been tested on Windows, but should work on Linux as well. The version has to be at least 4.2.14.0, as it depends on SDK 1.4.2.0.
• An OpenTherm Gateway (OTGW) connected to your network via Wi-Fi or LAN. USB/COM is not supported. See chapter “Serial Connection”. Please make sure that it gets a fixed IPv4 address. It helps if you have already connected it in between your thermostat and boiler and have tested it, for example with the OpenTherm Monitor as provided by Schelte Bron, to make sure it works on the intended IP address/port.

Abbreviations

CH

Central Heating

CH2

Central Heating, 2nd circuit

DHW

Domestic Hot Water

FHB

Fault History Buffer

OEM

Original Equipment Manufacturer

OTC

Outside Temperature Compensation

TSP

Transparent Slave Parameters

V/H

Ventilation/Heat-Recovery

OTGW is an abbreviation of OpenTherm Gateway

Installation/Configuration

1. Install and activate the plugin like any other plugin. If you're new to HS4, here is how:
   • Go to your HomeSeer Web Control page.
   • Use the Plugin dropdown and choose Add.
   • Use the (2nd) Search bar, or scroll to OTGW Plugin.
   • Choose Install.
   • In Plugins > Installed use the toggle to turn on the plugin.
2. Configure:
   • Go to Plugins > OTGW Plugin > Add OpenTherm Gateway.
   • Follow the steps:
     • Choose Continue at the introduction step.
     • Enter the IPv4 address of the OTGW. Choose Continue.
     • Enter the port number that goes with that IP address. Choose Continue.
     • Optionally enter a name for this OTGW. This is useful when you have more than one. If you don't enter a name, the IP and port will be used. If you now continue by choosing Create Device/Features, the entered information will be validated and the device and a few of its features will be created. After that, the connection to the OTGW will be made.

Noteworthy

• Other features will be added only as soon as a matching message is received. This way you will only get features that are actually supported by your thermostat/boiler.
• However, it may take hours before every message was received, possibly even a day (for instance for the date feature).
• Please note that if your thermostat/boiler would support all messages you may end up with 150+ features.
• You may want to hide features that are of no use to you. Do not delete features. Also, you may want to restrict access to certain features for certain users for safety/security reasons. You can do this by clicking on each feature and under User Access remove the Any checkmark, chose your (admin) account(s) instead and then Save.
• A timeout is applicable. If the plugin does not receive an OT message for 2,5 seconds, it assumes the connection is down, it will write a warning to the Log and tries to reconnect. Meanwhile the plugin will not receive OT messages, so features may not be entirely up to date for a while. If this happens often, you may want to check how your OTGW is connected to your network: Wi-Fi reception may be poor, or you have a faulty cable. During timeout at least 2 messages are missed (According to the OT Specification there should be a message at least every second, with a 15% margin). The total number of missed messages depends on how fast the plugin can reconnect.

Devices and Features

There are quite a lot of (feature) devices being created. This chapter gives you more information on them. Given the amount of possible features it's not really doable to list them all. But here is some general information.

Features that are related to an OpenTherm MsgID

Most features have a MsgID reference. This is the ID which is used in the OpenTherm protocol. These IDs carry different information. All of these are converted to feature values.

• Byte values from -127..128 or 0..255. Each ID can have max. 2 of these.
• Double byte values from 0..65535 or -32768..32767
• Double byte fractional (1/256) values from -128 ..127 and 255/256th (127.99609375). These features are all set to show 2 decimals. Your thermostat or boiler may only support 0.1 increases though.
• Bit values (flags): false or true, which become 0 resp. 100 and have status set to their meaning). Each ID can have max. 16 of these.

Noteworthy:

• MsgID20 has a button which sends the SC command to the OTGW to sync the clock with the current time of your HS4 system. See: https://otgw.tclcode.com/firmware.html#cmdsc
• The following MsgIDs are counters and have a hidden “button” to reset each counter (if supported by your boiler). No button has been created, so you can't accidentally reset any of these counters. If you do want to add the button, please add a Single Value Control with a value of -1. This is applicable to the following features: MsgID116 Burner Starts, MsgID117 Pump Starts, MsgID118 DHW Pump/Valve Starts, MsgID119 DHW Burner Starts, MsgID120 Burner Operation Hours, MsgID121 CH Pump Operation Hours, MsgID122 DHW Pump/Valve Operation Hours, MsgID123 DHW Burner Operation Hours See: https://otgw.tclcode.com/firmware.html#cmdrs
• Though it seems that OpenTherm is only used in countries where degrees are expressed in Celsius, this plugin does support Fahrenheit. At the time of creation of every feature, the global HS4 setting for that will be checked (Setup > General > Other Settings > Temps Fahrenheit/Temps Celsius). If the setting is Fahrenheit, the suffix will be set to °F and otherwise it will be set to °C. The Temperature Temporary and Temperature Constant features get whole Fahrenheit values, rather than converted Celsius values. However, behind the dropdown are values in Celsius. So if you pick a value from the dropdown, it will send the converted value to the OTGW. A value will be converted to °F only if the setting is still valid while the value is being updated. Features will not be changed from °F to °C - and vice versa - if the global setting is changed. If you want that, please manually change each suffix (or remove and add the OTGW again if you don't care much about device references).
• Please note that this plugin interprets some messages differently than Opentherm Monitor. For example MsgID56 DHW Setpoint will show you what the boiler says the setpoint is, instead of what the thermostat guesses it might be: T10383C00 Write-Data DHW setpoint (MsgID=56): 60.00 BE0382800 Data-Inv DHW setpoint (MsgID=56): 40.00 – Boiler says “No, setpoint is actually 40.00).

Other features

Then there are features that are not directly related to Msg IDs. Here is a list of all of them:

• Connection Status, which shows you if the particular OTGW is Disconnected or Connected and has buttons to Disconnect, (Re)Connect or send the PS=0 command. Which is useful if, prior to using this plugin, you have used a solution which used the PS=1 summaries, which stops the OTGW from showing regular OpenTherm messages. In other words, this should get the messages going again.
• Error 01/Error 02/Error 03/Error 04. Please see: https://otgw.tclcode.com/firmware.html#errors

Each Error feature has a button to reset the feature value to 0 (It's not sent to the OTGW).

• Gateway State. The state can be Unknown (if the state has not been changed through the plugin yet), Monitor Mode, or Gateway Mode. The feature has buttons to send commands Monitor Mode (GW=0), Gateway Mode (GW=1) or Reset the OTGW (GW=R). See: https://otgw.tclcode.com/firmware.html#cmdgw Status will be updated after the OTGW has sent corresponding response (GW: 0 or GW: 1). This may look delayed, because of waiting for the response and HS4's UI update frequency.
• Override Temperature Temporary, to override the thermostat temperature temporary (until next scheduled temperature change). It has a dropdown with values it can send to the OTGW. Setting it to 0 cancels it. See: https://otgw.tclcode.com/firmware.html#cmdtt
• Override Temperature Constant, to override the thermostat temperature. It has a dropdown with values it can send to the OTGW. Setting it to 0 cancels it. See: https://otgw.tclcode.com/firmware.html#cmdtc
• Smart Power State, which will only be created if MsgID 2 says it's supported. Status will say unknown until the plugin receives a power message, which can be Low power, Medium power, or High power. In case of my thermostat, medium power means the backlight is lit, low power means it's not. So it will tell me if someone is manually operating the thermostat. Your mileage may vary.
• ΔT, which will only be created if both MsgID25 Boiler Flow Water Temperature and MsgID28 Return Water Temperature are available. It will show the difference (delta) between the water temperature leaving your boiler and returning to your boiler, which is a good first indication of the efficiency of your central heating system.

Sending a Command

While some features have buttons to send commands, I decided to not create a feature for every possible command. Mainly to keep the number of features to a minimum (kind of), but mostly because not every OpenTherm device supports every command and some commands are only available on an OTGW with a certain type of PIC or a certain firmware version. These features would be not be useful for everybody. Besides, some commands have to be used with care.

So instead I chose to create an event action that lets you send any command to the OTGW.

Example

As an example, here is how to send the outside temperature from a separate sensor (not connected to the boiler/thermostat/OTGW) to the OTGW.

First, create the trigger. In this case, the event will run when the sensor's temperature has been set or changed:

[Description of the HomeSeer event configuration screenshot: A visual representation of a HomeSeer event trigger and action. The trigger is set to "A Device's Value is..." for "Outside-Outside back-Temperature" when "Just had its value set or changed". The action is "OTGW Plugin Action - Send command" to a specific OTGW Device (iSense (192.168.20.80:8080)) with the command "OT=$$DVR:1256:"]

If this event is triggered, the Send Command action is used to send, to the selected OTGW, the OT (Outside Temperature) command with the value from the replacement variable of feature device with reference 1256 (which in this case is the reference of the same outside temperature sensor as the trigger uses).

For a full list of OTGW commands, see: https://otgw.tclcode.com/firmware.html#commands

And a list of replacement variables can be found here: https://docs.homeseer.com/products/software/hs4-smart-home-software/scripting/applications-and-plugins/replacevariables/using-replacement-variables

Of course, sending commands is fully at your own risk. Especially the commands which allow you to modify setpoints can cause unwanted situations. Always make sure that commands are confirmed, by checking their matching MsgID.

Modifying a Gateway

To modify the IP address, port and/or name of a previously added OTGW you can use the Modify OpenTherm Gateway page as follows:

• Go to Plugins > OTGW Plugin > Modify OpenTherm Gateway.
• Follow the steps:
  • Choose Continue at the introduction step.
  • Pick the OTGW you want to modify from the dropdown. Choose Continue.
  • Modify the IPv4 address of the OTGW, if needed. Choose Continue.
  • Modify the port number that goes with that IP address, if needed. Choose Continue.
  • Modify the name for this OTGW, if needed. Choose Continue.
  • If you want to modify the Location (room) of the features to the new IP address/port just like when you added the OTGW, choose Modify location(s)/room(s) to the new IP address/port. If since adding the OTGW you have modified the location(s) to something custom, you may want to choose Leave location(s)/room(s) as they are instead. Choose Continue.
  • Confirm the change and choose Modify Now. Features and settings will then be modified to use the new IP/port/name (unless invalid or already in use).

Removing a Gateway

To completely remove an OTGW from the settings and remove its device and features you can use the Remove OpenTherm Gateway page as follows:

• Go to Plugins > OTGW Plugin > Remove OpenTherm Gateway.
• Follow the steps:
  • Choose Continue at the introduction step.
  • Pick the OTGW you want to remove from the dropdown. Choose Continue.
  • Confirm the removal and choose Remove Now. Features and settings will then be removed.

Donate

As the Donate page (Plugins > OTGW Plugin > Please Donate) explains, I decided to make the plugin free. Considering the amount of work that went into it (research, writing code, testing, etc.) and expected support/updating in future, this would have been a paid plugin.

The reason for this plugin being released as a free plugin is simple. Schelte Bron has released the OTGW without the intention to make money. Its PCB design, firmware, software and sources are available for everyone, free of charge.

If you are willing to donate, please first consider to donate to Schelte Bron. There is a link to his PayPal at the bottom (Feedback) of this page on his site.

If you are willing to donate to me I'm asking you to buy my paid plugin: MiLight (LimitlessLED). That way HomeSeer will get their share too, which I think is fair.

Thank you for your support.

Serial Connection

Although this plugin does not natively support using a serial connection (USB/COM/TTY), there are ways to connect an OTGW that has no LAN/Wi-Fi yet:

1. Use a free COM/TTY port to IP address redirector to connect. They can easily be found through an internet search engine.
2. Use Schelte Bron's Opentherm Monitor to connect via serial port (Options > Connection > Serial port. Set the radio button and choose the Serial device). Then use its relaying function under Options (Configuration) > Remote Access. Enable both Enable relay server and Relay opentherm messages. Modify the Server port if needed. Then add the OTGW to the plugin with the IP of the machine running Opentherm Monitor and the port you have set for relaying.

Note you may want to save resources by:

• Running Opentherm Monitor with parameter –deamon, which will make it run without GUI and save resources.
• Disable Logging.

[Description of the Opentherm Monitor screenshots: Two screenshots of the Opentherm Monitor software are displayed. The left screenshot, labeled "Connection", shows configuration options for serial port (e.g., COM1) and TCP connection (localhost:25238). The right screenshot, labeled "Remote access", shows settings for enabling a relay server on port 7686 and relaying OpenTherm messages.]

Thanks to forum user mo046 for this addition.

Support

If you have a question about this plugin or want to report a bug, please use the dedicated sub-forum on https://forums.homeseer.com/

Everything about the OTGW can be found here: https://otgw.tclcode.com/

And a forum about the OTGW, where the creator is present as moderator: https://domoticaforum.eu/viewforum.php?f=75

Changelog