Skip to content

/ node-hue-api

Permalink
master

node-hue-api/docs/sensor.md

Go to file
 
 
Cannot retrieve contributors at this time
291 lines (190 sloc) 9.63 KB
Raw Blame

Sensor

The Hue Bridge can support a number of sensors. The API has various objects for each of the types of Sensors that the Hue Bridge can support.

Some of these Sensors are Hardware sensors whilst others are Software constructs that can be updated by API calls.

The sensors that can be built and controlled via software are the CLIP variety.

The API provides access to the Sensor objects via the v3.api.sensors API, but you can also create new CLIP Sensor objects using the various CLIP sensor classes by using the v3.model.createCLIP[xxx]Sensor() functions.

CLIP Sensors

CLIP Sensors allow you to integrate external objects and statuses into the Hue Bridge via CLIP Sensors.

For example you may have the ability to detect the humidity in a room and want to store this value in the Hue Bridge. You can do this using a CLIPHumidity Sensor which can be saved and then updated in the Hue Bridge upon changes.

All sensors have the following mandatory properties:

  • type: This is the type of sensor, this is readable and only set at the time of instantiation of the object
  • modelid: A model ID for the sensor which should uniquely identify the hardware model oif the device from the manufacturer
  • manufacturername: The manufacturer name of the sensor
  • uniqueid: A unique ID for the sensor, this should be the MAC Address of the device
  • swversion: A software version running on the sensor
  • name: A name for the sensor which will be the human readable name

The above properties have to be set when creating a new sensor from scratch in code, except for name which can be modified after creation.

All CLIP Sensors also have the following properties:

  • id: A readonly value for the id that the Hue Bridge will assign to a Sensor
  • lastupdated: A readonly timestamp value when the sensor was last updated in the Hue Bridge
  • on: get and set, turns the sensor on/off. When off, state changes of the sensor are not reflected in the sensor resource
  • reachable: get and set, indicates whether communication with the device is possible
  • battery: get and set, the current battery state in percent for battery powered devices
  • url: get and set, an optional URL to the CLIP sensor

CLIPGenericFlag

The CLIPGenericFlag sensor is a Boolean flag sensor.

A generic sensor object for 3rd party IP sensor use. E.g. the portal can make use of a Generic sensor to indicate IFTTT events.

The unique properties for the GenericFlag Sensor are:

  • flag: get and set stores a Boolean state

Creating a CLIPGenericFlag sensor can be done as shown below:

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

const mySensor = model.createCLIPGenericFlagSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'My awesome clip generic flag sensor';

// Set the flag state to true
mySensor.flag = true;

A complete code sample for sensors is available here.

CLIPGenericStatus

The CLIPGenericStatus sensor is a Integer value sensor.

A generic sensor object for 3rd party IP sensor use. E.g. the portal can make use of a Generic sensor to indicate IFTTT events.

The unique properties for the GenericFlag Sensor are:

  • status: get and set, stores an integer value

Creating a CLIPGenericStatus sensor can be done as shown below:

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

const mySensor = model.createCLIPGenericStatusSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'My awesome clip generic status sensor';
// Set the status to 1000
mySensor.status = 1000;

A complete code sample for sensors is available here.

CLIPHumidity

The CLIPHumidity sensor is a sensor measuring the current ambient humidity.

The unique properties for the Humidity Sensor are:

  • humidity: get and set, the ambient humidity in 0.01% steps, e.g. 2000 = 20%

Creating a CLIPHumidity sensor can be done as shown below:

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

const mySensor = model.createCLIPHumiditySensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'Lounge Humidity';
// Set the humidity level
mySensor.humidity = 1000; // 10%

A complete code sample for sensors is available here.

CLIPLightLevel

The CLIPLightLevel sensor indicates the ambient light level at the sensor location.

The unique properties for the Lighlevel Sensor are:

  • tholddark: get and set, threshold used in rules to determine insufficient light level, below threshold, between 0 and 65535
  • tholdoffset: get and set, threshold used in riles to determine sufficient light level, above threshold, between 0 and 65535
  • lightlevel: get and set, light level in 10000 log10 (lux) + 1 value measured by sensor, between 0 and 65535
  • dark: get and set, Boolean indicating light level is at or below given dark threshold, between 0 and 65535
  • daylight: get and set, Boolean indicating light level is at or above light threshold (dark + offset), between 0 and 65535

Creating a CLIPLightLevel sensor can be done as shown below:

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

const mySensor = model.createCLIPLightlevelSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'Lounge LightLevel';
// Set the light level
mySensor.lightlevel = 1000;

A complete code sample for sensors is available here.

CLIPOpenClose

The CLIPOpenClose sensor is for open/close status sensors, like a door or window.

The unique properties for the OpenClose Sensor are:

  • open: get and set, boolean indicating open state

Creating a CLIPOpenClose sensor can be done as shown below:

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

const mySensor = model.createCLIPOpenCloseSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'Lounge Door';
// Set the open state
mySensor.open = false;

A complete code sample for sensors is available here.

CLIPPresence

The CLIPPresense sensor is for registering the presence of someone at the location of the sensor.

The unique properties for the Presense Senor are:

  • presence: get and set, boolean indicating if there is a presence at the sensor

Creating a CLIPPresence sensor can be done as shown below:

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

const mySensor = model.createCLIPPresenceSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'Lounge Presence';
// Set the presence state
mySensor.presence = true;

A complete code sample for sensors is available here.

CLIPSwitch

The CLIPSwitch sensor is for registering switch button states.

The unique properties for the Switch Sensor are:

  • buttonevent: get and set, an integer value indicating the button event that has been triggered on the switch.

In Zigbee switches the events relate to the individual buttons that are present on the switch and the state triggered on the last button pressed/released an whether it was a short or long press.

Creating a CLIPSwitch sensor can be done as shown below:

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

const mySensor = model.createCLIPSwitchSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'Lounge Wall Switch';
// Set a button event code state
mySensor.buttonevent = 2000;

A complete code sample for sensors is available here.

CLIPTemperature

The CLIPTemperature sensor is for measuring current ambient temperature.

The unique properties for the Temperature Sensor are:

  • temperature: get and set, the current temperature in 0.01 degrees celsius, e.g. 3000 is 30.00 degrees

Creating a CLIPTemperature sensor can be done as shown below:

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

const mySensor = model.createCLIPTemperatureSensor();
mySensor.modelid = 'software';
mySensor.swversion = '1.0';
mySensor.uniqueid = '00:00:00:01';
mySensor.manufacturername = 'node-hue-api';

// Set the name of the sensor
mySensor.name = 'Lounge Temperature';
// Set a the temperature to 18.5 degrees
mySensor.buttonevent = 1850;

A complete code sample for sensors is available here.
You can’t perform that action at this time.