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.
/drivers/<driver_id>/device.js
1
const Homey = require('homey');
2
const DeviceApi = require('device-api');
3
​
4
class Device extends Homey.Device {
5
  async onInit() {
6
    this.registerCapabilityListener("onoff", async (value) => {
7
      await DeviceApi.setMyDeviceState({ on: value });
8
    });
9
​
10
    DeviceApi.on('state-changed', (isOn) => {
11
      this.setCapabilityValue('onoff', isOn).catch(this.error);
12
    });
13
  }
14
}
15
​
16
module.exports = Device;
Copied!
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
1
{
2
  "name": { "en": "My Driver" },
3
  "images": {
4
    "small": "/drivers/my_driver/assets/images/small.png",
5
    "large": "/drivers/my_driver/assets/images/large.png"
6
  },
7
  "class": "light",
8
  "capabilities": ["onoff", "dim"],
9
  "capabilitiesOptions": {
10
    "dim": { "preventInsights": true }
11
  }
12
}
Copied!
Options that apply to all capabilities are:
Attribute
Description
title
Overwrite the capability title { "en": "My Custom Title" }.
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
1
const Homey = require('homey');
2
const DeviceApi = require('device-api');
3
​
4
const DEFAULT_DIM_DURATION = 1000;
5
​
6
class Device extends Homey.Device {
7
  async onInit() {
8
    this.registerCapabilityListener("dim", async (value, options) => {
9
      await DeviceApi.setMyDeviceState({
10
        on: value,
11
        duration: typeof options.duration === "number"
12
          ? options.duration
13
          : DEFAULT_DIM_DURATION,
14
      });
15
    });
16
  }
17
}
18
​
19
module.exports = Device;
Copied!
Boolean capability options
Options that apply to boolean capabilities, such as onoff, windowcoverings_closed, garagedoor_closed 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.
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.
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 and alarm_contact 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
1
{
2
  "type": "boolean",
3
  "title": { "en": "My Boolean capability" },
4
  "getable": true,
5
  "setable": true,
6
  "uiComponent": "toggle",
7
  "uiQuickAction": true,
8
  "icon": "/assets/my_boolean_capability.svg"
9
}
Copied!
/.homeycompose/capabilities/my_numeric_capability.json
1
{
2
  "type": "number",
3
  "title": { "en": "My Numeric capability" },
4
  "uiComponent": "slider",
5
  "getable": true,
6
  "setable": false,
7
  "units": { "en": "Cb" },
8
  "min": 0,
9
  "max": 30,
10
  "step": 0.5
11
}
Copied!
/drivers/<driver_id>/driver.compose.json
1
{
2
  "name": { "en": "My Driver" },
3
  "images": {
4
    "small": "/drivers/my_driver/assets/images/small.png",
5
    "large": "/drivers/my_driver/assets/images/large.png"
6
  },
7
  "class": "other",
8
  "capabilities": ["onoff", "my_boolean_capability", "my_numeric_capability"]
9
}
Copied!
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.
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.
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'.
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.
Ternary
"uiComponent": "ternary"
The ternary component accepts one enum capability with three values, meant for motorized components.
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
1
{
2
  "name": { "en": "P1 Meter" },
3
  "capabilities": [
4
    "meter_power",
5
    "measure_power",
6
    "button.calibrate",
7
    "button.reset_meter"
8
  ],
9
  "capabilitiesOptions": {
10
    "button.calibrate": {
11
      "maintenanceAction": true,
12
      "title": { "en": "Start calibration" },
13
      "desc": { "en": "Start the sensor calibration process." }
14
    },
15
    "button.reset_meter": {
16
      "maintenanceAction": true,
17
      "title": { "en": "Reset power meter" },
18
      "desc": { "en": "Reset the accumulated power usage (kWh), this can not be restored." }
19
    }
20
  }
21
}
Copied!
Listening for maintenance action events
Register the capability listeners in device.js to listen for maintenance action events.
/drivers/<driver_id>/device.js
1
const Homey = require('homey');
2
​
3
class Device extends Homey.Device {
4
  async onInit() {
5
    this.registerCapabilityListener('button.reset_meter', async () => {
6
      // Maintenance action button was pressed
7
    });
8
​
9
    this.registerCapabilityListener('button.calibrate', async () => {
10
      // Maintenance action button was pressed, return a promise
11
      throw new Error('Something went wrong');
12
    });
13
  }
14
}
15
​
16
module.exports = Device;
Copied!
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.
Pairing
Energy
Last modified 7d ago