Pairing is started when the user selects the device they want to add from the Homey app. The pair property of the driver defines a list of views, which the user navigates through. These views are called pairing templates. Homey includes a set of system templates that implement consistent pairing steps for most devices.
Homey already knows how to pair Zigbee and Z-Wave devices so it is not possible to implement your own pairing for those devices. Read the Zigbee and Z-Wave documentations to learn how to pair devices using those technologies with Homey.
Basic pairing example
This example is a basic way to enable pairing in your driver. To add pairing to your driver, add the following to your driver.compose.json:
// we use a system template here, for consistency, and less work for us!
// show pair view with id 'add_my_devices' when clicked 'Next'
// again, use a template
This defines a pairing process with 2 steps. The first step requires the user to pick the devices to add from a list and the second step will automatically add these devices to Homey. Both these steps use Homey's built-in pairing templates list_devices and add_devices. The navigation option determines which of the steps the pairing will go to when the user presses the "Next" button.
The navigation object also supports a prev option for when a user can go back to the previous screen. This can be useful, for example, with a login_credentials system templates to allow users to retry logging-in.
If your pairing only uses the list_devices and add_devices templates you can use the Driver#onPairListDevices() method to quickly implement a pairing process. From this method you can return a list of devices that will be presented to the user.
const Homey =require("homey");
const DeviceApi =require("device-api");
const devices =await DeviceApi.discoverDevices();
module.exports = Driver;
Device pairing data
The following is an overview of the data you can supply for a device to be added, you should return an array of objects like this from Driver#onPairListDevices() or session.setHandler("list_devices").
// The name of the device that will be displayed
// 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)
// Optional: The store is dynamic and persistent storage for your device
// For example store the IP address of your device
// Optional: Initial device settings that can be changed by the user afterwards
// Optional: These overwrite properties overwrite those specified in the app manifest:
icon:"/my_icon.svg",// relative to: /drivers/<driver_id>/assets/
This view will show a list of selectable devices to the user. Devices that have already been paired with Homey will automatically be filtered out, based on their data property.
This view will automatically close the pair session.
Most drivers will suffice using the provided templates. In certain cases you may want, or need, to create pairing screens that are more suited to your driver. For these cases it is possible to create custom pairing views, to learn more read the custom pairing view guide.
To ensure users with a great experience, your app's devices should always stay available without user interaction.
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.
To enable repairing, you must add support for this to your driver by adding repair to your App Manifest: