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

Library:
Example

/drivers/my_driver/device.js

const Homey = require('homey');

class MyDevice extends Homey.Device {
  async onInit() {
    this.log('MyDevice has been initialized');
  }
}

module.exports = MyDevice;

Properties

driver :Driver

The device's driver instance

Type:

homey :Homey

The Homey instance of this app

Type:

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 string

getAvailable() → {boolean}

Get the device's availability

Returns:
Type:
boolean

If the device is marked as available

getCapabilities() → {Array.<string>}

Get an array of capabilities

Returns:
Type:
Array.<string>

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) → {any}

Get a device's capability value

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

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

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) → {any}

Get a device's setting value

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

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) → {any}

Get a store value.

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

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

(async) 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(event) → {Promise.<(string|void)>}

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

Library:
Parameters:
Name Type Description
event object

the onSettings event data

Name Type Description
oldSettings object

The old settings object

newSettings object

The new settings object

changedKeys Array.<string>

An array of keys changed since the previous version

Returns:
Type:
Promise.<(string|void)>

return a custom message that will be displayed

ready() → {Promise.<void>}

Returns a Promise which is resolved when the Device is ready (Device#onInit has been run).

Returns:
Type:
Promise.<void>

registerCapabilityListener(capabilityId, listener)

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
listener function
Name Type Description
value any

The new value

opts object

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

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

registerMultipleCapabilityListener(capabilityIds, listener, 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>
listener function
Name Type Description
capabilityValues any

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

capabilityOptions object

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

timeout number

The debounce timeout

Example
this.registerMultipleCapabilityListener([ 'dim', 'light_hue', 'light_saturation' ], ( capabilityValues, capabilityOptions ) => {
  this.log('capabilityValues', capabilityValues);
  this.log('capabilityOptions', capabilityOptions);
  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 string

setAlbumArtImage(image) → {Promise.<any>}

Set this device's album art

Parameters:
Name Type Description
image Image
Returns:
Type:
Promise.<any>

setAvailable() → {Promise.<any>}

Set the device's availability to true

Returns:
Type:
Promise.<any>

setCameraImage(id, title, image) → {Promise.<any>}

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
Returns:
Type:
Promise.<any>

(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

(async) setCapabilityValue(capabilityId, value) → {Promise.<void>}

Set a device's capability value

Parameters:
Name Type Description
capabilityId string
value any
Returns:
Type:
Promise.<void>

(async) setClass(deviceClass) → {Promise.<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:
Promise.<void>

(async) setEnergy(energy)

Set the device's energy object

Since:
  • 3.0.0
Parameters:
Name Type Description
energy object

(async) setSettings(settings) → {Promise.<void>}

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 Description
settings object

A settings object

Returns:
Type:
Promise.<void>

(async) setStoreValue(key, value) → {Promise.<Object>}

Set a store value.

Parameters:
Name Type Description
key string
value any
Returns:
Type:
Promise.<Object>
  • The new store

setUnavailable(messageopt) → {Promise.<any>}

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

Parameters:
Name Type Attributes Description
message string | null <optional>

Custom unavailable message, or null for default

Returns:
Type:
Promise.<any>

setWarning(messageopt) → {Promise.<any>}

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

Parameters:
Name Type Attributes Description
message string | null <optional>

Custom warning message, or null to unset the warning

Returns:
Type:
Promise.<any>

(async) triggerCapabilityListener(capabilityId, value, opts) → {Promise.<any>}

Trigger a capability listener programmatically.

Parameters:
Name Type Description
capabilityId string
value any
opts object
Returns:
Type:
Promise.<any>

(async) unsetStoreValue(key) → {Promise.<Object>}

Unset a store value.

Parameters:
Name Type Description
key string
Returns:
Type:
Promise.<Object>
  • The new store

unsetWarning() → {Promise.<any>}

Unset the warning message for this device

Returns:
Type:
Promise.<any>