Skip to content

Commit 6796d21

Browse files
jacquesbachjacquesbach
authored
Update README.md
1 parent 0936a20 commit 6796d21

1 file changed

Lines changed: 135 additions & 64 deletions

File tree

‎README.md‎

Lines changed: 135 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,25 @@
1-
# ☀️ Balkonkraftwerk Analytics
1+
# Balkonkraftwerk Analytics
22

3-
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.
3+
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.
44

5-
## ✨ Features
65

7-
* **📡 Echtzeit-Monitoring:** Empfängt sekündliche Updates des Wechselrichters via MQTT (Leistung, Strom, Spannung, Temperatur).
8-
* **🧠 KI-gestützter Forecast:** * Nutzt **Quantil-Regression** (GradientBoosting) zur Berechnung eines 80%-Konfidenzintervalls für die erwartete Tagesproduktion.
6+
7+
## 🚀 Features
8+
9+
* **Echtzeit-Monitoring:** Empfängt sekündliche Live-Werte (Leistung/Watt, Strom/Ampere, Spannung/Volt, Temperatur) des Wechselrichters via MQTT (OpenDTU/AhoyDTU).
10+
* **Energie-Statistiken & Live-Metriken:** Präzise Errechnung der produzierten kWh mittels Trapez-Regel sowie automatische Berechnung der Ersparnis (EUR) und Spitzenwerte.
11+
* **ML-gestützter Forecast:** Vorhersage des Ertrags (Best/Worst/Expected Case) basierend auf Bewölkung und Temperatur.
12+
* **Quantil-Regression:** Nutzt GradientBoosting zur Berechnung eines 80%-Konfidenzintervalls für die erwartete Tagesproduktion.
913
* **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").
10-
* **📊 Interaktive Visualisierungen (Chart.js):**
14+
* **Interaktive Visualisierungen (Chart.js):**
1115
* **Dynamisches Donut-Chart:** Zeigt die DC-Leistung pro Panel. Durch Antippen/Hovern ändert sich die zentrale Anzeige.
1216
* **Hourly Heatmap:** Visualisiert historische Erträge auf Stundenbasis für jeden Monat.
13-
* **Live-Metriken:** Automatische Berechnung von kWh, Ersparnis (EUR) und Spitzenwerten.
14-
* **🌦 Automatische Wetterdaten:** Integriert die kostenlose Open-Meteo API für aktuelle Bewölkung und stündliche Prognosen.
15-
* **💾 Leichtgewichtig & Lokal:** Kein Cloud-Zwang. Speicherung erfolgt in einer lokalen SQLite-Datenbank (`solar_data.db`). Automatisches Training des ML-Modells im Hintergrund.
17+
* **Automatische Wetterdaten:** Integriert die kostenlose Open-Meteo API für aktuelle Bewölkung und stündliche Prognosen.
18+
* **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.
19+
* **Staging-System:** Vollautomatisches Deployment via GitHub Actions auf eine Live- (Port 5000) und Test-Umgebung (Port 5001).
20+
1621

17-
## 🛠 Tech Stack
22+
## 🏗️ Tech Stack
1823

1924
* **Backend:** Python 3.11, Flask, Flask-MQTT
2025
* **Machine Learning:** Scikit-Learn (RandomForest, GradientBoosting), SHAP, Pandas, Numpy
@@ -23,65 +28,135 @@ Ein intelligentes, lokal gehostetes Dashboard zur Überwachung, Analyse und Vorh
2328
* **Datenbank:** SQLite3
2429

2530
## 📂 Projektstruktur
26-
27-
\`\`\`text
28-
/
29-
├── app.py # Hauptanwendung (Flask Backend, MQTT, ML-Logik)
30-
├── requirements.txt # Python-Abhängigkeiten
31-
├── .env # (Nicht in Git) Deine geheimen Zugangsdaten
32-
├── .env.example # Vorlage für Umgebungsvariablen
33-
├── .gitignore # Schützt sensible Daten vor dem Upload
34-
├── pv_model.pkl # (Wird automatisch generiert) Trainiertes ML-Modell
35-
├── solar_data.db # (Wird automatisch generiert) SQLite Datenbank
31+
```text
32+
.
33+
├── .github/workflows/
34+
│ ├── deploy.yml # Live-Deployment (Main Branch)
35+
│ └── deploy-staging.yml # Staging-Deployment (Dev Branch)
3636
├── static/
3737
│ ├── css/
38-
│ │ └── style.css # Dashboard Styling
38+
│ │ └── styles.css
3939
│ └── js/
40-
│ └── script.js # Frontend Logik (API-Calls, Chart.js)
41-
└── templates/
42-
└── index.html # Dashboard HTML-Template
43-
\`\`\`
40+
│ └── script.js
41+
├── templates/
42+
│ └── index.html
43+
├── app.py
44+
├── requirements.txt
45+
├── .env
46+
├── .gitignore
47+
└── README.md
48+
```
49+
4450

45-
## 🚀 Installation & Setup
51+
## 🛠 Installation & Setup
4652

4753
### 1. Repository klonen
48-
\`\`\`bash
49-
git clone https://github.com/DEIN_USERNAME/DEIN_REPO.git
50-
cd DEIN_REPO
51-
\`\`\`
54+
```bash
55+
git clone https://github.com/jacquesbach/balkonkraftwerk.git
56+
cd balkonkraftwerk
57+
```
5258

5359
### 2. Virtuelle Umgebung & Abhängigkeiten
54-
Es wird empfohlen, eine virtuelle Python-Umgebung zu nutzen:
55-
\`\`\`bash
56-
python -m venv venv
57-
source venv/bin/activate # Unter Windows: venv\Scripts\activate
60+
```bash
61+
python3 -m venv venv
62+
source venv/bin/activate
5863
pip install -r requirements.txt
59-
\`\`\`
60-
61-
### 3. Umgebungsvariablen (.env) konfigurieren
62-
Kopiere die Vorlage und trage deine spezifischen Daten ein:
63-
\`\`\`bash
64-
cp .env.example .env
65-
\`\`\`
66-
Öffne die `.env` Datei und passe folgende Werte an:
67-
* `ADMIN_PASS`: (Optional für zukünftige Admin-Routen)
68-
* `LATITUDE` / `LONGITUDE`: Deine Standortkoordinaten (für Open-Meteo Vorhersagen).
69-
* `MQTT_BROKER_URL`, `MQTT_USERNAME`, `MQTT_PASSWORD`: Deine MQTT-Broker Daten.
70-
71-
*(Hinweis: Das System lauscht standardmäßig auf `inverter/+/status`, `inverter/+/ch0/P` etc. Stelle sicher, dass dein Wechselrichter/deine DTU diese Topics sendet).*
72-
73-
### 4. Anwendung starten
74-
\`\`\`bash
75-
python app.py
76-
\`\`\`
77-
Die Datenbank (`solar_data.db`) wird beim ersten Start automatisch mit dem korrekten Schema initialisiert.
78-
Das Dashboard ist nun unter `http://localhost:5000` erreichbar.
79-
80-
## ⚙️ Automatisierung (Hintergrund-Tasks)
81-
82-
Das Backend nutzt das `schedule` Modul in einem separaten Thread, um:
83-
* **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.
84-
* **Um Mitternacht:** Die Tagesstatistik (Tagesertrag, Max-Werte, Ersparnis) zu berechnen und in die Tabelle `daily_stats` zu aggregieren.
64+
```
65+
66+
### 3. Konfiguration (`.env`)
67+
Erstelle eine `.env` Datei im Hauptverzeichnis:
68+
```env
69+
ADMIN_PASS=dein_passwort
70+
LATITUDE=49.xxxx
71+
LONGITUDE=8.xxxx
72+
MQTT_BROKER_URL=deine_ip
73+
MQTT_BROKER_PORT=1883
74+
MQTT_USERNAME=dein_user
75+
MQTT_PASSWORD=dein_pw
76+
```
77+
## ⚙️ Deployment (Systemd)
78+
79+
Um das System mit Live- und Staging-Umgebung dauerhaft zu betreiben, werden zwei separate Instanzen und Services auf dem Ubuntu-Server eingerichtet.
80+
81+
### 1. Verzeichnisstruktur vorbereiten
82+
Klone das Projekt zweimal in unterschiedliche Ordner:
83+
```bash
84+
# Live-Instanz (Port 5000)
85+
git clone [https://github.com/jacquesbach/balkonkraftwerk.git](https://github.com/jacquesbach/balkonkraftwerk.git) /home/ubuntu/balkonkraftwerk
86+
87+
# Staging-Instanz (Port 5001)
88+
git clone -b dev [https://github.com/jacquesbach/balkonkraftwerk.git](https://github.com/jacquesbach/balkonkraftwerk.git) /home/ubuntu/balkonkraftwerk-staging
89+
```
90+
91+
### 2. Systemd Services anlegen
92+
Erstelle zwei Service-Dateien, um beide Instanzen unabhängig voneinander zu steuern.
93+
94+
**Live-Service:** `sudo nano /etc/systemd/system/balkonkraftwerk.service`
95+
```ini
96+
[Unit]
97+
Description=Balkonkraftwerk Analytics - Live (Port 5000)
98+
After=network.target
99+
100+
[Service]
101+
User=ubuntu
102+
WorkingDirectory=/home/ubuntu/balkonkraftwerk
103+
ExecStart=/home/ubuntu/balkonkraftwerk/venv/bin/python3 app.py
104+
Restart=always
105+
Environment="PORT=5000"
106+
107+
[Install]
108+
WantedBy=multi-user.target
109+
```
110+
111+
**Staging-Service:** `sudo nano /etc/systemd/system/balkonkraftwerk-staging.service`
112+
```ini
113+
[Unit]
114+
Description=Balkonkraftwerk Analytics - Staging (Port 5001)
115+
After=network.target
116+
117+
[Service]
118+
User=ubuntu
119+
WorkingDirectory=/home/ubuntu/balkonkraftwerk-staging
120+
ExecStart=/home/ubuntu/balkonkraftwerk-staging/venv/bin/python3 app.py
121+
Restart=always
122+
Environment="PORT=5001"
123+
124+
[Install]
125+
WantedBy=multi-user.target
126+
```
127+
128+
### 3. Dienste starten
129+
```bash
130+
sudo systemctl daemon-reload
131+
132+
# Live starten
133+
sudo systemctl enable --now balkonkraftwerk
134+
135+
# Staging starten
136+
sudo systemctl enable --now balkonkraftwerk-staging
137+
```
138+
139+
### ⚠️ Wichtig: GitHub Actions konfigurieren
140+
Damit das automatische Deployment funktioniert, müssen die Pfade in deinen `.github/workflows/*.yml` Dateien mit der Serverstruktur übereinstimmen:
141+
142+
* **deploy-staging.yml:** Muss auf das Verzeichnis `/home/ubuntu/balkonkraftwerk-staging` zeigen.
143+
* **deploy.yml:** Muss auf das Verzeichnis `/home/ubuntu/balkonkraftwerk` zeigen.
144+
145+
Stelle sicher, dass dein SSH-User Schreibrechte für beide Verzeichnisse besitzt.
146+
147+
## 🧪 Entwicklung & Staging
148+
Das Projekt nutzt einen automatisierten **Staging-Workflow** via GitHub Actions:
149+
* **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.
150+
* **Vorschau:** Änderungen sind sofort unter `http://deine-ip:5001` sichtbar.
151+
* **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.
152+
153+
**Staging-URL:** `http://deine-ip:5001`
154+
**Live-URL:** `http://deine-ip:5000`
155+
156+
## 📈 Machine Learning Info
157+
Die App verwendet einen `RandomForestRegressor` für den Erwartungswert und zwei `GradientBoostingRegressor`, um ein Konfidenzintervall (Quantile Regression) zu berechnen.
158+
* **Input-Features:** Sonnenstand, Tag des Jahres (Sin/Cos), Bewölkung, Temperatur, Rollierender Durchschnitt (7 Tage).
159+
* **Modell-Datei:** `pv_model.pkl` (wird nach jedem Tagesabschluss automatisch neu trainiert).
85160

86161
## 🤝 Mitwirken (Contributing)
87162

@@ -92,7 +167,3 @@ Pull Requests sind herzlich willkommen. Für größere Änderungen öffne bitte
92167
3. Commit deine Änderungen (`git commit -m 'Add some AmazingFeature'`)
93168
4. Push auf den Branch (`git push origin feature/AmazingFeature`)
94169
5. Öffne einen Pull Request
95-
96-
## 📄 Lizenz
97-
98-
Dieses Projekt ist unter der MIT-Lizenz lizenziert. Weitere Details findest du in der Datei `LICENSE`.

0 commit comments

Comments
 (0)