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)


A driver defines a list of views, which the user navigates through. A view can link to another view programmatically or by a navigation button.

System Views

Most drivers will suffice using the system templates.

Custom Views

A few types of devices might need to create a Custom pair view.


This example is the most easy way to enable pairing in your driver.

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


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


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 ) {

    const devices = [
        // Required properties:
        "data": { "id": "abcd" },

        // Optional properties, these overwrite those specified in app.json:
        // "name": "My Device",
        // "icon": "/my_icon.svg", // relative to: /drivers/<driver_id>/assets/
        // "capabilities": [ "onoff", "dim" ],
        // "capabilitiesOptions: { "onoff": {} },

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


    callback( null, devices );



Child Topics