MQTT

Werte über MQTT mitlesen, Geräte schalten und Szenen ausführen

Der Controller betreibt einen eigenen MQTT-Broker und ist selbst daran angemeldet. Über ihn veröffentlicht er jede Wertänderung seiner Geräte und nimmt Schaltbefehle und Szenenaufrufe entgegen. Ein fremdes System braucht dafür nur einen MQTT-Client, keine Kenntnis der Socket.io-API.

Den Broker schalten Sie in der Konfigurationsoberfläche ein, dort legen Sie auch den Zugang für Ihren Client fest: MQTT im Integratoren-Handbuch. Seit Version 3.0.0 verwendet der Controller ausschließlich seinen eigenen Broker; ein externer Broker lässt sich nicht mehr einstellen.

DANGER

MQTT kennt keine Benutzerrechte.

Wer am Broker schreiben darf, kann jedes Gerät schalten und jede Szene ausführen. Die Raum- und Szenenrechte der nomos Benutzer gelten über MQTT nicht.

• Betreiben Sie den Broker immer mit Anmeldung. Ohne Anmeldung meldet die Sicherheitsprüfung des Controllers CVE-24-0012 „MQTT Broker hat keine Authentifizierung konfiguriert“.
• Geben Sie die Zugangsdaten nur Systemen, denen Sie wie einem Administrator vertrauen.
• Der Broker lauscht unverschlüsselt auf Port 1883. Nutzen Sie ihn nur im eigenen, vertrauenswürdigen Netz.

Verbindung

Adresse	mqtt://<controller-ip>:1883
Anmeldung	Benutzername und Kennwort aus den MQTT-Einstellungen
Verschlüsselung	keine (kein TLS)

Die Adresse für Ihren Client zeigt die Konfigurationsoberfläche als „Broker-URL“. Per API liefert sie getMQTTStatus im Feld clientBrokerUrl, zusammen mit den drei Topic-Präfixen und dem Verbindungsstatus des Controllers:

curl -s -X POST http://<controller-ip>/api/v1/getMQTTStatus \
  -H 'auth-username: <benutzer>' -H 'auth-password: <kennwort>'

{"statusTopic":"nomos/status","subscriberTopic":"nomos/in","publisherTopic":"nomos/out",
 "brokerUrl":"mqtt://127.0.0.1:1883","clientBrokerUrl":"mqtt://192.168.0.199:1883",
 "status":"Connected","connected":true}

brokerUrl ist die Adresse, über die sich der Controller selbst verbindet; für Ihren Client gilt clientBrokerUrl. Wie Sie sich bei der HTTP-API anmelden, steht unter HTTP-API.

Topics

Jedes Topic enthält die Seriennummer des Controllers (SID), zum Beispiel NS123456789. Sie steht in jeder Komponente aus getAllComponents im Feld sid. CID und Property-Namen erklärt das Datenmodell.

Richtung	Topic	Inhalt
Controller → Client	nomos/out/<SID>/component/<cid>/<property>	neuer Wert als Text
Client → Controller	nomos/in/<SID>/component/<cid>/<property>	Wert, der gesetzt wird
Client → Controller	nomos/in/<SID>/scene/<id>	beliebig, wird nicht ausgewertet
Controller → Client	nomos/status/<SID>	online oder offline

Der Controller sendet mit QoS 0 und ohne Retain-Flag. Ein Client, der sich später anmeldet, bekommt also keinen letzten Stand, sondern nur die Änderungen ab seiner Anmeldung. Den aktuellen Stand aller Werte holen Sie einmal über die API, zum Beispiel mit getAllComponents.

Werte mitlesen

Auf nomos/out/<SID>/component/<cid>/<property> erscheint jede Änderung eines Werts, etwa state, level oder temperature. Der Wert ist Text: true/false bei Schaltzuständen, Zahlen wie 21.5. Werte mit Einheit kommen in den Einheiten, die in den Systemeinstellungen gewählt sind, wie in der App.

Werte setzen

Eine Nachricht auf nomos/in/<SID>/component/<cid>/<property> setzt die Property wie componentUpdate. Der Inhalt wird als JSON gelesen, wenn das gelingt (true, 42, "text"), sonst als Text. Welche Properties eine Komponente annimmt und welche Werte, steht in ihrer Beschreibung aus getAllComponents.

Eine Rückmeldung gibt es nicht. Ob der Befehl angekommen ist, sehen Sie am geänderten Wert auf nomos/out/…. Nachrichten mit fremder SID oder unvollständigem Topic verwirft der Controller ohne Antwort.

Szenen ausführen

Eine Nachricht auf nomos/in/<SID>/scene/<id> führt die Szene mit dieser ID aus. Der Inhalt der Nachricht spielt keine Rolle. Die IDs liefert getScenes.

Status des Controllers

Beim Verbinden veröffentlicht der Controller online auf nomos/status/<SID>. offline ist als Last Will hinterlegt: Der Broker sendet es, wenn die Verbindung des Controllers abreißt. Beendet der Controller die Verbindung geordnet, etwa beim Ausschalten des Skills, kommt kein offline. Da beide Nachrichten nicht gespeichert werden, eignet sich das Topic nur für Clients, die dauerhaft verbunden sind.

Beispiele

Die Beispiele verwenden mosquitto_sub und mosquitto_pub aus den Mosquitto-Clients. Ersetzen Sie Adresse, Zugangsdaten, SID und CID durch Ihre eigenen.

Alle Werte und den Status mitlesen:

mosquitto_sub -h <controller-ip> -u <mqtt-benutzer> -P <mqtt-kennwort> -v \
  -t 'nomos/out/<SID>/#' -t 'nomos/status/<SID>'

Ein Gerät einschalten und wieder ausschalten:

mosquitto_pub -h <controller-ip> -u <mqtt-benutzer> -P <mqtt-kennwort> \
  -t 'nomos/in/<SID>/component/C5/state' -m true
mosquitto_pub -h <controller-ip> -u <mqtt-benutzer> -P <mqtt-kennwort> \
  -t 'nomos/in/<SID>/component/C5/state' -m false

mosquitto_sub zeigt dabei:

nomos/out/NS123456789/component/C5/state true
nomos/out/NS123456789/component/C5/state false

Eine Szene ausführen:

mosquitto_pub -h <controller-ip> -u <mqtt-benutzer> -P <mqtt-kennwort> \
  -t 'nomos/in/<SID>/scene/17' -n

Grenzen

• MQTT kennt nur Komponenten und Szenen. Räume, Automationen, Benutzer und Einstellungen erreichen Sie über die Socket.io- und HTTP-API.
• Es gibt keine Antworten und keine Fehlermeldungen. Brauchen Sie eine Bestätigung, lesen Sie den Wert auf nomos/out/… mit.
• Weitere Topics auf dem Broker, etwa nomos/wiser/…, nomos/zeptrion/… oder die Topics von MQTT-Geräten, gehören zu den Integrationen des Controllers. Sie sind keine Schnittstelle für eigene Anwendungen.