Heart Rate

The Heart Rate module provides comprehensive methods for heart rate measurement, automatic monitoring, historical data synchronization, and resting heart rate analysis on connected wearable devices.

Prerequisites

• A wearable device connected via the TopStepComKit SDK
• The device must support at least one of the heart rate features (measurement, monitoring, or resting heart rate tracking)
• Proper initialization and delegation of the health data interface
• For automatic monitoring: device must support automatic heart rate monitoring capability
• For daily data synchronization: valid timestamp parameters in seconds since 1970

Data Models

TSHRValueItem

Single heart rate measurement sample with timing information and classification.

Property	Type	Description
hrValue	UInt8	Heart rate value in beats per minute (BPM)
isUserInitiated	BOOL	Indicates whether the measurement was initiated by the user
startTime	NSTimeInterval	Start time of the measurement (inherited from TSHealthValueItem)
endTime	NSTimeInterval	End time of the measurement (inherited from TSHealthValueItem)
duration	NSTimeInterval	Duration of the measurement (inherited from TSHealthValueItem)
valueType	TSItemValueType	Classification of the value: normal, maximum, minimum, or resting (inherited from TSHealthValueItem)

TSHRDailyModel

Per-day aggregated heart rate data with maximum, minimum, and resting measurements.

Property	Type	Description
maxHRItem	TSHRValueItem *	Maximum heart rate item of the day
minHRItem	TSHRValueItem *	Minimum heart rate item of the day
restingItems	NSArray<TSHRValueItem *> *	Array of resting heart rate items, ordered by time ascending
manualItems	NSArray<TSHRValueItem *> *	Array of user-initiated heart rate measurements, ordered by time ascending
autoItems	NSArray<TSHRValueItem *> *	Array of automatically monitored heart rate items, ordered by time ascending

Enumerations

No specific enumerations are defined for the Heart Rate module. The module uses TSItemValueType (inherited from parent class) to distinguish between normal, maximum, minimum, and resting heart rate values.

Callback Types

TSCompletionBlock

typedef void (^TSCompletionBlock)(NSError * _Nullable error);

Standard completion callback for operations that only return success/failure status.

Parameter	Type	Description
error	NSError *	Error information if the operation failed; nil if successful

Heart Rate Measurement Start Handler

void (^)(BOOL success, NSError * _Nullable error)

Callback for when heart rate measurement starts or fails to start.

Parameter	Type	Description
success	BOOL	Whether the measurement started successfully
error	NSError *	Error information if failed; nil if successful

Heart Rate Measurement Data Handler

void (^)(TSHRValueItem * _Nullable data, NSError * _Nullable error)

Callback to receive real-time measurement data during ongoing measurement.

Parameter	Type	Description
data	TSHRValueItem *	Real-time heart rate measurement data; nil if error occurs
error	NSError *	Error information if data reception fails; nil if successful

Heart Rate Measurement End Handler

void (^)(BOOL success, NSError * _Nullable error)

Callback when heart rate measurement ends normally or abnormally.

Parameter	Type	Description
success	BOOL	Whether the measurement ended normally (YES) or was interrupted (NO)
error	NSError *	Error information if measurement ended abnormally; nil if normal end

Auto Monitor Configs Handler

void (^)(TSAutoMonitorHRConfigs * _Nullable configuration, NSError * _Nullable error)

Callback for fetching current automatic monitoring configuration.

Parameter	Type	Description
configuration	TSAutoMonitorHRConfigs *	Current automatic heart rate monitoring configuration
error	NSError *	Error information if fetch failed; nil if successful

Raw Heart Rate Data Handler

void (^)(NSArray<TSHRValueItem *> * _Nullable hrItems, NSError * _Nullable error)

Callback for synchronizing raw heart rate data.

Parameter	Type	Description
hrItems	NSArray<TSHRValueItem *> *	Array of synchronized raw heart rate items
error	NSError *	Error information if sync failed; nil if successful

Daily Heart Rate Data Handler

void (^)(NSArray<TSHRDailyModel *> * _Nullable dailyModels, NSError * _Nullable error)

Callback for synchronizing daily aggregated heart rate data.

Parameter	Type	Description
dailyModels	NSArray<TSHRDailyModel *> *	Array of daily heart rate models
error	NSError *	Error information if sync failed; nil if successful

Today Resting Heart Rate Handler

void (^)(TSHRValueItem * _Nullable todayRestingHR, NSError * _Nullable error)

Callback for synchronizing today's resting heart rate data.

Parameter	Type	Description
todayRestingHR	TSHRValueItem *	Today's resting heart rate data
error	NSError *	Error information if sync failed; nil if successful

API Reference

Check if device supports heart rate alert monitoring

Check whether the connected device can notify users when their heart rate exceeds normal ranges or reaches potentially dangerous levels.

- (BOOL)isSupportHeartRateAlert;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports heart rate alert monitoring, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsAlert = [hrInterface isSupportHeartRateAlert];
if (supportsAlert) {
    TSLog(@"Device supports heart rate alert monitoring");
}

---

Check if device supports enhanced heart rate monitoring

Verify if the device can perform more frequent and accurate heart rate measurements with higher precision.

- (BOOL)isSupportEnhancedMonitoring;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports enhanced heart rate monitoring, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsEnhanced = [hrInterface isSupportEnhancedMonitoring];
if (supportsEnhanced) {
    TSLog(@"Device supports enhanced heart rate monitoring");
}

---

Check if device supports manual heart rate measurement

Determine if users can manually initiate heart rate measurements on the device.

- (BOOL)isSupportActivityMeasureByUser;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports manual measurement, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsManual = [hrInterface isSupportActivityMeasureByUser];
if (supportsManual) {
    TSLog(@"User can initiate manual measurements");
}

---

Start heart rate measurement with specified parameters

Begin a heart rate measurement session with real-time data callbacks and completion handlers.

- (void)startMeasureWithParam:(TSActivityMeasureParam *_Nonnull)measureParam
                 startHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))startHandler
                  dataHandler:(void(^_Nullable)(TSHRValueItem * _Nullable data, NSError * _Nullable error))dataHandler
                   endHandler:(void(^_Nullable)(BOOL success, NSError * _Nullable error))endHandler;

Parameter	Type	Description
measureParam	TSActivityMeasureParam *	Configuration parameters for the measurement activity
startHandler	void (^)(BOOL, NSError *)	Block called when measurement starts or fails to start
dataHandler	void (^)(TSHRValueItem *, NSError *)	Block to receive real-time measurement data
endHandler	void (^)(BOOL, NSError *)	Block called when measurement ends normally or abnormally

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];

[hrInterface startMeasureWithParam:param
                      startHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"Measurement started successfully");
    } else {
        TSLog(@"Failed to start measurement: %@", error.localizedDescription);
    }
} dataHandler:^(TSHRValueItem * _Nullable data, NSError * _Nullable error) {
    if (data) {
        TSLog(@"Real-time HR: %d BPM", data.hrValue);
    } else {
        TSLog(@"Data reception error: %@", error.localizedDescription);
    }
} endHandler:^(BOOL success, NSError * _Nullable error) {
    if (success) {
        TSLog(@"Measurement completed normally");
    } else {
        TSLog(@"Measurement interrupted: %@", error.localizedDescription);
    }
}];

---

Stop the ongoing heart rate measurement

Terminate a currently active heart rate measurement session.

- (void)stopMeasureCompletion:(nonnull TSCompletionBlock)completion;

Parameter	Type	Description
completion	TSCompletionBlock	Block called when the measurement stops or fails to stop

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;

[hrInterface stopMeasureCompletion:^(NSError * _Nullable error) {
    if (!error) {
        TSLog(@"Measurement stopped successfully");
    } else {
        TSLog(@"Failed to stop measurement: %@", error.localizedDescription);
    }
}];

---

Check if device supports automatic heart rate monitoring

Verify if the device can automatically monitor heart rate at specified intervals.

- (BOOL)isSupportAutomaticMonitoring;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports automatic monitoring, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsAutoMonitoring = [hrInterface isSupportAutomaticMonitoring];
if (supportsAutoMonitoring) {
    TSLog(@"Automatic heart rate monitoring is supported");
}

---

Check if device supports resting heart rate alert

Determine if the device can alert users when resting heart rate is abnormal.

- (BOOL)isSupportRestHRAlert;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports resting heart rate alerts, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsRestAlert = [hrInterface isSupportRestHRAlert];
if (supportsRestAlert) {
    TSLog(@"Resting heart rate alert is supported");
}

---

Check if device supports exercise heart rate alert

Verify if the device can alert when exercise heart rate is abnormal.

- (BOOL)isSupportExerciseHRAlert;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports exercise heart rate alerts, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsExerciseAlert = [hrInterface isSupportExerciseHRAlert];
if (supportsExerciseAlert) {
    TSLog(@"Exercise heart rate alert is supported");
}

---

Check if device supports configuring monitor time range

Determine if the device allows configuration of start and end times for heart rate monitoring.

- (BOOL)isSupportMonitorScheduleTime;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports monitoring time range configuration, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsTimeRange = [hrInterface isSupportMonitorScheduleTime];
if (supportsTimeRange) {
    TSLog(@"Device supports monitoring time range configuration");
}

---

Check if device supports configuring monitor interval

Verify if the device allows configuration of the monitoring interval for automatic heart rate measurements.

- (BOOL)isSupportMonitorScheduleInterval;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports monitoring interval configuration, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsInterval = [hrInterface isSupportMonitorScheduleInterval];
if (supportsInterval) {
    TSLog(@"Device supports monitoring interval configuration");
}

---

Configure automatic heart rate monitoring

Set up automatic heart rate monitoring parameters on the connected device.

- (void)pushAutoMonitorConfigs:(TSAutoMonitorHRConfigs *_Nonnull)configuration
                      completion:(nonnull TSCompletionBlock)completion;

Parameter	Type	Description
configuration	TSAutoMonitorHRConfigs *	Configuration parameters for automatic heart rate monitoring
completion	TSCompletionBlock	Block called when configuration is applied or fails

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
TSAutoMonitorHRConfigs *config = [[TSAutoMonitorHRConfigs alloc] init];
config.enable = YES;

[hrInterface pushAutoMonitorConfigs:config completion:^(NSError * _Nullable error) {
    if (!error) {
        TSLog(@"Auto monitoring configuration applied successfully");
    } else {
        TSLog(@"Failed to apply configuration: %@", error.localizedDescription);
    }
}];

---

Get the current automatic heart rate monitoring configuration

Retrieve the existing automatic monitoring configuration from the connected device.

- (void)fetchAutoMonitorConfigsWithCompletion:(nonnull void (^)(TSAutoMonitorHRConfigs *_Nullable configuration, NSError *_Nullable error))completion;

Parameter	Type	Description
completion	void (^)(TSAutoMonitorHRConfigs *, NSError *)	Block with current configuration or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;

[hrInterface fetchAutoMonitorConfigsWithCompletion:^(TSAutoMonitorHRConfigs * _Nullable configuration, NSError * _Nullable error) {
    if (configuration) {
        TSLog(@"Current auto monitoring enabled: %@", configuration.enable ? @"YES" : @"NO");
    } else {
        TSLog(@"Failed to fetch configuration: %@", error.localizedDescription);
    }
}];

---

Synchronize raw heart rate data within a specified time range

Retrieve raw heart rate measurement samples from the device within a specific time period.

- (void)syncRawDataFromStartTime:(NSTimeInterval)startTime
                         endTime:(NSTimeInterval)endTime
                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable hrItems, NSError *_Nullable error))completion;

Parameter	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (seconds since 1970)
endTime	NSTimeInterval	End time for data synchronization (seconds since 1970)
completion	void (^)(NSArray<TSHRValueItem *> *, NSError *)	Block with synchronized raw heart rate items or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-86400] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[hrInterface syncRawDataFromStartTime:startTime endTime:endTime 
                           completion:^(NSArray<TSHRValueItem *> * _Nullable hrItems, NSError * _Nullable error) {
    if (hrItems) {
        TSLog(@"Synchronized %lu raw HR samples", (unsigned long)hrItems.count);
        for (TSHRValueItem *item in hrItems) {
            TSLog(@"  HR: %d BPM at %.0f", item.hrValue, item.startTime);
        }
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Synchronize raw heart rate data from a specified start time until now

Retrieve all raw heart rate measurements from the specified start time to the current time.

- (void)syncRawDataFromStartTime:(NSTimeInterval)startTime
                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable hrItems, NSError *_Nullable error))completion;

Parameter	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (seconds since 1970)
completion	void (^)(NSArray<TSHRValueItem *> *, NSError *)	Block with synchronized raw heart rate items or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-604800] timeIntervalSince1970];

[hrInterface syncRawDataFromStartTime:startTime 
                           completion:^(NSArray<TSHRValueItem *> * _Nullable hrItems, NSError * _Nullable error) {
    if (hrItems) {
        TSLog(@"Synchronized %lu raw HR samples from start time to now", (unsigned long)hrItems.count);
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Synchronize daily heart rate data within a specified time range

Retrieve aggregated daily heart rate data (including max, min, resting, manual, and automatic measurements) for the specified date range.

- (void)syncDailyDataFromStartTime:(NSTimeInterval)startTime
                           endTime:(NSTimeInterval)endTime
                        completion:(nonnull void (^)(NSArray<TSHRDailyModel *> *_Nullable dailyModels, NSError *_Nullable error))completion;

Parameter	Type	Description
startTime	NSTimeInterval	Start time normalized to 00:00:00 of specified day (seconds since 1970)
endTime	NSTimeInterval	End time normalized to 23:59:59 of specified day (seconds since 1970)
completion	void (^)(NSArray<TSHRDailyModel *> *, NSError *)	Block with daily models or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
NSDate *sevenDaysAgo = [NSDate dateWithTimeIntervalSinceNow:-604800];
NSDate *today = [NSDate date];

[hrInterface syncDailyDataFromStartTime:[sevenDaysAgo timeIntervalSince1970]
                                endTime:[today timeIntervalSince1970]
                             completion:^(NSArray<TSHRDailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (dailyModels) {
        TSLog(@"Synchronized %lu days of HR data", (unsigned long)dailyModels.count);
        for (TSHRDailyModel *daily in dailyModels) {
            TSLog(@"  Day max: %d BPM, min: %d BPM, resting items: %lu", 
                  [daily maxBPM], [daily minBPM], (unsigned long)daily.restingItems.count);
        }
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Synchronize daily heart rate data from a specified start time until now

Retrieve aggregated daily heart rate data from the specified start date to the current date.

- (void)syncDailyDataFromStartTime:(NSTimeInterval)startTime
                        completion:(nonnull void (^)(NSArray<TSHRDailyModel *> *_Nullable dailyModels, NSError *_Nullable error))completion;

Parameter	Type	Description
startTime	NSTimeInterval	Start time normalized to 00:00:00 of specified day (seconds since 1970)
completion	void (^)(NSArray<TSHRDailyModel *> *, NSError *)	Block with daily models or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
NSDate *thirtyDaysAgo = [NSDate dateWithTimeIntervalSinceNow:-2592000];

[hrInterface syncDailyDataFromStartTime:[thirtyDaysAgo timeIntervalSince1970]
                             completion:^(NSArray<TSHRDailyModel *> * _Nullable dailyModels, NSError * _Nullable error) {
    if (dailyModels) {
        TSLog(@"Synchronized %lu days of HR data from start to now", (unsigned long)dailyModels.count);
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Check if device supports resting heart rate monitoring

Determine if the connected device can measure and track resting heart rate during periods of complete rest.

- (BOOL)isSupportRestingHeartRate;

Parameter	Type	Description

Return Value: BOOL — YES if the device supports resting heart rate monitoring, NO otherwise

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
BOOL supportsResting = [hrInterface isSupportRestingHeartRate];
if (supportsResting) {
    TSLog(@"Device supports resting heart rate monitoring");
}

---

Synchronize raw resting heart rate data within a specified time range

Retrieve raw resting heart rate measurements from the device within a specific time period.

- (void)syncRawRestingHeartRateDataFromStartTime:(NSTimeInterval)startTime
                                         endTime:(NSTimeInterval)endTime
                                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable restingHRItems, NSError *_Nullable error))completion;

Parameter	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (seconds since 1970)
endTime	NSTimeInterval	End time for data synchronization (seconds since 1970)
completion	void (^)(NSArray<TSHRValueItem *> *, NSError *)	Block with resting HR items or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-86400] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[hrInterface syncRawRestingHeartRateDataFromStartTime:startTime endTime:endTime
                                           completion:^(NSArray<TSHRValueItem *> * _Nullable restingHRItems, NSError * _Nullable error) {
    if (restingHRItems) {
        TSLog(@"Synchronized %lu resting HR samples", (unsigned long)restingHRItems.count);
        for (TSHRValueItem *item in restingHRItems) {
            TSLog(@"  Resting HR: %d BPM at %.0f", item.hrValue, item.startTime);
        }
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Synchronize raw resting heart rate data from a specified start time until now

Retrieve all resting heart rate measurements from the specified start time to the current time.

- (void)syncRawRestingHeartRateDataFromStartTime:(NSTimeInterval)startTime
                                      completion:(nonnull void (^)(NSArray<TSHRValueItem *> *_Nullable restingHRItems, NSError *_Nullable error))completion;

Parameter	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (seconds since 1970)
completion	void (^)(NSArray<TSHRValueItem *> *, NSError *)	Block with resting HR items or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-604800] timeIntervalSince1970];

[hrInterface syncRawRestingHeartRateDataFromStartTime:startTime
                                           completion:^(NSArray<TSHRValueItem *> * _Nullable restingHRItems, NSError * _Nullable error) {
    if (restingHRItems) {
        TSLog(@"Synchronized %lu resting HR samples from start to now", (unsigned long)restingHRItems.count);
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Synchronize today's resting heart rate data

Retrieve the current day's resting heart rate measurements and aggregated data.

- (void)syncTodayRestingHeartRateDataWithCompletion:(nonnull void (^)(TSHRValueItem *_Nullable todayRestingHR, NSError *_Nullable error))completion;

Parameter	Type	Description
completion	void (^)(TSHRValueItem *, NSError *)	Block with today's resting HR data or error

Code Example:

id<TSHeartRateInterface> hrInterface = (id<TSHeartRateInterface>)healthInterface;

[hrInterface syncTodayRestingHeartRateDataWithCompletion:^(TSHRValueItem * _Nullable todayRestingHR, NSError * _Nullable error) {
    if (todayRestingHR) {
        TSLog(@"Today's resting HR: %d BPM at %.0f", todayRestingHR.hrValue, todayRestingHR.startTime);
    } else {
        TSLog(@"Sync failed: %@", error.localizedDescription);
    }
}];

---

Important Notes

1. **Capability Checking**: Always call the appropriate isSupport* methods before attempting to use a feature. Different devices may support different heart rate capabilities.

2. **Measurement Parameters**: When starting a measurement, ensure TSActivityMeasureParam is properly configured with valid values before passing to startMeasureWithParam:.

3. **Time Values**: All timestamp parameters use seconds since 1970 (Unix epoch). Convert NSDate objects appropriately using timeIntervalSince1970.

4. **Daily Data Normalization**: The syncDailyData* methods automatically normalize time boundaries to day start (00:00:00) and end (23:59:59). Exact hour/minute values are adjusted automatically.

5. **Alert Configuration Validation**: Before configuring alert thresholds in TSAutoMonitorHRConfigs, verify support using isSupportRestHRAlert and isSupportExerciseHRAlert methods.

6. **Real-time Data Callbacks**: The dataHandler in startMeasureWithParam: is called for each real-time measurement. Handle both data and error cases separately.

7. **Data Ordering**: Returned arrays (hourly, daily, manual, auto items) are sorted in ascending time order by default.

8. **Completion Handler Threading**: All completion handlers are called on the main thread. Update UI directly without additional dispatch.

9. **Network Connectivity**: Device synchronization methods require an active connection. Ensure the device is connected before initiating sync operations.

10. **Data Persistence**: Use the valueType property of TSHRValueItem to distinguish between normal measurements, maximum/minimum readings, and resting heart rate values in your data processing logic.