Device - Homey Apps SDK v3

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

Driver

homey

homey: Homey

The Homey instance of this app

Type

Homey

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)

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>

setCameraVideo

(async) setCameraVideo(id, title, video): Promise.<any>

Set a device's camera stream

Parameters

Name	Type	Description
`id`	string	Unique ID of the video (e.g. `front_door`)
`title`	string	Title of the video (e.g. `Front Door`)
`video`	Video	The video instance

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

setLastSeenAt

(async) setLastSeenAt()

Set a device's lastSeenAt property. This method should be called if the device is known to be alive and responding. Note: available since Homey v12.6.1.

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