AlarmClock Module

The AlarmClock module provides comprehensive alarm clock management functionality for TopStepComKit iOS SDK. It enables reading, writing, and monitoring device alarm settings, supporting multiple alarms with individual configurations including time, repeat patterns, labels, and remarks.

Prerequisites

• Device must support alarm clock functionality (verify by checking supportMaxAlarmCount method)
• Device must be connected and authenticated
• Appropriate permissions must be granted for alarm management operations
• For devices with limited alarm storage, ensure alarm count does not exceed supportMaxAlarmCount

Data Models

TSAlarmClockModel

Represents an individual alarm clock configuration on the device.

Property	Type	Description
alarmId	UInt8	Device-side alarm unique identifier. Valid range: 0-255.
identifier	NSString *	App-side alarm identifier generated by the app for tracking purposes.
label	NSString *	Display name of the alarm (e.g., "Wake up", "Take medicine"). Maximum length: 32 bytes.
time	NSDateComponents *	Alarm time settings with hour (0-23) and minute (0-59) components.
isOn	BOOL	Alarm enable status. YES means enabled and will trigger; NO means disabled.
supportRemindLater	BOOL	Indicates whether the alarm supports snooze/remind later function.
remark	NSString *	Additional description for the alarm. Maximum length determined by supportMaxAlarmRemarkLength.
repeatOptions	TSAlarmRepeat	Bitmask specifying which days the alarm should repeat.

Enumerations

TSAlarmRepeat

Alarm repeat options using bitmask representation. Values can be combined using bitwise OR operator.

Value	Type	Description
TSAlarmRepeatNone	0	No repeat.
TSAlarmRepeatMonday	1 << 0	Repeat on Monday.
TSAlarmRepeatTuesday	1 << 1	Repeat on Tuesday.
TSAlarmRepeatWednesday	1 << 2	Repeat on Wednesday.
TSAlarmRepeatThursday	1 << 3	Repeat on Thursday.
TSAlarmRepeatFriday	1 << 4	Repeat on Friday.
TSAlarmRepeatSaturday	1 << 5	Repeat on Saturday.
TSAlarmRepeatSunday	1 << 6	Repeat on Sunday.
TSAlarmRepeatWorkday	Composite	Repeat on Monday through Friday.
TSAlarmRepeatWeekend	Composite	Repeat on Saturday and Sunday.
TSAlarmRepeatEveryday	Composite	Repeat every day (all weekdays).

Callback Types

TSAlarmClockResultBlock

typedef void(^TSAlarmClockResultBlock)(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError * _Nullable error);

Callback block for alarm clock operations.

Parameter	Type	Description
allAlarmClocks	NSArray<TSAlarmClockModel *> *	Array of alarm clocks containing all current alarm settings. Empty array if no alarms are set.
error	NSError * _Nullable	Error object if operation fails; nil if successful.

API Reference

Get Maximum Alarm Count

Returns the maximum number of alarm clocks supported by the device.

- (NSInteger)supportMaxAlarmCount;

Return Value

Type	Description
NSInteger	Maximum number of alarms supported by device. Returns 0 if device does not support alarm function. Different device models may support different numbers.

Code Example

id<TSAlarmClockInterface> alarmInterface = (id<TSAlarmClockInterface>)device;
NSInteger maxAlarms = [alarmInterface supportMaxAlarmCount];
if (maxAlarms > 0) {
    TSLog(@"Device supports up to %ld alarms", (long)maxAlarms);
} else {
    TSLog(@"Device does not support alarm function");
}

---

Get Maximum Alarm Remark Length

Returns the maximum byte length allowed for alarm remark/label.

- (NSInteger)supportMaxAlarmRemarkLength;

Return Value

Type	Description
NSInteger	Maximum byte length for alarm remark. Returns 0 if device does not support alarm remarks. Note: One Chinese character typically occupies 3 bytes in UTF-8 encoding.

Code Example

id<TSAlarmClockInterface> alarmInterface = (id<TSAlarmClockInterface>)device;
NSInteger maxRemarkLength = [alarmInterface supportMaxAlarmRemarkLength];
TSLog(@"Maximum remark length: %ld bytes", (long)maxRemarkLength);

// Validate remark before setting alarm
NSString *remark = @"吃药";
if ([remark lengthOfBytesUsingEncoding:NSUTF8StringEncoding] <= maxRemarkLength) {
    TSLog(@"Remark is valid");
} else {
    TSLog(@"Remark exceeds maximum length");
}

---

Get All Alarm Clocks

Retrieves all alarm clock settings from the device.

- (void)getAllAlarmClocksCompletion:(TSAlarmClockResultBlock)completion;

Parameters

Parameter	Type	Description
completion	TSAlarmClockResultBlock	Callback block returning all alarm clocks or error details.

Code Example

id<TSAlarmClockInterface> alarmInterface = (id<TSAlarmClockInterface>)device;
[alarmInterface getAllAlarmClocksCompletion:^(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError *error) {
    if (error) {
        TSLog(@"Failed to get alarm clocks: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"Retrieved %lu alarm clocks", (unsigned long)allAlarmClocks.count);
    for (TSAlarmClockModel *alarm in allAlarmClocks) {
        TSLog(@"Alarm ID: %d, Time: %02ld:%02ld, Enabled: %@",
              alarm.alarmId,
              (long)alarm.hour,
              (long)alarm.minute,
              alarm.isEnabled ? @"YES" : @"NO");
    }
}];

---

Set All Alarm Clocks

Synchronizes alarm clock settings to the device, overwriting all existing alarms.

- (void)setAllAlarmClocks:(NSArray<TSAlarmClockModel *> *)allAlarmClocks
               completion:(TSCompletionBlock)completion;

Parameters

Parameter	Type	Description
allAlarmClocks	NSArray<TSAlarmClockModel *> *	Array of TSAlarmClockModel objects to be set on device. Pass nil or empty array to clear all alarms.
completion	TSCompletionBlock	Callback block returning operation result and error if any.

Code Example

id<TSAlarmClockInterface> alarmInterface = (id<TSAlarmClockInterface>)device;

// Create first alarm: Monday to Friday at 07:00
TSAlarmClockModel *workdayAlarm = [[TSAlarmClockModel alloc] init];
workdayAlarm.label = @"Work";
workdayAlarm.remark = @"Morning alarm";
[workdayAlarm setHour:7 minute:0];
workdayAlarm.isOn = YES;
workdayAlarm.repeatOptions = TSAlarmRepeatWorkday;
workdayAlarm.supportRemindLater = YES;

// Create second alarm: Weekend at 09:00
TSAlarmClockModel *weekendAlarm = [[TSAlarmClockModel alloc] init];
weekendAlarm.label = @"Weekend";
[weekendAlarm setHour:9 minute:0];
weekendAlarm.isOn = YES;
weekendAlarm.repeatOptions = TSAlarmRepeatWeekend;

NSArray<TSAlarmClockModel *> *alarms = @[workdayAlarm, weekendAlarm];

[alarmInterface setAllAlarmClocks:alarms completion:^(NSError *error) {
    if (error) {
        TSLog(@"Failed to set alarms: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"Successfully set %lu alarms", (unsigned long)alarms.count);
}];

---

Register Alarm Change Notifications

Monitors device alarm clock changes and triggers callback when alarms are added, modified, or deleted.

- (void)registerAlarmClocksDidChangedBlock:(TSAlarmClockResultBlock)completion;

Parameters

Parameter	Type	Description
completion	TSAlarmClockResultBlock	Callback block triggered when alarm settings change, providing updated array of all alarms. Only one listener allowed at a time; new registration replaces previous listener.

Code Example

id<TSAlarmClockInterface> alarmInterface = (id<TSAlarmClockInterface>)device;

[alarmInterface registerAlarmClocksDidChangedBlock:^(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError *error) {
    if (error) {
        TSLog(@"Alarm monitoring failed: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"Alarm settings changed. Current alarms: %lu", (unsigned long)allAlarmClocks.count);
    for (TSAlarmClockModel *alarm in allAlarmClocks) {
        NSString *repeatDays = @"";
        if (alarm.repeatOptions & TSAlarmRepeatMonday) repeatDays = [repeatDays stringByAppendingString:@"Mon "];
        if (alarm.repeatOptions & TSAlarmRepeatFriday) repeatDays = [repeatDays stringByAppendingString:@"Fri "];
        
        TSLog(@"ID:%d | Time:%02ld:%02ld | Repeat:%@ | Enabled:%@",
              alarm.alarmId,
              (long)alarm.hour,
              (long)alarm.minute,
              repeatDays.length > 0 ? repeatDays : @"Once",
              alarm.isEnabled ? @"YES" : @"NO");
    }
}];

---

Get Alarm Hour

Returns the hour component of the alarm time.

- (NSInteger)hour;

Return Value

Type	Description
NSInteger	Hour value in 24-hour format (0-23).

Code Example

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];
[alarm setHour:14 minute:30];
NSInteger hour = [alarm hour];
TSLog(@"Alarm hour: %ld", (long)hour);  // Output: Alarm hour: 14

---

Get Alarm Minute

Returns the minute component of the alarm time.

- (NSInteger)minute;

Return Value

Type	Description
NSInteger	Minute value (0-59).

Code Example

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];
[alarm setHour:14 minute:30];
NSInteger minute = [alarm minute];
TSLog(@"Alarm minute: %ld", (long)minute);  // Output: Alarm minute: 30

---

Set Alarm Time

Sets the alarm time with hour and minute values.

- (void)setHour:(NSInteger)hour minute:(NSInteger)minute;

Parameters

Parameter	Type	Description
hour	NSInteger	Hour value in 24-hour format (0-23). Invalid values are clamped to valid range.
minute	NSInteger	Minute value (0-59). Invalid values are clamped to valid range.

Code Example

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];

// Set valid time
[alarm setHour:7 minute:30];
TSLog(@"Alarm set to %02ld:%02ld", (long)alarm.hour, (long)alarm.minute);

// Invalid values are automatically adjusted
[alarm setHour:25 minute:75];  // Will be clamped to 23:59
TSLog(@"Adjusted time: %02ld:%02ld", (long)alarm.hour, (long)alarm.minute);

// Negative values are adjusted to 0
[alarm setHour:-5 minute:-10];  // Will be clamped to 0:0
TSLog(@"Adjusted time: %02ld:%02ld", (long)alarm.hour, (long)alarm.minute);

---

Important Notes

1. Device Support Verification: Always check supportMaxAlarmCount before attempting alarm operations. A return value of 0 indicates the device does not support alarms.

2. Remark Length Validation: Before setting a remark, validate its byte length using supportMaxAlarmRemarkLength method. Chinese characters occupy 3 bytes in UTF-8 encoding.

3. Array Overwrite Behavior: setAllAlarmClocks:completion: completely overwrites device alarm settings. Passing nil or empty array will clear all existing alarms.

4. Single Listener Registration: Only one alarm change listener can be active at a time. Registering a new listener will replace any previously registered listener.

5. Time Format Validation: The setHour:minute: method automatically clamps invalid values to valid ranges (hour: 0-23, minute: 0-59).

6. Repeat Options Combination: Use bitwise OR operator to combine multiple repeat days. Example: TSAlarmRepeatMonday | TSAlarmRepeatWednesday | TSAlarmRepeatFriday.

7. Enabled/Disabled Status: The isOn property getter is named isEnabled. Use this method to check if alarm is active.

8. Device-side vs App-side IDs: The alarmId is assigned by the device (0-255 range), while identifier is created by the app for internal tracking purposes.

9. Asynchronous Operations: All network operations (getAllAlarmClocksCompletion:, setAllAlarmClocks:completion:) are asynchronous. Always handle responses in completion blocks.

10. Change Monitoring: The registerAlarmClocksDidChangedBlock: callback may be triggered by changes initiated from the device itself or other connected clients, not just from the current app instance.