Ghid de automatizare MQTT

Automatizările MQTT vă permit să publicați automat datele de sănătate pe un broker MQTT. Este potrivit pentru integrarea cu platforme IoT, sisteme de domotică sau orice serviciu care suportă mesagerie MQTT.

Prezentare generală

Automatizările MQTT publică datele de sănătate ca mesaje JSON către un topic MQTT specificat pe un broker MQTT. Datele sunt trimise ori de câte ori rulează automatizarea, conform setărilor de ritm de sincronizare.

Cazuri de utilizare:

• Integrare cu platforme IoT (Home Assistant, OpenHAB etc.)
• Publicarea datelor de sănătate pe panouri de control bazate pe MQTT
• Sisteme de monitorizare a sănătății în timp (aproximativ) real
• Integrări personalizate de domotică
• Platforme de înregistrare și analiză a datelor

Caracteristici principale:

• Doar format JSON (optimizat pentru MQTT)
• Suportă conexiuni autentificate și anonime
• Structură de topic configurabilă
• Gestionare Client ID
• Autentificare opțională cu utilizator și parolă

Limitări

• Acces la datele de sănătate: Aplicațiilor nu li se permite accesul la datele de sănătate cât timp iPhone-ul este blocat. Automatizările vor rula doar în perioadele în care dispozitivul este deblocat. Aceasta este o limitare impusă de Apple care nu poate fi ocolită. Mai multe informații

• Procesare în fundal: iOS limitează procesarea în fundal pentru a prelungi durata de viață a bateriei. Automatizările se bazează pe Reîmprospătare aplicație în fundal și s-ar putea să nu ruleze imediat dacă:

  • Reîmprospătarea în fundal este dezactivată pentru aplicație
  • Dispozitivul este în modul de economisire a energiei
  • Dispozitivul a fost inactiv perioade îndelungate
  • Resursele sistemului sunt limitate
  • Mai multe aplicații concurează pentru timp de execuție în fundal

• Doar format JSON (nu poate fi schimbat)

• Necesită un broker MQTT (local sau în cloud)

Cerințe preliminare

• Un broker MQTT (ex.: Mosquitto, HiveMQ, AWS IoT Core etc.)
• Conectivitate la rețea către brokerul MQTT
• Adresă IP sau hostname al brokerului
• Număr de port
• Opțional: utilizator și parolă dacă brokerul cere autentificare

Configurare

Deschideți ecranul Exporturi automate din navigarea principală, apoi atingeți „Automatizare nouă” și selectați „MQTT” ca tip de automatizare.

Nume automatizare

Introduceți un nume descriptiv pentru automatizare (ex.: „Home Assistant MQTT”, „Broker MQTT cloud”).

Notificări

Configurați când doriți să primiți notificări:

• Notificare la actualizarea cache-ului — primiți o notificare când datele din cache se actualizează
• Notificare la rulare — primiți o notificare de fiecare dată când automatizarea publică date

Configurare broker

Adresă IP

Introduceți adresa IP sau hostname-ul brokerului MQTT.

Exemple:

• 192.168.1.100 (adresă IP locală)
• mqtt.example.com (hostname)
• broker.hivemq.com (broker MQTT cloud)
• localhost (dacă rulează pe același dispozitiv — nerecomandat pe iOS)

Notă: Folosiți adrese IP pentru brokeri locali din rețea sau hostname-uri pentru brokeri în cloud. Asigurați-vă că brokerul este accesibil de pe dispozitiv.

Port

Introduceți numărul de port al brokerului MQTT.

Notă: Portul implicit este 1883.

Topic

Introduceți topicul MQTT unde vor fi publicate datele de sănătate. Acesta este topicul pe care îl vor folosi abonații pentru a primi datele de sănătate.

Exemple de topicuri:

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

Bune practici pentru topicuri:

• Folosiți bara oblică (/) pentru ierarhii de topicuri
• Folosiți nume descriptive care indică tipul de date
• Evitați spațiile și caracterele speciale
• Luați în calcul includerea numelui automatizării dacă aveți mai multe automatizări

Notă: Numele topicului ține cont de majuscule și minuscule. Asigurați-vă că abonații folosesc exact același nume de topic.

Client ID

Introduceți un Client ID unic pentru această conexiune MQTT. Acesta identifică dispozitivul către brokerul MQTT.

Exemple de Client ID:

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

Utilizator (opțional)

Introduceți utilizatorul pentru autentificarea la brokerul MQTT. Lăsați gol dacă brokerul nu cere autentificare.

Parolă (opțional)

Introduceți parola pentru autentificarea la brokerul MQTT. Lăsați gol dacă brokerul nu cere autentificare.

Setări tip de date

Tip de date

Selectați ce tip de date de sănătate exportați:

• Metrici de sănătate — pași, puls, somn și alte măsurători de sănătate
• Antrenamente — activități de exercițiu și fitness
• Simptome — simptome și afecțiuni de sănătate
• ECG — înregistrări electrocardiografice
• Notificări privind pulsul — evenimente de puls ridicat sau scăzut
• Stare de spirit — intrări legate de dispoziție și stare mentală (iOS 18.0+)
• Monitorizarea ciclului — date despre ciclul menstrual și sănătatea reproductivă
• Medicamente — jurnale de medicamente și aderență (iOS 26.0+)

Configurare metrici de sănătate

Când este selectat Metrici de sănătate:

Selectare metrici de sănătate — alegeți ce metrici specifice includeți. Puteți selecta toate metricile disponibile sau doar anumite.

Sfat: Selectarea doar a metricilor de care aveți nevoie reduce dimensiunea mesajului și timpul de procesare.

Surse preferate — configurați ce surse de date au prioritate când mai multe surse oferă aceeași metrică.

Configurare antrenamente

Când sunt selectate Antrenamente:

Includeți date de traseu — activați pentru a include traseele pentru antrenamentele care au date de locație.

Includeți metrici din antrenament — activați pentru a include metrici de sănătate colectate în timpul antrenamentelor (puls, calorii etc.).

Grupare temporală (metrici antrenament) — când folosiți versiunea de export 2 și Includeți metrici din antrenament este activat:

• Minute — grupează metricile antrenamentului pe minut
• Secunde — grupează metricile antrenamentului pe secundă

Setări export

Format export

Notă: Automatizările MQTT suportă doar formatul JSON. Această setare nu poate fi schimbată și este setată automat la JSON.

Versiune export

Selectați o versiune de export pentru datele de antrenament:

• Versiunea 1 — format moștenit
• Versiunea 2 — format actual, cu date de antrenament îmbunătățite

Notă: Versiunea de export afectează în principal structura datelor de antrenament dacă exportați antrenamente.

Interval de date

Selectați când trebuie exportate datele:

• Implicit — sincronizează datele pentru întreaga zi anterioară, plus date până la data și ora curente
• De la ultima sincronizare — la fiecare sincronizare, exportă toate datele de la ultima rulare a exportului până la data și ora curente
• Astăzi — sincronizează toate datele pentru ziua curentă până la momentul curent
• Ieri — sincronizează toate datele pentru întreaga zi anterioară
• Ultimele 7 zile — sincronizează datele pentru întregul interval de șapte zile anterioare

Rezumat date

Când folosiți formatul JSON cu tipul de date Metrici de sănătate, activați sau dezactivați Rezumat date.

• Activat — oferă rezumate agregate ale datelor (implicit)
• Dezactivat — oferă date dezagregate pe cât posibil, cu puncte individuale de date

Grupare temporală

Când Rezumat date este activat, selectați modul în care trebuie agregate datele.

Rezumat date

Comutați Rezumat date activat sau dezactivat pentru Metrici de sănătate.

• Activat — oferă rezumate agregate ale datelor (implicit)
• Dezactivat — oferă date dezagregate pe cât posibil

Notă: Această setare se aplică doar tipului de date Metrici de sănătate.

Ritm de sincronizare

Configurați cât de des ar trebui să publice automatizarea date pe MQTT:

Selectați un număr și un interval.

Testare și verificare

Utilizarea unui client MQTT

Pentru a verifica că mesajele sunt publicate:

1. Configurați un client MQTT
2. Conectați-vă la brokerul MQTT folosind aceleași credențiale
3. Abonați-vă la topic
4. Declanșați un export manual din aplicație
5. Verificați că mesajul apare în clientul MQTT

Format mesaj

Mesajele MQTT sunt publicate ca JSON. Payload-ul mesajului urmează formatul JSON standard de export:

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

Mesajul este publicat cu:

• Topic: conform configurării din automatizare
• QoS: livrare cel mult o dată
• Retain: mesajele nu sunt păstrate
• Payload: șir JSON care conține datele de sănătate

Depanare

Probleme frecvente

Eșecuri de conexiune

• Verificați că adresa IP / hostname-ul brokerului este corectă
• Verificați că portul este corect și că brokerul ascultă pe acel port
• Asigurați-vă că există conectivitate la rețea către broker
• Verificați regulile de firewall care permit conexiuni la broker
• Verificați dacă brokerul cere TLS/SSL

Eșecuri de autentificare

• Verificați că utilizatorul și parola sunt corecte
• Verificați că autentificarea este activată pe broker dacă furnizați credențiale
• Asigurați-vă că utilizatorul are permisiunea de a publica pe topicul specificat

Mesaje neprimite

• Verificați că numele topicului se potrivește exact (ține cont de majuscule/minuscule)
• Verificați că abonații sunt conectați la același broker
• Asigurați-vă că abonații sunt abonați la topicul corect
• Verificați că automatizarea este activată și rulează
• Consultați jurnalele de activitate pentru erori la publicare

Dimensiune mare a mesajului

• Reduceți numărul de metrici de sănătate selectate
• Folosiți opțiuni de agregare mai puțin granulare
• Luați în calcul împărțirea pe mai multe automatizări pentru tipuri diferite de date

Sfaturi și bune practici

1. Sincronizare automată:

   • Încărcați dispozitivul și folosiți iPhone Mirroring
     • Când dispozitivul se încarcă, iOS aplică mai puține restricții asupra performanței, astfel că datele se pot sincroniza mai frecvent
     • Folosind iPhone Mirroring, dispozitivul se comportă la fel ca atunci când ar fi deblocat. Astfel, datele de sănătate sunt accesibile pentru Health Auto Export, pentru a rula acțiuni automate

2. Organizare topicuri:

   • Folosiți structuri ierarhice de topicuri (ex.: health/metrics, health/workouts)
   • Includeți în topicuri identificatori de dispozitiv sau de automatizare
   • Documentați structura topicurilor pentru referință ușoară

3. Dimensiune mesaje:

   • Păstrați mesajele la o dimensiune rezonabilă pentru a evita limitele brokerului MQTT
   • Folosiți o agregare mai puțin granulare pentru a reduce volumul de date
   • Luați în calcul împărțirea seturilor mari de date pe mai multe mesaje

4. Monitorizare:

   • Folosiți jurnalele de activitate din aplicație pentru a urmări reușita publicărilor

5. Brokeri cloud:

   • Când folosiți brokeri MQTT cloud (AWS IoT, HiveMQ Cloud etc.):
     • Respectați cerințele lor specifice de conexiune
     • Verificați limitele de dimensiune și rată ale mesajelor
     • Verificați convențiile de denumire a topicurilor

Vizualizarea jurnalelor de activitate

1. Atingeți Vizualizați jurnalele de activitate pe ecranul de configurare a automatizării.
2. Examinați rulări (grupate, cele mai recente primele) și extindeți evenimentele din fiecare rulare.
3. Distingeți avertismente (de ex., interogare lentă a datelor de sănătate) de erori (eșecuri de conexiune la broker sau de publicare)—consultați Prezentare generală automatizări — Jurnale de activitate.
4. Verificați liniile de publicare reușite și eșuate pentru fiecare rulare.
5. Partajare (bară de instrumente) exportă ZIP-ul diagnostic complet Jurnale de evenimente ale aplicației pentru asistență (la fel ca Setări → Avansat).
6. Ștergere elimină doar istoricul de activitate al acestei automatizări.