Drivers

The most used reason to create a Homey App is to add support for devices of a certain type or brand to Homey.

One certain type of device, e.g. a Light bulb or Switch works under a separate Driver. A driver manages the addition and working of devices. There is only one Driver instance and as many Device instances as there are devices added by the user to Homey.

diagram

A driver must be defined in your App Manifest under drivers, and have code existing under /drivers/<your driver id>/driver.js.

To create a driver interactively, run:

$ athom app driver create

Example

/app.json

{
	"id": "com.athom.example",
	...
	"drivers": [
		{
			"id": "my_driver",
			"name": {
				"en": "My Driver"
			},
			"class": "socket",
			"capabilities": [ "onoff", "dim" ],
			"pair": [
				{
					"id": "list_devices",
					"template": "list_devices",
					"navigation": {
						"next": "add_devices"
					}
				},
				{
					"id": "add_devices",
					"template": "add_devices"
				}
			]
		}
	]
}

/drivers/my_driver/driver.js

const Homey = require('homey');

module.exports = class MyDriver extends Homey.Driver {

  // This method is called when a user is adding a device
  // and the 'list_devices' view is called
	onPairListDevices( data, callback ) {
		callback( null, [
			{
				name: 'Foo Device',
				data: {
					id: 'abcd1234'
				}
			}
		]);
	}

}

/drivers/my_driver/device.js

const Homey = require('homey');

module.exports = class MyDevice extends Homey.Device {

	// this method is called when the Device is inited
	onInit() {
		this.log('Device init');
		this.log('Name:', this.getName());
		this.log('Class:', this.getClass());

		// register a capability listener
		this.registerCapabilityListener('onoff', this.onCapabilityOnoff.bind(this));
	}

	// this method is called when the Device has requested a state change (turned on or off)
	async onCapabilityOnoff( value, opts ) {

		// ... set value to real device, e.g.
		// await setMyDeviceState({ on: value });

		// or, throw an error
		// throw new Error('Switching the device failed!');
	}

}

Properties

Device Class

"class": "light"

A device belongs to a class, e.g. socket, light, lock etc. When a specific device is unknown to Homey, use the class other.

Find your device's class in the Apps Reference.

Capabilities

"capabilities": [ "onoff", "dim" ]

A capability is a value of a device's state. For example, the capability onoff is of type boolean and can thus be either true or false. The capability dim is of type number and can be any number between 0 - 1, as defined in the capability's definition.

All capabilities together form the device's state. For example, when a user presses a button in the Homey app, the new capability's value is requested in the Device instance (see Device#registerCapabilityListener). The app should then update the device's state by making a Wi-Fi, Bluetooth, 433 Mhz etc. request to the physical device.

Homey ships with many system capabilities. For other cases, app-specific capabilities can be defined in the App Manifest.

Homey has built-in Flow cards and Speech commands for every system capability.

Energy

"energy": {...}

A device can use or generate power. To keep track of the data related to power usage and generation a device can have an energy object. This object contains power usage approximation data and flags to indicate a device generates power or should be omitted from automatic shutdown.

Settings

"settings": [ ... ]

A device can have user-configurable settings, such as the orientation of a curtain or a poll-interval. Settings are shown to the user in the front-end, or can be changed programmatically.

Pairing

"pair": [ ... ]

A device can only be added to Homey when the user starts a 'pair session' (see Driver#onPair). The driver can communicate with the front-end, and eventually add one or more devices.

For most devices a simple pair wizard is enough. For more advanced devices, where more user-steps are required, a frond-end view can be provided.

Availability

A device can be marked as unavailable using Device#setUnavailable to prevent the user from interacting with the device. This can for example be useful when a device is offline.

When a device is marked as unavailable, all capabilities and Flow actions will be prevented.

When a device is available again, use Device#setAvailable to mark the device as available.

The data object

During pairing, you must provide a data property. This object cannot be changed afterwards.

This must be an Object, String or Number and unique to the device. Homey uses this object to identify your device, together with the driver's ID.

Only put the essential properties needed to identify a device in the data object. For example, a MAC address is a good property, an IP address is not, because it can change over time.

All other properties that could change over time should be kept in-memory or saved in the device's store.

Store

The device's store is persistent storage to save device's properties and can be provided during pairing or programmatically afterwards.

See Device#getStore and Device#setStoreValue.

Deprecated

Sometimes a Driver that has been available in the past should be removed. To not break compatibility for users that were using it, add "deprecated": true to your driver in /app.json. It will still work, but won't show up anymore in the 'Add Device' list.