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
const Homey = require('homey');
​
class Driver extends Homey.Driver {
  async onPair(session) {
    // Show a specific view by ID
    await session.showView("my_view");
​
    // Show the next view
    await session.nextView();
​
    // Show the previous view
    await session.prevView();
​
    // Close the pair session
    await session.done();
​
    // Received when a view has changed
    session.setHandler("showView", async function (viewId) {
      console.log("View: " + viewId);
    });
  }
}
​
module.exports = Driver;
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
{
  "name": { "en": "My Driver" },
  "class": "socket",
  "capabilities": ["onoff", "dim"],
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png",
    "xlarge": "/drivers/my_driver/assets/images/xlarge.png"
  },
  "pair": [
    {
      "id": "my_view"
    }
  ]
}
/drivers/<driver_id>/pair/my_view.html
<script type="application/javascript">
  Homey.emit("my_event", { foo: "bar" }).then(function (result) {
    console.log(result); // result is: Hello!
  });
</script>
/drivers/<driver_id>/driver.js
const Homey = require('homey');
​
class Driver extends Homey.Driver {
  async onPair(session) {
    session.setHandler("my_event", async function (data) {
      // data is { 'foo': 'bar' }
      return "Hello!";
    });
  }
}
​
module.exports = Driver;
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
<script type="application/javascript">
  Homey.on("hello", function (message) {
    Homey.alert(message); // Hello to you!
    return "Hi!"; // send a reply back to the pairing session
​
    // you can return a promise if you need to do some async
    // work before replying to the message.
  });
</script>
/drivers/<driver_id>/driver.js
const Homey = require('homey');
​
class Driver extends Homey.Driver {
  async onPair(session) {
    session.setHandler("showView", async (viewId) => {
      if (viewId === "start") {
        const data = await session.emit("hello", "Hello to you!");
        console.log(data); // Hi!
      }
    });
  }
}
​
module.exports = Driver;
Set a Title
Homey.setTitle( String title )
Set the window's title.
Example
/drivers/<driver_id>/pair/start.html
<script type="application/javascript">
  Homey.setTitle(Homey.__("pair.title_searching"));
</script>
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
<script type="application/javascript">
  Homey.showView("list_devices");
</script>
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
<script type="application/javascript">
  Homey.createDevice({
    // The name of the device that will be shown to the user
    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",
    },
  })
    .then(function (result) {
      Homey.done();
    })
    .catch(function (error) {
      Homey.alert(err);
    });
</script>
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
<script type="application/javascript">
  function onHomeyReady(Homey) {
    alert(Homey.__("pair.title")); // will alert "Settings page title"
  }
</script>
Within your custom views, you can also use translations. For example:
/drivers/<driver_id>/pair/start.html
<span data-i18n="pair.title"></span>
<p data-i18n="pair.intro"></p>
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
<script type="application/javascript">
  var devicesArray = [
    {
      name: "My Device",
      data: {
        id: "abcd",
      },
    },
  ];
  Homey.setViewStoreValue("add_devices", "devices", devicesArray);
</script>

App Settings

Next - Advanced

Web API

Last modified 9mo ago

Copy link

Outline

Back-end API

Front-end API

Emit an event

Receive an event

Set a Title

Show a View

Previous View

Next View

Get the current view

Create a device

Get current zone

Get view options

Set navigation close

Close the pair session

Alert dialog

Confirm dialog

Popup

Internationalisation

Show the loading overlay

Hide the loading overlay

Get a view's store value

Set a view's store value