Objects from type state
need their common.role
property set to one of the roles defined in the list below.
The Role information is a very important information and allows Visualization- and Smart-Assistant adapters
to detect the function of the object and also how/if they relate to other objects in the same channel, device or folder.
Example: A RGB Lamp can have thw following three objects (or more) with different roles that belong together:
switch
- (On/Off)level.color.rgb
with #RRGGBB color code of the lamplevel.brightness
with the brightness value
Different Device templates used for the detecting with the required and optional objects and their roles can be found in the Type-detector repository.
state
- very common purpose. If you don't know which role the state has, use this one.text
common.type = string
text.url
common.type = string
state val contains an url for usage in an anchor, iframe or imghtml
common.type = string
json
common.type = string
list
common.type = array
date
common.type = string
- parsable bynew Date(ddd)
stringdate
common.type = number
-epoch seconds * 1000
common.type=boolean, common.write=false
sensor.window
- window opened-true
or closed-false
sensor.door
- door opened-true
or closed-false
sensor.alarm
- some common alarmsensor.alarm.flood
- water leakagesensor.alarm.fire
- fire sensorsensor.alarm.secure
- door opened, window opened or motion detected during alarm is ON.sensor.alarm.power
- No power (voltage = 0
)sensor.light
- feedback from lamp, that it is ONsensor.lock
- actual position of locksensor.motion
- motion sensorsensor.rain
- rain detectedsensor.noise
- noise detected
common.type=boolean, common.write=true, common.read=false
button
button.long
button.stop
- e.g. rollo stop,button.stop.tilt
button.start
button.resume
button.open.door
button.open.window
button.open.blind
button.open.tilt
button.close.blind
button.close.tilt
button.mode.
*button.mode.auto
button.mode.manual
button.mode.silent
common.type=boolean, common.write=false, common.read=true
button
- the difference, thatcommon.write=false
. Please avoid this role and usebutton.press
orbutton.long
.button.long
button.press
common.type=number, common.write=false
value
value.window
(common.states={"0": "CLOSED", "1": "TILTED", "2": "OPEN"}
) It is important to have (CLOSED/TILTED/OPEN
). Values can differ.value.temperature
(common.unit='°C' or '°F' or 'K'
)value.humidity
value.co2
- CO2 (unit: ppm)value.brightness
- luminance level (unit: lux, )value.min
value.max
value.default
value.battery
- battery levelvalue.valve
- valve levelvalue.time
- getTime() of Date() objectvalue.interval
(common.unit='sec') - Interval in seconds (can be 0.1 or less)value.date (common.type=string) - Date in form 2015.01.01 (without time)value.datetime (common.type=string) - Date and time in system formatvalue.gps.longitude
- gps longitude coordinatesvalue.gps.latitude
- gps latitudevalue.gps.elevation
- gps elevationvalue.gps
- longitude and latitude together like '5.56;43.45'value.gps.accuracy
- accuracy of current gps measurementvalue.gps.radius
- radius of current gps measurementvalue.power.consumption
- energy consumption (unit=Wh or KWh)value.power.production
- energy production (unit=Wh or KWh)value.energy
- energy (unit=Wh, kWh or m3 for gasoline)value.energy.active
- active energy (unit=Ws, Wh, kWh)value.energy.reactive
- reactive energy (unit=vars, kVarh)value.energy.consumed
- energy consumed (unit=Ws, Wh, kWh)value.energy.produced
- power produced (unit=Ws, Wh or kWh)value.power
- energy power (unit=W or kW)value.power.active
- active power (unit=W, kW)value.power.reactive
- reactive power (unit=var, kVar)value.power.consumed
- power consumed (unit=W or kW)value.power.produced
- power produced (unit=W or kW)value.direction
- (common.type=numberor string, indicates up/down, left/right, 4-way switches, wind-direction, ... )value.curtain
- actual position of curtainvalue.blind
- actual position of blind (max = fully open, min = fully closed
)value.tilt
- actual tilt position (max = fully open, min = fully closed
)value.lock
- actual position of lockvalue.speed
- wind speedvalue.pressure
- (unit: mbar)value.distance
value.distance.visibility
value.severity
- some severity (states can be provided), Higher is more importantvalue.warning
- some warning (states can be provided), Higher is more importantvalue.sun.elevation
- sun elevation in °value.sun.azimuth
- sun azimuth in °value.voltage
- Voltage in Volt,unit=V
value.current
- Current in Ampere,unit=A
value.frequency
- Frequency in Hz,unit=Hz
value.fill
- Fill level,unit=l,ml,m3,%
value.blood.sugar
- Blood sugar value,unit=mmol,mgdl
common.type=boolean, common.write=false
The difference of Indicators from Sensors is that indicators will be shown as small icon. Sensors as a real value. So the indicator may not be alone in the channel. It must be some other main state inside channel.
indicator
indicator.working
- indicates that the target systems is executing something, like blinds or lock opening.indicator.reachable
- If device is onlineindicator.connected
- used only for instances. Useindicator.reachable
for devicesindicator.maintenance
- indicates system warnings/errors, alarms, service messages, battery empty or stuff like thatindicator.maintenance.lowbat
indicator.maintenance.unreach
indicator.maintenance.alarm
indicator.lowbat
- true if low batteryindicator.alarm
- same as indicator.maintenance.alarmindicator.alarm.fire
- fire detectedindicator.alarm.flood
- flood detectedindicator.alarm.secure
- door or window is openedindicator.alarm.health
- health problem
With levels, you can control or set some number value.
common.type=number, common.write=true
level
level.humidity
- humidity as a setpoint, i.e. for humifiers / climatecontrolslevel.battery
- battery target voltage / capacity i.e.for loadinglevel.battery.min
- battery minimum voltage / capacitylevel.battery.max
- battery maximum voltage / capacitylevel.valve
- opening value for valveslevel.pressure
-level.pressure.min
- minimum air or oil pressure value allowedlevel.pressure.max
- maximum air or oil pressure value allowedlevel.voltage
- target voltage for generatorslevel.voltage.min
- minimum voltage for generatorslevel.voltage.max
- maximum voltage for generatorslevel.current
- target current for i.e. loading battery deviceslevel.current.min
- minimum current for i.e. loading battery deviceslevel.current.max
- maximum current for i.e. loading battery deviceslevel.frequency
- target frequency for generatorslevel.frequency.min
- minimum frequency for generators or for power grid alarmslevel.frequency.max
- maximum frequency for generators or for power grid alarmslevel.fill
- setpoint for any container fill level stateslevel.brightness
- luminance level (unit: lux, )level.min
- minimum level allowedlevel.max
- maximum level allowedlevel.default
- default levellevel.dimmer
- brightness is dimmer toolevel.blind
- set blind position (max = fully open, min = fully closed)level.temperature
- set desired temperaturelevel.valve
- set point for valve positionlevel.color.red
level.color.green
level.color.blue
level.color.white
- rgbWlevel.color.hue
- color in °0-360; 0=red, 120=green, 240=blue, 360=red(cyclic)
level.color.saturation
level.color.rgb
- hex color like#rrggbb
(common.type=string
)level.color.rgbw
- hex color like#rrggbbww
(common.type=string
)level.color.cie
- cie color in form[x, y]
(`common.type=string)level.color.luminance
level.color.temperature
- color temperature in K°2200 warm-white, 6500° cold white
level.timer
level.timer.sleep
- sleep timer. 0 - off, or in minutes- ...
level.volume
- (min=0, max=100
) - sound volume, but min, max can differ. min < maxlevel.volume.group
- (min=0, max=100
) - sound volume, for the group of deviceslevel.curtain
- set the curtain positionlevel.tilt
- set the tilt position of blinds (max = fully open, min = fully closed)level.speed
- speed eg. fan, ventilator, ..
Switch controls boolean device (true = ON, false = OFF
)
common.type=boolean, common.write=true
switch
switch.lock
- lock (true - open lock, false - close lock
)switch.lock.door
- door lockswitch.lock.window
- window lockswitch.mode.boost
- start/stop boost mode of thermostatswitch.mode.party
- start/stop party mode of thermostatswitch.power
- on/off power, thermostat or air conditionerswitch.light
switch.comfort
- comfort modeswitch.enable
switch.mode.
*switch.mode.auto
- auto mode on/offswitch.mode.manual
- manual mode on/offswitch.mode.silent
- silent mode on/offswitch.mode.moonlight
- moon light mode on/offswitch.mode.color
- color mode on/offswitch.gate
- closes(false) or opens(true) the gate
level.mode.fan
-AUTO, HIGH, LOW, MEDIUM, QUIET, TURBO
level.mode.swing
-AUTO, HORIZONTAL, STATIONARY, VERTICAL
level.mode.airconditioner
- air conditioner:AUTO, COOL, DRY, ECO, FAN_ONLY, HEAT, OFF
, heating thermostat:AUTO, MANUAL, VACATION
,level.mode.thermostat
- thermostat:AUTO, MANUAL, VACATION
, Additionally to these states normally thelevel.temperature
andswitch.power
required to map the air conditioner.
TODO: Think about ionization`and oscillation.
level.mode.cleanup
- Enumeration ofAUTO, ECO, EXPRESS, NORMAL, QUIET
. OnlyAUTO
andNORMAL
are required.level.mode.work
- Enumeration ofAUTO, FAST, MEDIUM, SLOW, TURBO
. Optional state.value.water
- 0-100% water level.value.waste
- 0-100% waste bin level. (0% - empty, 100% - full)indicator.maintenance.waste
- Waste bin is fool.value.state
-HOME, CLEANING, PAUSE
and so on.
Additionally, to these states normally the switch.power
required to map the vacuum cleaner. switch.power
in this case works as: true
- clean, false
- back to home.
Optionally value.battery
and
switch.gate
- closes(false) or opens(true) the gate (required)value.position
- position of the gate in percent (100% opened, 0% - closed)value.gate
- same asvalue.position
button.stop
- stop motion of gate
Special roles for media players
button.stop
button.play
button.next
button.prev
button.pause
switch.pause
button.forward
button.reverse
button.fastforward
button.fastreverse
button.volume.up
button.volume.down
media.seek
- (common.type=number
) %media.mode.shuffle
- (common.type=number
) 0 - none, 1 - all, 2 - onemedia.mode.repeat
- (common.type=boolean
)media.state
-['play','stop','pause']
or[0 - pause, 1 - play, 2 - stop]
or[true - playing/false - pause]
media.artist
media.album
media.title
media.title.next
media.cover
- cover urlmedia.cover.big
- big cover urlmedia.cover.small
- tiny cover urlmedia.duration.text
- e.g "2:35"media.duration
- (common.type=number
) secondsmedia.elapsed.text
- e.g "1:30"media.elapsed
- (common.type=number
) secondsmedia.broadcastDate
- (common.type=string
) Broadcast datemedia.mute
- (common.type=boolean
) true is mutedmedia.season
- (common.type=string
) season number (important the type is really "string" to be able to indicate absence of season with "")media.episode
- (common.type=string
) episode number (important the type is really "string" to be able to indicate absence of episode with "")media.mute.group
- (common.type=boolean
) mute of group of devicesmedia.tts
- text to speechmedia.bitrate
- kbpsmedia.genre
- genre songmedia.date
- year songmedia.track
- (common.type=string
) current play track id[0 - ~]
(important the type is reallystring
to be able to indicate absence of track with "")media.playid
- media player track idmedia.add
- add current playlistmedia.clear
- clear current playlist (write-only)media.playlist
- json array likemedia.url
- url to play or current urlmedia.url.announcement
- URL to play announcementmedia.jump
- Number of items to jump in the playlist (it can be negative)media.content
- Type of media being played such as audio/mp3media.link
- State with the current filemedia.input
- number or string of input (AUX, AV, TV, SAT, ...)level.bass
- Bass levellevel.treble
- Treble levelswitch.power.zone
- power zone
[
{
"artist": "",
"album": "",
"bitrate":0,
"title": "",
"file": "",
"genre": "",
"year": 0,
"len": "00:00",
"rating": "",
"cover": ""
}
]
media.browser
- json array like "files"
[
{
"fanart": "",
"file": "",//smb://192.168.1.10/music/AtlantidaProject/
"filetype": "", //directory
"label": "",
"lastmodified": "",
"mimetype": "",
"size": 0,
"thumbnail": "",
"title": "",
"type": "",
"lastmodified": "2016-02-27 16:05:46",
"time": "88",
"track": "01",
"date": "2005",
"artist": "yonderboy (H)",
"album": "splendid isolation",
"genre": "Trip-Hop"
}
]
-
value.temperature
- Actual temperature -
value.temperature.windchill
- Actual wind chill -
value.temperature.dewpoint
- Actual dew-point -
value.temperature.feelslike
- Actual temperature "feels like" -
value.temperature.min
- Minimal temperature in last 24h -
value.temperature.max
- Maximal temperature in last 24h -
value.humidity
- actual or average humidity -
value.humidity.min
- actual humidity -
value.humidity.max
- actual humidity -
value.speed.wind
- actual or average wind speed -
value.speed.max.wind
- maximal wind speed in last 24h -
value.speed.min.wind
- minimal wind speed in last 24h -
value.speed.wind.gust
- actual wind gust speed -
value.direction.wind
- actual or average wind direction in degrees -
value.direction.max.wind
- actual wind direction in degrees -
value.direction.min.wind
- actual wind direction in degrees -
weather.direction.wind
- actual or average wind direction as text, e.g. NNW -
date
- actual date or date of last read information -
date.sunrise
- Sunrise for today -
date.sunset
- Sunset for today -
dayofweek
- day of week as text -
location
- Text description of location (e.g. address) -
weather.icon
- Actual state icon URL for now -
weather.icon.wind
- Actual wind icon URL for now -
weather.icon.name
- Actual state icon name for now -
weather.state
- Actual weather description -
value.precipitation
- (type: number, unit: mm
) precipitation for last 24 hours rain/snow (Niederschlag heute für Schnee oder Regen / осадки сегодня снега или дождя) -
value.precipitation.hour
- Actual precipitation level in last hour -
value.precipitation.today
- Actual precipitation level for today (till 0:00) -
value.precipitation.chance
- Actual precipitation chance for today -
value.precipitation.type
- Actual precipitation type for today. (type: number
) States: 0 - NO, 1 - RAIN, 2 - SNOW, 3 - HAIL -
value.radiation
- Actual sun radiation level -
value.uv
- Actual UV level -
value.clouds
- Clouds on the sky. 0% - no clouds, 100% - many clouds. -
value.rain
- Actual rain level in last 24 hours -
value.rain.hour
- Actual rain level in last hour -
value.rain.today
- Actual rain level for today (till 0:00) -
value.snow
- Actual snow level in last 24 hours -
value.snow.hour
- Actual snow level in last hour -
value.snow.today
- Actual snow level for today (till 0:00) -
value.snowline
- Actual snow line in meters -
weather.chart.url
- URL to chart for weather history -
weather.chart.url.forecast
- URL to chart for weather forecast -
weather.html
- HTML object with weather description -
weather.title
- Very short description -
weather.title.short
- Very, very short description (One word) -
weather.type
- Type of weather information -
weather.json
- JSON object with specific data -
value.speed.wind.forecast.0
- wind speed forecast for today -
weather.state.forecast.0
- Weather description for today -
value.direction.wind.forecast.0
- wind direction forecast for today in degrees -
weather.direction.wind.forecast.0
- wind direction forecast for today as text -
value.pressure.forecast.0
- forecast for pressure for today -
value.temperature.min.forecast.0
- Min temperature forecast for today -
value.temperature.max.forecast.0
- Max temperature forecast for today -
value.precipitation.forecast.0
- (type: number, unit: %
) Forecast of precipitation chance for today -
value.precipitation.forecast.0
- (type: number, unit: mm
) Forecast of precipitation level for today -
weather.title.forecast.0
- Very short description for tomorrow -
value.precipitation.day.forecast.0
- Forecast for precipitation for daytime -
value.precipitation.night.forecast.0
- Forecast for precipitation for nighttime -
date.forecast.1
- tomorrow date -
weather.icon.forecast.1
- tomorrow icon -
weather.state.forecast.1
- tomorrow weather state -
value.temperature.min.forecast.1
-
value.temperature.max.forecast.1
-
value.precipitation.forecast.1
- (type: number, unit: %
) Forecast of precipitation chance for tomorrow -
value.precipitation.forecast.1
- (type: number, unit: mm
) Forecast of precipitation level for tomorrow -
value.direction.wind.forecast.1
-
value.speed.wind.forecast.1
-
value.pressure.forecast.1
info.ip
- ip of deviceinfo.mac
- mac of deviceinfo.name
- name of deviceinfo.address
- some other address (e.g. KNX)info.serial
- serial numberinfo.firmware
- firmware versioninfo.hardware
- hardware versioninfo.port
- tcp portinfo.standby
- true if device in standby modeinfo.status
- status of deviceinfo.display
- information shown on device displaydate.start
- string or numberdate.end
- string or number
common.type=number, common.read=true, common.write=false
value.health.fat
- body fat index in %value.health.weight
- body weight in kg, lbsvalue.health.bmi
- bmi indexvalue.health.calories
- burned caloriesvalue.health.steps
- steps donevalue.health.bpm
- heart beats per minute
-
url
-
url.icon
- icon (additionally every object can havecommon.icon
) -
url.cam
- web camera url -
url.blank
- open URL in new window -
url.same
- open URL in this window -
url.audio
- URL for audio file -
text.phone
- phone number -
time.span
- time difference in ms (common.type=number), i.e. time since last update, duration of operation, time until next try, ... -
time.interval
- intervall value in ms (common.type=number), i.e. some polling interval -
time.timeout
- timeout value in ms (common.type=number), i.e. timeouts for communication requests -
chart
- JSON array with chart data, like[{ts: 1678575600000, val: 1}, {ts: 1678579200000, val: 2}]
-
adapter.messagebox
(common.type=object, common.write=true
) used to send messages to email, pushover and other adapters -
adapter.wakeup
(common.type=boolean, common.write=true
) wake up adapter from suspended mode