Sincronizar dados do Apple Health com MQTT

As automações MQTT permitem-lhe publicar automaticamente os seus dados de saúde num broker MQTT. Isto é ideal para integrar com plataformas IoT, sistemas de automação doméstica ou qualquer serviço que suporte mensagens MQTT.

Visão geral

As automações MQTT publicam os seus dados de saúde como mensagens JSON num tópico MQTT especificado num broker MQTT. Os dados são enviados sempre que a automação é executada de acordo com as suas definições de frequência de sincronização.

Casos de utilização:

• Integração com plataformas IoT (Home Assistant, OpenHAB, etc.)
• Publicação de dados de saúde em painéis baseados em MQTT
• Sistemas de monitorização de saúde em tempo real
• Integrações personalizadas de automação doméstica
• Plataformas de registo e análise de dados

Características principais:

• Apenas formato JSON (otimizado para MQTT)
• Suporta ligações autenticadas e anónimas
• Estrutura de tópicos configurável
• Gestão de ID do cliente
• Autenticação opcional de nome de utilizador/palavra-passe

Limitações

• Acesso aos dados de saúde: As aplicações não têm permissão para aceder aos dados de saúde enquanto o iPhone está bloqueado. As automações serão executadas apenas durante os períodos em que o seu dispositivo estiver desbloqueado. Isto pode afetar a atualidade dos dados. Consulte as instruções para sincronização manual para manter os dados atualizados.

• Processamento em segundo plano: O iOS limita o processamento em segundo plano para preservar a vida útil da bateria. As automações dependem da Atualização de aplicação em segundo plano e podem não ser executadas imediatamente se:

  • A Atualização de aplicação em segundo plano estiver desativada para a aplicação
  • O dispositivo estiver em Modo de baixo consumo
  • O dispositivo estiver inativo por períodos prolongados
  • Os recursos do sistema estiverem limitados
  • Múltiplas aplicações estiverem a competir por tempo de execução em segundo plano

• Apenas formato JSON (não pode ser alterado)

• Requer um broker MQTT (local ou baseado na nuvem)

Pré-requisitos

• Um broker MQTT (por exemplo, Mosquitto, HiveMQ, AWS IoT Core, etc.)
• Conectividade de rede ao seu broker MQTT
• Endereço IP ou nome do anfitrião do broker
• Número da porta
• Opcional: Nome de utilizador e palavra-passe se o seu broker exigir autenticação

Configuração

Navegue até ao ecrã Exportações Automatizadas na navegação principal, depois toque em "Nova Automação" e selecione "MQTT" como Tipo de Automação.

Nome da automação

Introduza um nome descritivo para a sua automação (por exemplo, "MQTT Home Assistant", "Broker MQTT na nuvem").

Notificações

Configure quando deseja receber notificações:

• Notificar na atualização da cache - Receba uma notificação quando os dados em cache forem atualizados
• Notificar quando executar - Receba uma notificação sempre que a automação publicar dados

Configuração do broker

Endereço IP

Introduza o endereço IP ou nome do anfitrião do seu broker MQTT.

Exemplos:

• 192.168.1.100 (endereço IP local)
• mqtt.example.com (nome do anfitrião)
• broker.hivemq.com (broker MQTT na nuvem)
• localhost (se executado no mesmo dispositivo, não recomendado para iOS)

Nota: Utilize endereços IP para brokers locais na sua rede ou nomes de anfitrião para brokers baseados na nuvem. Certifique-se de que o broker esteja acessível a partir do seu dispositivo.

Porta

Introduza o número da porta do seu broker MQTT.

Nota: A porta predefinida é 1883.

Tópico

Introduza o tópico MQTT onde os dados de saúde serão publicados. Este é o tópico que os assinantes utilizarão para receber os seus dados de saúde.

Exemplos de tópicos:

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

Melhores práticas para tópicos:

• Utilize barras (/) para criar hierarquias de tópicos
• Utilize nomes descritivos que indiquem o tipo de dados
• Evite espaços e caracteres especiais
• Considere incluir o nome da automação para múltiplas automações

Nota: O nome do tópico diferencia maiúsculas de minúsculas. Certifique-se de que os assinantes utilizem exatamente o mesmo nome de tópico.

ID do cliente

Introduza um ID de cliente exclusivo para esta ligação MQTT. Isto identifica o seu dispositivo para o broker MQTT.

Exemplos de ID do cliente:

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

Nome de utilizador (Opcional)

Introduza o nome de utilizador para autenticação do broker MQTT. Deixe em branco se o seu broker não exigir autenticação.

Palavra-passe (Opcional)

Introduza a palavra-passe para autenticação do broker MQTT. Deixe em branco se o seu broker não exigir autenticação.

Definições de tipo de dados

Tipo de dados

Selecione qual tipo de dados de saúde exportar:

• Métricas de saúde - Passos, frequência cardíaca, sono e outras medições de saúde
• Treinos - Atividades de exercício e fitness
• Sintomas - Sintomas e condições de saúde
• ECG - Leituras de eletrocardiograma
• Notificações de frequência cardíaca - Eventos de frequência cardíaca alta/baixa
• Estado mental - Entradas de humor e estado mental (iOS 18.0+)
• Acompanhamento do ciclo - Dados do ciclo menstrual e saúde reprodutiva
• Medicamentos - Registos de medicamentos e aderência (iOS 26.0+)

Configuração de métricas de saúde

Quando Métricas de saúde está selecionado:

Selecionar métricas de saúde - Escolha quais métricas específicas incluir. Pode selecionar todas as métricas disponíveis ou escolher específicas.

Dica: Selecionar apenas as métricas de que precisa reduz o tamanho da mensagem e o tempo de processamento.

Fontes preferidas - Configure quais fontes de dados têm prioridade quando várias fontes fornecem a mesma métrica.

Configuração de treinos

Quando Treinos está selecionado:

Incluir dados de rota - Ative para incluir rotas para treinos que têm dados de localização.

Incluir métricas de treino - Ative para incluir métricas de saúde recolhidas durante os treinos (frequência cardíaca, calorias, etc.).

Agrupamento de tempo (Métricas de treino) - Ao utilizar Versão de exportação 2 e Incluir métricas de treino está ativado:

• Minutos - Agrupa métricas de treino por minuto
• Segundos - Agrupa métricas de treino por segundo

Definições de exportação

Formato de exportação

Nota: As automações MQTT suportam apenas o formato JSON. Esta definição não pode ser alterada e é automaticamente definida como JSON.

Versão de exportação

Selecione uma Versão de exportação para dados de treino:

• Versão 1 - Formato legado
• Versão 2 - Formato atual com dados de treino melhorados

Nota: A Versão de exportação afeta principalmente a estrutura dos dados de treino se estiver a exportar treinos.

Intervalo de datas

Selecione quando os dados devem ser exportados:

• Predefinido - Sincroniza dados para o dia anterior completo mais dados até à data e hora atuais
• Desde a última sincronização - Em cada sincronização, exporta todos os dados desde a última vez que a exportação foi executada até à data e hora atuais
• Hoje - Sincroniza todos os dados para a data atual até à hora atual
• Ontem - Sincroniza todos os dados para o dia anterior completo
• Últimos 7 dias - Sincroniza dados para os últimos sete dias completos

Resumir dados

Ao utilizar o formato JSON com o tipo de dados Métricas de saúde, ative ou desative Resumir dados.

• LIGADO - Fornece resumos de dados agregados (predefinido)
• DESLIGADO - Fornece dados desagregados quando possível, mostrando pontos de dados individuais

Agrupamento de tempo

Quando Resumir dados está ativado, selecione como os dados devem ser agregados.

Resumir dados

Ative ou desative Resumir dados para Métricas de saúde.

• LIGADO - Fornece resumos de dados agregados (predefinido)
• DESLIGADO - Fornece dados desagregados quando possível

Nota: Esta definição aplica-se apenas ao tipo de dados Métricas de saúde.

Frequência de sincronização

Configure com que frequência a automação deve publicar dados no MQTT:

Selecione um número e um intervalo.

Testes e verificação

Testes manuais

1. Toque em "Exportação manual" no ecrã de configuração da automação
2. Selecione um intervalo de datas
3. Toque em "Exportar" para publicar uma mensagem
4. Utilize um cliente MQTT para subscrever o seu tópico e verificar se a mensagem foi recebida

Utilizar um cliente MQTT

Para verificar se as mensagens estão a ser publicadas:

1. Configure um cliente MQTT
2. Ligue-se ao seu broker MQTT utilizando as mesmas credenciais
3. Subscreva o seu tópico
4. Acione uma exportação manual da aplicação
5. Verifique se a mensagem aparece no seu cliente MQTT

Visualizar registos de atividade

1. Toque em "Ver registos de atividade" no ecrã de configuração da automação
2. Revise as execuções recentes da automação
3. Verifique erros de ligação ou falhas de publicação
4. Verifique os carimbos de data/hora de publicação

Formato da mensagem

As mensagens MQTT são publicadas como JSON. O conteúdo da mensagem segue o formato JSON de exportação padrão:

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

A mensagem é publicada com:

• Tópico: Conforme configurado na automação
• QoS: Entrega no máximo uma vez
• Manter: As mensagens não são mantidas
• Conteúdo: String JSON contendo dados de saúde

Resolução de problemas

Problemas comuns

Falhas de ligação

• Verifique se o endereço IP/nome do anfitrião do broker está correto
• Verifique se a porta está correta e o broker está a ouvir nessa porta
• Certifique-se da conectividade de rede ao broker
• Verifique se as regras da firewall permitem ligações ao broker
• Verifique se o broker requer TLS/SSL

Falhas de autenticação

• Verifique se o nome de utilizador e a palavra-passe estão corretos
• Verifique se a autenticação está ativada no seu broker se as credenciais forem fornecidas
• Certifique-se de que o utilizador tem permissão para publicar no tópico especificado

Mensagens não recebidas

• Verifique se o nome do tópico corresponde exatamente (diferencia maiúsculas de minúsculas)
• Verifique se os assinantes estão ligados ao mesmo broker
• Certifique-se de que os assinantes estão subscritos ao tópico correto
• Verifique se a automação está ativada e em execução
• Verifique os Registos de atividade para erros de publicação

Tamanho grande da mensagem

• Reduza o número de métricas de saúde selecionadas
• Utilize opções de agregação menos granulares
• Considere dividir em múltiplas automações para diferentes tipos de dados

Dicas e melhores práticas

1. Organização de tópicos:

   • Utilize estruturas de tópicos hierárquicas (por exemplo, health/metrics, health/workouts)
   • Inclua identificadores de dispositivo ou automação nos tópicos
   • Documente a sua estrutura de tópicos para referência fácil

2. Tamanho da mensagem:

   • Mantenha as mensagens com tamanho razoável para evitar limites do broker MQTT
   • Utilize agregação menos granular para reduzir o volume de dados
   • Considere dividir grandes conjuntos de dados em múltiplas mensagens

3. Monitorização:

   • Utilize os Registos de atividade na aplicação para rastrear o sucesso da publicação

4. Brokers na nuvem:

   • Ao utilizar brokers MQTT na nuvem (AWS IoT, HiveMQ Cloud, etc.):
     • Siga os seus requisitos de ligação específicos
     • Verifique os seus limites de tamanho e taxa de mensagens
     • Verifique as convenções de nomenclatura de tópicos