Optolink platform to integrate Viessmann heating units into Home Assistant

[j0ta29]

What does this implement/fix?

Monitor and control your Viessmann heating components via an Optolink adapter controlled by ESP microcontroller

Types of changes

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

Related issue or feature (if applicable): N/A

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

Test Environment

• ESP32
• ESP32 IDF
• ESP8266
• RP2040

Example entry for config.yaml:

optolink:
  protocol: P300

sensor:
  - platform: optolink
    name: Boiler Temperature
    address: 0xA309
    bytes: 2
    div_ratio: 100
    unit_of_measurement: °C
    device_class: temperature

binary_sensor:
  - platform: optolink
    name: Disturbance
    address: 0x0A82

text_sensor:
  - platform: optolink
    name: Error history 1
    address: 0x7590
    bytes: 9
    type: RAW
    
text:
  - platform: optolink
     name: Warm water schedule Monday
     address: 0x2100
     bytes: 56
     type: DAY_SCHEDULE
     day_of_week: MONDAY
     icon: mdi:shower

number:
  - platform: optolink
    name: Room Temperature Setpoint
    unit_of_measurement: °C
    address: 0x2306
    bytes: 1
    min_value: 3
    max_value: 37
    step: 1
    mode: box
    icon: "mdi:home-thermometer"
    device_class: temperature

switch:
  - platform: optolink
    name: Economy mode
    address: 0x2302
    icon: mdi:sprout-outline

select:
  - platform: optolink
    name: Operation mode
    address: 0x2323
    bytes: 1
    map:
      - "0 -> Off"
      - "1 -> Only hot water"
      - "2 -> Heating and hot water"

Checklist:

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

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

• Documentation added/updated in esphome-docs.

[probot-esphome]

Hey there @j0ta29,
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 = ["@j0ta29"]

And run script/build_codeowners.py

_{^{(message by NeedsCodeownersLabel)}}

[tunip]

@j0ta29 how do you connect the Optolink adapter to the ESP? I would like to help with testing, but I only have a USB adapter with vcontrold in use.

[j0ta29]

@tunip , thanks for offering help. I'm still working on the documentation, where I plan to integrate information for the hardware stuff.
The USB adapter unfortunately is the wrong piece of hardware. The USB-Port of the ESP is blocked for power supply, so
I built a simple adapter with two LEDs (TX and RX) and two resistors compared to that documented in the OpenV-Wiki (unfortunately only in German language). The parts only cost a few cents. I had to replace the "SFH-487" with a "SIR 204 EVL" because first is out of stock.

[esphome]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[j0ta29]

@jesserockz , thanks for your review and feedback.

I started going through this PR and got to a part that does API subscriptions for states from HA. This is not the right way to do things. If I understand it correctly, it is reading a schedule from a input_text entity in HA.

Yes, that is correct.

If this is the case, this component should be modified to provide its own text entities to HA that will give the best experience for everyone and not need extra code to subscribe to HA states etc inside this component.

You mean the Text Components invented in release 2023.11?
If yes, this seems to be a great improvement. That was the missing piece when I started working on backward sync from HA to ESPHome in autumn last year. I was looking for something like number/switch/select to send back text data to ESPHome. Unfortunately I missed reading the change log of that release.
I will rewrite that piece of code.
By the way: Are there any plans to invent a schedule entity in ESPHome to sync back data from HA to ESPHome? ;-)

[adorobis]

By the way: Are there any plans to invent a schedule entity in ESPHome to sync back data from HA to ESPHome? ;-)

Esphome is one thing but there is no relevant entity type in HA to sync from...

[j0ta29]

Esphome is one thing but there is no relevant entity type in HA to sync from...

@adorobis , what about that? -> https://www.home-assistant.io/integrations/schedule/

[adorobis]

what about that? -> https://www.home-assistant.io/integrations/schedule/

Oh, interesting. I didn't know it existed :) A bit limited though - only on/off for a weekly schedule as far as I can see. But for thermostat type of schedule should be good enough.

[j0ta29]

----------- ========= BREAKING CHANGES ========= -----------

text_sensor configuration attribute mode is renamed to type.

text_sensorof type DAY_SCHEDULE_SYNCHRONIZED is discontinued. Replace it with a text of type DAY_SCHEDULE.

Refer to updated PR documentation https://deploy-preview-2737--esphome.netlify.app/components/optolink

[jesserockz]

@j0ta29

By the way: Are there any plans to invent a schedule entity in ESPHome to sync back data from HA to ESPHome? ;-)

Date entities were recently added (#6191), and I have an open PR (#6399) for Time entities too. This will be followed by a datetime entity when time permits.

The schedule entity in HA is not something that can be used directly by ESPHome, it's state is on or off, and only exposes the next event time as an attribute.

[rorso]

I'm trying to figure out, whether/how I could access the daily schedule of my warm water production on my Vitocal 333. These datapoints are separate per day and values are 24 bytes.

In the controller I can set 4 different values for every hour. The documentation states "5+3" with 5-bit hour and 3 bit minutes in 15min raster. This seems not right, as I can set only one value per hour and the "value" has to be encoded there. I assume the last 3 (2?) Bits are the value 0-3.

However, I found no way to really glimpse at those values, as none of the options allows me to read a 24 Byte record and display any value, not even the unaltered hex bytes.

Is it possible to get a RAW (HEX/DEBUG) return as Text(?) without limiting the possible values to either 9 (text_sensor / RAW) or 56 (DAY_SCHEDULE)?

Maybe the high-level OptoLink component is not the optimal tool to explore uncharted voids in datapoint land, but I have just that piece of hardware.

[j0ta29]

@rorso

In the controller I can set 4 different values for every hour. The documentation states "5+3" with 5-bit hour and 3 bit minutes in 15min raster. This seems not right, as I can set only one value per hour and the "value" has to be encoded there. I assume the last 3 (2?) Bits are the value 0-3.

I also suspect that the documentation „5+3“ is wrong. In my version of ecnEventType.xml there is a statement „every quarter of an hour gets 2 bits“. These two bits encode the operation mode.
This would result in one byte per hour, 24 bytes per day and 168 bytes per week. This corresponds to the documented size of the datapoint.

Try to configure a sensor with 4 byte and the address of the datapoint and you should get the time slot 0:00 AM to 4:00 AM of Monday.

Feel free to open a pull request at https://github.com/j0ta29/esphome/issues so we can add support for 168 byte schedules and continue the discussion at that place.

[rorso]

Try to configure a sensor with 4 byte and the address of the datapoint and you should get the time slot 0:00 AM to 4:00 AM of Monday.

I was not aware that I can request smaller or bigger byte length than documented. The individual weekdays have their own datapoints from 0x901c to 0x9022 (MO to SU), 24 bytes each.

I try and report back for verification with the known values.

I seem to refer to the same exnEventType table but interpreted the values wrongly.

---

did not work out. :-(

  - platform: optolink
    name: schedule_ww_su
    address: 0x9022
    bytes: 4

does compile, but is rejected from the interface. I presume, length "4" is not supported with this datapoint (is defined as 24)

I cannot set bytes to "24", as this does not compile - would result in a HUGE integer...

I guess, I have to poke around with other software, as the component is not meant to request arbitrary length from arbitrary address to get "raw" data for debugging purpose.

I tried the VitoWIFI documentation but this has limited examples too. Nothing larger than 4 Bytes.

[pyzimmer]

@adorobis I try this , but it does not work.

With this, I got no more sensors and no more log :

esphome:
on_boot:
priority: 200
then:
- lambda: |-
delay(xxxx);

This didnt do anything , I think it is an aynchronous timer :

esphome:
on_boot:
priority: 200
then:
- delay 60s