Interfaces for DeviceClasses

When creating a DeviceClass, the interfaces field can be used to specify a list of interfaces this DeviceClass implements.

When implementing an interface, the DeviceClass must follow the interface specification for the according interface. This means the DeviceClass needs to have at least all the states, actions and events the given interface requires. A DeviceClass may add custom states, actions or events, or even implement multiple interfaces.

The main purpose of interfaces is to provide for a better user experience. Using interfaces, a plugin developer can suggest the ui to be used for this DeviceClass. For example, having a plugin that can control a dimmable light would likely have a state named "powered" of type boolean and one named "brightness" of type int, ranging from 0 to 100%. Having just this information, the ui would create a generic switch component to flip the bool state and a generic slider component to allow adjusting the brightness because it can't know what the actual switch or slider do. For a better user experience though, the plugin developer could just add the interface "dimmedlight" to this deviceclass and this way tell the ui that this actually is a dimmed light. The ui can use this information to paint a pretty brightness slider, and implicitly flip the power switch off when the brightness slider is moved to the lower end.

Another purpose of interfaces is to help the ui grouping and managing device classes. For example the gateway interface does not require to implement any properties, however, it tells the ui that this is a gateway and thus not relevant to show to the user in the main control entity. Instead, gateways might be listed in the configuration section of the client application.

In general it is a good idea to follow as many interfaces as precicely as possible in order to provide for the best user experience.

A interface can extend another interface. For example, the light interface only requires one state called powered of type bool. A dimmablelight extends this type and adds a brightness property to it. This means, if a DeviceClass implements dimmablelight, it also needs to cater for the light interface's states.

Available interfaces

This following list shows you the current available interfaces.

battery

{
    "states": [
        {
            "name": "batteryCritical",
            "type": "bool"
        }
    ]
}

batterylevel

{
    "extends": "battery",
    "states": [
        {
            "name": "batteryLevel",
            "type": "int",
            "minValue": 0,
            "maxValue": 100
        }
    ]
}

blind

{
    "extends": "simpleclosable",
    "actions": [
        {
            "name": "stop"
        }
    ]
}

button

{
}

closable

{
    "extends": "simpleclosable",
    "states": [
        {
            "name": "state",
            "type": "QString",
            "allowedValues": ["open", "closed", "opening", "closing"]
        }
    ]
}

colorlight

{
    "extends": "dimmablelight",
    "states": [
        {
            "name": "colorTemperature",
            "type": "int",
            "minimumValue": "any",
            "maximumValue": "any"
        },
        {
            "name": "color",
            "type": "QColor"
        }
    ]
}

connectable

{
    "states": [
        {
            "name": "connected",
            "type": "bool",
            "defaultValue": false
        }
    ]
}

dimmablelight

{
    "extends": "light",
    "states": [
        {
            "name": "brightness",
            "type": "int",
            "minimumValue": 0,
            "maximumValue": 100,
            "writable": true
        }
    ]
}

extendedvolumecontroller

{
    "extends": "media",
    "states": [
        {
            "name": "mute",
            "type": "bool",
            "writable": true
        },
        {
            "name": "volume",
            "type": "int",
            "minValue": 0,
            "maxValue": 100,
            "writable": true
        }
    ]
}

garagegate

{
    "extends": "closable",
    "states": [
        {
            "name": "intermediatePosition",
            "type": "bool"
        }
    ],
    "actions": [
        {
            "name": "stop"
        }
    ]
}

gateway

{

}

humiditysensor

{
    "extends": "sensor",
    "states": [
        {
            "name": "humidity",
            "type": "double",
            "minValue": 0,
            "maxValue": 100
        }
    ]
}

inputtrigger

{
    "events": [
        {
            "name": "triggered"
        }
    ]
}

light

{
    "extends": "power"
}

longpressbutton

{
    "extends": "simplebutton",
    "events": [
        {
            "name": "longPressed"
        }
    ]
}

longpressmultibutton

{
    "extends": "longpressbutton",
    "events": [
        {
            "name": "longPressed",
            "params": [
                {
                    "name": "buttonName",
                    "type": "QString"
                }
            ]
        }
    ]
}

mediacontroller

{
    "extends": "media",
    "states": [
        {
            "name": "mute",
            "type": "bool",
            "writable": true
        },
        {
            "name": "volume",
            "type": "int",
            "minValue": 0,
            "maxValue": 100,
            "writable": true
        },
        {
            "name": "playbackStatus",
            "type": "QString",
            "allowedValues": ["Playing", "Paused", "Stopped"],
            "writable": true
        }

    ],
    "actions": [
        {
            "name": "skipBack"
        },
        {
            "name": "rewind"
        },
        {
            "name": "stop"
        },
        {
            "name": "play"
        },
        {
            "name": "pause"
        },
        {
            "name": "fastForward"
        },
        {
            "name": "skipNext"
        }
    ]
}

media

{

}

mediametadataprovider

{
    "extends": "media",
    "states": [
        {
            "name": "artist",
            "type": "string"
        },
        {
            "name": "album",
            "type": "string"
        },
        {
            "name": "title",
            "type": "string"
        },
        {
            "name": "artwork",
            "type": "string"
        }
    ]
}

mediaplayer

{
    "extends": "media",
    "states": [
        {
            "name": "playbackStatus",
            "type": "string",
            "allowedValues": ["Playing", "Paused", "Stopped"],
            "writable": true
        },
        {
            "name": "playerType",
            "type": "string",
            "allowedValues": ["audio", "video"]
        }
    ]
}

notifications

{
    "actions": [
        {
            "name": "notify",
            "params": [
                {
                    "name": "title",
                    "type": "QString"
                },
                {
                    "name": "body",
                    "type": "QString"
                }
            ]
        }

    ]
}

outputtrigger

{
    "actions": [
        {
            "name": "trigger"
        }
    ]
}

power

{
    "states": [
        {
            "name": "power",
            "type": "bool",
            "writable": true
        }
    ]
}

pressuresensor

{
    "extends": "sensor",
    "states": [
        {
            "name": "pressure",
            "type": "double"
        }
    ]
}

sensor

{

}

shutter

{
    "extends": "simpleclosable",
    "actions": [
        {
            "name": "stop"
        }
    ]
}

simplebutton

{
    "extends": "button",
    "events": [
        {
            "name": "pressed"
        }
    ]
}

simpleclosable

{
    "actions": [
        {
            "name": "open"
        },
        {
            "name": "close"
        }
    ]
}

simplemultibutton

{
    "extends": "button",
    "events": [
        {
            "name": "pressed",
            "params": [
                {
                    "name": "buttonName",
                    "type": "QString"
                }
            ]
        }
    ]
}

smartlock

{
    "extends": "simpleclosable",
    "states": [
        {
            "name": "state",
            "type": "QString",
            "allowedValues": ["locked", "locking", "unlocked", "unlocking", "unlatched",  "unlatching"]
        }
    ],
    "actions": [
        {
            "name": "unlatch"
        }
    ]
}

temperaturesensor

{
    "extends": "sensor",
    "states": [
        {
            "name": "temperature",
            "type": "double"
        }

    ]
}

volumecontroller

{
    "extends": "media",
    "actions": [
        {
            "name": "increaseVolume",
            "params": [
                {
                    "name": "step",
                    "type": "int"
                }
            ]
        },
        {
            "name": "decreaseVolume",
            "params": [
                {
                    "name": "step",
                    "type": "int"
                }
            ]
        },
        {
            "name": "setMute",
            "params": [
                {
                    "name": "mute",
                    "type": "bool"
                }

            ]
        }
    ]
}

weather

{
    "states": [
        {
            "name": "weatherDescription",
            "type": "QString"
        },
        {
            "name": "weatherCondition",
            "type": "QString",
            "allowedValues": ["clear-day", "clear-night", "few-clouds-day", "few-clouds-night", "clouds", "overcast", "light-rain", "shower-rain", "thunderstorm", "snow", "fog"]
        },
        {
            "name": "temperature",
            "type": "double"
        },
        {
            "name": "humidity",
            "type": "int"
        },
        {
            "name": "pressure",
            "type": "double"
        },
        {
            "name": "windSpeed",
            "type": "double"
        },
        {
            "name": "windDirection",
            "type": "int"
        }
    ]
}