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.

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;

Instance Properties

driver

driver: Driver

The device's driver instance

Type

homey

homey: Homey

The Homey instance of this app

Type

Instance Methods

addCapability

(async) addCapability(capabilityId)

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

Parameters

Name Type Description
capabilityId 		string

getAvailable

getAvailable(): boolean

Get the device's availability

Returns

If the device is marked as available

boolean

getCapabilities

getCapabilities(): Array.<string>

Get an array of capabilities

Returns

The device's capabilities array

Array.<string>

getCapabilityOptions

getCapabilityOptions(capabilityId): any

Get a device's capability options.

Parameters

Name Type Description
capabilityId 		string

Returns

any

getCapabilityValue

getCapabilityValue(capabilityId): any

Get a device's capability value

Parameters

Name Type Description
capabilityId 		string

Returns

The value, or null when unknown

any

getClass

getClass(): string

Get the device's class

Returns

The device's class

string

getData

getData(): any

Get the device's data object

Returns

The device's data object

any

getEnergy

getEnergy(): any

Get the device's energy object

Returns

The device's energy info object

any

getName

getName(): string

Get the device's name

Returns

The device's name

string

getSetting

getSetting(key): any

Get a device's setting value

Parameters

Name Type Description
key 		string

Returns

The value, or null when unknown

any

getSettings

getSettings(): any

Get the device's settings object

Returns

The device's settings object

any

getState

getState(): any

Get the device's state (capability values)

Returns

The device's state object

any

getStore

getStore(): any

Get the entire store

Returns

any

getStoreKeys

getStoreKeys(): Array.<string>

Get all store keys.

Returns

Array.<string>

getStoreValue

getStoreValue(key): any

Get a store value.

Parameters

Name Type Description
key 		string

Returns

value

any

hasCapability

hasCapability(capabilityId): boolean

Returns true if the device has a certain capability

Parameters

Name Type Description
capabilityId 		string

Returns

boolean

onAdded

onAdded()

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

onDeleted

onDeleted()

This method is called when the user deleted the device.

onDiscoveryAddressChanged

onDiscoveryAddressChanged(discoveryResult)

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

Parameters

Name Type Description
discoveryResult 		DiscoveryResult

onDiscoveryAvailable

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

onDiscoveryLastSeenChanged(discoveryResult)

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

Parameters

Name Type Description
discoveryResult 		DiscoveryResult

onDiscoveryResult

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

(async) onInit()

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

onRenamed

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

(async) onSettings(event): Promise.<(string|void)>

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

Parameters

Name Type Description
event 		object

the onSettings event data
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

return a custom message that will be displayed

Promise.<(string|void)>

onUninit

(async) onUninit()

This method is called when the device is destroyed.

ready

(async) ready(): Promise.<void>

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

Returns

Promise.<void>

registerCapabilityListener

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 		Device.CapabilityCallback

Example

this.registerCapabilityListener('dim', async (value, opts) => {
  this.log('value', value);
  this.log('opts', opts);
});

registerMultipleCapabilityListener

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 		Device.MultipleCapabilityCallback
timeout 		number default:250

The debounce timeout

Example

this.registerMultipleCapabilityListener(['dim', 'light_hue', 'light_saturation'], async (capabilityValues, capabilityOptions) => {
  this.log('capabilityValues', capabilityValues);
  this.log('capabilityOptions', capabilityOptions);
}, 500);

removeCapability

(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.

Parameters

Name Type Description
capabilityId 		string

setAlbumArtImage

(async) setAlbumArtImage(image): Promise.<any>

Set this device's album art

Parameters

Name Type Description
image 		Image

Returns

Promise.<any>

setAvailable

(async) setAvailable(): Promise.<any>

Set the device's availability to true

Returns

Promise.<any>

setCameraImage

(async) 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

Promise.<any>

setCapabilityOptions

(async) setCapabilityOptions(capabilityId, options)

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

Parameters

Name Type Description
capabilityId 		string
options 		object

setCapabilityValue

(async) setCapabilityValue(capabilityId, value): Promise.<void>

Set a device's capability value

Parameters

Name Type Description
capabilityId 		string
value 		any

Returns

Promise.<void>

setClass

(async) setClass(deviceClass): Promise.<void>

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

Parameters

Name Type Description
deviceClass 		string

Returns

Promise.<void>

setEnergy

(async) setEnergy(energy)

Set the device's energy object

Parameters

Name Type Description
energy 		object

setSettings

(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.

Parameters

Name Type Description
settings 		any

A settings object

Returns

Promise.<void>

setStoreValue

(async) setStoreValue(key, value): Promise.<void>

Set a store value.

Parameters

Name Type Description
key 		string
value 		any

Returns

Promise.<void>

setUnavailable

(async) setUnavailable(messageopt): Promise.<any>

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

Parameters

Name Type Description
message 		string | null <optional>

Custom unavailable message, or null for default

Returns

Promise.<any>

setWarning

(async) setWarning(messageopt): Promise.<any>

Set a warning message for this device, to be shown to the user. This message is persistent, so make sure to unset it when necessary.

Parameters

Name Type Description
message 		string | null <optional>

Custom warning message, or null to unset the warning

Returns

Promise.<any>

triggerCapabilityListener

(async) triggerCapabilityListener(capabilityId, value, opts): Promise.<any>

Trigger a capability listener programmatically.

Parameters

Name Type Description
capabilityId 		string
value 		any
opts 		object

Returns

Promise.<any>

unsetStoreValue

(async) unsetStoreValue(key): Promise.<void>

Unset a store value.

Parameters

Name Type Description
key 		string

Returns

Promise.<void>

unsetWarning

(async) unsetWarning(): Promise.<any>

Unset the warning message for this device

Returns

Promise.<any>

Type Definitions

CapabilityCallback

CapabilityCallback(value, opts): Promise.<void>|void

Parameters

Name Type Description
value 		any

The new value
opts 		any

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

Returns

Promise.<void> | void

MultipleCapabilityCallback

MultipleCapabilityCallback(capabilityValues, capabilityOptions): Promise.<void>|void

Parameters

Name Type Description
capabilityValues 		Object.<string, any>

An object with the changed capability values, e.g. { dim: 0.5 }
capabilityOptions 		Object.<string, any>

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

Returns

Promise.<void> | void