Capabilities

A capability is a programmatic representation of a device's state. For example, onoff 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 Apps Reference.

Using capabilities in your driver

In your /app.json, 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.

Using capabilities in your device

Your Device (device.js) instance needs to keep the device synchronised with Homey.

The device's state has changed

Listen for device state changes and update them with Homey by calling Device#setCapabilityValue.

/drivers/my_driver/device.js

this.setCapabilityValue('onoff', true)
  .catch(this.error);

Homey changes the device's state

You need to register a method with Device#registerCapabilityListener that pushes the new state to the physical device.

When a user or Flow changes the device's state, this method will be called.

this.registerCapabilityListener('onoff', async (value) => {
  return setMyDeviceState({ on: value });
});

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 subcapabilities.

Capability options

Some capabilities make use of capability options, which can be set to improve the user experience. Capability-specific options can be found in the Apps Reference.

Capability options can be set using the capabilitiesOptions object in the driver's entry in app.json.

/app.json

{
  "id": "com.athom.example",
  ...
  "drivers": [
    {
      "id": "my_driver",
      "capabilities": [ "onoff", "dim" ],
      "capabilitiesOptions": {
        "dim": {
          "preventInsights": true
        }
      }
    }
  ]
}

Options that apply to all capabilities are:

| Attribute | Type | Example | Description | | --- | --- | --- | | title | object (i18n) | { "en": "My Custom Title" } | Overwrite the capability title | | preventInsights | boolean | true | Prevent Insights from being automatically generated | | preventTag | boolean | true | Prevent a Tag from being automatically generated |

Custom capabilities

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

Define custom capabilities in /app.json, in an object capabilities.

/app.json

{
  "id": "com.athom.example",
  ...
  "capabilities": {
    "my_boolean_capability": {
      "type": "boolean",
      "title": {
        "en": "My Boolean capability"
      },
      "getable": true,
      "setable": true,
      "uiComponent": "toggle",
      "uiQuickAction": true,
      "icon": "/assets/my_boolean_capability.svg"
    },
    "my_numeric_capability": {
      "type": "number",
      "title": {
        "en": "My Numeric capability"
      },
      "uiComponent": "slider",
      "getable": true,
      "setable": false,
      "units": {
        "en": "Cb"
      },
      "min": 0,
      "max": 30,
      "step": 0.5
    }
  },
  "drivers": [
    {
      "id": "my_driver",
      "capabilities": [ "onoff", "my_boolean_capability", "my_numeric_capability" ],
      ...
    }
  ]
}

Type

"type": boolean

A capability can be of type boolean, number, string or enum.

Title

"title": { "en": "My Capability" }

An i18n-object with the capability's title.

Getable

"getable": false 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.updateCapabilityValue.

Setable

"setable": false 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

"units": "°C"

An i18n-object of the capability's units, when applicable.

Minimum

"min": 0"

Only use this when the capability type is number.

A minimum number of the value.

Maximum

"max": 0"

Only use this when the capability type is number.

A minimum number of the value.

Step size

"step": 2"

Only use this when the capability type is number.

A step size of the value.

Decimals

"decimals": 2

Only use this when the capability type is number.

The number of decimals to show in the UI.

UI Component

"uiComponent": "slider"

A preferred component to display in the UI. To hide a capability in the UI, set uiComponent to null.

UI Quick Action

"uiQuickAction": true

Only use this when the capability type is boolean.

Set this to true when you want the user to quick-toggle the capability's value from the UI.

Icon

"icon": "/assets/my_capability.svg"

A path to an .svg Icon.

Insights

"insights": true Default: false

Whether this capability should create an Insights log.

Insights Title (when true)

"insightsTitleTrue": { "en": "Turned on" }

Only use this when the capability type is boolean.

An i18n-object which describes the title when shown in a Timeline.

Insights Title (when false)

"insightsTitleFalse": { "en": "Turned on" }

Only use this when the capability type is boolean.

An i18n-object which describes the title when shown in a Timeline.

Values

"values": [ ... ]

Only use this when the capability type is enum.

An array of possible values for this capability.

"values": [
  {
    "id": "value1",
    "title": {
      "en": "First Value"
    }
  },
  {
    "id": "value2",
    "title": {
      "en": "Second Value"
    }
  }
]

A value consists of an id, which will be the capability value, and a title, which is an i18n-object.

Starting Flows for custom capabilities

Custom capabilities starting with alarm_, meter_ and measure_ will automatically try to trigger a Flow. You only need to define this Flow trigger in your /app.json.

Numbers

Calling setCapabilityValue('measure_my_number', 1) will try to start a Flow trigger with ID measure_my_number_changed, with a Tag measure_my_number.

Booleans

Calling setCapabilityValue('alarm_my_alarm', true) will try to start a Flow trigger with ID alarm_my_alarm_true, with a Tag alarm_my_alarm.