AlarmClock Module

The AlarmClock module provides comprehensive management of device alarm clock settings, including reading, writing, and monitoring alarm configurations. It supports multiple alarms with customizable repeat patterns, snooze functionality, and labels. The module handles automatic ID assignment for new alarms and validates all alarm configurations before synchronization with the device.

Prerequisites

The device must be connected and ready for communication
The device firmware must support alarm clock functionality
Check supportMaxAlarmCount before attempting to add new alarms
Verify supportMaxAlarmLabelLength before setting alarm labels
Use supportAlarmSnooze to determine if the device supports snooze features

Data Models

TSAlarmClockModel

Represents a single alarm clock configuration on the device.

Property	Type	Description
`alarmId`	`UInt8`	Device-side alarm identifier. Valid range: [0, supportMaxAlarmCount). Do not set when adding; must be set when updating or deleting.
`identifier`	`NSString *`	App-side alarm identifier generated by the app for tracking purposes.
`label`	`NSString *`	Display name/label for the alarm (e.g., "Wake up", "Take medicine"). Maximum byte length obtained from `supportMaxAlarmLabelLength`.
`time`	`NSDateComponents *`	Alarm time settings with hour (0-23) and minute (0-59) properties.
`enable`	`BOOL`	Whether the alarm is active. YES = enabled and will trigger, NO = disabled.
`snoozeEnable`	`BOOL`	Whether snooze function is enabled. Only effective if device supports snooze.
`snoozeInterval`	`NSUInteger`	Snooze interval in minutes. Only effective when `snoozeEnable` is YES.
`snoozeRepeatCount`	`NSUInteger`	Number of times snooze will repeat. Only effective when `snoozeEnable` is YES.
`repeatOptions`	`TSAlarmRepeat`	Bitmask specifying which days the alarm should repeat. Combine multiple `TSAlarmRepeat` values.

Enumerations

TSAlarmRepeat

Bitmask enumeration specifying alarm repeat days. Values can be combined using bitwise OR operator.

Value	Description
`TSAlarmRepeatNone`	No repeat
`TSAlarmRepeatMonday`	Repeat on Monday
`TSAlarmRepeatTuesday`	Repeat on Tuesday
`TSAlarmRepeatWednesday`	Repeat on Wednesday
`TSAlarmRepeatThursday`	Repeat on Thursday
`TSAlarmRepeatFriday`	Repeat on Friday
`TSAlarmRepeatSaturday`	Repeat on Saturday
`TSAlarmRepeatSunday`	Repeat on Sunday
`TSAlarmRepeatWorkday`	Repeat on all weekdays (Monday-Friday)
`TSAlarmRepeatWeekend`	Repeat on weekends (Saturday-Sunday)
`TSAlarmRepeatEveryday`	Repeat every day (all days of week)

Callback Types

TSAlarmClockResultBlock

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

Callback block for alarm clock operations that return a list of alarms.

Parameter	Type	Description
`allAlarmClocks`	`NSArray<TSAlarmClockModel > `	Array of 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 number of supported alarms

- (NSInteger)supportMaxAlarmCount;

Returns the maximum number of alarm clocks the device can support.

Parameter	Type	Description
`return`	`NSInteger`	Maximum alarm count supported. Returns 0 if device does not support alarm functionality.

Code Example:

NSInteger maxCount = [alarmClockInterface supportMaxAlarmCount];
if (maxCount > 0) {
    TSLog(@"Device supports up to %ld alarms", (long)maxCount);
} else {
    TSLog(@"Device does not support alarms");
}

Get maximum alarm label byte length

- (NSInteger)supportMaxAlarmLabelLength;

Returns the maximum byte length allowed for alarm labels.

Parameter	Type	Description
`return`	`NSInteger`	Maximum byte length for label. Returns 0 if device does not support alarm labels. Note: One Chinese character typically takes 3 bytes in UTF-8.

Code Example:

NSInteger maxLabelLength = [alarmClockInterface supportMaxAlarmLabelLength];
if (maxLabelLength > 0) {
    TSLog(@"Max label length: %ld bytes", (long)maxLabelLength);
}

Check if device supports alarm snooze

- (BOOL)supportAlarmSnooze;

Determines whether the device supports the alarm snooze feature.

Parameter	Type	Description
`return`	`BOOL`	YES if device supports snooze, NO otherwise.

Code Example:

if ([alarmClockInterface supportAlarmSnooze]) {
    TSLog(@"Device supports snooze functionality");
} else {
    TSLog(@"Device does not support snooze");
}

Get all alarm clocks from device

- (void)getAllAlarmClocksCompletion:(_Nullable TSAlarmClockResultBlock)completion;

Retrieves all alarm clock settings from the device.

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

Code Example:

[alarmClockInterface getAllAlarmClocksCompletion:^(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError *error) {
    if (error) {
        TSLog(@"Failed to get alarms: %@", error.localizedDescription);
        return;
    }
    TSLog(@"Retrieved %lu alarms", (unsigned long)allAlarmClocks.count);
    for (TSAlarmClockModel *alarm in allAlarmClocks) {
        TSLog(@"Alarm %d: %02ld:%02ld %@", alarm.alarmId, (long)alarm.hour, (long)alarm.minute, alarm.label);
    }
}];

Set all alarm clocks to device

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

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

Parameter	Type	Description
`allAlarmClocks`	`NSArray<TSAlarmClockModel > _Nullable`	Array of alarm models to set. Pass nil or empty array to clear all alarms.
`completion`	`TSCompletionBlock`	Callback block returning success status and error if any.

Code Example:

NSMutableArray<TSAlarmClockModel *> *alarms = [NSMutableArray array];

TSAlarmClockModel *alarm1 = [[TSAlarmClockModel alloc] init];
alarm1.label = @"Wake up";
alarm1.time = [[NSDateComponents alloc] init];
[alarm1.time setHour:7];
[alarm1.time setMinute:30];
alarm1.enable = YES;
alarm1.repeatOptions = TSAlarmRepeatWorkday;
[alarms addObject:alarm1];

[alarmClockInterface setAllAlarmClocks:alarms completion:^(NSError *error) {
    if (error) {
        TSLog(@"Failed to set alarms: %@", error.localizedDescription);
    } else {
        TSLog(@"Alarms set successfully");
    }
}];

Add a single alarm clock

- (void)addAlarmClock:(TSAlarmClockModel *)alarm completion:(_Nullable TSCompletionBlock)completion;

Adds a single alarm without affecting existing alarms. The SDK automatically assigns an alarmId.

Parameter	Type	Description
`alarm`	`TSAlarmClockModel *`	Alarm model to add. Do not set `alarmId`; SDK will assign it automatically.
`completion`	`TSCompletionBlock`	Callback block returning success status and error if any.

Code Example:

TSAlarmClockModel *newAlarm = [[TSAlarmClockModel alloc] init];
newAlarm.label = @"Exercise";
newAlarm.time = [[NSDateComponents alloc] init];
[newAlarm.time setHour:6];
[newAlarm.time setMinute:0];
newAlarm.enable = YES;
newAlarm.repeatOptions = TSAlarmRepeatMonday | TSAlarmRepeatWednesday | TSAlarmRepeatFriday;

if ([alarmClockInterface supportAlarmSnooze]) {
    newAlarm.snoozeEnable = YES;
    newAlarm.snoozeInterval = 5;
    newAlarm.snoozeRepeatCount = 2;
}

[alarmClockInterface addAlarmClock:newAlarm completion:^(NSError *error) {
    if (error) {
        TSLog(@"Failed to add alarm: %@", error.localizedDescription);
    } else {
        TSLog(@"Alarm added successfully");
    }
}];

Update a single alarm clock

- (void)updateAlarmClock:(TSAlarmClockModel *)alarm completion:(_Nullable TSCompletionBlock)completion;

Updates only the specified alarm identified by alarmId. Other alarms remain unchanged.

Parameter	Type	Description
`alarm`	`TSAlarmClockModel *`	Alarm model to update. Must have a valid `alarmId` obtained from the device.
`completion`	`TSCompletionBlock`	Callback block returning success status and error if any.

Code Example:

[alarmClockInterface getAllAlarmClocksCompletion:^(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError *error) {
    if (error || allAlarmClocks.count == 0) return;
    
    TSAlarmClockModel *alarmToUpdate = allAlarmClocks[0];
    alarmToUpdate.label = @"Updated Label";
    [alarmToUpdate.time setHour:8];
    [alarmToUpdate.time setMinute:15];
    alarmToUpdate.enable = YES;
    
    [alarmClockInterface updateAlarmClock:alarmToUpdate completion:^(NSError *updateError) {
        if (updateError) {
            TSLog(@"Failed to update alarm: %@", updateError.localizedDescription);
        } else {
            TSLog(@"Alarm updated successfully");
        }
    }];
}];

Delete a single alarm clock by ID

- (void)deleteAlarmClockWithId:(UInt8)alarmId completion:(_Nullable TSCompletionBlock)completion;

Deletes only the specified alarm identified by alarmId. Other alarms remain unchanged.

Parameter	Type	Description
`alarmId`	`UInt8`	Device-side alarm ID of the alarm to delete. Must be a valid ID from the alarm list.
`completion`	`TSCompletionBlock`	Callback block returning success status and error if any.

Code Example:

[alarmClockInterface getAllAlarmClocksCompletion:^(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError *error) {
    if (error || allAlarmClocks.count == 0) return;
    
    TSAlarmClockModel *firstAlarm = allAlarmClocks[0];
    [alarmClockInterface deleteAlarmClockWithId:firstAlarm.alarmId completion:^(NSError *deleteError) {
        if (deleteError) {
            TSLog(@"Failed to delete alarm: %@", deleteError.localizedDescription);
        } else {
            TSLog(@"Alarm deleted successfully");
        }
    }];
}];

Delete all alarm clocks

- (void)deleteAllAlarmClocksWithCompletion:(_Nullable TSCompletionBlock)completion;

Removes all alarm clocks from the device at once.

Parameter	Type	Description
`completion`	`TSCompletionBlock`	Callback block returning success status and error if any.

Code Example:

[alarmClockInterface deleteAllAlarmClocksWithCompletion:^(NSError *error) {
    if (error) {
        TSLog(@"Failed to delete all alarms: %@", error.localizedDescription);
    } else {
        TSLog(@"All alarms deleted successfully");
    }
}];

Register for alarm clock change notifications

- (void)registerAlarmClocksDidChangedBlock:(_Nullable TSAlarmClockResultBlock)completion;

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

Parameter	Type	Description
`completion`	`TSAlarmClockResultBlock`	Callback block triggered when alarm settings change. Provides updated list of all alarms. Only one listener allowed at a time.

Code Example:

[alarmClockInterface registerAlarmClocksDidChangedBlock:^(NSArray<TSAlarmClockModel *> *allAlarmClocks, NSError *error) {
    if (error) {
        TSLog(@"Alarm monitoring error: %@", error.localizedDescription);
        return;
    }
    
    TSLog(@"Alarms changed. Current count: %lu", (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");
    }
}];

Get alarm hour

- (NSInteger)hour;

Returns the alarm hour value from the time property.

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

Code Example:

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];
[alarm.time setHour:14];
TSLog(@"Alarm hour: %ld", (long)alarm.hour);

Get alarm minute

- (NSInteger)minute;

Returns the alarm minute value from the time property.

Parameter	Type	Description
`return`	`NSInteger`	Minute value (0-59).

Code Example:

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];
[alarm.time setMinute:30];
TSLog(@"Alarm minute: %ld", (long)alarm.minute);

Set alarm time

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

Sets the alarm time, automatically clamping invalid values to valid ranges.

Parameter	Type	Description
`hour`	`NSInteger`	Hour value in 24-hour format (0-23). Out-of-range values automatically clamped.
`minute`	`NSInteger`	Minute value (0-59). Out-of-range values automatically clamped.

Code Example:

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];
[alarm setHour:22 minute:45];
TSLog(@"Alarm time set to %02ld:%02ld", (long)alarm.hour, (long)alarm.minute);

// Invalid values are automatically clamped
[alarm setHour:25 minute:70];  // Clamped to 23:59
TSLog(@"After clamping: %02ld:%02ld", (long)alarm.hour, (long)alarm.minute);

Validate alarm clock models

+ (NSError * _Nullable)validateAlarmClocks:(NSArray<TSAlarmClockModel *> *)alarmClocks
                            maxLabelLength:(NSInteger)maxLabelLength
                             maxAlarmCount:(NSInteger)maxAlarmCount;

Validates an array of alarm clock models against device constraints.

Parameter	Type	Description
`alarmClocks`	`NSArray<TSAlarmClockModel > `	Array of alarm models to validate.
`maxLabelLength`	`NSInteger`	Maximum byte length for labels. Pass 0 to skip length validation.
`maxAlarmCount`	`NSInteger`	Maximum number of alarms supported. Valid `alarmId` range is [0, maxAlarmCount). Pass 0 to skip ID validation.
`return`	`NSError * _Nullable`	NSError if any model fails validation, nil if all pass.

Code Example:

NSMutableArray<TSAlarmClockModel *> *alarms = [NSMutableArray array];

TSAlarmClockModel *alarm = [[TSAlarmClockModel alloc] init];
alarm.label = @"Test Alarm";
alarm.time = [[NSDateComponents alloc] init];
[alarm setHour:10 minute:0];
[alarms addObject:alarm];

NSInteger maxLabel = [alarmClockInterface supportMaxAlarmLabelLength];
NSInteger maxCount = [alarmClockInterface supportMaxAlarmCount];

NSError *validationError = [TSAlarmClockModel validateAlarmClocks:alarms 
                                                    maxLabelLength:maxLabel 
                                                     maxAlarmCount:maxCount];
if (validationError) {
    TSLog(@"Validation failed: %@", validationError.localizedDescription);
} else {
    TSLog(@"All alarms are valid");
}

Generate unique alarm identifier

+ (NSString *)newClockIdentifier;

Generates a globally-unique alarm identifier string for app-side tracking.

Parameter	Type	Description
`return`	`NSString *`	Identifier string in format "alarmItem" + base36(random in [1, 2_000_000_000]). SDK assigns automatically on add; normally not called by developers.

Code Example:

NSString *uniqueId = [TSAlarmClockModel newClockIdentifier];
TSLog(@"Generated unique alarm ID: %@", uniqueId);

Important Notes

**Device Connection**: Ensure the device is connected and communication is established before performing any alarm operations.
**Maximum Limits**: Always check supportMaxAlarmCount before adding new alarms. Attempting to exceed the limit will return an error.
**Label Length Validation**: Verify label byte length using supportMaxAlarmLabelLength before setting labels. One Chinese character typically occupies 3 bytes in UTF-8 encoding.
**Snooze Support**: Call supportAlarmSnooze before setting snooze properties (snoozeEnable, snoozeInterval, snoozeRepeatCount). These properties have no effect on unsupported devices.
**Alarm ID Assignment**: When adding alarms, do NOT set the alarmId property; the SDK assigns it automatically. Only provide alarmId when updating or deleting alarms.
**Time Format**: Use 24-hour format (0-23) for hours. The setHour:minute: method automatically clamps invalid values to valid ranges.
**Repeat Options**: Use bitwise OR to combine multiple TSAlarmRepeat values (e.g., TSAlarmRepeatMonday | TSAlarmRepeatFriday). Use predefined combinations like TSAlarmRepeatWorkday or TSAlarmRepeatEveryday for convenience.
**Listener Registration**: Only one change listener is allowed at a time. Registering a new listener replaces the previous one.
**Set vs. Add vs. Update**: Use setAllAlarmClocks: to replace all alarms, addAlarmClock: to add without affecting others, and updateAlarmClock: to modify a specific alarm.
**Validation**: Before setting alarms, use validateAlarmClocks:maxLabelLength:maxAlarmCount: to catch configuration errors early.

Prerequisites​

Data Models​

TSAlarmClockModel​

Enumerations​

TSAlarmRepeat​

Callback Types​

TSAlarmClockResultBlock​

API Reference​

Get maximum number of supported alarms​

Get maximum alarm label byte length​

Check if device supports alarm snooze​

Get all alarm clocks from device​

Set all alarm clocks to device​

Add a single alarm clock​

Update a single alarm clock​

Delete a single alarm clock by ID​

Delete all alarm clocks​

Register for alarm clock change notifications​

Get alarm hour​

Get alarm minute​

Set alarm time​

Validate alarm clock models​

Generate unique alarm identifier​

Important Notes​

Prerequisites

Data Models

TSAlarmClockModel

Enumerations

TSAlarmRepeat

Callback Types

TSAlarmClockResultBlock

API Reference

Get maximum number of supported alarms

Get maximum alarm label byte length

Check if device supports alarm snooze

Get all alarm clocks from device

Set all alarm clocks to device

Add a single alarm clock

Update a single alarm clock

Delete a single alarm clock by ID

Delete all alarm clocks

Register for alarm clock change notifications

Get alarm hour

Get alarm minute

Set alarm time

Validate alarm clock models

Generate unique alarm identifier

Important Notes