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

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

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

単発の時間条件を持つトリガーとして、「今から 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 に設定した関数が呼び出されます。

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

繰り返しの時間条件を持つトリガーとして、「毎日午前 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 にトリガーの実行時間を指定し、トリガーの実行条件とします。設定方法については、時間条件（繰り返し）を参照してください。

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

単純なステート条件を持つトリガーとして、「室温が 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 インスタンスの api と api2 によって、それぞれ温度計デバイスとエアコンの Thing が管理されているものとします。api（温度計）のステートが指定条件を満たした場合、api2（エアコン）から取得した target に対してエアコンの電源を入れるコマンドを実行します。
  api と api2 は、それぞれでインスタンス生成や初期登録処理が実行されており、同一のオーナーであることが必要です。
- コマンドが実行するアクションを actions に用意します。
- commandTitle、 commandDescription、 commandMetadata に詳細情報を用意します。
  これらはコマンドの詳細情報に示すとおり、アプリケーションの仕様に合わせて自由に利用できます。最大長などの制限値についてもコマンドの詳細情報をご覧ください。
実行する条件を StatePredicate として作成します。
PostCommandTriggerRequest に上記の TriggerCommandObject、 StatePredicate、トリガーの詳細情報を指定します。トリガーの詳細情報は、コマンドと同様、アプリケーション独自の情報を設定できます。最大長などの制限値はコマンドに対する詳細情報と同じです。
最後に、作成した PostCommandTriggerRequest を引数として postCommandTrigger メソッドを呼び出して、新しいトリガーを登録します。