Zendure API (#7)

* Erster Test Daten von Zendure lesen

* Zendure-Werte auf dem Dashboard darstellen.
Akku Ladung/Entladung berechnen.

* Zenduredaten konfigurable, Anleitung erweitert

* Zendure:
- Akkustandsanzeige
- Ladezeit  der Statusseiten optimiert

Bugfixes:
- Falscher Einkaufswert in den Übersichtsseiten in der obersten Zeile
- Richtige Kurzschreibweise Monat März

* Zendure: Darstellung und Logmeldungen verbessert

* Zendure simple Stats

* Bugfix: Berechnung Einspeisung + Ersparnis
Energietabelle: Ersparnis in 1. Spalte

* Readme angepasst, kleine Anpassungen

Author: SvenoF54

README.md

@@ -4,6 +4,8 @@
 
 <img src="./images/gallery/dashboard_mobile.png" alt="Mobile Dashboardansicht" width="250">
 
+<img src="./images/gallery/hours-overview_mobile.png" alt="Mobile Stundenübersicht" width="250">
+
 Zur Bildergallerie [gallery.md](gallery.md)
 
 ## Beschreibung
@@ -17,7 +19,7 @@ Der Benutzer muss einen eigenen PHP- und MySQL-Provider anmieten / bereitstellen
 
 ### Zielsetzung
 
-Das Projekt richtet sich an technisch erfahrene Benutzer, die ihren privaten Echtzeit-Energieverbrauch und/oder ihre private Echtzeit-Stromerzeugung durch PV-Anlagen, Balkonkraftwerke oder andere Energieerzeuger im Detail analysieren möchten. Die Software kann mobil auf dem Handy als auch auf dem PC benutzt werden. 
+Das Projekt richtet sich an technisch erfahrene Benutzer, die ihren privaten Echtzeit-Energieverbrauch und/oder ihre private Echtzeit-Stromerzeugung durch PV-Anlagen, Balkonkraftwerke, Akkusysteme oder andere Energieerzeuger in der eigenen Datenbank speichern möchten. Es werden umfangreiche Analyseansichten angeboten, wie z.B. eine nahezu Echtzeitübersicht, eine Eigenverbrauchsquote oder eine Autarkieansicht jeweils für Stunden, Tage, Monate oder Jahre. Die Software kann mobil auf dem Handy als auch auf dem PC benutzt werden. 
 
 Beispielsweise können Stromspitzen in Echtzeit erkannt und mithilfe von zwei Berechnungslinien analysiert werden. Dies ermöglicht es, den Energieverbrauch oberhalb, unterhalb oder zwischen den definierten Linien zu ermitteln.
 
@@ -56,7 +58,8 @@ In der Datenbank ist pro Zeitabschnitt ein Wert für Verbrauchsdaten vorgesehen,
 - **Netzeinspeisung**: Definiert die überschüssige erzeugte Energie, die nicht selbst verbraucht wird.
 
 ### Echtzeitdaten und Daten-Logger
-Die Echtzeitdaten und Stundenübersicht sind nur in Verbindung mit Echtzeitdaten sinnvoll nutzbar. Gleiches gilt für die Tagesansicht, da man in der Regel nur Werte für einen ganzen Monat manuell eingibt.  
+Die Echtzeitdaten und Stundenübersicht sind nur in Verbindung mit Echtzeitdaten sinnvoll nutzbar. Gleiches gilt für die Tagesansicht, da man in der Regel nur Werte für einen ganzen Monat manuell eingibt. Es handelt sich hierbei um eine nahezu Echtzeitanzeige, d.h. es tritt immer eine geringe Verzögerung im Sekundenbereich auf. 
+
 Für das Datenlogging der Echtzeitdaten gibt es eine API, die diese entgegennimmt und in die Datenbank speichert. Dieses Projekt enthält Skripte für die Shelly-Energiemesssensoren. Bitte unbedingt die Sicherheitshinweise beachten, falls Sensoren genutzt werden, die in die Elektroinstallation eingebaut werden.
 Die API kann auch mit anderen Energiedaten bedient werden, man kann sich also auch ein Skript für andere Geräte programmieren.
 
@@ -78,6 +81,10 @@ Preisdaten können ebenfalls manuell für mehrere Zeiträume eingegeben werden.
 ### Status fehlender Werte
 Hier wird ein Status angezeigt, der einen Überblick über die Datenabdeckung gibt und die Möglichkeit bietet, fehlende Daten manuell nachzupflegen. Falls bei der Berechnung der Echtzeitdaten ein Fehler beim Cronjob aufgetreten ist, kann der Monat manuell nachberechnet werden. Fehlen allerdings die Echtzeitdaten vollständig, bleibt die Lücke bestehen.
 
+### Zendure (Hyper 2000 System)
+Es können Daten von dem Zendure System zusätzlich mit angezeigt werden. Derzeit ist es nur mit dem Hyper 2000 System getestet, da keine spezifischen Hyper 2000 Werte benutzt werden, sollten auch die anderen Zendure Systeme funktionieren.
+Die Daten werden von der offiziellen Zendure-API aus deren Cloud ausgelesen.
+
 ## Lizenz
 
 Dieses Projekt ist unter der [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html) lizenziert. Sie dürfen es verwenden, modifizieren und weitergeben, solange alle Kopien und abgeleiteten Werke ebenfalls unter dieser Lizenz stehen.
@@ -117,6 +124,14 @@ Das Projekt nutzt folgende Open-Source-Bibliotheken:
 7. **Bootstrap Icons** - [Bootstrap Icons](https://icons.getbootstrap.com/)
    - **Funktion**: Sammlung von Icons für die Verwendung in Bootstrap-basierten Webseiten.
 
+8. **Bluerhinos phpmqtt** - [Bluerhinos phpmqtt](https://github.com/bluerhinos/phpMQTT/)
+   - **Funktion**: Optional Bluerhinos phpmqtt Bibliothek, derzeit für die Zendure Anbindung.
+
+9. **Zendure API** - [Zendure API](https://github.com/Zendure/developer-device-data-report)
+   - **Funktion**: Optional, falls ein Zendure Akkusystem benutzt wird, um die Daten aus der Zendure API zu lesen.
+
+
+
 ## Shelly-Geräte und Skripte
 
 ### Verwendung von Shelly-Geräten und -Skripten
@@ -142,3 +157,9 @@ Ebenso wird keine Haftung für die erfassten Daten, deren Speicherung oder deren
 Darüber hinaus wird keine Verantwortung für etwaige Datenverluste, Abwärtskompatibilitätsprobleme (z. B. nach einem Update) oder andere technische Probleme übernommen. Es wird ausdrücklich empfohlen, regelmäßig ein Backup der Datenbank zu erstellen, um den Verlust wichtiger Informationen zu vermeiden.
 
 **Wichtiger Hinweis**: Die Geräte und Skripte dürfen nur in Übereinstimmung mit den geltenden gesetzlichen Bestimmungen und Sicherheitsvorgaben genutzt werden.
+
+## Zendure Geräte und API (Optional)
+
+### Auslesen von PV Ertrag sowie Akkudaten
+
+Falls entsprechend konfiguriert, wird die Zendure-API benutzt um den Erzeugten PV-Ertrag und den aktuellen Akkustand auszulesen. Aktuell nur mit dem Hyper 2000 System getestet.

api/get-dashboard-data.php

@@ -4,12 +4,12 @@
 
 include_once("lib/appLibLoader.php");
 
-//ApiHelper::assertApiKeyIsCorrect(isset($_REQUEST["apikey"]) ? $_REQUEST["apikey"] : "");
+#ApiHelper::assertApiKeyIsCorrect(isset($_REQUEST["apikey"]) ? $_REQUEST["apikey"] : "");
 
 $actualConfig = Configuration::getInstance()->monthsOverview();
 
 $dashboardService = new DashboardService();
 $dashboardService->prepareInstantData();
-$jsondData = $dashboardService->getInstantDataAsJson();
+$jsonData = $dashboardService->getInstantDataAsJson();
 
-ApiHelper::dieWithJsonResponse($jsondData);
+ApiHelper::dieWithJsonResponse($jsonData);

api/get-hasAlert.php

@@ -4,7 +4,7 @@
 
 include_once("lib/appLibLoader.php");
 
-//ApiHelper::assertApiKeyIsCorrect(isset($_REQUEST["apikey"]) ? $_REQUEST["apikey"] : "");
+#ApiHelper::assertApiKeyIsCorrect(isset($_REQUEST["apikey"]) ? $_REQUEST["apikey"] : "");
 $hasAlert = TaskService::hasAlertStatus();
 $jsondData = json_encode(["hasAlert" => $hasAlert]);
 

api/taskrunner.php

@@ -11,6 +11,11 @@
 
 TaskService::checkRealtimeEnergyData();
 
+if ($currentMinute % 1 === 0) {
+    // Every minute
+    TaskService::readZendureData();
+}
+
 if ($currentMinute % 5 === 0) {
     // Every 5 minutes
     TaskService::unifyRealTimeData();

config/local-config.php.sample

@@ -25,12 +25,12 @@ define('SYSTEM_EMAIL', 'mail@example.org');  // Mailempfänger für Systemnachri
 $config = Configuration::getInstance();
 
 // Konfiguriert, den Alarmstatus, falls keine Daten geloggt werden.
-$config->configRealtimeAlert()->setSendAlertMail(true);
-$config->configRealtimeAlert()->setAlertThresholdInMinutes(5);      // Wenn x Minuten keine Einträge gefunden werden, wird ein Mail und ein Hinweis in der Navigation gezeigt, solange das Problem besteht.
-$config->configRealtimeAlert()->setSendAlertMailEveryXMinutes(30);  // Die Mail wird alle x Minuten erneut gesendet, solange das Problem besteht.
-$config->configRealtimeAlert()->setShouldAlertForEnergyType(EnergyTypeEnum::EM, true);  // Welche Kanäle überwacht werden
-$config->configRealtimeAlert()->setShouldAlertForEnergyType(EnergyTypeEnum::PM1, true);
-$config->configRealtimeAlert()->setShouldAlertForEnergyType(EnergyTypeEnum::PM3, true);
+$config->realtimeAlert()->setSendAlertMail(true);
+$config->realtimeAlert()->setAlertThresholdInMinutes(5);      // Wenn x Minuten keine Einträge gefunden werden, wird ein Mail und ein Hinweis in der Navigation gezeigt, solange das Problem besteht.
+$config->realtimeAlert()->setSendAlertMailEveryXMinutes(30);  // Die Mail wird alle x Minuten erneut gesendet, solange das Problem besteht.
+$config->realtimeAlert()->setShouldAlertForEnergyType(EnergyTypeEnum::EM, true);  // Welche Kanäle überwacht werden
+$config->realtimeAlert()->setShouldAlertForEnergyType(EnergyTypeEnum::PM1, true);
+$config->realtimeAlert()->setShouldAlertForEnergyType(EnergyTypeEnum::PM3, true);
 
 // Konfiguriert einige Werte auf der Energy-Chart-Seite
 // Es gibt jeweils 2 Energiesets, welche Energie1 und Energie2 heißen und einzeln konfiguriert werden können.
@@ -80,4 +80,17 @@ $config->hoursOverview()->configEnergy1()->setTablePageLength(10);
 // Die Echtzeitübersichtsseite hat zusätzlich folgende Optionen, es sind nicht alle Optionen der Übersichtsseite benutzbar
 $config->realtimeOverview()->setPastPeriodPossibilities([0.5, 1, 2, 4, 6, 8, 12, 24, 24*7, 24*14, 24*28]);
 $config->realtimeOverview()->setRefreshIntervalInSec(5);
+
+// Zendure
+$config->zendure()->setAppKey("DeinAppKey");                            // Der AppKey, siehe Installationsanleitung
+$config->zendure()->setAppSecret("DeinAppSecret");                      // Das AppSecret, siehe Installationsanleitung
+$config->zendure()->setReadTimeInSec(60);                               // Wie lange ein Request die Zendure Nachrichten abfragt, hängt vom Timeout des Webservers ab.
+$config->zendure()->setDisplayName("Akku");                             // Name auf dem Dashboard
+$config->zendure()->setConnectedToPmPort("PM3");                        // An welcher Phase der Zendure angeschlossen ist. Kann auch in der Echtzeitübersicht erkannt werden
+$config->zendure()->setCalculatePackData(true);                         // Wenn Zendure im Smart Mode, also mit Nulleinspeisung betrieben wird, bekommt man schnellere ungefähr Werte, wenn der Akku berechnet wird.
+
+$config->dashboardPage()->setShowZendureOnDashboard(false);             // Falls ein Zendure-System benutzt wird, das die Werte auf dem Dashboard angezeigt werden
+$config->dashboardPage()->setConsumptionIndicatedAs100Percent(6000);  	// Max. Wert für 100% Hausverbrauch, z.B. 6000W
+$config->dashboardPage()->setMaxEnergyProduction(1600);					// Max. Wert für Energieproduktion, z.B. 1600W PV-Panel Leistung
+
 ?>

css/allPages.css

@@ -100,6 +100,11 @@ body {
     --autarky-color2: rgba(97, 141, 141, 0.6);
     --self-consumption-color: rgba(127, 181, 181, 0.3);
     --self-consumption-color2: rgba(97, 141, 141, 0.3);
+    --akku-red-color: rgba(233, 115, 115, 0.8);
+    --akku-orange-color: rgba(239, 180, 120, 0.8);
+    --akku-yellow-color: rgba(240, 210, 130, 0.8);
+    --akku-green-color: rgba(145, 195, 165, 0.8);
+    --akku-greenfull-color: rgba(102, 179, 102, 0.8);
 }
 
 .em-color {
@@ -181,3 +186,23 @@ body {
 .self-consumption-color2 {
     background-color: var(--self-consumption-color2);
 }
+
+.akku-red-color {
+    background-color: var(--akku-red-color);
+}
+
+.akku-orange-color {
+    background-color: var(--akku-orange-color);
+}
+
+.akku-yellow-color {
+    background-color: var(--akku-yellow-color);
+}
+
+.akku-green-color {
+    background-color: var(--akku-green-color);
+}
+
+.akku-greenfull-color {
+    background-color: var(--akku-greenfull-color);
+}

css/dashboardPage.css

@@ -50,20 +50,27 @@
     position: relative;
 }
 
-.progress-bar-1 {
+.progress-bar-house {
     height: 100%;
     width: 0%;
     transition: width 1.5s ease-in-out;
     background: linear-gradient(90deg, var(--em-over-zero-color), var(--em-over-zero-color));
 }
 
-.progress-bar-2 {
+.progress-bar-production {
     height: 100%;
     width: 0%;
     transition: width 1.5s ease-in-out;
     background: linear-gradient(90deg, var(--pm-total-color), var(--pm-total-color));
 }
 
+.progress-bar-akkupack {
+    height: 100%;
+    width: 0%;
+    transition: width 1.5s ease-in-out;
+    background: var(--akku-orange-color)
+}
+
 .table-custom th,
 .table-custom td {
     text-align: center;

dashboard.php

@@ -5,7 +5,7 @@
 include_once("lib/appLibLoader.php");
 
 // Defaults
-$actualConfig = Configuration::getInstance()->configDashboardPage();;
+$actualConfig = Configuration::getInstance()->dashboardPage();;
 $dashboardsServce = new DashboardService();
 $dashboardsServce->prepareStaticData();
 $overviewPageService = new OverviewPageService();

install.md

@@ -144,3 +144,47 @@ AuthName "Bitte Anmelden"
 AuthUserFile /www/htdocs/[pfad]/[zum]/[projekt]/.htpasswd
 Require valid-user
 ```
+## Zendure (optional, rudimentär)
+
+Es kann der aktuelle Wert der PV Stromgenerierung und der Akkustand aus dem Zendure-System ausgelesen und mit angezeigt werden. Die Werte werden dann außerdem auf dem Dashboard auch für die Anzeige der gesamten Energieproduktion berücksichtigt. Dies zeigt dann auch die PV-Energie an, welche für das Laden des Akkus verwendet wird.
+Die Werte werden über die API ausgelesen und in der DB zwischengespeichert.
+
+Beim Lesen der Zendure-Werte kann es zu geringfügigen Datenverlusten, insbesondere bei der aktuellen PV-Leistung kommen, wodurch ggfls. die Echtzeitanzeige etwas verfälscht ist. Die Akkudaten können auch berechnet werden, weil die API die Akkudaten nur ~ alle Minute sendet und im Smart-Modus dann nur ein Indiz sind.
+
+Hintergrund: Das Auslesen erfolgt per einzelne Requests durch den TaskManager welcher dann einen gewissen Zeitraum läuft, da auf dem Webserver kein dauerhafter Prozess laufen kann. Dies ist nicht so, wie das MQQT-Protokoll es vorsieht, funktioniert aber auch. Deshalb ist das Feature als rudimentär gekennzeichnet.
+
+Um ein Zendure-System anzubinden, sind folgende Schritt notwendig:
+
+1. AppKey und AppSecret für die Zendure API besorgen
+Als Vorbereitung muss man die Seriennummer aus der Zendure-App im Einstellungsbereich auslesen.
+Mit der Seriennummer und die E-Mail, mit welcher man sich registriert hat setzt man folgenden Befehl ab, um die Zugangsdaten zu erhalten:
+- Eingabeaufforderung (cmd) öffnen
+- Die Werte in diesem Befehl entsprechend ersetzen und abschicken:
+- Nicht empfohlen: Bei Zertifikatsfehlermeldung am Ende --insecure anhängen.
+
+```
+curl -i --json "{'snNumber': '<deine Seriennummer>', 'account': '<dein Account>'}" https://app.zendure.tech/eu/developer/api/apply
+
+```
+
+Als Ergebnis erhält man ein JSON, das so aussieht:
+```
+{"code":200,"success":true,"data":{"appKey":"DeinAppKey","secret":"DeinAppSecret","mqttUrl":"mqtt.zen-iot.com","port":1883},"msg":"Successful operation"}
+```
+
+Die Werte von DeinAppKey + DeinAppSecret werden in der local-config.php eingetragen.
+Folgende Einstellungen können für Zendure vorgenommen werden:
+
+```
+// Zendure
+$config->zendure()->setAppKey("DeinAppKey");                            // Der oben gelesene AppKey
+$config->zendure()->setAppSecret("DeinAppSecret");                      // Das oben gelesene AppSecret
+$config->zendure()->setReadTimeInSec(60);                               // Wie lange ein Request die Zendure Nachrichten abfragt, hängt vom Timeout des Webservers ab.
+$config->zendure()->setDisplayName("Akku");                             // Name auf dem Dashboard
+$config->zendure()->setConnectedToPmPort("PM3");                        // An welcher Phase der Zendure angeschlossen ist. Kann auch in der Echtzeitübersicht erkannt werden
+$config->zendure()->setCalculatePackData(true);                         // Wenn Zendure im Smart Mode, also mit Nulleinspeisung betrieben wird, bekommt man schnellere ungefähre Werte, wenn der Akku berechnet wird.
+
+$config->dashboardPage()->setShowZendureOnDashboard(true);              // Falls ein Zendure-System benutzt wird, das die Werte auf dem Dashboard angezeigt werden
+$config->dashboardPage()->setConsumptionIndicatedAs100Percent(6000);  	// Max. Wert für 100% Hausverbrauch, z.B. 6000W
+$config->dashboardPage()->setMaxEnergyProduction(1600);					// Max. Wert für Energieproduktion, z.B. 1600W PV-Panel Leistung
+```

js/dashboard/documentReady.js

@@ -3,23 +3,6 @@
 
 $(document).ready(function() {
 
-    function prepareCircle(id, color) {
-        return new ProgressBar.Circle(id, {
-            color: color,
-            strokeWidth: 10,
-            trailColor: '#e0e0e0',
-            duration: 500,
-            easing: 'easeInOut',
-            text: {
-                value: '0%',
-                className: 'progress-text'
-            },
-            step: function(state, bar) {
-                bar.setText(Math.round(bar.value() * 100) + '%');
-            }
-        });
-    }
-
     // Prepare Cirlce for now
     var autarkyColorRGB = autarkyColor.replace(/rgba?\(([^,]+),([^,]+),([^,]+),?.*\)/, 'rgb($1,$2,$3)'); // Extracts RGB-Part from RGBA
     var circleNow = prepareCircle('#circle-now', autarkyColorRGB);
@@ -56,13 +39,22 @@ $(document).ready(function() {
                 circleNow.animate(response.now.autInPct / 100);
                 circleToday.animate(response.today.autInPct / 100);
 
+                // Bar 1 (Hausdaten)
                 $("#em-now-bar").css("width", (response.now.emPercent) + "%");
                 $("#em-now-bar").css("background", response.now.em > 0 ? emOverZeroColor : feedInColor);
                 $('#now-em-caption').html(response.now.em > 0 ? "Einkauf" : "Einspeisung");
-                $("#pm-now-bar").css("width", (response.now.pmPercent) + "%");
 
-                // set zero feed in active
-                $('#zeroFeedInActive').toggle(response.now.isZeroFeedInActive);
+                // Bar 2 (Produktionsdaten)
+                $("#pm-now-bar").css("width", (response.now.productionPercent) + "%");
+                $('#zeroFeedInActive').toggle(response.now.isZeroFeedInActive); // Set zero feed in active msg
+
+                // Bar 3 (Zendure Batteriedaten)
+                $("#pm-pack-bar").css("width", (response.zendure.akkuPackLevelPercent) + "%");
+                $("#pm-pack-bar").css("background-color", "var(--" + getAkkuColor(response.zendure.akkuPackLevelPercent) + ")");
+                $('#zendure-chargeActive').toggle(response.zendure.isZendureChargeActive);
+                $('#zendure-dischargeActive').toggle(response.zendure.isZendureDischargeActive);
+                $('#zendure-dataloss').toggle(response.zendure.isDataloss);
+                $('#zendure-akkuPackLevelPercent').toggle(!response.zendure.isDataloss);
 
             },
 
@@ -72,20 +64,45 @@ $(document).ready(function() {
         });
     }
 
-    // Initialer Aufruf
+    // Initial call + intervall
     fetchDashboardData();
-
-    // Wiederhole den Abruf alle 1 Sekunden
     setInterval(fetchDashboardData, 2000);
 
+    // Format helper
     function formatJsValue(category, key, value) {
         if (key.toLowerCase().includes("price")) {
             return formatPrice(value);
-        }
-        if (category.toLowerCase().includes("now")) {
+        } else if (category.toLowerCase().includes("now")) {
             return formatCurrent(value);
+        } else if (key.toLowerCase().includes("percent")) {
+            return formatNumber(value, 0) + "%";
         }
 
         return formatCurrent(value, "h");
     }
+
+    // Prepare circle
+    function prepareCircle(id, color) {
+        return new ProgressBar.Circle(id, {
+            color: color,
+            strokeWidth: 10,
+            trailColor: '#e0e0e0',
+            duration: 500,
+            easing: 'easeInOut',
+            text: {
+                value: '0%',
+                className: 'progress-text'
+            },
+            step: function(state, bar) {
+                bar.setText(Math.round(bar.value() * 100) + '%');
+            }
+        });
+    }
+
+    function getAkkuColor(stateInPercent) {
+        if (stateInPercent < 9) return "akku-red-color";
+        if (stateInPercent >= 9 && stateInPercent < 25) return "akku-orange-color";
+        if (stateInPercent >= 25 && stateInPercent < 85) return "akku-green-color";
+        if (stateInPercent >= 85) return "akku-greenfull-color";
+    }
 });