定时任务

更新时间:2024-06-24 06:53:19下载pdf

智能生活 App SDK 提供了基本的定时能力,支持设备定时和群组定时,设备可以是 Wi-Fi 设备、蓝牙 Mesh 子设备、Zigbee 子设备的。并封装了针对设备功能(DP)的定时器信息的增删改查接口。App 通过定时接口设置好定时器信息后,云模组会自动根据定时要求进行预订的操作。

功能说明

  • 封装类:

    说明
    IThingCommonTimer 定时封装类
  • 以下多个接口用到了 taskName 参数,具体可理解为一个分组,一个分组可以有多个定时器。每个定时属于或不属于一个分组,分组仅用于展示。例如:

    • 一个开关可能有多个功能,可以根据每个设备功能设置一个定时分组。

    • 每个分组可以添加多个定时器,用于控制这个设备功能各个时段的开启或关闭。

      每个定时任务下可以包含多个定时器。如下图所示:

      定时任务

版本说明

为了解决老接口存在的问题,本文描述的定时任务接口是从 3.18.0 SDK 版本新增的。

  • 新版定时接口在 ThingHomeSdk.getTimerInstance()
  • 旧版定时接口在 ThingHomeSdk.getTimerManagerInstance()

与旧版接口相比,新版接口有以下几点更新:

  • 新增或更新定时器接口,可以设置定时器开关状态
  • 提供批量修改定时器状态接口
  • 修复旧版关闭定时分组失效问题
  • 提供分组定时删除功能

旧版接口不再维护,建议您升级到新版接口。升级需要将替换整套定时接口。为了提高兼容性,使用旧版接口设置定时,仍可以通过新版查询定时器列表查询。

增加定时任务

为设备或群组新增一个定时器,到指定的任务(task)下。每个设备或群组定时的上限为 30 个。

接口说明

void addTimer(ThingTimerBuilder builder, final IResultCallback callback);

参数说明

ThingTimerBuilderIResultCallback 说明

参数 说明
taskName 定时分组名称
devId 设备 ID 或群组 ID
loops 循环次数,格式为 0000000,每一位数字的取值可以是
  • 0:关闭
  • 1:开启
从左至右依次表示周日、周一、周二、周三、周四、周五、周六。如每个周一循环该任务,则取值为 01000000000000 表示只执行一次,1111111 表示每天执行。
actions 设备功能(dps)的操作任务的 JSON 格式表达方式,格式为 {"dps":{}, "time":""},其中 Raw 类型的 DP 需要转换格式,转换方式为:new String(Base64.encodeBase64(HexUtil.hexStringToBytes(dps)))
status 初始化定时器开关状态:
  • 0:关闭
  • 1:开启
appPush 是否支持定时执行结果推送
aliasName 设置定时备注名
TimerDeviceTypeEnum 枚举,定时类型:
  • DEVICE:设备定时
  • GROUP:设备群组定时
callback 回调,返回成功或失败的结果,不能为 null

示例代码

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

    }
});

批量修改普通定时状态或删除定时器

接口说明

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

参数说明

参数 说明
devId 设备 ID 或群组 ID
TimerDeviceTypeEnum 枚举,定时类型:
  • DEVICE:设备定时
  • GROUP:设备群组定时
ids 定时器 ID 列表
TimerUpdateEnum 枚举,操作类型:
  • OPEN:开启定时器
  • CLOSE:关闭定时器
  • DELETE:删除定时器
callback 回调,主要包括发送成功或失败的回调,不能为 null

示例代码

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

    }
});

修改定时任务的定时信息

接口说明

更新设备或群组下某个任务的定时器信息。

void updateTimer(ThingTimerBuilder builder, final IResultCallback callback);

参数说明

ThingTimerBuilderIResultCallback 说明

参数 说明
taskName 定时分组名称
devId 设备 ID 或群组 ID
loops 循环次数,格式为 0000000,每一位数字的取值可以是
  • 0:关闭
  • 1:开启
从左至右依次表示周日、周一、周二、周三、周四、周五、周六。如每个周一循环该任务,则取值为 01000000000000 表示只执行一次,1111111 表示每天执行。
actions 设备功能(dps)的操作任务的 JSON 格式表达方式,格式为 {"dps":{}, "time":""},其中 Raw 类型的 DP 需要转换格式,转换方式为:new String(Base64.encodeBase64(HexUtil.hexStringToBytes(dps)))
status 初始化定时器开关状态:
  • 0:关闭
  • 1:开启
appPush 是否支持定时执行结果推送
aliasName 设置定时备注名
TimerDeviceTypeEnum 枚举,定时类型:
  • DEVICE:设备定时
  • GROUP:设备群组定时
callback 回调,返回成功或失败的结果,不能为 null

示例代码

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

    }
});

查询定时任务下所有定时任务

接口说明

查询设备或群组下某个任务的定时器。

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

参数说明

参数 说明
taskname 定时分组,可选,如果为空表示查询普通定时器列表
devId 设备 ID 或群组 ID
TimerDeviceTypeEnum 枚举,定时类型:
  • DEVICE:设备定时
  • GROUP:设备群组定时
callback 回调,主要包括发送成功或失败的回调,不能为 null

回调参数 TimerTask 说明

参数 说明
TimerTaskStatus 定时器开关状态及名称
ArrayList 单个定时器列表
category 定时分组信息

示例代码

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

    }

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

    }
});

查询设备或群组下的定时任务

接口说明

查询设备或群组下所有的定时器,根据任务分类。

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

参数说明

参数 说明
devId 设备 ID 或群组 ID
TimerDeviceTypeEnum 枚举,定时类型:
  • DEVICE:设备定时
  • GROUP:设备群组定时
callback 回调,主要包括发送成功或失败的回调,不能为 null

回调参数 TimerTask 说明

参数 说明
TimerTaskStatus 定时器开关状态及名称
ArrayList 单个定时器列表
category 定时分组信息

示例代码

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

    }
});

修改分类下所有定时任务状态或删除定时器

接口说明

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

参数说明

参数 说明
taskname 定时分组
devId 设备 ID 或群组 ID
TimerDeviceTypeEnum 枚举,定时类型:
  • DEVICE:设备定时
  • GROUP:设备群组定时
TimerUpdateEnum 枚举,操作类型:
  • OPEN:开启定时器
  • CLOSE:关闭定时器
  • DELETE:删除定时器
callback 回调,主要包括发送成功或失败的回调,不能为 null

示例代码

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

    }

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

    }
});