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.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;
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. |
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;
Options that apply to boolean capabilities, such as
onoff, windowcoverings_closed, garagedoor_closed, alarm_generic and button, are:Attribute | Description |
insightsTitleTrue | |
insightsTitleFalse | |
titleTrue | |
titleFalse |
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. |
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. |
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. |
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. |
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.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 | |
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 | |
insightsTitleFalse |
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" }} |
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, 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, 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'.
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."uiComponent": "toggle"The toggle component displays one
boolean capability. Depending on the capability, the look might change.
"uiComponent": "slider"The slider component displays one
number capability. Depending on the capability, the look might change.
"uiComponent": "sensor"The sensor component displays multiple
number, enum, string or boolean capabilities.Booleans that are
true and begin with alarm_ will flash red.
"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.
"uiComponent": "media"The media component accepts the
speaker_playing, speaker_next, speaker_prev, speaker_shuffle and speaker_repeat capabilities.
"uiComponent": "color"The color component accepts the
light_hue, light_saturation, light_temperature and light_mode capabilities.
"uiComponent": "battery"The battery component accepts either a
measure_battery or alarm_battery capability.
"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. 
"uiComponent": "ternary"The ternary component accepts one
enum capability with three values, meant for motorized components.
"uiComponent": nullTo hide the UI component, specify
null as value.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
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." }
}
}
}
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;
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.
Last modified 4mo ago