Bluetooth Mesh SDK for local scheduling

Overview

Usage notes

Check the Bluetooth Mesh network connection

You can use the following methods to determine whether you are connected to the Mesh network.

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

Local scheduling operations

Get the MeshTimerTransaction object

Before you add, delete, or update a local scheduled task on a mesh node, you must obtain the MeshTimerTransaction object.

// The input parameter is the iotId of the mesh device.
String iotId = "***";
MeshTimerTransaction meshTimerTransaction = MeshTimerTransaction.initWithIotID(iotId);

Get the list of scheduled tasks for a device

• The MeshTimerModel object model

  public enum TimerType {
      TIMER_NONE(0),
      TIMER_COUNTDOWN(1), // Countdown timer
      TIMER_NORMAL(2), // Normal timer
      TIMER_CIRCULATION(3); // Periodic timer
  }
  
  public enum TimerEnableType {
      TIMER_ENABLE_NONE(0), // Timer disabled
      TIMER_ENABLE(1), // Enabled
      TIMER_IN_FLIGHT(2);
  }
  
  public class MeshTimerModel{
      private String timerID;
      // Start time
      // Countdown timer: yyyy-MM-dd HH:mm
      // Normal timer: HH:mm
      // Periodic timer: HH:mm
      private String time;
      // For normal and periodic timers
      // Format: "1,2,3,4,5,6,7" (1 for Sunday, 2 for Monday, and so on)
      private String days;
      // Timer type
      private TimerType timerType;
      // Specifies whether the timer is enabled.
      private TimerEnableType enableType;
      // The specific action for the scheduled task. This controls multiple properties and their values. Separate each property-value pair with a comma (,). Example: "powerstate:1,mode:2"
      // For periodic timers, if the string contains a pipe (|), the action before the pipe is executed during RunTime, and the action after the pipe is executed during SleepTime.
      private String attributesTargets;
      // The difference between the local event time and UTC.
      // Unit: seconds.
      // Value range: -43200 to 50400.
      // Step size: 3600.
      private int timeZone;
      // End time. Used for periodic timers.
      // Example: HH:mm
      private String endTime;
      // The running duration, such as on for 30 minutes. Used for periodic timers. Unit: seconds.
      private int runTime;
      // The sleep duration. Used for periodic timers. Unit: seconds.
      private int sleepTime;
  }

• Retrieve the list of scheduled tasks

  Retrieve the list of scheduled tasks for the current device.

  Note

  Call this method before you update, delete, or add a local scheduled task.

  // The input parameter is the iotId of the mesh device.
  String iotId = "";
  MeshTimerTransaction meshTimerTransaction = MeshTimerTransaction.initWithIotID(iotId);
  
  meshTimerTransaction.getDeviceTimerList(new ITimerActionCallback<List<MeshTimerModel>>() {
          @Override
          public void onSuccess(List<MeshTimerModel> result) {
              // result is the list of local scheduled tasks for the current device.
          }
  
          @Override
          public void onFailure(int errorCode, String desc) {
              //
          }
      });
  
                      

Timer operations

The SDK lets you add, delete, or update a timer. You must ensure that an operation is complete before you start the next one. Operate on only one timer at a time.

Operation error codes

public interface ErrorCode {
    // The SDK failed to get the list of scheduled tasks for the current device. Check if the device's Thing Specification Language model supports local scheduling.
    int ERROR_UNSUPPORTED_OPERATIONS = -1;
    // Call the getDeviceTimerList method first to initialize the SDK.
    int ERROR_INVOCATION_PROCESS = -2;
    // The local timer list is full. You cannot add more timers.
    int ERROR_TIMING_ALREADY_FULL = -3;
    // The timerID in MeshTimerModel is invalid. The caller must ensure that the timerID is not updated.
    int ERROR_INVALID_TIMER_ID = -4;
    // Failed to set the local timer. The device may not be connected to the local mesh network.
    int ERROR_SEND_FAILED = -5;
    // The device's local timer timed out. Possible reasons:
    // 1. The target device is not nearby or is powered off.
    // 2. The device firmware does not support setting timers.
    // 3. The timer parameters are invalid.
    int ERROR_SET_TIMER_TIMEOUT = -6;
    // You must wait for the previous operation to complete.
    int ERROR_EXIT_PENDING_TASK = -7;
}

Add a local scheduled task

The SDK provides Builder methods to create normal, periodic, and countdown local timers.

For countdown timers, the cloud automatically purges the timer when it expires. Use getDeviceTimerList to refresh the local list of scheduled tasks.

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

// Add a normal local timer.
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 is the latest list of scheduled tasks. The business layer must use this object for subsequent operations.
        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);
    }
});

// Add a periodic local timer.
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);
    }
});

// Add a local countdown timer.
MeshTimerModel.CountDownTimerBuilder countDownTimerBuilder = new MeshTimerModel.CountDownTimerBuilder();
// 2023-03-08 22:00 is the start time. If the current time is 2023-03-08 21:00, the countdown is 1 hour.
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);
    }
});
            

Delete a local scheduled task

// The latest list of local scheduled tasks.
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);
    }
});

Update a local scheduled task

// The latest list of local scheduled tasks.
List<MeshTimerModel> currentTimerModels;

MeshTimerModel timerModel1 = currentTimerModels.get(0);
// Disable the timer.
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);
    }
});