Capabilities

A simple example of capabilities is onoff. This is a boolean capability that tells Homey whether the device is turned on (when true) or off (when false). Homey ships with many capabilities (called system capabilities). These can be found in the Device Capability Reference.

Using capabilities

In your App Manifest, for every driver an array capabilities is required. This is an array with the keys of all capabilities. This array can be overwritten during pairing.

Your Device (device.js) instance needs to keep the device synchronised with Homey. Capabilities need to be synchronized both ways. This means that if a device's state changes, for example if the user turns on the lights, your app needs to tell Homey. It is also possible for Homey to request your app to change the state of the device, for example when a Flow is triggered to turn off the lights.

Your Device class should listen for changes to the device's and then update the capability value within Homey by calling Device#setCapabilityValue(). You should also register a method with Device#registerCapabilityListener() that to update the state of the physical device.

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

class Device extends Homey.Device {
  async onInit() {
    this.registerCapabilityListener("onoff", async (value) => {
      await DeviceApi.setMyDeviceState({ on: value });
    });

    DeviceApi.on('state-changed', (isOn) => {
      this.setCapabilityValue('onoff', isOn).catch(this.error);
    });
  }
}

module.exports = Device;

Capability options

Some capabilities make use of capability options, which can be set to change the default behaviour of capabilities. Capability options can be set using the capabilitiesOptions object in the driver's entry in the App Manifest.

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "light",
  "capabilities": ["onoff", "dim"],
  "capabilitiesOptions": {
    "dim": { "preventInsights": true }
  }
}

Options that apply to all capabilities are:

Duration

The duration capability option can be used to allow users to specify the duration of a Flow Action card for built-in capabilities. The configured duration will be passed as a second argument to your capability listener in Device#registerCapabilityListener().

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

const DEFAULT_DIM_DURATION = 1000;

class Device extends Homey.Device {
  async onInit() {
    this.registerCapabilityListener("dim", async (value, options) => {
      await DeviceApi.setMyDeviceState({
        on: value,
        duration: typeof options.duration === "number"
          ? options.duration
          : DEFAULT_DIM_DURATION,
      });
    });
  }
}

module.exports = Device;

Boolean capability options

Options that apply to boolean capabilities, such as onoff, windowcoverings_closed, garagedoor_closed, alarm_generic and button, are:

Number capability options

Options that apply to number capabilities, such as the measure_* capabilities, are:

Enum capability options

Options that apply to enum capabilities, such as the thermostat_mode, are:

"capabilitiesOptions": {
    "thermostat_mode": {
      "values": [
        {
          "id": "heat",
          "title": { 
            "en": "Heat",
            "nl": "Verhitten"
          }
        },
        {
          "id": "cool",
          "title": { 
            "en": "Cool",
            "nl": "Koelen"
          }
        }
      ]
    }
  }

Zone activity capability options

Certain capabilities will mark their device's zone active when their value changes. This behaviour can be controlled using capability options.

Options that apply to alarm_motion, alarm_contact, alarm_vibration, alarm_occupancy and alarm_presence are:

Homey Energy capability options

Options that apply to measure_power are:

Light device capability options

Options that apply to onoff are:

Getable

Options that apply to onoff and volume_mute are:

Custom capabilities

In some cases these might not suit your device. Your app can provide additional capabilities (called custom capabilities).

Define custom capabilities in your App Manifest, in an object capabilities.

{
  "type": "boolean",
  "title": { "en": "My Boolean capability" },
  "getable": true,
  "setable": true,
  "uiComponent": "toggle",
  "uiQuickAction": true,
  "icon": "/assets/my_boolean_capability.svg"
}

{
  "type": "number",
  "title": { "en": "My Numeric capability" },
  "uiComponent": "slider",
  "getable": true,
  "setable": false,
  "units": { "en": "Cb" },
  "min": 0,
  "max": 30,
  "step": 0.5
}

{
  "name": { "en": "My Driver" },
  "images": {
    "small": "/drivers/my_driver/assets/images/small.png",
    "large": "/drivers/my_driver/assets/images/large.png"
  },
  "class": "other",
  "capabilities": ["onoff", "my_boolean_capability", "my_numeric_capability"]
}

The following options can be set for all custom capabilities:

When the capability type is boolean the following additional properties can be set:

When the capability type is number the following additional properties can be set:

When the capability type is enum the following additional properties can be set:

Device Indicators and Custom Capabilities

The Homey web app and mobile app can display indicators next to the device icons. This gives users the ability to view a specific capability, such as a temperature value or battery status, at a glance. Custom boolean and number capabilities can also be shown as indicators as device indicators.

Boolean Capabilities

Boolean capabilities, also called Alarms in Homey, are displayed in two different ways if they start with the prefix alarm_. By default all capabilities with this prefix are grouped, and a warning icon is shown if the value of any of the boolean capabilities is true. Alternatively users can choose to show the indicator value of a single specific Alarm capability. The alarm_battery capabilities will show an "empty battery" icon instead of an exclamation mark.

Number Capabilities

Number capabilities, are displayed as a numeric value together with the unit of the capability. Users are able to select capabilities that start with either the prefix measure_ or meter_. The measure_battery capability will always be displayed with a custom battery icon instead of a number.

UI Components

All system capabilities have their own UI component. Custom capabilities can also use these UI components. Homey will automatically try to find the right component, but you can override this by specifying the uiComponent property in your custom capability.

Toggle

"uiComponent": "toggle"

The toggle component displays one boolean capability. Depending on the capability, the look might change.

Slider

"uiComponent": "slider"

The slider component displays one number capability. Depending on the capability, the look might change.

Sensor

"uiComponent": "sensor"

The sensor component displays multiple number, enum, string or boolean capabilities.

Booleans that are true and begin with alarm_ will flash red.

Thermostat

"uiComponent": "thermostat"

The thermostat component displays a target_temperature capability, and an optional measure_temperature.

If you use sub-capabilities for target_temperature and measure_temperature, make sure the dot suffix of the capabilities are the same so that they will be displayed together, for instance: target_temperature.top and measure_temperature.top.

Media

"uiComponent": "media"

The media component accepts the speaker_playing, speaker_next, speaker_prev, speaker_shuffle and speaker_repeat capabilities.

Additionally, it shows the album art as set using Device#setAlbumArt().

Color

"uiComponent": "color"

The color component accepts the light_hue, light_saturation, light_temperature and light_mode capabilities.

Battery

"uiComponent": "battery"

The battery component accepts either a measure_battery or alarm_battery capability.

Picker

"uiComponent": "picker"

The picker component accepts one enum capability and shows a list of possible values. Make sure the values titles fit on one line and are never more than 3 words.

Ternary

"uiComponent": "ternary"

The ternary component accepts one enum capability with three values, meant for motorized components.

Button

"uiComponent": "button"

The button component displays one or moreboolean capabilities. Depending on the capability, the look might change. Most buttons are stateless but it is possible to add a stateful button if the capability is both setable and getable. Some buttons will be grouped together like volume_up and volume_down.

No UI component

"uiComponent": null

To hide the UI component, specify null as value.

Maintenance Actions

This feature depends on Homey v3.1.0 and Homey Smartphone App v3.0.1.

Button capabilities can be flagged as maintenance action. This will show a button in 'Device settings > Maintenance actions' and hide the uiComponent in the device view. When this button is pressed the registered capability listener will be triggered. This allows you to initiate actions from the device's settings.

Example use cases:

• Starting the calibration process on a device

• Resetting accumulated power measurements

Creating a maintenance action

A maintenance action capability must be a capability that extends the system capability button. In order to mark it as a maintenance action add the maintenanceAction: true property to the capabilitiesOptions object of the driver manifest. Additionally, provide a title property, and optionally a desc property.

{
  "name": { "en": "P1 Meter" },
  "capabilities": [
    "meter_power",
    "measure_power",
    "button.calibrate",
    "button.reset_meter"
  ],
  "capabilitiesOptions": {
    "button.calibrate": {
      "maintenanceAction": true,
      "title": { "en": "Start calibration" },
      "desc": { "en": "Start the sensor calibration process." }
    },
    "button.reset_meter": {
      "maintenanceAction": true,
      "title": { "en": "Reset power meter" },
      "desc": { "en": "Reset the accumulated power usage (kWh), this can not be restored." }
    }
  }
}

Listening for maintenance action events

Register the capability listeners in device.js to listen for maintenance action events.

const Homey = require('homey');

class Device extends Homey.Device {
  async onInit() {
    this.registerCapabilityListener('button.reset_meter', async () => {
      // Maintenance action button was pressed
    });

    this.registerCapabilityListener('button.calibrate', async () => {
      // Maintenance action button was pressed, return a promise
      throw new Error('Something went wrong');
    });
  }
}

module.exports = Device;

Sub-capabilities - using the same capability more than once

In certain cases it might occur that a device should use a capability more than once. You can use a sub-capability for this purpose.

An example would be a device with an outside and inside temperature sensor. Simply append a dot followed by an identifier after the capability string during in your driver, e.g. measure_temperature.inside & measure_temperature.outside.