コマンドを実行するトリガー

コマンドを自動実行する場合、実行するコマンドのテンプレートと実行条件をトリガーに設定します。以下に例を示します。

時間条件（単発）のトリガーの登録

単発の時間条件を持つトリガーとして、「今から 1 時間後に、エアコンをオンにする（設定温度 25 度、ファンスピード 5）」というトリガーを登録する例を以下に示します。

// Create a command.
List<Action> actions = new ArrayList<Action>();
TurnPower action1 = new TurnPower();
action1.power = true;

SetPresetTemperature action2 = new SetPresetTemperature();
action2.presetTemperature = 25;

SetFanSpeed action3 = new SetFanSpeed();
action3.fanSpeed = 5;

actions.add(action1);
actions.add(action2);
actions.add(action3);

// Create a predicate.
// Execute the command in an hour.
long scheduleAt = new Date().getTime() + 60 * 60 * 1000;
ScheduleOncePredicate predicate = new ScheduleOncePredicate(scheduleAt);

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger("AirConditioner-Demo", 1, actions, predicate);
} catch (ThingIFException e) {
  // Handle the error.
}

ここでは以下の処理が行われています。

  • List<Action> に、トリガーによって実行されるコマンドを作成します。ここでは、3 つのアクションを順番に設定しています。設定方法は コマンドの実行 のコードと同じです。

  • scheduleAt にトリガーの実行時間を設定し、ScheduleOncePredicate の引数とします。

  • 最終的に、postNewTrigger メソッドでトリガーを登録します。

Thing Interaction Framework がトリガーを受け付けた段階で API は制御を返します。

時間条件（繰り返し）のトリガーの登録

繰り返しの時間条件を持つトリガーとして、「毎日午前 9 時に、エアコンをオンにする（設定温度 25 度、ファンスピード 5）」というトリガーを登録する例を以下に示します。

// Create a command.
List<Action> actions = new ArrayList<Action>();
TurnPower action1 = new TurnPower();
action1.power = true;

SetPresetTemperature action2 = new SetPresetTemperature();
action2.presetTemperature = 25;

SetFanSpeed action3 = new SetFanSpeed();
action3.fanSpeed = 5;

actions.add(action1);
actions.add(action2);
actions.add(action3);

// Create a predicate.
// Execute the command at 9:00 a.m. every day.
SchedulePredicate predicate = new SchedulePredicate("0 9 * * *");

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger("AirConditioner-Demo", 1, actions, predicate);
} catch (ThingIFException e) {
  // Handle the error.
}

基本的な流れは、単発の時間条件の場合と同じですが、トリガーの実行条件の初期化方法が異なります。

  • SchedulePredicate の引数としてトリガーの実行時間を設定します。設定方法については、時間条件（繰り返し） を参照してください。

ステート条件のトリガーの登録

単純なステート条件を持つトリガーとして、「室温が 30 度以上の時、エアコンをオンにする（設定温度 25 度、ファンスピード 5）」というトリガーを登録する例を以下に示します。

// Create a command.
List<Action> actions = new ArrayList<Action>();
TurnPower action1 = new TurnPower();
action1.power = true;

SetPresetTemperature action2 = new SetPresetTemperature();
action2.presetTemperature = 25;

SetFanSpeed action3 = new SetFanSpeed();
action3.fanSpeed = 5;

actions.add(action1);
actions.add(action2);
actions.add(action3);

// Create a predicate.
// Execute the command when the temperature is greater than or equal to 30 deg C.
Condition condition = new Condition(Range.greaterThanEquals("currentTemperature", 30));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger("AirConditioner-Demo", 1, actions, predicate);
} catch (ThingIFException e) {
  // Handle the error.
}

基本的な流れは、時間条件の場合と同じですが、トリガーの実行条件の初期化方法が異なります。

  • トリガーの実行条件を作成します。まず、Condition に比較条件を設定します。ここでは、ステート で登録している currentTemperature が 30 以上の場合に true になる条件を作成しています。
  • 次に、StatePredicate を作成します。StatePredicate が最終的にトリガーに登録する条件です。コマンドは、30 度未満の状態から 30 度以上になったときに実行したいため、CONDITION_FALSE_TO_TRUE を指定します。

複数のステート条件での登録例

ステート条件を AND で結合するトリガーの例を以下に示します。この例では、「電源がオン」かつ「湿度が 80 より大きい」場合に「ファンスピードを 10 に設定する」というトリガーを登録します。

// Create a command.
List<Action> actions = new ArrayList<Action>();
SetFanSpeed action = new SetFanSpeed();
action.fanSpeed = 10;

actions.add(action);

// Create a predicate.
// Execute the command when the power is on and the humidity is greater than 80%.
Condition condition = new Condition(
    new And(new Equals("power", true),
            Range.greaterThan("currentHumidity", 80)));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger("AirConditioner-Demo", 1, actions, predicate);
} catch (ThingIFException e) {
  // Handle the error.
}

基本的な流れは、単一のステート条件の場合と同じですが、Condition の初期化方法が異なります。ここでは、「power が true に等しい」という条件と、「currentHumidity が 80 より大きい」という 2 つの条件を作成し、それを And で結合したものを比較条件として設定しています。

詳細情報を指定したトリガーの登録例

トリガーを設定する際、詳細情報を指定することで、以下のようなトリガーを登録することができます。

  • 他の Thing にコマンドを送信

    ある Thing でステート条件が満たされたとき、別の Thing にコマンドを送信するようなトリガーを登録できます。

    例えば、温度計デバイスとエアコンが別の Thing として管理されているとき、「温度計デバイスが一定の温度以上になったとき、エアコンの電源を入れる」というようなトリガーを実現できます。

  • コマンドやトリガーの詳細情報を設定

    コマンドとトリガーのそれぞれに対して、タイトル、詳細な説明文、JSON 形式で表現された任意のメタ情報を設定できます。

// Create a command.
List<Action> actions = new ArrayList<Action>();
TurnPower action1 = new TurnPower();
action1.power = true;

SetPresetTemperature action2 = new SetPresetTemperature();
action2.presetTemperature = 25;

SetFanSpeed action3 = new SetFanSpeed();
action3.fanSpeed = 5;

actions.add(action1);
actions.add(action2);
actions.add(action3);

// Get the target thing that receives the command.
Target target = api2.getTarget();

// Create a command form from detailed information.
TriggeredCommandForm.Builder cb = TriggeredCommandForm.builder("AirConditioner-Demo", 1, actions);
cb.setTargetID(target.getTypedID());
cb.setTitle("Power on");
cb.setDescription("Power on and set to 25 deg C");
cb.setMetadata(new JSONObject("{ \"iconIndex\" : 2, \"issuer\" : \"trigger\" }"));
TriggeredCommandForm form = cb.build();

// Create a predicate.
Condition condition = new Condition(Range.greaterThanEquals("currentTemperature", 30));
StatePredicate predicate = new StatePredicate(condition, TriggersWhen.CONDITION_FALSE_TO_TRUE);

// Create trigger options from detailed information.
TriggerOptions.Builder ob = TriggerOptions.builder();
ob.setTitle("Power on");
ob.setDescription("Power on when the temperature goes over 30 deg C");
ob.setMetadata(new JSONObject("{ \"createdBy\" : \"Alice\" }"));
TriggerOptions options = ob.build();

try {
  // Send a trigger.
  Trigger trigger = api.postNewTrigger(form, predicate, options);
} catch (ThingIFException e) {
  // Handle the error.
}

ここでは、次の処理を行っています。

  • 条件が満たされた場合に実行されるアクションを actions に用意します。

  • TriggeredCommandForm.Builder によって、実行するコマンドの詳細を以下のように指定します。設定後、build メソッドで TriggeredCommandForm を作成します。

    • setTargetID メソッドでコマンドの送信先の Thing を指定します。
      このサンプルコードでは、ThingIFAPI インスタンスの api と api2 によって、それぞれ温度計デバイスとエアコンの Thing が管理されているものとします。api（温度計）のステートが指定条件を満たした場合、api2（エアコン）から取得した target に対してエアコンの電源を入れるコマンドを実行します。
      api と api2 は、それぞれでインスタンス生成や初期登録処理が実行されており、同一のオーナーであることが必要です。
      なお、setTargetID の呼び出しを省略した場合は postNewTrigger を実行した ThingIFAPI に設定されている Thing にコマンドを送信します。
    • setTitle、 setDescription、 setMetadata メソッドによって詳細情報を設定できます。
      これらは コマンドの詳細情報 に示すとおり、アプリケーションの仕様に合わせて自由に利用できます。最大長などの制限値についても コマンドの詳細情報 をご覧ください。

  • 実行する条件を StatePredicate として作成します。

  • TriggerOptions.Builder によって、トリガーに対する詳細情報を指定します。コマンドと同様、アプリケーション独自の情報を設定できます。最大長などの制限値はコマンドに対する詳細情報と同じです。設定後、build メソッドで TriggerOptions を作成します。

  • 最後に、作成した TriggeredCommandForm、 StatePredicate、 TriggerOptions を postNewTrigger メソッドに指定して、新しいトリガーを登録します。