Command Triggers

To execute a command automatically, set the template of the command and the condition in the trigger. See the below examples.

Registering One-Time Schedule Triggers

We will show how to register a trigger to turn on an air conditioner (with the preset temperature and fan speed set to 25 degrees and 5, respectively) 1 hour from now.

  • // 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.
  }
);

This is what is happening in the sample code:

  • Create actions of the command to be executed by the trigger as actions. Here, we are setting three actions. How the command is set is the same as that in the code of Executing Commands.

  • Create a TriggerCommandObject with the schema information and actions as the command to be executed by the trigger.

  • Set the execution time in a ScheduleOncePredicate as the execution condition.

  • Create a PostCommandTriggerRequest with the command and execution condition and register it with the postCommandTrigger method as the trigger.

The function set in then of the promise will be called when Thing Interaction Framework accepts the trigger.

Registering Recurring Schedule Triggers

We will show how to register a trigger to turn on an air conditioner (with the preset temperature and fan speed set to 25 degrees and 5, respectively) at 9:00 a.m. every day.

  • // 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.
  }
);

The basic steps are the same as the case of a one-time schedule trigger. The only difference is how the execution condition is initialized.

  • Set the execution time in a SchedulePredicate as the execution condition. See Recurring Schedule to learn how to set the time.

Registering State Condition Triggers

The next example shows how to register a trigger with a simple condition. We will show how to register a trigger to turn on an air conditioner (with the preset temperature and fan speed set to 25 degrees and 5, respectively) when "the room temperature goes over 30 degrees".

  • // 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.
  }
);

The basic steps are the same as the case of schedule triggers. The only difference is how the execution condition is initialized.

  • Create a trigger condition. First, set the comparison condition in a Condition. In this example, we are creating the condition that will become true when currentTemperature defined in State is greater than or equal to 30 degrees.
  • Create a StatePredicate to finalize the trigger condition. In this example, we are specifying CONDITION_FALSE_TO_TRUE because we want to execute the command when the room temperature goes up from below 30 degrees to above 30 degrees.

Setting a Trigger with Multiple Conditions

The next example shows how to concatenate conditions with AND. In this example, we will set a trigger to set the fan speed to 10 when "the power is on" and "the room humidity is above 80".

  • // 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.
  }
);

The basic steps are the same as the case of a single condition trigger. The only difference is how a Condition is initialized. In this example, we first create two conditions "power is equal to true" and "currentHumidity is greater than 80", concatenate them with an And, and then set the concatenated condition as the comparison condition.

Registering Advanced Triggers

You can register advanced triggers as below by specifying detailed information.

  • A trigger which sends a command to a different thing

    You can register a trigger that sends a command to a different thing when a state condition is met on the thing to which you register the trigger.

    For example, if you manage a thermometer and an air conditioner as separate things, you can register a trigger to "turn on the air conditioner when the thermometer rises to a certain temperature".

  • A trigger with details of the trigger and the command in it

    You can set the title, description, and metadata of the trigger and the command in it.

  • // 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.
  }
);

The following processes are executed in the code:

  • Specify the command to be executed when the condition is met as a TriggerCommandObject. Create this instance from the information below.

    • Specify the thing to which the trigger sends the command in target.
      This sample code assumes that the thermometer and the air conditioner are managed with the ThingIFAPI instances, api and api2, respectively. When the state of api (thermometer) meets the trigger condition, the trigger sends a command which turns on the air conditioner to target obtained from api2 (air conditioner).
      You need to have instantiated and onboarded api and api2 with the same owner.
    • Specify actions to be executed by the command in actions.
    • Specify the command details in commandTitle, commandDescription, and commandMetadata.
      You can freely use these fields according to your mobile app specification as explained in Command Details. See Command Details also for limits such as the maximum length of each field.

  • Create the execution condition as a StatePredicate.

  • Specify the above TriggerCommandObject, StatePredicate, and trigger details in a PostCommandTriggerRequest. You can set the trigger details for your mobile app as you can for commands. The same limits such as the maximum length apply to triggers and commands.

  • Finally, register the new trigger by calling the postCommandTrigger method with the created PostCommandTriggerRequest.