async/await
everywhere you want/need to. We hope supporting asynchronous calls everywhere will make it easier to develop and maintain Homey apps.sdk
property in your App Manifest from 2
to 3
. Since SDK v3 is introduced in Homey 5.0.0 the Homey compatibility
field in your App Manifest should be changed to >=5.0.0
.homey-oauth2app
, homey-rfdriver
, homey-meshdriver
and homey-log
) are not compatible with SDK v3. Make sure to upgrade these libraries to versions that do support SDK v3. When using homey-meshdriver
for Zigbee or Z-Wave, please look at the specific sections for Z-Wave and Zigbee.require('homey')
to this.homey
const Homey = require('homey')
. This is a very convenient way to give access to the managers anywhere it is needed however this prevents us from optimizing apps in the future as it pollutes the "global namespace". Therefore, the homey module now only exports the classes you might need such as Homey.App
, Homey.Driver
and Homey.Device
. The module also contains your environment variables through Homey.env
, and app manifest through Homey.manifest
. All managers (the API you use to interact with Homey) have moved to this.homey
, a property that is set on your App, Driver and Device instances. You can find the name of your manager in the Homey
instance documentation.api.js
. Additionally since you can no longer gain access to the API through require-ing homey it is now passed as an argument to your API handler method. Read more about the Homey App Web API in the Web API guide. Here is an example of the new structure for Homey App Web API's:Driver.getManifest()
and Device.getDriver()
in favour of using properties: Driver#manifest
and Device#driver
.Device#onSettings()
has been changed to support destructuring: onSettings({ oldSettings, newSettings, changedKeys })
.Driver#onPair()
has been changed. Previously this argument was an EventEmitter
with an .on
method that would receive a callback as its last argument. In order to offer better support for promises this was changed to a PairSession
that has a .setHandler
method where it is possible to return a Promise.onPair
method like this:Driver#onPairListDevices()
. If you're app is overriding this method you can upgrade by removing the callback, making it async and returning the device list.onPairListDevices
method like this:App#onInit()
method would be executed after all managers where ready. Unfortunately this also meant that your Driver and Device onInit
methods where executed before your App#onInit()
. This ordering was somewhat confusing so we changed the order in which we call the onInit
methods in SDK v3.app.js
and two drivers (driver-one
and driver-two
both have a single device) the order of onInit
calls is now:App#onInit()
you cannot access Drivers (this.homey.drivers.getDriver()
will throw an error). Instead of accessing Drivers from your App you can use App#onInit()
to set up any data or classes that you might need in your application, then when your Driver or Device's onInit
methods are called you are able to access this data directly through this.homey.app
.alarm_contact
and alarm_motion
activated a zone when an alarm is triggered. As of Homey v5.0.0 it is possible to disable this behaviour by using the capability option zoneActivity
. This option accepts a boolean and defaults to true
. This makes it possible to disable zone activity for these capabilities.zwave.associationGroups
driver property has changed in Homey v5.0.0 to be more predictable:associationGroups: []
will now remove the default association group 1 (Z-Wave Plus lifeline)associationGroups
will now set the default association group 1 (Z-Wave Plus lifeline)associationGroups
or that set associationGroups
to an empty array still behave correctly on Homey v5.0.0.process.env.TZ
) will always be set to UTC
. In SDK v2, the timezone of an app would match the timezone the user set in their settings. This behaviour was confusing and could cause correct apps to have bugs when a user changes their timezone. To have more consistent and predictable behaviour all dates in SDK v3 apps will now default to UTC
.new Date('3/14/20')
Date.parse('3/14/20')
myDate.getHours()
myDate.setHours(12)
this.homey.clock.getTimezone()
, the timezone can then be used to format a date to the users timezone.this.homey.setTimeout
, this.homey.clearTimeout
, this.homey.setInterval
and this.homey.clearInterval
instead. These are the same as the native variants, but will take care of clearing the timeouts/intervals themselves when the app gets removed. Alternatively you could use this.homey.on('unload', () => clearInterval(myInterval))
.Image.format
, Image.getFormat()
, Image.getBuffer()
and Image.setBuffer()
APIs have been removed. More information can be found in the Image Api guide.