Skip to content

Latest commit

 

History

History
162 lines (111 loc) · 6.96 KB

ruleCondition.md

File metadata and controls

162 lines (111 loc) · 6.96 KB
Raw

RuleCondition

A RuleCondition is an object that defines a condition that can be used to trigger a Rule in the Hue Bridge.

There are a number of different types of RuleConditions that can be built and to aid in this, the API provides a fluent interface for building up the various RuleConditions for Rules.

Condition Builders

A RuleCondition can be built using the v3.model.ruleCconditions Object, currently this allows for the creation of conditions for Sensors and Groups.

SensorCondition Builder

A SensorCondition builder can be created using the v3.model.ruleConditions.sensor(sensor) function.

  • sensor: The Sensor obtained from bridge via the API that you wish to use in a condition.

You have to provide a Sensor object from the Hue Bridge (you can use the Sensors API to get an instance of the one you desire).

const v3 = require('node-hue-api').v3
  , conditions = v3.model.ruleConditions;

const mySensor = await v3.sensors.get(sesnorId);
const mySensorCondition = conditions.sensor(mySensor);
// Then build the condition using the functions/properties on the SensorConditions

when(attribute)

The whne(attribute) function specifies the target attribute of the sensor to set the condition on. The attributes vary on the Sensors based on what type of sensor that it is.

  • attribute: The String name of the attribute for the Sensor that you are applying the condition to

For example a CLIPGenericFlag has an attribute of flag that is a boolean flag that can be monitored.

This function will return an Object that allows you to select the appropriate RuleOperator by invoking an appropriate function, see below for more details.

Sensor Attribute Operator

  • equals(val): The specified attribute equals val, compatible with boolean and int attributes
  • greaterThan(val): The specified attribute is greater than val, compatible with int attributes
  • lessThan(val): The specified attribute is less than val, compatible with int attributes
  • changed(): The specified attribute has changed
  • changedDelayed(val): The specified attribute changed within a val interval period (a delayed change)
  • stable(val): The specified attribute has not changed in a specified val interval
  • notStable(val): The specified attribute has changed in a specified val interval
  • in(val): Current time is within the specified interval, triggered on starttime
  • notIn(val): Current time is not with the specified interval, triggered on endtime

Any of these functions when called will return the SensorCondition object that you started with.

getRuleCondition()

The getRuleCondition() function will generate the RuleCondition instance that has been built from the various calls that you have made via the fluent API for the builder.

This will return a RuleCondition if the provided configuration is valid. Otherwise it will throw and ApiError.

Note: Not every aspect of the condition can be checked at this point, and as such the final validation will be performed via the Hue Bridge when the RuleCondition is saved/updated on a Rule.

SensorCondition Examples

The following are code examples of setting up various SensorConditions.

Create a RuleCondition that will trigger on a flag attribute change on a CLIPGenericFlag Sensor (i.e. trigger on every change):

const v3 = require('node-hue-api').v3
  , conditions = v3.model.ruleConditions
;

// Create a SensorCondition that will trigger on a flag attribute change for the CLIPGenericFlag Sensor:
const sensorCondition = conditions.sensor(aFlagSensor).when('flag').changed();
const ruleCondition = sensorCondition.getRuleCondition();

Create a RuleCondition that will trigger when the flag attribute changes to true for a CLIPGenericFlag Sensor:

const v3 = require('node-hue-api').v3
  , conditions = v3.model.ruleConditions
;

// Create a SensorCondition that will trigger on the flag attribute being true CLIPGenericFlag Sensor:
const sensorCondition = conditions.sensor(aFlagSensor).when('flag').equals(true);
const ruleCondition = sensorCondition.getRuleCondition();

GroupCondition Builder

A GroupCondition builder can be created using the v3.model.ruleConditions.group(id) function.

  • id: The id for the group (or the Group instance) that you wish to build the condition on

You can pass in either the id value for the group or a Group instance from the API to start building the condition.

when()

The when() function obtains the Attribute selector for the group which allows you to select the desired Group attribute that the condition will be built from.

Group Attribute Selector

There are only two attributes for a group that can be used to build a condition on which are exposed via the following functions:

  • allOn(): Boolean attribute that is true when ALL the lights in a group are on
  • anyOn(): Boolean attribute that is true when ANY of the lights in a group are on

Either of these functons will return an Operator Selector object that will allow you to set the operator (and possible value) on the condition that you are building.

Group Attribute Operator

  • equals(val): The attribute equals the specified val
  • changed(): The attribute is changed
  • changedDelayed(val): The attribute is a delayed changed within a period val

Any of these functions will return the GroupCondition that you started with.

getRuleCondition()

The getRuleCondition() function will generate the RuleCondition instance that has been built from the various calls that you have made via the fluent API for the builder.

This will return a RuleCondition if the provided configuration is valid. Otherwise it will throw and ApiError.

Note: Not every aspect of the condition can be checked at this point, and as such the final validation will be performed via the Hue Bridge when the RuleCondition is saved/updated on a Rule.

GroupCondition Examples

The following are code examples of setting up various GroupConditions.

Create a GroupCondition that will trigger when any light is on in a group:

const v3 = require('node-hue-api').v3
  , conditions = v3.model.ruleConditions
;

// Create a SensorCondition that will trigger on a flag attribute change for the CLIPGenericFlag Sensor:
const groupCondition = conditions.group(groupId).when().anyOn().equals(true);
const ruleCondition = groupCondition.getRuleCondition();