Posted on by Floris

Connected Vaillant to Home Assistant

Introduction

I bought a new Vaillant ( Hr-ketel ecoTEC plus) central heating boiler a few months back, my old boiler from 2001 still worked, but I rather had it replaced, before it broke. When ordering there was an option to make it connected with the vSMART for about €200 extra. It sounded a bit to much and saw no integration with Home Assistant (HA) directly (at that time). So I tried an alternate way.

eBUS

Vaillant uses a protocol called eBUS for external communication. This protocol is based on UART but at different voltage levels, so be able to use this protocol we need some hardware to do the translation. Although there were some solutions available online, I couldn’t find a tiny and SMD variant. This is why I decided to create my own PCB in KiCAD. My design is based on the following project: https://ebus.github.io/adapter/. My project can be found here: https://gitlab.com/fromeijn/ebuzzz-adapter

This PCB uses a USB to UART converter board with an CP2102, e.g this one. It is electrically isolated so no harmful ground loops or other issues can occur. There are also some helpfull LEDs to show you what is going on.

Home Assistant Integration

To integrate with Home Assistant I used ebusd running on an Raspberry Pi I had laying around. The ebusd has an MQTT client integrated, this is an easy way to hook it up to Home Assistant. To give you an idea how it is hooked up see this drawing below. The eBUS to USB converter board will be connected to the bus with two wires. The position of those wires doesn’t matter.

To install ebusd on Raspberry Pi OS (Raspbian) you use the following documentation from the ebusd repository: https://github.com/john30/ebusd/wiki/1.-Build-and-install

I used it in the following configuration for ebusd, there are some optional parts.

# add custom config for the VRT350 thermostat (only needed if you have VRT350)
cd /home/pi/
git clone https://github.com/john30/ebusd-configuration.git
cd ebusd-configuration/
cp ebusd-2.1.x/en/vaillant/15.370.csv ebusd-2.1.x/en/vaillant/15.350.csv

# you can change the r; at the beginning of the lines by r1; so it will be read out automatically and pushed on MQTT. If you can also poll values via MQTT, see down below for an example.

Edit /etc/default/ebusd

# Without local ebusd-configuration
EBUSD_OPTS="--scanconfig 
--mqtthost=<homeassistant_ip> --mqttport=1883 --mqttuser=<user> --mqttpass=<passwd>"

# With local ebusd-configuration
EBUSD_OPTS="--scanconfig 
--configpath=/home/pi/ebusd-configuration/ebusd-2.1.x/en --mqtthost=<homeassistant_ip> --mqttport=1883 --mqttuser=<user> --mqttpass=<passwd>"

To restart the ebusd

sudo service ebusd restart

In Home Assistant you need to have a MQTT broker setup. In my case I use Mosquitto broker addon, what can be install via the Supervisor. See the documentation of the addon. Also do not forget to add the MQTT integration into your config. I used the MQTT HVAC integration and set is up as follows:

mqtt:
  broker: core-mosquitto
  username: <your-mqtt-user>
  password: <your-mqtt-pass>
  discovery: true

climate:
  - platform: mqtt
    name: CV
    max_temp: 25
    min_temp: 15
    precision: 0.1
    temp_step: 0.5
    modes:
     - auto
     - heat
     - cool
     - 'off'
    mode_state_template: >-
      {% set values = { 'auto':'auto', 'on':'heat',  'night':'cool', 'summer':'off'} %}
      {{ values[value] if value in values.keys() else 'off' }}
    mode_state_topic:  "ebusd/350/Hc1OPMode"
    mode_command_template: >-
      {% set values = { 'auto':'auto', 'heat':'on',  'cool':'night', 'off':'summer'} %}
      {{ values[value] if value in values.keys() else 'auto' }}
    mode_command_topic: "ebusd/350/Hc1OPMode/set"
    temperature_state_topic: "ebusd/350/DisplayedHc1RoomTempDesired"
    temperature_low_state_topic: "ebusd/350/Hc1NightTemp"
    temperature_high_state_topic: "ebusd/350/Hc1DayTemp"
    temperature_low_command_topic: "ebusd/350/Hc1NightTemp/set"
    temperature_high_command_topic: "ebusd/350/Hc1DayTemp/set"
    current_temperature_topic: "ebusd/350/DisplayedRoomTemp"

Tip: Use MQTT Explorer if you are having problems getting MQTT to work between HA and ebusd.

Automations

When having home assistant and ebusd connected we can start automating things and let the computer do stuff for us. I have configured a google calendar in which I can plan my normal heating schedule. But this only is enabled when i’m home, and turns off when I leave the house.

Heater on/off on calendar automation

alias: Heater on/off on calendar
description: ''
trigger:
  - entity_id: calendar.heater
    platform: state
  - entity_id: binary_sensor.people_home
    platform: state
    to: 'on'
condition:
  - condition: state
    entity_id: binary_sensor.people_home
    state: 'on'
  - condition: template
    value_template: '{{ not is_state("climate.heater", "off") }}'
action:
  - choose:
      - conditions:
          - condition: state
            entity_id: calendar.heater
            state: 'on'
        sequence:
          - service: climate.set_hvac_mode
            data:
              hvac_mode: heat
            entity_id: climate.heater
    default:
      - service: climate.set_hvac_mode
        data:
          hvac_mode: cool
        entity_id: climate.heater
mode: single

Heater low when nobody home automation 

alias: Heater low when nobody home
description: ''
trigger:
  - entity_id: binary_sensor.people_home
    from: 'on'
    platform: state
    to: 'off'
    for: '00:05:00'
condition: []
action:
  - data:
      hvac_mode: cool
    entity_id: climate.heater
    service: climate.set_hvac_mode
mode: single

Poll WaterPressure from bai over ebus

alias: Poll WaterPressure from bai over ebus
description: ''
trigger:
  - platform: time_pattern
    minutes: /1
condition: []
action:
  - service: mqtt.publish
    data:
      topic: ebusd/bai/WaterPressure/get
mode: single

we also want a sensor to receive this data, add this to your configuration.yaml

sensor:
  - platform: mqtt
    name: "Water Pressure CV"
    state_topic: "ebusd/bai/WaterPressure"
    unit_of_measurement: 'bar'
    value_template: "{{ value.split(';')[0] }}"

Conclusion

With this integration we can control the temperature remotely or automatically. I’ve added presence detection and a google calendar so no energy is wasted which is a big plus for me. This project was fun to get my home automation kick stared and I learned something one the way. Hope this helps some of you as well!

Boards (un)available

Unfortunately I have decided to stop my production of these board. If you want to build your own see https://gitlab.com/fromeijn/ebuzzz-adapter

67 Replies to “Connected Vaillant to Home Assistant”

  2. Hey Chris,

    I do have some PCB’s and parts, so if you want I can make one and send it to you. Do you want to solder them yourself?

    Reply

  3. Hi Floris,

    nice job! I’ve just got around to connecting my Vaillant EcoTec Plus heater to Home Assistant.
    Thank you for sharing your configuration. I will definitly use parts of your configuration.

    Reply

    1. Wow. Looks really nice. Possible to purchase one? 🙂 I really want to know what the f.. is going om within my heatpump, and the APP is completely rubbish!

      Reply

  4. Hello Floris,

    I’m Dirk from Belgium, I am also interested in this project.
    I have a ecoVIT VKK SWE 366/4 with a actoSTOR VIH K 300 ‘Boiler’, we have a calorMATIC 430f thermostat.

    Inside of the VKK366
    https://photos.app.goo.gl/DjjkBmPLUHEhxo4N7

    I am wondering if this would work with my installation also, if this is true then I’m interested in the pcb and components, soldering is no problem.

    Alvast bedankt!
    Dirk

    Reply

  5. Looks quite elegant indeed. Have a Brink B16HRD air heater which communicates with its thermostat using that eBUS protocol. Also got a Rarpberry Pi 3B+ with Domoticz, MQTT and Node Red running. I would like to more closely monitor that Brink air heater in order to verify its parameters ans possibly optimize those.
    So your eBUS PCB, a UART and the ebusd daemon on the Pi ought to be able to publish eBUS data to MQTT. With Node Red it would be easy to filter and channel the data towards Domoticz virtual devices for display.
    Given the 2 optocouplers this board provides bidirectional albeit simplex communication. Does it support the Wemos extension board?
    Makes me wonder if you still have such board available?
    If so please contact me. Of course some reimbursement for your costs will be in order.

    Reply

    1. No the board has no Wemos support, you can probably also interface directly on a raspberry pi or some sorts, with the ebusd via other options. I will make a few boards this month, and will contact if you when it’s ready, i am waiting for a few parts.

      Reply

    2. Hello Joep,

      I just read your comment. I have a Brink Allure 16 Downflow air heater as well.
      I am looking al around the internet if some has ever managed to connect with the heater via ebusd.
      I didn’t find the confidence yet to order a Ebus board and try it out myself without knowing if it will work at all.

      Can you tell me how far you are with your setup?

      Roy

      Reply

  6. I have integrated Vailant gas boiler from 2002 with netatmo and then did HA integration. It works perfectly. Now, I don’t care did I turn off heating as HA know when I’m at home.

    Reply

  7. Hi Floris,

    I’ve build one of your PCB’s and I can confirm that the ebus part is working. But I only get device info and the date/time of the thermostat (vrt350). I have a ecoTEC VHR 30-34/5-5 heatpump. Are you using a thermostat? And how do you write to ebus? Have you changed the CSV files?

    Thanks in advance!

    Corjan

    Reply

    1. Hey Corjan,

      I have the same thermostat, i forgot to mention that I changed the config a bit. I have used the 370 thermostat config for the 350, do not aks why but it works. so do the follwing:

      cd /home/pi/
      git clone https://github.com/john30/ebusd-configuration.git
      cd ebusd-configuration/
      cp ebusd-2.1.x/en/vaillant/15.370.csv ebusd-2.1.x/en/vaillant/15.350.csv

      you can change the r; at the beginning of the lines by r1; so it will be read out automatically

      write is done via MQTT via the ebusd/350/Hc1OPMode/set topic

      Reply

  8. Helo Floris

    Really nice job, I am looking for a Vaillant Boiler integration and your solution looks pretty good, where can I buy your PCB to get it to Spain? Could you provide it? regards.

    Reply

  9. Hey Floris

    I was very excited reading what you’ve done, awesome job! I too am interested in the PCB and purchasing one if possible or if you can point me in the right direction for pets that would be greatly appreciated.

    Looking forward to integrating my boiler soon.

    Reply

  13. Hey Floris,

    cool project 🙂 Is there a chance you have some leftover PCB lying around? I will be interested in buying one. Preferably with components – I can do soldering on my own.
    Please let me know.

    All the best,
    Jan

    Reply

  14. Hi Floris,
    Do you have PCBs to sell me or PCBs design no share?
    Pls email me, trying to connect ebus of my heating pump.
    BR,
    Gonçalo

    Reply

  15. Hey all, I have made an updated version of this board (can also be found on Gitlab). I’m trying to setup a small web shop but it’s not working yet. I have a few boards build and tested, please contact me if you are interested (see contact page). I sell them for €20 euro’s each and ships to Europe for €3,10.

    Reply

  16. Anyone already tried to stick an ESP32 module onto this board, my older Valliant boiler from 2010 has and ebus connection but it’s to far from my home assistant setup. I’m a zero in electronics, so … anybody has an idea how this can be done?

    Reply

      1. Hello Floris,

        Please let me know if you would like to create the ESP32 board. I’m intersected to buy one and test on my Saunier Duval Thema Condens.

        Thanks in advance!
        Regrads,
        Bogdan

        Reply

  17. Hello, nice project, thanks for sharing! I found your article while looking at solution to connect my Vaillant boiler to my future HA install (I just moved in into a new house).

    Does this allow you to fully control your boiler (heaters & domestic hot water)? Is it as complete as the proprietary solution sold by Vaillant (vSmart or even the newer multimatic)? When you set temperature or schedule instructions into HA, does it reflect in the thermostat of your Vaillant boiler?

    If so, I would be interested in buying a “plug & play” board, do you still have some in stock? Am I correct in saying that I will just have to plug connect the ebus wires to the board, and then plug the board into a USB port of a Raspberry Pi running ebusd? What model of Raspberry Pi do you recommend?

    Thank you!

    Reply

    1. Hey William, yes as far as I am aware. I can set the temperature from two places, with my Home Assistant or with the my thermostat (VRT350). Changes by HA is reflected on the display on my thermostat.

      I am using a Raspberry Pi 3, but I think lower will do as well. I have heard some people have issues with the Raspberry Pi Zero W and USB, but I haven’t tested that.

      I still have assembled and tested boards available, you can contact me directly (via contact form) or buy them via tindie.com : https://www.tindie.com/products/foxrom/ebus-usb-adapter-ebuzzz-adapter

      Reply

  18. Hello Floris,
    I recieved your adapter few days ago, connected it to my VWZ Heat pump, with Multimatic VRC 700 and MEH 61 boiler/mixer and it is working flawlessly on first try. Thank you for this awesome board.

    I just struggled a bit setting up the ebusd, the HA integration is limited so I went the MQTT route all the way.
    I am mainly using the VRC 700 circuit as it has all the info. HMU circuit is just for the current state of the heat pump and compressor modulation.

    Someone in the comment above asked if when anything is set on the termostat itself, if it is reflected in the HA/MQTT.
    I can confirm that at least with the VRC 700 this works. However when using MQTT you need to be polling the data manually for each topic. VRC 700 doesn’t automatically publish the changes, thus they are not available on MQTT.

    I set up an automation which polls these values 30 seconds from the thermostat via MQTT.
    So for example to read the current temperature set on the thermostat I use topic: “ebusd/700/z1ActualRoomTempDesired” , but for this value to be automatically updated, the topic “ebusd/700/z1ActualRoomTempDesired/get” needs to be called repeatedly to poll the value.

    These values are then used in the “climate” component in HA. Now if I set the new temp on the termostat, it takes at most 30 seconds and the correct value shows in HA.

    These are the values I am currently grabbing from ebus: https://i.imgur.com/FR2ScfI.png

    Reply

    1. Hey Jaroslav,

      Great to hear you got it working! About polling of values, you can use custom configurations see https://github.com/john30/ebusd-configuration.git You can edit the file for your VRC 700 and change the “r” on the beginning of the line to something like “r1” so automatically poll it for you. ( https://github.com/john30/ebusd-configuration/blob/master/ebusd-2.1.x/en/vaillant/15.700.csv ) You can probably also do this for your HMU.

      Reply

      1. Thank you for the info.. yes I think I found this in the docs after I set the MQTT up, but there has been some version mismatch since the latest v21.1 (looks like the versioning scheme changed this year) and it always says there is a new version and it also complained about wrong version of config files when I downloaded them from the github (I used the ebusd-2.1.x as that’s what is in the latest folder), I guess it worked anyway but since I had to figure out how all the ebus and configurations work first I didn’t want to take a chance of having more problems.

        Now seeing this I will probably set the “r1” for the realtime values I need for the climate but I will keep the MQTT /get for other values like Energy Consumption since that needs to get updated only once a day and the config with “r9” only allows 45 seconds with poll interval of 5secs and I don’t want to clutter the bus when it’s not needed.

        Reply

    2. Hello Jaroslav,
      I just got the board (Floris: thank you, you did an amazing work!) and connected it.
      I own a VRC700 too
      , could you share the yaml sections involved? climate and automation?

      Great compliments to all!

      Riccardo

      Reply

  19. Hi Floris,
    I recieved your adapter yesterday and today all works great. I have Vaillant ecoTec boiler and thermostat VRC 720. Good job.
    Thx

    Reply

    1. Hi Jaroslav,

      I have the saem heater and struggle to implement it in HA. Would you mind to share your configuration.yaml?

      Thanks

      Christian

      Reply

      1. Hey all infromation regarding the configuration.yaml should be here, did you add your mqtt broker info also?

        Reply

  20. Hi Floris,
    Very interesting article and very good work! Could you please publish a BOM file. Thanks for your work!

    Reply

  21. I tried buying one of your usb ebus adaptors and it said it cannot be shipped to my country (UK)…. how come?

    Reply

  23. Hi Floris,

    First thanks for the initiative.
    I have also a vaillant system and I would like to be able to remotely control the heat pump setting.
    I received ebus-usb-adapter-ebuzzz-adapter. But it does not seems so easy to integrate.
    I’m a novice in Homeassistant and I failed to properly install ebusd.
    I have a raspberry 3B+.
    First which version of home assistant should I use (Home Assistant Operating System or Home Assistant Core)?
    I tried both versions, but :
    1. I don’t know how to install ebusd with Home Assistant Operating System.
    2. I tried the other method by installing Debian first in the raspberry. Then I can install ebusd, but I do not manage to start the service.
    Tanks for your help.
    Regards,
    Stéphane

    Reply

  24. I bought two ebuzzz adapters, and they work fine, very easy to set up. I just have one open issue: I have two separate heating systems, each with its own ebus/thermostat. I have set up two gateways, each with its own mqtt topic. I configured homeassistant like this:

    climate:
    – platform: mqtt
    name: Heating Office
    modes:
    – auto
    – heat
    – cool
    – ‘off’
    mode_state_template: >-
    {% set values = { ‘auto’:’auto’, ‘on’:’heat’, ‘night’:’cool’, ‘summer’:’off’} %}
    {{ values[value] if value in values.keys() else ‘off’ }}
    mode_command_topic: “convert/modeset”
    mode_state_topic: “ebusd/350/Hc1OPMode”
    temperature_state_topic: “ebusd/350/DisplayedHc1RoomTempDesired”
    temperature_low_state_topic: “ebusd/350/Hc1NightTemp”
    temperature_high_state_topic: “ebusd/350/Hc1DayTemp”
    temperature_low_command_topic: “ebusd/350/Hc1NightTemp/set”
    temperature_high_command_topic: “ebusd/350/Hc1DayTemp/set”
    current_temperature_topic: “ebusd/350/DisplayedRoomTemp”

    – platform: mqtt
    name: Heating Cafetaria
    modes:
    – auto
    – heat
    – cool
    – ‘off’
    mode_state_template: >-
    {% set values = { ‘auto’:’auto’, ‘on’:’heat’, ‘night’:’cool’, ‘summer’:’off’} %}
    {{ values[value] if value in values.keys() else ‘off’ }}
    mode_command_topic: “convert/modeset”
    mode_state_topic: “ebusd/351/Hc1OPMode”
    temperature_state_topic: “ebusd/351/DisplayedHc1RoomTempDesired”
    temperature_low_state_topic: “ebusd/351/Hc1NightTemp”
    temperature_high_state_topic: “ebusd/351/Hc1DayTemp”
    temperature_low_command_topic: “ebusd/351/Hc1NightTemp/set”
    temperature_high_command_topic: “ebusd/351/Hc1DayTemp/set”
    current_temperature_topic: “ebusd/351/DisplayedRoomTemp”

    This works fine for the temperatures, but when I change the mode of the second one (Cafetaria), the mode of the first one Office) is changed. I suppose it has to do with the translation (convert/modeset) setting the wrong topic on mqtt. Do you know where that is configured?

    Reply

    1. Hey Kelly,

      Thanks for your question, I was not sure why I did not do it like this at the time, but now I also added a “mode_command_template”.
      So now the extra automation to do the mode conversion is no longer required. So in your case you need to add/replace the following:

      mode_command_template: >-
      {% set values = { 'auto':'auto', 'heat':'on', 'cool':'night', 'off':'summer'} %}
      {{ values[value] if value in values.keys() else 'auto' }}
      mode_command_topic: "ebusd/350/Hc1OPMode/set"

      and

      mode_command_template: >-
      {% set values = { 'auto':'auto', 'heat':'on', 'cool':'night', 'off':'summer'} %}
      {{ values[value] if value in values.keys() else 'auto' }}
      mode_command_topic: "ebusd/351/Hc1OPMode/set"

      Hope that helps!

      Kind regards

      Reply

  25. Well, it’s different but I’m not sure it’s better 🙂

    I replaced mode_state_template by the new mode_command_template.
    Now I can indeed control both heaters, but I don’t get any feedback anymore. All 4 mode icons are grey and when I click one nothing happens in the visualisation. Using an MQTT client I can see that the correct mode is set (and read back) so it does work.

    I suppose this is because HA can’t map the state back to a mode, so I tried adding the mode_state_template again but that gives me an error when validating the configuration:

    Invalid config for [climate.mqtt]: invalid template (TemplateSyntaxError: unexpected char ‘‘’ at 18) for dictionary value @ data[‘mode_state_template’]. Got ‘{% set values = { ‘auto’:’auto’, ‘on’:’heat’, ‘night’:’cool’, ‘summer’:’off’} %} {{ values[value] if value in values.keys() else ‘off’ }}’. (See ?, line ?).

    The second heater also doesn’t show any temperatures anymore, and that worked fine with the state_template.
    So not completely there yet. Can you still see the modes when only using the command_template?

    Reply

  26. Never mind, I copy-pasted the mode_state_template from this page again and the ‘ got translated. After cleanup it seems to work, although at the same time I seem to have lost my second raspberry (which explains why the second heater doesn’t respond anymore) So it’s probably fine, thank you for your assistance!

    Reply

  27. Hey folks. This is a very exciting post.
    I am new to Home Assistant, and Have Vaillant boiler and USB adapter.
    My PI has HA OS installed, I have accessed via Terminal&SSH to give it the command:
    git clone https://github.com/john30/ebusd-configuration.git

    It now looks like it has copied it onto my PI. But I don’t know how to start the software.

    Could anyone explain in basic terms what to do next

    tx
    J

    Reply

    1. Hey JJ,

      ebusd is automatically started as a service, but restarting can be done by sudo service ebusd restart

      Reply

  30. Hey Floris!

    Congrats on the success story here 🙂 Any chance you’ll be re-stocking soon? I’d gladly pay a bit more than the market price.

    Reply

  32. Hi all
    I have connected my boiler Vaillant with VRC700 by ebus adapter to HA.
    I created as in this article thermostat to control settings heating… but it no working…. No change mode and no show status mode…. This icon from mode are grey….
    My code looks like this….
    For thermostat i need 4 mode: off, auto, day and night. This status is show on my VRC700 on ebusd/700/z2OPMode
    Please help me why status is not refresh and not change.
    https://pastebin.com/bFrnmRsz

    Reply

  33. Hi – I just got this adapter setup on a Raspberry Pi Zero W. When using ebusd I get this error – anyone seen this?

    2021-12-29 17:03:20.680 [main notice] ebusd 21.3.v21.3-130-g13221e2 started with auto scan on device /dev/ttyUSB0
    2021-12-29 17:03:21.043 [bus error] unable to open /dev/ttyUSB0: ERR: element not found
    2021-12-29 17:03:21.045 [bus notice] bus started with own address 31/36
    2021-12-29 17:03:21.045 [bus notice] device invalid
    2021-12-29 17:03:26.046 [bus error] unable to open /dev/ttyUSB0: ERR: element not found

    Reply

  35. Hi Floris,
    pretty awesome project!
    What bothers me a bit is a second computer. I would like to run ebusd on my server where all other services are running. Then a Raspberry Pi would be pretty overpowered just to be a WLAN bridge.
    Would it be possible to connect your adapter, either without or with customizations, to an ESP without similar?
    Kind regards
    Sören

    Reply

  36. Hey! Great implementation. I do struggle a bit, because I don’t really know where I would connect to the ebus.
    Can you give clarification, where and how you connected to it?
    Thanks!

    Reply

  37. I still have a working adapter from Fromeijn, i’m going to move to another house..
    If someone is in the netherlands, let me know i’d like to sell you mine or it will be expensive e-waste again..

    Reply

    1. Hello Gerard,
      I am interested to buy your adapter.
      Would you be so kind to tell me what you want for it?
      I am situated in Zuid Holland. I can pick it up if it is nearby.

      Reply

    3. I’m running into this post by accident.
      Is your offer to sell een ebus adapter still valid?
      Regards
      Rob

      Reply

  39. Your post discusses the potential of leveraging e-commerce platforms to sell products and generate income. It’s a booming industry with immense opportunities. For more details, click here.

    Reply

  40. Hi Floris,

    Thx for the excellent guidelines. I managed to get the ebus values in HA but I would like to have a thermostat card (like nest thermostat) as you displayed. How did you get that?

    Kind regards,
    Peter

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *