# Victron BLE Dashboard — Benutzerhandbuch

## ESP32-S3 Bluetooth Gateway für Victron-Energy-Geräte

**Version:** 3.5.0  
**Autor:** Michael Schäfer · [schaefer-services.de](https://schaefer-services.de)  
**Repository:** [gitlab.com/schaefer-services/victron-ble-tunnel](https://gitlab.com/schaefer-services/victron-ble-tunnel)

---

## Inhaltsverzeichnis

1. [Überblick](#1-überblick)
2. [Lieferumfang](#2-lieferumfang)
3. [Inbetriebnahme](#3-inbetriebnahme)
4. [Die Status-LED](#4-die-status-led)
5. [Das Web-Dashboard](#5-das-web-dashboard)
6. [Geräte steuern](#6-geräte-steuern)
7. [MQTT-Integration](#7-mqtt-integration)
8. [Auto-Update](#8-auto-update)
9. [Werkseinstellungen zurücksetzen](#9-werkseinstellungen-zurücksetzen)
10. [Fehlerbehebung](#10-fehlerbehebung)
11. [Technische Daten](#11-technische-daten)
12. [Unterstützte Geräte](#12-unterstützte-geräte)

---

## 1. Überblick

Das Victron BLE Dashboard ist ein kleines Modul, das alle Ihre Victron-Energy-Geräte mit Bluetooth drahtlos überwacht und steuert. Es läuft komplett lokal — keine Cloud, keine App, keine monatlichen Kosten.

**Was es macht:**
- Liest Live-Daten von allen Victron-Geräten in Bluetooth-Reichweite (Instant Readout)
- Zeigt die Daten in einem Web-Dashboard (Smartphone, Tablet, PC)
- Ermöglicht Steuerung von Ladegeräten (Lademodus, Strom, Spannung, An/Aus)
- Sendet alle Daten via MQTT an Home Automation Systeme
- Aktualisiert sich selbstständig (Auto-Update über GitLab)

**Was es NICHT braucht:**
- VictronConnect App
- Internetverbindung (außer für Auto-Update)
- Cloud-Service
- Monatliche Gebühren

---

## 2. Lieferumfang

- 1x ESP32-S3 DevKitC-1 N16R8 mit IPEX-Antennenanschluss
- 1x 2.4GHz Stabantenne (IPEX-Stecker)
- 1x Kurzanleitung (dieses Dokument)

**Nicht enthalten:**
- USB-C Kabel zur Stromversorgung (Standard USB-C, wie Smartphone)
- WLAN-Router (Sie benötigen ein bestehendes WLAN)
- Victron-Geräte (diese müssen Sie bereits besitzen)

---

## 3. Inbetriebnahme

### Schritt 1: Mit Strom verbinden

Verbinden Sie den ESP32-S3 mit einem USB-C Kabel mit einem USB-Netzteil (mindestens 500mA, Standard Smartphone-Lader reicht). Die Status-LED beginnt gelb zu blinken.

### Schritt 2: WLAN einrichten

1. Suchen Sie auf Ihrem Smartphone oder PC nach dem WLAN "Victron-S3-Setup"
2. Verbinden Sie sich (Passwort: `victron123`)
3. Es öffnet sich automatisch das Setup-Portal (ansonsten `http://192.168.4.1` im Browser)
4. Geben Sie Ihre WLAN-SSID und Ihr WLAN-Passwort ein
5. Tippen Sie auf "Speichern"

Die Status-LED wechselt auf Grün (WLAN verbunden) oder Blau (Geräte erkannt).

### Schritt 3: Dashboard öffnen

Öffnen Sie in Ihrem Browser:
- `http://victron-s3.local/` (empfohlen, funktioniert auf meisten Geräten)
- Oder die IP-Adresse des ESP32 (im Router nach "victron-s3" suchen)

Das Dashboard zeigt automatisch alle Victron-Geräte in Bluetooth-Reichweite an.

### Schritt 4: MQTT einrichten (optional)

Wenn Sie Home Assistant, ioBroker oder Node-RED verwenden:

1. Öffnen Sie das Dashboard → Settings-Tab
2. Tragen Sie MQTT-Broker, Port, Topic, User und Passwort ein
3. Speichern — der ESP32 verbindet sich automatisch

MQTT-Topics (Tasmota-kompatibel):
```
victron/s3/tele/[MAC]/STATE    → Live-Werte (alle 10s, retained)
victron/s3/tele/[MAC]/SENSOR   → Sensor-Werte (alle 10s)
victron/s3/cmnd/[MAC]/#        → Steuer-Befehle empfangen
victron/s3/stat/[MAC]/RESULT   → Bestätigung nach Befehl
```

---

## 4. Die Status-LED

Die LED auf dem ESP32-Modul zeigt den aktuellen Betriebszustand an:

| LED-Zustand | Bedeutung | Was zu tun ist |
|-------------|-----------|----------------|
| 🟡 **Gelb blinkend** | WLAN Setup Modus | WLAN einrichten (siehe Schritt 2) |
| 🔴 **Rot blinkend** | WLAN nicht verbunden | WLAN-Passwort prüfen, Router neu starten |
| 🟢 **Grün durchgehend** | WLAN verbunden, keine Geräte gefunden | Victron-Gerät in Reichweite bringen |
| 🔵 **Blau durchgehend** | WLAN + Geräte erkannt — alles okay! | Nichts — alles läuft |

---

## 5. Das Web-Dashboard

Das Dashboard hat 4 Tabs (unten auf dem Bildschirm auf Mobile, oben auf PC):

### 📊 Live-Tab
Zeigt alle erkannten Victron-Geräte mit Live-Werten:
- **AC Ladegeräte:** Batteriespannung, Ladestrom, Lademodus, Temperatur
- **Solar-Laderegler:** Batteriespannung, Ladestrom, Solarleistung (W), Tagesertrag (Wh)
- **Batterie-Monitor:** Spannung, Strom, Ladestand (SoC), Starterbatterie
- **DC-DC Wandler:** Eingangsspannung, Ausgangsspannung
- **Wechselrichter:** Batteriespannung, AC-Spannung, AC-Strom, AC-Leistung

### 📡 Scan-Tab
Zeigt alle gefundenen Bluetooth-Geräte mit:
- MAC-Adresse
- Modellname
- Signalstärke (RSSI)
- "Verbinden"-Button (für GATT-Steuerung)

### 🎮 Steuerungs-Tab
Zeigt verbundene Geräte mit Steuerungsmöglichkeiten:
- **AC Ladegeräte:** Lademodus (Normal, High, Storage, Li-Ion, Custom, PSU), Strom, Spannungen
- **Solar-Laderegler:** An/Aus
- **DC-DC Wandler:** An/Aus
- **Wechselrichter:** An/Aus/Auto (AES-Modus)
- **Universeller Register-Write** für erweiterte Steuerung

### ⚙️ Settings-Tab
- System-Info (Firmware-Version, Build-Datum, IP, Heap, Uptime)
- WiFi-Konfiguration (SSID, Passwort)
- MQTT-Konfiguration
- Syslog-Konfiguration
- OTA Firmware-Update (Datei-Upload oder URL)
- Auto-Update Status
- WiFi Reset / Reboot / Werksreset

---

## 6. Geräte steuern

### Über das Web-Dashboard

1. Öffnen Sie den **Scan-Tab**
2. Tippen Sie auf "Verbinden" beim gewünschten Gerät
3. Wechseln Sie zum **Steuerungs-Tab**
4. Wählen Sie den Slot des verbundenen Geräts
5. Steuern Sie: Lademodus, Strom, Spannungen, An/Aus

**Wichtig:** Die Steuerung erfolgt über eine aktive Bluetooth-Verbindung (GATT). Der ESP32 kann sich mit bis zu 3 Geräten gleichzeitig verbinden. Die Verbindung hält ca. 15 Minuten (dann Auto-Reconnect). Während einer aktiven App-Verbindung (VictronConnect) kann der ESP32 sich nicht verbinden — schließen Sie die App zuerst.

### Über MQTT

Senden Sie Befehle an:
```
victron/s3/cmnd/[MAC]/charge-mode 0    → Lademodus Normal
victron/s3/cmnd/[MAC]/charge-mode 1    → Lademodus High
victron/s3/cmnd/[MAC]/max-current 15   → Max. 15A Ladestrom
victron/s3/cmnd/[MAC]/charger 1        → Charger AN
victron/s3/cmnd/[MAC]/charger 0        → Charger AUS
```

### Über die HTTP-API

```
GET /api/md/connect?mac=c8:0a:57:0f:48:41    → Gerät verbinden
GET /api/md/charge-mode?idx=0&mode=0          → Lademodus setzen
GET /api/md/max-current?idx=0&amps=15         → Ladestrom setzen
GET /api/md/charger?idx=0&on=1                → Charger AN
```

---

## 7. MQTT-Integration

### Home Assistant

Fügen Sie in Ihrer `configuration.yaml` hinzu:
```yaml
mqtt:
  sensor:
    - name: "Victron Batteriespannung"
      state_topic: "victron/s3/tele/c80a570f4841/STATE"
      value_template: "{{ value_json.Battery.Voltage }}"
      unit_of_measurement: "V"
    - name: "Victron Ladestrom"
      state_topic: "victron/s3/tele/c80a570f4841/STATE"
      value_template: "{{ value_json.Battery.Current }}"
      unit_of_measurement: "A"
```

### ioBroker

Fügen Sie den MQTT-Adapter hinzu und abonnieren Sie `victron/s3/tele/#`.

---

## 8. Auto-Update

Der ESP32 prüft alle 60 Minuten automatisch nach Firmware-Updates auf GitLab. Wenn eine neue Version verfügbar ist, wird sie automatisch heruntergeladen und installiert.

**Manuell prüfen:**
```
GET /api/auto-update/check
```

**Deaktivieren:**
```
GET /api/auto-update/disable
```

**Aktivieren:**
```
GET /api/auto-update/enable
```

---

## 9. Werkseinstellungen zurücksetzen

Es gibt drei Wege, das Gerät zurückzusetzen:

### Methode 1: Power-Cycle (Hardware, wie Tasmota)
1. **5x** innerhalb von **10 Sekunden** den Strom aus- und wieder einschalten
2. Alle Daten werden gelöscht (WiFi, MQTT, Keys, PIN)
3. Das Gerät startet ins WLAN-Setup-Portal

### Methode 2: Über das Web-Dashboard
1. Settings-Tab → "🏭 Werksreset" Button
2. Bestätigen — alle Daten werden gelöscht

### Methode 3: Über die API
```
GET /api/factory-reset
```

### Nur WLAN zurücksetzen (ohne andere Daten zu löschen):
```
GET /api/wifi/reset
```

---

## 10. Fehlerbehebung

| Problem | Lösung |
|---------|--------|
| LED blinkt rot | WLAN-Passwort falsch → WiFi Reset, neu einrichten |
| LED leuchtet grün, aber keine Geräte | Victron-Gerät zu weit entfernt → näher platzieren oder externe Antenne ausrichten |
| Gerät nicht im Scan-Tab | VictronConnect App schließen (blockiert Bluetooth) → ESP32 neu starten |
| Steuerung funktioniert nicht | Verbindung hält nur 15s → innerhalb der 15s steuern, oder Auto-Reconnect abwarten |
| Dashboard nicht erreichbar | IP-Adresse prüfen → `victron-s3.local` versuchen → Router DHCP-Tabelle prüfen |
| MQTT nicht verbunden | Broker-IP und Port prüfen → Settings-Tab → MQTT-Konfiguration |
| ESP32 nicht erreichbar | Power-Cycle (Strom abziehen, 5s warten, wieder anschließen) |

### Wenn nichts mehr geht: Power-Cycle Factory Reset
5x Strom aus/an innerhalb 10 Sekunden → komplett frisches Gerät.

---

## 11. Technische Daten

| Parameter | Wert |
|-----------|------|
| **Chip** | ESP32-S3 N16R8 (16MB Flash, 8MB PSRAM) |
| **WLAN** | 802.11 b/g/n, 2.4 GHz |
| **Bluetooth** | BLE 5.0 mit externer Antenne (IPEX/U.FL) |
| **Reichweite** | 10-15m (mit externer Antenne im Freien) |
| **Stromversorgung** | 5V USB-C (ab 100mA) |
| **Abmessungen** | 51×28mm (nur das Modul) |
| **Gewicht** | ca. 10g |
| **Firmware** | Open Source (MIT-Lizenz) |
| **API** | REST + WebSocket |
| **MQTT** | Tasmota-kompatibel |
| **Auto-Update** | Über GitLab (alle 60min, deaktivierbar) |
| **Werksreset** | 5x Power-Cycle innerhalb 10s (Tasmota-Prinzip) |

---

## 12. Unterstützte Geräte

### Getestet und funktionsfähig:
| Gerät | Monitoring | Steuerung |
|-------|------------|-----------|
| Blue Smart IP22 12/20 (3-Output) | ✅ | ✅ Voll |
| Blue Smart IP65 6V/12V 1.1A | ✅ | ✅ Voll |
| SmartSolar MPPT 100/30 | ✅ | ✅ An/Aus |
| SmartShunt Battery Monitor (2nd Gen) | ✅ | — (read-only) |
| Orion Smart DC-DC 12/12-30 | ✅ | ✅ An/Aus |
| VE.Direct Inverter 12/800 230V (mit BT Dongle) | ✅ | ✅ An/Aus/Auto |

### Prinzipiell kompatibel (gleicher Protokoll-Typ):
- Alle Blue Smart IP22/IP65 Ladegeräte
- Alle SmartSolar/BlueSolar MPPT Laderegler mit Bluetooth
- Alle Orion Smart DC-DC Wandler mit Bluetooth
- Alle SmartShunt/BMV-712 Batterie-Monitore
- Alle Phoenix Inverter mit Bluetooth
- Alle VE.Direct Geräte mit VE.Direct Bluetooth Smart Dongle

**Voraussetzung:** Das Gerät muss "Instant Readout" (BLE Advertising) unterstützen. Dies ist bei allen Victron-Geräten mit Bluetooth ab Werk aktiviert.

---

© Michael Schäfer · [schaefer-services.de](https://schaefer-services.de) · 2026