You are currently viewing the Homey Apps SDK v2 documentation. New apps should use Homey Apps SDK v3 ››

Homey.Device 

const { Device } = require('homey');

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

Library:

Methods

(async) addCapability(capabilityId)

Add a capability to this device. Note: this is an expensive method so use it only when needed.

Since:
  • 3.0.0
Parameters:
Name Type Description
capabilityId

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

getCapabilityOptions(capabilityId) → {Object}

Get a device's capability options.

Since:
  • 3.0.0
Parameters:
Name Type Description
capabilityId string
Returns:
Type:
Object

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

getEnergy() → {object}

Get the device's energy object

Since:
  • 3.0.0
Returns:
Type:
object

The device's energy info object

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

Library:
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.

onDiscoveryAddressChanged(discoveryResult)

This method is called when the device's address has changed.

Parameters:
Name Type Description
discoveryResult DiscoveryResult

onDiscoveryAvailable(discoveryResult)

This method is called when the device is found for the first time. Overload this method to create a connection to the device. Throwing here will make the device unavailable with the error message.

Parameters:
Name Type Description
discoveryResult DiscoveryResult

onDiscoveryLastSeenChanged(discoveryResult)

This method is called when the device has been found again.

Parameters:
Name Type Description
discoveryResult DiscoveryResult

onDiscoveryResult(discoveryResult)

This method is called when a device has been discovered. Overload this method, and return a truthy value when the result belongs to the current device or falsy when it doesn't. By default, the method will match on a device's data.id property.

Parameters:
Name Type Description
discoveryResult DiscoveryResult

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.

Library:
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);

(async) removeCapability(capabilityId)

Removes a capability from this device. Any Flow that depends on this capability will become broken. Note: this is an expensive method so use it only when needed.

Since:
  • 3.0.0
Parameters:
Name Type Description
capabilityId

setAlbumArtImage(image, callback) → {Promise}

Set this device's album art

Parameters:
Name Type Description
image Image
callback
Name Type Description
err Error
Returns:
Type:
Promise

setAvailable(callbackopt) → {Promise}

Set the device's availability to true

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

setCameraImage(id, title, image, callback) → {Promise}

Set a device's camera image

Parameters:
Name Type Description
id string

Unique ID of the image (e.g. front)
title string

Title of the image (e.g. Front)
image Image
callback
Name Type Description
err Error
Returns:
Type:
Promise

(async) setCapabilityOptions(capabilityId, options)

Set a device's capability options. Note: this is an expensive method so use it only when needed.

Since:
  • 3.0.0
Parameters:
Name Type Description
capabilityId string
options Object

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

(async) setClass(deviceClass) → {void}

Set the device's class Any Flow that depends on this class will become broken.

Since:
  • 3.0.0
Parameters:
Name Type Description
deviceClass string
Returns:
Type:
void

(async) setEnergy(energy)

Set the device's energy object

Since:
  • 3.0.0
Parameters:
Name Type Description
energy Object

setSettings(settings, 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.

Library:
Parameters:
Name Type Attributes Description
settings 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

setWarning(message, callbackopt) → {Promise}

Set a warning message for this device, to be shown to the user

Parameters:
Name Type Attributes Description
message string

Custom warning message, or null to unset the warning
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

unsetWarning(callbackopt) → {Promise}

Unset the warning message for this device

Parameters:
Name Type Attributes Description
callback genericCallbackFunction <optional>
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.