Pairing

To connect a new physical device to Homey, your driver must support pairing. Pairing happens when the user adds a device to Homey, and clicks on your driver.

Pairing has a front-end (html, css and javascript in the browser), located at /drivers/<driver_id>/pair/, and a back-end (your /drivers/<driver_id>/driver.js)

Views

Most drivers will suffice using the system templates. These are documented at Drivers-Pairing-System-Views.

Some advanced drivers however can benefit from creating Drivers-Pairing-Custom-Views.

Example

This example is the most easy way to enable pairing in your driver. The pair wizard will look as follows:

To add pairing to your driver, add the following to your /app.json:

/app.json

{
    "id": "com.athom.hello",
    ...
    "drivers": [
        {
            "id": "my_driver"
            ...
            "pair": [
                {
                    "id": "list_devices",
                    "template": "list_devices", // we use a system template here, for consistency, and less work for us!
                    "navigation": {
                        "next": "add_my_devices" // show pair view with id `add_my_devices` when clicked `Next`
                    }
                },
                {
                    "id": "add_my_devices",
                    "template": "add_devices" // again, use a template
                }
            ]
        }
    ]
}

/drivers/<driver_id>/driver.js

class MyDriver extends Homey.Driver {

    // this is the easiest method to overwrite, when only the template 'Drivers-Pairing-System-Views' is being used.
    onPairListDevices( data, callback ) {

        let devices = [
            {
                // Required properties: 
                "name": "My Device",
                "data": { "id": "abcd" },

                // Optional properties, these overwrite those specified in app.json:
                // "icon": "/path/to/another/icon.svg",
                // "capabilities": [ "onoff", "dim" ],
                // "capabilitiesOptions: { "onoff": {} },
                // "mobile": {},

                // Optional properties, device-specific:
                // "store": { "foo": "bar" },
                // "settings": {},

            }
        ]

        callback( null, devices );

    }

}

The objects in the pair Array are called views. They will be shown in the pairing wizard in the same order as defined. It is possible to programmatically navigate between them by calling Homey.showView( String viewId ).


Child Topics