Device

The Device class is a representation of a device paired in Homey. This class should be extended and exported from device.js, or any custom class as returned in Driver#onMapDeviceClass. Methods prefixed with on are meant to be overriden. It is not allowed to overwrite the constructor.

Table of Contents

Tutorials:

Methods

getAvailable() → {boolean}

Get the device's availability

Returns:
Type:
boolean

If the device is marked as available

getCapabilities() → {Array}

Get an array of capabilities

Returns:
Type:
Array

The device's capabilities array

getCapabilityValue(capabilityId) → {*}

Get a device's capability value

Parameters:
Name Type Description
capabilityId string
Returns:
Type:
*

The value, or null when unknown

getClass() → {string}

Get the device's class

Returns:
Type:
string

The device's class

getData() → {Object}

Get the device's data object

Returns:
Type:
Object

The device's data object

getDriver() → {Driver}

Get the device's driver

Returns:
Type:
Driver

The device's driver instance

getName() → {string}

Get the device's name

Returns:
Type:
string

The device's name

getSetting(key) → {*}

Get a device's setting value

Parameters:
Name Type Description
key String
Returns:
Type:
*

The value, or null when unknown

getSettings() → {Object}

Get the device's settings object

Tutorials:
Returns:
Type:
Object

The device's settings object

getState() → {Object}

Get the device's state (capability values)

Returns:
Type:
Object

The device's state object

getStore() → {Object}

Get the entire store

Returns:
Type:
Object

getStoreKeys() → {Array.<String>}

Get all store keys.

Returns:
Type:
Array.<String>

getStoreValue(key) → {*}

Get a store value.

Parameters:
Name Type Description
key string
Returns:
Type:
*

value

hasCapability(capabilityId) → {boolean}

Returns true if the device has a certain capability

Parameters:
Name Type Description
capabilityId string
Returns:
Type:
boolean

onAdded()

This method is called when the user adds the device, called just after pairing.

onDeleted()

This method is called when the user deleted the device.

onInit()

This method is called when the device is loaded, and properties such as name, capabilities and state are available.

onRenamed(name)

This method is called when the user updates the device's name. Use this to synchronize the name to the device or bridge.

Parameters:
Name Type Description
name string

The new name

onSettings(oldSettings, newSettings, changedKeys, callback)

This method is called when the user updates the device's settings.

Tutorials:
Parameters:
Name Type Description
oldSettings Object

The old settings object

newSettings Object

The new settings object

changedKeys Array

An array of keys changed since the previous version

callback Device~settingsCallback

ready(callback)

Pass a callback method, which is called when the Device is ready (Device#onInit has been run). The callback is executed immediately when the Drivers Manager was already ready.

Parameters:
Name Type Description
callback function

registerCapabilityListener(capabilityId, fn)

Register a listener for a capability change event. This is invoked when a device's state change is requested.

Parameters:
Name Type Description
capabilityId string
fn function
Name Type Description
value Mixed

The new value

opts Object

An object with optional properties, e.g. { duration: 300 }

callback genericCallbackFunction
Example
this.registerCapabilityListener('dim', ( value, opts ) => {
  this.log('value', value);
  this.log('opts', opts);
  return Promise.resolve();
});

registerMultipleCapabilityListener(capabilityIds, fn, timeout)

Register a listener for multiple capability change events. The callback is debounced with timeout This is invoked when a device's state change is requested.

Parameters:
Name Type Description
capabilityIds Array.<string>
fn function
Name Type Description
valueObj Mixed

An object with the changed capability values, e.g. { dim: 0.5 }

optsObj Object

An object with optional properties, per capability, e.g. { dim: { duration: 300 } }

callback genericCallbackFunction
timeout number

The debounce timeout

Example
this.registerMultipleCapabilityListener([ 'dim', 'light_hue', 'light_saturation' ], ( valueObj, optsObj ) => {
  this.log('valueObj', valueObj);
  this.log('optsObj', optsObj);
  return Promise.resolve();
}, 500);

setAvailable(callbackopt) → {Promise}

Set the device's availability to true

Parameters:
Name Type Attributes Description
callback genericCallbackFunction <optional>
Returns:
Type:
Promise

setCapabilityValue(capabilityId, value, callbackopt) → {Promise}

Set a device's capability value

Parameters:
Name Type Attributes Description
capabilityId string
value *
callback genericCallbackFunction <optional>
Returns:
Type:
Promise

setSettings(newSettings, callbackopt) → {Promise}

Set the device's settings object. The newSettings object may contain a subset of all settings. Note that the Device#onSettings method will not be called when the settings are changed programmatically.

Tutorials:
Parameters:
Name Type Attributes Description
newSettings Object

A settings object

callback genericCallbackFunction <optional>
Returns:
Type:
Promise

setStoreValue(key, value, callbackopt) → {Promise}

Set a store value.

Parameters:
Name Type Attributes Description
key string
value *
callback function <optional>
Name Type Description
err Error
store Object

The new store

Returns:
Type:
Promise

setUnavailable(message, callbackopt) → {Promise}

Set the device's availability to false, with a message

Parameters:
Name Type Attributes Description
message string

Custom unavailable message, or null for default

callback genericCallbackFunction <optional>
Returns:
Type:
Promise

triggerCapabilityListener(capabilityId, value, opts, callbackopt) → {Promise}

Trigger a capability listener programmatically.

Parameters:
Name Type Attributes Description
capabilityId string
value Mixed
opts Object
callback genericCallbackFunction <optional>
Returns:
Type:
Promise

unsetStoreValue(key, callbackopt) → {Promise}

Unset a store value.

Parameters:
Name Type Attributes Description
key string
callback function <optional>
Name Type Description
err Error
store Object

The new store

Returns:
Type:
Promise

Type Definitions

settingsCallback(erropt, resultopt)

Parameters:
Name Type Attributes Description
err Error <optional>

Show a custom error message to the user upon saving the settings

result string <optional>

A custom success message. Leave empty for the default message.