MQTT-Automatisierungsanleitung

MQTT-Automatisierungen ermöglichen es Ihnen, Ihre Gesundheitsdaten automatisch an einen MQTT-Broker zu veröffentlichen. Dies ist ideal für die Integration mit IoT-Plattformen, Hausautomationssystemen oder jedem Dienst, der MQTT-Messaging unterstützt.

Übersicht

MQTT-Automatisierungen veröffentlichen Ihre Gesundheitsdaten als JSON-Nachrichten an ein bestimmtes MQTT-Thema auf einem MQTT-Broker. Die Daten werden gesendet, wann immer die Automatisierung gemäß Ihren Synchronisierungsfrequenzeinstellungen ausgeführt wird.

Anwendungsfälle:

• Integration mit IoT-Plattformen (Home Assistant, OpenHAB, etc.)
• Veröffentlichung von Gesundheitsdaten auf MQTT-basierten Dashboards
• Echtzeit-Gesundheitsüberwachungssysteme
• Benutzerdefinierte Hausautomationsintegrationen
• Datenprotokollierungs- und Analyseplattformen

Hauptfunktionen:

• Nur JSON-Format (für MQTT optimiert)
• Unterstützt authentifizierte und anonyme Verbindungen
• Konfigurierbare Themenstruktur
• Client-ID-Verwaltung
• Optionale Benutzername/Passwort-Authentifizierung

Einschränkungen

• Zugriff auf Gesundheitsdaten: Apps dürfen nicht auf Gesundheitsdaten zugreifen, während das iPhone gesperrt ist. Automatisierungen laufen nur, wenn Ihr Gerät entsperrt ist. Das ist eine von Apple auferlegte Einschränkung, die nicht umgangen werden kann. Weitere Informationen

• Hintergrundverarbeitung: iOS begrenzt die Hintergrundverarbeitung, um die Batterielebensdauer zu erhalten. Automatisierungen sind auf Hintergrundaktualisierung der App angewiesen und werden möglicherweise nicht sofort ausgeführt, wenn:

  • Hintergrundaktualisierung der App für die App deaktiviert ist
  • Das Gerät im Energiesparmodus ist
  • Das Gerät über längere Zeiträume inaktiv war
  • Systemressourcen eingeschränkt sind
  • Mehrere Apps um Hintergrundausführungszeit konkurrieren

• Nur JSON-Format (kann nicht geändert werden)

• Erfordert einen MQTT-Broker (lokal oder cloudbasiert)

Voraussetzungen

• Ein MQTT-Broker (z. B. Mosquitto, HiveMQ, AWS IoT Core, etc.)
• Netzwerkverbindung zu Ihrem MQTT-Broker
• Broker-IP-Adresse oder Hostname
• Portnummer
• Optional: Benutzername und Passwort, wenn Ihr Broker eine Authentifizierung erfordert

Konfiguration

Navigieren Sie zum Bildschirm Automatisierte Exporte aus der Hauptnavigation, tippen Sie dann auf "Neue Automatisierung" und wählen Sie "MQTT" als Automatisierungstyp.

Automatisierungsname

Geben Sie einen beschreibenden Namen für Ihre Automatisierung ein (z. B. "Home Assistant MQTT", "Cloud MQTT Broker").

Benachrichtigungen

Konfigurieren Sie, wann Sie Benachrichtigungen erhalten möchten:

• Bei Cache-Aktualisierung benachrichtigen - Erhalten Sie eine Benachrichtigung, wenn zwischengespeicherte Daten aktualisiert werden
• Bei Ausführung benachrichtigen - Erhalten Sie eine Benachrichtigung jedes Mal, wenn die Automatisierung Daten veröffentlicht

Broker-Konfiguration

IP-Adresse

Geben Sie die IP-Adresse oder den Hostname Ihres MQTT-Brokers ein.

Beispiele:

• 192.168.1.100 (lokale IP-Adresse)
• mqtt.example.com (Hostname)
• broker.hivemq.com (Cloud-MQTT-Broker)
• localhost (wenn auf demselben Gerät ausgeführt, nicht empfohlen für iOS)

Hinweis: Verwenden Sie IP-Adressen für lokale Broker in Ihrem Netzwerk oder Hostnames für cloudbasierte Broker. Stellen Sie sicher, dass der Broker von Ihrem Gerät aus erreichbar ist.

Port

Geben Sie die Portnummer für Ihren MQTT-Broker ein.

Hinweis: Der Standardport ist 1883.

Thema

Geben Sie das MQTT-Thema ein, an das Gesundheitsdaten veröffentlicht werden. Dies ist das Thema, das Abonnenten verwenden, um Ihre Gesundheitsdaten zu empfangen.

Themenbeispiele:

• health/data
• home/health/metrics
• user/health/export
• hae/automation-name

Best Practices für Themen:

• Verwenden Sie Schrägstriche (/) zur Erstellung von Themenhierarchien
• Verwenden Sie beschreibende Namen, die den Datentyp angeben
• Vermeiden Sie Leerzeichen und Sonderzeichen
• Erwägen Sie, den Automatisierungsnamen für mehrere Automatisierungen einzubeziehen

Hinweis: Der Themenname ist case-sensitive. Stellen Sie sicher, dass Abonnenten genau denselben Themennamen verwenden.

Client-ID

Geben Sie eine eindeutige Client-ID für diese MQTT-Verbindung ein. Dies identifiziert Ihr Gerät beim MQTT-Broker.

Client-ID-Beispiele:

• health-export-iphone
• hae-client-001
• ios-health-app

Benutzername (Optional)

Geben Sie den Benutzernamen für die MQTT-Broker-Authentifizierung ein. Lassen Sie es leer, wenn Ihr Broker keine Authentifizierung erfordert.

Passwort (Optional)

Geben Sie das Passwort für die MQTT-Broker-Authentifizierung ein. Lassen Sie es leer, wenn Ihr Broker keine Authentifizierung erfordert.

Datentyp-Einstellungen

Datentyp

Wählen Sie aus, welche Art von Gesundheitsdaten exportiert werden sollen:

• Gesundheitsmetriken - Schritte, Herzfrequenz, Schlaf und andere Gesundheitsmessungen
• Workouts - Trainings- und Fitnessaktivitäten
• Symptome - Gesundheitssymptome und -zustände
• EKG - Elektrokardiogramm-Messwerte
• Herzfrequenz-Benachrichtigungen - Hohe/niedrige Herzfrequenzereignisse
• Gemütszustand - Stimmungs- und Geisteszustandseinträge (iOS 18.0+)
• Zyklusverfolgung - Menstruationszyklus- und Reproduktionsgesundheitsdaten
• Medikamente - Medikamentenprotokolle und Einhaltung (iOS 26.0+)

Gesundheitsmetriken-Konfiguration

Wenn Gesundheitsmetriken ausgewählt ist:

Gesundheitsmetriken auswählen - Wählen Sie aus, welche spezifischen Metriken einbezogen werden sollen. Sie können alle verfügbaren Metriken auswählen oder spezifische auswählen.

Tipp: Die Auswahl nur der benötigten Metriken reduziert die Nachrichtengröße und Verarbeitungszeit.

Bevorzugte Quellen - Konfigurieren Sie, welche Datenquellen Priorität haben, wenn mehrere Quellen dieselbe Metrik bereitstellen.

Workout-Konfiguration

Wenn Workouts ausgewählt ist:

Routendaten einbeziehen - Aktivieren Sie, um Routen für Workouts mit Standortdaten einzubeziehen.

Workout-Metriken einbeziehen - Aktivieren Sie, um während Workouts gesammelte Gesundheitsmetriken (Herzfrequenz, Kalorien, etc.) einzubeziehen.

Zeitgruppierung (Workout-Metriken) - Bei Verwendung von Exportversion 2 und aktivierter Option "Workout-Metriken einbeziehen":

• Minuten - Gruppiert Workout-Metriken nach Minute
• Sekunden - Gruppiert Workout-Metriken nach Sekunde

Export-Einstellungen

Exportformat

Hinweis: MQTT-Automatisierungen unterstützen nur das JSON-Format. Diese Einstellung kann nicht geändert werden und ist automatisch auf JSON gesetzt.

Exportversion

Wählen Sie eine Exportversion für Workout-Daten:

• Version 1 - Legacy-Format
• Version 2 - Aktuelles Format mit erweiterten Workout-Daten

Hinweis: Die Exportversion betrifft hauptsächlich die Workout-Datenstruktur, wenn Sie Workouts exportieren.

Datumsbereich

Wählen Sie aus, wann Daten exportiert werden sollen:

• Standard - Synchronisiert Daten für den vollständigen vorherigen Tag plus Daten bis zum aktuellen Datum und zur aktuellen Uhrzeit
• Seit letzter Synchronisierung - Bei jeder Synchronisierung werden alle Daten seit der letzten Ausführung des Exports bis zum aktuellen Datum und zur aktuellen Uhrzeit exportiert
• Heute - Synchronisiert alle Daten für das aktuelle Datum bis zur aktuellen Uhrzeit
• Gestern - Synchronisiert alle Daten für den vollständigen vorherigen Tag
• Letzte 7 Tage - Synchronisiert Daten für die vollständigen vorherigen sieben Tage

Daten zusammenfassen

Wenn JSON-Format mit dem Datentyp Gesundheitsmetriken verwendet wird, aktivieren oder deaktivieren Sie Daten zusammenfassen.

• EIN - Bietet aggregierte Datenzusammenfassungen (Standard)
• AUS - Bietet nach Möglichkeit disaggregierte Daten und zeigt einzelne Datenpunkte an

Zeitgruppierung

Wenn Daten zusammenfassen aktiviert ist, wählen Sie aus, wie Daten aggregiert werden sollen.

Daten zusammenfassen

Aktivieren oder deaktivieren Sie Daten zusammenfassen für Gesundheitsmetriken.

• EIN - Bietet aggregierte Datenzusammenfassungen (Standard)
• AUS - Bietet nach Möglichkeit disaggregierte Daten

Hinweis: Diese Einstellung gilt nur für den Datentyp Gesundheitsmetriken.

Synchronisierungsfrequenz

Konfigurieren Sie, wie oft die Automatisierung Daten an MQTT veröffentlichen soll:

Wählen Sie eine Zahl und ein Intervall.

Tests und Überprüfung

Verwendung eines MQTT-Clients

Um zu überprüfen, ob Nachrichten veröffentlicht werden:

1. Richten Sie einen MQTT-Client ein
2. Verbinden Sie sich mit Ihrem MQTT-Broker mit denselben Anmeldedaten
3. Abonnieren Sie Ihr Thema
4. Lösen Sie einen manuellen Export aus der App aus
5. Überprüfen Sie, ob die Nachricht in Ihrem MQTT-Client erscheint

Nachrichtenformat

MQTT-Nachrichten werden als JSON veröffentlicht. Die Nachrichtennutzlast folgt dem standardmäßigen Export-JSON-Format:

{
  "data": {
    "metrics": [...],
    "workouts": [...],
    ...
  }
}

Die Nachricht wird veröffentlicht mit:

• Thema: Wie in der Automatisierung konfiguriert
• QoS: Höchstens einmalige Zustellung
• Behalten: Nachrichten werden nicht beibehalten
• Nutzlast: JSON-Zeichenkette mit Gesundheitsdaten

Aktivitätsprotokolle anzeigen

1. Tippen Sie auf Aktivitätsprotokolle anzeigen im Automatisierungskonfigurationsbildschirm.
2. Überprüfen Sie Ausführungen (gruppiert, neueste zuerst) und klappen Sie Ereignisse innerhalb jeder Ausführung auf.
3. Unterscheiden Sie Warnungen (z. B. langsame Gesundheitsdatenabfrage) von Fehler (Broker-Verbindungs- oder Veröffentlichungsfehler)—siehe Übersicht zu Automatisierungen — Aktivitätsprotokolle.
4. Prüfen Sie Erfolgs- und Fehlerzeilen der Veröffentlichung für jede Ausführung.
5. Teilen (Symbolleiste) exportiert das vollständige Diagnose-ZIP der App-Ereignisprotokolle für den Support (wie Einstellungen → Erweitert).
6. Löschen entfernt nur den Aktivitätsverlauf dieser Automatisierung.

Fehlerbehebung

Häufige Probleme

Verbindungsfehler

• Überprüfen Sie, ob die Broker-IP-Adresse/der Hostname korrekt ist
• Überprüfen Sie, ob der Port korrekt ist und der Broker auf diesem Port lauscht
• Stellen Sie sicher, dass Netzwerkverbindung zum Broker besteht
• Überprüfen Sie, ob Firewall-Regeln Verbindungen zum Broker zulassen
• Überprüfen Sie, ob der Broker TLS/SSL erfordert

Authentifizierungsfehler

• Überprüfen Sie, ob Benutzername und Passwort korrekt sind
• Überprüfen Sie, ob die Authentifizierung auf Ihrem Broker aktiviert ist, wenn Anmeldedaten bereitgestellt werden
• Stellen Sie sicher, dass der Benutzer die Berechtigung hat, am angegebenen Thema zu veröffentlichen

Nachrichten nicht empfangen

• Überprüfen Sie, ob der Themenname genau übereinstimmt (case-sensitive)
• Überprüfen Sie, ob Abonnenten mit demselben Broker verbunden sind
• Stellen Sie sicher, dass Abonnenten am richtigen Thema abonniert sind
• Überprüfen Sie, ob die Automatisierung aktiviert ist und läuft
• Überprüfen Sie Aktivitätsprotokolle auf Veröffentlichungsfehler

Große Nachrichtengröße

• Reduzieren Sie die Anzahl der ausgewählten Gesundheitsmetriken
• Verwenden Sie weniger granulare Aggregationsoptionen
• Erwägen Sie, in mehrere Automatisierungen für verschiedene Datentypen aufzuteilen

Tipps und Best Practices

1. Automatische Synchronisierung:

   • Laden Sie Ihr Gerät und nutzen Sie iPhone-Spiegelung
     • Beim Laden legt iOS weniger Leistungsbeschränkungen auf, sodass Daten häufiger synchronisiert werden können
     • Mit iPhone-Spiegelung verhält sich das Gerät wie entsperrt. So kann Health Auto Export auf Gesundheitsdaten zugreifen und automatisierte Aktionen ausführen

2. Themenorganisation:

   • Verwenden Sie hierarchische Themenstrukturen (z. B. health/metrics, health/workouts)
   • Fügen Sie Geräte- oder Automatisierungsidentifikatoren in Themen ein
   • Dokumentieren Sie Ihre Themenstruktur zur einfachen Referenz

3. Nachrichtengröße:

   • Halten Sie Nachrichten angemessen groß, um MQTT-Broker-Limits zu vermeiden
   • Verwenden Sie weniger granulare Aggregation, um das Datenvolumen zu reduzieren
   • Erwägen Sie, große Datensätze auf mehrere Nachrichten aufzuteilen

4. Überwachung:

   • Verwenden Sie Aktivitätsprotokolle in der App, um den Veröffentlichungserfolg zu verfolgen

5. Cloud-Broker:

   • Bei Verwendung von Cloud-MQTT-Brokern (AWS IoT, HiveMQ Cloud, etc.):
     • Befolgen Sie ihre spezifischen Verbindungsanforderungen
     • Überprüfen Sie ihre Nachrichtengrößen- und Ratenlimits
     • Überprüfen Sie Themenbenennungskonventionen