Scheduled Tasks

Last Updated on : 2024-06-24 09:19:24download

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.

      Scheduled Tasks

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.

The earlier API methods for scheduled tasks will no longer be maintained. We recommend that you update to the latest API methods. During the update, all API methods for scheduled tasks are replaced. To improve compatibility, the list of timers created with earlier API methods can still be queried with the latest API methods.

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) {

    }
});