文档

蓝牙 Mesh 本地定时 SDK

更新时间:

蓝牙 Mesh 本地定时 SDK 提供了通过 App 设置Mesh设备本地定时,以及自动对时的功能。

概述

依赖 SDK

概述

物模型SDK

物模型 SDK 提供了 App 端的物模型

蓝牙 Mesh SDK

提供蓝牙mesh基础能力

使用说明

获取蓝牙Mesh网络是否有连接

可以使用下面的方式判断当前是否已经连接到了Mesh网络。

boolean isConnected2Mesh = TgMeshManager.getInstance().isConnectedToMesh();

本地定时操作

获取 MeshTimerTransaction 对象

在添加/删除/更新某个mesh节点的本地定时前,需要获取MeshTimerTransaction对象。

// 入参为mesh设备的iotId
String iotId = "***";
MeshTimerTransaction meshTimerTransaction = MeshTimerTransaction.initWithIotID(iotId);

获取设备的定时列表

  • 定时对象模型MeshTimerModel

    public enum TimerType {
        TIMER_NONE(0),
        TIMER_COUNTDOWN(1), // 倒计时定时
        TIMER_NORMAL(2), // 普通定时
        TIMER_CIRCULATION(3); // 循环定时
    }
    
    public enum TimerEnableType {
        TIMER_ENABLE_NONE(0), // 定时未启用
        TIMER_ENABLE(1), // 已启用
        TIMER_IN_FLIGHT(2);
    }
    
    public class MeshTimerModel{
        private String timerID;
        // 开始时间
        // 倒计时: yyyy-MM-dd HH:mm
        // 普通定时: HH:mm
        // 循环定时: HH:mm
        private String time;
        // 循环定时普通定时
        // 格式:"1,2,3,4,5,6,7"    (1表示星期天,2表示星期一)
        private String days;
        // 定时器类型
        private TimerType timerType;
        // 该定时器是否启用
        private TimerEnableType enableType;
        // 表示当次设置的定时任务的具体动作。控制多个属性及属性值,每对属性之间使用,分割,示例:"powerstate:1,mode:2"
        // 对于循环定时,字符串里包含"|",则"|"前面的是RunTime需执行的action,"|"后面的是SleepTime需执行的action
        private String attributesTargets;
        // 表示本地事件与UTC时间的差值
        // 单位:秒
        // 取值范围为:-43200到50400
        // 步长:3600
        private int timeZone;
        // 结束时间,周期循环定时的类型用到
        // 示例:HH:mm
        private String endTime;
        // 运行的时长,如打开30分钟,周期循环定时的类型用到   单位秒
        private int runTime;
        // 睡眠的时长,如打开30分钟,周期循环定时的类型用到   单位秒
        private int sleepTime;
    }
  • 获取定时器任务列表

    获取当前设备列表中的定时任务列表。

    说明

    在更新/删除/增加本地定时功能前,必须调用该接口。

    // 入参为mesh设备的iotId
    String iotId = "";
    MeshTimerTransaction meshTimerTransaction = MeshTimerTransaction.initWithIotID(iotId);
    
    meshTimerTransaction.getDeviceTimerList(new ITimerActionCallback<List<MeshTimerModel>>() {
            @Override
            public void onSuccess(List<MeshTimerModel> result) {
                // result 为当前设备的本地定时列表
            }
    
            @Override
            public void onFailure(int errorCode, String desc) {
                //
            }
        });
    
                        

定时器操作

SDK提供添加/删除/更新某个定时器的功能,但调用方必须保证一个操作接口完成后,才可以进行下一次调用。保证一次只操作一个定时器。

操作错误码

public interface ErrorCode {
    // SDK内部没有获取到当前设备的定时列表,需要检查该设备的物模型中是否支持本地定时
    int ERROR_UNSUPPORTED_OPERATIONS = -1;
    // 需先调用 getDeviceTimerList 方法,保证 SDK 内部初始化
    int ERROR_INVOCATION_PROCESS = -2;
    // 本地定时器已满,不能继续添加定时器
    int ERROR_TIMING_ALREADY_FULL = -3;
    // MeshTimerModel 中的 timerID 非法,调用发需要保证不会更新 timerID
    int ERROR_INVALID_TIMER_ID = -4;
    // 设置本地定时器失败。可能Mesh本地网络未连接
    int ERROR_SEND_FAILED = -5;
    // 设备本地定时器超时。可能原因:
    // 1. 目标设备不在周边或者断电
    // 2. 设备固件不支持设置定时器
    // 3. 定时器参数不合法。
    int ERROR_SET_TIMER_TIMEOUT = -6;
    // 需要等待上一个调用操作完成
    int ERROR_EXIT_PENDING_TASK = -7;
}

添加本地定时任务

SDK 提供了 Builder 方法分别创建本地普通定时、循环定时以及倒计时。

对于倒计时定时,时间到达后云端会自动清除该定时器。SDK调用方需要使用getDeviceTimerList来刷新本地定时列表。

String iotId = "";
MeshTimerTransaction meshTimerTransaction = MeshTimerTransaction.initWithIotID(iotId);

// 添加本地普通定时
MeshTimerModel.NormalTimerBuilder builder = new MeshTimerModel.NormalTimerBuilder();
builder.setTime("21:30").setTargets("powerstate:0").setDays("1,2,3,4,5,6,7").setTimeZone(28800);
MeshTimerModel timerModel = builder.build();

meshTimerTransaction.addTimerWithTimerModel(timerModel, new ITimerActionCallback<List<MeshTimerModel>>() {
    @Override
    public void onSuccess(List<MeshTimerModel> result) {
        // result为最新的定时任务列表。业务层必须该对象进行后续的操作
        Log.i(TAG, "On successful to add timer, result: " + JSON.toJSONString(result));
    }

    @Override
    public void onFailure(int errorCode, String desc) {
        Log.e(TAG, "On failed to add timer, errorCode: " + errorCode + ", desc: " + desc);
    }
});

// 添加本地循环定时
MeshTimerModel.CirculationTimerBuilder circulationTimerBuilder = new MeshTimerModel.CirculationTimerBuilder();
MeshTimerModel circulationTimerModel = circulationTimerBuilder.setTime("21:30")
        .setTargets("powerstate:0|powerstate:1")
        .setDays("1,2,3,4,5,6,7")
        .setTimeZone(28800)
        .setEndTime("23:00")
        .setRunTime(30)
        .setSleepTime(30).build();
meshTimerTransaction.addTimerWithTimerModel(circulationTimerModel, new ITimerActionCallback<List<MeshTimerModel>>() {
    @Override
    public void onSuccess(List<MeshTimerModel> result) {
        Log.i(TAG, "On successful to add timer, result: " + JSON.toJSONString(result));
    }

    @Override
    public void onFailure(int errorCode, String desc) {
        Log.e(TAG, "On failed to add timer, errorCode: " + errorCode + ", desc: " + desc);
    }
});

// 添加本地倒计时
MeshTimerModel.CountDownTimerBuilder countDownTimerBuilder = new MeshTimerModel.CountDownTimerBuilder();
// 2023-03-08 22:00 为开始执行时间,假如当前时间是2023-03-08 21:00,倒计时1个小时
MeshTimerModel countDownTimer = countDownTimerBuilder.setTime("2023-3-8 22:00")
        .setTargets("powerstate:0")
        .setTimeZone(28800)
        .build();
meshTimerTransaction.addTimerWithTimerModel(countDownTimer, new ITimerActionCallback<List<MeshTimerModel>>() {
    @Override
    public void onSuccess(List<MeshTimerModel> result) {
        Log.i(TAG, "On successful to add timer, result: " + JSON.toJSONString(result));
    }

    @Override
    public void onFailure(int errorCode, String desc) {
        Log.e(TAG, "On failed to add timer, errorCode: " + errorCode + ", desc: " + desc);
    }
});
            

删除某个本地定时

// 当前最新的本地定时列表
List<MeshTimerModel> currentTimerModels;
meshTimerTransaction.deleteTimerWithTimerModel(currentTimerModels.get(0), new ITimerActionCallback<List<MeshTimerModel>>() {
    @Override
    public void onSuccess(List<MeshTimerModel> result) {
        Log.i(TAG, "On successful to delete timer, result: " + JSON.toJSONString(result));
    }

    @Override
    public void onFailure(int errorCode, String desc) {
        Log.e(TAG, "On failed to delete timer, errorCode: " + errorCode + ", desc: " + desc);
    }
});

更新某个本地定时

// 当前最新的本地定时列表
List<MeshTimerModel> currentTimerModels;

MeshTimerModel timerModel1 = currentTimerModels.get(0);
// disable该定时器
timerModel1.setEnableType(TimerEnableType.TIMER_ENABLE_NONE);

meshTimerTransaction.editTimerWithTimerModel(timerModel1, new ITimerActionCallback<List<MeshTimerModel>>() {
    @Override
    public void onSuccess(List<MeshTimerModel> result) {
        Log.i(TAG, "On successful to edit timer, result: " + JSON.toJSONString(result));
    }

    @Override
    public void onFailure(int errorCode, String desc) {
        Log.e(TAG, "On failed to edit timer, errorCode: " + errorCode + ", desc: " + desc);
    }
});