Custom Pairing Views

Most drivers will suffice using the provided pairing templates. Some advanced drivers however can benefit from creating their own 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.

JavaScript

/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;

TypeScript

/drivers/<driver_id>/driver.mts

import Homey from "homey";

export default class Driver extends Homey.Driver {
  async onPair(session: Homey.Driver.PairSession): Promise<void> {
    // 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 (viewId: string) => {
      this.log("View:", viewId);
    });
  }
}

Python

/drivers/<driver_id>/driver.py

from homey import driver
from homey.pair_session import PairSession


class Driver(driver.Driver):
    async def on_pair(self, session: PairSession) -> None:
        # Show a specific view by ID
        await session.show_view("my_view")

        # Show the next view
        await session.next_view()

        # Show the previous view
        await session.prev_view()

        # Close the pair session
        await session.done()

        # Received when a view has changed
        async def on_show_view(view_id: str) -> None:
            self.log("View:", view_id)

        session.set_handler("showView", on_show_view)


homey_export = 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 your driver implementation.

/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>

JavaScript

/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;

TypeScript

/drivers/<driver_id>/driver.mts

import Homey from "homey";

type MyEventData = {
  foo: string;
};

export default class Driver extends Homey.Driver {
  async onPair(session: Homey.Driver.PairSession): Promise<void> {
    session.setHandler("my_event", async (data: MyEventData): Promise<string> => {
      return "Hello!";
    });
  }
}

Python

/drivers/<driver_id>/driver.py

from typing import TypedDict

from homey import driver
from homey.pair_session import PairSession


class MyEventData(TypedDict):
    foo: str


class Driver(driver.Driver):
    async def on_pair(self, session: PairSession) -> None:
        async def on_my_event(data: MyEventData) -> str:
            return "Hello!"

        session.set_handler("my_event", on_my_event)


homey_export = 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>

JavaScript

/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;

TypeScript

/drivers/<driver_id>/driver.mts

import Homey from "homey";

export default class Driver extends Homey.Driver {
  async onPair(session: Homey.Driver.PairSession): Promise<void> {
    session.setHandler("showView", async viewId => {
      if (viewId === "start") {
        const data: string = await session.emit("hello", "Hello to you!");
        console.log(data); // Hi!
      }
    });
  }
}

Python

/drivers/<driver_id>/driver.py

from typing import TypedDict

from homey import driver
from homey.pair_session import PairSession


class MyEventData(TypedDict):
    foo: str


class Driver(driver.Driver):
    async def on_pair(self, session: PairSession) -> None:
        async def on_show_view(view: str) -> None:
            if view == "start":
                data: str = await session.emit("hello", "Hello to you!")
                print(data)  # Hi!

        session.set_handler("showView", on_show_view)


homey_export = 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"));
</script>

Set a Subtitle

Homey.setSubtitle( String subtitle )

Set the window's subtitle.

Example

/drivers/<driver_id>/pair/start.html

<script type="application/javascript">
  Homey.setSubtitle(Homey.__("pair.subtitle"));
</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 properties data and name and may contain 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(error);
    });
</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>