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

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

時間条件(単発)のトリガーの登録

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

  • // Create a command.
    const actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    const command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command in an hour.
    const predicate = new ThingIF.ScheduleOncePredicate(new Date().getTime() + 60 * 60 * 1000);
    
    // Create a trigger request.
    const triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then((trigger: ThingIF.Trigger) => {
      // Do something.
    }).catch((error: ThingIF.ThingIFError) => {
      // Handle the error.
    });
  • // Create a command.
    var actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    var command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command in an hour.
    var predicate = new ThingIF.ScheduleOncePredicate(new Date().getTime() + 60 * 60 * 1000);
    
    // Create a trigger request.
    var triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then(
      function(trigger) {
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
      }
    );

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

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

  • スキーマの情報とアクションから TriggerCommandObject を作成し、トリガーによって実行されるコマンドとします。

  • ScheduleOncePredicate にトリガーの実行時間を指定し、トリガーの実行条件とします。

  • コマンドと実行条件から PostCommandTriggerRequest を作成し、postCommandTrigger メソッドでトリガーを登録します。

Thing Interaction Framework がトリガーを受け付けた段階で Promise の then に設定した関数が呼び出されます。

401 Unauthorized が発生する場合

時間指定のトリガーの利用にはサーバーの設定が必要です。まだ設定していない場合は、support@kii.com 宛てにお申し込みください。

時間条件(繰り返し)のトリガーの登録

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

  • // Create a command.
    const actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    const command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command at 9:00 a.m. every day.
    const predicate = new ThingIF.SchedulePredicate("0 9 * * *");
    
    // Create a trigger request.
    const triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then((trigger: ThingIF.Trigger) => {
      // Do something.
    }).catch((error: ThingIF.ThingIFError) => {
      // Handle the error.
    });
  • // Create a command
    var actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    var command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command at 9:00 a.m. every day.
    var predicate = new ThingIF.SchedulePredicate("0 9 * * *");
    
    // Create a trigger request.
    var triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then(
      function(trigger) {
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
      }
    );

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

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

401 Unauthorized が発生する場合

時間指定のトリガーの利用にはサーバーの設定が必要です。まだ設定していない場合は、support@kii.com 宛てにお申し込みください。

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

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

  • // Create a command.
    const actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    const command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command when the temperature is greater than or equal to 30 deg C.
    const condition = new ThingIF.Condition(ThingIF.Range.greaterThanEquals("currentTemperature", 30));
    const predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);
    
    // Create a trigger request.
    const triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then((trigger: ThingIF.Trigger) => {
      // Do something.
    }).catch((error: ThingIF.ThingIFError) => {
      // Handle the error.
    });
  • // Create a command.
    var actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    var command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command when the temperature is greater than or equal to 30 deg C.
    var condition = new ThingIF.Condition(ThingIF.Range.greaterThanEquals("currentTemperature", 30));
    var predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);
    
    // Create a trigger request.
    var triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then(
      function(trigger) {
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
      }
    );

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

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

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

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

  • // Create a command.
    const actions = [
      {"setFanSpeed":{"fanSpeed":10}}
    ];
    const command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command when the power is on and the humidity is greater than 80%.
    const condition = new ThingIF.Condition(
                new ThingIF.And(new ThingIF.Equals("power", true),
                                ThingIF.Range.greaterThan("currentHumidity", 80)));
    const predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);
    
    // Create a trigger request.
    const triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then((trigger: ThingIF.Trigger) => {
      // Do something.
    }).catch((error: ThingIF.ThingIFError) => {
      // Handle the error.
    });
  • // Create a command.
    var actions = [
      {"setFanSpeed":{"fanSpeed":10}}
    ];
    var command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, api.target);
    
    // Create a predicate.
    // Execute the command when the power is on and the humidity is greater than 80%.
    var condition = new ThingIF.Condition(
                new ThingIF.And(new ThingIF.Equals("power", true),
                                ThingIF.Range.greaterThan("currentHumidity", 80)));
    var predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);
    
    // Create a trigger request.
    var triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then(
      function(trigger) {
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
      }
    );

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

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

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

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

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

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

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

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

  • // Get the target thing that receives a command.
    const target = api2.target;
    
    // Create a command.
    const actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    const commandTitle = "Power on";
    const commandDescription = "Power on and set to 25 deg C";
    const commandMetadata = { "iconIndex":2, "issuer":"trigger" };
    const command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, target, null, commandTitle, commandDescription, commandMetadata);
    
    // Create a predicate.
    const condition = new ThingIF.Condition(ThingIF.Range.greaterThanEquals("currentTemperature", 30));
    const predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);
    
    // Create a trigger request from detailed information.
    const triggerTitle = "Power on";
    const triggerDescription = "Power on when the temperature goes over 30 deg C";
    const triggerMetadata = { "createdBy":"Alice" };
    const triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate, triggerTitle, triggerDescription, triggerMetadata);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then((trigger: ThingIF.Trigger) => {
      // Do something.
    }).catch((error: ThingIF.ThingIFError) => {
      // Handle the error.
    });
  • // Get the target thing that receives a command.
    var target = api2.target;
    
    // Create a command.
    var actions = [
      {"turnPower":{"power":true}},
      {"setPresetTemperature":{"presetTemperature":25}},
      {"setFanSpeed":{"fanSpeed":5}}
    ];
    var commandTitle = "Power on";
    var commandDescription = "Power on and set to 25 deg C";
    var commandMetadata = { "iconIndex":2, "issuer":"trigger" };
    var command = new ThingIF.TriggerCommandObject("AirConditioner-Demo", 1, actions, target, null, commandTitle, commandDescription, commandMetadata);
    
    // Create a predicate.
    var condition = new ThingIF.Condition(ThingIF.Range.greaterThanEquals("currentTemperature", 30));
    var predicate = new ThingIF.StatePredicate(condition, ThingIF.TriggersWhen.CONDITION_FALSE_TO_TRUE);
    
    // Create a trigger request from detailed information.
    var triggerTitle = "Power on";
    var triggerDescription = "Power on when the temperature goes over 30 deg C";
    var triggerMetadata = { "createdBy":"Alice" };
    var triggerRequest = new ThingIF.PostCommandTriggerRequest(command, predicate, triggerTitle, triggerDescription, triggerMetadata);
    
    // Send a trigger.
    api.postCommandTrigger(triggerRequest).then(
      function(trigger) {
        // Do something.
      }
    ).catch(
      function(error) {
        // Handle the error.
      }
    );

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

  • 条件が満たされた場合に実行されるコマンドを TriggerCommandObject として作成します。このインスタンスは以下の情報から作成します。

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

  • PostCommandTriggerRequest に上記の TriggerCommandObjectStatePredicate、トリガーの詳細情報を指定します。トリガーの詳細情報は、コマンドと同様、アプリケーション独自の情報を設定できます。最大長などの制限値はコマンドに対する詳細情報と同じです。

  • 最後に、作成した PostCommandTriggerRequest を引数として postCommandTrigger メソッドを呼び出して、新しいトリガーを登録します。