Capabilities

A capability is a pre-defined value of a device's state. For example, onoff tells Homey whether the device is turned on (when true) or off (when false).

Homey uses system capabilities, as can be found in the Reference.

Custom capabilities

Additionally to system capabilities, an app can add capabilities to Homey by providing them in app.json. These capabilities can then be used in your own app's drivers.

Define custom capabilities in the root object capabilities and reference the key (capability name) in drivers.driver_x.capabilities

/app.json


{
    "id": "com.athom.hello",
    ...
    "capabilities": {
        "my_boolean_capability": {
            "type": "boolean",
            "title": {
                "en": "My Boolean capability"
            },
            "getable": true,
            "setable": true
        },
        "my_numeric_capability": {
            "type": "number",
            "title": {
                "en": "My Numeric capability"
            },
            "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" ],
            ...
        }
    ]
}

Using the same capability more than once

In certain cases it might occur that a device should use a capability more than once. 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.

Capability options

Some capabilities hold options, that can be set to improve the user experience. Capability-specific options can be found in the in the Reference.

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

/app.json


{
    "id": "com.athom.hello",
    ...
    "drivers": [
        {
            "id": "my_driver",
            "capabilities": [ "onoff" ],
            "capabilitiesOptions": {
                "onoff": {
                    "title": {
                        "en": "My custom Title"
                    }
                }
            },
            ...
        }
    ]
}

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