Interfaces
- accesscontrol
- account
- alert
- awning
- barcodescanner
- battery
- batterylevel
- blind
- button
- closable
- closablesensor
- co2sensor
- colorlight
- colortemperaturelight
- conductivitysensor
- connectable
- daylightsensor
- dimmablelight
- doorbell
- evcharger
- extendedawning
- extendedblind
- extendedclosable
- extendedevcharger
- extendedheating
- extendednavigationpad
- extendedshutter
- extendedsmartmeterconsumer
- extendedsmartmeterproducer
- extendedstatefulgaragedoor
- fingerprintreader
- garagedoor
- garagegate
- gateway
- heating
- humiditysensor
- impulsegaragedoor
- inputtrigger
- irrigation
- light
- lightsensor
- longpressbutton
- longpressmultibutton
- media
- mediacontroller
- mediametadataprovider
- mediaplayer
- moisturesensor
- multibutton
- navigationpad
- noisesensor
- notifications
- outputtrigger
- power
- powersocket
- powerswitch
- presencesensor
- pressuresensor
- sensor
- shutter
- simplebutton
- simpleclosable
- simplegaragedoor
- simplemultibutton
- smartlock
- smartmeter
- smartmeterconsumer
- smartmeterproducer
- statefulgaragedoor
- system
- temperaturesensor
- thermostat
- update
- useraccesscontrol
- venetianblind
- ventilation
- volumecontroller
- weather
- windspeedsensor
- wirelessconnectable
List of all supported interfaces
accesscontrol
{
"events": [
{
"name": "accessGranted"
},
{
"name": "accessDenied"
}
]
}
account
This is used to flag a thing that manages user a user account. It is similar to the gateway interface. For example, if there is a remote API that requires logging in but doesn’t really offer any more functionality than that, this account shall be used. It inherits “connectable” which is used to flag if the remote server is unreachable. In addition, the “loggedIn” state indicates if the login fails. While logged in, the “userDisplayName” state should give the user’s name in a pretty printed form. A client may reconfigure the device then to login again. Such device classes usually will cause auto-devices implementing the actual features as child devices.
{
"extends": "connectable",
"states": [
{
"name": "loggedIn",
"type": "bool"
},
{
"name": "userDisplayName",
"type": "QString"
}
]
}
See also: connectable
alert
Used for things that have some sort of alert. For instance, light bulbs may be able to blink on alert actions, or speaker might be able to play an alert sound. Zigbee devices for example often provide alert actions to identify themselves.
{
"actions": [
{
"name": "alert"
}
]
}
awning
Simple awnings which can be opened and closed. Note that awnings operate inverted compared to other closables.
{
"extends": "closable"
}
See also: closable
barcodescanner
{
"events": [
{
"name": "codeScanned",
"params": [
{
"name": "content",
"type": "QString"
}
]
}
]
}
battery
{
"states": [
{
"name": "batteryCritical",
"type": "bool"
}
]
}
batterylevel
{
"extends": "battery",
"states": [
{
"name": "batteryLevel",
"type": "int",
"minValue": 0,
"maxValue": 100
}
]
}
See also: battery
blind
Simple blinds which can be opened and closed.
{
"extends": "closable"
}
See also: closable
button
The base for all buttons that emit a pressed event.
{
"events": [
{
"name": "pressed"
}
]
}
closable
Interface for generic devices that can be opened and closed. The process of opening or closing can be interrupted by the stop action.
{
"extends": "simpleclosable",
"actions": [
{
"name": "stop"
}
]
}
See also: simpleclosable
closablesensor
This interface can be used for i.e. magnetic window/door sensors
{
"extends": "sensor",
"states": [
{
"name": "closed",
"type": "bool"
}
]
}
See also: sensor
co2sensor
CO2 sensors. Measures co2 in parts per million.
{
"extends": "sensor",
"states": [
{
"name": "co2",
"type": "double",
"unit": "PartsPerMillion"
}
]
}
See also: sensor
colorlight
{
"extends": "colortemperaturelight",
"states": [
{
"name": "color",
"type": "QColor",
"writable": true
}
]
}
See also: colortemperaturelight
colortemperaturelight
{
"extends": "dimmablelight",
"states": [
{
"name": "colorTemperature",
"type": "int",
"minimumValue": "any",
"maximumValue": "any",
"writable": true
}
]
}
See also: dimmablelight
conductivitysensor
{
"extends": "sensor",
"states": [
{
"name": "conductivity",
"type": "double",
"unit": "MicroSiemensPerCentimeter"
}
]
}
See also: sensor
connectable
{
"states": [
{
"name": "connected",
"type": "bool",
"defaultValue": false
}
]
}
daylightsensor
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",
"unit": "UnixTime",
"type": "int"
},
{
"name": "sunsetTime",
"unit": "UnixTime",
"type": "int"
}
]
}
See also: sensor
dimmablelight
{
"extends": "light",
"states": [
{
"name": "brightness",
"type": "int",
"minimumValue": 0,
"maximumValue": 100,
"writable": true
}
]
}
See also: light
doorbell
An interface for doorbells. Emits “doorbellPressed” when the doorbell is pressed.
{
"events": [
{
"name": "doorbellPressed"
}
]
}
evcharger
An EV-charger. Extends the power interface for charging/not charging an electric vehicle.
{
"extends": "power"
}
See also: power
extendedawning
Awnings that support indicating their position and the moving state. Note that awnings operate inverted compared to other closables.
{
"extends": [
"awning",
"extendedclosable"
]
}
See also: awning, extendedclosable
extendedblind
Blinds that support indicating their position and the moving state.
{
"extends": [
"blind",
"extendedclosable"
]
}
See also: blind, extendedclosable
extendedclosable
A more advanced form of devices that support opening and closing in a more fine grained manner. They can report whether the opening/closing is currently in progress and provide a percentage of the opening/closing position. 0% means fully opened, while 100% indicates the device is fully closed
{
"extends": "closable",
"states": [
{
"name": "moving",
"type": "bool"
},
{
"name": "percentage",
"type": "int",
"minimumValue": 0,
"maximumValue": 100,
"writable": true
}
]
}
See also: closable
extendedevcharger
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",
"writable": true,
"unit": "MilliAmpere"
}
]
}
See also: evcharger
extendedheating
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": [
{
"name": "percentage",
"type": "int",
"min": 0,
"max": 100,
"unit": "Percentage",
"writable": true
}
]
}
See also: heating
extendednavigationpad
The extended media interface offers also the info and menu button of media devices.
{
"extends": "navigationpad",
"actions": [
{
"name": "navigate",
"params": [
{
"name": "to",
"type": "QString",
"allowedValues": [
"up",
"down",
"left",
"right",
"enter",
"back",
"menu",
"info",
"home"
]
}
]
}
]
}
See also: navigationpad
extendedshutter
Advanced roller shutters that support indicating their position and the moving state.
{
"extends": [
"shutter",
"extendedclosable"
]
}
See also: shutter, extendedclosable
extendedsmartmeterconsumer
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",
"unit": "Watt"
}
]
}
See also: smartmeterconsumer
extendedsmartmeterproducer
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
extendedstatefulgaragedoor
A garage door which can be controlled like an extended closable, that is, by reporting and taking a percentage of the position
{
"extends": [
"statefulgaragedoor",
"extendedclosable"
]
}
See also: statefulgaragedoor, extendedclosable
fingerprintreader
{
"extends": "useraccesscontrol",
"events": [
{
"name": "accessGranted",
"params": [
{
"name": "userId",
"type": "QString"
},
{
"name": "finger",
"type": "QString",
"allowedValues": [
"ThumbLeft",
"IndexFingerLeft",
"MiddleFingerLeft",
"RingFingerLeft",
"PinkyLeft",
"ThumbRight",
"IndexFingerRight",
"MiddleFingerRight",
"RingFingerRight",
"PinkyRight"
]
}
]
}
],
"actions": [
{
"name": "addUser",
"params": [
{
"name": "userId",
"type": "QString"
},
{
"name": "finger",
"type": "QString",
"allowedValues": [
"ThumbLeft",
"IndexFingerLeft",
"MiddleFingerLeft",
"RingFingerLeft",
"PinkyLeft",
"ThumbRight",
"IndexFingerRight",
"MiddleFingerRight",
"RingFingerRight",
"PinkyRight"
]
}
]
},
{
"name": "removeUser",
"params": [
{
"name": "userId",
"type": "QString"
}
]
}
]
}
See also: useraccesscontrol
garagedoor
The base for all garage door interfaces. Can be used by the client to filter for garage doors in the system.
{}
garagegate
{
"deprecated": "Use statefulgaragedoor instead",
"extends": [
"garagedoor",
"closable"
],
"states": [
{
"name": "state",
"type": "QString",
"allowedValues": [
"open",
"closed",
"opening",
"closing"
]
},
{
"name": "intermediatePosition",
"type": "bool"
}
]
}
See also: garagedoor, closable
gateway
The gateway interface is used for gateway devices like bridges to other networks. For instance Ethernet to Zigbee bridges, Ethernet to RF bridges or similar. Typically such device classes implement the actual functionality in child devices that will auto-appear after successful connection to the gateway/bridge.
{
"extends": "connectable"
}
See also: connectable
heating
The heating interface defines basic heating appliances.
{
"extends": "power"
}
See also: power
humiditysensor
{
"extends": "sensor",
"states": [
{
"name": "humidity",
"type": "double",
"minValue": 0,
"maxValue": 100
}
]
}
See also: sensor
impulsegaragedoor
This interface is for the simplest form of garage doors which can be controlled only via an impulse. Triggering the impulse will start moving the door, triggering it again will stop the movement. Triggering it yet another time will start movement in the reverse direction. Note that there is no feedback channel on such devices. The system has no chance of knowing the current state this device is actually in.
{
"extends": "garagedoor",
"actions": [
{
"name": "triggerImpulse"
}
]
}
See also: garagedoor
inputtrigger
{
"events": [
{
"name": "triggered"
}
]
}
irrigation
The irrigation interface is used for irrigation systems. It is used for water pumps or valves that supply any sort of irrigation. The power state turns irrigation on and off.
{
"extends": "power"
}
See also: power
light
{
"extends": "power"
}
See also: power
lightsensor
{
"extends": "sensor",
"states": [
{
"name": "lightIntensity",
"type": "double",
"unit": "Lux"
}
]
}
See also: sensor
longpressbutton
A button that emits different events, pressed and longpressed, depending on how long the user presses it. Note that the button should only emit one of them at a time. I.e. don’t emit pressed on botton down and later longPressed if the user keeps on holding the button. Such a longpress should only emit longPressed. Common practice is to emit pressed if a release event is received before a timeout expires, else emit longpress when the timeout expires.
{
"extends": "button",
"events": [
{
"name": "longPressed"
}
]
}
See also: button
longpressmultibutton
A remote control with multiple buttons that can distinguish between short and long presses. Note that the button should only emit one of them at a time. I.e. don’t emit pressed on botton down and later longPressed if the user keeps on holding the button. Such a longpress should only emit longPressed. Common practice is to emit pressed if a release event is received before a timeout expires, else emit longpress when the timeout expires.
{
"extends": "simplemultibutton",
"events": [
{
"name": "longPressed",
"params": [
{
"name": "buttonName",
"type": "QString"
}
]
}
]
}
See also: simplemultibutton
media
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.
{}
mediacontroller
The mediacontroller interface contains actions to control media streams.
{
"extends": "media",
"states": [
{
"name": "shuffle",
"type": "bool",
"writable": true,
"optional": true
},
{
"name": "repeat",
"type": "QString",
"allowedValues": [
"None",
"One",
"All"
],
"writable": true,
"optional": true
},
{
"name": "like",
"type": "bool",
"writable": true,
"optional": true
},
{
"name": "equalizerPreset",
"type": "QString",
"allowedValues": "any",
"writable": true,
"optional": true
},
{
"name": "nightMode",
"type": "bool",
"writable": true,
"optional": true
}
],
"actions": [
{
"name": "skipBack"
},
{
"name": "stop"
},
{
"name": "play"
},
{
"name": "pause"
},
{
"name": "skipNext"
},
{
"name": "fastForward",
"optional": true
},
{
"name": "fastRewind",
"optional": true
}
]
}
See also: media
mediametadataprovider
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
mediaplayer
Media player interface. Used by devices/services which can play back media. Even if a device only supports e.g. audio, the playerType state must still be added to the metadata. It may default to a single value and never change in this case. Players supporting duration and play time should provide those values in seconds.
{
"extends": "media",
"states": [
{
"name": "playbackStatus",
"type": "QString",
"allowedValues": [
"Playing",
"Paused",
"Stopped"
]
},
{
"name": "playerType",
"type": "QString",
"allowedValues": [
"audio",
"video"
]
},
{
"name": "inputSource",
"type": "QString",
"allowedValues": "any",
"writable": true,
"optional": true
},
{
"name": "playDuration",
"type": "uint",
"unit": "Seconds",
"optional": true
},
{
"name": "playTime",
"type": "uint",
"unit": "Seconds",
"optional": true
}
]
}
See also: media
moisturesensor
{
"extends": "sensor",
"states": [
{
"name": "moisture",
"type": "double"
}
]
}
See also: sensor
multibutton
A remote control with multiple buttons. Emits pressed(buttonName) on button presses.
{
"extends": "button",
"events": [
{
"name": "pressed",
"params": [
{
"name": "buttonName",
"type": "QString"
}
]
}
]
}
See also: button
navigationpad
Many media devices have a navigation pad for browsing a library or a menu. This interface represents a basic navigation pad.
{
"extends": "media",
"actions": [
{
"name": "navigate",
"params": [
{
"name": "to",
"type": "QString",
"allowedValues": [
"up",
"down",
"left",
"right",
"enter",
"back"
]
}
]
}
]
}
See also: media
noisesensor
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
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
}
]
}
powersocket
The powersocket interface is used for smart power sockets and just extends the simple power interface.
{
"extends": "power"
}
See also: power
powerswitch
The powerswitch interface is used for smart power switches and just extends the simple button interface. Use this for switches that can be on or off.
{
"extends": "button",
"states": [
{
"name": "power",
"type": "bool"
}
]
}
See also: button
presencesensor
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
pressuresensor
{
"extends": "sensor",
"states": [
{
"name": "pressure",
"type": "double",
"unit": "MilliBar"
}
]
}
See also: sensor
sensor
{}
shutter
Simple roller shutters which can be opened and closed.
{
"extends": "closable"
}
See also: closable
simplebutton
Deprecated - Use button instead.
{
"extends": "button"
}
See also: button
simpleclosable
Interface for very basic devices that support opening and closing.
{
"actions": [
{
"name": "open"
},
{
"name": "close"
}
]
}
simplegaragedoor
A Garage door that can take up and down as commands but cannot provide state information
{
"extends": [
"garagedoor",
"closable"
]
}
See also: garagedoor, closable
simplemultibutton
Deprecated - Use multibutton instead
{
"extends": "multibutton"
}
See also: multibutton
smartlock
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.
{
"states": [
{
"name": "state",
"type": "QString",
"allowedValues": [
"locked",
"locking",
"unlocked",
"unlocking",
"unlatched",
"unlatching"
]
}
],
"actions": [
{
"name": "unlatch"
}
]
}
smartmeter
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.
{}
smartmeterconsumer
A smartmeterproducer can monitor total energy consumed by this thing.
{
"extends": "smartmeter",
"states": [
{
"name": "totalEnergyConsumed",
"type": "double",
"unit": "KiloWattHour"
}
]
}
See also: smartmeter
smartmeterproducer
A smartmeterproducer can monitor total energy produced by this thing.
{
"extends": "smartmeter",
"states": [
{
"name": "totalEnergyProduced",
"type": "double"
}
]
}
See also: smartmeter
statefulgaragedoor
A garagedoor which can be controller like a closable, with open and close actions. It can report whether it’s opened or closed or standing still something in between (intermediate position) as well as reporting that it’s moving (opening/closing).
{
"extends": [
"garagedoor",
"closable"
],
"states": [
{
"name": "state",
"type": "QString",
"allowedValues": [
"open",
"closed",
"opening",
"closing",
"intermediate"
]
}
]
}
See also: garagedoor, closable
system
This interface is used to mark device classes as system-internal. The user interface will likely hide it.
{}
temperaturesensor
{
"extends": "sensor",
"states": [
{
"name": "temperature",
"type": "double",
"unit": "DegreeCelsius"
}
]
}
See also: sensor
thermostat
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",
"minValue": "any",
"maxValue": "any"
}
]
}
update
The update interface is used for things that support being updated by nymea.
{
"states": [
{
"name": "updateStatus",
"type": "QString",
"allowedValues": [
"idle",
"available",
"updating"
]
},
{
"name": "currentVersion",
"type": "QString"
},
{
"name": "availableVersion",
"type": "QString",
"optional": true
}
],
"actions": [
{
"name": "performUpdate"
}
]
}
useraccesscontrol
{
"extends": "accesscontrol",
"states": [
{
"name": "users",
"type": "QStringList"
}
],
"events": [
{
"name": "accessGranted",
"params": [
{
"name": "userId",
"type": "QString"
}
]
}
],
"actions": [
{
"name": "addUser",
"params": [
{
"name": "userId",
"type": "QString"
}
]
},
{
"name": "removeUser",
"params": [
{
"name": "userId",
"type": "QString"
}
]
}
]
}
See also: accesscontrol
venetianblind
Venetian blinds that can be tilted. Venetian blinds must support an angle and specify the minimum and maximum supported angle. For instance, if a venetian blinds supports tilting from horizontal to vertical by 90°, the minValue should be set to 0° and the maxValue to 90°. For venetian blinds that support tilting both direction, that is, a total of 180°, the minValue should be -90° and the maxValue should be 90°. 0° is always the horizontal position. Note that the “moving” state should be true when either the percentage or the angle are moving.
{
"extends": "extendedblind",
"states": [
{
"name": "angle",
"type": "int",
"unit": "Degree",
"minValue": "any",
"maxValue": "any",
"writable": true
}
]
}
See also: extendedblind
ventilation
The ventilation interface is used for any sort of ventilation. It extends the “power” interface and thus can be turned on or off.
{
"extends": "power"
}
See also: power
volumecontroller
{
"desciption": "A volume controller allows to control volume and mute. At the very least, increaseVolume and decreaseVolume are to be implemented for devices that don't have a way to fetch the current volume. For devices allowing to set an absolute volume value, the volume and mute states should be implemented as well.",
"extends": "media",
"states": [
{
"name": "mute",
"type": "bool",
"writable": true,
"optional": true
},
{
"name": "volume",
"type": "int",
"minValue": "any",
"maxValue": "any",
"writable": true,
"optional": true
}
],
"actions": [
{
"name": "increaseVolume"
},
{
"name": "decreaseVolume"
}
]
}
See also: media
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"
}
]
}
windspeedsensor
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
wirelessconnectable
Interface for wireless connectable devices. If reporting the signal strength is supported, the optional signalStrength state should be implemented.
{
"extends": "connectable",
"states": [
{
"name": "signalStrength",
"type": "uint",
"unit": "Percentage",
"minValue": 0,
"maxValue": 100,
"optional": true
}
]
}
See also: connectable