Reverse Engineering the Buderus KM271 – And Making It WiFi-Flying on ESPhome and Home Assistant

Reverse Engineering the Buderus KM271 – And Making It WiFi-Flying on ESPhome and Home Assistant

The PCB for this project was sponsored by PCBway.

And I really liked what I received. I ordered a few times in the past and always received excellent PCBs from this manufacturer. And also the engineering service is best in class. They ask you what to do, if any problem occurs and either you send new gerbers or they fix it themselves (if possible by editing the gerber). Sooner or later, I’m sure, I’ll also try their assembly and milling services…

If you want to read an article about preparing your data for PCBway, stay tuned, it will be also linked here.

If you tend to skip sections and go to the action part, please look out for the fixes section in this post. They are needed to make the board work at all.

Current Version is V0.0.4 (see Changelog close to the end of this blog post)

Update (2022-05-22): I’m again working on the ESPhome implementation. If you want to live on the edge, have a look at the GitHub repository.

Motivation

As you all know, my home is stuffed with more sensors than the ISS, but I still have some heating installation burning oil… and it stops working quite often (approx. once a week), raising an error from the flame sensor that easily can be commited and everything is working fine for the next days or weeks. In summer-time this is only nasty, and sometimes when I want to take a shower, I realize, that there is no hot water left, the boiler decided to raise an error and I (a) need to wait for the water to heat up or (b) need to take a cold shower if I’m in a hurry… In wintertime, this is worse, because not only the hot water, but also the whole heating is stopped. Not a satisfiying situation 🙁

While I’m planning to renovate the house and switch to some heat pump installation, there is still plenty of time to take cold showers. If I only would know that the heating has an error in advance or when the error just have been raised… For sure, I could simply attach some binary sensor to the flame detector and make an alarm bell ring, by using some analog interface or simply a 230 VAC relay. But this would be way too easy…

My heating system is running a Buderus Logamatic 2107 M main control unit and this has some free slot for a so called KM271 communication module… In my control unit, it is unpopulated 🙁

Here are some additional information that helped me to dig through:

Remote Reverse Engineering

Since I have no KM217 available, I need to do the reverse engineering without some real hardware. For sure I could buy one, but the effort to dongle it to my smart home would not be much less and I don’t want to spend 100 € for a nasty level converter and some chicken feed, only because it has the buderus sign on it…

OK, I found some pictures online of top and bottom sides of the original KM271 module. Then I compared my measurements of the slot inside the LM 2107 with the sizes from the photos and started to draw the PCB outline…

Some handy online tool to take measurements out of photos can be found here.

What you can also see on the photo is the main IC on this board, namely the LT1281ACSW (datasheet), which is a simple 5V-to-EIA/RS-232 level converter. From it’s datasheet, we can see, what are the supply pins and which are the relevant signals. The FG-Connector is just to wire an exhaust probe head, which is irrelevant for us.

LT1281A

Tracing some signals…

Tracing REC2 Out (RX input of Logamatic, upper image is mirrored)
Assumed trace of TR2 In (since TR2 Out at pin 7 is used, TR2 In at pin 10 must also be, upper image is mirrored)

I also found some information on mikrocontroller.net about some possible pinout.

OK, we have quite some information collected about the module and now we can start to create some PCB…

Here come some details to the mechanics and to the the circuit, we want to develop. At first, I really don’t need a EIA/RS-232 signal to connect it with my smart home. What I really need is some wireless network connection. So, I decided to implement some ESP32 directly. With this, I can easily flash ESPhome, run OTA updates, push decoded data to MQTT or whatever I deserve, with a simple click of my fingers (or some more clicks, but not many 🙂 ).

Schematic & PCB Design

Given these requirements, we will use an ESP32 (WROOM-32D module). We will also need to shift the levels of the 5V-TTL serial interface to comply with 3.3V of our ESP32 and vice versa and we also need to generate 3.3V from 5V for our supply…

For the serial interface, getting down from 5V to 3.3V could be easily done with a resistor. Ideally, the heating control will accept the 3.3V as a high level, but to make sure, we will put a simple MOSFET level shifter in between.

On the other side, we are not yet sure, if we identified the signals correctly. To accompany that, we added a connector 1:1 connecting the signals of the blade connection to some standard pin header, so we can easily add a flat ribbon cable to it and use a second board to get a simple „range extender“ for measuring every signal without a risk of shorting them.

Additionally, we add some dual row header. On this header, we can use jumpers if we guessed correctly and jumper wires, if we got it wrong.

OK, here is the first shot of the design:

Schematic for V0.0.1
Schematic V0.0.4
PCB V0.0.1
PCB V0.0.4
3D PCB V0.0.1
3D PCB V0.0.4

My Own PCBs

I ordered a bunch of PCBs (Think BMS, Think-Balancer-Adapter, ESP32-18650-Humidity-Temperature-Board and this KM271-WiFi Adapter) on Juli, 27th 2021 from PCBway. And it was lightning fast… Today (August, 4th 2021), one week after I placed my order, it was delivered by FedEX-IP. As I mention in my other post on designing PCBs (coming soon), do not use DHL. It is expensive and they will draw another 12,50 € from you for a short tie credit of the taxes and duty.

You can order the PCB and the parts from my tindie shop.

I also want to thank PCBways, to support my projects with sponsored PCBs. And also the ones I paid

Real PCB V0.0.1 (no more recent version produced yet)

The PCBs look great and also the 0.3mm holes are totally in the center of the vias. There is no visible offset between any of the layers and I totally believe, that going down to 6 mil (0,15mm) with traces and spacings will be no problem.

I already rasped one of it to better slide into the socket. I’ll now prepare two boards to act as a wire extension using a flat ribbon cable between th AN_DEBUG (J3) headers and see, if I can measure the supply correctly and if I’m able to connect to the Buderus controller via TTL-UART. If this succeeds, I’ll populate the components of one card and start the implementation via ESPhome.

Important Bug-Fixes

Changelog V0.0.4

Switched LM_RX and LM_TX since they have been swapped accidently.

Changelog V0.0.3

Buderus Communication Module Presence Detection

Buderus uses some modue detection resistors (R1 and R2 on the original KM271) between the second and the fourth finger contact on the upper side. This relates to LM_P4 and LM_P8 in my schematic. The version with this patch is 0.0.3.

Changelog V0.0.2

One of the drawbacks of releasing stuff early is, that it often requires patches and fixes of hard- and software. Fortunately, most of them are easy to accomplish and my batch of first drafts is usually around 25 pieces for the early adopters that are experienced with hardware modifications (like me).

Mechanical

As you can remember, I took the measurments from images from the internet. I simply had no real hardware. And as murphy tells, the one side of the PCB is a little to long for the connector to slide in. So, the short edge beside the ESP-Module needs to be cut by one millimeter (I used a rasp). This should be done before soldering the components.

You should also sharpen the connector to make it easier to slide it into the receptor of your buderus control unit.

Power-Supply Issues

It seems, that the supply from buderus has quite some limits and maybe a relatively high impedance, so that if the ESP switches on WiFi, the supply drops down to a region, where the ESP resets or even worse, does not come up again a is trapped in a dead state until you reset manually or cycle the power. But this can be easily solved by two additional caps (100 uF/16V or more).

UART pinout

I somehow realized too late, that some of the external pins of the ESP32 module are used internally for important stuff like the program flash 🙁 So I need to remap them to unused pins and this requires some hardware patches. Fortunately, they are easy to accomplish. The new 0.0.2 in Gitlab already compensates for this issues.

All changes together V0.0.1 upgraded to V0.0.4 looks like following:

PCB Assembly

Assembling a prototype should always be done step by step and intermediately checking, if everything still works. First, we should start with the ESP32-WROOM-Module (U1) and put the blocking capacitor (C1@100nF) into place. Then soldering the resistors need to connect to the programming interface (R19, R20, R12, R22). Their values do not matter too much. You can simply take something between 100 Ohms and 1 KOhm. It’s just to eventually compensate a 5V adapter and to protect a bit against overvoltages. Now you should solder J4 to connect the programmer.

Already assembled completely (forgot to take photos of intermediate steps)

You should connect the supply, ESP32-RX to CP-TXD (orange1) and ESP32-TX to CP-RXD (yellow). Also CP-RTS should be connected to ESP-EN (green) and CP-DTR to ESP-IO0 (orange2). If you did this correctly, you do not need to place the RESET and the BOOT button since programming mode can then be entered correctly. Alternatively, only connect RX and TX as described, hold BOOT-Button down while shortly pressing the RESET-Button and then start to flash the module from your PC.

After wiring this, connect the USB to the converter, got to ESPhome and add a new target. Select ESP32 as the platform and if you are connected via HTTPS (e.g. with nabu casa) to ESPhome/Home Assistant, you can simply select to flash it locally using USB

If not connected with HTTPS, you can manually download the binary and then flash it e.g. using ESPhome flasher. After the first successful flashing, you can use wireless mode (OTA) to transfer new firmwares. Home Assistant will inform you, that a new device is available with the name given by you during create.

When this was successful, disconnect your PCB again and continue with assembly. I would suggest, to first put the LEDs (D1@green, D2@green, D3@yellow, D4@red) and their resistors (R23, R24, R25, R26) in place and edit your ESPhome device configuration to contain the following lines

switch:
  - platform: gpio
    name: LED1_Green
    pin: 
      number: 21
      mode: OUTPUT
      inverted: true
  - 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

After installing the new firmware, you should see four new switches in Home Assistant (maybe refresh the page). As soon as you switch one of them, the correlated LED will light up.

After succeeding with this, finish the assembly and put some jumpers on, to make the supply work. I first only jumpered the supply (two leftmost pins of J2), switched the buderus control off and put my module in place. Then I switched on again and checked, if I can still switch on the LEDs.

To get it out again, you need to release the little plastics lock at the bottom, that catches the rectangular hole in our PCB.

Putting On The Software Sauce

How To Debug A remote Serial Connection Easily

Since the protocol of the buderus is not yet known very well to me and debugging all the stuff with ESPhome logs and quirks is a pain, I decided to forward and analyze the traffic on my PC.

See my blog post to get to know how to access serial data over ethernet on windows: The Remote Serial Debugging Nightmare

Unfortunately, I currently have no clue, what the group 0x04 represents…

The (not yet) Final Software

Since this will be a much harder task than designing just another ESP32 board, you need to wait some days (maybe weeks) for me to figure all that stuff out. I’ll need to send a control word on the serial connection to activate the reporting of the Buderus controller and then I also need to parse the data that is thrown out. I’m not yet excatly sure, how I’ll do it, but I plan to implement a new Sensor, that can be used also with a breadboard-type of electronics.

In the meanwhile, I received some help from Michael. He already connected some ATmega and a WiFi module to the original KM271 and implemented the reverse engineered protocol with help of some forum guys on mikrocontroller.net:

https://www.mikrocontroller.net/topic/309075

https://www.mikrocontroller.net/topic/141831

https://homematic-forum.de/forum/viewtopic.php?f=18&t=26955

Stay tuned, to keep updated…

You can get the design files in my project on GitLab (KiCad)…

Current State of Software

I just turned the inside out and decided, to create an external component, as it is the preffered way to do so, according to the ESPhome website.

To develop the component’s source, the easiest way is to install Visual Studio Code, install the ESP-IDF add-on and the C/C++ add-on within visual studio code. Then get the source of esphome via GIT, add it to your browse-path, enable samba share add-on on your Home Assistant, link the remote drive and start developing in VScode by opening the appropriate folder on the just linked share.

If you did so, you just need to create a folder on the share e.g. my_components, create another folder in it called „components“ and you can put one „local“ external component in there as one folder per component.

If you now add a config part to your ESPhome device YAML, you can easily adjust the source and instantly test it on your ESP.

In my case, the my_components folder is the root of the GIT repository, so I can simply push it to GitHub to get the most recent updates there. If I reach a certain state of my code, I’ll branch away from main to develop and only merge stable stuff back to main.

From the current sources you should get the Buderus monologue from the log:

To get relevant data from Buderus controller, we need to kick-off the log mode…

TODO

Now there is only a tiny step left to communicate more intensively with the module, but many steps to interpret all the data that is spit out by the buderus controller as soon as you enable logging. As a friend of mine told, as soon as you send 0x10 when logging is enabled, it will report many sensor values, listed below (with german names):

# Param:'Identifier'
-------------------------
0x8000: 'Betriebswerte 1 HK1'
0x8001: 'Betriebswerte 2 HK1'
0x8002: 'Vorlaufsolltemperatur HK1'       (Grad)
0x8003: 'Vorlaufisttemperatur HK1'        (Grad)
0x8004: 'Raumsolltemperatur HK1'          (Grad)
0x8005: 'Raumisttemperatur HK1'           (Grad)   
0x8006: 'Einschaltoptimierungszeit HK1'
0x8007: 'Ausschaltoptimierungszeit HK1'
0x8008: 'Pumpenleistung HK1'              (Grad)
0x8009: 'Mischerstellung HK1'             (Grad)
0x800a: 'nicht belegt'
0x800b: 'nicht belegt'
0x800c: 'Heizkennlinie HK1 bei + 10 Grad' (Grad)
0x800d: 'Heizkennlinie HK1 bei 0 Grad'    (Grad)
0x800e: 'Heizkennlinie HK1 bei - 10 Grad' (Grad)
0x800f: 'nicht belegt'
0x8010: 'nicht belegt'
0x8011: 'nicht belegt'
#
0x8112: 'Betriebswerte 1 HK2'
0x8113: 'Betriebswerte 1 HK2'
0x8114: 'Vorlaufsolltemperatur HK2'       (Grad)
0x8115: 'Vorlaufisttemperatur HK2'        (Grad)
0x8116: 'Raumsolltemperatur HK2'          (Grad)
0x8117: 'Raumisttemperatur HK2'           (Grad)
0x8118: 'Einschaltoptimierungszeit HK2'
0x8119: 'Ausschaltoptimierungszeit HK2'
0x811a: 'Pumpenleistung HK2'
0x811b: 'Mischerstellung HK2'
0x811c: 'nicht belegt'
0x811d: 'nicht belegt'
0x811e: 'Heizkennlinie HK2 bei + 10 Grad' (Grad)
0x811f: 'Heizkennlinie HK2 bei 0 Grad'    (Grad)
0x8120: 'Heizkennlinie HK2 bei - 10 Grad' (Grad)
0x8121: 'nicht belegt'
0x8122: 'nicht belegt'
0x8123: 'nicht belegt'
#
0x8424: 'Betriebswerte 1 WW'
0x8425: 'Betriebswerte 2 WW'
0x8426: 'Warmwassersolltemperatur'        (Grad)
0x8427: 'Warmwasseristtemperatur',        (Grad)
0x8428: 'Warmwasseroptimierungszeit'
0x8429: 'Ladepumpe'                       ['aus', 'Ladepumpe', 'Warmwasserpumpe', 'beide']
#
0x882a: 'Kesselvorlaufsolltemperatur'     (Grad)
0x882b: 'Kesselvorlaufisttemperatur'      (Grad)
0x882c: 'Brennereinschalttemperatur'      (Grad)
0x882d: 'Brennerausschalttemperatur'      (Grad)
0x882e: 'Kesselintegral 1'
0x882f: 'Kesselintegral 2'
0x8830: 'Kesselfehler'
0x8831: 'Kesselbetrieb'
0x8832: 'Brenneransteuerung'              ['aus', 'an']
0x8833: 'Abgastemperatur'                 (Grad)
0x8834: 'modulare Brenner Stellwert'
0x8835: 'nicht belegt'
0x8836: 'Brennerlaufzeit 1 Stunden 2'
0x8837: 'Brennerlaufzeit 1 Stunden 1'
0x8838: 'Brennerlaufzeit 1 Stunden 0'
0x8839: 'Brennerlaufzeit 2 Stunden 2'
0x883a: 'Brennerlaufzeit 2 Stunden 1'
0x883b: 'Brennerlaufzeit 2 Stunden 0'
#
0x893c: 'Aussentemperatur'                (Grad)
0x893d: 'gedaempfte Aussentemperatur'     (Grad)
0x893e: 'Versionsnummer VK'
0x893f: 'Versionsnummer NK'
0x8940: 'Modulkennung'
0x8941: 'nicht belegt'

There should be also a way to control the Buderus heating system, but this is another story and I do not need it to be honest 🙂

Have fun!

Some other references

5
Rated 5 out of 5
5 von 5 Sternen (basierend auf 3 Bewertungen)
Ausgezeichnet100%
Sehr gut0%
Durchschnittlich0%
Schlecht0%
Furchtbar0%

Super Sache …………….

Rated 5 out of 5
20. Januar 2022

…. kann man so ein fertiges Modul auch erwerben ?

Bin grad so in das Thema Smart Home mit NodeRed eingestiegen und

meine (ur-) alte Heizung wär natürlich schon ein interessantes Thema …

Manfred

Antwort von MolesBlog

Ja klar, schicke mir doch bitte eine Email an me@the78mole.de. Bausatz ginge Recht flott, für eine fertig aufgebaute Platine musst Du mit ein paar Tage Zeit geben…

Great Project – I was looking for this!

Rated 5 out of 5
3. Dezember 2021

I’m using FHEM right at the moment, but I like to switch to HA. The is a working implementation also for write the data. In fact, I can edit my heat programms.

https://fhem.de/commandref_modular.html#KM271

Benedikt

Mutig …

Rated 5 out of 5
2. Dezember 2021

Du hast da einen kleinen aber feinen Zahlendreher … KM271 und nicht KM217! 🙂

Ein eigenes PCB zu designen ist schon echt Mutig vor allem wenn man bedenkt, dass das Ding im Herzen der Zentralheizung steckt. Wär mir dann doch etwas riskant … dann doch lieber die günstige Variante der KM271 von Bosch direkt (80€) + RS232 USB-Kabel + RasPi 3a+ mit seperater Stromversorgung und das KM271-Modul in FHEM drauf laufen lassen (3m entfernt) und per MQTT wohin auch immer schicken … ist zwar etwas unhandlicher / größer aber deutlich komfortabler.

https://fhem.de/commandref_modular.html#KM271

Wie löst du das Problem mit der Abschirmung des WLAN-Signals durch das Blech?

„raising an error from the flame sensor … often once peer week“

Das klingt aber nicht normal.

Hast du irgendein Muster ausgemacht? Tritt das nur auf wenn dein Ölstand einen gewissen Pegel erreicht?

Schau mal deinen Ölfilter an, wenn da zuviele Bläschen rausgedrückt werden dann liegt es daran dass er bei deinen Tanks irgendwo Luft zieht.

Entweder die Dichtungen gehören gewechselt, und/oder aber die Ansaugstutzen in den Öltanks sind mit den Jahren porös geworden – alternativ ist die Leitung irgendwo undicht (müsste man aber sehen). Kann auch einfach nur Ölschlamm sein … damals wurden meistens noch Tanks verbaut die Ansaugstutzen hatten die keinen Schwimmer integriert hatten – sprich Schläuche – deswegen auch die Frage nach dem Ölpegel.

Wenn das ausgeschlossen ist würde ich mich mal dem Brenner widmen … die Anlage ist eigentlich der VW Golf 1 der Ölheizungen (laut meinem Heizungsfachmann) zickt aber wenn ein paar Dinge nicht passen / verbraucht sind. Wurde allerdings deswegen oftmals auch so gut wie nie gewartet (auch von den Vorbesitzern bei unserem Haus nicht).

p.s.: Deine Kommentarfunktion geht nicht …

Simon

Antwort von MolesBlog

Hallo Simon,

Danke für die Sterne…

KM271… Mist, einmal falsch abgetippt und dann immer „kopiert“…

Naja, mutig… PCB-Design ist bei mir Tagesgeschäft (gewesen bis August). Ist ja nicht so, dass ich das zum ersten Mal mache…. Ich sehe daran nichts Riskantes, es sind einfach elektrische Signale, nicht mehr und nicht weniger. Ich habe schon darauf geachtet, dass es keine Kurzschlüsse verursacht und die übrigen Signale genügend hochohmig angebunden sind, dass man nichts kaputt machen kann. Ich bin ja schließlich kein Laie sondern Elektrotechnik-Profi (Dipl.-Ing.) seit über 10 Jahren, gelernter Energieelektroniker Fachrichtung Betriebstechnik seit 20 Jahren und Elektronik-Bastler seit über 30 Jahren. Nur dass ich mittlerweile (seit August eben) Projektleitung in der Produktentwicklung mache und selbst beruflich kein Schaltungsdesign mehr.

Ehrlich gesagt finde ich die Lösung mit dem ESP32 die einfachste und schickste Variante und die vielen Anfragen, die ich bekomme, geben mir da Recht. Hab schon einige Bausätze bzw. fertige Module verschickt…

Das Problem mit dem Blech löst sich dadurch, dass der Deckel original aus Kunststoff ist und deswegen eine relativ gute WLAN-Anbindung sogar durch meine Kellerdecke hindurch gegeben ist. Der ESP berichtet -58 dBm, ab -85 dBm reißt der Empfang so langsam ab, also fast 30 dB Luft nach unten…

Wenn Du wüsstest, was ich an meinem Brenner schon alles gereinigt und getauscht habe. Ich habe auch einen Schwimmer, der Filter und das Öl sehen absolut klar aus (null-komma-null Schmutz oder Schwebstoffe), keine Bläschen, nichts… Das Öl kommt perfekt an der Pumpe an. Vom Filter bis zum Rückschlagventil über die Düse bis hin zum Tausch der Ölpumpe, inkl. Zerlegung des ganzen Brenners in Einzelteile und deren Reinigung. Auch die Brennkammer und die Wärmetauschrippen schon öfter sauber gemacht. Nichts, was ich nciht versucht habe. Nur den Flammsensor selbst habe ich noch nicht ausgetauscht, allerdings reagiert er korrekt auf Flammbildänderungen, wenn man das Signal und das Flammbild durchs Schauglas vergleicht. Auch Flammgeräusche und Flammsensorsignal passen „gut“ zusammen (wenn man z.B. an der Luftzufuhr „spielt“. Auch Fachleute waren da nach mehrmaligem Handanlegen ratlos. Die Werte am Messgerät des Schlotfegers sind traumhaft gut und zeigen keine Auffälligkeiten… Naja, das Ding weicht früher oder später ohnehin einer Wärmepumpe. Jetzt zum Beispiel läuft er schon wieder seit über einem Monat problemlos durch 🙁

Kommentarfunktion ist moderiert, sonst steht da Massenweise Spam. Dauert nur manchmal, bis ich die Kommentare bemerke und frei gebe 😛

Aber Danke für die Hinweise. Rückmeldung und Ideen sind immer gut.

themole

1 Kommentar bisher

Eberhard Veröffentlicht am13:55 - 25. April 2022

habe Interesse am kauf einer fertig aufgebauten Platine. Leider kann ich die Bestellung nicht aufgeben da einige Bauteile nicht zur Verfügung sind.

Schreibe einen Kommentar

WordPress Cookie Plugin von Real Cookie Banner