Homey Apps SDK
📖 Apps SDK Reference🌍 Web API🛠 Developer Tools
Search…
Welcome to the Apps SDK documentation 👋
The Basics
Getting Started
App
Drivers & Devices
Pairing
Capabilities
Energy
Settings
Best practices
Flow
Wireless
Wi-Fi
Bluetooth LE
Z-Wave
Zigbee
433 MHz
Infrared
Cloud
OAuth2
Webhooks
App Store
Publishing
Guidelines
Updating
Advanced
Custom Views
Web API
Images
LED Ring
Homey Compose
Homey CLI
Guides
Homey Cloud
Breaking changes
Tools
Upgrade Guides
Homey v6.0.0
Upgrading to SDK v3
Powered By GitBook
Pairing
Pairing allows users to add new devices to Homey.
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:
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"class": "socket",
8
"capabilities": ["onoff"],
9
"platforms": ["local", "cloud"],
10
"connectivity": "cloud",
11
"pair": [
12
{
13
"id": "list_my_devices",
14
// we use a system template here, for consistency, and less work for us!
15
"template": "list_devices",
16
// show pair view with id 'add_my_devices' when clicked 'Next'
17
"navigation": { "next": "add_my_devices" }
18
},
19
{
20
"id": "add_my_devices",
21
// again, use a template
22
"template": "add_devices"
23
}
24
]
25
}
Copied!
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.
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
const DeviceApi = require("device-api");
3
​
4
class Driver extends Homey.Driver {
5
async onPairListDevices() {
6
const devices = await DeviceApi.discoverDevices();
7
return devices;
8
}
9
}
10
​
11
module.exports = Driver;
Copied!

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").
1
{
2
// The name of the device that will be displayed
3
name: "My Device",
4
​
5
// The data object is required and should contain only unique properties for the device.
6
// So a MAC address is good, but an IP address is bad (can change over time)
7
data: {
8
id: "abcd",
9
},
10
​
11
// Optional: The store is dynamic and persistent storage for your device
12
store: {
13
// For example store the IP address of your device
14
address: "127.0.0.1",
15
},
16
​
17
// Optional: Initial device settings that can be changed by the user afterwards
18
settings: {
19
pincode: "1234",
20
},
21
​
22
// Optional: These overwrite properties overwrite those specified in the app manifest:
23
icon: "/my_icon.svg", // relative to: /drivers/<driver_id>/assets/
24
capabilities: ["onoff", "target_temperature"],
25
capabilitiesOptions: {
26
target_temperature: {
27
min: 5,
28
max: 35,
29
},
30
},
31
}
Copied!

System templates

The pairing templates are built with HTML, CSS and JavaScript. Most drivers will suffice using the system templates that are provided by Homey.

Devices List

"template": "list_devices"
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.
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"pair": [
8
{
9
"id": "list_devices",
10
"template": "list_devices",
11
"navigation": { "next": "add_devices" },
12
"options": { "singular": true }
13
},
14
{
15
"id": "add_devices",
16
"template": "add_devices"
17
}
18
]
19
}
Copied!
Options
Key
Type
Default
Description
singular
boolean
false
Only allow a single device to be selected
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
const DeviceApi = require("device-api");
3
​
4
class Driver extends Homey.Driver {
5
async onPair(session) {
6
session.setHandler("list_devices", async function () {
7
const devices = await DeviceApi.discoverDevices();
8
9
// you can emit when devices are still being searched
10
// session.emit("list_devices", devices);
11
​
12
// return devices when searching is done
13
return devices;
14
​
15
// when no devices are found, return an empty array
16
// return [];
17
​
18
// or throw an Error to show that instead
19
// throw new Error('Something bad has occured!');
20
});
21
}
22
}
23
​
24
module.exports = Driver;
Copied!
Because the list_devices template is very common the Driver#onPairListDevices() method exists which you can implement instead of the Driver#onPair() method.

Add Devices

"template": "add_devices"
This view will simply add the devices as selected by list_devices, and finish the pairing session.

OAuth2 Login

"template": "login_oauth2"
This view can be used for devices that need OAuth2 authorization. When it's successful, it will automatically proceed to the next view.
The example below is for completeness only. Pleaser read OAuth2 to learn how to integrate with OAuth2 APIs the easy way.
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"pair": [
8
{
9
"id": "login_oauth2",
10
"template": "login_oauth2",
11
"options": {
12
"hint": "Login with your credentials",
13
"button": "Log-in"
14
}
15
},
16
{
17
"id": "list_devices",
18
"template": "list_devices",
19
"navigation": { "next": "add_devices" }
20
},
21
{
22
"id": "add_devices",
23
"template": "add_devices"
24
}
25
]
26
}
Copied!
Options
Key
Type
Default
Description
hint
""
​
button
""
​
When either hint or button are set to a value, a button will appear and wait for the user to click it before opening the popup.
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
​
3
const API_URL = "https://api.myservice.com/oauth2/authorise?response_type=code";
4
const CALLBACK_URL = "https://callback.athom.com/oauth2/callback/";
5
const CLIENT_ID = Homey.env.CLIENT_ID;
6
const OAUTH_URL = `${API_URL}&client_id=${CLIENT_ID}&redirect_uri=${CALLBACK_URL}`;
7
​
8
class Driver extends Homey.Driver {
9
async onPair(session) {
10
const myOAuth2Callback = await this.homey.cloud.createOAuth2Callback(OAUTH_URL);
11
​
12
myOAuth2Callback
13
.on("url", (url) => {
14
// dend the URL to the front-end to open a popup
15
session.emit("url", url);
16
})
17
.on("code", (code) => {
18
// ... swap your code here for an access token
19
​
20
// tell the front-end we're done
21
session.emit("authorized");
22
});
23
}
24
}
25
​
26
module.exports = Driver;
Copied!

Credentials Login

"template": "login_credentials"
This pair template shows a username & password view where the user can enter credentials.
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"pair": [
8
{
9
"id": "login_credentials",
10
"template": "login_credentials",
11
"options": {
12
"logo": "logo.png",
13
"usernameLabel": { "en": "E-mail address" },
14
"usernamePlaceholder": { "en": "[email protected]" },
15
"passwordLabel": { "en": "Password" },
16
"passwordPlaceholder": { "en": "Password" }
17
}
18
},
19
{
20
"id": "list_devices",
21
"template": "list_devices",
22
"navigation": { "next": "add_devices" }
23
},
24
{
25
"id": "add_devices",
26
"template": "add_devices"
27
}
28
]
29
}
Copied!
Options
Key
Type
Default
Description
logo
string
null
A path to an image for a logo
usernameLabel
"E-mail address"
​
usernamePlaceholder
​
passwordLabel
"Password"
​
passwordPlaceholder
"Password"
​
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
const DeviceAPI = require("device-api");
3
​
4
class Driver extends Homey.Driver {
5
async onPair(session) {
6
let username = "";
7
let password = "";
8
​
9
session.setHandler("login", async (data) => {
10
username = data.username;
11
password = data.password;
12
​
13
const credentialsAreValid = await DeviceAPI.testCredentials({
14
username,
15
password,
16
});
17
​
18
// return true to continue adding the device if the login succeeded
19
// return false to indicate to the user the login attempt failed
20
// thrown errors will also be shown to the user
21
return credentialsAreValid;
22
});
23
​
24
session.setHandler("list_devices", async () => {
25
const api = await DeviceAPI.login({ username, password });
26
const myDevices = await api.getDevices();
27
​
28
const devices = myDevices.map((myDevice) => {
29
return {
30
name: myDevice.name,
31
data: {
32
id: myDevice.id,
33
},
34
settings: {
35
// Store username & password in settings
36
// so the user can change them later
37
username,
38
password,
39
},
40
};
41
});
42
​
43
return devices;
44
});
45
}
46
}
47
​
48
module.exports = Driver;
Copied!

Pincode

"template": "pincode"
This pair template shows a pincode input. When the pincode is correct, it will proceed to the next view.
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"pair": [
8
{
9
"id": "list_devices",
10
"template": "list_devices",
11
"navigation": { "next": "pincode" }
12
},
13
{
14
"id": "pincode",
15
"template": "pincode",
16
"options": {
17
"title": "Enter pincode:",
18
"hint": "Enter the device's pincode",
19
"type": "number",
20
"length": 4
21
}
22
},
23
{
24
"id": "add_devices",
25
"template": "add_devices"
26
}
27
]
28
}
Copied!
Options
Key
Type
Default
Description
type
string
"number"
Either number or text. This changes how the keyboard is presented on mobile phones when the pincode field is selected.
length
number
4
The number of characters
hint
""
​
title
"Enter pincode:"
​
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
​
3
class Driver extends Homey.Driver {
4
onPair(session) {
5
session.setHandler("pincode", async (pincode) => {
6
// The pincode is given as an array of the filled in values
7
return (
8
pincode[0] === "1"
9
&& pincode[1] === "2"
10
&& pincode[2] === "3"
11
&& pincode[3] === "4"
12
);
13
});
14
}
15
}
16
​
17
module.exports = Driver;
Copied!

Loading

"template": "loading"
This view will show a loading indicator. It's usually useful to show this view when an asynchronous operation needs to be made.
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"pair": [
8
{
9
"id": "list_devices",
10
"template": "list_devices",
11
"navigation": { "next": "loading" }
12
},
13
{
14
"id": "loading",
15
"template": "loading"
16
},
17
{
18
"id": "add_devices",
19
"template": "add_devices"
20
}
21
]
22
}
Copied!
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
const DeviceAPI = require("device-api");
3
​
4
class Driver extends Homey.Driver {
5
onPair(session) {
6
session.setHandler("list_devices", async () => {
7
return [
8
{
9
name: "My Device",
10
data: {
11
id: "abcd",
12
},
13
},
14
];
15
});
16
​
17
session.setHandler('showView', async (view) => {
18
if (view === 'loading') {
19
await DeviceAPI.connect();
20
await session.nextView();
21
}
22
});
23
}
24
}
25
​
26
module.exports = Driver;
Copied!

Done

"template": "done"
This view will automatically close the pair session.

Custom Views

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.

Repairing

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:
/drivers/<driver_id>/driver.compose.json
1
{
2
"name": { "en": "My Driver" },
3
"images": {
4
"small": "/drivers/my_driver/assets/images/small.png",
5
"large": "/drivers/my_driver/assets/images/large.png"
6
},
7
"repair": [
8
{
9
"id": "login_oauth2",
10
"template": "login_oauth2"
11
}
12
]
13
}
Copied!
It is also possible to use custom pairing views for repairing. To learn more about custom pairing templates read the custom pairing view guide.
Note that when repairing the Homey.createDevice() method is not available in the custom view and you can add a onRepair method to your driver, which is similar to the onPair method.
/drivers/<driver_id>/driver.js
1
const Homey = require("homey");
2
​
3
class Driver extends Homey.Driver {
4
onRepair(session, device) {
5
// Argument session is a PairSocket, similar to Driver.onPair
6
// Argument device is a Homey.Device that's being repaired
7
​
8
session.setHandler("my_event", (data) => {
9
// Your code
10
});
11
​
12
session.setHandler("disconnect", () => {
13
// Cleanup
14
});
15
}
16
}
17
​
18
module.exports = Driver;
Copied!
The Basics - Previous
Drivers & Devices
Next
Capabilities
Last modified 3d ago
Copy link
Contents
Basic pairing example
Device pairing data
System templates
Devices List
Add Devices
OAuth2 Login
Credentials Login
Pincode
Loading
Done
Custom Views
Repairing