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.
This following list shows you the current available interfaces.
{ "events": [ { "name": "accessGranted" }, { "name": "accessDenied" } ] }
{ "extends": "closable" }
See also: closable
{ "states": [ { "name": "batteryCritical", "type": "bool" } ] }
{ "extends": "battery", "states": [ { "maxValue": 100, "minValue": 0, "name": "batteryLevel", "type": "int" } ] }
See also: battery
{ "extends": "closable" }
See also: closable
{}
{ "actions": [ { "name": "stop" } ], "extends": "simpleclosable" }
See also: simpleclosable
CO2 sensors. Measures co2 in parts per million.
{ "extends": "sensor", "states": [ { "name": "co2", "type": "double", "unit": "PartsPerMillion" } ] }
See also: sensor
{ "extends": "colortemperaturelight", "states": [ { "name": "color", "type": "QColor", "writable": true } ] }
See also: colortemperaturelight
{ "extends": "dimmablelight", "states": [ { "maximumValue": "any", "minimumValue": "any", "name": "colorTemperature", "type": "int", "writable": true } ] }
See also: dimmablelight
{ "extends": "sensor", "states": [ { "name": "conductivity", "type": "double", "unit": "UnitMicroSiemensPerCentimeter" } ] }
See also: sensor
{ "states": [ { "defaultValue": false, "name": "connected", "type": "bool" } ] }
Devices implementing the daylight sensor interface have a boolean state indicating if currently is daylight. Additionally the current times for sunrise and sunset are provided.
{ "extends": "sensor", "states": [ { "name": "daylight", "type": "bool" }, { "name": "sunriseTime", "type": "int", "unit": "UnixTime" }, { "name": "sunsetTime", "type": "int", "unit": "UnixTime" } ] }
See also: sensor
{ "extends": "light", "states": [ { "maximumValue": 100, "minimumValue": 0, "name": "brightness", "type": "int", "writable": true } ] }
See also: light
An EV-charger. Extends the power interface for charging/not charging an electric vehicle.
{ "extends": "power" }
See also: power
{ "extends": [ "awning", "extendedclosable" ] }
See also: awning, extendedclosable
{ "extends": [ "blind", "extendedclosable" ] }
See also: blind, extendedclosable
{ "extends": "closable", "states": [ { "name": "moving", "type": "bool" }, { "maximumValue": 100, "minimumValue": 0, "name": "percentage", "type": "int" } ] }
See also: closable
An extended version of the EV-charger interface. Supports regulation of percentage in addition ot be powered on or off.
{ "extends": "evcharger", "states": [ { "name": "maxChargingCurrent", "type": "uint", "unit": "MilliAmpere", "writable": true } ] }
See also: evcharger
The extendedheating interface defines heating appliances which can also be controlled with a percentage range. When implementing such a device class, do not set power to true when the percentage is set.
{ "extends": "heating", "states": [ { "max": 100, "min": 0, "name": "percentage", "type": "int", "unit": "Percentage", "writable": true } ] }
See also: heating
A more advanced media controller interface, supporting fast forward and rewind
{ "actions": [ { "name": "fastRewind" }, { "name": "fastForward" } ], "extends": "mediacontroller" }
See also: mediacontroller
{ "extends": [ "shutter", "extendedclosable" ] }
See also: shutter, extendedclosable
Like smartmeterconsumer, but instead of only providing total consumed energy, this also supports retrieving the current power demand rate. Note that currentPower is negative for consumers but might also be positive if a device implements consumer and producer and currently produces more than it consumes.
{ "extends": "smartmeterconsumer", "states": [ { "name": "currentPower", "type": "double" } ] }
See also: smartmeterconsumer
Like smartmeterproducer, but instead of only providing total produced energy, this also supports retrieving the current power supply rate. Note that currentPower is positive for producers but might also be negative if a device implements consumer and producer and currently consumes more than it produces.
{ "extends": "smartmeterproducer", "states": [ { "name": "currentPower", "type": "double" } ] }
See also: smartmeterproducer
{ "extends": "media", "states": [ { "name": "mute", "type": "bool", "writable": true }, { "maxValue": 100, "minValue": 0, "name": "volume", "type": "int", "writable": true } ] }
See also: media
{ "actions": [ { "name": "addUser", "params": [ { "name": "userId", "type": "QString" }, { "allowedValues": [ "ThumbLeft", "IndexFingerLeft", "MiddleFingerLeft", "RingFingerLeft", "PinkyLeft", "ThumbRight", "IndexFingerRight", "MiddleFingerRight", "RingFingerRight", "PinkyRight" ], "name": "finger", "type": "QString" } ] }, { "name": "removeUser", "params": [ { "name": "userId", "type": "QString" } ] } ], "events": [ { "name": "accessGranted", "params": [ { "name": "userId", "type": "QString" }, { "allowedValues": [ "ThumbLeft", "IndexFingerLeft", "MiddleFingerLeft", "RingFingerLeft", "PinkyLeft", "ThumbRight", "IndexFingerRight", "MiddleFingerRight", "RingFingerRight", "PinkyRight" ], "name": "finger", "type": "QString" } ] } ], "extends": "useraccesscontrol" }
See also: useraccesscontrol
{ "extends": "closable", "states": [ { "allowedValues": [ "open", "closed", "opening", "closing" ], "name": "state", "type": "QString" }, { "name": "intermediatePosition", "type": "bool" } ] }
See also: closable
{ "extends": "connectable" }
See also: connectable
The heating interface defines basic heating appliances.
{}
{ "extends": "sensor", "states": [ { "maxValue": 100, "minValue": 0, "name": "humidity", "type": "double" } ] }
See also: sensor
{ "events": [ { "name": "triggered" } ] }
{ "extends": "power" }
See also: power
{ "extends": "sensor", "states": [ { "name": "lightIntensity", "type": "double", "unit": "Lux" } ] }
See also: sensor
{ "events": [ { "name": "longPressed" } ], "extends": "simplebutton" }
See also: simplebutton
{ "events": [ { "name": "longPressed", "params": [ { "name": "buttonName", "type": "QString" } ] } ], "extends": "longpressbutton" }
See also: longpressbutton
The base for all media interfaces. Client applications might use this to group/filter things supporting media playback/control. When implementing a plugin use mediaplayer or mediacontroller for actual devices.
{}
The mediacontroller interface contains basic actions to control media streams. If a device supports fast forward and rewind, use extendedmediacontroller instead.
{ "actions": [ { "name": "skipBack" }, { "name": "stop" }, { "name": "play" }, { "name": "pause" }, { "name": "skipNext" } ], "extends": "media" }
See also: media
Provide media information, meant to be used in combination with mediaplayer. For music players, use collection to provide the album/compilation, for video players fill in the series name or a movie collection name there. Artwork can be a URL to a artwork image.
{ "extends": "media", "states": [ { "name": "title", "type": "QString" }, { "name": "artist", "type": "QString" }, { "name": "collection", "type": "QString" }, { "name": "artwork", "type": "QString" } ] }
See also: media
Media player interface. Used by devices/services which can play back media.
{ "extends": "media", "states": [ { "allowedValues": [ "Playing", "Paused", "Stopped" ], "name": "playbackStatus", "type": "QString" }, { "allowedValues": [ "audio", "video" ], "name": "playerType", "type": "QString" } ] }
See also: media
{ "extends": "sensor", "states": [ { "name": "moisture", "type": "double" } ] }
See also: sensor
A sensor interface for noise sensors. Should deliver a median noise level in regular intervals. This is meant for overall noise level monitoring (e.g. in buildings) and not real time audio processing.
{ "extends": "sensor", "states": [ { "name": "noise", "type": "double", "unit": "Dezibel" } ] }
See also: sensor
{ "actions": [ { "name": "notify", "params": [ { "name": "title", "type": "QString" }, { "name": "body", "type": "QString" } ] } ] }
{ "actions": [ { "name": "trigger" } ] }
{ "states": [ { "name": "power", "type": "bool", "writable": true } ] }
The powersocket interface is used for smart power sockets and just extends the simple power interface.
{ "extends": "power" }
See also: power
The presence sensor interface provides information whether a certain thing, for instance a human person, a tracked animal, a tracked mobile phone or smart watch is currently present. Additionally it gives information about the last time the tracked thing has been seen.
{ "extends": "sensor", "states": [ { "name": "isPresent", "type": "bool" }, { "name": "lastSeenTime", "type": "int", "unit": "UnixTime" } ] }
See also: sensor
{ "extends": "sensor", "states": [ { "name": "pressure", "type": "double", "unit": "MilliBar" } ] }
See also: sensor
{}
Devices/services supporting this interface can control reproduction flow. E.g. a media controller, but could also be used by light scenes or other workflows
{ "states": [ { "name": "shuffle", "type": "bool", "writable": true }, { "allowedValues": [ "None", "One", "All" ], "name": "repeat", "type": "QString", "writable": true } ] }
{ "extends": "simpleclosable" }
See also: simpleclosable
{ "events": [ { "name": "pressed" } ], "extends": "button" }
See also: button
{ "actions": [ { "name": "open" }, { "name": "close" } ] }
{ "events": [ { "name": "pressed", "params": [ { "name": "buttonName", "type": "QString" } ] } ], "extends": "button" }
See also: button
The smartlock interface is used for locks which can be opened digitally. The simplest form is a door opener which just unlatches the door lock for a few seconds so a person can enter. Implement the unlatch action and set the state to "unlatching" while opening. Set the state back to "locked" when done. More advanced devices might also allow keeping a door unlatched or distinguish between locked and unlocked. Fully electric doors might even support opening and closing the entire door by combining this interface with the "simpleclosable" interface.
{ "actions": [ { "name": "unlatch" } ], "states": [ { "allowedValues": [ "locked", "locking", "unlocked", "unlocking", "unlatched", "unlatching" ], "name": "state", "type": "QString" } ] }
This interface is used for things that can monitor energy consumption/production. This interface is the base for smartmeter things. Actual things will most likely want to use one of the extending interfaces like smartmeterconsumer and/or smartmeterproducer instead.
{}
A smartmeterproducer can monitor total energy consumed by this thing.
{ "extends": "smartmeter", "states": [ { "name": "totalEnergyConsumed", "type": "double" } ] }
See also: smartmeter
A smartmeterproducer can monitor total energy produced by this thing.
{ "extends": "smartmeter", "states": [ { "name": "totalEnergyProduced", "type": "double" } ] }
See also: smartmeter
This interface is used to mark device classes as system-internal. The user interface will likely hide it.
{}
{ "extends": "sensor", "states": [ { "name": "temperature", "type": "double" } ] }
See also: sensor
The thermostat interface describes devices which have a target temperature value and regulate themselves to match that target temperature. Often combined with the power and temperaturesensor interfaces.
{ "states": [ { "name": "targetTemperature", "type": "double", "unit": "DegreeCelsius" } ] }
{ "actions": [ { "name": "addUser", "params": [ { "name": "userId", "type": "QString" } ] }, { "name": "removeUser", "params": [ { "name": "userId", "type": "QString" } ] } ], "events": [ { "name": "accessGranted", "params": [ { "name": "userId", "type": "QString" } ] } ], "extends": "accesscontrol", "states": [ { "name": "users", "type": "QStringList" } ] }
See also: accesscontrol
{ "actions": [ { "name": "increaseVolume", "params": [ { "name": "step", "type": "int" } ] }, { "name": "decreaseVolume", "params": [ { "name": "step", "type": "int" } ] }, { "name": "setMute", "params": [ { "name": "mute", "type": "bool" } ] } ], "extends": "media" }
See also: media
{ "states": [ { "name": "weatherDescription", "type": "QString" }, { "allowedValues": [ "clear-day", "clear-night", "few-clouds-day", "few-clouds-night", "clouds", "overcast", "light-rain", "shower-rain", "thunderstorm", "snow", "fog" ], "name": "weatherCondition", "type": "QString" }, { "name": "temperature", "type": "double" }, { "name": "humidity", "type": "int" }, { "name": "pressure", "type": "double" }, { "name": "windSpeed", "type": "double" }, { "name": "windDirection", "type": "int" } ] }
This interface represents a wind sensor measurment and has the unit [m/s].
{ "extends": "sensor", "states": [ { "name": "windSpeed", "type": "double", "unit": "MeterPerSecond" } ] }
See also: sensor
This interface should be used for device which have the signal strength available. If the signal is to weak, the thing is not connected any more.
{ "extends": "connectable", "states": [ { "defaultValue": 0, "maxValue": 100, "minValue": 0, "name": "signalStrength", "type": "uint", "unit": "Percentage" } ] }
See also: connectable