Temperature

The Temperature module provides comprehensive temperature measurement and monitoring capabilities for TopStepComKit-enabled devices. It supports both manual user-initiated temperature measurements and automatic monitoring, with real-time data streaming during measurements and historical data synchronization capabilities. The module distinguishes between body temperature (core body temperature estimates) and wrist temperature measurements.

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 via the TSHealthManager
• For automatic monitoring configuration, the device must support the TSAutoMonitorConfigs protocol

Data Models

TSTempValueItem

Temperature measurement data item representing a single temperature reading.

Property	Type	Description
temperature	CGFloat	Temperature value in Celsius. Meaning depends on temperatureType: core body temperature if TSTemperatureTypeBody, wrist temperature if TSTemperatureTypeWrist
temperatureType	TSTemperatureType	Specifies whether this is body temperature (TSTemperatureTypeBody: 36.1-37.2°C normal range) or wrist temperature (TSTemperatureTypeWrist, typically lower)
isUserInitiated	BOOL	Boolean indicating whether the measurement was user-initiated or automatically monitored
timeStamp	NSTimeInterval	Measurement timestamp (inherited from TSHealthValueItem)

TSTempDailyModel

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

Property	Type	Description
maxBodyTempItem	TSTempValueItem *	TSTempValueItem representing the highest body temperature measurement for the day (based on temperatureType being TSTemperatureTypeBody)
minBodyTempItem	TSTempValueItem *	TSTempValueItem representing the lowest body temperature measurement for the day (based on temperatureType being TSTemperatureTypeBody)
maxWristTempItem	TSTempValueItem *	TSTempValueItem representing the highest wrist temperature measurement for the day (based on temperatureType being TSTemperatureTypeWrist)
minWristTempItem	TSTempValueItem *	TSTempValueItem representing the lowest wrist temperature measurement for the day (based on temperatureType being TSTemperatureTypeWrist)
manualItems	NSArray<TSTempValueItem *>	Array of user-initiated temperature measurements, ordered by time ascending
autoItems	NSArray<TSTempValueItem *>	Array of automatically monitored temperature items, ordered by time ascending
date	NSDate *	Date representing the day (inherited from TSHealthDailyModel)

Enumerations

TSTemperatureType

Distinguishes between body temperature and wrist temperature measurements.

Value	Name	Description
0	TSTemperatureTypeBody	Body temperature — estimated core body temperature (normal range: 36.1-37.2°C)
1	TSTemperatureTypeWrist	Wrist temperature — measured at the wrist, typically lower than body temperature

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

Temperature 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];

[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 temp: %.1f°C (Type: %ld)", 
              data.temperature, (long)data.temperatureType);
    } 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 called when the measurement stops or fails to stop

**Code Example**

id<TSTemperatureInterface> tempInterface = (id<TSTemperatureInterface>)device;
[tempInterface stopMeasureCompletion:^(NSError *error) {
    if (!error) {
        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 called when the configuration is set or fails to set

**Code Example**

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

[tempInterface pushAutoMonitorConfig:config completion:^(NSError *error) {
    if (!error) {
        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) {
        TSLog(@"Current auto monitor enabled: %@", config.isEnabled ? @"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) {
        TSLog(@"Synced %lu raw temperature items", (unsigned long)items.count);
        for (TSTempValueItem *item in items) {
            TSLog(@"Temp: %.1f°C at %@", item.temperature, 
                  [NSDate dateWithTimeIntervalSince1970:item.timeStamp]);
        }
    } 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) {
        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) {
        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",
                  daily.date, 
                  [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) {
        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. **Temperature Types**: Distinguish between body temperature (core body temperature estimate, normal range 36.1-37.2°C) and wrist temperature (typically lower). Check the temperatureType property of TSTempValueItem to determine measurement type.

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**: All completion handlers are called on the main thread. Safe to update UI directly without additional synchronization.

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

8. **Monitor Schedule Support**: Check isSupportMonitorScheduleTime and isSupportMonitorScheduleInterval before configuring corresponding fields in TSAutoMonitorConfigs. Unsupported fields are ignored by the device.

9. **Data Synchronization Order**: Always synchronize data after configuration changes to ensure device and app remain in sync. Use timestamps from device to prevent duplicate or missing data.

10. **Error Handling**: Check both the returned error object and the nilness of data parameters in completion handlers. Some operations may fail partially with partial data available.