From 6d081c0362655efad21a55e4a144446203dcc5b5 Mon Sep 17 00:00:00 2001 From: jacquesbach Date: Wed, 11 Mar 2026 23:11:58 +0100 Subject: [PATCH 1/4] Test des Dev Deployments --- templates/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/index.html b/templates/index.html index 6d17c01..16d6407 100644 --- a/templates/index.html +++ b/templates/index.html @@ -3,7 +3,7 @@ - Balkonkraftwerk Analytics + Balkonkraftwerk Analytics Test From 0936a2022e554543c06a281082214f5748255efd Mon Sep 17 00:00:00 2001 From: jacquesbach Date: Wed, 11 Mar 2026 23:14:20 +0100 Subject: [PATCH 2/4] =?UTF-8?q?Test=20r=C3=BCckg=C3=A4ngig?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- templates/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/templates/index.html b/templates/index.html index 16d6407..6d17c01 100644 --- a/templates/index.html +++ b/templates/index.html @@ -3,7 +3,7 @@ - Balkonkraftwerk Analytics Test + Balkonkraftwerk Analytics From 6796d21436dad11a029afb4afde5fe7fa7bdb8be Mon Sep 17 00:00:00 2001 From: jacquesbach <110992374+jacquesbach@users.noreply.github.com> Date: Thu, 12 Mar 2026 07:16:35 +0100 Subject: [PATCH 3/4] Update README.md --- README.md | 199 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 135 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 6ec32e0..b92a463 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,25 @@ -# ☀️ Balkonkraftwerk Analytics +# Balkonkraftwerk Analytics -Ein intelligentes, lokal gehostetes Dashboard zur Überwachung, Analyse und Vorhersage von Balkonkraftwerken. Dieses Projekt kombiniert Echtzeit-MQTT-Daten (kompatibel mit AhoyDTU / OpenDTU) mit modernem Machine Learning (Scikit-Learn), um nicht nur historische Daten zu visualisieren, sondern auch präzise, wetterbasierte Leistungsprognosen zu erstellen. +Ein intelligentes Monitoring-System für Balkonkraftwerke. Es kombiniert Echtzeit-Daten via MQTT mit Wettervorhersagen von Open-Meteo, um mittels Machine Learning den Ertrag der nächsten Tage vorherzusagen. -## ✨ Features -* **📡 Echtzeit-Monitoring:** Empfängt sekündliche Updates des Wechselrichters via MQTT (Leistung, Strom, Spannung, Temperatur). -* **🧠 KI-gestützter Forecast:** * Nutzt **Quantil-Regression** (GradientBoosting) zur Berechnung eines 80%-Konfidenzintervalls für die erwartete Tagesproduktion. + +## 🚀 Features + +* **Echtzeit-Monitoring:** Empfängt sekündliche Live-Werte (Leistung/Watt, Strom/Ampere, Spannung/Volt, Temperatur) des Wechselrichters via MQTT (OpenDTU/AhoyDTU). +* **Energie-Statistiken & Live-Metriken:** Präzise Errechnung der produzierten kWh mittels Trapez-Regel sowie automatische Berechnung der Ersparnis (EUR) und Spitzenwerte. +* **ML-gestützter Forecast:** Vorhersage des Ertrags (Best/Worst/Expected Case) basierend auf Bewölkung und Temperatur. + * **Quantil-Regression:** Nutzt GradientBoosting zur Berechnung eines 80%-Konfidenzintervalls für die erwartete Tagesproduktion. * **SHAP-Integration (Erklärbare KI):** Das System zeigt im Tooltip genau an, *warum* eine bestimmte Vorhersage getroffen wurde (z. B. "Wolkenbedeckung senkt den Ertrag um X Watt"). -* **📊 Interaktive Visualisierungen (Chart.js):** +* **Interaktive Visualisierungen (Chart.js):** * **Dynamisches Donut-Chart:** Zeigt die DC-Leistung pro Panel. Durch Antippen/Hovern ändert sich die zentrale Anzeige. * **Hourly Heatmap:** Visualisiert historische Erträge auf Stundenbasis für jeden Monat. - * **Live-Metriken:** Automatische Berechnung von kWh, Ersparnis (EUR) und Spitzenwerten. -* **🌦 Automatische Wetterdaten:** Integriert die kostenlose Open-Meteo API für aktuelle Bewölkung und stündliche Prognosen. -* **💾 Leichtgewichtig & Lokal:** Kein Cloud-Zwang. Speicherung erfolgt in einer lokalen SQLite-Datenbank (`solar_data.db`). Automatisches Training des ML-Modells im Hintergrund. +* **Automatische Wetterdaten:** Integriert die kostenlose Open-Meteo API für aktuelle Bewölkung und stündliche Prognosen. +* **Leichtgewichtig, Lokal & Self-Healing:** Kein Cloud-Zwang. Speicherung erfolgt in einer lokalen SQLite-Datenbank (`solar_data.db`) mit automatischer Nachberechnung fehlender Tage (Self-Healing). Das Training des ML-Modells läuft automatisch im Hintergrund. +* **Staging-System:** Vollautomatisches Deployment via GitHub Actions auf eine Live- (Port 5000) und Test-Umgebung (Port 5001). + -## 🛠 Tech Stack +## 🏗️ Tech Stack * **Backend:** Python 3.11, Flask, Flask-MQTT * **Machine Learning:** Scikit-Learn (RandomForest, GradientBoosting), SHAP, Pandas, Numpy @@ -23,65 +28,135 @@ Ein intelligentes, lokal gehostetes Dashboard zur Überwachung, Analyse und Vorh * **Datenbank:** SQLite3 ## 📂 Projektstruktur - -\`\`\`text -/ -├── app.py # Hauptanwendung (Flask Backend, MQTT, ML-Logik) -├── requirements.txt # Python-Abhängigkeiten -├── .env # (Nicht in Git) Deine geheimen Zugangsdaten -├── .env.example # Vorlage für Umgebungsvariablen -├── .gitignore # Schützt sensible Daten vor dem Upload -├── pv_model.pkl # (Wird automatisch generiert) Trainiertes ML-Modell -├── solar_data.db # (Wird automatisch generiert) SQLite Datenbank +```text +. +├── .github/workflows/ +│ ├── deploy.yml # Live-Deployment (Main Branch) +│ └── deploy-staging.yml # Staging-Deployment (Dev Branch) ├── static/ │ ├── css/ -│ │ └── style.css # Dashboard Styling +│ │ └── styles.css │ └── js/ -│ └── script.js # Frontend Logik (API-Calls, Chart.js) -└── templates/ - └── index.html # Dashboard HTML-Template -\`\`\` +│ └── script.js +├── templates/ +│ └── index.html +├── app.py +├── requirements.txt +├── .env +├── .gitignore +└── README.md +``` + -## 🚀 Installation & Setup +## 🛠 Installation & Setup ### 1. Repository klonen -\`\`\`bash -git clone https://github.com/DEIN_USERNAME/DEIN_REPO.git -cd DEIN_REPO -\`\`\` +```bash +git clone https://github.com/jacquesbach/balkonkraftwerk.git +cd balkonkraftwerk +``` ### 2. Virtuelle Umgebung & Abhängigkeiten -Es wird empfohlen, eine virtuelle Python-Umgebung zu nutzen: -\`\`\`bash -python -m venv venv -source venv/bin/activate # Unter Windows: venv\Scripts\activate +```bash +python3 -m venv venv +source venv/bin/activate pip install -r requirements.txt -\`\`\` - -### 3. Umgebungsvariablen (.env) konfigurieren -Kopiere die Vorlage und trage deine spezifischen Daten ein: -\`\`\`bash -cp .env.example .env -\`\`\` -Öffne die `.env` Datei und passe folgende Werte an: -* `ADMIN_PASS`: (Optional für zukünftige Admin-Routen) -* `LATITUDE` / `LONGITUDE`: Deine Standortkoordinaten (für Open-Meteo Vorhersagen). -* `MQTT_BROKER_URL`, `MQTT_USERNAME`, `MQTT_PASSWORD`: Deine MQTT-Broker Daten. - -*(Hinweis: Das System lauscht standardmäßig auf `inverter/+/status`, `inverter/+/ch0/P` etc. Stelle sicher, dass dein Wechselrichter/deine DTU diese Topics sendet).* - -### 4. Anwendung starten -\`\`\`bash -python app.py -\`\`\` -Die Datenbank (`solar_data.db`) wird beim ersten Start automatisch mit dem korrekten Schema initialisiert. -Das Dashboard ist nun unter `http://localhost:5000` erreichbar. - -## ⚙️ Automatisierung (Hintergrund-Tasks) - -Das Backend nutzt das `schedule` Modul in einem separaten Thread, um: -* **Stündlich:** Die Durchschnittsdaten der letzten Stunde in die Heatmap-Tabelle (`data`) zu schreiben und das Machine-Learning-Modell (`pv_model.pkl`) mit den neuesten Daten neu zu trainieren. -* **Um Mitternacht:** Die Tagesstatistik (Tagesertrag, Max-Werte, Ersparnis) zu berechnen und in die Tabelle `daily_stats` zu aggregieren. +``` + +### 3. Konfiguration (`.env`) +Erstelle eine `.env` Datei im Hauptverzeichnis: +```env +ADMIN_PASS=dein_passwort +LATITUDE=49.xxxx +LONGITUDE=8.xxxx +MQTT_BROKER_URL=deine_ip +MQTT_BROKER_PORT=1883 +MQTT_USERNAME=dein_user +MQTT_PASSWORD=dein_pw +``` +## ⚙️ Deployment (Systemd) + +Um das System mit Live- und Staging-Umgebung dauerhaft zu betreiben, werden zwei separate Instanzen und Services auf dem Ubuntu-Server eingerichtet. + +### 1. Verzeichnisstruktur vorbereiten +Klone das Projekt zweimal in unterschiedliche Ordner: +```bash +# Live-Instanz (Port 5000) +git clone [https://github.com/jacquesbach/balkonkraftwerk.git](https://github.com/jacquesbach/balkonkraftwerk.git) /home/ubuntu/balkonkraftwerk + +# Staging-Instanz (Port 5001) +git clone -b dev [https://github.com/jacquesbach/balkonkraftwerk.git](https://github.com/jacquesbach/balkonkraftwerk.git) /home/ubuntu/balkonkraftwerk-staging +``` + +### 2. Systemd Services anlegen +Erstelle zwei Service-Dateien, um beide Instanzen unabhängig voneinander zu steuern. + +**Live-Service:** `sudo nano /etc/systemd/system/balkonkraftwerk.service` +```ini +[Unit] +Description=Balkonkraftwerk Analytics - Live (Port 5000) +After=network.target + +[Service] +User=ubuntu +WorkingDirectory=/home/ubuntu/balkonkraftwerk +ExecStart=/home/ubuntu/balkonkraftwerk/venv/bin/python3 app.py +Restart=always +Environment="PORT=5000" + +[Install] +WantedBy=multi-user.target +``` + +**Staging-Service:** `sudo nano /etc/systemd/system/balkonkraftwerk-staging.service` +```ini +[Unit] +Description=Balkonkraftwerk Analytics - Staging (Port 5001) +After=network.target + +[Service] +User=ubuntu +WorkingDirectory=/home/ubuntu/balkonkraftwerk-staging +ExecStart=/home/ubuntu/balkonkraftwerk-staging/venv/bin/python3 app.py +Restart=always +Environment="PORT=5001" + +[Install] +WantedBy=multi-user.target +``` + +### 3. Dienste starten +```bash +sudo systemctl daemon-reload + +# Live starten +sudo systemctl enable --now balkonkraftwerk + +# Staging starten +sudo systemctl enable --now balkonkraftwerk-staging +``` + +### ⚠️ Wichtig: GitHub Actions konfigurieren +Damit das automatische Deployment funktioniert, müssen die Pfade in deinen `.github/workflows/*.yml` Dateien mit der Serverstruktur übereinstimmen: + +* **deploy-staging.yml:** Muss auf das Verzeichnis `/home/ubuntu/balkonkraftwerk-staging` zeigen. +* **deploy.yml:** Muss auf das Verzeichnis `/home/ubuntu/balkonkraftwerk` zeigen. + +Stelle sicher, dass dein SSH-User Schreibrechte für beide Verzeichnisse besitzt. + +## 🧪 Entwicklung & Staging +Das Projekt nutzt einen automatisierten **Staging-Workflow** via GitHub Actions: +* **Entwicklung:** Änderungen werden in den `dev` Branch gepusht. Die GitHub Action führt einen Deploy auf dem Server im Verzeichnis `/home/ubuntu/balkonkraftwerk-staging` aus. +* **Vorschau:** Änderungen sind sofort unter `http://deine-ip:5001` sichtbar. +* **Production:** Nach einem erfolgreichen Merge von `dev` in den `main` Branch aktualisiert die Action das Verzeichnis `/home/ubuntu/balkonkraftwerk` und startet den Live-Dienst neu. + +**Staging-URL:** `http://deine-ip:5001` +**Live-URL:** `http://deine-ip:5000` + +## 📈 Machine Learning Info +Die App verwendet einen `RandomForestRegressor` für den Erwartungswert und zwei `GradientBoostingRegressor`, um ein Konfidenzintervall (Quantile Regression) zu berechnen. +* **Input-Features:** Sonnenstand, Tag des Jahres (Sin/Cos), Bewölkung, Temperatur, Rollierender Durchschnitt (7 Tage). +* **Modell-Datei:** `pv_model.pkl` (wird nach jedem Tagesabschluss automatisch neu trainiert). ## 🤝 Mitwirken (Contributing) @@ -92,7 +167,3 @@ Pull Requests sind herzlich willkommen. Für größere Änderungen öffne bitte 3. Commit deine Änderungen (`git commit -m 'Add some AmazingFeature'`) 4. Push auf den Branch (`git push origin feature/AmazingFeature`) 5. Öffne einen Pull Request - -## 📄 Lizenz - -Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Details findest du in der Datei `LICENSE`. \ No newline at end of file From 4c84d69c65f51cb3b0417d5c3f2fdcc6808cfea5 Mon Sep 17 00:00:00 2001 From: jacquesbach <110992374+jacquesbach@users.noreply.github.com> Date: Thu, 12 Mar 2026 07:20:23 +0100 Subject: [PATCH 4/4] Update README.md --- README.md | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index b92a463..69e5245 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,8 @@ -# Balkonkraftwerk Analytics +# Balkonkraftwerk Analytics Dashboard Ein intelligentes Monitoring-System für Balkonkraftwerke. Es kombiniert Echtzeit-Daten via MQTT mit Wettervorhersagen von Open-Meteo, um mittels Machine Learning den Ertrag der nächsten Tage vorherzusagen. - ## 🚀 Features * **Echtzeit-Monitoring:** Empfängt sekündliche Live-Werte (Leistung/Watt, Strom/Ampere, Spannung/Volt, Temperatur) des Wechselrichters via MQTT (OpenDTU/AhoyDTU). @@ -136,19 +135,32 @@ sudo systemctl enable --now balkonkraftwerk sudo systemctl enable --now balkonkraftwerk-staging ``` -### ⚠️ Wichtig: GitHub Actions konfigurieren -Damit das automatische Deployment funktioniert, müssen die Pfade in deinen `.github/workflows/*.yml` Dateien mit der Serverstruktur übereinstimmen: +### ⚠️ Wichtig: GitHub Actions & CI/CD Setup + +Damit das automatische Deployment funktioniert, müssen zwei Dinge konfiguriert sein: + +#### 1. Pfade in den Workflows +Stelle sicher, dass die Zielverzeichnisse in deinen `.github/workflows/*.yml` Dateien exakt mit der Serverstruktur übereinstimmen: +* **deploy-staging.yml:** Zielpfad `/home/ubuntu/balkonkraftwerk-staging` +* **deploy.yml:** Zielpfad `/home/ubuntu/balkonkraftwerk` -* **deploy-staging.yml:** Muss auf das Verzeichnis `/home/ubuntu/balkonkraftwerk-staging` zeigen. -* **deploy.yml:** Muss auf das Verzeichnis `/home/ubuntu/balkonkraftwerk` zeigen. +#### 2. GitHub Secrets +Hinterlege in deinem GitHub-Repository unter `Settings > Secrets and variables > Actions` folgende Secrets, damit die Action auf deinen Server zugreifen kann: -Stelle sicher, dass dein SSH-User Schreibrechte für beide Verzeichnisse besitzt. +| Secret Name | Beschreibung | +| :--- | :--- | +| `SERVER_IP` | Die IP-Adresse deines Ubuntu-Servers | +| `SERVER_USER` | Dein Benutzername (z. B. `ubuntu`) | +| `SSH_PRIVATE_KEY` | Dein privater SSH-Schlüssel (für den passwortlosen Login) | + +--- ## 🧪 Entwicklung & Staging Das Projekt nutzt einen automatisierten **Staging-Workflow** via GitHub Actions: -* **Entwicklung:** Änderungen werden in den `dev` Branch gepusht. Die GitHub Action führt einen Deploy auf dem Server im Verzeichnis `/home/ubuntu/balkonkraftwerk-staging` aus. -* **Vorschau:** Änderungen sind sofort unter `http://deine-ip:5001` sichtbar. -* **Production:** Nach einem erfolgreichen Merge von `dev` in den `main` Branch aktualisiert die Action das Verzeichnis `/home/ubuntu/balkonkraftwerk` und startet den Live-Dienst neu. + +1. **Entwicklung:** Änderungen werden in den `dev` Branch gepusht. Die GitHub Action führt einen Deploy auf dem Server im Verzeichnis `/home/ubuntu/balkonkraftwerk-staging` aus. +2. **Vorschau:** Änderungen sind sofort unter `http://deine-ip:5001` sichtbar. +3. **Production:** Nach einem erfolgreichen Merge von `dev` in den `main` Branch aktualisiert die Action das Live-Verzeichnis und startet den Dienst `balkonkraftwerk.service` neu. **Staging-URL:** `http://deine-ip:5001` **Live-URL:** `http://deine-ip:5000`