Sincronizar dados do Apple Health com MQTT

As automações MQTT permitem que você publique automaticamente seus dados de saúde em um broker MQTT. Isso é ideal para integrar com plataformas IoT, sistemas de automação residencial ou qualquer serviço que suporte mensageria MQTT.

Visão geral

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

Casos de uso:

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

Recursos principais:

• Apenas formato JSON (otimizado para MQTT)
• Suporta conexões autenticadas e anônimas
• Estrutura de tópicos configurável
• Gerenciamento de ID do cliente
• Autenticação opcional de nome de usuário/senha

Limitações

• Acesso aos dados de saúde: Os aplicativos não têm permissão para acessar dados de saúde enquanto o iPhone está bloqueado. As automações serão executadas apenas durante os períodos em que seu dispositivo estiver desbloqueado. Isso 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 aplicativo em segundo plano e podem não ser executadas imediatamente se:

  • A Atualização de aplicativo em segundo plano estiver desabilitada para o aplicativo
  • O dispositivo estiver em Modo de baixo consumo
  • O dispositivo estiver inativo por períodos prolongados
  • Os recursos do sistema estiverem limitados
  • Múltiplos aplicativos estiverem competindo por tempo de execução em segundo plano

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

• Requer um broker MQTT (local ou baseado em 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 host do broker
• Número da porta
• Opcional: Nome de usuário e senha se seu broker exigir autenticação

Configuração

Navegue até a tela 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

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

Notificações

Configure quando deseja receber notificações:

• Notificar na atualização do 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

Digite o endereço IP ou nome do host do seu broker MQTT.

Exemplos:

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

Nota: Use endereços IP para brokers locais em sua rede ou nomes de host para brokers baseados em nuvem. Certifique-se de que o broker esteja acessível do seu dispositivo.

Porta

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

Nota: A porta padrão é 1883.

Tópico

Digite o tópico MQTT onde os dados de saúde serão publicados. Este é o tópico que os assinantes usarão para receber 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:

• Use barras (/) para criar hierarquias de tópicos
• Use 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 usem exatamente o mesmo nome de tópico.

ID do cliente

Digite um ID de cliente exclusivo para esta conexão MQTT. Isso identifica seu dispositivo para o broker MQTT.

Exemplos de ID do cliente:

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

Nome de usuário (Opcional)

Digite o nome de usuário para autenticação do broker MQTT. Deixe em branco se seu broker não exigir autenticação.

Senha (Opcional)

Digite a senha para autenticação do broker MQTT. Deixe em branco se seu broker não exigir autenticação.

Configuraçõ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 - Registros 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. Você pode selecionar todas as métricas disponíveis ou escolher específicas.

Dica: Selecionar apenas as métricas de que você 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 coletadas durante os treinos (frequência cardíaca, calorias, etc.).

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

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

Configurações de exportação

Formato de exportação

Nota: As automações MQTT suportam apenas o formato JSON. Esta configuraçã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 aprimorados

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

Intervalo de datas

Selecione quando os dados devem ser exportados:

• Padrão - Sincroniza dados para o dia anterior completo mais dados até a 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é a data e hora atuais
• Hoje - Sincroniza todos os dados para a data atual até a 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 usar o formato JSON com o tipo de dados Métricas de saúde, ative ou desative Resumir dados.

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

Agrupamento de tempo

Quando Resumir dados está habilitado, 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 (padrão)
• DESLIGADO - Fornece dados desagregados quando possível

Nota: Esta configuração se aplica 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" na tela de configuração da automação
2. Selecione um intervalo de datas
3. Toque em "Exportar" para publicar uma mensagem
4. Use um cliente MQTT para assinar seu tópico e verificar se a mensagem foi recebida

Usando um cliente MQTT

Para verificar se as mensagens estão sendo publicadas:

1. Configure um cliente MQTT
2. Conecte-se ao seu broker MQTT usando as mesmas credenciais
3. Assine seu tópico
4. Acione uma exportação manual do aplicativo
5. Verifique se a mensagem aparece no seu cliente MQTT

Visualizando logs de atividade

1. Toque em "Ver logs de atividade" na tela de configuração da automação
2. Revise as execuções recentes da automação
3. Verifique erros de conexã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

Solução de problemas

Problemas comuns

Falhas de conexão

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

Falhas de autenticação

• Verifique se o nome de usuário e a senha estão corretos
• Verifique se a autenticação está habilitada no seu broker se as credenciais forem fornecidas
• Certifique-se de que o usuário 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 conectados ao mesmo broker
• Certifique-se de que os assinantes estão inscritos no tópico correto
• Verifique se a automação está habilitada e em execução
• Verifique os Logs de atividade para erros de publicação

Tamanho grande da mensagem

• Reduza o número de métricas de saúde selecionadas
• Use 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:

   • Use estruturas de tópicos hierárquicas (por exemplo, health/metrics, health/workouts)
   • Inclua identificadores de dispositivo ou automação nos tópicos
   • Documente 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
   • Use agregação menos granular para reduzir o volume de dados
   • Considere dividir grandes conjuntos de dados em múltiplas mensagens

3. Monitoramento:

   • Use os Logs de atividade no aplicativo para rastrear o sucesso da publicação

4. Brokers na nuvem:

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