MQTT-Broker

Der Hub kann seine Live-Messwerte an einen MQTT-Broker in Ihrem Netzwerk veröffentlichen und Befehle von dort entgegennehmen. Home Assistant nutzt dieselbe Verbindung: Der Hub meldet seine Sensoren über die MQTT-Discovery.

MQTT ist aus, bis Sie einen Broker einstellen. Der Hub verbindet sich nur, wenn er in Ihrem Heim-WLAN ist, nicht solange er nur seinen eigenen Access Point betreibt.

Den Hub mit einem Broker verbinden

Öffnen Sie in der App Settings → Home Assistant und füllen Sie das Formular MQTT broker aus: die Adresse des Brokers, den Port (meist 1883), Benutzername und Passwort. Speichern Sie und starten Sie den Hub neu, wenn die App dazu auffordert; die Broker-Einstellungen gelten nach einem Neustart.

Alternativ über die API: POST /api/system/mqtt-config mit {"broker_uri":"mqtt://user:password@host:1883"}. Beim Auslesen wird das Passwort maskiert angezeigt.

Verwenden Sie eine einfache mqtt://-Adresse oder mqtts:// für eine sichere Verbindung:

• ab v1.1.7 mit einem Zertifikat einer öffentlichen Zertifizierungsstelle – eine aus der Mozilla-Root-Liste, etwa Let's Encrypt oder DigiCert –, das zum Hostnamen des Brokers passt;
• ab v1.1.8 auch mit Ihrer eigenen Zertifizierungsstelle: ein Heim-Broker mit einer privaten CA oder ein selbstsigniertes Zertifikat, was Mosquitto innerhalb von Home Assistant mit einem eigenen Zertifikat abdeckt. Siehe Your own broker CA unten.

Auf v1.1.7 konnte ein privates oder selbstsigniertes Zertifikat gar nicht verwendet werden; ein solcher Broker brauchte eine einfache mqtt://-Adresse in einem Netzwerk, dem Sie vertrauen.

Eigene CA des Brokers

Settings → Home Assistant hat eine Karte Broker CA (for mqtts). Solange nichts hochgeladen ist, steht dort „None uploaded: the hub trusts public certificate authorities only.“ Upload CA certificate nimmt die PEM-Datei Ihrer Zertifizierungsstelle entgegen – die Datei, die mit -----BEGIN CERTIFICATE----- beginnt – und der Hub antwortet „Certificate saved on the hub. It is used after a restart.“ Die Karte listet dann auf, was gespeichert ist: Subject, Issuer und die Gültigkeitsdaten.

Der Hub lehnt eine Datei ab, die nicht stimmt, und sagt, warum:

⚠️ Das Entfernen der CA trennt einen Broker, der von ihr abhängt. Remove the broker CA? warnt: „After a restart the hub connects only to brokers with a public certificate. A broker that uses this CA stops connecting.“ Danach: „Certificate removed. After a restart the hub trusts public certificate authorities only.“

Die hochgeladene CA ersetzt das öffentliche Bundle, statt es zu ergänzen, und wirkt beim nächsten Neustart. Über die API: POST /api/system/mqtt-ca mit dem PEM, GET, um Gespeichertes zu sehen, DELETE, um zum öffentlichen Bundle zurückzukehren.

Warum eine sichere Verbindung abgelehnt wurde

Ab v1.1.8 prüft der Hub neben Zertifizierungsstelle und Hostnamen auch die Gültigkeitsdaten des Zertifikats und sagt, was er gefunden hat. Die Karte zeigt eines dieser Ergebnisse:

⚠️ Ein Hub ohne Uhr öffnet überhaupt keine TLS-Verbindung, und das ist beabsichtigt. Eine nicht gesetzte Uhr lässt jedes Zertifikat als „noch nicht gültig“ erscheinen, daher wartet der Hub ab v1.1.8, bis er die Zeit hat – per NTP oder von Hand gesetzt –, bevor er es versucht. Das Ereignisprotokoll zeigt „mqtt: TLS broker — waiting for the clock“. Ein einfacher mqtt://-Broker wird nicht verzögert. → Time

Jede Ablehnung schreibt außerdem eine Zeile in das Ereignisprotokoll. Über die API steht derselbe Zustand in GET /api/system/mqtt-config → tls: {state, ca, ca_uploaded}, wobei state ok, expired, not_yet_valid, name_mismatch, unknown_ca, waiting_clock, connecting, tls_error oder off für eine einfache Verbindung ist und ca den Wert custom oder bundle hat.

Kann der Hub den Broker nicht prüfen, versucht er es weiter, und nichts anderes stoppt: Settings → MQTT zeigt MQTT als nicht verbunden, und das Ereignisprotokoll des Hubs nennt den Grund. → Events

Halten Sie den Broker privat. Wer auf dem Broker lesen und schreiben kann, kann die Einstellungen des Hubs über den Befehlskanal lesen, und ein mit einem Befehl gesendetes Admin-Token ist für jeden Client sichtbar, der ihn abonniert hat. Verwenden Sie einen Broker mit eigenen Benutzern und Zugriffsregeln (ACL) in Ihrem eigenen Netzwerk: Geben Sie dem Hub einen eigenen Broker-Benutzer und beschränken Sie den Zugriff auf rbgrid/<mac>/# auf den Hub und die Clients, denen Sie vertrauen. Verwenden Sie niemals einen öffentlichen Broker.

Topics

<mac> ist die WLAN-MAC-Adresse des Hubs: 12 Hex-Ziffern in Kleinbuchstaben, zum Beispiel a0b1c2d3e4f5. Der Hub verbindet sich mit der Client-ID rbgrid-<mac>.

Der Telemetrie-Frame

Jeder Frame ist ein JSON-Objekt. Die wichtigsten Felder:

Energiewerte (e_in, e_out, e_day_in, e_day_out) sind in Wh angegeben; Geldwerte (cost_*, rev_*) in der Währung des Tarifs. Bei Modulen, die die Energie an Bord zählen ("energy_mode": "on_device"), steigen die Energiesummen einmal pro 15-Minuten-Periode; Leistung, Strom und Spannung aktualisieren sich alle 3 Sekunden. Frames werden nur gesendet, während der Hub verbunden ist. Ist der Broker nicht erreichbar, werden Live-Frames verworfen (nichts wird zwischengespeichert oder nachgeliefert). Der Verlauf bleibt auf dem Hub und kann später über HTTP oder mit dem Befehl history gelesen werden.

Beispiel

Ein echter Frame von einem Testhub, auf einen Messpunkt gekürzt: eine Küchenleitung mit etwa 400 W. Auf der Leitung ist es eine kompakte Zeile. Die Energiesumme ist noch klein, weil dieser Punkt die Energie im Modul zählt und die 15-Minuten-Periode mit der Last noch nicht abgeschlossen war.

{
  "v": 2,
  "sntp": 1793756448,
  "tq": 1,
  "time_src": "sntp",
  "seq": 707,
  "boot_id": 1158837418,
  "freq": 50,
  "system": {
    "tariff": {
      "zone": "NIGHT",
      "buy_rate": 0.2,
      "sell_rate": 0.12,
      "buy_rate_all_in": 0.27104,
      "currency": "EUR",
      "placeholder": true
    },
    "units": 3,
    "present": 2
  },
  "units": {
    "0102": {
      "point": "kitchen",
      "v": 222.85,
      "i": 1.804,
      "p_act": 402.22,
      "p_rea": 0,
      "pf": 1,
      "dir": 1,
      "present": true,
      "module": 1,
      "ch": 0,
      "ch_label": "I0",
      "energy_mode": "on_device",
      "e_in": 0.0223,
      "e_day_in": 0.0223,
      "e_out": 0,
      "e_day_out": 0,
      "load_pct": 6,
      "type": "CURRENT_LOAD",
      "role": "DEVICE_LOAD"
    }
  },
  "main_unit": "0006",
  "vbus_unit": "0007"
}

"placeholder": true bedeutet hier, dass der Testhub noch den werkseitigen Beispieltarif hatte.

Home-Assistant-Discovery

Bei jeder Verbindung veröffentlicht der Hub Discovery-Nachrichten mit Retained-Flag, sodass Home Assistant die Geräte und Sensoren selbst anlegt. Jeder Sensor liest seinen Wert vom Telemetrie-Topic und seine Verfügbarkeit vom Status-Topic (ein Sensor wird etwa 30 Sekunden, nachdem der Hub aufhört zu senden, unavailable).

• Jeder Messpunkt: Strom (A), Leistung (W), Blindleistung (var), Leistungsfaktor, Energie ein und Energie aus (Wh, gesamt und heute).
• Der Hub: Netzleistung (W) und Frequenz (Hz).
• Der Spannungsbus: Spannung (V).

Die Energiesensoren (total_increasing, Wh) gehen direkt ins Energie-Dashboard; siehe Integrations.

Wenn Sie einen Punkt löschen (oder die Zuordnung aufheben), entfernt der Hub seine Discovery-Nachrichten, und Home Assistant entfernt die zugehörigen Entitäten. Das funktioniert nur, solange der Hub mit dem Broker verbunden ist. Löschen Sie einen Punkt, während MQTT aus ist oder der Broker nicht erreichbar ist, bleiben seine Entitäten in Home Assistant als unavailable stehen: Entfernen Sie das Gerät dann von Hand (Settings → Devices & services → MQTT, das Gerät, Delete).

Befehle

Veröffentlichen Sie einen JSON-Befehl auf rbgrid/<mac>/cmd mit einer id Ihrer Wahl. Die Antwort kommt auf rbgrid/<mac>/cmd/resp mit derselben id. Mehrere Clients können cmd/resp teilen, ordnen Sie Antworten daher über die id zu.

Daten lesen:

{"cmd": "get", "section": "summary", "unit": "0x0100", "period": "day", "id": "q1"}

section kann system, telemetry (Einstellungen), telemetry_data (der Live-Frame), sensors, units, tariff, schema, summary (mit unit, period = hour|day|week|month|year, optional from/to als Unix-Zeit) oder economics (mit unit) sein.

Verlauf lesen:

{"cmd": "history", "unit": "0x0100", "period": "hour", "type": "energy", "offset": 0, "limit": 50, "id": "h1"}

type ist electrical, energy, economics, quality oder direction; limit beträgt höchstens 720. Die Antwort ist dasselbe JSON wie GET /api/v1/history.

Tarif setzen:

{"cmd": "set", "section": "tariff", "data": { "...": "the same body as the HTTP tariff call" }, "token": "<admin token>", "id": "t1"}

Das token ist erforderlich, sobald auf dem Hub ein Admin-Token gesetzt ist. Denken Sie daran, dass es für alle sichtbar ist, die cmd abonniert haben.

Eine erfolgreiche Antwort ist dasselbe JSON wie beim passenden HTTP-Endpunkt. Ein Fehler sieht so aus:

{"type": "cmd_ack", "data": {"cmd": "frobnicate", "result": "error", "message": "unknown cmd (use 'get' / 'set' / 'history')"}, "id": "q2"}

Identifizieren Sie Hubs über <mac> im Topic: Die device_id in den Antworten ist auf jedem Hub gleich.

Daten lesen ohne Token in der URL

Ab v1.1.7 brauchen MQTT-Lesezugriffe das read-Token, wenn auf dem Hub Read- und Admin-Token gesetzt sind, genau wie HTTP-Lesezugriffe: cmd get und history werden ohne es abgelehnt. Für einen Browser-Client, der kein Token in der Adresse tragen soll, liefert POST /api/v1/ws-ticket ein Einmal-Ticket, das 30 Sekunden gültig ist. → Settings → Security

Fehlerbehebung

Auf dem Broker kommt nichts an

• Prüfen Sie, ob Broker-Adresse, Port, Benutzername und Passwort stimmen und ob Sie den Hub nach dem Speichern neu gestartet haben.
• Der Hub muss in Ihrem Heim-WLAN sein; im reinen Access-Point-Betrieb startet MQTT nicht.
• Prüfen Sie rbgrid/<mac>/status: online bedeutet, dass der Hub verbunden ist.

Home Assistant zeigt die Sensoren als unavailable

• Der Hub sendet nicht: Prüfen Sie das Status-Topic und die Verbindung zum Broker. Die Sensoren kommen zurück, sobald wieder Frames eintreffen.