OpenTherm device

[khenderick]

What does this implement?

This PR introduces support for opentherm devices such as:

• DIYLess' Master OpenTherm Shield
• Ihor Melnyk' OpenTherm adapter

Those are typically connected to an ESP8266 or ESP32

The functional aspect (OpenTherm communications) is heavily based on ihormelnyk/opentherm_library.

The goal of this integration is not to provide a full-blown climate device, but rather expose a bunch of OpenTherm data and functionality. To make use of this data and functionality is up to the user. This could be by - for example - using the exposed enities in ESPHome/HA automations or by using the exposed entities in other components (e.g. a combination of PID Climate and a few Template Outputs)

As this is my first contribution, I'm also looking for constructive criticism on how to enhance this integration where needed.

Types of changes

• [ ] Bugfix (non-breaking change which fixes an issue)
• [x] New feature (non-breaking change which adds functionality)
• [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
• [ ] Other

Pull request in esphome-docs with documentation (if applicable): esphome/esphome-docs#2379

Test Environment

• [x] ESP32
• [ ] ESP32 IDF
• [ ] ESP8266

Example entry for config.yaml:

opentherm:
  read_pin: 21
  write_pin: 22

sensor:
  - platform: opentherm
    ch_min_temperature:
      name: "CH minimum temperature"
    ch_max_temperature:
      name: "CH maximum temperature"
    dhw_min_temperature:
      name: "DHW minimum temperature"
    dhw_max_temperature:
      name: "DHW maximum temperature"
    pressure:
      name: "pressure"
    modulation:
      name: "modulation"
    boiler_temperature:
      name: "boiler temperature"
    return_temperature:
      name: "return temperature"

binary_sensor:
  - platform: opentherm
    ch_active:
      name: "CH active"
    dhw_active:
      name: "DHW active"
    flame_active:
      name: "flame active"
    fault:
      name: "fault"
    diagnostic:
      name: "diagnostic"

switch:
  - platform: opentherm
    ch_enabled:
      name: "CH enabled"
    dhw_enabled:
      name: "DHW enabled"

number:
  - platform: opentherm
    ch_setpoint_temperature:
      name: "CH setpoint temperature"
      min_value: 20.0
      max_value: 45.0
      step: 0.5
      restore_value: true
    dhw_setpoint_temperature:
      name: "DHW setpoint temperature"
      min_value: 38.0
      max_value: 60.0
      step: 0.5
      restore_value: true

Checklist:

• [x] The code change is tested and works locally.
• [x] Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

• [x] Documentation added/updated in esphome-docs.

[probot-esphome[bot]]

Hey there @khenderick, Thanks for submitting this pull request! Can you add yourself as a codeowner for this integration? This way we can notify you if a bug report for this integration is reported. In __init__.py of the integration, please add:

CODEOWNERS = ["@khenderick"]

And run script/build_codeowners.py

_{^{(message by NeedsCodeownersLabel)}}

[Weissnix4711]

Hi, nice to see someone else is interested in getting OpenTherm working in ESPHome.

Sadly the approach you've taken here almost certainly won't be accepted.

As per the docs:

Specifically methods like delay(10) should be avoided and delays above ~10ms are not permitted.

Yeah blocking for 32ms at a time (1ms per bit, 32 bit frame) probably won't pass.

Ideally we would rewrite the entire thing using interrupts. Or, the lazy approach I've taken is to simply write a new remote protocol, as the remote transmitter / receiver components already make use of the ESP32's rmt peripheral. It ain't pretty, but it works.

[khenderick]

Thanks for the valuable feedback. I was - incorrectly - looking at individual delays, the total delay is indeed at least 32ms per loop. While the code is already running quite a while without issues, I can indeed see the potential issues if combined with multiple other components.

Your approach seems interesting and from what I read in your code not too complex. I wonder if it would be possible to embed such a protocol transceiver inside my current component so from the outside (so in the yaml) users don't have to fiddle with OpenTherm data, but rather can just set numbers and read sensors :thinking:.

[Weissnix4711]

embed such a protocol transceiver inside my current component so from the outside (so in the yaml) users don't have to fiddle with OpenTherm data, but rather can just set numbers and read sensors

Yes, that should be quite easy.

I'm not sure if that would be accepted into ESPHome. But either way, if you decide to go down that route, I would certainly encourage you to publish your work so others can use it as an external component.

[khenderick]

Yeah, I've been thinking about it and I'm going to investigate the interrupt route first, to see what the possibilities are, with the main goal of native ESPHome integration.

If that would be no option or it would be unlikely that the protocol route wouldn't be accepted (as it indeed feels somewhat hack/workaround -ish), I'm definitely going to publish this PR as a stand alone component so it can be easily used.

[Weissnix4711]

Yes, hack is probably the best way to describe it.

I did hear some talk a while ago that an entire restructure of the remote components was wanted (for this reason, to create an easy way for devs to use the esp32's rmt to implement all sorts of weird protocols with little effort). The current system was created very much with IR and RF in mind more than anything else, hence also the name. That it could be used for so much more was an afterthought.

But I think that idea's been abandoned now.

Anyways, I don't know shit about interrupts or timers on ESP8266/32, but I can suggest you have a look at the existing CAN bus and tuya components as to how they handle the registration of individual sensors, buttons, switches, etc.

Also, there's a FR here: esphome/feature-requests#520 for opentherm you might want to look at, because it has a few other people's attempts to get OT working. Though most seem to have gone down the route of using either Ihor Melnyk or jpraus' libraries (again, not going to be accepted as 1. try not to use libraries whenever possible and 2. both block for long periods of time).

Also, if you want to chat on discord, matrix, whatever, lmk. I don't know if I'll be much help, but I can try lol.

[khenderick]

The code of this PR is now also available in a separate repository (khenderick/esphome-opentherm) in case users want to test it. I'll keep the repo and this PR in sync.

Note: The component on my repo contains the delay as discussed above, so might not behave well with other functionality. In my own setup, it is the only component running, and it works fine.

I didn't find the time yet for making the code async or implement the remote protocol as there's some learning for me on that topic :sweat_smile:

[PierreAronnax]

In my opinion, this integration should be hardware independent and not contain any hardware reading and writing. That way it can be used easily for other hardware that receive OpenTherm over a uart (like the Nodo-Shop OpenTherm Gateway). The actual support for the two devices should be moved to a different integration.

[khenderick]

@PierreAronnax, the device you've linked uses the OTGW firmware, which doesn't expose the raw OpenTherm data, but a higher-level protocol. For these devices there's already a native Home Assistant integration available.

[PierreAronnax]

That gateway has two processors, one PIC16F88/PIC16F1847 that uses the OTGW firmware, and one Wemos D1 mini that currently runs https://github.com/rvdbreemen/OTGW-firmware and acts as a bridge between the PIC and the native Home Assistant integration (or MQTT).

I am working on creating new firmware for the Wemos D1 mini using ESPHome. Initially only for the same bridge functionality. Eventually also exposing as sensors and services, and that's where this integration comes in.

[khenderick]

If the ESP device has indeed access to the raw OT messages and not the OTGW pre-parsed protocol, it shouldn't be too hard to extend this code to also support UART.

If you would decide to work with this code, feel free to check out khenderick/esp-opentherm which is this code as external component.

[khenderick]

I wonder if somebody from the core team could elaborate whether using a new remote transmitter protocol would be acceptable, and if so, whether the protocol definition should be inside the opentherm component folder, or in one of the remote_* folders. May I politely tag @jesserockz for this information?

[github-actions[bot]]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[khenderick]

This branch isn't stale, but I'd like to get some feedback on the best way forward here. See for example https://github.com/esphome/esphome/pull/3921#issuecomment-1369015504.

The current code is already running for many months now, working without any issues.

[khenderick]

Thanks for the feedback @jesserockz. I've made the requested changes.

I also brought the PR up-to-date with pending changes from my separate component repo. These changes include some new sensors etc, but also include a refactor to spread communication in time, getting rid of the "took a long time for an operation"-messages. I did my best to also apply your suggestions to that new code.

[github-actions[bot]]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days. Thank you for your contributions.

[khenderick]

This PR is not stale from my end.

I still hope that eventually I will get some constructive feedback and that it will get merged in. If it's unlikely this will ever be merged in, I also would like to know. To be honest, it's a bit demotivating to have a PR open for well over a year with some review feedback, but nothing about if and when it would or could be merged in.

[rotilho]

Hello @khenderick! I'm very excited about this PR; thanks for putting in the effort. I really appreciate it.

I'm not part of the esphome team, but I've worked with GitHub before and see why nobody reviewed your PR. If you don't re-request the review, the PR won't appear in the list of PRs to be reviewed. I'd also mark the previous review as closed, just in case.

Again, thank you 🙏

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 54.13%. Comparing base (4d8b5ed) to head (b510178). Report is 627 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #3921      +/-   ##
==========================================
+ Coverage   53.70%   54.13%   +0.42%     
==========================================
  Files          50       50              
  Lines        9408     9619     +211     
  Branches     1654     1698      +44     
==========================================
+ Hits         5053     5207     +154     
- Misses       4056     4086      +30     
- Partials      299      326      +27     

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[khenderick]

Hello @khenderick! I'm very excited about this PR; thanks for putting in the effort. I really appreciate it.

I'm not part of the esphome team, but I've worked with GitHub before and see why nobody reviewed your PR. If you don't re-request the review, the PR won't appear in the list of PRs to be reviewed. I'd also mark the previous review as closed, just in case.

I've re-requested the review, thanks for the tip. Hope it helps :crossed_fingers:.

Again, thank you 🙏

You're welcome :slightly_smiling_face:. In case you didn't know yet, you can already use this component directly via https://github.com/khenderick/esphome-opentherm :+1:.

[jesserockz]

https://github.com/esphome/esphome/pull/6645#issuecomment-2261656949

Please talk with the author of #6645 (and maybe #7169) and come to a concensus as to which PR we (reviewers) should spend our time on.

Please use https://github.com/esphome/esphome/discussions/7170 to discuss.