Devices List

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.

Usage: "template": "list_devices"

/drivers/<driver_id>/driver.compose.json

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "pair": [
    {
      "id": "list_devices",
      "template": "list_devices",
      "navigation": { "next": "add_devices" },
      "options": { "singular": true }
    },
    {
      "id": "add_devices",
      "template": "add_devices"
    }
  ]
}

Options

Key	Type	Default	Description
singular	boolean	false	Only allow a single device to be selected

/drivers/<driver_id>/driver.js

const Homey = require("homey");
const DeviceApi = require("device-api");

class Driver extends Homey.Driver {
  async onPair(session) {
    session.setHandler("list_devices", async function () {
      const devices = await DeviceApi.discoverDevices();
      
      // you can emit when devices are still being searched
      // session.emit("list_devices", devices);

      // return devices when searching is done
      return devices;

      // when no devices are found, return an empty array
      // return [];

      // or throw an Error to show that instead
      // throw new Error('Something bad has occured!');
    });
  }
}

module.exports = Driver;

Because the list_devices template is very common the Driver#onPairListDevices() method exists which you can implement instead of the Driver#onPair() method.