diff --git a/docs/module/Waermepumpe/README.md b/docs/module/Waermepumpe/README.md
new file mode 100644
index 0000000..9d71658
--- /dev/null
+++ b/docs/module/Waermepumpe/README.md
@@ -0,0 +1,47 @@
+# Wärmepumpe
+
+> Status: Diskussionsentwurf.
+
+Die Kontaktwirkung ist als Sperrkontakte oder SG Ready konfigurierbar. Die
+elektrische Leistung kann fehlen, berechnet oder gemessen werden.
+
+## Zusätzliche Variablen
+
+| Ident | Typ / Zugriff | Beschreibung |
+| --- | --- | --- |
+| `Waermepumpenzustand` | Integer / Anzeige | `0` unbekannt, `1` aus, `2` normal, `3` erhöht, `4` gesperrt. |
+| `SperreAktiv` | Boolean / Anzeige | Aktuelle Sperranforderung. |
+| `ErhoehungAktiv` | Boolean / Anzeige | Aktuelle Erhöhungsanforderung. |
+| `SGReadyZustand` | Integer / Anzeige | Bei SG Ready Zustand 0–3. |
+| `Laufzeit` | Integer / Anzeige | Kumulierte bestätigte Laufzeit in Sekunden. |
+
+## Zusätzliche Properties
+
+| Ident | Typ | Standard / Beschreibung |
+| --- | --- | --- |
+| `Kontaktwirkung` | Auswahl | `Sperrkontakte`; alternativ `SG Ready`. |
+| `Kontakt1VariableID` | Integer | `0`; Sperre oder SG-Ready-Eingang 1. |
+| `Kontakt2VariableID` | Integer | `0`; Erhöhung oder SG-Ready-Eingang 2. |
+| `Kontakt1Invertiert` | Boolean | `false`. |
+| `Kontakt2Invertiert` | Boolean | `false`. |
+| `Leistungsermittlung` | Auswahl | `Nicht vorhanden`, `Berechnet` oder `Gemessen`; entspricht Quelle 0/1/2. |
+| `LeistungsmessungVariableID` | Integer | `0`; nur bei gemessener Leistung. |
+| `Zustandskennlinie` | String/JSON | `[]`; bei berechneter Leistung je Zustand Planleistung und Kontaktbelegung. |
+| `BetriebsrueckmeldungVariableID` | Integer | `0`; optionale echte Betriebsrückmeldung. |
+| `Mindestlaufzeit` | Integer | `0*` s; anlagengerecht festlegen. |
+| `Mindeststillstand` | Integer | `0*` s; anlagengerecht festlegen. |
+| `MaxSperrzeit` | Integer | `0` s; `0` deaktiviert die EMS-Sperrfunktion. |
+
+Zeit- und wetterabhängiges Sperren beziehungsweise Erhöhen aus dem Altmodul
+entfällt.
+
+## Zustand
+
+`Waermepumpenzustand`, `SperreAktiv`, `ErhoehungAktiv` beziehungsweise
+`SGReadyZustand` als Status, `Laufzeit_s` als Istwert und
+`Kommunikationsfehler` als Störung.
+
+## Offene Punkte
+
+- Der Formularbutton „Wassererwärmer über Wärmepumpe betreiben“ bleibt ohne
+  Regelwirkung, bis Anschluss und Verriegelung gemeinsam definiert sind.