Homey makes use of drivers to connect to remote devices. Apps can provide these drivers to Homey to add support for more devices.

Basic concepts

A device in Homey has a few basic properties.


A device belongs to a class, e.g. socket, light, lock etc. Homey has many built-in Flow cards, Speech commands and Devices-Mobile Cards for every class. When a specific device is unknown to Homey, use the class other.

Read more about Classes »


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

All capabilities together form the device's state. When the user pressed a button in for example the Homey Smartphone App, the new capability's value is requested in the Device instance. From there, the app can make sure the physical device actually changes its state.

Homey ships with many capabilities, but app-specific capabilities can be defined in the /app.json.

Read more about Capabilities »


A device has a mobile card, which is inherited from its Class. A mobile card is a group of components, which all can change or display one or more capabilities. For example, a component slider can change a capability dim.

Read more about Mobile »


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.

Read more about Settings »


A device can only be added to Homey when the user starts a pair session. The driver can communicate back and forth 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.

Read more about Pairing »


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 cards will return an error.

Creating your first driver

A driver must be defined in /app.json, and the according files must be placed in /drivers/<driver_id>/.

An example of a simple driver could be:


    "id": "com.athom.hello",
    "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"

Now that a driver with ID my_driver has been defined, a directory /drivers/my_driver/ must be created. In this folder, two files may be placed, and at least one: driver.js and device.js.

The file driver.js is best seen as a 'manager' for devices, and provides functionality for adding new devices (pairing). The file device.js is a representation of an already paired device on Homey. Both files will automatically use their standard classes, respectively Driver and Device. The files driver.js and device.js should export a class that extends these classes.

The following examples are simple driver.js and device.js implementations.


'use strict';

const Homey = require('homey');

class MyDriver extends Homey.Driver {

    onPairListDevices( data, callback ){

        callback( null, [
                name: 'Foo Device',
                data: {
                    id: 'foo'



module.exports = MyDriver;


'use strict';

const Homey = require('homey');

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 is added
    onAdded() {
        this.log('device added');

    // this method is called when the Device is deleted
    onDeleted() {
        this.log('device deleted');

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

        // ... set value to real device

        // Then, emit a callback ( err, result )
        callback( null );

        // or, return a Promise
        return Promise.reject( new Error('Switching the device failed!') );


module.exports = MyDevice;

Child Topics