ESP32 WebSerial Installation - Professionelle Vor-Ort-Lösung

Datum: 23. Oktober 2025
Methode: WebSerial API + USB-Kabel (Browser-basiert)
Zielgruppe: Servicetechniker bei Vor-Ort-Installation

---

🎯 Installationskonzept

Szenario: Professionelle Installation durch Servicetechniker

Servicetechniker bekommt Auftrag:
  └─> "PV-Anlage in Würzburg, neues Monitoring-Display installieren"

Vor Ort:
  ├─> Wechselrichter läuft bereits (SMA, Kostal, etc.)
  ├─> Techniker bringt mit:
  │   ├─> Laptop (Chrome/Edge Browser)
  │   ├─> ESP32 E-Paper Display (neu, ungeflasht)
  │   ├─> USB-Kabel (USB-C oder Micro-USB)
  │   └─> Netzteil für ESP32
  │
  └─> Installation dauert: 5-10 Minuten
      ├─> 2 Min: ESP32 anschließen & flashen
      ├─> 2 Min: Konfiguration eingeben
      ├─> 1 Min: Test & Verifizierung
      └─> 5 Min: Montage & Dokumentation

---

🔧 Technischer Workflow

Schritt 1: Portal öffnen

Techniker öffnet auf seinem Laptop:

https://solarlog.karma.organic/setup/install

Portal-Login mit Techniker-Account:

E-Mail: techniker@solarfirma.de
Passwort: ***********

Nach Login wird angezeigt:

┌─────────────────────────────────────────────────────┐
│  🔧 Neues Gerät installieren                       │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Auftrag auswählen (optional):                     │
│  ┌───────────────────────────────────────────────┐ │
│  │ ⦿ Neuer Kunde: Max Mustermann                │ │
│  │   Würzburg, Hauptstraße 42                    │ │
│  │   PV-Anlage: SMA Sunny Boy 5.0                │ │
│  │   Installation geplant: 23.10.2025 14:00      │ │
│  └───────────────────────────────────────────────┘ │
│  ⭘ Ohne Auftrag (Manuell)                          │
│                                                     │
│  [Weiter →]                                        │
└─────────────────────────────────────────────────────┘

Schritt 2: ESP32 vorbereiten

┌─────────────────────────────────────────────────────┐
│  📦 Gerät vorbereiten                              │
├─────────────────────────────────────────────────────┤
│                                                     │
│  1. ESP32 E-Paper Display auspacken                │
│                                                     │
│  2. USB-Kabel an ESP32 anschließen                 │
│     (Noch NICHT an Laptop!)                        │
│                                                     │
│  3. Display-Typ bestätigen:                        │
│     ⦿ LilyGO T5 4.7" (540×960)                     │
│     ⭘ Waveshare 2.9" (296×128)                     │
│     ⭘ Waveshare 4.2" (400×300)                     │
│     ⭘ Custom (Manuell)                             │
│                                                     │
│  4. ESP32 jetzt per USB mit Laptop verbinden       │
│                                                     │
│  [Gerät ist angeschlossen →]                       │
└─────────────────────────────────────────────────────┘

Techniker: - Klickt "Gerät ist angeschlossen" - Browser fragt: "solarlog.karma.organic möchte eine serielle Verbindung aufbauen" - Liste zeigt: "USB JTAG/serial debug unit (USB VID:PID 303A:1001)" - Techniker klickt "Verbinden"

Schritt 3: Firmware flashen

┌─────────────────────────────────────────────────────┐
│  ⚡ Firmware installieren                          │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Gerät erkannt:                                    │
│  • Chip: ESP32-S3                                  │
│  • MAC: A1:B2:C3:D4:E5:F6                         │
│  • Flash: 16 MB                                    │
│                                                     │
│  Firmware-Version:                                 │
│  ⦿ Latest Stable (v1.2.5) - Empfohlen             │
│  ⭘ Beta (v1.3.0-beta.2)                           │
│  ⭘ Custom Upload                                   │
│                                                     │
│  ┌─────────────────────────────────────────────┐  │
│  │  [████████████████████░░░░░░] 75%          │  │
│  │  Lösche Flash...                            │  │
│  │  Schreibe Bootloader... ✓                   │  │
│  │  Schreibe Partition Table... ✓              │  │
│  │  Schreibe Firmware... (1.2 MB / 1.6 MB)     │  │
│  └─────────────────────────────────────────────┘  │
│                                                     │
│  ⏱ Geschätzte Zeit: 45 Sekunden                   │
└─────────────────────────────────────────────────────┘

Was passiert im Hintergrund:

// Portal verwendet esptool.js
import { ESPLoader, Transport } from 'esptool-js';

const firmware = await fetch('/api/v1/firmware/latest/esp32s3');
const blob = await firmware.blob();

const loader = new ESPLoader(transport);
await loader.main('bootloader', 0x1000);      // Bootloader
await loader.main('partition',  0x8000);       // Partition Table
await loader.main('firmware',   0x10000);      // Main Firmware
await loader.main('spiffs',     0x290000);     // File System

// WICHTIG: Konfiguration wird NACH dem Flashen eingegeben!
// ESP32 bootet erstmal mit Default-Config

Nach erfolgreichem Flash:

┌─────────────────────────────────────────────────────┐
│  ✅ Firmware erfolgreich installiert!              │
├─────────────────────────────────────────────────────┤
│                                                     │
│  • Bootloader: ✓                                   │
│  • Partition Table: ✓                              │
│  • Firmware v1.2.5: ✓                              │
│  • File System: ✓                                  │
│                                                     │
│  Gerät wurde automatisch neu gestartet.            │
│                                                     │
│  [Weiter zur Konfiguration →]                      │
└─────────────────────────────────────────────────────┘

Schritt 4: WLAN-Konfiguration

┌─────────────────────────────────────────────────────┐
│  📡 WLAN-Verbindung                                │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Option 1: Automatisch von Laptop übernehmen       │
│  ┌───────────────────────────────────────────────┐ │
│  │ Laptop ist verbunden mit:                     │ │
│  │ SSID: "PV-Anlage-Fritz7590"                   │ │
│  │                                                │ │
│  │ [✓] Dieses WLAN verwenden                     │ │
│  │     Passwort: [********************]          │ │
│  │     [Passwort anzeigen]                       │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  Option 2: Manuell eingeben                        │
│  SSID:     [_____________________________]         │
│  Passwort: [_____________________________]         │
│            [Passwort anzeigen]                     │
│                                                     │
│  [Verbindung testen →]                             │
└─────────────────────────────────────────────────────┘

Test-Prozess:

// Portal sendet Config via USB Serial an ESP32
await serial.writeText(JSON.stringify({
  cmd: 'test_wifi',
  ssid: 'PV-Anlage-Fritz7590',
  password: '***************'
}));

// ESP32 versucht zu verbinden und antwortet:
const response = await serial.readLine();
// {"status": "ok", "ip": "192.168.178.42", "rssi": -52}

Ergebnis:

┌─────────────────────────────────────────────────────┐
│  ✅ WLAN-Verbindung erfolgreich!                   │
├─────────────────────────────────────────────────────┤
│                                                     │
│  • SSID: PV-Anlage-Fritz7590                       │
│  • IP-Adresse: 192.168.178.42                      │
│  • Signalstärke: -52 dBm (Ausgezeichnet)           │
│                                                     │
│  [Weiter zur Inverter-Suche →]                     │
└─────────────────────────────────────────────────────┘

Schritt 5: Inverter-Erkennung

┌─────────────────────────────────────────────────────┐
│  ⚡ Wechselrichter finden                          │
├─────────────────────────────────────────────────────┤
│                                                     │
│  [🔍 Automatisch suchen]                           │
│                                                     │
│  ⏳ Scanne lokales Netzwerk...                     │
│  • 192.168.178.1-254 (254 Hosts)                  │
│  • Modbus Port 502                                 │
│  • HTTP Ports 80, 8080, 8081                       │
│                                                     │
│  ━━━━━━━━━━━━━━━━━━━━━━━ 45% (115/254)           │
│                                                     │
│  Gefunden:                                         │
│  ┌───────────────────────────────────────────────┐ │
│  │ ✓ SMA Sunny Boy 5.0                           │ │
│  │   192.168.178.50                              │ │
│  │   Modbus Unit ID: 3                           │ │
│  │   Aktuell: 3.8 kW                             │ │
│  │   Seriennummer: 1234567890                    │ │
│  │   [Auswählen]                                 │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  Oder manuell eingeben:                            │
│  Hersteller: [SMA          ▼]                      │
│  Modell:     [Sunny Boy 5.0▼]                      │
│  IP:         [192.168.178.50]                      │
│  Port:       [502          ] (Modbus TCP)          │
│  Unit ID:    [3            ]                       │
│                                                     │
│  [Verbindung testen]                               │
└─────────────────────────────────────────────────────┘

Scan läuft über ESP32:

// Portal sendet Scan-Befehl via USB
await serial.writeText(JSON.stringify({cmd: 'scan_inverters'}));

// ESP32 scannt Netzwerk und sendet Ergebnisse zurück
// {"found": [{
//   "type": "SMA",
//   "ip": "192.168.178.50",
//   "modbus_unit": 3,
//   "serial": "1234567890",
//   "current_power": 3842
// }]}

Test-Verbindung:

┌─────────────────────────────────────────────────────┐
│  ✅ Wechselrichter gefunden!                       │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Verbindungstest erfolgreich:                      │
│  • Hersteller: SMA                                 │
│  • Modell: Sunny Boy 5.0                           │
│  • Seriennummer: 1234567890                        │
│  • Firmware: 3.20.12.R                             │
│  • Status: Producing                               │
│  • AC Leistung: 3.84 kW                            │
│  • DC Spannung: 385 V                              │
│  • Temperatur: 42°C                                │
│                                                     │
│  [Weiter zur Portal-Registrierung →]               │
└─────────────────────────────────────────────────────┘

Schritt 6: Portal-Registrierung

┌─────────────────────────────────────────────────────┐
│  🌐 Portal-Verbindung                              │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Geräte-Informationen:                             │
│  • MAC-Adresse: A1:B2:C3:D4:E5:F6                 │
│  • Firmware: v1.2.5                                │
│  • Display: LilyGO T5 4.7"                         │
│                                                     │
│  Kunde zuordnen:                                   │
│  ⦿ Max Mustermann (aus Auftrag)                   │
│  ⭘ Anderer Kunde                                   │
│                                                     │
│  Standort-Details:                                 │
│  Name:     [Hauptstraße 42, Würzburg         ]     │
│  Notizen:  [PV-Anlage Süddach, 7.5 kWp      ]     │
│            [Installiert am 23.10.2025        ]     │
│                                                     │
│  Einstellungen:                                    │
│  Display Update:  [30 Sekunden ▼]                  │
│  API Upload:      [60 Sekunden ▼]                  │
│  Zeitzone:        [Europe/Berlin ▼]                │
│                                                     │
│  [Gerät registrieren & aktivieren]                 │
└─────────────────────────────────────────────────────┘

Was passiert:

// 1. Portal registriert Gerät in Datenbank
const device = await fetch('/api/v1/devices/register', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${technicianToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mac_address: 'A1:B2:C3:D4:E5:F6',
    model: 'LilyGO T5 4.7"',
    firmware_version: 'v1.2.5',
    customer_id: 42,  // Max Mustermann
    inverter_config: {
      type: 'SMA',
      model: 'Sunny Boy 5.0',
      ip: '192.168.178.50',
      port: 502,
      modbus_unit_id: 3
    }
  })
});

// 2. Portal generiert Device-Token
const response = await device.json();
// {
//   "device_id": 123,
//   "device_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
//   "mqtt_credentials": {...}
// }

// 3. Portal sendet komplette Config via USB an ESP32
await serial.writeText(JSON.stringify({
  cmd: 'save_config',
  config: {
    wifi: {
      ssid: 'PV-Anlage-Fritz7590',
      password: '***************'
    },
    portal: {
      url: 'https://solarlog-api.karma.organic',
      device_id: 123,
      device_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    },
    inverter: {
      type: 'SMA',
      ip: '192.168.178.50',
      port: 502,
      modbus_unit_id: 3
    },
    intervals: {
      display_update: 30,
      api_upload: 60
    },
    timezone: 'Europe/Berlin'
  }
}));

// 4. ESP32 speichert in Flash und bestätigt
const ack = await serial.readLine();
// {"status": "ok", "config_saved": true}

Schritt 7: Finalisierung

┌─────────────────────────────────────────────────────┐
│  ✅ Installation abgeschlossen!                    │
├─────────────────────────────────────────────────────┤
│                                                     │
│  Gerät-ID: #123                                    │
│  Kunde: Max Mustermann                             │
│  Standort: Hauptstraße 42, Würzburg                │
│                                                     │
│  Konfiguration gespeichert:                        │
│  ✓ WLAN: PV-Anlage-Fritz7590                       │
│  ✓ Inverter: SMA Sunny Boy 5.0 @ 192.168.178.50   │
│  ✓ Portal: Registriert & authentifiziert           │
│  ✓ Display: Konfiguriert & getestet               │
│                                                     │
│  Nächste Schritte:                                 │
│  1. USB-Kabel entfernen                            │
│  2. ESP32 mit Netzteil verbinden                   │
│  3. Display zeigt nach ~10 Sek erste Daten         │
│  4. Gerät an gewünschter Stelle montieren          │
│                                                     │
│  [Live-Ansicht öffnen] [Installation dokumentieren]│
└─────────────────────────────────────────────────────┘

Techniker: 1. Trennt USB-Kabel 2. Schließt ESP32 an 5V-Netzteil an 3. Display bootet und zeigt nach 10 Sekunden:

┌────────────────────────────────┐
│  SolarLog                     │
│  🔄 Starte...                 │
│                                │
│  ✓ WLAN verbunden             │
│  ✓ Portal verbunden           │
│  ✓ Inverter verbunden         │
│                                │
│  ⏳ Lade Daten...             │
└────────────────────────────────┘

⬇ Nach 5 Sekunden ⬇

┌────────────────────────────────┐
│  Max Mustermann               │
│  SMA Sunny Boy 5.0            │
│                                │
│  ⚡ AKTUELL    3.8 kW         │
│  ☀️ HEUTE     28.5 kWh        │
│  📊 GESAMT    12.45 MWh       │
│                                │
│  📡 Online    ━━━━ 95%        │
│  🕐 14:23    23.10.2025       │
└────────────────────────────────┘

Schritt 8: Live-Verifikation im Portal

Techniker öffnet im Browser:

https://solarlog.karma.organic/devices/123

┌─────────────────────────────────────────────────────┐
│  🟢 Gerät #123 - ONLINE                            │
├─────────────────────────────────────────────────────┤
│                                                     │
│  📍 Standort: Hauptstraße 42, Würzburg             │
│  👤 Kunde: Max Mustermann                          │
│  📅 Installiert: 23.10.2025 14:23                  │
│  👷 Techniker: techniker@solarfirma.de             │
│                                                     │
│  ⚡ Aktuelle Daten:                                │
│  ┌───────────────────────────────────────────────┐ │
│  │ Leistung:        3.84 kW                      │ │
│  │ Heute:          28.5 kWh                      │ │
│  │ Gesamt:      12.45 MWh                        │ │
│  │ Temperatur:      42°C                         │ │
│  │ Status:      Producing                        │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  📊 Datenübertragung:                              │
│  • Letzte Übertragung: vor 12 Sekunden            │
│  • Intervall: 60 Sekunden                         │
│  • Erfolgsrate: 100% (5/5)                        │
│                                                     │
│  📡 Verbindung:                                    │
│  • WLAN: -52 dBm (Ausgezeichnet)                  │
│  • Uptime: 2 Minuten                              │
│  • Firmware: v1.2.5                               │
│                                                     │
│  [📷 Screenshot anfordern] [⚙️ Einstellungen]     │
└─────────────────────────────────────────────────────┘

✅ Installation erfolgreich abgeschlossen!

Techniker: - Macht Foto vom Display (Dokumentation) - Notiert Geräte-ID (#123) im Installationsprotokoll - Montiert Display an gewünschter Stelle - Gibt Kunde Zugang zum Portal

---

🔒 Sicherheitskonzept

Device-Token-Generierung

# backend/app/api/v1/devices.py

@router.post("/register")
async def register_device(
    data: DeviceRegistrationRequest,
    current_user: User = Depends(get_current_technician)  # Nur Techniker!
):
    """
    Registriert neues ESP32-Gerät.
    Nur von Techniker-Accounts aufrufbar.
    """

    # 1. Prüfe ob MAC-Adresse eindeutig
    existing = await get_device_by_mac(data.mac_address)
    if existing:
        raise HTTPException(409, "Device already registered")

    # 2. Generiere Device-Token (256-bit)
    device_token = secrets.token_urlsafe(32)
    device_token_hash = hashlib.sha256(device_token.encode()).hexdigest()

    # 3. Erstelle Device in Datenbank
    device = Device(
        mac_address=data.mac_address,
        device_token_hash=device_token_hash,
        firmware_version=data.firmware_version,
        model=data.model,
        customer_id=data.customer_id,
        inverter_config=data.inverter_config,
        installed_by=current_user.id,
        installed_at=datetime.utcnow()
    )
    db.add(device)
    await db.commit()

    # 4. Generiere MQTT-Credentials (optional)
    mqtt_creds = {
        "broker": "mqtt.solarlog.io",
        "port": 8883,
        "username": f"device_{device.id}",
        "password": secrets.token_urlsafe(16)
    }

    # 5. Rückgabe (Token nur EINMAL!)
    return {
        "device_id": device.id,
        "device_token": device_token,  # Klartext, nur hier!
        "mqtt_credentials": mqtt_creds
    }

Authentifizierung im Betrieb

# ESP32 sendet bei jedem API-Call:
headers = {
    "Authorization": f"Bearer {device_token}",
    "X-Device-MAC": mac_address
}

# Backend validiert:
@router.post("/devices/{device_id}/data")
async def receive_data(
    device_id: int,
    data: ProductionDataUpload,
    device: Device = Depends(authenticate_device)
):
    # Device-Token wurde bereits in Middleware validiert
    # Nur valide Geräte kommen hier an
    ...

---

📦 Hardware-Paket für Techniker

Standard-Installations-Kit

Im Koffer:

1× ESP32 E-Paper Display (vakuumversiegelt)
1× USB-Kabel (USB-C oder Micro-USB, je nach ESP32-Modell)
1× 5V/2A USB-Netzteil (EU-Stecker)
1× Montagematerial (Schrauben, Dübel, Klebestreifen)
1× Anleitung (QR-Code zum Portal-Setup)
1× Installationsprotokoll (Papier, zum Ausfüllen)

Auf dem Laptop:

Chrome oder Edge Browser (aktuell)
Lesezeichen: https://solarlog.karma.organic/setup/install
Techniker-Login gespeichert

Optional:

Multimeter (WLAN-Signalstärke messen)
Ethernet-Adapter (für Laptop ohne WLAN)
Powerbank (falls keine Steckdose verfügbar)

---

🚀 Vorteile dieser Lösung

✅ Für Techniker

• Schnell: 2-3 Minuten reine Setup-Zeit
• Einfach: Ein klarer Workflow, keine Verzweigungen
• Zuverlässig: USB = keine WLAN-Probleme während Installation
• Dokumentiert: Automatische Protokollierung im Portal
• Support: Bei Problemen → Portal zeigt Debug-Infos

✅ Für Firma

• Professionalität: Kein "Benutzer muss selber machen"
• Kontrolle: Nur Techniker können Geräte registrieren
• Qualität: Jede Installation wird getestet
• Support-Reduzierung: Weniger Fehlerquellen
• Skalierbar: Techniker können 10+ Geräte/Tag installieren

✅ Für Endkunden

• Einfach: Kunde muss nichts machen
• Sicher: Keine WLAN-Passwörter selbst eingeben
• Funktioniert: Techniker testet vor Ort
• Support: Bei Problemen kontaktiert Kunde Firma, nicht Hersteller

---

🔧 Entwicklungsaufwand

Phase 1: Portal-WebSerial-Tool (1 Woche)

// frontend-web/src/pages/SetupFlash.tsx

- USB Serial Connection Handler
- esptool.js Integration
- Firmware Download & Flash
- Config Generator & Upload
- Live-Test & Verification
- Installation Documentation

Phase 2: Backend Device-Management (3-4 Tage)

# backend/app/api/v1/devices.py

- POST /devices/register (Techniker-Only)
- POST /devices/{id}/data (Device-Token Auth)
- POST /devices/{id}/heartbeat
- GET  /devices/{id}/logs
- GET  /devices/{id}/screenshot (optional)

Phase 3: ESP32 Firmware (1-1.5 Wochen)

// esp32-firmware/src/

- USB Serial Command Interface
- WiFi Test & Connect
- Inverter Scan & Connect
- Config Storage (SPIFFS/NVS)
- Display Manager
- Portal Client (HTTPS)
- Error Handling & Recovery

Phase 4: Testing & Dokumentation (3-4 Tage)

• End-to-End Tests
• Techniker-Schulung
• Video-Tutorial
• Troubleshooting-Guide

GESAMT: 3-4 Wochen Entwicklung

---

📊 Kostenanalyse

Entwicklungskosten (einmalig)

Entwickler:     20 Tage × 500 EUR = 10.000 EUR
Tester:          5 Tage × 400 EUR =  2.000 EUR
Dokumentation:   3 Tage × 350 EUR =  1.050 EUR
────────────────────────────────────────────
GESAMT:                             13.050 EUR

Pro-Gerät-Kosten

Hardware:
├─ ESP32-S3 + Display:  35 EUR
├─ Gehäuse:              8 EUR
├─ Netzteil:             4 EUR
└─ Verpackung:           2 EUR
                        ────────
                        49 EUR/Gerät

Installation (Techniker):
└─ 10 Min × 60 EUR/Std = 10 EUR/Gerät

Cloud (monatlich):
└─ 12 MB × 0.01 EUR    = 0.12 EUR/Gerät/Monat
                         1.44 EUR/Gerät/Jahr

Break-Even bei 100 Geräten

Entwicklung:        13.050 EUR
Hardware (100×):     4.900 EUR
Installation (100×): 1.000 EUR
Cloud (Jahr 1):        144 EUR
────────────────────────────
GESAMT:             19.094 EUR

Pro Gerät:             191 EUR
Verkaufspreis:         299 EUR (empfohlen)
Gewinn pro Gerät:      108 EUR
Break-Even:           ~175 Geräte

---

🔮 Zukunftserweiterungen

Phase 2 Features

Remote-Updates:

Techniker muss nicht mehr vor Ort
ESP32 lädt neue Firmware vom Portal (OTA)
Automatische Updates nachts
Rollback bei Fehler

Ferndiagnose:

Portal → ESP32: "Sende Screenshot"
ESP32 → Portal: PNG-Bild vom Display
Techniker sieht exakt was Kunde sieht

Bulk-Installation:

Techniker flasht 10 Geräte parallel
Jedes Gerät bekommt QR-Code
Vor Ort nur noch QR-Code scannen → Fertig

Offline-Modus:

ESP32 funktioniert ohne Internet
Lokales Dashboard im WLAN
Automatische Sync wenn Internet wieder da

---

✅ Checkliste für Go-Live

• Portal-Tool entwickelt & getestet
• Backend API implementiert
• ESP32 Firmware funktionsfähig
• 5 Test-Installationen durchgeführt
• Techniker-Schulung absolviert
• Video-Tutorial erstellt
• Support-Dokumentation fertig
• Fehlerbehebungs-Guide vorhanden
• Hardware-Kits für 3 Techniker gepackt
• Go-Live mit Pilot-Kunden

Geschätzte Zeit bis Go-Live: 6-8 Wochen