# IDM Wärmepumpe MCP Server

MCP-Server für IDM Navigator 2.0 Wärmepumpen (z. B. TERRA SWM) über Modbus TCP.  
Ermöglicht Claude die vollständige Überwachung und Steuerung der Wärmepumpe als Teil
des integrierten Smart-Home-Energiemanagementsystems.

---

## Voraussetzungen

- Python ≥ 3.11
- `uv` installiert
- IDM Wärmepumpe im selben LAN, Modbus TCP aktiviert (Menü „Gebäudeleittechnik")
- IP-Adresse der Wärmepumpe manuell gesetzt (kein DHCP — sonst nach Stromausfall ggf. geändert)

## Installation

```bash
cd /Users/chris/Entwicklung_local/idm-mcp
uv sync
```

## Umgebungsvariablen

| Variable   | Standardwert   | Beschreibung                   |
|------------|----------------|--------------------------------|
| `IDM_HOST` | `10.10.10.188` | IP-Adresse der IDM Wärmepumpe  |
| `IDM_PORT` | `502`          | Modbus-TCP-Port                |
| `IDM_UNIT` | `1`            | Modbus Unit-ID                 |

## Claude Desktop Konfiguration

Ergänze `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "idm-mcp": {
      "command": "/Users/chris/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/chris/Entwicklung_local/idm-mcp",
        "run",
        "python",
        "-m",
        "idm_mcp.server"
      ],
      "env": {
        "IDM_HOST": "10.10.10.188",
        "IDM_PORT": "502",
        "IDM_UNIT": "1"
      }
    }
  }
}
```

---

## Verfügbare Tools (13)

### Read-only (8)

| Tool | Beschreibung |
|------|-------------|
| `idm_health_check` | Verbindungstest: Außentemp., Betriebsart, Störungsstatus |
| `idm_get_system_status` | Betriebsart System + WP, Außentemp., Störung, Smart Grid, PV-Überschuss, Leistungsaufnahme |
| `idm_get_temperatures` | Alle Sensoren: WP-Vorlauf B33, Rücklauf B34, HGL B35, Wärmequelle B43/B36, Luft B37/B46/B72, Speicher B38/B40 |
| `idm_get_hot_water_status` | Trinkwasser oben/unten B48/B41, Zapftemperatur B42, Soll/Ein/Aus-Temperaturen, Ladepumpe M73 |
| `idm_get_heat_circuits` | Heizkreise A–G: Vorlauf ist/soll, Raumtemperatur, Betriebsart je Kreis |
| `idm_get_compressor_status` | Verdichter 1–4, Stufen Heizen/Kühlen/WW, Pumpen M15/M16/M73/M84/M17, alle Umschaltventile M61–M99 |
| `idm_get_energy_data` | Momentanleistung, WP-Aufnahme, kumulierte Wärmemengen (Heizen/Kühlen/WW/Abtauung/Solar/E-Heiz) |
| `idm_get_solar_status` | Kollektor B73/B75, Ladetemperatur B74, Pool B76, Betriebsart Solar |

### Schreibend (5)

| Tool | Register | Besonderheit |
|------|----------|-------------|
| `idm_set_system_mode` | 1005 | ⚠ EEPROM — nicht zyklisch schreiben! |
| `idm_set_smart_grid` | 1006 | Kernsteuerung für PV & Strommarkt (0/1/2/4) |
| `idm_set_pv_surplus` | 74 | ⚠ E3DC schreibt diesen Wert normalerweise selbst! |
| `idm_set_hot_water_setpoints` | 1032/1033/1034 | ⚠ EEPROM — nur bei Bedarf ändern |
| `idm_set_demand` | 1710/1711/1712 | ⚠ Zyklisch schreiben (alle 30 s), sonst nach Neustart inaktiv |

---

## Systemarchitektur & Zusammenhänge

### E3DC ↔ IDM Kommunikation

Das **E3DC S10E Pro Hauskraftwerk** (10.10.10.166) verfügt über ein integriertes
Modbus-Modul speziell für IDM Wärmepumpen. Bei vorhandenem PV-Überschuss schreibt das
E3DC **automatisch und zyklisch** den Überschusswert in Register 74 der IDM.

Die Wärmepumpe reagiert darauf und produziert mehr Wärme als für die aktuelle
Raumtemperatur nötig wäre — sie „überlädt" gezielt:
- Fußbodenheizung wird höher als Normalniveau temperiert
- Pufferspeicher werden auf erhöhtes Temperaturniveau gebracht

Damit wird thermische Masse als kostenloser Energiespeicher genutzt, um z. B.
über die Nacht zu kommen, ohne abends auf teuren Netzstrom angewiesen zu sein.

> ⚠ Das direkte Schreiben von Register 74 via `idm_set_pv_surplus` überschreibt
> die E3DC-Vorgabe **temporär** bis zum nächsten E3DC-Kommunikationszyklus.

### Smart Grid Status (Register 1006)

Das zentrale Steuerregister für alle externen Eingriffe:

| Wert | Bezeichnung | Verwendung |
|------|-------------|-----------|
| `0` | EVU-Sperre & kein PV-Ertrag | WP komplett sperren (Hochpreisstunden) |
| `1` | EVU-Bezug & kein PV-Ertrag | Normalbetrieb |
| `2` | Kein EVU-Bezug & PV-Ertrag | PV-Überschuss aktiv → WP auf Hochtouren |
| `4` | EVU-Sperre & PV-Ertrag | WP läuft trotz Netzsperrung weiter (PV-only) |

### Betriebsart System (Register 1005)

| Wert | Bezeichnung |
|------|-------------|
| `0` | Standby |
| `1` | Automatik (Normalbetrieb) |
| `2` | Abwesend |
| `4` | Nur Warmwasser |
| `5` | Nur Heizung/Kühlung |

### Betriebseinschränkung Spitzenlastzeiten

Die IDM ist eine dreiphasige Erdwärme-Wärmepumpe mit **7,5 kW**. Im aktuellen
Tarifsystem (Kaskadenzähler ohne Smart Meter Gateway) wird der WP-Betrieb in den
Hochpreisstunden **17:00–22:00 Uhr** eingeschränkt, um teuren Netzstrombezug zu
vermeiden.

---

## Vorbereitung: Zukünftige Strommarktsteuerung

Der Server ist bereits auf eine spätere **viertelstündliche Direktvermarktung**
am Strommarkt vorbereitet — sobald ein Smart Meter Gateway und eine direkte
Marktteilnahme möglich sind.

**Strategie:**

| Zeitfenster | Strompreis | Aktion |
|-------------|-----------|--------|
| Nachts (günstig) | niedrig | `idm_set_smart_grid(2)` + Puffer & WW hochladen + E-Auto laden + Batterien füllen |
| 06–08 Uhr | hoch | `idm_set_smart_grid(0)` → WP sperren, Batterie entladen |
| 17–20 Uhr | hoch | `idm_set_smart_grid(0)` → WP sperren, aus Wärmespeicher leben |
| PV-Überschuss | — | `idm_set_smart_grid(2)` → maximale thermische Einlagerung |

Diese Steuerung würde in Verbindung mit E3DC, Victron/Felicity und dem 22-kW-Wallbox-
Lader über Node-RED oder einen dedizierten Automations-Flow koordiniert.

---

## Wichtige Hinweise

- **EEPROM-Register** (mit `*` in IDM-Doku): Begrenzte Schreibzyklen → **nicht permanent/zyklisch schreiben**!
- **Zyklische Register** 1710/1711/1712 und 74: Müssen **alle ~30 s** geschrieben werden, damit die Anforderung nach einem WP-Neustart wieder anliegt.
- **PV-Überschuss Register 74**: Im laufenden Betrieb vom **E3DC Hauskraftwerk** beschrieben — direktes MCP-Schreiben nur für manuelle Tests/Overrides.
- **Solltemperaturen nicht permanent schreiben**: Bei Navigator Pro führt permanentes Schreiben der Solltemperaturen zu einem Neustart des Zonenmoduls.
- **GLT Log**: Zur Diagnose kann im IDM-Menü „Gebäudeleittechnik" → „GLT Log Einschalten" aktiviert werden. Zeigt alle Modbus-Lese- und Schreibzugriffe; wird nach 1 Stunde automatisch deaktiviert.

---

## Datentypen

| Typ | Beschreibung |
|-----|-------------|
| `uint16be` | 1 Register, 16-Bit Unsigned Integer, Big-Endian |
| `floatsw` | 2 Register, IEEE-754 Float, **Word-vertauscht** (Low-Word zuerst = CDAB) |

### Float-Dekodierung (struct-basiert, kein pymodbus-Interna)

```python
# Lesen: Reg[0]=Low-Word, Reg[1]=High-Word → float
raw = struct.pack(">HH", registers[1], registers[0])
value = struct.unpack(">f", raw)[0]

# Schreiben: float → [low_word, high_word]
raw = struct.pack(">f", value)
high_word, low_word = struct.unpack(">HH", raw)
registers = [low_word, high_word]
```

> Hintergrund: pymodbus 3.x hat `Endian` aus `pymodbus.constants` und den
> `BinaryPayloadDecoder`/`Builder` entfernt. Die `struct`-basierte Implementierung
> ist unabhängig von pymodbus-internen APIs und damit stabiler.

---

## Modbus-Registerübersicht (Kurzreferenz)

### Schlüsselregister

| Adresse | Typ | R/W | Bezeichnung |
|---------|-----|-----|-------------|
| 74 | floatsw | W | PV-Überschuss (kW) — E3DC schreibt zyklisch |
| 78 | floatsw | R | Aktuelle PV-Produktion (kW) |
| 1000 | floatsw | R | Außentemperatur aktuell (°C) |
| 1002 | floatsw | R | Außentemperatur gemittelt (°C) |
| 1004 | uint16 | R | Aktuelle Störungsnummer (020–999) |
| 1005 | uint16 | RW | Betriebsart System ⚠ EEPROM |
| 1006 | uint16 | RW | Smart Grid Status |
| 1090 | uint16 | R | Betriebsart Wärmepumpe aktiv |
| 1099 | uint16 | R | Summenstörung (0=OK, 1=Störung) |
| 1710 | uint16 | RW | Externe Heizanforderung (zyklisch!) |
| 1711 | uint16 | RW | Externe Kühlanforderung (zyklisch!) |
| 1712 | uint16 | RW | Anforderung Warmwasserladung (zyklisch!) |
| 4122 | floatsw | R | Aktuelle Leistungsaufnahme WP (kW) |