Temperature

The Temperature module provides manual measurement, automatic monitoring, real-time data, and historical synchronization. One sampling event can contain both body and wrist temperature, and the SDK represents that event with one TSTempValueItem rather than two records with the same timestamp.

Prerequisites

• Device must support temperature measurement features (verify with isSupportActivityMeasureByUser and isSupportAutomaticMonitoring)
• User must have granted necessary health and device permissions
• Device must be connected and initialized through TopStepComKit
• For automatic monitoring configuration, the device must support the corresponding schedule capabilities

Data Models

TSTempValueItem

Temperature data for one sampling event. Body and wrist values from that event remain paired in the same item.

Property	Type	Description
bodyTemperature	CGFloat	Body temperature in Celsius. A positive number is valid; 0 means body temperature is unavailable for this sample
wristTemperature	CGFloat	Wrist temperature in Celsius. A positive number is valid; 0 means wrist temperature is unavailable for this sample
isUserInitiated	BOOL	Boolean indicating whether the measurement was user-initiated or automatically monitored
startTime	NSTimeInterval	Sampling start timestamp in seconds since 1970 (inherited from TSHealthValueItem)

bodyTemperature and wristTemperature can both be valid, or only one can be valid. The item has no valid temperature only when both fields are 0.

This release changes the temperature model to paired fields and is a breaking change. After upgrading, read bodyTemperature and wristTemperature directly.

TSTempDailyModel

Daily aggregated temperature data model containing statistics and item collections for a single day.

Property	Type	Description
maxBodyTempItem	TSTempValueItem *	Sample with the day's highest positive bodyTemperature, calculated independently from wrist values
minBodyTempItem	TSTempValueItem *	Sample with the day's lowest positive bodyTemperature, calculated independently from wrist values
maxWristTempItem	TSTempValueItem *	Sample with the day's highest positive wristTemperature, calculated independently from body values
minWristTempItem	TSTempValueItem *	Sample with the day's lowest positive wristTemperature, calculated independently from body values
manualItems	NSArray<TSTempValueItem *> *	User-initiated sampling events in ascending time order; a paired sample appears once
autoItems	NSArray<TSTempValueItem *> *	Automatically monitored sampling events in ascending time order; a paired sample appears once
startTime	NSTimeInterval	Start timestamp of the represented day (inherited from TSHealthDailyModel)

Callback Types

Temperature Measurement Start Handler

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

Called when temperature 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

Temperature Measurement Data Handler

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

Called to receive real-time measurement data during active temperature measurement.

Parameter	Type	Description
data	TSTempValueItem *	Real-time temperature measurement data, nil if error occurs
error	NSError *	Error information if data reception fails, nil if successful

Temperature Measurement End Handler

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

Called when temperature 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

Operation Completion Block (TSCompletionBlock)

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

Used by stopMeasureCompletion: and pushAutoMonitorConfig:completion:.

Parameter	Type	Description
isSuccess	BOOL	Whether the operation completed successfully
error	NSError *	Error information if the operation failed, nil on success

Raw Temperature Sync Completion Block

void (^)(NSArray<TSTempValueItem *> *_Nullable tempItems, NSError *_Nullable error)

Completion block returning synchronized temperature measurement items or error.

Parameter	Type	Description
tempItems	NSArray<TSTempValueItem *> *	Array of synchronized temperature items, nil if error occurs
error	NSError *	Error information if synchronization fails, nil if successful

Daily Temperature Completion Block

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

Completion block returning synchronized daily temperature models or error.

Parameter	Type	Description
dailyModels	NSArray<TSTempDailyModel *> *	Array of synchronized daily temperature models, nil if error occurs
error	NSError *	Error information if synchronization fails, nil if successful

Auto Monitor Config Completion Block

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

Completion block returning current automatic monitoring configuration or error.

Parameter	Type	Description
configuration	TSAutoMonitorConfigs *	Current automatic monitoring configuration, nil if error occurs
error	NSError *	Error information if fetch fails, nil if successful

API Reference

Check if device supports manual temperature measurement

Verifies whether the connected device supports user-initiated temperature measurements.

- (BOOL)isSupportActivityMeasureByUser;

Return Value

Type	Description
BOOL	YES if the device supports manual temperature measurement, NO otherwise

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
if ([tempInterface isSupportActivityMeasureByUser]) {
    TSLog(@"Device supports manual temperature measurement");
} else {
    TSLog(@"Device does not support manual temperature measurement");
}

Start temperature measurement

Initiates a temperature measurement with specified parameters and receives real-time data and completion status.

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

Parameters

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

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
TSActivityMeasureParam *param = [[TSActivityMeasureParam alloc] init];
param.measureType = TSMeasureTypeTemperature;

[tempInterface startMeasureWithParam:param
                       startHandler:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Temperature measurement started successfully");
    } else {
        TSLog(@"Failed to start measurement: %@", error.localizedDescription);
    }
} dataHandler:^(TSTempValueItem *data, NSError *error) {
    if (data) {
        TSLog(@"Real-time body: %.1f°C, wrist: %.1f°C",
              data.bodyTemperature, data.wristTemperature);
    } else {
        TSLog(@"Data reception error: %@", error.localizedDescription);
    }
} endHandler:^(BOOL success, NSError *error) {
    if (success) {
        TSLog(@"Temperature measurement completed normally");
    } else {
        TSLog(@"Measurement interrupted: %@", error.localizedDescription);
    }
}];

Stop temperature measurement

Stops the ongoing temperature measurement process.

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

Parameters

Name	Type	Description
completion	TSCompletionBlock	Completion block with isSuccess and error when the measurement stops or fails to stop

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
[tempInterface stopMeasureCompletion:^(BOOL isSuccess, NSError *error) {
    if (isSuccess) {
        TSLog(@"Temperature measurement stopped successfully");
    } else {
        TSLog(@"Failed to stop measurement: %@", error.localizedDescription);
    }
}];

Check if device supports automatic temperature monitoring

Verifies whether the connected device supports automatic temperature monitoring.

- (BOOL)isSupportAutomaticMonitoring;

Return Value

Type	Description
BOOL	YES if the device supports automatic temperature monitoring, NO otherwise

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
if ([tempInterface isSupportAutomaticMonitoring]) {
    TSLog(@"Device supports automatic temperature monitoring");
} else {
    TSLog(@"Device does not support automatic temperature monitoring");
}

Check if device supports configuring monitor time range

Verifies whether the device supports configuring start and end times for temperature monitoring.

- (BOOL)isSupportMonitorScheduleTime;

Return Value

Type	Description
BOOL	YES if the device supports configuring start/end time for temperature monitoring, NO otherwise

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
if ([tempInterface isSupportMonitorScheduleTime]) {
    TSLog(@"Device supports monitor schedule time configuration");
}

Check if device supports configuring monitor interval

Verifies whether the device supports configuring the monitoring interval for temperature measurements.

- (BOOL)isSupportMonitorScheduleInterval;

Return Value

Type	Description
BOOL	YES if the device supports configuring monitoring interval, NO otherwise

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
if ([tempInterface isSupportMonitorScheduleInterval]) {
    TSLog(@"Device supports monitor schedule interval configuration");
}

Configure automatic temperature monitoring

Sets up automatic temperature monitoring with specified configuration parameters.

- (void)pushAutoMonitorConfig:(TSAutoMonitorConfigs *_Nonnull)configuration
                   completion:(nonnull TSCompletionBlock)completion;

Parameters

Name	Type	Description
configuration	TSAutoMonitorConfigs *	Configuration parameters for automatic monitoring
completion	TSCompletionBlock	Completion block with isSuccess and error when the configuration is set or fails to set

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
TSAutoMonitorConfigs *config = [[TSAutoMonitorConfigs alloc] init];
config.schedule.enabled = YES;

[tempInterface pushAutoMonitorConfig:config completion:^(BOOL isSuccess, NSError *error) {
    if (isSuccess) {
        TSLog(@"Auto monitor configuration set successfully");
    } else {
        TSLog(@"Failed to set configuration: %@", error.localizedDescription);
    }
}];

Get current automatic temperature monitoring configuration

Retrieves the current automatic temperature monitoring configuration from the device.

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

Parameters

Name	Type	Description
completion	void (^)(TSAutoMonitorConfigs *, NSError *)	Completion block with the current configuration or error

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
[tempInterface fetchAutoMonitorConfigsWithCompletion:^(TSAutoMonitorConfigs *config, NSError *error) {
    if (config && !error) {
        TSLog(@"Current auto monitor enabled: %@", config.schedule.enabled ? @"YES" : @"NO");
    } else {
        TSLog(@"Failed to fetch configuration: %@", error.localizedDescription);
    }
}];

Synchronize raw temperature data within time range

Synchronizes raw temperature measurement data for a specified time range.

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

Parameters

Name	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (timestamp in seconds since 1970)
endTime	NSTimeInterval	End time for data synchronization (timestamp in seconds since 1970)
completion	void (^)(NSArray<TSTempValueItem *> *, NSError *)	Completion block with synchronized raw temperature items or error

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-86400] timeIntervalSince1970];
NSTimeInterval endTime = [[NSDate date] timeIntervalSince1970];

[tempInterface syncRawDataFromStartTime:startTime 
                                endTime:endTime 
                             completion:^(NSArray<TSTempValueItem *> *items, NSError *error) {
    if (items && !error) {
        TSLog(@"Synced %lu raw temperature items", (unsigned long)items.count);
        for (TSTempValueItem *item in items) {
            TSLog(@"Body: %.1f°C, wrist: %.1f°C at %@",
                  item.bodyTemperature, item.wristTemperature,
                  [NSDate dateWithTimeIntervalSince1970:item.startTime]);
        }
    } else {
        TSLog(@"Failed to sync raw data: %@", error.localizedDescription);
    }
}];

Synchronize raw temperature data from start time to now

Synchronizes raw temperature measurement data from a specified start time until the current time.

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

Parameters

Name	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (timestamp in seconds since 1970)
completion	void (^)(NSArray<TSTempValueItem *> *, NSError *)	Completion block with synchronized raw temperature items or error

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
NSTimeInterval startTime = [[NSDate dateWithTimeIntervalSinceNow:-604800] timeIntervalSince1970];

[tempInterface syncRawDataFromStartTime:startTime 
                             completion:^(NSArray<TSTempValueItem *> *items, NSError *error) {
    if (items && !error) {
        TSLog(@"Synced %lu raw temperature items from past 7 days", (unsigned long)items.count);
    } else {
        TSLog(@"Failed to sync: %@", error.localizedDescription);
    }
}];

Synchronize daily temperature data within time range

Synchronizes aggregated daily temperature data for a specified time range. Time parameters are automatically normalized to day boundaries.

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

Parameters

Name	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (timestamp in seconds since 1970). Automatically normalized to 00:00:00 of the specified day. Must be earlier than endTime.
endTime	NSTimeInterval	End time for data synchronization (timestamp in seconds since 1970). Automatically normalized to 23:59:59 of the specified day. Must be later than startTime and not in the future.
completion	void (^)(NSArray<TSTempDailyModel *> *, NSError *)	Completion block with synchronized daily temperature models or error. Each TSTempDailyModel represents one day's aggregated data.

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
NSDate *sevenDaysAgo = [NSDate dateWithTimeIntervalSinceNow:-604800];
NSDate *today = [NSDate date];

[tempInterface syncDailyDataFromStartTime:[sevenDaysAgo timeIntervalSince1970]
                                  endTime:[today timeIntervalSince1970]
                               completion:^(NSArray<TSTempDailyModel *> *dailyModels, NSError *error) {
    if (dailyModels && !error) {
        TSLog(@"Synced %lu days of temperature data", (unsigned long)dailyModels.count);
        for (TSTempDailyModel *daily in dailyModels) {
            TSLog(@"Date: %@, Max Body: %.1f°C, Min Body: %.1f°C",
                  [NSDate dateWithTimeIntervalSince1970:daily.startTime],
                  [daily maxBodyTemperature], 
                  [daily minBodyTemperature]);
        }
    } else {
        TSLog(@"Failed to sync daily data: %@", error.localizedDescription);
    }
}];

Synchronize daily temperature data from start time to now

Synchronizes aggregated daily temperature data from a specified start time until the current time. Time parameters are automatically normalized to day boundaries.

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

Parameters

Name	Type	Description
startTime	NSTimeInterval	Start time for data synchronization (timestamp in seconds since 1970). Automatically normalized to 00:00:00 of the specified day. Data will be synchronized from this time to the current time.
completion	void (^)(NSArray<TSTempDailyModel *> *, NSError *)	Completion block with synchronized daily temperature models or error. Each TSTempDailyModel represents one day's aggregated data.

Code Example

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
NSDate *thirtyDaysAgo = [NSDate dateWithTimeIntervalSinceNow:-2592000];

[tempInterface syncDailyDataFromStartTime:[thirtyDaysAgo timeIntervalSince1970]
                               completion:^(NSArray<TSTempDailyModel *> *dailyModels, NSError *error) {
    if (dailyModels && !error) {
        TSLog(@"Synced %lu days of temperature data up to today", (unsigned long)dailyModels.count);
        
        TSTempDailyModel *lastDay = [dailyModels lastObject];
        TSLog(@"Latest day - Max Body: %.1f°C, Min Wrist: %.1f°C",
              [lastDay maxBodyTemperature],
              [lastDay minWristTemperature]);
    } else {
        TSLog(@"Failed to sync daily data: %@", error.localizedDescription);
    }
}];

Important Notes

1. Device support verification: Always check device capabilities using isSupportActivityMeasureByUser and isSupportAutomaticMonitoring before calling measurement or monitoring methods. Not all devices support all features.

2. Paired values: One TSTempValueItem represents one sampling event. Body and wrist temperature can both be present; 0 means only that component is unavailable.

3. Real-time data streaming: During active measurement, the dataHandler callback receives real-time data. Process this data immediately in the callback for responsive UI updates.

4. Measurement state management: Only one measurement can be active at a time. Call stopMeasureCompletion: before starting a new measurement to avoid conflicts.

5. Time normalization: The syncDailyDataFromStartTime:endTime:completion: and syncDailyDataFromStartTime:completion: methods automatically normalize time parameters to day boundaries (00:00:00 to 23:59:59). Provide any time within the desired day.

6. Completion handler threading: Daily synchronization completion handlers are called on the main thread, as documented by TSTemperatureInterface.

7. Historical data organization: Daily models contain aggregated data including minimum/maximum readings and separate arrays for manual and automatic measurements. Use allMeasuredItems to get combined time-ordered data.

8. Monitor schedule support: Check isSupportMonitorScheduleTime and isSupportMonitorScheduleInterval before configuring the corresponding TSMonitorSchedule fields.

9. Data synchronization order: Daily models are returned in ascending time order. Each daily model also keeps its manual and automatic samples in ascending time order.

10. Error handling: Check both the returned error object and the returned data in completion handlers.

11. Model migration: The temperature model only exposes bodyTemperature and wristTemperature. Update every model read site when upgrading the SDK.