Custom pairing views

The pairing views consists of .html files in the /drivers/<driver_id>/pair-folder. Where the name of the file is the view ID, as id described in the App Manifest.
The pairing views have a few Homey-specific JavaScript functions available. They are documented below.
Back-end API
The session property passed in onPair can control the front-end programmatically.
/drivers/<driver_id>/driver.js
1
const Homey = require('homey');
2
​
3
class Driver extends Homey.Driver {
4
  async onPair(session) {
5
    // Show a specific view by ID
6
    await session.showView("my_view");
7
​
8
    // Show the next view
9
    await session.nextView();
10
​
11
    // Show the previous view
12
    await session.prevView();
13
​
14
    // Close the pair session
15
    await session.done();
16
​
17
    // Received when a view has changed
18
    session.setHandler("showView", async function (viewId) {
19
      console.log("View: " + viewId);
20
    });
21
  }
22
}
23
​
24
module.exports = Driver;
Copied!
Front-end API
The following methods are available at the front-end to communicate with the back-end. The Homey object is globally available.
Emit an event
Homey.emit( String event, Mixed data ): Promise<any>
Emit an event to your app. The function called will be the one registered by session.setHandler( String event, Function callback ) in driver.js.
/drivers/<driver_id>/driver.compose.json
1
{
2
  "name": { "en": "My Driver" },
3
  "class": "socket",
4
  "capabilities": ["onoff", "dim"],
5
  "images": {
6
    "small": "/drivers/my_driver/assets/images/small.png",
7
    "large": "/drivers/my_driver/assets/images/large.png",
8
    "xlarge": "/drivers/my_driver/assets/images/xlarge.png"
9
  },
10
  "pair": [
11
    {
12
      "id": "my_view"
13
    }
14
  ]
15
}
Copied!
/drivers/<driver_id>/pair/my_view.html
1
<script type="application/javascript">
2
  Homey.emit("my_event", { foo: "bar" }).then(function (result) {
3
    console.log(result); // result is: Hello!
4
  });
5
</script>
Copied!
/drivers/<driver_id>/driver.js
1
const Homey = require('homey');
2
​
3
class Driver extends Homey.Driver {
4
  async onPair(session) {
5
    session.setHandler("my_event", async function (data) {
6
      // data is { 'foo': 'bar' }
7
      return "Hello!";
8
    });
9
  }
10
}
11
​
12
module.exports = Driver;
Copied!
Receive an event
Homey.on( String event, Function callback )
Listen to a message from your app. You can trigger this function from your app by calling session.emit().
/drivers/<driver_id>/pair/start.html
1
<script type="application/javascript">
2
  Homey.on("hello", function (message) {
3
    Homey.alert(message); // Hello to you!
4
    return "Hi!"; // send a reply back to the pairing session
5
​
6
    // you can return a promise if you need to do some async
7
    // work before replying to the message.
8
  });
9
</script>
Copied!
/drivers/<driver_id>/driver.js
1
const Homey = require('homey');
2
​
3
class Driver extends Homey.Driver {
4
  async onPair(session) {
5
    session.setHandler("showView", async (viewId) => {
6
      if (viewId === "start") {
7
        const data = await session.emit("hello", "Hello to you!");
8
        console.log(data); // Hi!
9
      }
10
    });
11
  }
12
}
13
​
14
module.exports = Driver;
Copied!
Set a Title
Homey.setTitle( String title )
Set the window's title.
Example
/drivers/<driver_id>/pair/start.html
1
<script type="application/javascript">
2
  Homey.setTitle(Homey.__("pair.title_searching"));
3
</script>
Copied!
Show a View
Homey.showView( String viewId )
Navigate to another view. The parameter viewId should be an ID as specified in your App Manifest.
/drivers/<driver_id>/pair/start.html
1
<script type="application/javascript">
2
  Homey.showView("list_devices");
3
</script>
Copied!
Previous View
Homey.prevView()
Show the previous view.
Next View
Homey.nextView()
Show the next view.
Get the current view
Homey.getCurrentView()
Returns the current view ID.
Create a device
Homey.createDevice( Object device ): Promise<Object>
Create a device with the properties in device.
The device object must at least contain the property data and may contain name, icon, class, capabilities, capabilitiesOptions, store and settings.
Example:
/drivers/<driver_id>/pair/start.html
1
<script type="application/javascript">
2
  Homey.createDevice({
3
    // The name of the device that will be shown to the user
4
    name: "My Device",
5
​
6
    // The data object is required and should contain only unique properties for the device.
7
    // So a MAC address is good, but an IP address is bad (can change over time)
8
    data: {
9
      id: "abcd",
10
    },
11
​
12
    // Optional: The store is dynamic and persistent storage for your device
13
    store: {
14
      // For example store the IP address of your device
15
      address: "127.0.0.1",
16
    },
17
​
18
    // Optional: Initial device settings that can be changed by the user afterwards
19
    settings: {
20
      pincode: "1234",
21
    },
22
  })
23
    .then(function (result) {
24
      Homey.done();
25
    })
26
    .catch(function (error) {
27
      Homey.alert(err);
28
    });
29
</script>
Copied!
Get current zone
Homey.getZone(): Promise<string>
Get the Zone ID of the active Zone. The promise resolves to the zone id.
Get view options
Homey.getOptions( [String viewId] ): Promise<Object>
Get the options of a view, or the current view when viewId is omitted. The promise resolves to the viewOptions of the specified view.
View options may be added to a view by specifying an options object in the App Manifest.
Set navigation close
Homey.setNavigationClose()
Remove all navigation buttons and show a single Close button.
Close the pair session
Homey.done()
Close the pairing window.
Alert dialog
Homey.alert( String message[, String icon] ): Promise<void> Show an alert dialog. The second parameter icon can be null, error, warning or info.
Confirm dialog
Homey.confirm( String message[, String icon] ): Promise<boolean> Show a confirm dialog. The second parameter icon can be null, error, warning or info.
The promise will resolve to true when the user pressed OK.
Popup
Homey.popup( String url ) Show a popup with a remote website.
Internationalisation
Homey.__( String key [, Object tokens] )
Translate a string programmatically. The first argument key is the name in your /locales/__language__.json. Use dots to get a sub-property, e.g. settings.title. The optional second argument tokens is an object with replacers.
/drivers/<driver_id>/pair/start.html
1
<script type="application/javascript">
2
  function onHomeyReady(Homey) {
3
    alert(Homey.__("pair.title")); // will alert "Settings page title"
4
  }
5
</script>
Copied!
Within your custom views, you can also use translations. For example:
/drivers/<driver_id>/pair/start.html
1
<span data-i18n="pair.title"></span>
2
<p data-i18n="pair.intro"></p>
Copied!
Read more about translations in the internationalization guide.
Show the loading overlay
Homey.showLoadingOverlay()
Shows the loading overlay.
Hide the loading overlay
Homey.hideLoadingOverlay()
Hides the loading overlay.
Get a view's store value
Homey.getViewStoreValue( String viewId, String key ): Promise<any>
Get's a view's store value. Promise will resolve to the requested value.
Set a view's store value
Homey.setViewStoreValue( String viewId, String key, Mixes value): Promise<void>
Set a view's store value.
Example
/drivers/<driver_id>/pair/start.html
1
<script type="application/javascript">
2
  var devicesArray = [
3
    {
4
      name: "My Device",
5
      data: {
6
        id: "abcd",
7
      },
8
    },
9
  ];
10
  Homey.setViewStoreValue("add_devices", "devices", devicesArray);
11
</script>
Copied!
App Settings
Next - Advanced
Web API
Last modified 5mo ago