Capabilities

A capability is a programmatic representation of a device's state.

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.

/drivers/<driver_id>/device.js

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.

/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"
  },
  "class": "light",
  "capabilities": ["onoff", "dim"],
  "capabilitiesOptions": {
    "dim": { "preventInsights": true }
  }
}

Options that apply to all capabilities are:

Attribute	Description
title	Overwrite the capability title { "en": "My Custom Title" }. Make sure a custom title is never more than 2 - 3 words.
preventInsights	Prevent Insights from being automatically generated.
preventTag	Prevent a Flow Tag from being automatically generated.

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().

Attribute	Description
duration	Set to true to allow users to set a duration on the Flow Action card associated with this capability.

/drivers/<driver_id>/device.js

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:

Attribute	Description
insightsTitleTrue	A translation object which describes the title when shown in a Timeline.
insightsTitleFalse	A translation object which describes the title when shown in a Timeline.
titleTrue	A translation object which describes the title when shown in a sensor UI component.
titleFalse	A translation object which describes the title when shown in a sensor UI component.

Number capability options

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

Attribute	Description
units	A translation object of the capability's units, when applicable. If set to "°C" Homey can automatically convert this capability value to Fahrenheit.
decimals	The number of decimals to show in the UI.
min	A minimum for the capability value.
max	A maximum for the capability value.
step	A step size of the capability value.

Enum capability options

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

Attribute	Description
values	An array of object's where each object contains a unique id and a title property that is a translation object.

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

Note that these are only available since Homey v12.0.1 so in order to use this option increase your app's compatibility.

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:

Attribute	Description
zoneActivity	Controls whether changes to this capability value also trigger the zone to become active. Set to false to disable zone activity for this capability.

Homey Energy capability options

Options that apply to measure_power are:

Attribute	Description
approximated	This capability option shows to the user that this power usage measurement might not be accurate. See Approximated power usage for more information.

Light device capability options

Options that apply to onoff are:

Attribute	Description
setOnDim	You can set this capability to false to prevent the onoff capability from being set when the dim capability is updated by a Flow action card. See Lights for more information.

Getable

Options that apply to onoff and volume_mute are:

Attribute	Description
getable	This capability option can be set to false to make the onoff or volume_mute capability stateless. If this option is set to false the device's quickAction will be disabled, the UI components will be updated, and some Flow cards will be added/removed.

The getable capability option is available as of Homey v7.2.1.

Adding getable: false to an existing driver will break users' Flows as it removes a number of Flow cards belonging to the onoff and volume_mute capabilities.

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.

/.homeycompose/capabilities/my_boolean_capability.json

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

/.homeycompose/capabilities/my_numeric_capability.json

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

/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"
  },
  "class": "other",
  "capabilities": ["onoff", "my_boolean_capability", "my_numeric_capability"]
}

The following options can be set for all custom capabilities:

Property	Description
type	A capability can be of type boolean, number, string or enum.
title	A translation object with the capability's title. Keep titles short, max 3 words.
getable	Default: true, a boolean whether the capability's value can be requested by a front-end. When getable is false, your Device doesn't need to call Device#setCapabilityValue.
setable	Default: true, a boolean whether the capability's value can be set by a front-end. When setable is false, your Device doesn't need to register a capability listener.
units	A translation object of the capability's units, when applicable. If set to "°C" Homey can automatically convert this capability value to Fahrenheit.
uiComponent	A preferred component to display in the UI. To hide a capability in the UI, set uiComponent to null.
icon	A path to an .svg Icon.
insights	Default: false, whether this capability should create an Insights log. Only applicable to the number and boolean type.

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

Property	Description
uiQuickAction	Set this to true when you want the user to quick-toggle the capability's value from the UI.
insightsTitleTrue	A translation object which describes the title when shown in a Timeline.
insightsTitleFalse	A translation object which describes the title when shown in a Timeline.

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

Property	Description
min	A minimum for the capability value.
max	A maximum for the capability value.
step	A step size of the capability value.
decimals	The number of decimals to show in the UI.

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

Property	Description
values	An array of possible values for this capability. A value consists of an id, which will be the capability value, and a title, which is a translation object. The three values should have the ID's up, idle, and down.{ "id": "option1", "title": { "en": "First option" }}

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.

An example with capabilities: 'meter_power', 'measure_battery' and 'alarm_motion'.

Note that it's not possible for users to select and override the default indicator if the device class is thermostat, light, lock or speaker.

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.

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

{
  "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.

/drivers/<driver_id>/device.js

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.

Flow Cards will not be automatically generated for sub-capabilities, you should create these cards yourself.