Skip to content

Home

Jump to bottom
Laxilef edited this page Mar 24, 2024 · 21 revisions

Quick Start

  1. Flash firmware via ESP Flash Download Tool or PlatformIO
  2. Connect to OpenTherm Gateway hotspot, password: otgateway123456
  3. Open configuration page in browser: 192.168.4.1
  4. Set up a connection to your wifi network
  5. Set up a connection to your MQTT server: ip, port, user, password
  6. Set up a Opentherm GPIO IN and Opentherm GPIO OUT. Typical GPIOs for your board can be see here.
  7. Set up a Outdoor sensor GPIO and Indoor sensor GPIO.
  8. if necessary, set up a the Opentherm Master Member ID

After connecting to your wifi network, you can go to the setup page at the address that ESP received. The OTGateway device will be automatically added to homeassistant if MQTT server ip, login and password are correct.

Build firmware

  1. It is recommended to use PlatformIO: all necessary dependencies and libraries will be downloaded and installed automatically.
  2. After installing PlatformIO, download the repository as a zip archive and open it in your IDE or clone the repository in your IDE.
  3. Now you need to select your board from the list of environment and click on Build. After building the firmware and file system image, they will be placed in the "build" directory.

Flash firmware via ESP Flash Download Tool

  1. Download the latest version ESP Flash Download Tool
  2. Download the firmware and filesystem image for your board from the releases page (or compile yourself)
  3. Run ESP Flash Download Tool as administrator
  4. Select the firmware image file, address: 0x0. For ESP32 use factory images!
  5. Select the filesystem image file, address:
  • ESP8266: 0x300000
  • ESP32: 0x370000
  1. Select the COM port to which the board is connected and the speed (BAUD) 921600
  2. Press ERASE to clear all ESP memory
  3. Press START to upload firmware and file system
  4. Manually restart the ESP

HomeAsssistant settings

By default, the "Equitherm" and "PID" modes are disabled. In this case, the boiler will simply maintain the temperature you set. To use "Equitherm" or "PID" modes, the controller needs to know the temperature inside and outside the house.

Some boilers have the ability to connect inside and outside temperature sensors. If your boiler supports it, you need to go to Settings page, in the Outdoor sensor settings and Indoor sensor settings sections change the parameters:

  • Source type: Boiler

After this, you need to check the "Outdoor temperature" and "Indoor temperature" sensors. If any of them has a value of 0, then the boiler does not report the temperature via OpenTherm and you need to use an external sensor or report the temperature from the home assistant using automation.

External temperature sensors

The highest accuracy of readings is when using external temperature sensors. I prefer to use DS18B20, but you can use any compatible sensor. These sensors must be connected directly to the ESP GPIO. Some OT adapters already have connectors to connect them.
After physically connecting the sensors, you need to set the GPIO numbers in the controller settings.
To do this, you need to go to Settings page, in the Outdoor sensor settings and Indoor sensor settings sections change the parameters:

  • GPIO
  • Source type: External

And save the settings. After this you can check the sensors. To do this, look at the values of the "Indoor temperature" and "Outdoor temperature" sensors.

Tip

Of course you can combine temperature sources. For example, you can take the outside temperature from an external DS18B20 sensor, and the inside temperature from a Zigbee sensor using automation.

Reporting indoor/outdoor temperature from any Home Assistant sensor

There is a simple automation that takes the temperature from any temperature sensor (eg Zigbee) and reports it to the controller. How to create automation in HA you can read here.

Before creating automation you need to go to Settings page, in the Indoor sensor settings sections change the parameters:

  • Source type: Manual

And save the settings. After that, you can create automation. The automation code can be copied from here. Before saving, you need to change the entity IDs:

  # The source sensor from which we take the temperature
  source_entity: "sensor.livingroom_temperature"

  # Target entity number where we set the temperature
  # To report indoor temperature: number.opentherm_indoor_temp
  # To report outdoor temperature: number.opentherm_outdoor_temp
  target_entity: "number.opentherm_indoor_temp"

Tip

The same code can be used to report the outside temperature. For example, if you have a Zigbee temperature sensor that is installed outside.
But don't forget to change the parameters on the Settings page in the External sensor settings section:

  • Source type: Manual

Reporting outdoor temperature from Home Assistant weather integration

There is a simple automation that takes the temperature from Home Assistant weather integration and reports it to the controller. It is important that the address of your home is entered correctly in the Home Assistant settings.

Before creating automation you need to go to Settings page, in the Outdoor sensor settings sections change the parameters:

  • Source type: Manual

After that, you can create automation. The automation code can be copied from here. Before saving, you need to change the entity IDs:

  # The source weather from which we take the temperature
  source_entity: "weather.home"

  # Target entity number where we set the temperature
  # If the prefix has not changed, then you do not need to change it
  target_entity: "number.opentherm_outdoor_temp"

DHW meter

Some boilers have a water flow rate sensor and report this value via OpenTherm. You can check this, to do this you need to activate the "DHW flow rate" entity. Now when you open a hot water tap, the value of this sensor should change. If the value is non-zero, then your boiler supports this function.

Now we can create a sensor that will calculate the consumption of hot water.

Note

After changing the Home Assistant configuration, you must restart HA.

Once the sensor appears in your Home Assistant, you can add it to your Energy dashboard and monitor your hot water consumption:

Advanced Settings

Some entities are not activated by default to avoid confusion for new users. These entities can be useful for flexible configuration, some of them are:

  • Heating min temp - minimum possible temperature of the heat carrier.
  • Heating max temp - maximum possible temperature of the heat carrier.
  • Max modulation - maximum possible modulation level. Can be used to reduce the burner startup frequency.

Equitherm mode

Weather-compensated temperature control maintains a comfortable set temperature in the house. The algorithm requires temperature sensors in the house and outside.
Instead of an outdoor sensor, you can use the weather forecast and automation for HA.

Ratios

N - heating curve coefficient. The coefficient is selected individually, depending on the insulation of the room, the heated area, etc.
Range: 0.001...10, default: 0.7, step 0.001

K - сorrection for desired room temperature.
Range: 0...10, default: 3, step 0.01

T - thermostat correction.
Range: 0...10, default: 2, step 0.01

Fit coefficients

Tip

I created a table in Excel in which you can enter temperature parameters inside and outside the house and select coefficients. On the graph you can see the temperature that the boiler will set.

  1. Set the K and T coefficients to 0.
  2. The first thing you need to do is to fit the curve (N coefficient). If your home has low heat loss, then start with 0.5. Otherwise start at 0.7. When the temperature inside the house stops changing, increase or decrease the coefficient value in increments of 0.1 to select the optimal curve.
    Please note that passive heating (sun) will affect the house temperature during curve fitting. This process is not fast and will take you 1-2 days. Important. During curve fitting, the temperature must be kept stable as the outside temperature changes.
    At this stage, it is important for you to stabilize the indoor temperature at exactly 20 (+- 0.5) degrees.
    For example. You fit curve 0.67; set temperature 20; the temperature in the house is 20.1 degrees while the outside temperature is -10 degrees and -5 degrees. This is good.
  3. After fitting the curve, you must select the K coefficient. It influences the boiler temperature correction to maintain the set temperature. For example. Set temperature: 23 degrees; temperature in the house: 20 degrees. Try setting it to 2 and see how the temperature in the house changes after stabilization. Select the value so that the temperature in the house is close to the set.
  4. Now you can choose the T coefficient. Simply put, it affects the sharpness of the temperature change. If you want fast heating, then set a high value (6-10), but then the room may overheat. If you want smooth heating, set 1-5. Choose the optimal value for yourself.
  5. Check to see if it works correctly at different set temperatures over several days.

Read more about the algorithm here.

PID mode

See Wikipedia. PID example

In Google you can find instructions for tuning the PID controller.

Clone this wiki locally