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;

Properties

driver

driver: Driver

The device's driver instance

Type

homey

homey: Homey

The Homey instance of this app

Type

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

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

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

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