Skip to content

Home

Jump to bottom Edit New page
Yurii edited this page Dec 7, 2024 · 28 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. Configure the connection to your WiFi network on the Network settings page.
  5. Configure the connection to the OpenTherm bus in the OpenTherm settings section on the Settings page. Required parameters: In GPIO and Out GPIO. If necessary, set up a the Master Member ID.
    Typical GPIOs for your board can be see here.
  6. Optional: Configure the indoor and outdoor temperature sensors on the Sensors settings page.
  7. Optional: Configure MQTT credentials in the MQTT settings section on the Settings page. Required for integration with Home Assistant.
    The OTGateway device will be automatically added to Home Assistant if MQTT credentials are correct.

Tip

After connecting to your WiFi network, you can go to the web portal at the IP address that ESP received.

Build firmware

  1. It is recommended to use PlatformIO: all necessary dependencies and libraries will be downloaded and installed automatically.
  2. To build the file system need to install Node.js (for GULP)
  3. After installing PlatformIO, download the repository as a zip archive and open it in your IDE or clone the repository in your IDE.
  4. 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

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.

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

  • Source type: Manual via MQTT/API

Use Blueprint to import automation into your Home Assistant:
Import Blueprint

  • Source entity: the source sensor from which we take the temperature.
  • Target entity: to report indoor temperature: number.opentherm_indoor_temp; to report outdoor temperature: number.opentherm_outdoor_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 via MQTT/API

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 via MQTT/API

Use Blueprint to import automation into your Home Assistant:
Import Blueprint

  • Source entity: the source weather from which we take the temperature.
  • Target entity: target entity number where we set the temperature, usually: 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. It is good practice to use Home Assistant Packages:

  1. Add to your configuration.yaml:
homeassistant:
  ...
  packages: !include_dir_merge_named packages/
  1. Create folders packages/dhw_meters in the root directory /homeassistant
  2. Create file dhw_meter.yaml in the directory /homeassistant/packages/dhw_meters
  3. 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

  • 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.

Logs and debug

  • To display all debug messages, you need to change the Log level to VERBOSE in section System settings on the Settings page.
  • You can see debug messages via:
    • Serial port over USB connection
    • Telnet (host: ESP IP, default port: 23)
Add a custom footer
Add a custom sidebar
Clone this wiki locally