node-hue-api

A RuleCondition is an object that defines the criteria used to trigger a Rule on the Hue Bridge. The API provides a fluent interface via v3.model.ruleConditions to build these conditions. Currently, you can build conditions for two types of entities:

1. Sensors: Using v3.model.ruleConditions.sensor(sensor)
2. Groups: Using v3.model.ruleConditions.group(id)

To finalize the builder and obtain a valid RuleCondition object, you must call .getRuleCondition() at the end of your fluent chain. If the configuration is invalid, this method will throw an ApiError.

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

// Example pattern for building a condition
const ruleCondition = conditions.sensor(mySensor)
  .when('attribute')
  .equals(value)
  .getRuleCondition();

A RuleAction is an object that defines an action to be performed when a Hue Bridge Rule is triggered. The API provides a fluent interface via v3.rules.actions to build these actions.

All RuleAction types inherit from a base class that provides the following properties and methods:

• address: Gets the target address for the action.
• id: Gets the target ID (e.g., Light ID, Group ID, or Sensor ID).
• method: Gets the HTTP method (usually PUT).
• withMethod(method): Sets the HTTP method.
• payload(): Returns the JSON payload that will be sent to the Hue Bridge.
• body: Gets the body payload.
• toString(): Returns a string representation.

The Scenes API interacts with Scene objects stored on the Hue Bridge. These are distinct from the preset scenes found in mobile Hue applications.

Be aware of the following hardware limitations on the Hue Bridge:

• Maximum Scenes: Up to 200 scenes.
• Maximum Scene LightStates: 2048 total.

Note that the actual number of scenes you can store depends on how many light states each scene contains. For example, if every scene contains 20 light states, the bridge can only support 102 scenes ($2048 / 20 = 102.4$).

The Hue Bridge supports two distinct types of Scenes. The type attribute is implicitly set by the API based on the properties you provide, so you should generally avoid setting it manually.

1. LightScene: The default scene type. It maintains a specific list of lights that can be updated independently of any group membership.
2. GroupScene: A scene linked to a specific group. The lights involved in a GroupScene are determined by the membership of that group. If the group is removed or becomes empty, the associated GroupScene is also removed. You cannot modify the lights of a GroupScene directly; they are controlled via the group object.

The library supports interacting with the Hue Remote API in addition to local network connections. While most endpoints function similarly to the local API, there are some limitations on remote endpoints.

Setup involves either:

1. Connecting from scratch (remote access setup).
2. Using existing OAuth tokens.

Refer to the docs/remoteApi.md for full documentation and the examples/v3/remote/ directory for implementation details.

In node-hue-api, all lights on the Hue Bridge are represented by a Light instance. Because different hardware supports different features, the properties available on a Light instance depend on its underlying type.

Known light types include:

• On Off Light
• Dimmable Light
• Color Light
• Color Temperature Light
• Extended Color Light