Introduction

At first, do not get confused, KM217 and KM271 ist the same, I just had a number swap in and it is simply impossible to change all the historic stuff and naming 🙁

If you ordered the module described in Reverse Engineering the Buderus KM271 – And Making It WiFi-Flying on ESPhome and Home Assistant from my Tindie store or built it on your own, this is the place to search for, when it comes to getting it up and running. This article is based on the Version 0.0.5.

The Hardware

To make your life easier for aseembly and to find the parts and signals, here is the interactie BOM.

The Software

There is a ton of software alternatives for the board, but I’ll only describe three of them in more detail. You can select the firmware when you order the board.

Default, no FW selected: Blinkenlights

At first, I’ll just tell you, what is on the board, when you did not select any firmware during your order on Tindie. It is a simple test program, that ensures, that the ESP32 and the LEDs are working.

It does nothing more than rolling through the 4 LEDs on the board.

It will be possibly extended in future to catch hardware and assembly bugs, should they arise in future.

You can find it on GitLab. Use VSCode with PlatformIO to open, compile and flash it. This is also a very nice foundation for developing your own firmware.

Flashing can be done, by connecting power, ground, RX and TX. IO0 and EN is not needed and can be triggered with the buttons. Press BOOT and keep it pressed, shortly press RESET and start your flash tool. Then release BOOT and flashing will start.

I’ll possibly improve the Blinkenlight to be able to update the board via WiFi or BLE. If you feel responsible to do this, I would be happy to take the pull request. If I get a working firmware, the minimal thing I would do is refunding the board you bought from me 🙂

Sven’s great MQTT-firmware

Sven published a firmware on GitHub for my module that speaks MQTT on the network. This was probably the most complete piece of code for my module before JEns accepted the challenge on the ESPhome part. The „only thing“ you need to do is installing VSCode and the PlatformIO addon, set the credentials for WiFi, MQTT and OTA (in include/Credentials.h), compile and flash it to the board.

ESPhome

If you selected ESPhome, you will get the latest ESPhome firmware version for this board. Currently, the features are very limited and I need to still do some work on it. But you can already connect your board to your ESPhome instance with the follwing steps.

Update (2022-12-06)

The Firmware is almost complete. Writing values that are not yet integrated can be done easily with template sensors and a few lines of lambda. I’m fascinated about the community and especially Jens and Bascht. This is, why I love open hardware and open source!!!

Update (2022-11-26)

I just received some Pull-Request on the ESPhome component from Jens and now, some of the sensors are nicely integrated. It is still missing the write feature to control the heating, but you can already get the most releveant data from your heating system.

Diggers Full Example YAML (Drop Down Accordeon)

esphome:
  name: buderus-km217
  platform: ESP32
  board: esp32dev

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:
  password: "XYZ"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_pass

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Fallback Hotspot"
    password: "XXX"

captive_portal:

uart:
  id: uart_bus
  tx_pin: GPIO2
  rx_pin: GPIO4
  baud_rate: 2400

external_components:
#  - source:
#      type: local
#      path: my_components/components
#    components: [ km271_wifi ]
  - source: github://the78mole/esphome_components@main
    components: [ km271_wifi ]
 

km271_wifi:
  - id: budoil
    uart_id: uart_bus

status_led:
  id: ledgn1
  pin: 
    number: GPIO21
    inverted: true

number:
  - platform: km271_wifi
    warm_water_temperature:
      name: "Warmwassersolltemperatur Tag"

select:
  - platform: template
    name: "Warmwasser Betriebsart"
    id: warmwasser_betriebsart
    entity_category: config
    optimistic: true
    options:
      - Dauerhaft aus (0)
      - Dauerhaft ein (1)
      - Automatik (2)
    initial_option: Automatik (2)
    set_action: 
      - lambda:
          auto index = id(warmwasser_betriebsart).index_of(x);
          if (index.has_value()) {
            uint8_t command[] = {0x0C, 0x0E, (uint8_t)index.value(), 0x65, 0x65, 0x65, 0x65, 0x65};
            budoil->writer.enqueueTelegram(command, 8);
          }

binary_sensor:
  - platform: km271_wifi
    boiler_error:
      name: "KM271 Kesselfehler"
    boiler_running:
      name: "KM271 Kesselbetrieb"
    load_pump_running:
      name: "KM271 Ladepumpe"

sensor:
  - platform: km271_wifi
    heating_circuit_1_flow_target_temperature:
      name: "KM271 Vorlaufsolltemperatur"
    heating_circuit_1_flow_temperature:
      name: "KM271 Vorlauftemperatur"
    hot_water_target_temperature:
      name: "KM271 Warmwassersolltemperatur"
    hot_water_temperature:
      name: "KM271 Warmwassertemperatur"
    boiler_target_temperature:
      name: "KM271 Kesselvorlaufsolltemperatur"
    boiler_temperature:
      name: "KM271 Kesselvorlauftemperatur"
    outdoor_temperature:
      name: "KM271 Außentemperatur"
    heating_circuit_1_room_target_temperature:
      name: "KM271 Raumsolltemperatur"
    heating_circuit_1_curve_n10:
      name: "KM271 Heizkurve -10 °C"
    heating_circuit_1_curve_0:
      name: "KM271 Heizkurve 0 °C"
    heating_circuit_1_curve_p10:
      name: "KM271 Heizkurve +10 °C"
    boiler_turn_on_temperature:
      name: "KM271 Brennereinschalttemperatur"
    boiler_turn_off_temperature:
      name: "KM271 Brennerausschalttemperatur"

  - platform: wifi_signal
    name: "KM217 WiFi Signal Sensor"
    update_interval: 60s

  - platform: adc
    pin: 36
    unit_of_measurement: "V"
    name: "KM217 5V Supply"
    accuracy_decimals: 2
    update_interval: 5s
    attenuation: 6dB
    filters:
      - multiply: 27.7317
      - throttle_average: 60s
      
switch:
  - platform: gpio
    name: LED2_Green
    pin: 
      number: 22
      mode: OUTPUT
      inverted: true
  - platform: gpio
    name: LED3_Yellow
    pin: 
      number: 23
      mode: OUTPUT
      inverted: true
  - platform: gpio
    name: LED4_Red
    pin: 
      number: 25
      mode: OUTPUT
      inverted: true

Connecting to the board

I configured the ESPhome firmware to run a captive portal after approx one minute. So, after powering the board, you could (after one minute) connect to the SSID „Fallback Hotspot“. Turn of your cellular internet (it disturbs the WiFi very often) and select the Fallback (password is "Z8zfajgxVvNw"). When WiFi of your phone is connected (sometimes you need some tries), a pop-up should ask you to sign in to the network. Follow this. It will present the portal of the ESPhome firmware and show you all WiFis it has found. Select the appropriate one and enter the password of this WiFi.

You have two choices. Flash another firmware through OTA or join your domestic WiFi. If joining was successful and your board connects to the network, it will show up in Home Assistant (ESPhome) after some time. If you then enter the right config (especially the passphrase for OTA ("c38c9fd48a1afe7a76834cc5721c5c46") and the credentials for your WiFi), you could simply start over with your KM271-WiFi-Stuff.

The relevant part of the YAML is as follows:

esphome:
  name: km217-for-friends
  platform: ESP32
  board: esp32dev

# Enable logging
logger:

# Enable Home Assistant API
api:

ota:
  password: "c38c9fd48a1afe7a76834cc5721c5c46"

wifi:
  ssid: "<YOUR WIFI SSID>"
  password: "<YOUR WIFI PASSPHRASE>"

  # Enable fallback hotspot (captive portal) in case wifi connection fails
  ap:
    ssid: "Fallback Hotspot"
    password: "Z8zfajgxVvNw"

Other Settings

Renaming the module should be done using ESPhome GUI

For more detailed information, see my blog about the development of the module.

Using Arduino with MQTT

Coming soon 🙂