MQTT-Anbindung

Alle Aqua-Scope WLAN-Geräte unterstützen MQTT zur Integration in Smart-Home-Systeme, eigene Dashboards oder Automatisierungsplattformen wie Home Assistant, Node-RED oder ioBroker.

Home Assistant Nutzer

Wenn Sie Home Assistant verwenden, folgen Sie der Schritt-für-Schritt-Anleitung Home Assistant Integration – diese richtet MQTT-Broker, Benutzer und Discovery automatisch korrekt ein.

MQTT aktivieren

MQTT kann auf zwei Wegen aktiviert werden:

Beim Erstsetup (Konfigurationsseite)

Während der WLAN-Einrichtung können Sie unter „Advanced" die MQTT-Verbindungsdaten direkt eingeben.

Nachträglich über die App

1. Öffnen Sie die Aqua-Scope App
2. Wählen Sie das Gerät aus
3. Navigieren Sie zu Konfiguration → Kommunikationsoptionen
4. Tragen Sie die MQTT-Verbindungsdaten ein

Konfigurationsparameter

Parameter	Beschreibung
server	Hostname oder IP-Adresse des MQTT-Brokers
port	Port des Brokers (Standard: 1883, TLS: 8883)
login	Benutzername (optional)
password	Passwort (optional)
enable	Dienst aktivieren (1) oder deaktivieren (0)

Beispiel JSON-Downlink zur MQTT-Konfiguration:

{
  "mqtt": {
    "enable": "1",
    "server": "mein-broker.example.com",
    "port": 1883,
    "login": "benutzername",
    "password": "passwort"
  }
}

MQTT über TLS

Aqua-Scope Geräte unterstützen MQTT über TLS für verschlüsselte Verbindungen. Verwenden Sie Port 8883 (oder den von Ihrem Broker konfigurierten TLS-Port). Die Geräte validieren das Server-Zertifikat automatisch.

MQTT Topics

Alle Topics verwenden die 8-stellige Geräte-ID (auf dem Gerät aufgedruckt). Beispiel mit Geräte-ID 12345678:

Topic	Richtung	Beschreibung
/AQS/12345678/stat	Gerät → Broker	Regelmäßige Statusmeldungen
/AQS/12345678/alarm	Gerät → Broker	Alarmmeldungen
/AQS/12345678/cmnd	Broker → Gerät	Steuerbefehle an das Gerät

Nachrichtenformat

Alle MQTT-Nachrichten verwenden JSON. Die Werte entsprechen dem gleichen Format wie beim JSON-Webhook-Dienst.

Statusmeldung (stat)

Beispiel einer regelmäßigen Statusmeldung:

{
  "uptime": 12345,
  "temperature": 22.5,
  "pressure": 3200,
  "battery": 3.1
}

Die enthaltenen Felder variieren je nach Gerätetyp (z.B. rainlevel beim Regenmesser, pressure beim Drucksensor).

Alarmmeldung (alarm)

{
  "alarm": "flood",
  "state": 1,
  "source": 0,
  "value": 0
}

Feld	Beschreibung
alarm	Alarmtyp (z.B. flood, overpressure, underpressure, temperature)
state	1 = Alarm aktiv, 0 = Alarm gelöscht
source	0 = Hauptgerät, 1 oder höher = Untergerät (z.B. angelernter Flutsensor oder Motor)
value	Aktueller Sensorwert, der den Alarm ausgelöst hat (z.B. Druck in mBar bei Unterdruck-Alarm, Temperatur bei Frost-Alarm). Nicht bei allen Alarmtypen vorhanden.

Steuerbefehle (cmnd)

Beispiel – Ventil schließen:

{"valve": "0"}

Beispiel – Ventil öffnen:

{"valve": "100"}

Test-Werkzeug: MQTT-Nachrichten live mitlesen

Online-Tester

io.aqua-scope.com/mqtt – kostenloses Browser-Werkzeug, das sich mit einem öffentlichen MQTT-Broker verbindet und alle Nachrichten eines Aqua-Scope Gerätes in Echtzeit anzeigt. Keine Installation, keine Anmeldung.

Das Werkzeug ist nützlich, um

• vor der Einrichtung eines eigenen Brokers zu prüfen, ob das Gerät überhaupt MQTT-Nachrichten sendet und wie Topics und JSON-Payloads tatsächlich aussehen,
• bei Problemen mit dem eigenen Broker Gerät und Broker unabhängig voneinander zu testen – zeigt das Werkzeug Nachrichten an, liegt der Fehler nicht am Gerät,
• die Home-Assistant-Discovery-Nachrichten (Topic homeassistant/.../config) zu inspizieren, die das Gerät beim Aktivieren des Home-Assistant-Supports einmalig sendet,
• Steuerbefehle und Alarm-Payloads vor dem Übergang in den Produktivbetrieb zu dokumentieren.

Funktionsumfang

Nach dem Öffnen der Seite wählen Sie einen von zwei öffentlichen, anonym erreichbaren MQTT-Brokern aus:

Broker	Host	Port
HiveMQ Public	broker.hivemq.com	1883
EMQX Public	broker.emqx.io	1883

Zusätzlich wählbar sind:

• Geräte-ID – die 8-stellige ID des Gerätes (auf dem Gerät aufgedruckt)
• Topic-Präfix – Standard AQS, kann bei abweichenden Konfigurationen angepasst werden
• Kanal „Gerät" – abonniert AQS/<ID>/# (Status, Alarme, Befehle)
• Kanal „Home Assistant Config" – abonniert homeassistant/+/<ID>_*/config (Discovery-Nachrichten)

Nach dem Klick auf Verbinden erscheinen eintreffende Nachrichten chronologisch im Log, jeweils mit Zeitstempel, vollständigem Topic und formatiertem JSON-Payload. Ein Zähler zeigt die Gesamtzahl der empfangenen Nachrichten.

Vorgehen

1. In der Aqua-Scope App unter Konfiguration → Kommunikationsoptionen einen der beiden Broker als MQTT-Server eintragen (Benutzername und Passwort leer lassen) und speichern.
2. io.aqua-scope.com/mqtt öffnen, denselben Broker auswählen, die 8-stellige Geräte-ID eingeben und auf Verbinden klicken.
3. Nach wenigen Sekunden erscheinen Statusmeldungen (/AQS/<ID>/stat) und – sofern ausgelöst – Alarmnachrichten (/AQS/<ID>/alarm) mit vollständigem Topic und JSON-Payload.
4. Nach dem Test die MQTT-Server-Einstellung in der App wieder auf den produktiven Broker zurückstellen.

Werden Nachrichten angezeigt, arbeitet die MQTT-Seite des Gerätes einwandfrei; das Debugging kann sich anschließend auf den eigenen Broker beschränken. Kommt gar nichts an, prüfen Sie WLAN-Verbindung, Uhrzeit und Firewall-Regeln am Gerät.

Quellcode einsehen und herunterladen

Das Werkzeug besteht aus einer einzigen, in sich geschlossenen HTML-Datei mit eingebettetem JavaScript – ohne Build-Prozess, Tracker oder Analytics. Der komplette Quellcode kann daher direkt im Browser überprüft werden:

• Im Browser: Strg+U (Windows/Linux) bzw. Cmd+Alt+U (macOS) öffnet die Quelltextansicht.
• Herunterladen: Rechtsklick → „Seite speichern unter…" sichert die vollständige Datei lokal.
• Per Kommandozeile: curl -O https://io.aqua-scope.com/mqtt

Die lokal gespeicherte Datei ist voll funktionsfähig – sie kann in jedem Browser geöffnet werden und verbindet sich dann unverändert mit dem gewählten öffentlichen Broker. So lässt sich bei Bedarf prüfen, welche Daten das Werkzeug sendet, empfängt und darstellt.

Öffentliche Broker – nur zum Testen

broker.hivemq.com und broker.emqx.io sind für jedermann sichtbar – Statuswerte, Alarme und Ventilbefehle sind in diesem Betriebsmodus öffentlich mitlesbar. Verwenden Sie sie ausschließlich zum Testen, niemals im Dauerbetrieb.

Unterstützte Geräte

MQTT wird von allen WLAN-fähigen Aqua-Scope Geräten unterstützt:

• AQMWIE01 – Ultraschall-Durchflussmesser
• AQSWIE02 / AQXWIE02 – Leckageschutz-Monitor
• RANWIE01 – Regenmesser
• CLPWIE01 – Pipe Clip
• KFRWIE01 – KFR-Motor (WLAN)
• PREWIE02 – Drucksensor
• MCLWIE01 – WLAN-Konnektor