Scheduled Tasks

Smart Life App SDK provides basic capabilities to manage scheduled tasks. For example, set scheduled tasks for devices and groups. Supported types of devices include Wi-Fi devices, Bluetooth mesh sub-devices, and Zigbee sub-devices. This SDK encapsulates the API methods to query, add, modify, or delete timers for data points (DPs). The app can be used to set timers based on specific scheduled task API calls. Then, network modules will automatically run predefined tasks.

Functional description

• Encapsulation class

  Class name	Description
  IThingCommonTimer	Encapsulates API methods for scheduled tasks.

• Multiple API methods require the taskName parameter. It can be regarded as a group of timers. Each timer belongs to at most one group. A group is only used for display. Example:

  • A switch might support multiple DPs. A group of timers can be created for each DP.

  • Multiple timers can be added to each group to control the switch status of the DP in different periods.

    A scheduled task can include multiple timers. The following figure shows the architecture of the device, scheduled tasks, and timers.

    

Version description

To fix certain known issues, the API methods for scheduled tasks mentioned in this topic are added to SDK v3.18.0 and later.

• You can call these API methods in ThingHomeSdk.getTimerInstance().
• The API methods for scheduled tasks in earlier versions can be found in ThingHomeSdk.getTimerManagerInstance().

Compared with the earlier API methods, the latest API methods support the following new features:

• Added or updated the timer API methods that allow users to set the timer switch status.
• Added the API methods to modify timer status in bulk.
• Fixed the issue in which a timer group failed to be disabled.
• Added the feature to delete a timer group.

Add a scheduled task

Adds a timer to a specified scheduled task specified by task for a device or group. The maximum number of timers allowed for each device or group is 30.

API description

void addTimer(ThingTimerBuilder builder, final IResultCallback callback);

Parameters

Parameters of ThingTimerBuilder and IResultCallback

Parameter	Description
taskName	The name of the timer group.
devId	The device ID or group ID.
loops	The way the scheduled task is repeated. Format: 0000000. Valid values of each digit: 0: disabled 1: enabled The digits represent Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday sequentially from left to right. For example, for a scheduled task that repeats each Monday, set the value to 0100000. 0000000 represents that the scheduled task repeats only once. 1111111 represents that the scheduled task repeats every day.
actions	The scheduled tasks in the JSON format assigned to DPs. Format: {"dps":{}, "time":""}. For DPs of Raw type, you must convert the format by using new String(Base64.encodeBase64(HexUtil.hexStringToBytes(dps))).
status	Initializes the status of the timer switch. Valid values: 0: disabled 1: enabled
appPush	Specifies whether to send a push notification of the scheduled task result.
aliasName	The alias of the scheduled task.
TimerDeviceTypeEnum	The target for which the scheduled task runs. Valid values: DEVICE: device GROUP: device group
callback	The success or failure callback. null cannot be returned.

Example

ThingTimerBuilder builder = new ThingTimerBuilder.Builder()
        .taskName(mTaskName)
        .devId("efw9990wedsew")
        .deviceType(TimerDeviceTypeEnum.DEVICE)
        .actions(dps)
        .loops("1100011")
        .aliasName("Test")
        .status(1)
        .appPush(true)
        .build();
ThingHomeSdk.getTimerInstance().addTimer(builder, new IResultCallback() {
    @Override
    public void onSuccess() {
            }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});

Modify common timer status or delete timers in bulk

API description

void updateTimerStatus(String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, List<String> ids, TimerUpdateEnum timerUpdateEnum, final IResultCallback callback);

Parameters

Parameter	Description
devId	The device ID or group ID.
TimerDeviceTypeEnum	The target for which the scheduled task runs. Valid values: DEVICE: device GROUP: device group
ids	The list of timer IDs.
TimerUpdateEnum	The type of operation. Valid values: OPEN: enable timers CLOSE: disable timers DELETE: delete timers
callback	The success or failure callback. null cannot be returned.

Example

List<String> list = new ArrayList<>();
list.add("111");
ThingHomeSdk.getTimerInstance().updateTimerStatus(mDevId, TimerDeviceTypeEnum.DEVICE, list, TimerUpdateEnum.DELETE, new IResultCallback() {
    @Override
    public void onError(String code, String error) {

    }

    @Override
    public void onSuccess() {

    }
});

Modify timer information of a scheduled task

API description

Updates the timer information of a scheduled task for a device or group.

void updateTimer(ThingTimerBuilder builder, final IResultCallback callback);

Parameters

Parameters of ThingTimerBuilder and IResultCallback

Parameter	Description
taskName	The name of the timer group.
devId	The device ID or group ID.
loops	The way the scheduled task is repeated. Format: 0000000. Valid values of each digit: 0: disabled 1: enabled The digits represent Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday sequentially from left to right. For example, for a scheduled task that repeats each Monday, set the value to 0100000. 0000000 represents that the scheduled task repeats only once. 1111111 represents that the scheduled task repeats every day.
actions	The scheduled tasks in the JSON format assigned to DPs. Format: {"dps":{}, "time":""}. For DPs of Raw type, you must convert the format by using new String(Base64.encodeBase64(HexUtil.hexStringToBytes(dps))).
status	Initializes the status of the timer switch. Valid values: 0: disabled 1: enabled
appPush	Specifies whether to send a push notification of the scheduled task result.
aliasName	The alias of the scheduled task.
TimerDeviceTypeEnum	The target for which the scheduled task runs. Valid values: DEVICE: device GROUP: device group
callback	The success or failure callback. null cannot be returned.

Example

ThingTimerBuilder builder = new ThingTimerBuilder.Builder()
    .timerId("1204923")
    .devId(groupId+"")
    .deviceType(TimerDeviceTypeEnum.GROUP)
    .actions(dps)
    .loops("0000000")
    .aliasName("test")
    .status(1)
    .appPush(true)
    .build();
ThingHomeSdk.getTimerInstance().updateTimer(builder, new IResultCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});

Query all timers of a scheduled task

API description

Returns all timers of a scheduled task for a device or group.

void getTimerList(String taskName, String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, final IThingDataCallback<TimerTask> callback);

Parameters

Parameter	Description
taskname	The name of the timer group. If this parameter is empty, common timers are queried.
devId	The device ID or group ID.
TimerDeviceTypeEnum	The target for which the scheduled task runs. Valid values: DEVICE: device GROUP: device group
callback	The success or failure callback. null cannot be returned.

Parameters of TimerTask

Parameter	Description
TimerTaskStatus	The switch status and name of a timer.
ArrayList	The list of timers.
category	The category of the timer group.

Example

ThingHomeSdk.getTimerInstance().getTimerList(null, mGwId, TimerDeviceTypeEnum.DEVICE, new IThingDataCallback<TimerTask>() {
    @Override
    public void onSuccess(TimerTask timerTask){

    }

    @Override
    public void onError(String errorCode, String errorMessage){

    }
});

Query scheduled tasks for a device or group

API description

Returns all timers for a device or group. Each timer is assigned to a scheduled task.

void getAllTimerList(String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, final IThingDataCallback<List<TimerTask>> callback);

Parameters

Parameter	Description
devId	The device ID or group ID.
TimerDeviceTypeEnum	The target for which the scheduled task runs. Valid values: DEVICE: device GROUP: device group
callback	The success or failure callback. null cannot be returned.

Parameters of TimerTask

Parameter	Description
TimerTaskStatus	The switch status and name of a timer.
ArrayList	The list of timers.
category	The category of the timer group.

Example

ThingHomeSdk.getTimerInstance().getAllTimerList(mGwId, TimerDeviceTypeEnum.DEVICE, new IThingDataCallback<List<TimerTask>>() {
    @Override
    public void onSuccess(List<TimerTask> timerTaskList){

    }

    @Override
    public void onError(String errorCode, String errorMessage){

    }
});

Modify scheduled task status or delete timers by category

API description

void updateCategoryTimerStatus(String taskName, String devId, TimerDeviceTypeEnum deviceTimerTypeEnum, TimerUpdateEnum timerUpdateEnum, IResultCallback callback);

Parameters

Parameter	Description
taskname	The timer group.
devId	The device ID or group ID.
TimerDeviceTypeEnum	The target for which the scheduled task runs. Valid values: DEVICE: device GROUP: device group
TimerUpdateEnum	The type of operation. Valid values: OPEN: enable timers CLOSE: disable timers DELETE: delete timers
callback	The success or failure callback. null cannot be returned.

Example

ThingHomeSdk.getTimerInstance().updateCategoryTimerStatus("test" ,"90sdjoi3dedj33", TimerDeviceTypeEnum.DEVICE, TimerUpdateEnum.CLOSE,new IResultCallback() {
    @Override
    public void onSuccess() {

    }

    @Override
    public void onError(String errorCode, String errorMsg) {

    }
});