Update Pflichtenheft v2.0 → v2.1 based on Adrian's feedback

- Netzwerk aus 2.3 raus, neue Anforderungssektion 3.6 (NW-001..008) mit VPN, Firewall, Router, SSH/VPN Remote-Zugriff - Physische Installation klar als Out-of-Scope mit Verweis auf separates Pflichtenheft Inbetriebnahme - 2.2.2 präzisiert: vollautomatischer Modus-Wechsel = Wunsch, FA-014 Hinweis ergänzt (kein Widerspruch mehr) - NFA-006: Begründung für Python vs CodeSys ergänzt - SA-001: FLOW OK entfernt, Temperaturüberwachung als Ersatz - SA-002: Remote Safety-Reset per VPN erlaubt (Software-Zustand) - SA-006: bei Safety-Trip aktiv gRPC-Leistung auf 0 setzen - SA-007: Remote-Quittierung via VPN ergänzt - SA-008: Ventil-Verriegelung verständlicher erklärt - 6.1: Miner-Topics korrigiert (Miner 2 ohne hashrate), P3 als relay-only, erweiterte Inverter-Variablen, aussen+miner-Temps, power_setpoints als schreibbar in setpoints/ - 6.2: Publisher/Subscriber-Tabelle aktualisiert - 6.3: Nomenklatur (QoS 0/1, retained) mit Erklärungstabelle - Alle Hauptsektionen mit erklärendem Einleitungsabsatz - HARDWARE.md: FLOW OK entfernt, Sensor-Sektion strukturiert - Offene Punkte 11-13 ergänzt (Router, IP-Plan, Miner-2-Hashrate) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-08 12:35:21 +02:00 · 2026-05-08 12:35:21 +02:00 · 0513248d7f
commit 0513248d7f
parent ba6622bed7
2 changed files with 183 additions and 61 deletions
--- a/docs/HARDWARE.md
+++ b/docs/HARDWARE.md
@ -113,7 +113,18 @@ If RevPi crashes → miners must shut down (hardware safety ensures this).

 ## Sensors

- Flow sensor (FLOW OK — NC contact to safety relay)
+### Hardware-Sicherheitssensoren (direkt in Safety-Kette)
 - Temperature sensor (TEMP MAX — NC contact to safety relay)
 - Emergency stop buttons (E-Stop 1, E-Stop 2 — NC)
 - Reset button (NO)
+
+> **Hinweis:** Ein physischer Durchflusssensor (FLOW OK) wird nicht verbaut. Die Überwachung des Miner-Kühlkreisdurchflusses erfolgt softwareseitig über Temperaturauswertung (PFLICHTENHEFT_SOFTWARE.md, SA-001).
+
+### Analoge Temperatursensoren (RevPi AI)
+- AI1 — Pufferspeicher-Temperatur (PT1000 oder 4-20 mA, TBD)
+- AI2 — Warmwasserspeicher-Temperatur (PT1000 oder 4-20 mA, TBD)
+- AI3 — Außentemperatur (optional, für Übergangs-Modus)
+
+### Miner-Temperaturen (via gRPC)
+- Miner 1 Chip-Temperatur — ausgelesen via Braiins OS gRPC API
+- Miner 2 Chip-Temperatur — ausgelesen via Braiins OS gRPC API
--- a/docs/PFLICHTENHEFT_SOFTWARE.md
+++ b/docs/PFLICHTENHEFT_SOFTWARE.md
@ -7,7 +7,7 @@

 **Dokument:** Pflichtenheft Software — Phase 1

-**Version:** 2.0
+**Version:** 2.1

 **Stand:** 2026-05

@ -43,11 +43,14 @@

 Dieses Pflichtenheft beschreibt die Softwareanforderungen für den Automatisierungsschaltschrank ASP1 des ThermIQ-Systems. Es definiert die zu erbringenden Leistungen für:

- die **SPS-Programmierung** auf dem RevolutionPi (Python/Node-RED via MQTT)
+- die **SPS-Programmierung** auf dem RevolutionPi (Python via MQTT)
 - die **Node-RED Automatisierungslogik** auf dem Site Server (Intel N100)
+- die **Netzwerk- und Remote-Zugriffs-Konfiguration** (VPN, Firewall, Router)

 Home Assistant (Phase-1-Dashboard) ist in diesem Dokument **nicht** enthalten und wird separat spezifiziert.

+> **Hinweis zur physischen Installation:** Die physische Installation und Inbetriebnahme des Schaltschranks (Verdrahtung, Montage, Elektroabnahme) wird von Adrian durchgeführt und ist in einem **separaten Pflichtenheft Inbetriebnahme ASP1** dokumentiert. Dieses Dokument und das Inbetriebnahme-Pflichtenheft sind unabhängig voneinander abnahmefähig und blockieren sich nicht gegenseitig.
+
 ### Abgrenzung

 | In Scope | Out of Scope |
@ -55,9 +58,10 @@ Home Assistant (Phase-1-Dashboard) ist in diesem Dokument **nicht** enthalten un
 | RevPi I/O-Steuerung (DO, DI, AO, AI) | Home Assistant Konfiguration |
 | MQTT-Kommunikation RevPi ↔ Site Server | Cloud-Anbindung |
 | Node-RED Modbus-Polling (Deye, Energiezähler) | Hydraulikplanung |
-| Node-RED gRPC Miner-Integration | Netzwerk-Infrastruktur (Switch, IP-Vergabe) |
-| Energie- und Wärmemanagement-Logik | Elektrische Hausinstallation |
-| Watchdog und Alarmierung | Buderus-interne Konfiguration |
+| Node-RED gRPC Miner-Integration | Elektrische Hausinstallation |
+| Energie- und Wärmemanagement-Logik | Buderus-interne Konfiguration |
+| Netzwerktopologie im Schrank (Router, Switch, IP-Vergabe, VPN, Firewall) | Physische Schaltschrank-Installation (→ Pflichtenheft Inbetriebnahme) |
+| Watchdog und Alarmierung | |

 ---

@ -80,7 +84,7 @@ Die folgenden Ziele sind zwingend zu erfüllen. Das System gilt ohne diese als n
 Die folgenden Ziele sind wünschenswert und sollen in späteren Phasen realisiert werden.

 1. Integration eines dynamischen Stromtarifs (z. B. Tibber API) zur weiteren Kostenoptimierung (Phase 2).
-2. Automatischer Modus-Wechsel (Winter/Sommer) basierend auf Außentemperatursensor (optional).
+2. **Vollautomatischer** Modus-Wechsel (Winter/Sommer) basierend auf Außentemperatursensor ohne manuelle Eingabe. Die vier Betriebsmodi selbst (`winter`, `summer`, `transition`, `maintenance`) sowie manuelles Umschalten zwischen ihnen sind Musskriterium (FA-014); lediglich der **vollautomatische** Wechsel ohne Benutzereingriff ist optional.
 3. Logging aller Messwerte in einer Zeitreihendatenbank (z. B. InfluxDB) für Energiebilanz-Analysen (Phase 2).
 4. Push-Benachrichtigungen (Telegram, E-Mail) bei kritischen Alarmen (Phase 2).
 5. Webbasiertes Monitoring-Dashboard über Home Assistant.
@ -92,11 +96,12 @@ Die folgenden Punkte sind explizit **nicht** Bestandteil dieses Pflichtenhefts:

 1. Home Assistant Konfiguration, Dashboards und Automatisierungen.
 2. Hydraulische Planung und Ausführung der Wärmesysteme.
-3. Netzwerk-Infrastruktur (Switch, Verkabelung, IP-Vergabe).
-4. Elektrische Hausinstallation (Zähler, Unterverteilung, Absicherung).
-5. Buderus-interne Konfiguration (Heizkurven, Hydraulikweichen).
-6. Cloud-Anbindung oder Remote-Zugriff (Phase 1).
-7. Physische Installation und Inbetriebnahme des Schaltschranks.
+3. Elektrische Hausinstallation (Zähler, Unterverteilung, Absicherung).
+4. Buderus-interne Konfiguration (Heizkurven, Hydraulikweichen).
+5. Cloud-Anbindung und externe Cloud-Services (Phase 1).
+6. Physische Installation und Inbetriebnahme des Schaltschranks (→ separates Pflichtenheft Inbetriebnahme ASP1).
+
+> **Hinweis:** Die Netzwerktopologie im Schaltschrank (Router, Switch, IP-Plan, VPN, Firewall) ist explizit **Teil dieses Pflichtenhefts** und in Abschnitt 3.6 spezifiziert.

 ---

@ -118,6 +123,8 @@ Kategorien: **FA** = Funktionale Anforderung · **NFA** = Nicht-funktionale Anfo

 ### 3.1 Funktionale Anforderungen (FA)

+Dieser Abschnitt beschreibt alle funktionalen Anforderungen an das System — d. h. was das System tun muss. Aufgeteilt in RevPi-SPS-Ebene (direkte I/O-Steuerung) und Node-RED-Ebene (Automatisierungslogik, Protokoll-Integration).
+
 #### RevolutionPi / SPS

 | ID | Verbindlichkeit | Anforderung |
@ -140,7 +147,7 @@ Kategorien: **FA** = Funktionale Anforderung · **NFA** = Nicht-funktionale Anfo
 | FA-011 | MUSS | Node-RED muss Miner-Status und Ist-Leistung via Braiins OS gRPC (braiins.bos.v1) alle ≤ 30 s abfragen und Ergebnisse auf MQTT publizieren. |
 | FA-012 | MUSS | Node-RED muss die Energiemanagement-Logik gemäß Abschnitt 10 ausführen und Miner-Leistungssetpoints auf MQTT publizieren. |
 | FA-013 | MUSS | Node-RED muss die Wärmemanagement-Logik gemäß Abschnitt 11 ausführen und Steuerbefehle für Pumpen, Ventile, Rückkühler und EVU-Sperre auf MQTT publizieren. |
-| FA-014 | MUSS | Node-RED muss vier Betriebsmodi verwalten: `winter`, `summer`, `transition`, `maintenance`. Der aktive Modus muss auf `thermiq/mode/current` (retained) publiziert werden. |
+| FA-014 | MUSS | Node-RED muss vier Betriebsmodi verwalten: `winter`, `summer`, `transition`, `maintenance`. Alle vier Modi müssen existieren und manuell schaltbar sein. Der aktive Modus muss auf `thermiq/mode/current` (retained) publiziert werden. **Hinweis:** Der vollautomatische Modus-Wechsel ohne Benutzereingriff (basierend auf Außentemperatur) ist ein Wunschkriterium (2.2.2) und kein MUSS. |
 | FA-015 | MUSS | Node-RED muss bei Safety-Trip (`safety/state = "tripped"`) alle Miner-Leistungssetpoints auf 0 setzen, Pumpen auf Minimum-Setpoint stellen und den Alarm-Flow auslösen. |
 | FA-016 | MUSS | Node-RED muss Alarme bei allen in Abschnitt 8.10 definierten Fehlerbedingungen auslösen und auf `thermiq/alarms/+` publizieren. |
 | FA-017 | MUSS | Node-RED muss Fallback-Setpoints senden, wenn der RevPi-Heartbeat mehr als 30 Sekunden ausbleibt. |
@ -154,6 +161,8 @@ Kategorien: **FA** = Funktionale Anforderung · **NFA** = Nicht-funktionale Anfo

 ### 3.2 Nicht-funktionale Anforderungen (NFA)

+Dieser Abschnitt beschreibt Qualitätsanforderungen an das System — wie es sich verhalten soll (Verfügbarkeit, Reaktionszeit, Wartbarkeit, Datensicherheit). Diese Anforderungen sind unabhängig von einzelnen Funktionen und gelten systemweit.
+
 | ID | Verbindlichkeit | Anforderung |
 |----|----------------|-------------|
 | NFA-001 | MUSS | Das gesamte System muss nach einem Stromausfall und vollständiger Netzwiederkehr ohne manuellen Eingriff selbstständig anlaufen. Alle Dienste (RevPi Python, Node-RED, sunsynk, Mosquitto) müssen als Systemd-Services mit `Restart=always` und `WantedBy=multi-user.target` konfiguriert sein. |
@ -161,7 +170,7 @@ Kategorien: **FA** = Funktionale Anforderung · **NFA** = Nicht-funktionale Anfo
 | NFA-003 | MUSS | Node-RED muss nach Neustart innerhalb von ≤ 60 Sekunden alle Flows aktiv haben und auf MQTT kommunizieren. |
 | NFA-004 | MUSS | Die Reaktionszeit der Software auf einen Safety-Trip (von Empfang des MQTT-Topics bis zur Ausgabe aller Fallback-Setpoints) darf 2 Sekunden nicht überschreiten. |
 | NFA-005 | MUSS | Alle konfigurierbaren Parameter (Schwellwerte, Sollwerte, Intervalle) müssen ohne Code-Änderung anpassbar sein — ausschließlich über Node-RED Context, Config-Flow oder `config.py`. |
-| NFA-006 | SOLL | Der Quellcode des RevPi-Programms soll ausreichend kommentiert sein, um von einem mit Python vertrauten Dritten gewartet werden zu können. |
+| NFA-006 | SOLL | Der Quellcode des RevPi-Programms soll ausreichend kommentiert sein, um von einem mit Python vertrauten Dritten gewartet werden zu können. **Anmerkung zur Programmierstrategie:** Der RevolutionPi unterstützt grundsätzlich auch CodeSys (IEC 61131-3). Für dieses Projekt wurde bewusst **Python** gewählt, da: (1) MQTT- und gRPC-Bibliotheken nativ verfügbar sind, (2) kein CodeSys-Lizenzaufwand anfällt, (3) der gesamte Stack (Node-RED, gRPC-Client, Miner-Integration) auf Python/JavaScript basiert und eine einheitliche Programmiersprache die Wartung vereinfacht. Das RevPi-Programm wird ausschließlich in Python 3 mit `paho-mqtt` und `revpimodio` entwickelt. |
 | NFA-007 | MUSS | Alle Zugangsdaten (Bearer-Token für Miner, MQTT-Passwörter) müssen in Umgebungsvariablen (`ENV`) gespeichert werden. Hardcodierung im Quellcode oder in Node-RED Flows ist unzulässig. |
 | NFA-008 | MUSS | Alle Systemkomponenten (RevPi, Site Server) müssen per NTP zeitsynchronisiert sein. Eine Abweichung > 5 Sekunden zwischen RevPi und Site Server ist unzulässig. |
 | NFA-009 | SOLL | Das System soll eine Betriebsverfügbarkeit von ≥ 99 % (maximal ≤ 87,6 Stunden ungeplanter Ausfall pro Jahr) anstreben. |
@ -171,22 +180,26 @@ Kategorien: **FA** = Funktionale Anforderung · **NFA** = Nicht-funktionale Anfo

 ### 3.3 Sicherheitsanforderungen (SA)

+Dieser Abschnitt definiert alle Anforderungen, die den sicheren Betrieb der Anlage gewährleisten. Die Hardware-Sicherheitskette hat immer Vorrang vor Software-Schutzfunktionen; die hier aufgeführten Anforderungen beschreiben ergänzende Software-Schutzebenen sowie Anforderungen an die Dokumentation der Hardware-Sicherheit.
+
 | ID | Verbindlichkeit | Anforderung |
 |----|----------------|-------------|
-| SA-001 | MUSS | Die Hardware-Sicherheitskette (Sicherheitsrelais, E-Stop, FLOW OK, TEMP MAX) muss vollständig unabhängig von der Software arbeiten. Die Software darf die Hardware-Sicherheitskette weder überbrücken noch deaktivieren. |
-| SA-002 | MUSS | Ein Safety-Reset darf ausschließlich durch manuellen Eingriff am Schaltschrank erfolgen. Ein Software-Reset des Sicherheitszustands ist unzulässig. |
+| SA-001 | MUSS | Die Hardware-Sicherheitskette (Sicherheitsrelais, E-Stop, TEMP MAX) muss vollständig unabhängig von der Software arbeiten. Die Software darf die Hardware-Sicherheitskette weder überbrücken noch deaktivieren. **Anmerkung:** Ein physischer Durchflusssensor (FLOW OK) wird nicht verbaut. Die Überwachung der Miner-Kühlkreistüchtigkeit erfolgt softwareseitig durch Auswertung der Miner-Temperaturen: ein unzureichender Durchfluss äußert sich in abnormal steigenden Temperaturen (SA-007) und wird durch die Software-Sicherheitslogik erkannt und behandelt. |
+| SA-002 | MUSS | Ein Hardware-Safety-Reset (Wiedereinschalten von K10/K11 nach Trip) erfordert zwingend einen physischen Reset-Taster am Schaltschrank — dies ist durch die Sicherheitsrelais-Beschaltung (Rückführkreis) hardware-seitig erzwungen und kann nicht software-seitig umgangen werden. **Software-Safety-Reset:** Der Software-Sicherheitszustand (MQTT `safety/state`) soll zusätzlich per Fernzugriff (VPN/SSH) quittierbar sein, um bei kurzfeitigen Sensor-Fehlalarmen nicht zwingend vor Ort erscheinen zu müssen. Der Software-Reset ändert ausschließlich den MQTT-Zustand; die Hardware-Sicherheitskette bleibt davon unberührt. |
 | SA-003 | MUSS | Das System muss bei einer Puffer-Temperatur > 80 °C (Softwaregrenze) die Miner-Leistungssetpoints auf 0 setzen und den Rückkühler einschalten, unabhängig vom aktuellen Energiebedarf. |
 | SA-004 | MUSS | Das System muss bei einer Warmwasser-Temperatur > 68 °C die EVU-Sperre aufheben (Wärmepumpe sperren), um Überhitzung zu verhindern. |
 | SA-005 | MUSS | Bei Ausfall des Deye-RS485-Pollings (kein Update > 60 s) muss das Energiemanagement in den konservativen Fallback-Modus wechseln: Miner werden abgeschaltet. |
-| SA-006 | MUSS | gRPC-Steuerbefehle an Miner dürfen nur gesendet werden, wenn `thermiq/safety/state = "ok"`. |
-| SA-007 | MUSS | Bei Plausibilitätsfehler eines Temperatursensors (Wert außerhalb −10…+95 °C) muss das System einen Alarm auslösen und in den sicheren Fallback-Zustand wechseln. Die betroffene Regelkreis-Automatik muss deaktiviert werden bis zur manuellen Quittierung. |
-| SA-008 | MUSS | Die Ventil-Verriegelung (K3/K4, K5/K6) muss sowohl auf Software-Ebene (RevPi-Programm) als auch als Hardware-Empfehlung im Schaltplan dokumentiert sein. |
+| SA-006 | MUSS | Bei `thermiq/safety/state = "tripped"` muss Node-RED sofort aktiv gRPC-Befehle an alle Miner senden, um die Leistung auf 0 W zu setzen (soweit Miner noch erreichbar). Neue Leistungs-Setpoints dürfen nur gesendet werden, wenn `thermiq/safety/state = "ok"`. Hinweis: Die Hardware-Abschaltung über K10/K11 hat Vorrang; die gRPC-Leistungsreduzierung ist eine ergänzende Software-Schutzmaßnahme für den Fall, dass die Schütze noch geschlossen sind und die Miner noch reagieren. |
+| SA-007 | MUSS | Bei Plausibilitätsfehler eines Temperatursensors (Wert außerhalb −10…+95 °C) muss das System einen Alarm auslösen und in den sicheren Fallback-Zustand wechseln. Die betroffene Regelkreis-Automatik muss deaktiviert werden bis zur Quittierung. Die Quittierung soll sowohl **physisch vor Ort** (z. B. per HA-Dashboard) als auch **per Fernzugriff via VPN** möglich sein (vgl. SA-002), um zu vermeiden, dass ein kurzfristiger Sensor-Ausreißer eine Anreise zur Anlage erzwingt. |
+| SA-008 | MUSS | Die Ventil-Verriegelung (K3 und K4 dürfen niemals gleichzeitig aktiv sein; ebenso K5/K6) muss auf zwei Ebenen sichergestellt sein: (1) **Software-Verriegelung im RevPi-Programm** — der Code prüft vor jedem Schaltbefehl, dass das Gegenstück nicht aktiv ist; (2) **Dokumentation im Schaltplan** — der Verdrahtungsplan enthält eine Notiz/Empfehlung zur Hardware-Verriegelung (z. B. mechanische oder elektrische Gegensperrung), damit auch bei zukünftigen Schaltplan-Änderungen die Verriegelungs-Absicht erkennbar bleibt. |
 | SA-009 | SOLL | Das System soll Kontaktor-Feedback (DI_K10_FB, DI_K11_FB) auf Übereinstimmung mit dem Sollzustand prüfen. Bei Diskrepanz (Soll ≠ Ist > 2 s) soll ein Alarm ausgelöst werden. |

 ---

 ### 3.4 Schnittstellenanforderungen (SI)

+Dieser Abschnitt definiert die Anforderungen an alle externen und internen Kommunikationsschnittstellen — Protokolle, Formate und physische Medien. Alle Schnittstellen müssen exakt wie spezifiziert implementiert werden, um Interoperabilität zu gewährleisten.
+
 | ID | Verbindlichkeit | Anforderung |
 |----|----------------|-------------|
 | SI-001 | MUSS | Alle internen Kommunikationen zwischen RevPi und Site Server müssen über den Mosquitto MQTT-Broker auf dem Site Server (TCP Port 1883) laufen. |
@ -199,9 +212,26 @@ Kategorien: **FA** = Funktionale Anforderung · **NFA** = Nicht-funktionale Anfo

 ---

+### 3.6 Netzwerk- und Remote-Zugriff-Anforderungen (NW)
+
+Dieser Abschnitt definiert die Anforderungen an die Netzwerktopologie im Schaltschrank sowie an den sicheren Remote-Zugriff auf das System. Remote-Zugriff ist notwendig, um Node-RED und das System aus der Ferne warten, debuggen und steuern zu können, ohne physisch vor Ort sein zu müssen.
+
+| ID | Verbindlichkeit | Anforderung |
+|----|----------------|-------------|
+| NW-001 | MUSS | Der Schaltschrank muss einen Router (z. B. GL.iNet oder vergleichbar) mit konfigurierbaren Firewall-Regeln enthalten. Alle kritischen Geräte (RevPi, Site Server, Miner) sind ausschließlich hinter diesem Router. |
+| NW-002 | MUSS | Der Router muss feste IP-Adressen für alle kritischen Geräte (RevPi, Site Server, Miner 1, Miner 2) verwalten (DHCP-Reservierung oder statische Konfiguration). |
+| NW-003 | MUSS | Der Router muss eine Firewall-Regel-Konfiguration enthalten, die ausschließlich definierten Datenverkehr zwischen den Geräten erlaubt. Unkontrollierter Zugang aus dem Hausnetz oder Internet ist unzulässig. |
+| NW-004 | MUSS | Das System muss per VPN erreichbar sein. Ein VPN-Endpunkt (z. B. WireGuard auf dem Router oder Site Server) muss konfiguriert sein, um Remote-Zugriff für Wartung und Fernsteuerung zu ermöglichen. |
+| NW-005 | MUSS | Der Site Server (Node-RED) muss per SSH über das VPN fernsteuerbar sein. SSH-Zugang ist ausschließlich über VPN erlaubt; direkte SSH-Erreichbarkeit aus dem Internet ist gesperrt. |
+| NW-006 | SOLL | Node-RED soll über das VPN per Browser erreichbar sein (Node-RED UI auf Port 1880), gesichert durch Passwortauthentifizierung. |
+| NW-007 | MUSS | Der RevPi muss per SSH über das VPN erreichbar sein (für Wartung und Programm-Updates). |
+| NW-008 | SOLL | Eine Netzwerktopologie-Dokumentation (IP-Plan, Geräteliste, offene Ports, Firewall-Regeln) soll als separates Dokument im Projektordner gepflegt werden. |
+
+---
+
 ### 3.5 Randbedingungen (RB)

-Randbedingungen sind vorgegebene Rahmenbedingungen, die nicht Gegenstand der Entwicklung sind, aber die Realisierung maßgeblich beeinflussen.
+Dieser Abschnitt listet vorgegebene Rahmenbedingungen, die nicht Gegenstand der Entwicklung sind, aber die Realisierung maßgeblich beeinflussen. Sie sind unveränderliche Vorgaben des Projekts.

 | ID | Randbedingung |
 |----|--------------|
@ -218,6 +248,8 @@ Randbedingungen sind vorgegebene Rahmenbedingungen, die nicht Gegenstand der Ent

 ## 4. Systemübersicht

+Dieser Abschnitt beschreibt die Systemarchitektur auf drei Ebenen (Supervision, Control, Field) und die Kommunikationswege zwischen den Komponenten. Er dient als Orientierung für alle weiteren Kapitel.
+
 ```
 ┌────────────────────────────────────────────────────────────────────┐
 │                  SUPERVISION LAYER (Intel N100 Site Server)         │
@ -278,55 +310,87 @@ Randbedingungen sind vorgegebene Rahmenbedingungen, die nicht Gegenstand der Ent

 ### 5.3 Netzwerk

+Die Netzwerktopologie im Schaltschrank ist ein integraler Bestandteil der Software-Inbetriebnahme. Dieser Abschnitt beschreibt die physische und logische Netzwerkkonfiguration; detaillierte Anforderungen in Abschnitt 3.6.
+
 - Ausschließlich kabelgebundenes Ethernet, kein WLAN für kritische Geräte
+- Router im Schaltschrank (z. B. GL.iNet) mit VPN-Endpunkt und Firewall
 - NTP-Zeitsynchronisation auf RevPi und Site Server verpflichtend
 - Feste IPs für RevPi, Site Server, Miner 1, Miner 2
+- VPN-Zugang für Remote-Wartung (SSH, Node-RED UI)

 ---

 ## 6. MQTT-Datenbus

+Dieser Abschnitt definiert den MQTT-Datenbus als zentrales Kommunikationsrückgrat des Systems. Er beschreibt die vollständige Topic-Struktur, die Publish/Subscribe-Zuordnungen sowie die Übertragungsqualitäts- und Persistenzregeln. Alle Komponenten kommunizieren ausschließlich über den hier definierten Bus.
+
 Mosquitto läuft auf dem Site Server. Alle Komponenten kommunizieren über diesen Broker.

 ### 6.1 Topic-Struktur

+Dieser Abschnitt definiert die vollständige MQTT-Topic-Hierarchie. Die Struktur ist verbindlich — eigenmächtige Abweichungen sind unzulässig (SI-002). Topics ohne explizite Angabe sind lesend (publish-only); als „schreibbar" markierte Topics können von externen Systemen (Node-RED, Home Assistant) beschrieben werden.
+
 ```
 thermiq/
 ├── miners/
 │   ├── 1/state              # "online" | "offline" | "error"
-│   ├── 1/power           # Watt (float)
-│   ├── 1/hashrate        # TH/s (float)
-│   ├── 2/state
-│   └── 2/power
+│   ├── 1/power              # Watt (float) — Ist-Leistung
+│   ├── 1/hashrate           # TH/s (float) — Miner 1 hat Hashrate-Feedback via gRPC
+│   ├── 1/temp               # °C (float) — Chip-Temperatur via gRPC
+│   ├── 1/power_setpoint     # Watt (float) — SCHREIBBAR, Ziel-Leistung
+│   ├── 1/contactor          # "closed" | "open" — K10 Hilfskontakt-Rückmeldung
+│   ├── 2/state              # "online" | "offline" | "error"
+│   ├── 2/power              # Watt (float) — Ist-Leistung
+│   ├── 2/temp               # °C (float) — Chip-Temperatur via gRPC
+│   ├── 2/power_setpoint     # Watt (float) — SCHREIBBAR, Ziel-Leistung
+│   └── 2/contactor          # "closed" | "open" — K11 Hilfskontakt-Rückmeldung
+│   (Hinweis: Miner 2 hat kein Hashrate-Feedback in der aktuellen Firmware-Version)
 ├── pumps/
-│   ├── p3/setpoint       # 0.0–10.0 (V, als float)
-│   ├── p4/setpoint
-│   └── p5/setpoint
+│   ├── p3/state             # "on" | "off" — Relay-Zustand (P3 = einfaches Relais, kein Drehzahlsignal)
+│   ├── p4/setpoint          # 0.0–10.0 (V, float) — SCHREIBBAR, Drehzahl-Sollwert Wilo P4
+│   └── p5/setpoint          # 0.0–10.0 (V, float) — SCHREIBBAR, Drehzahl-Sollwert Wilo P5
 ├── valves/
-│   ├── rv1/state         # "open" | "closed"
-│   └── rv2/state
+│   ├── rv1/state            # "open" | "closed" — SCHREIBBAR
+│   └── rv2/state            # "open" | "closed" — SCHREIBBAR
 ├── cooler/
-│   └── state             # "on" | "off"
+│   └── state                # "on" | "off" — SCHREIBBAR
 ├── heatpump/
-│   ├── evu_sperre        # "true" | "false"
+│   ├── evu_sperre           # "true" | "false" — SCHREIBBAR (true = WP gesperrt)
 │   └── state                # "running" | "blocked" | "fault"
 ├── inverter/
-│   ├── solar_power       # W
-│   ├── battery_soc       # % (0–100)
-│   ├── grid_power        # W (negativ = Einspeisung)
-│   └── load_power        # W
+│   ├── solar_power          # W (float) — Gesamt-PV-Erzeugung
+│   ├── pv1_power            # W (float) — PV-String 1
+│   ├── pv2_power            # W (float) — PV-String 2
+│   ├── battery_soc          # % (0–100, float)
+│   ├── battery_power        # W (float) — positiv = laden, negativ = entladen
+│   ├── battery_voltage      # V (float)
+│   ├── battery_current      # A (float)
+│   ├── battery_temperature  # °C (float)
+│   ├── grid_power           # W (float) — positiv = Bezug, negativ = Einspeisung
+│   ├── grid_voltage         # V (float)
+│   ├── grid_frequency       # Hz (float)
+│   ├── load_power           # W (float) — Hausverbrauch
+│   ├── inverter_temperature # °C (float)
+│   ├── day_pv_energy        # kWh (float) — Tagesertrag PV
+│   ├── day_load_energy      # kWh (float) — Tagesverbrauch
+│   ├── day_grid_import      # kWh (float)
+│   └── day_grid_export      # kWh (float)
 ├── temps/
-│   ├── puffer            # °C (float)
-│   ├── warmwasser        # °C (float)
-│   └── miner_outlet      # °C (float, optional)
+│   ├── puffer               # °C (float) — RevPi AI1
+│   ├── warmwasser           # °C (float) — RevPi AI2
+│   ├── aussen               # °C (float) — Außentemperatursensor
+│   ├── miner1               # °C (float) — Miner 1 Chip-Temp via gRPC (alias für miners/1/temp)
+│   └── miner2               # °C (float) — Miner 2 Chip-Temp via gRPC (alias für miners/2/temp)
 ├── safety/
 │   ├── state                # "ok" | "tripped"
-│   └── reason            # "flow" | "temp" | "estop" | "none"
+│   └── reason               # "temp_hw" | "estop" | "temp_sensor_fault" | "none"
 ├── setpoints/
-│   ├── puffer_target     # °C (Sollwert Pufferspeicher, schreibbar)
-│   └── warmwasser_target # °C (Sollwert Warmwasser, schreibbar)
+│   ├── puffer_target        # °C (float) — SCHREIBBAR, Sollwert Pufferspeicher
+│   ├── warmwasser_target    # °C (float) — SCHREIBBAR, Sollwert Warmwasser
+│   ├── miner1_power_target  # W (float) — SCHREIBBAR, Alias für miners/1/power_setpoint
+│   └── miner2_power_target  # W (float) — SCHREIBBAR, Alias für miners/2/power_setpoint
 ├── mode/
-│   └── current           # "winter" | "summer" | "transition" | "maintenance"
+│   └── current              # "winter" | "summer" | "transition" | "maintenance" — SCHREIBBAR (retained)
 └── system/
    ├── revpi/heartbeat      # Unix-Timestamp (sekündlich)
    └── nodered/heartbeat    # Unix-Timestamp (sekündlich)
@ -334,31 +398,55 @@ thermiq/

 ### 6.2 Publish/Subscribe-Zuordnung

+Dieser Abschnitt zeigt für jeden Topic-Bereich, welche Komponente publiziert und welche subscribed. Ein Topic kann nur einen primären Publisher haben.
+
 | Topic-Bereich | Publisher | Subscriber |
 |---------------|-----------|-----------|
-| `miners/+/state`, `miners/+/power` | Node-RED (gRPC) | RevPi, HA |
-| `pumps/+/setpoint` | Node-RED | RevPi |
+| `miners/+/state`, `miners/+/power`, `miners/+/hashrate`, `miners/+/temp` | Node-RED (gRPC) | RevPi, HA |
+| `miners/+/power_setpoint` | Node-RED (Energiemanagement) | Node-RED (gRPC-Flow) |
+| `miners/+/contactor` | RevPi (DI) | Node-RED, HA |
+| `pumps/p3/state` | Node-RED | RevPi |
+| `pumps/p4/setpoint`, `pumps/p5/setpoint` | Node-RED | RevPi |
 | `valves/+/state` | Node-RED | RevPi |
 | `cooler/state` | Node-RED | RevPi |
 | `heatpump/evu_sperre` | Node-RED | RevPi |
 | `inverter/+` | Node-RED (sunsynk) | Node-RED |
-| `temps/+` | RevPi (AI) | Node-RED, HA |
+| `temps/puffer`, `temps/warmwasser` | RevPi (AI) | Node-RED, HA |
+| `temps/aussen` | RevPi (AI) oder Site Server | Node-RED, HA |
+| `temps/miner1`, `temps/miner2` | Node-RED (gRPC) | Node-RED, HA |
 | `safety/+` | RevPi (DI) | Node-RED, HA |
-| `setpoints/+` | (HA in Phase 1) | Node-RED |
+| `setpoints/+` | HA oder Extern (Phase 1) | Node-RED |
 | `mode/current` | Node-RED | alle |
 | `system/+/heartbeat` | RevPi / Node-RED | gegenseitig |

 ### 6.3 QoS und Retained

- Setpoints und Modus: **QoS 1, retained=true** (überleben Neustart)
- Messwerte / Zustände: **QoS 0** (kein retained, hohe Frequenz)
- Safety-State: **QoS 1, retained=true**
- Heartbeats: **QoS 0**
+Dieser Abschnitt definiert die Übertragungsqualität und Persistenz-Einstellungen für MQTT-Nachrichten.
+
+**Nomenklatur:**
+- **QoS 0** (At most once): Nachricht wird einmal gesendet, keine Bestätigung. Geeignet für hochfrequente Messwerte, bei denen ein verlorenes Paket unerheblich ist.
+- **QoS 1** (At least once): Nachricht wird so lange wiederholt, bis der Broker eine Bestätigung sendet. Geeignet für Zustandsänderungen und Steuerbefehle.
+- **retained=true**: Der Broker speichert die letzte Nachricht eines Topics und sendet sie sofort an neue Subscribers. Wichtig für Sollwerte und Modus, damit Geräte beim Start sofort den aktuellen Sollwert kennen.
+- **retained=false**: Keine gespeicherte Nachricht — neue Subscribers erhalten erst Daten nach dem nächsten Publish.
+
+**Zuordnung:**
+
+| Topic-Kategorie | QoS | Retained | Begründung |
+|-----------------|-----|----------|-----------|
+| Setpoints (`setpoints/+`) | 1 | true | Sollwerte überleben Neustart |
+| Modus (`mode/current`) | 1 | true | Modus überleben Neustart |
+| Safety-State (`safety/state`) | 1 | true | Sicherheitszustand beim Start sofort bekannt |
+| Messwerte (`temps/+`, `inverter/+`) | 0 | false | Hohe Frequenz, Verlust akzeptabel |
+| Miner-Status (`miners/+/state`) | 0 | false | Wird regelmäßig aktualisiert |
+| Heartbeats (`system/+/heartbeat`) | 0 | false | Sekündlich, retained sinnlos |
+| Alarme (`alarms/+`) | 1 | false | Sicher zustellen, kein Retain |

 ---

 ## 7. RevolutionPi SPS-Programm

+Dieser Abschnitt beschreibt das Python-Programm auf dem RevolutionPi: seine Aufgaben, das I/O-Mapping aller physischen Anschlüsse, die Programmstruktur, den Zustandsautomaten sowie die Publish-Intervalle. Der RevPi ist die einzige Komponente mit direktem Zugriff auf physische I/Os.
+
 ### 7.1 Aufgaben

 Der RevPi ist für folgende Aufgaben zuständig:
@ -460,6 +548,8 @@ Im Zustand `SAFETY_TRIPPED`:

 ## 8. Node-RED Automatisierung

+Dieser Abschnitt beschreibt die Node-RED-Flows auf dem Site Server. Node-RED ist die einzige Quelle für Automatisierungslogik — alle Entscheidungen über Energie-, Wärme- und Sicherheitsreaktionen werden hier getroffen und über MQTT an den RevPi kommuniziert.
+
 ### 8.1 Aufgaben

 Node-RED läuft auf dem Site Server und ist für folgende Aufgaben zuständig:
@ -674,6 +764,8 @@ Erweiterung (Phase 2): Push-Benachrichtigung, E-Mail (optional).

 ## 9. Betriebsmodi

+Dieser Abschnitt beschreibt die vier Betriebsmodi des Systems und ihr Verhalten. Der aktive Modus beeinflusst maßgeblich die Energie- und Wärmemanagement-Logik. Modi sind manuell schaltbar; vollautomatisches Umschalten ist optional (vgl. 2.2.2).
+
 ### 9.1 Winter-Modus

 - Miner laufen vorrangig bei Solar-Überschuss oder günstigem Netzstrom
@ -703,6 +795,8 @@ Erweiterung (Phase 2): Push-Benachrichtigung, E-Mail (optional).

 ## 10. Energiemanagement-Logik

+Dieser Abschnitt definiert die Entscheidungslogik für den optimalen Betrieb der Kryptominer. Ziel ist es, die Miner so zu betreiben, dass sie vorrangig auf Solar- oder günstiger Batterieenergie laufen und der Haushalt energetisch nicht belastet wird.
+
 ### 10.1 Entscheidungspriorität (absteigend)

 1. Sicherheitszustand (Safety OK?)
@ -729,6 +823,8 @@ Erweiterung (Phase 2): Push-Benachrichtigung, E-Mail (optional).

 ## 11. Wärmemanagement-Logik

+Dieser Abschnitt definiert die Steuerlogik für die thermischen Komponenten der Anlage: Pumpen, Ventile, Rückkühler und Wärmepumpen-EVU-Sperre. Ziel ist es, Miner-Abwärme sinnvoll in den Pufferspeicher einzuleiten und Übertemperaturen sicher abzuführen.
+
 ### 11.1 Temperaturgrenzen

 | Sensor | Min (Alarm) | Sollwert (Default) | Max (Alarm) |
@ -760,6 +856,8 @@ Beispiel Puffer:

 ## 12. Miner-Steuerung (gRPC)

+Dieser Abschnitt beschreibt die gRPC-Kommunikation mit den Antminer S19J über die Braiins OS API. Die gRPC-Schicht ist ausschließlich für Leistungssteuerung und Status-Polling zuständig; das physische Ein-/Ausschalten der Miner erfolgt hardware-seitig über K10/K11.
+
 ### 12.1 Verbindungsmanagement

 - gRPC-Client baut Verbindung zu jedem Miner beim Start auf
@ -783,7 +881,9 @@ Beispiel Puffer:

 ## 13. Sicherheitslogik (Software-Ebene)

-> **Die Hardware-Sicherheitskette (Sicherheitsrelais, E-Stop, FLOW OK, TEMP MAX) ist vollständig hardware-unabhängig von der Software und hat IMMER Vorrang.**
+Dieser Abschnitt beschreibt die ergänzenden Software-Schutzfunktionen. Die Hardware-Sicherheitskette hat immer absoluten Vorrang; die hier definierten Maßnahmen sind eine zweite Schutzebene auf Software-Ebene, die früher eingreift und feinere Reaktionen erlaubt als die Hardware-Abschaltung.
+
+> **Die Hardware-Sicherheitskette (Sicherheitsrelais, E-Stop, TEMP MAX) ist vollständig hardware-unabhängig von der Software und hat IMMER Vorrang. Kein Durchflusssensor verbaut — Kühlkreisüberwachung erfolgt softwareseitig über Temperaturauswertung (SA-001, SA-007).**

 Die Software-Ebene ergänzt folgende Schutzfunktionen:

@ -800,6 +900,8 @@ Die Software-Ebene ergänzt folgende Schutzfunktionen:

 ## 14. Fallback- und Fehlerverhalten

+Dieser Abschnitt beschreibt das definierte Verhalten des Systems bei Komponentenausfällen oder Kommunikationsfehlern. Jeder Fehlerfall hat einen definierten sicheren Folgezustand, der die Anlage in einem kontrollierten, ungefährlichen Betrieb hält.
+
 ### 14.1 MQTT-Verbindungsverlust (RevPi)

 - RevPi verliert MQTT-Verbindung → alle letzten Befehle bleiben aktiv (kein Ändern mehr)
@ -840,6 +942,8 @@ Die Software-Ebene ergänzt folgende Schutzfunktionen:

 ## 15. Watchdog und Systemüberwachung

+Dieser Abschnitt definiert die gegenseitige Überwachung zwischen RevPi und Site Server über Heartbeat-Mechanismen sowie den Hardware-Watchdog des RevPi. Ziel ist die automatische Erkennung und Reaktion auf hängende oder abgestürzte Komponenten.
+
 ### 15.1 RevPi Watchdog

 - Hardware-Watchdog des RevPi aktivieren (Systemd-Watchdog oder RevPi-intern)
@ -863,6 +967,8 @@ Die Software-Ebene ergänzt folgende Schutzfunktionen:

 ## 16. Abnahme- und Testkriterien

+Dieser Abschnitt definiert die Testfälle und Abnahmekriterien für die Software-Abnahme. Die Tests sind in drei Ebenen aufgeteilt: RevPi I/O-Tests (Punkt-zu-Punkt), Node-RED Integrationstests (Logik und Kommunikation) und End-to-End Systemtests (vollständige Anlage). Die Abnahme der physischen Installation erfolgt separat im Pflichtenheft Inbetriebnahme ASP1.
+
 ### 16.1 RevPi I/O-Tests

 | Test | Erwartetes Ergebnis |
@ -926,18 +1032,23 @@ Die folgende Matrix verknüpft die formalen Anforderungen mit den Testfällen:

 ## 17. Offene Punkte

+Dieser Abschnitt dokumentiert Themen, die noch nicht abschließend entschieden oder spezifiziert sind und vor oder während der Implementierung geklärt werden müssen.
+
 | # | Thema | Status |
 |---|-------|--------|
 | 1 | Sensortyp Pufferspeicher (PT1000 vs. 4-20 mA) — beeinflusst AI-Kalibrierung | **offen** |
 | 2 | Sensortyp Warmwasserspeicher | **offen** |
-| 3 | Deye Modbus-Register-Map (sunsynk vs. direkte Modbus-Abfrage) | **offen** |
-| 4 | Netz-Tarif-Integration (dynamischer Strompreis, API TBD) | **Phase 2** |
-| 5 | Smart Meter Protokoll und Integration | **offen** |
-| 6 | Batterie-Kapazität und -Typ (Auswirkung auf SOC-Schwellwerte) | **offen** |
-| 7 | Außentemperatursensor (für Übergangs-Modus automatisch) | **optional** |
+| 3 | Außentemperatursensor Typ und Anschluss (RevPi AI3 oder Site Server GPIO) | **offen** |
+| 4 | Deye Modbus-Register-Map (sunsynk vs. direkte Modbus-Abfrage) | **offen** |
+| 5 | Netz-Tarif-Integration (dynamischer Strompreis, API TBD) | **Phase 2** |
+| 6 | Smart Meter Protokoll und Integration | **offen** |
+| 7 | Batterie-Kapazität und -Typ (Auswirkung auf SOC-Schwellwerte) | **offen** |
 | 8 | gRPC-Token-Rotations-Strategie (Miner Braiins OS) | **offen** |
 | 9 | Node-RED Environment-Variables Setup Dokumentation | **offen** |
 | 10 | Logging-Strategie (Influx DB, CSV, oder nur MQTT?) | **Phase 2** |
+| 11 | Router-Modell und VPN-Protokoll (WireGuard empfohlen, GL.iNet oder vergleichbar) | **offen** |
+| 12 | Netzwerktopologie-Dokumentation (IP-Plan, Firewall-Regeln) | **offen** |
+| 13 | Miner 2 Hashrate-Feedback: Firmware-Version prüfen, ggf. nachrüsten | **offen** |

 ---