Skip to content

Commit 2818b9a

Browse files
jacquesbachjacquesbach
authored
Merge pull request #1 from jacquesbach/dev
Update Readme
2 parents 413ca17 + 4c84d69 commit 2818b9a

1 file changed

Lines changed: 147 additions & 64 deletions

File tree

‎README.md‎

Lines changed: 147 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,24 @@
1-
# ☀️ Balkonkraftwerk Analytics
1+
# Balkonkraftwerk Analytics Dashboard
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+
## 🚀 Features
7+
8+
* **Echtzeit-Monitoring:** Empfängt sekündliche Live-Werte (Leistung/Watt, Strom/Ampere, Spannung/Volt, Temperatur) des Wechselrichters via MQTT (OpenDTU/AhoyDTU).
9+
* **Energie-Statistiken & Live-Metriken:** Präzise Errechnung der produzierten kWh mittels Trapez-Regel sowie automatische Berechnung der Ersparnis (EUR) und Spitzenwerte.
10+
* **ML-gestützter Forecast:** Vorhersage des Ertrags (Best/Worst/Expected Case) basierend auf Bewölkung und Temperatur.
11+
* **Quantil-Regression:** Nutzt GradientBoosting zur Berechnung eines 80%-Konfidenzintervalls für die erwartete Tagesproduktion.
912
* **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):**
13+
* **Interaktive Visualisierungen (Chart.js):**
1114
* **Dynamisches Donut-Chart:** Zeigt die DC-Leistung pro Panel. Durch Antippen/Hovern ändert sich die zentrale Anzeige.
1215
* **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.
16+
* **Automatische Wetterdaten:** Integriert die kostenlose Open-Meteo API für aktuelle Bewölkung und stündliche Prognosen.
17+
* **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.
18+
* **Staging-System:** Vollautomatisches Deployment via GitHub Actions auf eine Live- (Port 5000) und Test-Umgebung (Port 5001).
19+
1620

17-
## 🛠 Tech Stack
21+
## 🏗️ Tech Stack
1822

1923
* **Backend:** Python 3.11, Flask, Flask-MQTT
2024
* **Machine Learning:** Scikit-Learn (RandomForest, GradientBoosting), SHAP, Pandas, Numpy
@@ -23,65 +27,148 @@ Ein intelligentes, lokal gehostetes Dashboard zur Überwachung, Analyse und Vorh
2327
* **Datenbank:** SQLite3
2428

2529
## 📂 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
30+
```text
31+
.
32+
├── .github/workflows/
33+
│ ├── deploy.yml # Live-Deployment (Main Branch)
34+
│ └── deploy-staging.yml # Staging-Deployment (Dev Branch)
3635
├── static/
3736
│ ├── css/
38-
│ │ └── style.css # Dashboard Styling
37+
│ │ └── styles.css
3938
│ └── js/
40-
│ └── script.js # Frontend Logik (API-Calls, Chart.js)
41-
└── templates/
42-
└── index.html # Dashboard HTML-Template
43-
\`\`\`
39+
│ └── script.js
40+
├── templates/
41+
│ └── index.html
42+
├── app.py
43+
├── requirements.txt
44+
├── .env
45+
├── .gitignore
46+
└── README.md
47+
```
4448

45-
## 🚀 Installation & Setup
49+
50+
## 🛠 Installation & Setup
4651

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

5358
### 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
59+
```bash
60+
python3 -m venv venv
61+
source venv/bin/activate
5862
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.
63+
```
64+
65+
### 3. Konfiguration (`.env`)
66+
Erstelle eine `.env` Datei im Hauptverzeichnis:
67+
```env
68+
ADMIN_PASS=dein_passwort
69+
LATITUDE=49.xxxx
70+
LONGITUDE=8.xxxx
71+
MQTT_BROKER_URL=deine_ip
72+
MQTT_BROKER_PORT=1883
73+
MQTT_USERNAME=dein_user
74+
MQTT_PASSWORD=dein_pw
75+
```
76+
## ⚙️ Deployment (Systemd)
77+
78+
Um das System mit Live- und Staging-Umgebung dauerhaft zu betreiben, werden zwei separate Instanzen und Services auf dem Ubuntu-Server eingerichtet.
79+
80+
### 1. Verzeichnisstruktur vorbereiten
81+
Klone das Projekt zweimal in unterschiedliche Ordner:
82+
```bash
83+
# Live-Instanz (Port 5000)
84+
git clone [https://github.com/jacquesbach/balkonkraftwerk.git](https://github.com/jacquesbach/balkonkraftwerk.git) /home/ubuntu/balkonkraftwerk
85+
86+
# Staging-Instanz (Port 5001)
87+
git clone -b dev [https://github.com/jacquesbach/balkonkraftwerk.git](https://github.com/jacquesbach/balkonkraftwerk.git) /home/ubuntu/balkonkraftwerk-staging
88+
```
89+
90+
### 2. Systemd Services anlegen
91+
Erstelle zwei Service-Dateien, um beide Instanzen unabhängig voneinander zu steuern.
92+
93+
**Live-Service:** `sudo nano /etc/systemd/system/balkonkraftwerk.service`
94+
```ini
95+
[Unit]
96+
Description=Balkonkraftwerk Analytics - Live (Port 5000)
97+
After=network.target
98+
99+
[Service]
100+
User=ubuntu
101+
WorkingDirectory=/home/ubuntu/balkonkraftwerk
102+
ExecStart=/home/ubuntu/balkonkraftwerk/venv/bin/python3 app.py
103+
Restart=always
104+
Environment="PORT=5000"
105+
106+
[Install]
107+
WantedBy=multi-user.target
108+
```
109+
110+
**Staging-Service:** `sudo nano /etc/systemd/system/balkonkraftwerk-staging.service`
111+
```ini
112+
[Unit]
113+
Description=Balkonkraftwerk Analytics - Staging (Port 5001)
114+
After=network.target
115+
116+
[Service]
117+
User=ubuntu
118+
WorkingDirectory=/home/ubuntu/balkonkraftwerk-staging
119+
ExecStart=/home/ubuntu/balkonkraftwerk-staging/venv/bin/python3 app.py
120+
Restart=always
121+
Environment="PORT=5001"
122+
123+
[Install]
124+
WantedBy=multi-user.target
125+
```
126+
127+
### 3. Dienste starten
128+
```bash
129+
sudo systemctl daemon-reload
130+
131+
# Live starten
132+
sudo systemctl enable --now balkonkraftwerk
133+
134+
# Staging starten
135+
sudo systemctl enable --now balkonkraftwerk-staging
136+
```
137+
138+
### ⚠️ Wichtig: GitHub Actions & CI/CD Setup
139+
140+
Damit das automatische Deployment funktioniert, müssen zwei Dinge konfiguriert sein:
141+
142+
#### 1. Pfade in den Workflows
143+
Stelle sicher, dass die Zielverzeichnisse in deinen `.github/workflows/*.yml` Dateien exakt mit der Serverstruktur übereinstimmen:
144+
* **deploy-staging.yml:** Zielpfad `/home/ubuntu/balkonkraftwerk-staging`
145+
* **deploy.yml:** Zielpfad `/home/ubuntu/balkonkraftwerk`
146+
147+
#### 2. GitHub Secrets
148+
Hinterlege in deinem GitHub-Repository unter `Settings > Secrets and variables > Actions` folgende Secrets, damit die Action auf deinen Server zugreifen kann:
149+
150+
| Secret Name | Beschreibung |
151+
| :--- | :--- |
152+
| `SERVER_IP` | Die IP-Adresse deines Ubuntu-Servers |
153+
| `SERVER_USER` | Dein Benutzername (z. B. `ubuntu`) |
154+
| `SSH_PRIVATE_KEY` | Dein privater SSH-Schlüssel (für den passwortlosen Login) |
155+
156+
---
157+
158+
## 🧪 Entwicklung & Staging
159+
Das Projekt nutzt einen automatisierten **Staging-Workflow** via GitHub Actions:
160+
161+
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.
162+
2. **Vorschau:** Änderungen sind sofort unter `http://deine-ip:5001` sichtbar.
163+
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.
164+
165+
**Staging-URL:** `http://deine-ip:5001`
166+
**Live-URL:** `http://deine-ip:5000`
167+
168+
## 📈 Machine Learning Info
169+
Die App verwendet einen `RandomForestRegressor` für den Erwartungswert und zwei `GradientBoostingRegressor`, um ein Konfidenzintervall (Quantile Regression) zu berechnen.
170+
* **Input-Features:** Sonnenstand, Tag des Jahres (Sin/Cos), Bewölkung, Temperatur, Rollierender Durchschnitt (7 Tage).
171+
* **Modell-Datei:** `pv_model.pkl` (wird nach jedem Tagesabschluss automatisch neu trainiert).
85172

86173
## 🤝 Mitwirken (Contributing)
87174

@@ -92,7 +179,3 @@ Pull Requests sind herzlich willkommen. Für größere Änderungen öffne bitte
92179
3. Commit deine Änderungen (`git commit -m 'Add some AmazingFeature'`)
93180
4. Push auf den Branch (`git push origin feature/AmazingFeature`)
94181
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)