From 0513248d7febfad8e3ad9dc38ebf8b65b5ae5398 Mon Sep 17 00:00:00 2001 From: Adrian Bretsch Date: Fri, 8 May 2026 12:35:21 +0200 Subject: [PATCH] =?UTF-8?q?Update=20Pflichtenheft=20v2.0=20=E2=86=92=20v2.?= =?UTF-8?q?1=20based=20on=20Adrian's=20feedback?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- docs/HARDWARE.md | 13 +- docs/PFLICHTENHEFT_SOFTWARE.md | 231 ++++++++++++++++++++++++--------- 2 files changed, 183 insertions(+), 61 deletions(-) diff --git a/docs/HARDWARE.md b/docs/HARDWARE.md index 70f3318..5970c7a 100644 --- 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 diff --git a/docs/PFLICHTENHEFT_SOFTWARE.md b/docs/PFLICHTENHEFT_SOFTWARE.md index 6b5f994..b28a799 100644 --- 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,87 +310,143 @@ 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/state # "online" | "offline" | "error" +│ ├── 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" -│ └── state # "running" | "blocked" | "fault" +│ ├── 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" +│ ├── state # "ok" | "tripped" +│ └── 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) + ├── revpi/heartbeat # Unix-Timestamp (sekündlich) + └── nodered/heartbeat # Unix-Timestamp (sekündlich) ``` ### 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** | ---