If you bought one of my modules recently, it is also worth looking at the how-to project page for this module 🙂
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.
Current Version is V0.0.5 (see Changelog close to the end of this blog post)
Breaking News From „Under the Ground“
2023-01-16 Sneak Preview
A little later than planned, but here is a sneak preview of the 0.0.6 board, including analog inputs for Pt- or NTC-type temperature sensors, a OneWire break-out and extension, a I²C/SPI-extension header, USB external power supply option and a jumper to select power supply options.
I’ll order the new batch end of January, so it can get delivered until end of February.
the functionality of the km271 gets more and more fantastic. I can now instruct my heating system to switch the hot water mode from on to off and auto (following the heating day and night modes). I can also set the hot water target emperature and do way more stuff. The Buderus Logamatic soon will be simply an old Relay-Box with Temperature-Sensor-Circuits 🤣 All sensors I wished are now available.
And since I have only 10 of my 50 modules left after a single month, time comes closer to update the hardware again and implement a simple onewire interface (as many people suggested). I’ll add the hardware for the simple MCU-pin variant, but also to use an I2C-1wire-interface-IC from Maxim. The latter just produces way more clean 1-wire-signals, has Power-Pull-Up and therefore runs on way longer lines (to my experience). The drawback of the I2C solution is, that it is not yet integrated into ESPhome… Digging challenge accepted 😛
Sven published his firmware on GitHub. It is really worth looking at it, since it also contains writing commands to the buderus heating system. Thanks so much Sven!!!
ESPhome Firmware also received georgeous updates from Sven, Jens and Bascht. They added the sensors finally, two write params and now it is easy to add more.
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 🙁
I also recently found out, that Buderus sells a unit called Logamatic web KM200 for just 270 bucks (€). Man, this is cheap! And you can access it with your smartphone, but obiously get a nice vendor lock-in, everybody running a smart home is excited about.
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.
Tracing some signals…
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:
My Own PCBs
Latest Order on PCBway for V0.0.5
I ordered 50 pieces of assembled boards on PCBway. I’ll keep you updated as soon as they will arrive.
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
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.
I took over all improvements, that have been suggested by Michael and ordered 50 assembled boards from PCBway. They will arrive end of November and can then be ordered on tindie or by sending me an email.
Switched LM_RX and LM_TX since they have been swapped accidently.
Buderus Communication Module Presence Detection
Buderus uses some module 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.
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).
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.
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).
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.
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.
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
Home Assistant / ESPhome integration
The easiest way to integrate the heating controller into your smart home is by using Home Assistant and ESPhome, since there is now (2022-11-26) a working external component.
Check out my KM271-WiFi how-to page to get mor information on this.
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:
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…
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 🙂
Some other references
- Hirnfasching Blog (german)
- 3964R Protocol (Wikipedia german)
- sjs-77-logamatic (GitHub german)
- Steuerzeichen (de), Control Characters (en)
Tolle Arbeit, 6 Sterne von mir
es sollten eigentlich 5 Sterne sein. Ich hatte aber ein Problem mit meinem Browser, die Bewertung überhaupt abzugeben und habe mehrere Versuche benötigt. Dabei wurde die Bewertung von mir unbemerkt auf 3 zurückgesetzt – Sorry!
Antwort von MolesBlog
OK, vielen Dank! Jetzt passt es ja 😛
your initiative went alredy quit far together with an interested team of co-fighters. That is so good to see what can be achieved if a community takes the callenges to work together on such a complex project.
The WiFi-KM217 module will be a very interesting part for all owners of a Buderus Logamatic that are doing smart home automation.
As i am having a Buderus Ecomatic 4000 (HS4201) i was following your blog a few weeks now to figure out if your solution would be fitting for me as well.
I also would like to integrate my Ecomatic 4000 heating system to my Home Assistant smart home contoller via ESPHome, but it does not work with the KM271.
But i will get an original Buderus M404 KM 2.0 module. This is the communication module (with RS232 and RS485 interfaces) for the Ecomatic 4000.
I wonder if you or the community might be interested in a similar reverse engineering project to create an „Ecomatic Smart-Home WiFi module“ based on the knowledge from the „Logamatic KM217 wiFi module“.
What do you think?
Antwort von MolesBlog
thanks for all the flowers 🙂
I already answered on the mikrocontroller.net forum… but to make it complete, I’ll my answer here will be more complete.
It could be possible to do the reverse engineering, but I would like to first get the low hanging fruits and see, if your unit talks a (mostly) similar protocol on the serial interface. Afterwards you could attach a bread-board version of the ESP32 to the RS485 or the RS232 interface and try, if my ESPhome component is able to talk the dialect of your Buderus control unit. If all works fine, I would be willing to support in designing a PCB for/with you.
The major problem is, that I can not put my own hands on the hardware at yours and I don’t know anybody that has such a controller.
Vor einiger Zeit wollte ich so etwas mal selbst basteln, aber diese Lösung ist viel besser als das, was ich mal geplant hatte – super!
Die Platine läuft bei mir jetzt schon ein paar Wochen mit meiner Logamatic 2105 und FHEM/MQTT.
Was mir jetzt noch fehlt ist eine BFU-Emulation, um die Raumtemperatur per MQTT zu setzen (ich möchte keine Kabel verlegen). Irgendwie könnte das ja klappen, schließlich läßt sich ja auch die Uhrzeit einstellen. Gibt es zum Setzen von Parametern irgendwelche Unterlagen oder Erkenntnisse?
Alternativ gäbe es vielleicht noch die Möglichkeit, einen externen Raumsensor über ein Digipot (DS3502?) an einer vorhandenen BFU zu emulieren. Dazu wäre das Herausführen der I2C-Leitungen auf eine Steckleiste ggf. vorteilhaft.
Antwort von MolesBlog
schade, dass Du nur 3 Sterne gibts 🙁
Tatsächlich ist gerade eine neue Version in der Mache, die auch I2C herausführt. Das mit der BFU-Emulation wird aber schwierig. Habe da mal etwas recherchiert und relativ bald wieder aufgehört zu graben. Die ESPhome-Firmware kann dank JensG und QSchneider aber bereits jede Menge Parameter setzen. Die Raumtemperatur geht aber meines Wissens nicht über die interne Schnittstelle zu setzen. Allerdings darf man das nicht zu oft tun, da einige der Parameter dazu führen, dass die Steuerung diese ins EEPROM schreibt und das hat eine begrenzte Anzahl Schreibzyklen (100K bis 1M). Stündliches Schreiben sollte aber z.B. kein Problem sein, dann hält die Kiste noch 10 Jahre (8760 h/Jahr). Öfter wird dann schnell desaströs 🙂
Also aufgrund mehrere gleichen Probleme wie bei dir bin ich auf eine Seite gekommen. Ich hab immer wieder Brenner Fehler und der Heizungsmensch war schon 10 mal da und hat schon alles mögliche getauscht und findet nichts… doof natürlich wenn ich nicht daheim bin und der Fehler passiert und meine Frau nicht weis wie man es behebt mit dem Reset…. deshalb will ich das aus der Ferne machen können und benachrichtigt werden wenn es auftritt. Hab mich in deinem Shop mal auf die Warteliste setzen lassen und bin mega gespannt wann die neue Lieferung kommt und ob ich damit zurecht komme ! Vielen Dank auf alle Fälle mal das du da so hinterher bist !
Doku zur Jumper Row?
Erstmal vielen Dank für deine Arbeit!
Eine Kleinigkeit, nachdem ich grade alles zusammengelötet hab: welche Jumper müssen denn gesetzt sein? auf Fotos seh ich bei dir mal 5V, GND, P4, RX, TX und P8, aber auch mal P9 bis P12…
Gibts irgendwo Infos, welche wofür da sind?
Antwort von MolesBlog
also die Minimalkonfiguration, damit die Funktionalität gegeben ist, lautet 5V, GND, P4, RX, TX, P8. Die anderen Jumper schleifen nur Signale zum ESP durch, deren Funktion ich (noch) nicht kenne.
Hoffe, das hilft Dir weiter…
Daniel (der freundlich, elektrisierte Maulwurf von Nebenan)