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

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.

• Devices List
• Add Devices
• OAuth2 Login
• Credentials Login
• Done

Custom Views

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

Example

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:

/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
        }
      ]
    }
  ]
}

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

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

  }

}

Repairing

To ensure users with a great experience, your app's devices should always stay available without user interaction.

Repairing is available since Homey v4.1.0

However, sometimes when a device explicitly needs user interaction to be fixed (for example an OAuth2 token has been revoked and the user needs to authenticate again), the user can initiate a repair process.

The repair process is very similar to the pair process, with the exception that the Homey.createDevice method is not available.

To enable repairing, you must add support for this to your driver by adding repair to your /app.json:

/app.json

{
  "id": "com.athom.example",
  ...
  "drivers": [
    {
      "id": "my_driver"
      ...
        "pair": [
          ...
        ], 
        "repair": [
          {
            "id": "fix_my_device"
          }
        ]
      ]
    }
  ]
}

/drivers/<driver_id>/driver.js

class MyDriver extends Homey.Driver {

  onRepair( socket, device ) {
    // Argument socket is an EventEmitter, similar to Driver.onPair
    // Argument device is a Homey.Device that's being repaired

    socket.on('my_event', ( data, callback ) => {
      // Your code
      callback();
    });

    socket.on('disconnect', () => {
      // Cleanup
    })

  }

}

See Custom Views to learn more about creating your own custom views.

Child Topics

• System Views
• Custom Views