Feature: ShineDiag — portabler Vor-Ort-Diagnose-Gateway (Pi 3B)

Flask-App + mobile Web UI für Diagnose vor Ort ohne HAOS/MQTT. Pi 3B: eth0 → ShineLAN-X (DHCP), wlan0 → Hotspot "ShineDiag". Browser auf http://10.0.1.1: Modell wählen, alle Sensoren auslesen, Rohdaten-Register-Dump, Export als JSON. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-27 11:50:53 +02:00
parent a3e87da943
commit 391e615893
7 changed files with 529 additions and 1 deletions
@@ -9,11 +9,30 @@
 ## Phase 2 (ShineBridge Add-on)

 - [ ] Flash-Wizard — NuttX-Firmware via USB DFU direkt aus dem HA Web UI flashen (kein ST-Link)
- [ ] Persistente History — Sensorwerte über Add-on-Neustart hinaus speichern
+- [x] Persistente History — SQLite in /data/history.db, 7 Tage Retention (v1.3.0)
 - [ ] Weitere Growatt-Modelle — MOD 10000, SPH 10000 etc.

 ---

+## ShineDiag — Portabler Vor-Ort-Diagnose-Gateway (Pi 3B)
+
+Hardware: Raspberry Pi 3B (eth0 → ShineLAN-X, wlan0 → WiFi-Hotspot „ShineDiag")
+
+### Pi-Netzwerk-Setup
+- [ ] eth0: statische IP 10.0.0.1/24, dnsmasq DHCP → ShineLAN-X bekommt 10.0.0.100
+- [ ] wlan0: hostapd Hotspot „ShineDiag", WPA2
+- [ ] Autostart ShineDiag beim Boot (systemd)
+
+### ShineDiag Web App (`tools/shinediag/`)
+- [ ] Flask-App: verbindet sich mit ShineLAN-X, liest alle Register
+- [ ] Mobile-freundliche UI: Modell wählen, alle Sensorwerte anzeigen
+- [ ] Rohdaten-Ansicht: Register-Adresse, Hex, Dezimal
+- [ ] Fault-Codes decodiert (Growatt Status-Register)
+- [ ] Export als JSON für Kundendokumentation
+- [ ] Pi-Setup-Script (install.sh)
+
+---
+
 ## Phase 3 — Multi-Brand / Multi-Hardware

 ### Goodwe WiFi Stick (ESP32 + LAN)
@@ -32,6 +51,23 @@

 ---

+## Phase 4 — Messkonzept
+
+Ziel: korrekte, widerspruchsfreie Energiebilanz im HA Energie-Dashboard.
+
+### Messkonzept definieren
+- [ ] Messstellenplan: welcher Sensor misst was (SDM-630 = Netz, SPH = Batterie+AC, MIC = PV)
+- [ ] Hausverbrauch berechnen: `Hausverbrauch = PV_gesamt + Netzbezug - Einspeisung - Bat_Ladung + Bat_Entladung`
+- [ ] Vorzeichen-Konvention einheitlich festlegen (SDM-630 negativ = Einspeisung ✓)
+- [ ] Sensorüberschneidungen klären: SPH meldet AC-Leistung UND Netzleistung — was ist was?
+
+### HA Energie-Dashboard
+- [ ] Alle Dashboard-Slots mit den richtigen Aggregat-Sensoren belegen
+- [ ] Virtuelle Sensoren für berechnete Größen (Hausverbrauch) als MQTT-Sensor anlegen
+- [ ] Prüfen ob `total_increasing` auf allen Energie-Sensoren korrekt gesetzt ist
+
+---
+
 ## Erledigt

 - [x] v1.0.0 — Grundfunktion: ShineLAN-X + Growatt MIC via Modbus TCP + MQTT
@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""ShineDiag — Vor-Ort-Diagnose für Growatt-Wechselrichter via ShineLAN-X."""
+
+import json
+import logging
+import os
+import struct
+import sys
+
+from flask import Flask, jsonify, request, send_from_directory
+
+# Shared code aus dem Add-on
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "../../haos-addon/src"))
+from inverters import INVERTERS
+from modbus_client import ModbusReader
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s: %(message)s")
+log = logging.getLogger(__name__)
+
+WEB_DIR = os.path.join(os.path.dirname(__file__), "web")
+SHINELANX_IP = os.environ.get("SHINELANX_IP", "10.0.0.100")
+
+app = Flask(__name__, static_folder=WEB_DIR)
+
+
+@app.get("/")
+def index():
+    return send_from_directory(WEB_DIR, "index.html")
+
+
+@app.get("/api/models")
+def api_models():
+    return jsonify({
+        k: {"id": v.id, "name": v.name, "manufacturer": v.manufacturer,
+            "sensor_count": len(v.sensors)}
+        for k, v in INVERTERS.items()
+    })
+
+
+@app.post("/api/scan")
+def api_scan():
+    """Liest alle definierten Sensoren eines Geräts aus."""
+    body = request.get_json(force=True) or {}
+    model_id = body.get("model", "MIC_1500_TL_X")
+    ip = body.get("ip", SHINELANX_IP)
+    port = int(body.get("port", 502))
+    slave = int(body.get("slave", 1))
+
+    inverter = INVERTERS.get(model_id)
+    if not inverter:
+        return jsonify({"error": f"Unbekanntes Modell: {model_id}"}), 400
+
+    reader = ModbusReader(host=ip, port=port, slave=slave, timeout=5.0)
+    values = reader.read(inverter)
+    reader.close()
+
+    if values is None:
+        return jsonify({"ok": False, "error": "Keine Verbindung zum ShineLAN-X"}), 502
+
+    sensors_out = []
+    for s in inverter.sensors:
+        sensors_out.append({
+            "id": s.id,
+            "name": s.name,
+            "value": values.get(s.id),
+            "unit": s.unit,
+            "device_class": s.device_class,
+            "icon": s.icon,
+        })
+
+    return jsonify({"ok": True, "model": inverter.name,
+                    "manufacturer": inverter.manufacturer, "sensors": sensors_out})
+
+
+@app.post("/api/raw")
+def api_raw():
+    """Liest einen rohen Register-Bereich aus — für Diagnose unbekannter Werte."""
+    body = request.get_json(force=True) or {}
+    ip = body.get("ip", SHINELANX_IP)
+    port = int(body.get("port", 502))
+    slave = int(body.get("slave", 1))
+    start = max(0, int(body.get("start", 0)))
+    count = min(125, max(1, int(body.get("count", 100))))
+
+    from pymodbus.client import ModbusTcpClient
+    client = ModbusTcpClient(ip, port=port, timeout=5.0)
+    if not client.connect():
+        return jsonify({"ok": False, "error": "Verbindung fehlgeschlagen"}), 502
+
+    try:
+        result = client.read_input_registers(start, count, slave=slave)
+        if result.isError():
+            return jsonify({"ok": False, "error": str(result)}), 502
+        regs = []
+        for i, val in enumerate(result.registers):
+            regs.append({
+                "addr": start + i,
+                "hex": f"0x{val:04X}",
+                "dec": val,
+                "signed": val if val < 0x8000 else val - 0x10000,
+            })
+        return jsonify({"ok": True, "registers": regs})
+    finally:
+        client.close()
+
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", "80"))
+    log.info("ShineDiag startet auf Port %d — ShineLAN-X: %s", port, SHINELANX_IP)
+    app.run(host="0.0.0.0", port=port, threaded=True)
@@ -0,0 +1,8 @@
+# /etc/dhcpcd.conf — eth0 feste IP für ShineDiag
+# Diese Datei ans Ende von /etc/dhcpcd.conf anhängen
+
+interface eth0
+static ip_address=10.0.0.1/24
+static routers=
+static domain_name_servers=
+noipv6
@@ -0,0 +1,9 @@
+# /etc/dnsmasq.conf — DHCP für ShineLAN-X auf eth0
+
+interface=eth0
+dhcp-range=10.0.0.100,10.0.0.200,12h
+
+# ShineLAN-X bekommt immer 10.0.0.100 (MAC anpassen!)
+# dhcp-host=AA:BB:CC:DD:EE:FF,shinelanx,10.0.0.100
+
+bind-interfaces
@@ -0,0 +1,16 @@
+# /etc/hostapd/hostapd.conf — WiFi-Hotspot "ShineDiag"
+
+interface=wlan0
+driver=nl80211
+ssid=ShineDiag
+hw_mode=g
+channel=6
+ieee80211n=1
+wmm_enabled=1
+
+auth_algs=1
+wpa=2
+wpa_passphrase=shinelanx
+wpa_key_mgmt=WPA-PSK
+wpa_pairwise=CCMP
+rsn_pairwise=CCMP
@@ -0,0 +1,69 @@
+#!/bin/bash
+# ShineDiag Pi 3B Setup — einmalig als root ausführen
+set -e
+
+echo "=== ShineDiag Installation ==="
+
+# Pakete
+apt-get update -q
+apt-get install -y python3-pip hostapd dnsmasq
+
+# Python-Abhängigkeiten
+pip3 install flask pymodbus --break-system-packages
+
+# Netzwerk: eth0 statische IP
+cat setup/dhcpcd.conf >> /etc/dhcpcd.conf
+
+# DHCP-Server für eth0
+cp setup/dnsmasq.conf /etc/dnsmasq.conf
+systemctl enable dnsmasq
+
+# WiFi-Hotspot
+cp setup/hostapd.conf /etc/hostapd/hostapd.conf
+echo 'DAEMON_CONF="/etc/hostapd/hostapd.conf"' >> /etc/default/hostapd
+systemctl unmask hostapd
+systemctl enable hostapd
+
+# Wlan0 IP
+cat >> /etc/dhcpcd.conf << 'EOF'
+
+interface wlan0
+static ip_address=10.0.1.1/24
+nohook wpa_supplicant
+EOF
+
+# DHCP auch für wlan0 (MacBook-Verbindung)
+cat >> /etc/dnsmasq.conf << 'EOF'
+
+interface=wlan0
+dhcp-range=10.0.1.100,10.0.1.200,1h
+EOF
+
+# systemd-Service für ShineDiag
+INSTALL_DIR="$(pwd)"
+cat > /etc/systemd/system/shinediag.service << EOF
+[Unit]
+Description=ShineDiag Diagnose-Tool
+After=network.target
+
+[Service]
+ExecStart=/usr/bin/python3 ${INSTALL_DIR}/diagnose.py
+WorkingDirectory=${INSTALL_DIR}
+Environment=PORT=80
+Environment=SHINELANX_IP=10.0.0.100
+Restart=always
+User=root
+
+[Install]
+WantedBy=multi-user.target
+EOF
+
+systemctl daemon-reload
+systemctl enable shinediag
+
+echo ""
+echo "=== Fertig! Bitte neu starten: sudo reboot ==="
+echo ""
+echo "Nach dem Neustart:"
+echo "  WiFi: 'ShineDiag' | Passwort: shinelanx"
+echo "  Browser: http://10.0.1.1"
@@ -0,0 +1,280 @@
+<!DOCTYPE html>
+<html lang="de">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
+<title>ShineDiag</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body { font-family: system-ui, sans-serif; background: #0f172a; color: #e2e8f0; min-height: 100vh; }
+
+  header { background: #1e293b; padding: 16px 20px; border-bottom: 1px solid #334155;
+           display: flex; align-items: center; gap: 12px; }
+  header svg { flex-shrink: 0; }
+  header h1 { font-size: 1.2rem; font-weight: 700; color: #f8fafc; }
+  header p  { font-size: .75rem; color: #94a3b8; }
+
+  main { padding: 16px; max-width: 640px; margin: 0 auto; }
+
+  .card { background: #1e293b; border: 1px solid #334155; border-radius: 12px;
+          padding: 16px; margin-bottom: 16px; }
+  .card h2 { font-size: .85rem; font-weight: 600; color: #94a3b8;
+             text-transform: uppercase; letter-spacing: .05em; margin-bottom: 12px; }
+
+  label  { display: block; font-size: .8rem; color: #94a3b8; margin-bottom: 4px; margin-top: 10px; }
+  input, select {
+    width: 100%; padding: 10px 12px; border-radius: 8px;
+    border: 1px solid #334155; background: #0f172a; color: #f1f5f9;
+    font-size: .9rem;
+  }
+  input:focus, select:focus { outline: 2px solid #3b82f6; border-color: transparent; }
+
+  .row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+
+  button { width: 100%; padding: 12px; border-radius: 8px; border: none; cursor: pointer;
+           font-size: .95rem; font-weight: 600; margin-top: 14px; transition: opacity .15s; }
+  button:disabled { opacity: .4; cursor: not-allowed; }
+  .btn-primary { background: #3b82f6; color: #fff; }
+  .btn-primary:hover:not(:disabled) { background: #2563eb; }
+  .btn-raw { background: #475569; color: #e2e8f0; }
+  .btn-raw:hover:not(:disabled) { background: #334155; }
+  .btn-export { background: #059669; color: #fff; }
+  .btn-export:hover:not(:disabled) { background: #047857; }
+
+  .status { display: flex; align-items: center; gap: 8px; padding: 10px 12px;
+            border-radius: 8px; font-size: .85rem; margin-top: 12px; }
+  .status.ok    { background: #052e16; color: #4ade80; border: 1px solid #166534; }
+  .status.error { background: #1c0a09; color: #f87171; border: 1px solid #7f1d1d; }
+  .status.info  { background: #0c1a2e; color: #60a5fa; border: 1px solid #1e3a5f; }
+
+  .sensor-table { width: 100%; border-collapse: collapse; margin-top: 4px; }
+  .sensor-table th { text-align: left; font-size: .75rem; color: #64748b;
+                     padding: 6px 8px; border-bottom: 1px solid #334155; }
+  .sensor-table td { padding: 8px; font-size: .85rem; border-bottom: 1px solid #1e293b; }
+  .sensor-table tr:last-child td { border-bottom: none; }
+  .sensor-table .val { font-weight: 600; color: #f1f5f9; text-align: right; }
+  .sensor-table .unit { color: #64748b; font-size: .75rem; text-align: right; }
+  .sensor-name { color: #cbd5e1; }
+
+  .tabs { display: flex; gap: 4px; margin-bottom: 12px; }
+  .tab { flex: 1; padding: 8px; border-radius: 6px; border: 1px solid #334155;
+         background: transparent; color: #94a3b8; font-size: .8rem; cursor: pointer; }
+  .tab.active { background: #3b82f6; color: #fff; border-color: #3b82f6; }
+
+  .raw-table { width: 100%; border-collapse: collapse; font-family: monospace; font-size: .8rem; }
+  .raw-table th { text-align: left; color: #64748b; padding: 4px 8px;
+                  border-bottom: 1px solid #334155; }
+  .raw-table td { padding: 5px 8px; border-bottom: 1px solid #1e293b; color: #cbd5e1; }
+  .raw-table td:first-child { color: #60a5fa; }
+
+  #results { display: none; }
+  .spinner { display: inline-block; width: 16px; height: 16px; border: 2px solid #ffffff44;
+             border-top-color: #fff; border-radius: 50%; animation: spin .7s linear infinite; }
+  @keyframes spin { to { transform: rotate(360deg); } }
+</style>
+</head>
+<body>
+
+<header>
+  <svg width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="#f59e0b" stroke-width="2">
+    <circle cx="12" cy="12" r="5"/><line x1="12" y1="1" x2="12" y2="3"/>
+    <line x1="12" y1="21" x2="12" y2="23"/><line x1="4.22" y1="4.22" x2="5.64" y2="5.64"/>
+    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"/>
+    <line x1="1" y1="12" x2="3" y2="12"/><line x1="21" y1="12" x2="23" y2="12"/>
+    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"/>
+    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"/>
+  </svg>
+  <div>
+    <h1>ShineDiag</h1>
+    <p>Vor-Ort Diagnose via ShineLAN-X</p>
+  </div>
+</header>
+
+<main>
+  <div class="card">
+    <h2>Verbindung</h2>
+
+    <label>ShineLAN-X IP</label>
+    <input id="ip" type="text" value="10.0.0.100" placeholder="10.0.0.100">
+
+    <div class="row">
+      <div>
+        <label>Port</label>
+        <input id="port" type="number" value="502">
+      </div>
+      <div>
+        <label>Modbus-Adresse</label>
+        <input id="slave" type="number" value="1" min="1" max="247">
+      </div>
+    </div>
+
+    <label>Wechselrichter-Modell</label>
+    <select id="model"></select>
+
+    <button class="btn-primary" id="btnScan" onclick="scan()">
+      Auslesen
+    </button>
+  </div>
+
+  <div class="card" id="results">
+    <div class="tabs">
+      <button class="tab active" onclick="showTab('sensors')">Sensoren</button>
+      <button class="tab" onclick="showTab('raw')">Rohdaten</button>
+    </div>
+
+    <div id="statusMsg"></div>
+
+    <div id="tabSensors">
+      <table class="sensor-table">
+        <thead><tr><th>Sensor</th><th style="text-align:right">Wert</th><th style="text-align:right">Einheit</th></tr></thead>
+        <tbody id="sensorBody"></tbody>
+      </table>
+      <button class="btn-export" id="btnExport" onclick="exportJson()" style="margin-top:12px">
+        Export JSON
+      </button>
+    </div>
+
+    <div id="tabRaw" style="display:none">
+      <div class="row" style="margin-bottom:10px">
+        <div>
+          <label>Start-Register</label>
+          <input id="rawStart" type="number" value="0" min="0">
+        </div>
+        <div>
+          <label>Anzahl</label>
+          <input id="rawCount" type="number" value="100" min="1" max="125">
+        </div>
+      </div>
+      <button class="btn-raw" onclick="rawScan()">Register lesen</button>
+      <div style="overflow-x:auto; margin-top:12px">
+        <table class="raw-table">
+          <thead><tr><th>Addr</th><th>Hex</th><th>Dez</th><th>Signed</th></tr></thead>
+          <tbody id="rawBody"></tbody>
+        </table>
+      </div>
+    </div>
+  </div>
+</main>
+
+<script>
+let lastScan = null;
+
+async function loadModels() {
+  const res = await fetch('/api/models');
+  const data = await res.json();
+  const sel = document.getElementById('model');
+  sel.innerHTML = '';
+  for (const [id, m] of Object.entries(data)) {
+    const opt = document.createElement('option');
+    opt.value = id;
+    opt.textContent = `${m.name} (${m.sensor_count} Sensoren)`;
+    sel.appendChild(opt);
+  }
+}
+
+function showTab(tab) {
+  document.getElementById('tabSensors').style.display = tab === 'sensors' ? '' : 'none';
+  document.getElementById('tabRaw').style.display    = tab === 'raw'     ? '' : 'none';
+  document.querySelectorAll('.tab').forEach((t, i) =>
+    t.classList.toggle('active', (i === 0) === (tab === 'sensors')));
+}
+
+function setStatus(msg, type) {
+  const el = document.getElementById('statusMsg');
+  el.innerHTML = `<div class="status ${type}">${msg}</div>`;
+}
+
+async function scan() {
+  const btn = document.getElementById('btnScan');
+  btn.disabled = true;
+  btn.innerHTML = '<span class="spinner"></span> Verbinde…';
+  document.getElementById('results').style.display = 'block';
+  setStatus('Verbinde mit ShineLAN-X…', 'info');
+
+  try {
+    const res = await fetch('/api/scan', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        ip:    document.getElementById('ip').value,
+        port:  parseInt(document.getElementById('port').value),
+        slave: parseInt(document.getElementById('slave').value),
+        model: document.getElementById('model').value,
+      })
+    });
+    const data = await res.json();
+
+    if (!data.ok) {
+      setStatus('&#x26A0; ' + (data.error || 'Fehler'), 'error');
+      return;
+    }
+
+    lastScan = data;
+    setStatus(`&#x2713; ${data.manufacturer} ${data.model} — ${data.sensors.length} Sensoren gelesen`, 'ok');
+
+    const tbody = document.getElementById('sensorBody');
+    tbody.innerHTML = '';
+    for (const s of data.sensors) {
+      const val = s.value !== null ? s.value : '—';
+      const tr = document.createElement('tr');
+      tr.innerHTML = `
+        <td class="sensor-name">${esc(s.name)}</td>
+        <td class="val">${val}</td>
+        <td class="unit">${esc(s.unit || '')}</td>`;
+      tbody.appendChild(tr);
+    }
+  } catch (e) {
+    setStatus('&#x26A0; Netzwerkfehler: ' + e.message, 'error');
+  } finally {
+    btn.disabled = false;
+    btn.textContent = 'Auslesen';
+  }
+}
+
+async function rawScan() {
+  setStatus('Lese Register…', 'info');
+  try {
+    const res = await fetch('/api/raw', {
+      method: 'POST',
+      headers: {'Content-Type': 'application/json'},
+      body: JSON.stringify({
+        ip:    document.getElementById('ip').value,
+        port:  parseInt(document.getElementById('port').value),
+        slave: parseInt(document.getElementById('slave').value),
+        start: parseInt(document.getElementById('rawStart').value),
+        count: parseInt(document.getElementById('rawCount').value),
+      })
+    });
+    const data = await res.json();
+    if (!data.ok) { setStatus('&#x26A0; ' + data.error, 'error'); return; }
+
+    const tbody = document.getElementById('rawBody');
+    tbody.innerHTML = '';
+    for (const r of data.registers) {
+      const tr = document.createElement('tr');
+      tr.innerHTML = `<td>${r.addr}</td><td>${r.hex}</td><td>${r.dec}</td><td>${r.signed}</td>`;
+      tbody.appendChild(tr);
+    }
+    setStatus(`&#x2713; ${data.registers.length} Register gelesen`, 'ok');
+  } catch (e) {
+    setStatus('&#x26A0; ' + e.message, 'error');
+  }
+}
+
+function exportJson() {
+  if (!lastScan) return;
+  const blob = new Blob([JSON.stringify(lastScan, null, 2)], {type: 'application/json'});
+  const a = document.createElement('a');
+  a.href = URL.createObjectURL(blob);
+  a.download = `shinediag_${new Date().toISOString().slice(0,19).replace(/:/g,'-')}.json`;
+  a.click();
+}
+
+function esc(s) {
+  return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+}
+
+loadModels();
+</script>
+</body>
+</html>