Garmin SDK

[mojtaba]

In this section, we list the comprehensive range of Garmin SDK metrics that Avicenna supports.

Supported Garmin SDK Metrics in Avicenna

Each metric includes details about its fields and the default sampling rates. Also, all metrics include the common data fields and the following additional fields:

• Device: The Garmin device that collected the data. Internally stored as device. It contains the following fields:
  • Device ID: The unique ID of the device. Internally stored as identifier.
  • Device Name: The name of the device. Internally stored as name.
  • Device Model: The model of the device. Internally stored as model.
  • Device Firmware Version: The firmware version of the device. Internally stored as firmware_version.

[!note]
The specific metrics collected depend on your Garmin device model. Not all metrics listed below are available on every device. To determine which metrics are supported by your watch, please refer to your owner’s manual.

Garmin Health SDK Logged Accelerometer

Download Sample Data

Records 25Hz accelerometer data from all three axes in milli-Gs.

• Acceleration X: Measures acceleration along the x-axis. Internally stored as x_value.
• Acceleration Y: Measures acceleration along the y-axis. Internally stored as y_value.
• Acceleration Z: Measures acceleration along the z-axis. Internally stored as z_value.

Garmin Health SDK Logged Actigraphy

Download Sample Data

Provides actigraphy data from three independently configurable instances. Each sample includes three activity metrics computed from 25Hz accelerometer data. The data is logged with a default processing interval of 30 seconds.

• Instance: Indicates which of the three actigraphy instances the data belongs to. Internally stored as instance. Possible values are:

  Numeric Value	Name
  0	ACTIGRAPHY_INSTANCE_UNKNOWN
  1	ACTIGRAPHY_1
  2	ACTIGRAPHY_2
  3	ACTIGRAPHY_3

• End Timestamp: The end time of the actigraphy measurement interval. Internally stored as end_timestamp.

• Total Energy: The total energy calculated from the accelerometer data. Internally stored as total_energy.

• Zero Crossing Count: The number of zero crossings detected during the interval. Internally stored as zero_crossing_count.

• Time Above Threshold: The time spent above the activity threshold during the interval. Internally stored as time_above_threshold.

Garmin Health SDK Logged BBI

Download Sample Data

Provides beat-to-beat intervals (BBI) for individual heartbeats. This data type records all valid heartbeats continuously without intervals.

• BBI: The beat-to-beat interval value in milliseconds. Internally stored as bbi.

Garmin Health SDK Logged Enhanced BBI

Download Sample Data

Provides beat-to-beat intervals (BBI), supplemented with a confidence value that indicates the quality of the BBI data. This data type records all valid heartbeats continuously without intervals.

• Status: Indicates the confidence level and quality of the BBI measurement. Internally stored as status. Possible values are:

  Numeric Value	Name
  0	ENHANCED_BBI_STATUS_UNKNOWN
  1	ENHANCED_BBI_STATUS_GAP
  2	ENHANCED_BBI_STATUS_HIGH_CONFIDENCE
  3	ENHANCED_BBI_STATUS_LOW_CONFIDENCE

• BBI: The beat-to-beat interval value in milliseconds. Internally stored as bbi.

• Gap Duration: The duration of any gap in the BBI data in milliseconds. Internally stored as gap_duration.

Garmin Health SDK Logged Gyroscope

Download Sample Data

Records 32Hz gyroscope data, representing the rate of rotation around each of the three axes in degrees/second.

• Rotation Rate X: The rate of rotation around the x-axis in degrees per second. Internally stored as x_value.
• Rotation Rate Y: The rate of rotation around the y-axis in degrees per second. Internally stored as y_value.
• Rotation Rate Z: The rate of rotation around the z-axis in degrees per second. Internally stored as z_value.

Garmin Health SDK Logged Heart Rate

Download Sample Data

Measures heart rate in beats per minute (BPM). Data is reported as instantaneous values with a default interval of 60 seconds.

• Heart Rate: The heart rate in beats per minute (BPM). Internally stored as beats_per_minute.

• Status: Determines if the device is on-wrist or not, making it useful for adherence monitoring. Internally stored as status. Possible values are:

  Numeric Value	Name
  0	HEART_RATE_STATUS_UNKNOWN
  1	HEART_RATE_STATUS_SEARCHING
  2	HEART_RATE_STATUS_LOCKED

Garmin Health SDK Logged Heart Rate Variability

Download Sample Data

Reports heart rate variability (HRV) metrics calculated from beat-to-beat interval (BBI) data. Each entry represents HRV values computed over a 5-minute window of BBI data.

• HRV RMSSD: The root mean square of successive differences between normal heartbeats, in milliseconds. Internally stored as hrv_rmssd.

• HRV SDNN: The standard deviation of all normal-to-normal (NN) intervals, in milliseconds. Internally stored as hrv_sdnn.

Garmin Health SDK Motion Intensity

Download Sample Data

Provides motion intensity data with activity type classification. Motion intensity is a numerical abstraction of low-level accelerometer data calculated at minute-level granularity, representing the level of physical motion regardless of whether the user actually changes location. Motion intensity values can rise even if the user remains in the same place. For example, activities like jumping in place or fidgeting with a pencil will not contribute to distance metrics, but will still increase motion intensity scores during that period. It is also common to observe moderate motion intensity values during sedentary periods, since most people do not remain completely motionless.

• Activity Type: Indicates the type of activity detected during the motion intensity measurement. Internally stored as activity_type. Possible values are:

  Numeric Value	Name
  0	GENERIC
  1	RUNNING
  2	CYCLING
  3	TRANSITION
  4	FITNESS_EQUIPMENT
  5	SWIMMING
  6	WALKING
  7	SLEEP
  8	SEDENTARY
  9	UNMONITORED
  10	DRIVING
  11	DOG_TRAINING
  12	EATING
  13	ALL

• Intensity Level: The motion intensity level value ranging from 0 to 7, where 0 represents absolutely still and 7 represents constant, sharp motion. Internally stored as intensity_level.
• Start Timestamp: The start time of the motion intensity measurement interval. Internally stored as record_time.
• End Timestamp: The end time of the motion intensity measurement interval. Internally stored as end_timestamp.

Garmin Health SDK MoveIQ Event

Provides MoveIQ event data with activity type classification. MoveIQ events are Garmin activities that are not started by the user explicitly. Instead, a MoveIQ activity is triggered based on the analysis of user activity.

• Activity Type: Indicates the type of activity detected during the MoveIQ event. Internally stored as activity_type. Possible values are:

  Numeric Value	Name
  0	GENERIC
  1	RUNNING
  2	CYCLING
  3	TRANSITION
  4	FITNESS_EQUIPMENT
  5	SWIMMING
  6	WALKING
  7	SLEEP
  8	SEDENTARY
  9	UNMONITORED
  10	DRIVING
  11	DOG_TRAINING
  12	EATING
  13	ALL

• Start Timestamp: The start time of the MoveIQ event. Internally stored as record_time.

• End Timestamp: The end time of the MoveIQ event. Internally stored as end_timestamp.

Garmin Health SDK Logged Respiration

Measures respiration rate in breaths per minute. Data is reported as instantaneous values with a default interval of 60 seconds.

• Respiration: The respiration rate in breaths per minute. Internally stored as breaths_per_minute.

• Status: Indicates the quality and reliability of the respiration measurement. Internally stored as status. Possible values are:

  Numeric Value	Name
  0	RESPIRATION_STATUS_UNKNOWN
  1	RESPIRATION_STATUS_VALID
  2	RESPIRATION_STATUS_OFF_WRIST
  3	RESPIRATION_STATUS_LARGE_MOTION
  4	RESPIRATION_STATUS_INVALID
  5	RESPIRATION_STATUS_UNAVAILABLE

Garmin Health SDK Logged Sleep

Provides detailed sleep data, including sleep intervals, assessments, and overnight skin temperature.

• Sleep Result Type: Indicates the type of sleep analysis performed. Internally stored as sleep_result_type. Possible values are:

  Numeric Value	Name
  0	SLEEP_RESULT_TYPE_UNKNOWN
  1	SLEEP_RESULT_TYPE_ENHANCED
  2	SLEEP_RESULT_TYPE_MOTION_BASED

• Sleep Source Type: Indicates the source of the sleep data. Internally stored as sleep_source_type. Possible values are:

  Numeric Value	Name
  0	SLEEP_SOURCE_TYPE_UNKNOWN
  1	SLEEP_SOURCE_TYPE_SERVER
  2	SLEEP_SOURCE_TYPE_DEVICE

• Start Time: The start time of the sleep session. Internally stored as record_time.

• End Time: The end time of the sleep session. Internally stored as end_time.

• Sleep Intervals: Array of sleep intervals. Internally stored as sleep_interval. It contains the following fields:

  • Start Time: The start time of the sleep interval. Internally stored as start_time.

  • End Time: The end time of the sleep interval. Internally stored as end_time.

  • Sleep Level: Indicates the sleep stage or level during a sleep interval. Internally stored as sleep_level. Possible values are:

    Numeric Value	Name
    0	SLEEP_LEVEL_UNKNOWN
    1	SLEEP_LEVEL_INVALID
    2	SLEEP_LEVEL_UNMEASURABLE
    3	SLEEP_LEVEL_AWAKE
    4	SLEEP_LEVEL_LIGHT
    5	SLEEP_LEVEL_DEEP
    6	SLEEP_LEVEL_REM

• Sleep Assessments: Array of sleep assessments with various sleep quality scores. Internally stored as sleep_assessment. It contains the following fields:

  • Start Time: The start time of the sleep assessment period in milliseconds since epoch. Internally stored as start_time.
  • End Time: The end time of the sleep assessment period in milliseconds since epoch. Internally stored as end_time.
  • Awakenings Count: Number of awakenings during the sleep period. Internally stored as awakenings_count.
  • Awakenings Count Score: Garmin’s proprietary score based on the number of awakenings. Internally stored as awakenings_count_score.
  • Awake Time Score: Garmin’s proprietary score based on time spent awake. Internally stored as awake_time_score.
  • Combined Awake Score: Garmin’s proprietary combined score for awake-related metrics. Internally stored as combined_awake_score.
  • Deep Sleep Score: Garmin’s proprietary score based on deep sleep quality. Internally stored as deep_sleep_score.
  • Light Sleep Score: Garmin’s proprietary score based on light sleep quality. Internally stored as light_sleep_score.
  • Overall Sleep Score: Garmin’s proprietary overall sleep quality score. Internally stored as overall_sleep_score.
  • REM Sleep Score: Garmin’s proprietary score based on REM sleep quality. Internally stored as rem_sleep_score.
  • Sleep Duration Score: Garmin’s proprietary score based on total sleep duration. Internally stored as sleep_duration_score.
  • Sleep Quality Score: Garmin’s proprietary general sleep quality score. Internally stored as sleep_quality_score.
  • Sleep Recovery Score: Garmin’s proprietary score indicating sleep recovery quality. Internally stored as sleep_recovery_score.
  • Sleep Restlessness Score: Garmin’s proprietary score based on sleep restlessness. Internally stored as sleep_restlessness_score.
  • Interruptions Score: Garmin’s proprietary score based on sleep interruptions. Internally stored as interruptions_score.

• Sleep Restless Moments: Array of timestamps for restless moments during sleep. Each entry is a timestamp in milliseconds since epoch. Internally stored as sleep_restless_moments.

• Overnight Skin Temperature: Overnight skin temperature data, including average temperature and calibration information. Internally stored as overnight_skin_temperature. It contains the following fields:

  • Timestamp: The timestamp of the temperature measurement in milliseconds since epoch. Internally stored as timestamp.
  • Average Temperature Change: Change in average temperature from baseline in degrees Celsius. Internally stored as average_temperature_change.
  • Seven-Day Mean of Average Temperature Change: Seven-day average of temperature changes in degrees Celsius. Internally stored as seven_day_mean_of_average_temperature_change.
  • Average Temperature: Average skin temperature during sleep in degrees Celsius (range 0°C to 65°C). Internally stored as average_temperature.
  • Days Calibrated: Number of days the temperature sensor has been calibrated. Internally stored as days_calibrated.

Garmin Health SDK Logged Skin Temperature

Provides skin temperature readings in degrees Celsius, estimated using a calibrated heat flow model. Data is reported as instantaneous values with a default interval of 60 seconds.

• Status: Indicates the quality and reliability of the skin temperature measurement. Internally stored as status. Possible values are:

  Numeric Value	Name
  0	SKIN_TEMPERATURE_STATUS_UNKNOWN
  1	SKIN_TEMPERATURE_STATUS_VALID
  2	SKIN_TEMPERATURE_STATUS_INVALID

• Temperature: The skin temperature reading in degrees Celsius (range 0°C to 65°C). Internally stored as temperature.

Garmin Health SDK Logged SpO2

Measures blood oxygen saturation (SpO2). Data is reported as instantaneous values with a default interval of 60 seconds. Pulse Ox measurement is highly sensitive to motion.

• SpO2 Reading: The blood oxygen saturation (SpO2). Internally stored as spo2_reading.

Garmin Health SDK Logged Steps

Measures the number of steps taken during a one-minute interval. Data is reported as instantaneous values with a default interval of 60 seconds.

• Step Count: The number of steps recorded during the current interval. Internally stored as step_count.
• Total Steps: The cumulative total of steps recorded since the last reset. Internally stored as total_steps.
• Start Timestamp: The start time of the step counting interval. Internally stored as record_time.
• End Timestamp: The end time of the step counting interval. Internally stored as end_timestamp.

Garmin Health SDK Logged Stress

Download Sample Data

Records the Garmin stress score, a value normalized from 0 to 100. Data is reported as instantaneous values with a default interval of 60 seconds.

• Stress Score: The Garmin stress score. Internally stored as stress_score.

• Status: Helps determine the quality of the stress measurement. Internally stored as status. Possible values are:

  Numeric Value	Name
  0	STRESS_STATUS_UNKNOWN
  1	STRESS_STATUS_LARGE_MOTION
  2	STRESS_STATUS_NOT_ENOUGH_DATA
  3	STRESS_STATUS_OFF_WRIST
  4	STRESS_STATUS_RECOVERING_FROM_EXERCISE
  5	STRESS_STATUS_UNIDENTIFIED
  6	STRESS_STATUS_VALID

Garmin Health SDK Logged Wrist Status

Tracks whether the Garmin device is worn on the wrist. This data is generated every minute and whenever the wrist status changes. Logging is enabled by default when other data types are active.

• Status: Indicates whether the device is being worn on the wrist. Internally stored as status. Possible values are:

  Numeric Value	Name
  0	WRIST_STATUS_UNKNOWN
  1	WRIST_STATUS_OFF_WRIST
  2	WRIST_STATUS_ON_WRIST

Garmin Health SDK Logged Zero Crossing

Download Sample Data

Provides an algorithmic view of motion based on a count of “zero crossings” and a calculated physical power measurement. The data is aggregated with a default interval of 30 seconds.

• Zero Crossing Count: The number of zero crossings detected during the interval. Internally stored as zero_crossing_count.
• Total Energy: The total energy calculated from the motion data. Internally stored as total_energy.
• Deadband: The deadband value used in the zero crossing calculation. Internally stored as deadband.
• Start Timestamp: The start time of the zero crossing measurement interval. Internally stored as record_time.
• End Timestamp: The end time of the zero crossing measurement interval. Internally stored as end_timestamp.

Metric Configuration Options

The following table shows the default intervals and available configuration options for each Garmin SDK metric:

Metric	Default Interval/Frequency	Configurable Range	Notes
Accelerometer	25Hz continuous	Fixed (not configurable)	-
Actigraphy	30 seconds	1-30 seconds, or multiples of 30 seconds, max 1 hour	-
BBI	Continuous	Not applicable	-
Enhanced BBI	Continuous	Not applicable	-
Gyroscope	32Hz continuous	Fixed (not configurable)	-
Heart Rate	60 seconds	1 second to 1 hour	Shorter intervals recommended for detailed monitoring
Heart Rate Variability	5 minutes	Fixed (not configurable)	-
Motion Intensity	Not applicable	Not applicable	Motion intensity is calculated at minute-level granularity
MoveIQ Event	Not applicable	Not applicable	Events are triggered based on analysis of user activity
Respiration	60 seconds	1 second to 1 hour	Values may not update for intervals < 10 seconds
Sleep	Not applicable	Not applicable	Sleep data is collected automatically during sleep periods
Skin Temperature	60 seconds	1 second to 1 hour	-
SpO2	60 seconds	1 second to 1 hour	Values may not update for intervals < 10 seconds
Steps	60 seconds	Fixed (not configurable)	-
Stress	60 seconds	1 second to 1 hour	Values may not update for intervals < 10 seconds
Wrist Status	Every minute + status changes	Fixed (not configurable)	-
Zero Crossing	30 seconds	Multiples of 30 seconds, max 1 hour	-

To modify the default intervals or frequencies for your study, please contact our support team. Custom configurations can be set up based on your specific research requirements.

Data Collection Behavior

All data except for HRV is collected automatically on the watch once it is paired with the phone, and the app will sync data from the watch on certain events and at regular intervals while the watch is in proximity to the phone, the Bluetooth connection is active, and the app is running in the background or foreground. You can also manually sync data from the watch by tapping the sync button in the app, as described in the Garmin SDK Data Sources in Participant Device section.

[!note]
Considering the amount of data that is being collected, it is recommended to sync data from the watch regularly to avoid data loss.

HRV (Heart Rate Variability), however, is not directly collected on the watch. Instead, it is calculated on Avicenna server using the uploaded BBI (Beat-to-Beat Interval) data. Every 5 minutes, Avicenna checks for newly uploaded BBI data and calculates new HRV records accordingly.

Adding Garmin SDK Metrics As Data Sources

See Accessing Data Sources.

Monitoring and Exporting Garmin SDK Metrics Data

You can export and download the collected Garmin SDK metrics data using the Data Export page.

Garmin SDK Data Sources in Participant Device

To use any of these data sources, follow the instructions below.

1. Put your Garmin watch in pairing mode.
   This setting is typically found under Settings > Bluetooth or Phone > Pair Mobile Device or Pair Phone on your Garmin watch. Refer to your owner’s manual for specific steps.

2. Start the Garmin pairing process and grant Bluetooth permissions.
   If your study requires Garmin data, you will see an onboarding alert to pair your Garmin device. Tap START PAIRING button to begin. The app will then request permission to scan for Bluetooth devices, if not already granted. Tap Allow to proceed.

   
   
   

3. Select your Garmin device.
   The app will scan for nearby devices. When your Garmin watch appears in the list, select it.

   

4. Complete user settings.
   You will be asked to enter your personal information (e.g., gender, birth year, height, weight, sleep schedule). Fill in the required fields and tap Continue.

   

   [!note]
   These settings affect some of your metrics, so it is important to fill them in accurately. To modify these settings later, you will need to unpair your Garmin device and pair it again.

5. Pair the device.
   Tap Pair Device to initiate pairing.

   

6. Confirm pairing and connection.
   Once paired, your Garmin watch will appear as a connected device in the app. You can view its status and sync data as needed. By selecting your Garmin device, you will be able to view the connection status, the date and time of the last sync, and the unpairing option. You can tap Sync to manually synchronize data from your Garmin watch.