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.

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.
  async onPairListDevices() {
    const devices = [
      {
        // The name of the device that will be displayed
        name: 'My Device',

        // The data object is required and should contain only unique properties for the device.
        // So a MAC address is good, but an IP address is bad (can change over time)
        data: {
          id: 'abcd',
        },

        // Optional: The store is dynamic and persistent storage for your device
        store: {
          // For example store the IP address of your device
          address: '127.0.0.1',
        },

        // Optional: Initial device settings that can be changed by the user afterwards
        settings: {
          pincode: '1234',
        },

        // Optional: These overwrite properties overwrite those specified in app.json:
        icon: '/my_icon.svg', // relative to: /drivers/<driver_id>/assets/
        capabilities: ['onoff', 'dim'],
        capabilitiesOptions: {
          onoff: {},
        },
      },
    ];

    return 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(session, device) {
    // Argument session is a PairSocket, similar to Driver.onPair
    // Argument device is a Homey.Device that's being repaired

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

    session.setHandler('disconnect', () => {
      // Cleanup
    })
  }
}

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


Child Topics