Homebridge MQTT: MQTT-Geräte in Apple Home einbinden

Mit der Homebridge-MQTT-Integration steuern Sie selbstgebaute Sensoren, Relais und Lampen über die Apple-Home-App und Siri, obwohl HomeKit selbst nichts von MQTT weiß. In diesem Tutorial installieren Sie das Plugin mqttthing, ordnen Topics den HomeKit-Merkmalen für einen Temperatursensor, einen Schalter, eine dimmbare Lampe und einen Kontaktsensor zu, verarbeiten JSON-Payloads und verlagern das Setup auf einen privaten TLS-Broker.

Wie Homebridge mit MQTT spricht

Homebridge ist ein Node.js-Server, der HomeKit-Geräte emuliert. Plugins liefern die eigentliche Gerätelogik. Das am weitesten verbreitete MQTT-Plugin, homebridge-mqttthing, lässt Sie ein Gerät in JSON deklarieren und jedes HomeKit-Merkmal einem MQTT-Topic zuordnen: einem get-Topic, das Homebridge für den aktuellen Wert abonniert, und einem set-Topic, auf dem es veröffentlicht, wenn Sie auf eine Kachel tippen oder Siri fragen.

 Apple Home / Siri
        |
   (HomeKit, LAN)
        |
    Homebridge  --  homebridge-mqttthing
        |
   (MQTT over TLS)
        |
   MQTT broker  <-->  ESP32, Tasmota, Zigbee2MQTT, scripts

Da die Geräte ausschließlich mit dem Broker sprechen, können sie in einem anderen Netzwerk oder an einem anderen Standort stehen. Homebridge benötigt nur ausgehenden Zugriff auf den Broker. Wenn Sie zuerst den Hintergrund dieses Musters möchten, erklärt der Artikel darüber, was ein MQTT-Broker macht, Publish und Subscribe in einfachen Worten.

Das Plugin mqttthing installieren

Wenn Sie die Homebridge-UI verwenden (Standard in den offiziellen Images), öffnen Sie Plugins, suchen nach mqttthing und installieren Homebridge Mqttthing. Über die Kommandozeile auf einem Homebridge-Host:

sudo npm install -g homebridge-mqttthing
sudo hb-service restart

Geräte werden im Array accessories der config.json definiert. Die UI enthält einen formularbasierten Editor für das Plugin, doch das rohe JSON ist zum Lernen klarer, daher verwenden die folgenden Beispiele es. Sie können sie unter Config > JSON Config einfügen.

Ein erstes Homebridge-MQTT-Gerät: Temperatursensor

Beginnen Sie mit dem öffentlichen MQTT-Broker, damit Sie alles mitverfolgen können; er ist für Tests und Prototypen gedacht. Wählen Sie eine Zufallszeichenkette (hier h3m8x2), um Ihre Topics auf dem gemeinsam genutzten öffentlichen MQTT-Broker getrennt zu halten.

{
  "accessory": "mqttthing",
  "type": "temperatureSensor",
  "name": "Greenhouse Temperature",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-gh-temp-h3m8x2" },
  "topics": {
    "getCurrentTemperature": "connectmq/demo/h3m8x2/greenhouse/temperature"
  },
  "logMqtt": true
}

Speichern Sie, starten Sie Homebridge neu und veröffentlichen Sie dann einen Messwert:

mosquitto_pub -h broker.connectmq.com -p 1883 -i sim-h3m8x2 \
  -t 'connectmq/demo/h3m8x2/greenhouse/temperature' -m '23.5' -r

Die Kachel in Apple Home aktualisiert sich innerhalb einer Sekunde. Das Flag -r macht die Nachricht retained, sodass nach einem Neustart von Homebridge sofort der letzte Wert zugestellt wird, statt dass die Kachel bis zum nächsten Messwert „Keine Antwort“ anzeigt.

Schalter und Lampen mit Befehlen

Steuerbare Geräte brauchen sowohl ein get- als auch ein set-Topic. Getrennte Topics für Befehle und bestätigten Zustand sind gute Praxis: Homebridge veröffentlicht die Anfrage, das Gerät handelt, und das Gerät meldet seinen tatsächlichen Zustand zurück.

{
  "accessory": "mqttthing",
  "type": "switch",
  "name": "Vent Fan",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-fan-h3m8x2" },
  "topics": {
    "getOn": "connectmq/demo/h3m8x2/greenhouse/fan/state",
    "setOn": "connectmq/demo/h3m8x2/greenhouse/fan/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Eine dimmbare Lampe ergänzt ein Helligkeitsmerkmal:

{
  "accessory": "mqttthing",
  "type": "lightbulb",
  "name": "Grow Light",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-light-h3m8x2" },
  "topics": {
    "getOn": "connectmq/demo/h3m8x2/greenhouse/light/state",
    "setOn": "connectmq/demo/h3m8x2/greenhouse/light/set",
    "getBrightness": "connectmq/demo/h3m8x2/greenhouse/light/brightness",
    "setBrightness": "connectmq/demo/h3m8x2/greenhouse/light/brightness/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Beobachten Sie, was Homebridge sendet, während Sie auf die Kacheln tippen:

mosquitto_sub -h broker.connectmq.com -p 1883 -i mon-h3m8x2 \
  -t 'connectmq/demo/h3m8x2/greenhouse/#' -v

JSON-Payloads verarbeiten

Viele Geräte veröffentlichen ein JSON-Dokument mit mehreren Werten statt eines Topics pro Wert. mqttthing akzeptiert ein Topic-Objekt mit einer apply-Funktion, einem kurzen JavaScript-Rumpf, der message erhält und den zu verwendenden Wert zurückgibt.

{
  "accessory": "mqttthing",
  "type": "contactSensor",
  "name": "Greenhouse Door",
  "url": "mqtt://broker.connectmq.com:1883",
  "mqttOptions": { "clientId": "hb-door-h3m8x2" },
  "topics": {
    "getContactSensorState": {
      "topic": "connectmq/demo/h3m8x2/greenhouse/telemetry",
      "apply": "return JSON.parse(message).door === 'open' ? 1 : 0;"
    }
  }
}

Der Kontaktsensor von HomeKit verwendet 0 für erkannt (geschlossen) und 1 für nicht erkannt (offen), deshalb bildet die Funktion open auf 1 ab. Dieselbe Technik funktioniert auf set-Topics, um einen Befehl in JSON zu verpacken, zum Beispiel "apply": "return JSON.stringify({state: message});".

Gängige Gerätetypen zuordnen

Das Plugin unterstützt viele weitere Typen, darunter Garagentore, Thermostate, Ventilatoren und Jalousien. Jeder hat eigene Merkmalsnamen; die README des Plugins listet sie alle auf.

Verbindungsanzahl und Client-IDs

Jedes mqttthing-Gerät öffnet eine eigene MQTT-Verbindung. Zehn Geräte bedeuten also zehn Clients am Broker, die jeweils eine eindeutige Client-ID benötigen. Daraus folgen zwei Konsequenzen:

1. Geben Sie jedem Gerät eine eigene clientId in mqttOptions. Doppelte IDs führen dazu, dass der Broker die frühere Sitzung trennt, und Geräte wechseln ständig zwischen antwortend und nicht antwortend.
2. Rechnen Sie die Verbindungen gegen Ihren Plan. Der kostenlose Serverless-Plan von ConnectMQ erlaubt bis zu 25 gleichzeitige Verbindungen, was Homebridge plus eine überschaubare Anzahl Geräte abdeckt. Größere Setups passen in den kostenpflichtigen Serverless-Plan mit bis zu 1.000.

Wenn Sie viele Geräte über eine einzige Verbindung brauchen, erwägen Sie, Home Assistant oder Node-RED die Broker-Verbindung übernehmen zu lassen und HomeKit über deren eigene HomeKit-Bridges bereitzustellen.

Produktivbetrieb: TLS und Zugangsdaten

Alles auf dem öffentlichen MQTT-Broker kann jeder lesen, der das Topic errät, und jemand könnte auch auf Ihren set-Topics veröffentlichen. Bevor Sie echte Geräte steuern, legen Sie einen privaten Broker an und stellen jedes Gerät auf TLS um:

{
  "accessory": "mqttthing",
  "type": "switch",
  "name": "Vent Fan",
  "url": "mqtts://broker.connectmq.com:8883",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD",
  "mqttOptions": { "clientId": "YOUR_CLIENT_ID" },
  "topics": {
    "getOn": "site1/greenhouse/fan/state",
    "setOn": "site1/greenhouse/fan/set"
  },
  "onValue": "ON",
  "offValue": "OFF"
}

Node.js vertraut der von ConnectMQ verwendeten Let's-Encrypt-Kette von Haus aus, daher ist keine CA-Datei erforderlich. Bei ConnectMQ sind Client-IDs an die im Portal ausgegebenen Zugangsdaten gebunden; wenn Sie mehrere Verbindungen brauchen, geben Sie daher pro Gerätegruppe einen eigenen Satz Zugangsdaten aus und halten fest, welche ID wohin gehört.

mqttthing als Child Bridge betreiben

Homebridge kann ein Plugin als Child Bridge ausführen: als separaten Prozess mit eigener HomeKit-Kopplung. Die Aktivierung für mqttthing (in den Plugin-Einstellungen unter Bridge Settings) hat zwei praktische Vorteile. Ein Absturz oder eine fehlerhafte Gerätedefinition reißt nicht mehr alle anderen Plugins mit, und ein Neustart der Child Bridge nach dem Bearbeiten von Topics geht schneller als ein Neustart von ganz Homebridge. Sie koppeln die Child Bridge einmal in der Home-App, und später hinzugefügte Geräte erscheinen automatisch.

Es lohnt sich außerdem, von jedem Gerät ein retained Availability-Topic mit einem Last Will offline zu veröffentlichen. mqttthing kann es über das Topic getOnline zusammen mit onlineValue und offlineValue nutzen, sodass Apple Home ein Gerät als nicht antwortend anzeigt, wenn es wirklich offline ist, statt einen veralteten Wert darzustellen.

Fehlersuche bei Homebridge MQTT

• Gerät zeigt „Keine Antwort“. Seit dem Start von Homebridge ist auf dem get-Topic kein Wert angekommen. Veröffentlichen Sie den Zustand von den Geräten retained oder prüfen Sie das Topic mit logMqtt: true auf Tippfehler.
• Kachel schaltet von selbst zurück. Das Gerät veröffentlicht seinen neuen Zustand nicht auf dem get-Topic oder einen Wert, der nicht zu onValue passt.
• Ständige Reconnect-Meldungen im Log. Doppelte Client-IDs oder falsche Zugangsdaten. Suchen Sie im Homebridge-Log nach Connection refused und dem Grund.
• Siri meldet, das Gerät antworte nicht, aber die App funktioniert. Meist ein Problem der HomeKit-Steuerzentrale (Apple TV oder HomePod) und nicht von MQTT; prüfen Sie, ob die Steuerzentrale Homebridge im LAN erreicht.

Wie es weitergeht

Homebridge liefert Ihnen die Apple-Seite; die Geräte müssen trotzdem sinnvolle Topics veröffentlichen. Der Leitfaden zu ESPHome MQTT zeigt, wie Sie Sensoren bauen, die Zustände veröffentlichen und Befehle annehmen, und der Artikel zur Smart-Home-MQTT-Topic-Struktur hilft Ihnen, Topics zu entwerfen, die überschaubar bleiben. Läuft Home Assistant neben Homebridge, lesen Sie Home Assistant mit einem externen MQTT-Broker. Für den größeren Zusammenhang aus Geräten und Logik lesen Sie den Leitfaden zur IoT-Automatisierung, und um zu verstehen, warum ein verwalteter MQTT-Broker für den Fernzugriff besser ist als ein Broker auf dem Homebridge-Pi, vergleichen Sie dort die Optionen.

Homebridge mit ConnectMQ verbinden

ConnectMQ gibt Homebridge einen privaten, per TLS gesicherten Broker, der aus jedem Netzwerk erreichbar ist, mit einem Live-Topic-Explorer, um Ihre Geräte schon beim Konfigurieren zu debuggen. Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Broker, ganz ohne Kreditkarte, und fügen Sie die generierten Zugangsdaten in Ihre mqttthing-Geräte ein.

Häufig gestellte Fragen

Unterstützt HomeKit MQTT nativ?

Nein. HomeKit verwendet ein eigenes Geräteprotokoll, daher brauchen Sie eine Bridge wie Homebridge mit einem MQTT-Plugin, die zwischen beiden übersetzt.

Kann ich Homebridge-MQTT-Geräte steuern, wenn ich nicht zu Hause bin?

Ja, wie gewohnt über eine HomeKit-Steuerzentrale. Da die Geräte mit einem Cloud-Broker sprechen, können sie sich sogar an einem anderen Standort als Homebridge befinden.

Warum zeigen meine Sensoren nach einem Neustart „Keine Antwort“?

Homebridge hat noch keinen Wert empfangen. Veröffentlichen Sie Zustandsnachrichten mit dem Retain-Flag, damit der Broker den letzten Wert zustellt, sobald Homebridge abonniert.

Ist mqttthing das einzige Homebridge-MQTT-Plugin?

Nein, aber das universellste. Andere Plugins zielen auf bestimmte Ökosysteme wie Zigbee2MQTT oder Tasmota und können einfacher sein, wenn Sie nur solche Geräte verwenden.