HomeSeer HS4 Smart Home Software User Manual

: June 9, 2024
: HomeSeer

Table of Contents

Home Seer HS4 Smart Home Software
Installation/Configuration
Sending a Command
Serial Connection
- Support
Changelog
References
Read User Manual Online (PDF format)
Download This Manual (PDF format)

Home Seer HS4 Smart Home Software

OpenTherm Gateway Plugin for HomeSeer HS4 Manual

The OpenTherm Gateway Plugin for HS4 allows communication with an OpenTherm Gateway (OTGW) which is an open-source gateway that can be built or purchased to connect your OpenTherm thermostat and boiler.

Requirements

HomeSeer HS4 version 4.2.14.0 or higher on Windows or Linux
An OpenTherm Gateway (OTGW) connected to your network via Wi-Fi
or LAN with a fixed IPv4 address

Installation/Configuration

To install the plugin, follow the instructions provided by HomeSeer for installing plugins. Once installed, navigate to the plugin settings and configure the OTGW IP address and port number.

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.
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 to 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 removing 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 a 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

The plugin creates a variety of feature devices related to OpenTherm MsgIDs and other features:
There are quite a lot of (feature) devices being created. This chapter gives you more information on them. Given the number 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 that 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 a max. 16 of these.

Noteworthy:

MsgID20 has a button that 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 the 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, the 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.
This is useful if, prior to using this plugin, you have used a solution that 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

Features related to OpenTherm MsgIDs:

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

Other Features

Monitor Mode/Gateway Mode/Reset OTGW: This feature has buttons to send commands for Monitor Mode (GW=0), Gateway Mode (GW=1), or Reset the OTGW (GW=R).
Status: This displays the current status of the OTGW after it has sent a corresponding response (GW: 0 or GW:

There may be a delay due to waiting for the response and HS4’s UI update frequency.

If you find any bugs, please notify the developer through the HomeSeer forums.

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
The status will be updated after the OTGW has sent the 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 temporarily (until the 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. The status will say unknown until the plugin receives a powerful message, which can be Low Power, Medium Power, or High power. In the case of my thermostat, medium power means the backlight is lit, and 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 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:
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 the 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 to 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 to 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 the 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 donating 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:

Use a free COM/TTY port to IP address redirector to connect. They can easily be found through an internet search engine.
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 open therm 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 –daemon, which will make it run without GUI and save resources.
Disable Logging.

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