← Sensor-Kalibrierung | Inhaltsverzeichnis | Weiter: Home Assistant Integration →

11. MQTT-Integrationsanleitung

Version: 1.2.0
Date: 2025-12-24

Vollständige Anleitung zur MQTT-Anbindung des ACRouter, einschließlich Topic-Struktur und Home Assistant Integration.

Inhaltsverzeichnis

• Übersicht
• Funktionen
• Schnellstart
• Topic-Struktur
• Konsolenbefehle
• Konfiguration
• Topics testen
• Fehlerbehebung

Übersicht

ACRouter unterstützt das MQTT-Protokoll für:

• Echtzeit-Überwachung — Leistungskennzahlen, Spannung, Ströme, Router-Status
• Fernsteuerung — Moduswechsel, Dimmer-Steuerung, Not-Aus
• Konfiguration — Parameter aus der Ferne anpassen
• Home Assistant Integration — Auto-Discovery für nahtlose Smart-Home-Integration

The MQTT client is based on ESP-IDF's esp-mqtt library with automatic reconnection, Last Will & Testament (LWT), and QoS support.

Funktionen

Schnellstart

1. MQTT über die serielle Konsole aktivieren

# Set broker URL (replace with your broker IP)
mqtt-broker mqtt://192.168.1.10:1883

# Enable MQTT
mqtt-enable

# Check status
mqtt-status

2. Verbindung überprüfen

======================================================
  MQTT Status
======================================================
State:         Connected
Enabled:       Yes
Broker:        mqtt://192.168.1.10:1883
Device ID:     039C7C
Device Name:   (default)
HA Discovery:  Enabled
Pub Interval:  5000 ms
------------------------------------------------------
Uptime:        125 sec
Published:     250 messages
Received:      3 messages
======================================================

3. Topics abonnieren

Verwendung der Mosquitto-Client-Tools als Beispiel:

# Subscribe to all ACRouter topics
mosquitto_sub -h 192.168.1.10 -t "acrouter/#" -v

Topic-Struktur

Alle Topics folgen dem Muster: acrouter/{device_id}/category/name

Die {device_id} wird automatisch aus den letzten 6 Zeichen der MAC-Adresse generiert (z. B. 039C7C) oder kann manuell gesetzt werden.

Status-Topics (Retained)

Messwert-Topics (nicht Retained)

Veröffentlichung alle 5 Sekunden (konfigurierbar).

Konfigurations-Topics (Retained)

Befehls-Topics (nur Schreiben)

Befehle werden durch Veröffentlichung an diese Topics gesendet:

System-Topics (Retained)

JSON-aggregierte Topics

Zur Effizienzsteigerung werden Messwerte auch als aggregiertes JSON veröffentlicht:

Topic: json/metrics

{
  "voltage": 230.5,
  "power_grid": -150.2,
  "power_solar": 1250.0,
  "power_load": 1100.0,
  "current_grid": 0.65,
  "current_solar": 5.43,
  "current_load": 4.78,
  "direction": "supplying"
}

Konsolenbefehle

Verbindungsverwaltung

Konfiguration

Beispiele

# Configure broker with authentication
mqtt-broker mqtt://192.168.1.10:1883
mqtt-user myuser
mqtt-pass mypassword
mqtt-enable

# Set custom device name for Home Assistant
mqtt-device-name "Solar Router Kitchen"

# Reduce publish frequency to 10 seconds
mqtt-interval 10000

# Disable Home Assistant auto-discovery
mqtt-ha-discovery 0

Konfiguration

NVS-Speicherschlüssel

Alle MQTT-Einstellungen werden im NVS (Non-Volatile Storage) gespeichert:

Standardwerte

Topics testen

Sie können jeden MQTT-Client zum Testen der Topics verwenden. Die folgenden Beispiele nutzen die Mosquitto-Client-Tools (mosquitto_sub / mosquitto_pub).

Alle Topics abonnieren

mosquitto_sub -h 192.168.1.10 -t "acrouter/#" -v

Bestimmte Topics abonnieren

# Status only
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/status/#" -v

# Metrics only
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/metrics/#" -v

# JSON aggregated
mosquitto_sub -h 192.168.1.10 -t "acrouter/039C7C/json/#" -v

Befehle senden

# Change mode to AUTO
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/mode" -m "auto"

# Set dimmer to 50% (in MANUAL mode)
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/dimmer" -m "50"

# Emergency stop
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/emergency_stop" -m "1"

# Reboot device
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/reboot" -m "1"

# Force refresh all data
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/command/refresh" -m "1"

Konfiguration über MQTT aktualisieren

# Set control gain
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/config/control_gain/set" -m "200"

# Set balance threshold
mosquitto_pub -h 192.168.1.10 -t "acrouter/039C7C/config/balance_threshold/set" -m "25"

Fehlerbehebung

Verbindungsprobleme

Symptom: esp-tls: select() timeout

Lösungen:

1. Prüfen Sie, ob der Broker läuft und erreichbar ist
2. Prüfen Sie, ob die Firewall Port 1883 zulässt
3. Überprüfen Sie das Broker-URL-Format: mqtt://IP:PORT
4. Testen Sie die Broker-Konnektivität von einem anderen Client aus

"Client has started" Error

Symptom: Wiederholte mqtt_client: Client has started-Fehler

Lösung: Dies war ein Fehler in früheren Versionen. Aktualisieren Sie auf die neueste Firmware, in der esp_mqtt_client_start() nur einmal aufgerufen wird.

WLAN nicht verbunden

Symptom: MQTT doesn't connect on boot

Erklärung: MQTT wartet nun auf die WLAN-Verbindung, bevor ein Verbindungsversuch unternommen wird. Prüfen Sie zuerst den WLAN-Status:

wifi-status

Nachrichten werden nicht empfangen

Symptom: Befehle wurden gesendet, aber nicht verarbeitet

Lösungen:

1. Prüfen Sie die Topic-Schreibweise (Groß-/Kleinschreibung beachten)
2. Überprüfen Sie, ob die Geräte-ID übereinstimmt: mqtt-status
3. Prüfen Sie, ob die Nachricht empfangen wurde: Das Geräteprotokoll zeigt MQTT: Command: mode = auto

Home Assistant erkennt das Gerät nicht

Symptom: Device doesn't appear in Home Assistant

Lösungen:

1. Überprüfen Sie, ob HA Discovery aktiviert ist: mqtt-ha-discovery 1
2. Prüfen Sie, ob die HA MQTT-Integration konfiguriert ist
3. Erzwingen Sie eine erneute Veröffentlichung: mqtt-publish oder starten Sie das Gerät neu
4. Prüfen Sie die HA-Protokolle auf Discovery-Nachrichten

Siehe auch

• 12_HOME_ASSISTANT.md — Details zur Home Assistant Integration
• 07_COMMANDS_EN.md — Vollständige Befehlsreferenz
• 05_API_REFERENCE_EN.md — REST API Dokumentation

Zuletzt aktualisiert: 2025-12-24

← Sensor-Kalibrierung | Inhaltsverzeichnis | Weiter: Home Assistant Integration →