Initial commit

Author: jacquesbach

.dockerignore

@@ -0,0 +1,34 @@
+# --- Python & App ---
+__pycache__/
+*.py[cod]
+venv/
+.env
+.cache/
+.local/
+
+# --- Datenbank & Modelle ---
+# Wir ignorieren die Datenbank und das ML-Modell
+*.db
+*.sqlite3
+*.pkl
+
+# --- Logs & Temporäres ---
+*.log
+.sudo_as_admin_successful
+
+# --- Systemdateien (Bash & SSH) ---
+# Diese Dateien gehören zu deinem Server-User, nicht zum Projekt!
+.bash_history
+.bash_logout
+.bashrc
+.profile
+.ssh/
+.git
+.github
+.gitignore
+.dockerignore
+.gitconfig
+
+# --- OS spezifisch ---
+.DS_Store
+Thumbs.db

.env.example

@@ -0,0 +1,8 @@
+# Beispiel-Konfiguration
+ADMIN_PASS=dein_passwort
+LATITUDE=52.5200
+LONGITUDE=13.4050
+MQTT_BROKER_URL=192.168.178.xxx
+MQTT_BROKER_PORT=1883
+MQTT_USERNAME=dein_mqtt_user
+MQTT_PASSWORD=dein_mqtt_passwort

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: Balkonkraftwerk CI
+
+# Wann soll die Action laufen? Bei jedem Push auf den main-Branch
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  test-code:
+    runs-on: ubuntu-latest
+
+    steps:
+      # 1. Holt deinen Code von GitHub in den Test-Server
+      - name: Code auschecken
+        uses: actions/checkout@v4
+
+      # 2. Installiert Python 3.11
+      - name: Python einrichten
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip' # Macht zukünftige Durchläufe viel schneller!
+
+      # 3. Installiert deine requirements.txt
+      - name: Abhängigkeiten installieren
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      # 4. Ein einfacher Syntax-Check (kompiliert die app.py testweise)
+      - name: Python Syntax Check
+        run: |
+          python -m py_compile app.py

.gitignore

@@ -0,0 +1,32 @@
+# --- Python & App ---
+__pycache__/
+*.py[cod]
+venv/
+.env
+.cache/
+.local/
+
+# --- Datenbank & Modelle ---
+# Wir ignorieren die Datenbank und das ML-Modell
+*.db
+*.sqlite3
+*.pkl
+
+# --- Logs & Temporäres ---
+*.log
+.sudo_as_admin_successful
+
+# --- Systemdateien (Bash & SSH) ---
+# Diese Dateien gehören zu deinem Server-User, nicht zum Projekt!
+.bash_history
+.bash_logout
+.bashrc
+.profile
+.ssh/
+
+# --- Git spezifisch ---
+.gitconfig
+
+# --- OS spezifisch ---
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,24 @@
+# 1. Basis-Image (Python 3.11 schlank)
+FROM python:3.11-slim
+
+# 2. Arbeitsverzeichnis im Container
+WORKDIR /app
+
+# 3. System-Abhängigkeiten (für ML-Pakete oft nötig)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# 4. Abhängigkeiten kopieren und installieren
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 5. Den Rest der App kopieren
+# Dank .dockerignore landen DB und .env nicht hier drin
+COPY . .
+
+# 6. Port freigeben (Flask Standard)
+EXPOSE 5000
+
+# 7. Startbefehl
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,98 @@
+# ☀️ 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.
+
+## ✨ 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.
+  * **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):**
+  * **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.
+
+## 🛠 Tech Stack
+
+* **Backend:** Python 3.11, Flask, Flask-MQTT
+* **Machine Learning:** Scikit-Learn (RandomForest, GradientBoosting), SHAP, Pandas, Numpy
+* **Frontend:** HTML5, CSS3 (CSS Variables für konsistentes Theming), Vanilla JavaScript (ES6)
+* **Charts & Icons:** Chart.js (inkl. datalabels-Plugin), Phosphor Icons
+* **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
+├── static/
+│   ├── css/
+│   │   └── style.css      # Dashboard Styling
+│   └── js/
+│       └── script.js      # Frontend Logik (API-Calls, Chart.js)
+└── templates/
+    └── index.html         # Dashboard HTML-Template
+\`\`\`
+
+## 🚀 Installation & Setup
+
+### 1. Repository klonen
+\`\`\`bash
+git clone https://github.com/DEIN_USERNAME/DEIN_REPO.git
+cd DEIN_REPO
+\`\`\`
+
+### 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
+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.
+
+## 🤝 Mitwirken (Contributing)
+
+Pull Requests sind herzlich willkommen. Für größere Änderungen öffne bitte zuerst ein Issue, um zu diskutieren, was du ändern möchtest.
+
+1. Forke das Projekt
+2. Erstelle deinen Feature Branch (`git checkout -b feature/AmazingFeature`)
+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`.