Interfaces

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

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