Device Schedule

Last Updated on : 2024-08-22 03:43:40download

This topic describes the device schedule service that allows the user to schedule a smart device to run a task automatically. For example, schedule the curtains to close at 7 p.m. and open at 9 a.m.

The ThingSmartBusinessExtensionKit component offers more features than the ThingSmartTimer. If you are still using ThingSmartTimer, please refer to this document.

Schedule model

ThingTimerModel class

Property	Type	Description
timerId	NSString	The schedule ID.
date	NSString	The scheduled date.
time	NSString	The scheduled time, for example, `12:30`.
status	BOOL	The schedule status. `1`: Enabled. `0`: Disabled.
loops	NSString	The recurrence pattern, in the format of `0000000`. Each digit can be `0` (off) or `1` (on). The digits represent Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday sequentially from left to right. For example, if the schedule repeats every Monday, the value is set to `0100000`. `0000000` indicates a one-time schedule. `1111111` indicates the schedule runs every day.
dps	NSDictionary	The data point (DP) triggered when the schedule runs. The format is `{"dpid":"dp value"}`.
timezoneId	NSString	The time zone of the device.
aliasName	NSString	The name of the schedule.
isAppPush	BOOL	Specifies whether to notify the user of the schedule execution result via the app. `true`: Notify `false`: Not notify

Query the list of schedules

API description

Query the list of schedules.

- (void)getTimers:(ThingDeviceTimerGetParams *)params success:(void(^)(NSArray<ThingTimerModel *> *timers))success failure:(void(^)(NSError *error))failure;

Parameter description

ThingDeviceTimerGetParams

Property	Type	Description
bizType	ThingDeviceTimerBizType	Business type. `ThingDeviceTimerBizTypeDevice`: Device `ThingDeviceTimerBizTypeGroup`: Group
bizId	NSString	If the business type is device, the value of this parameter is the device ID. If the business type is group, the value of this parameter is the group ID.
category	NSString	The category of the schedule. Generally, its value is not passed in.

Description of return values

Data	Description
success	The success callback. `timers`: The schedule information. For more information, see Schedule model.
failure	The failure callback.

Example

func getTimerList(success: @escaping ([ThingTimerModel]) -> Void, failure: @escaping (Error) -> Void) {
    let params = ThingDeviceTimerGetParams(bizType: isGroup ? .group : .device, bizId: bizId, category: "")
    self.manager.getTimers(params, success: success, failure: failure)
}

Sync schedule list with device

API description

Sync the schedule list with the device. Only the Bluetooth device supports sync.

- (void)syncTimers:(NSArray<ThingTimerModel *> *)timers toDevice:(NSString *)deviceId success:(void(^)(void))success failure:(void(^)(NSError *error))failure;

Before calling this method, determine if the device supports sync through isDeviceCanSync:.

- (BOOL)isDeviceCanSync:(NSString *)deviceId;

Parameter description

Property	Type	Description
timers	NSArray	The schedule information. For more information, see Schedule model.
success	None.	The success callback.
failure	None.	The failure callback.

Example

override func viewDidLoad() {
    super.viewDidLoad()
    self.tableView.register(UITableViewCell.self, forCellReuseIdentifier: "DeviceDetailListViewControllerReuseIdentifier")
    self.setUpNavigationItem()

    SVProgressHUD.show()
    self.getTimerList { [weak self] list in
        self?.items = list
        self?.tableView.reloadData()
        SVProgressHUD.dismiss()

        guard let self = self, self.isGroup == false && self.manager.isDeviceCanSync(bizId) else {
            return
        }
        manager.syncTimers(list, toDevice: bizId) {

        } failure: { e in

        }

    } failure: { e in
        SVProgressHUD.dismiss()
    }
}

Add a schedule

API description

Add a schedule.

- (void)addTimer:(ThingDeviceTimerAddParams *)params success:(void(^)(NSString *timerId))success failure:(void(^)(NSError *error))failure;

Parameters

Property	Type	Description
params	ThingDeviceTimerAddParams	Add the parameters of the schedule. For more information, see ThingDeviceTimerAddParams.
success	None.	The success callback.
failure	None.	The failure callback.

ThingDeviceTimerAddParams

Property	Type	Description
bizType	ThingDeviceTimerBizType	Business type. `ThingDeviceTimerBizTypeDevice`: Device `ThingDeviceTimerBizTypeGroup`: Group
bizId	NSString	If the business type is device, the value of this parameter is the device ID. If the business type is group, the value of this parameter is the group ID.
category	NSString	The category of the schedule. Generally, its value is not passed in.
time	NSString	The scheduled time, for example, `12:30`.
status	BOOL	The schedule status. `1`: Enabled. `0`: Disabled.
loops	NSString	The recurrence pattern, in the format of `0000000`. Each digit can be `0` (off) or `1` (on). The digits represent Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday sequentially from left to right. For example, if the schedule repeats every Monday, the value is set to `0100000`. `0000000` indicates a one-time schedule. `1111111` indicates the schedule runs every day.
dps	NSDictionary	The data point (DP) triggered when the schedule runs. The format is `{"dpid":"dp value"}`.
aliasName	NSString	The name of the schedule.
isAppPush	BOOL	Specifies whether to notify the user of the schedule execution result via the app. `true`: Notify `false`: Not notify

Example

@objc func add() {
    SVProgressHUD.show()

    var dps: [AnyHashable: Any] = ["1": true]
    let params = ThingDeviceTimerAddParams(bizType: isGroup ? .group : .device, bizId: bizId, category: "", loops: "0000000", time: "12:30", dps: dps, aliasName: "new timer", isAppPush: true, status: true)
    self.manager.addTimer(params) { [weak self] timerId in
        self?.getTimerList(success: { list in
            self?.items = list
            self?.tableView.reloadData()
            SVProgressHUD.dismiss()
        }, failure: { e in
            SVProgressHUD.dismiss()
        })
    } failure: { e in
        SVProgressHUD.dismiss()
    }
}

Update a schedule

API description

Update a schedule.

- (void)updateTimer:(ThingDeviceTimerUpdateParams *)params success:(void(^)(void))success failure:(void(^)(NSError *error))failure;

Parameter description

Property	Type	Description
params	ThingDeviceTimerUpdateParams	Update the parameters of the schedule. For more information, see ThingDeviceTimerUpdateParams.
success	None.	The success callback.
failure	None.	The failure callback.

ThingDeviceTimerUpdateParams

Property	Type	Description
timerId	NSString	The schedule ID.
bizType	ThingDeviceTimerBizType	Business type. `ThingDeviceTimerBizTypeDevice`: Device `ThingDeviceTimerBizTypeGroup`: Group
bizId	NSString	If the business type is device, the value of this parameter is the device ID. If the business type is group, the value of this parameter is the group ID.
time	NSString	The scheduled time, for example, `12:30`.
status	BOOL	The schedule status. `1`: Enabled. `0`: Disabled.
loops	NSString	The recurrence pattern, in the format of `0000000`. Each digit can be `0` (off) or `1` (on). The digits represent Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday sequentially from left to right. For example, if the schedule repeats every Monday, the value is set to `0100000`. `0000000` indicates a one-time schedule. `1111111` indicates the schedule runs every day.
dps	NSDictionary	The data point (DP) triggered when the schedule runs. The format is `{"dpid":"dp value"}`.
aliasName	NSString	The name of the schedule.
isAppPush	BOOL	Specifies whether to notify the user of the schedule execution result via the app. `true`: Notify `false`: Not notify

Example

let params = ThingDeviceTimerUpdateParams(timerId: timer.timerId, bizType: self.isGroup ? .group : .device, bizId: self.bizId, loops: timer.loops, time: timer.time, dps: timer.dps, aliasName: timer.aliasName, isAppPush: !timer.isAppPush, status: !timer.status)

SVProgressHUD.show()

self.manager.updateTimer(params) { [weak self] in
    self?.getTimerList { list in
        self?.items = list
        self?.tableView.reloadData()
        SVProgressHUD.dismiss()
    } failure: { e in
        SVProgressHUD.dismiss()
    }
} failure: { e in
    SVProgressHUD.dismiss()
}

Update the status of a schedule

API description

Update the status of a schedule.

- (void)updateTimerStatus:(ThingDeviceTimerStatusUpdateParams *)params success:(void(^)(void))success failure:(void(^)(NSError *error))failure;

Parameter description

Property	Type	Description
params	ThingDeviceTimerStatusUpdateParams	Update the parameters of the schedule status. For more information, see ThingDeviceTimerStatusUpdateParams.
success	None.	The success callback.
failure	None.	The failure callback.

ThingDeviceTimerStatusUpdateParams

Property	Type	Description
timerId	NSString	The schedule ID.
bizType	ThingDeviceTimerBizType	Business type. `ThingDeviceTimerBizTypeDevice`: Device `ThingDeviceTimerBizTypeGroup`: Group
bizId	NSString	If the business type is device, the value of this parameter is the device ID. If the business type is group, the value of this parameter is the group ID.
time	NSString	The scheduled time, for example, `12:30`.
status	BOOL	The schedule status. `1`: Enabled. `0`: Disabled.
loops	NSString	The recurrence pattern, in the format of `0000000`. Each digit can be `0` (off) or `1` (on). The digits represent Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday sequentially from left to right. For example, if the schedule repeats every Monday, the value is set to `0100000`. `0000000` indicates a one-time schedule. `1111111` indicates the schedule runs every day.
dps	NSDictionary	The data point (DP) triggered when the schedule runs. The format is `{"dpid":"dp value"}`.
aliasName	NSString	The name of the schedule.
isAppPush	BOOL	Specifies whether to notify the user of the schedule execution result via the app. `true`: Notify `false`: Not notify

Example

let params = ThingDeviceTimerStatusUpdateParams(timerId: timer.timerId, bizType: self.isGroup ? .group : .device, bizId: self.bizId, loops: timer.loops, time: timer.time, dps: timer.dps, aliasName: timer.aliasName, isAppPush: timer.isAppPush, status: !timer.status)

SVProgressHUD.show()

self.manager.updateTimerStatus(params) { [weak self] in
    self?.getTimerList { list in
        self?.items = list
        self?.tableView.reloadData()
        SVProgressHUD.dismiss()
    } failure: { e in
        SVProgressHUD.dismiss()
    }
} failure: { e in
    SVProgressHUD.dismiss()
}

Delete a schedule

API description

Delete a schedule.

- (void)removeTimer:(ThingDeviceTimerRemoveParams *)params success:(void(^)(void))success failure:(void(^)(NSError *error))failure;

Parameter description

Property	Type	Description
params	ThingDeviceTimerRemoveParams	Delete the parameters of the schedule. For more information, see ThingDeviceTimerRemoveParams.
success	None.	The success callback.
failure	None.	The failure callback.

ThingDeviceTimerRemoveParams

Property	Type	Description
timerId	NSString	The schedule ID.
bizType	ThingDeviceTimerBizType	Business type. `ThingDeviceTimerBizTypeDevice`: Device `ThingDeviceTimerBizTypeGroup`: Group
bizId	NSString	If the business type is device, the value of this parameter is the device ID. If the business type is group, the value of this parameter is the group ID.

Example

let params = ThingDeviceTimerRemoveParams(timerId: timer.timerId, bizType: self.isGroup ? .group : .device, bizId: self.bizId)

SVProgressHUD.show()

self.manager.removeTimer(params) { [weak self] in
    self?.getTimerList { list in
        self?.items = list
        self?.tableView.reloadData()
        SVProgressHUD.dismiss()
    } failure: { e in
        SVProgressHUD.dismiss()
    }
} failure: { e in
    SVProgressHUD.dismiss()
}

Example

import UIKit
import ThingDeviceDetailKit
import SVProgressHUD
import ThingSmartDeviceCoreKit

class DeviceDetailKitTimerVC: UITableViewController {

    var bizId: String
    var isGroup: Bool
    var manager: ThingDeviceTimerManager

    var items: [ThingTimerModel] = []

    init(bizId: String, isGroup: Bool) {
        self.bizId = bizId
        self.isGroup = isGroup
        self.manager = ThingDeviceTimerManager()
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        fatalError("init(coder:) has not been implemented")
    }

    func setUpNavigationItem() {
        let title = "add"
        self.navigationItem.rightBarButtonItem = UIBarButtonItem(title: title, style: .plain, target: self, action: #selector(add))
    }

    @objc func add() {
        SVProgressHUD.show()

        var dps: [AnyHashable: Any] = ["1": true]
        let params = ThingDeviceTimerAddParams(bizType: isGroup ? .group : .device, bizId: bizId, category: "", loops: "0000000", time: "12:30", dps: dps, aliasName: "new timer", isAppPush: true, status: true)
        self.manager.addTimer(params) { [weak self] timerId in
            self?.getTimerList(success: { list in
                self?.items = list
                self?.tableView.reloadData()
                SVProgressHUD.dismiss()
            }, failure: { e in
                SVProgressHUD.dismiss()
            })
        } failure: { e in
            SVProgressHUD.dismiss()
        }
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        self.tableView.register(UITableViewCell.self, forCellReuseIdentifier: "DeviceDetailListViewControllerReuseIdentifier")
        self.setUpNavigationItem()

        SVProgressHUD.show()
        self.getTimerList { [weak self] list in
            self?.items = list
            self?.tableView.reloadData()
            SVProgressHUD.dismiss()

            guard let self = self, self.isGroup == false && self.manager.isDeviceCanSync(bizId) else {
                return
            }
            manager.syncTimers(list, toDevice: bizId) {

            } failure: { e in

            }

        } failure: { e in
            SVProgressHUD.dismiss()
        }

    }

    func getTimerList(success: @escaping ([ThingTimerModel]) -> Void, failure: @escaping (Error) -> Void) {
        let params = ThingDeviceTimerGetParams(bizType: isGroup ? .group : .device, bizId: bizId, category: "")
        self.manager.getTimers(params, success: success, failure: failure)
    }

    override func numberOfSections(in tableView: UITableView) -> Int {
        return 1
    }

    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        return items.count
    }

    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let cell = UITableViewCell(style: .value1, reuseIdentifier: "DeviceDetailListViewControllerReuseIdentifier")
        cell.textLabel?.text = self.items[indexPath.row].time
        cell.detailTextLabel?.text = self.items[indexPath.row].status ? "on" : "off"
        return cell
    }

    override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        tableView.deselectRow(at: indexPath, animated: true)
        self.handle(index: indexPath.row)
    }

    func handle(index: Int) {
        if (index >= self.items.count) {return}

        let alert = UIAlertController(title: nil, message: nil, preferredStyle: .actionSheet)
        let timer = self.items[index]

        alert.addAction(UIAlertAction(title: "delete", style: .default, handler: { action in
            let params = ThingDeviceTimerRemoveParams(timerId: timer.timerId, bizType: self.isGroup ? .group : .device, bizId: self.bizId)

            SVProgressHUD.show()

            self.manager.removeTimer(params) { [weak self] in
                self?.getTimerList { list in
                    self?.items = list
                    self?.tableView.reloadData()
                    SVProgressHUD.dismiss()
                } failure: { e in
                    SVProgressHUD.dismiss()
                }
            } failure: { e in
                SVProgressHUD.dismiss()
            }
        }))

        alert.addAction(UIAlertAction(title: "update", style: .default, handler: { action in
            let params = ThingDeviceTimerUpdateParams(timerId: timer.timerId, bizType: self.isGroup ? .group : .device, bizId: self.bizId, loops: timer.loops, time: timer.time, dps: timer.dps, aliasName: timer.aliasName, isAppPush: !timer.isAppPush, status: !timer.status)

            SVProgressHUD.show()

            self.manager.updateTimer(params) { [weak self] in
                self?.getTimerList { list in
                    self?.items = list
                    self?.tableView.reloadData()
                    SVProgressHUD.dismiss()
                } failure: { e in
                    SVProgressHUD.dismiss()
                }
            } failure: { e in
                SVProgressHUD.dismiss()
            }
        }))

        alert.addAction(UIAlertAction(title: "update status", style: .default, handler: { action in
            let params = ThingDeviceTimerStatusUpdateParams(timerId: timer.timerId, bizType: self.isGroup ? .group : .device, bizId: self.bizId, loops: timer.loops, time: timer.time, dps: timer.dps, aliasName: timer.aliasName, isAppPush: timer.isAppPush, status: !timer.status)

            SVProgressHUD.show()

            self.manager.updateTimerStatus(params) { [weak self] in
                self?.getTimerList { list in
                    self?.items = list
                    self?.tableView.reloadData()
                    SVProgressHUD.dismiss()
                } failure: { e in
                    SVProgressHUD.dismiss()
                }
            } failure: { e in
                SVProgressHUD.dismiss()
            }
        }))

        alert.addAction(UIAlertAction(title: "cancel", style: .cancel))
        self.present(alert, animated: true)
    }
}

Error codes

Error codes	Description
-10001	Failed to get the device information.
-10002	Device is offline.
-10003	Failed to get the schedule information.
-10004	Data transfer over Bluetooth timed out.
-10005	Failed to parse Bluetooth data.
-10006	Device does not support sync.

Prev DocDevice Information

Next DocDevice Offline Notification