Sincronizzare i dati Apple Health con MQTT

Le automazioni MQTT ti consentono di pubblicare automaticamente i tuoi dati sanitari su un broker MQTT. Questo è ideale per l'integrazione con piattaforme IoT, sistemi di automazione domestica o qualsiasi servizio che supporti la messaggistica MQTT.

Panoramica

Le automazioni MQTT pubblicano i tuoi dati sanitari come messaggi JSON su un argomento MQTT specificato su un broker MQTT. I dati vengono inviati ogni volta che l'automazione viene eseguita in base alle impostazioni di frequenza di sincronizzazione.

Casi d'uso:

• Integrazione con piattaforme IoT (Home Assistant, OpenHAB, ecc.)
• Pubblicazione di dati sanitari su dashboard basati su MQTT
• Sistemi di monitoraggio sanitario in tempo reale
• Integrazioni personalizzate di automazione domestica
• Piattaforme di registrazione e analisi dei dati

Caratteristiche principali:

• Solo formato JSON (ottimizzato per MQTT)
• Supporta connessioni autenticate e anonime
• Struttura argomenti configurabile
• Gestione ID client
• Autenticazione opzionale nome utente/password

Limitazioni

• Accesso ai dati sanitari: Le app non sono autorizzate ad accedere ai dati sanitari mentre l'iPhone è bloccato. Le automazioni verranno eseguite solo durante i periodi in cui il dispositivo è sbloccato. Questo può influire sulla freschezza dei dati. Consulta le istruzioni per la sincronizzazione manuale per mantenere i dati aggiornati.

• Elaborazione in background: iOS limita l'elaborazione in background per preservare la durata della batteria. Le automazioni dipendono dall'Aggiornamento app in background e potrebbero non essere eseguite immediatamente se:

  • L'Aggiornamento app in background è disabilitato per l'app
  • Il dispositivo è in Modalità risparmio energetico
  • Il dispositivo è stato inattivo per periodi prolungati
  • Le risorse di sistema sono limitate
  • Più app stanno competendo per il tempo di esecuzione in background

• Solo formato JSON (non può essere modificato)

• Richiede un broker MQTT (locale o basato su cloud)

Prerequisiti

• Un broker MQTT (ad esempio, Mosquitto, HiveMQ, AWS IoT Core, ecc.)
• Connettività di rete al tuo broker MQTT
• Indirizzo IP o nome host del broker
• Numero di porta
• Opzionale: Nome utente e password se il tuo broker richiede autenticazione

Configurazione

Naviga alla schermata Esportazioni Automatiche dalla navigazione principale, quindi tocca "Nuova Automazione" e seleziona "MQTT" come Tipo di Automazione.

Nome automazione

Inserisci un nome descrittivo per la tua automazione (ad esempio, "MQTT Home Assistant", "Broker MQTT Cloud").

Notifiche

Configura quando vuoi ricevere notifiche:

• Notifica all'aggiornamento della cache - Ricevi una notifica quando i dati in cache vengono aggiornati
• Notifica all'esecuzione - Ricevi una notifica ogni volta che l'automazione pubblica dati

Configurazione broker

Indirizzo IP

Inserisci l'indirizzo IP o il nome host del tuo broker MQTT.

Esempi:

• 192.168.1.100 (indirizzo IP locale)
• mqtt.example.com (nome host)
• broker.hivemq.com (broker MQTT cloud)
• localhost (se eseguito sullo stesso dispositivo, non raccomandato per iOS)

Nota: Usa indirizzi IP per broker locali sulla tua rete, o nomi host per broker basati su cloud. Assicurati che il broker sia accessibile dal tuo dispositivo.

Porta

Inserisci il numero di porta per il tuo broker MQTT.

Nota: La porta predefinita è 1883.

Argomento

Inserisci l'argomento MQTT dove verranno pubblicati i dati sanitari. Questo è l'argomento che gli abbonati useranno per ricevere i tuoi dati sanitari.

Esempi di argomenti:

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

Migliori pratiche per gli argomenti:

• Usa barre oblique (/) per creare gerarchie di argomenti
• Usa nomi descrittivi che indicano il tipo di dati
• Evita spazi e caratteri speciali
• Considera di includere il nome dell'automazione per più automazioni

Nota: Il nome dell'argomento è sensibile alle maiuscole/minuscole. Assicurati che gli abbonati usino esattamente lo stesso nome dell'argomento.

ID client

Inserisci un ID client univoco per questa connessione MQTT. Questo identifica il tuo dispositivo al broker MQTT.

Esempi di ID client:

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

Nome utente (Opzionale)

Inserisci il nome utente per l'autenticazione del broker MQTT. Lascia vuoto se il tuo broker non richiede autenticazione.

Password (Opzionale)

Inserisci la password per l'autenticazione del broker MQTT. Lascia vuoto se il tuo broker non richiede autenticazione.

Impostazioni tipo di dati

Tipo di dati

Seleziona quale tipo di dati sanitari esportare:

• Metriche sanitarie - Passi, frequenza cardiaca, sonno e altre misurazioni sanitarie
• Allenamenti - Attività di esercizio e fitness
• Sintomi - Sintomi e condizioni sanitarie
• ECG - Letture elettrocardiogramma
• Notifiche frequenza cardiaca - Eventi frequenza cardiaca alta/bassa
• Stato mentale - Voci di umore e stato mentale (iOS 18.0+)
• Monitoraggio ciclo - Dati del ciclo mestruale e salute riproduttiva
• Farmaci - Registri farmaci e aderenza (iOS 26.0+)

Configurazione metriche sanitarie

Quando Metriche sanitarie è selezionato:

Seleziona metriche sanitarie - Scegli quali metriche specifiche includere. Puoi selezionare tutte le metriche disponibili o scegliere quelle specifiche.

Suggerimento: Selezionare solo le metriche di cui hai bisogno riduce la dimensione del messaggio e il tempo di elaborazione.

Fonti preferite - Configura quali fonti di dati hanno priorità quando più fonti forniscono la stessa metrica.

Configurazione allenamenti

Quando Allenamenti è selezionato:

Includi dati percorso - Attiva per includere percorsi per allenamenti che hanno dati di posizione.

Includi metriche allenamento - Attiva per includere metriche sanitarie raccolte durante gli allenamenti (frequenza cardiaca, calorie, ecc.).

Raggruppamento temporale (Metriche allenamento) - Quando si usa Versione esportazione 2 e Includi metriche allenamento è abilitato:

• Minuti - Raggruppa le metriche di allenamento per minuto
• Secondi - Raggruppa le metriche di allenamento per secondo

Impostazioni esportazione

Formato esportazione

Nota: Le automazioni MQTT supportano solo il formato JSON. Questa impostazione non può essere modificata ed è automaticamente impostata su JSON.

Versione esportazione

Seleziona una Versione esportazione per i dati di allenamento:

• Versione 1 - Formato legacy
• Versione 2 - Formato attuale con dati di allenamento migliorati

Nota: La Versione esportazione influisce principalmente sulla struttura dei dati di allenamento se stai esportando allenamenti.

Intervallo date

Seleziona quando i dati devono essere esportati:

• Predefinito - Sincronizza i dati per l'intera giornata precedente più i dati fino alla data e ora correnti
• Dall'ultima sincronizzazione - Ad ogni sincronizzazione, esporta tutti i dati dall'ultima volta che l'esportazione è stata eseguita fino alla data e ora correnti
• Oggi - Sincronizza tutti i dati per la data corrente fino all'ora corrente
• Ieri - Sincronizza tutti i dati per l'intera giornata precedente
• Ultimi 7 giorni - Sincronizza i dati per gli ultimi sette giorni completi

Riassumi dati

Quando si usa il formato JSON con il tipo di dati Metriche sanitarie, attiva o disattiva Riassumi dati.

• ON - Fornisce riassunti di dati aggregati (predefinito)
• OFF - Fornisce dati disaggregati quando possibile, mostrando singoli punti dati

Raggruppamento temporale

Quando Riassumi dati è abilitato, seleziona come i dati devono essere aggregati.

Riassumi dati

Attiva o disattiva Riassumi dati per Metriche sanitarie.

• ON - Fornisce riassunti di dati aggregati (predefinito)
• OFF - Fornisce dati disaggregati quando possibile

Nota: Questa impostazione si applica solo al tipo di dati Metriche sanitarie.

Frequenza sincronizzazione

Configura con quale frequenza l'automazione deve pubblicare dati su MQTT:

Seleziona un numero e un intervallo.

Test e verifica

Test manuali

1. Tocca "Esportazione manuale" nella schermata di configurazione dell'automazione
2. Seleziona un intervallo di date
3. Tocca "Esporta" per pubblicare un messaggio
4. Usa un client MQTT per abbonarti al tuo argomento e verifica che il messaggio sia stato ricevuto

Utilizzo di un client MQTT

Per verificare che i messaggi vengano pubblicati:

1. Configura un client MQTT
2. Connettiti al tuo broker MQTT usando le stesse credenziali
3. Abbonati al tuo argomento
4. Attiva un'esportazione manuale dall'app
5. Verifica che il messaggio appaia nel tuo client MQTT

Visualizzazione log attività

1. Tocca "Visualizza log attività" nella schermata di configurazione dell'automazione
2. Rivedi le esecuzioni recenti dell'automazione
3. Controlla errori di connessione o errori di pubblicazione
4. Verifica i timestamp di pubblicazione

Formato messaggio

I messaggi MQTT vengono pubblicati come JSON. Il payload del messaggio segue il formato JSON di esportazione standard:

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

Il messaggio viene pubblicato con:

• Argomento: Come configurato nell'automazione
• QoS: Consegna al massimo una volta
• Conserva: I messaggi non vengono conservati
• Payload: Stringa JSON contenente dati sanitari

Risoluzione problemi

Problemi comuni

Errori di connessione

• Verifica che l'indirizzo IP/nome host del broker sia corretto
• Verifica che la porta sia corretta e che il broker stia ascoltando su quella porta
• Assicurati della connettività di rete al broker
• Verifica che le regole del firewall consentano connessioni al broker
• Verifica se il broker richiede TLS/SSL

Errori di autenticazione

• Verifica che nome utente e password siano corretti
• Verifica che l'autenticazione sia abilitata sul tuo broker se vengono fornite credenziali
• Assicurati che l'utente abbia il permesso di pubblicare sull'argomento specificato

Messaggi non ricevuti

• Verifica che il nome dell'argomento corrisponda esattamente (sensibile alle maiuscole/minuscole)
• Verifica che gli abbonati siano connessi allo stesso broker
• Assicurati che gli abbonati siano abbonati all'argomento corretto
• Verifica che l'automazione sia abilitata e in esecuzione
• Controlla i Log attività per errori di pubblicazione

Dimensione messaggio grande

• Riduci il numero di metriche sanitarie selezionate
• Usa opzioni di aggregazione meno granulari
• Considera di dividere in più automazioni per diversi tipi di dati

Suggerimenti e migliori pratiche

1. Organizzazione argomenti:

   • Usa strutture di argomenti gerarchiche (ad esempio, health/metrics, health/workouts)
   • Includi identificatori di dispositivo o automazione negli argomenti
   • Documenta la tua struttura di argomenti per riferimento facile

2. Dimensione messaggio:

   • Mantieni i messaggi di dimensioni ragionevoli per evitare limiti del broker MQTT
   • Usa aggregazione meno granulare per ridurre il volume dei dati
   • Considera di dividere grandi set di dati su più messaggi

3. Monitoraggio:

   • Usa i Log attività nell'app per tracciare il successo della pubblicazione

4. Broker cloud:

   • Quando usi broker MQTT cloud (AWS IoT, HiveMQ Cloud, ecc.):
     • Segui i loro requisiti di connessione specifici
     • Controlla i loro limiti di dimensione e velocità dei messaggi
     • Verifica le convenzioni di denominazione degli argomenti