Sync Apple Health Data to MQTT

MQTT automations allow you to automatically publish your health data to an MQTT broker. This is ideal for integrating with IoT platforms, home automation systems, or any service that supports MQTT messaging.

Overview

MQTT automations publish your health data as JSON messages to a specified MQTT topic on an MQTT broker. The data is sent whenever the automation runs according to your sync cadence settings.

Use Cases:

• Integrating with IoT platforms (Home Assistant, OpenHAB, etc.)
• Publishing health data to MQTT-based dashboards
• Real-time health monitoring systems
• Custom home automation integrations
• Data logging and analytics platforms

Key Features:

• JSON format only (optimized for MQTT)
• Supports authenticated and anonymous connections
• Configurable topic structure
• Client ID management
• Optional username/password authentication

Limitations

• Health Data Access: Apps are not allowed to access health data while iPhone is locked. Automations will only run during periods when your device is unlocked. This can affect data freshness. See instructions for manual syncing to keep data up to date.

• Background Processing: iOS limits background processing to preserve battery life. Automations rely on Background App Refresh and may not run immediately if:

  • Background App Refresh is disabled for the app
  • The device is in Low Power Mode
  • The device has been inactive for extended periods
  • System resources are constrained
  • Multiple apps are competing for background execution time

• JSON format only (cannot be changed)

• Requires an MQTT broker (local or cloud-based)

Prerequisites

• An MQTT broker (e.g., Mosquitto, HiveMQ, AWS IoT Core, etc.)
• Network connectivity to your MQTT broker
• Broker IP address or hostname
• Port number
• Optional: Username and password if your broker requires authentication

Configuration

Navigate to the Automated Exports screen from the main navigation, then tap New Automation" and select "MQTT" as the Automation Type.

Automation Name

Enter a descriptive name for your automation (e.g., "Home Assistant MQTT", "Cloud MQTT Broker").

Notifications

Configure when you want to receive notifications:

• Notify on Cache Update - Receive a notification when cached data is updated
• Notify When Run - Receive a notification each time the automation publishes data

Broker Configuration

IP Address

Enter the IP address or hostname of your MQTT broker.

Examples:

• 192.168.1.100 (local IP address)
• mqtt.example.com (hostname)
• broker.hivemq.com (cloud MQTT broker)
• localhost (if running on the same device, not recommended for iOS)

Note: Use IP addresses for local brokers on your network, or hostnames for cloud-based brokers. Ensure the broker is accessible from your device.

Port

Enter the port number for your MQTT broker.

Note: The default port is 1883.

Topic

Enter the MQTT topic where health data will be published. This is the topic that subscribers will use to receive your health data.

Topic Examples:

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

Topic Best Practices:

• Use forward slashes (/) to create topic hierarchies
• Use descriptive names that indicate the data type
• Avoid spaces and special characters
• Consider including the automation name for multiple automations

Note: The topic name is case-sensitive. Ensure subscribers use the exact same topic name.

Client ID

Enter a unique client ID for this MQTT connection. This identifies your device to the MQTT broker.

Client ID Examples:

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

Username (Optional)

Enter the username for MQTT broker authentication. Leave empty if your broker doesn't require authentication.

Password (Optional)

Enter the password for MQTT broker authentication. Leave empty if your broker doesn't require authentication.

Data Type Settings

Data Type

Select which type of health data to export:

• Health Metrics - Steps, heart rate, sleep, and other health measurements
• Workouts - Exercise and fitness activities
• Symptoms - Health symptoms and conditions
• ECG - Electrocardiogram readings
• Heart Rate Notifications - High/low heart rate events
• State of Mind - Mood and mental state entries (iOS 18.0+)
• Cycle Tracking - Menstrual cycle and reproductive health data
• Medications - Medication logs and adherence (iOS 26.0+)

Health Metrics Configuration

When Health Metrics is selected:

Select Health Metrics - Choose which specific metrics to include. You can select all available metrics or choose specific ones.

Tip: Selecting only the metrics you need reduces message size and processing time.

Preferred Sources - Configure which data sources take priority when multiple sources provide the same metric.

Workout Configuration

When Workouts is selected:

Include Route Data - Toggle ON to include routes for workouts that have location data.

Include Workout Metrics - Toggle ON to include health metrics collected during workouts (heart rate, calories, etc.).

Time Grouping (Workout Metrics) - When using Export Version 2 and Include Workout Metrics is enabled:

• Minutes - Groups workout metrics by minute
• Seconds - Groups workout metrics by second

Export Settings

Export Format

Note: MQTT automations only support JSON format. This setting cannot be changed and is automatically set to JSON.

Export Version

Select an Export Version for workout data:

• Version 1 - Legacy format
• Version 2 - Current format with enhanced workout data

Note: Export Version primarily affects workout data structure if you're exporting workouts.

Date Range

Select when data should be exported:

• Default - Syncs data for the full previous day plus data up to the current date and time
• Since Last Sync - On each sync, exports all data since the last time the export ran up until the current date and time
• Today - Syncs all data for the current date up to the current time
• Yesterday - Syncs all data for the full previous day
• Previous 7 Days - Syncs data for the full previous seven days

Summarize Data

When using JSON format with Health Metrics data type, toggle Summarize Data ON or OFF.

• ON - Provides aggregated data summaries (default)
• OFF - Provides disaggregated data where possible, showing individual data points

Time Grouping

When Summarize Data is enabled, select how data should be aggregated.

Summarize Data

Toggle Summarize Data ON or OFF for Health Metrics.

• ON - Provides aggregated data summaries (default)
• OFF - Provides disaggregated data where possible

Note: This setting only applies to Health Metrics data type.

Sync Cadence

Configure how often the automation should publish data to MQTT:

Select a number and interval.

Testing & Verification

Manual Testing

1. Tap "Manual Export" in the automation configuration screen
2. Select a date range
3. Tap "Export" to publish a message
4. Use an MQTT client to subscribe to your topic and verify the message was received

Using an MQTT Client

To verify messages are being published:

1. Set up an MQTT client
2. Connect to your MQTT broker using the same credentials
3. Subscribe to your topic
4. Trigger a manual export from the app
5. Verify the message appears in your MQTT client

Viewing Activity Logs

1. Tap "View Activity Logs" in the automation configuration screen
2. Review recent automation runs
3. Check for connection errors or publish failures
4. Verify publish timestamps

Message Format

MQTT messages are published as JSON. The message payload follows the standard export JSON format:

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

The message is published with:

• Topic: As configured in the automation
• QoS: At most once delivery
• Retain: Messages are not retained
• Payload: JSON string containing health data

Troubleshooting

Common Issues

Connection Failures

• Verify the broker IP address/hostname is correct
• Check that the port is correct and the broker is listening on that port
• Ensure network connectivity to the broker
• Verify firewall rules allow connections to the broker
• Check if the broker requires TLS/SSL

Authentication Failures

• Verify username and password are correct
• Check that authentication is enabled on your broker if credentials are provided
• Ensure the user has permission to publish to the specified topic

Messages Not Received

• Verify the topic name matches exactly (case-sensitive)
• Check that subscribers are connected to the same broker
• Ensure subscribers are subscribed to the correct topic
• Verify the automation is enabled and running
• Check Activity Logs for publish errors

Large Message Size

• Reduce the number of selected health metrics
• Use less granular aggregation options
• Consider splitting into multiple automations for different data types

Tips and Best Practices

1. Topic Organization:

   • Use hierarchical topic structures (e.g., health/metrics, health/workouts)
   • Include device or automation identifiers in topics
   • Document your topic structure for easy reference

2. Message Size:

   • Keep messages reasonably sized to avoid MQTT broker limits
   • Use less granular aggregation to reduce data volume
   • Consider splitting large datasets across multiple messages

3. Monitoring:

   • Use Activity Logs in the app to track publish success

4. Cloud Brokers:

   • When using cloud MQTT brokers (AWS IoT, HiveMQ Cloud, etc.):
     • Follow their specific connection requirements
     • Check their message size and rate limits
     • Verify topic naming conventions