This page is part of archived documentation for openHAB 2.5. Go to the current stable version
# ImperiHome integration service
This IO service exposes openHAB Items to the Evertygo ImperiHome (opens new window) dashboard app for Android and iOS. It creates a REST service at /imperihome/iss that implements the ImperiHome Standard System API (opens new window) (ISS).
# Installation
The ImperiHome integration service can be installed through the Paper UI. Navigate to Add-ons > Misc and click Install.
# Configuration
# openHAB Add-on
To configure the ImperiHome integration add-on in openHAB, create a imperihome.cfg file in the conf/services directory. The following configuration options can be used:
System ID
The ImperiHome integration service identifies itself to ImperiHome using a system ID. By default the unique identifier of your openHAB installation is used. To override the ID, use the system.id (opens new window) configuration option.
system.id=my-openhab-123
Warning: the system ID can not contain the underscore character (_).
Root URL
Root URL of your openHAB installation. Should point to the openHAB welcome page This option is currently only required when using the custom icon tag.
openhab.rootUrl=http://myserver.example.org:7070/
# ImperiHome
ImperiHome must be configured to connect to your openHAB instance.
Start ImperiHome, open the menu and go to My Systems. Add a new system (+) and choose 'ImperiHome Standard System' as the object type. Now enter the URL to your openHAB instance as Local URL, followed by /imperihome/iss. For example, if your openHAB instance is running at http://192.168.1.10:8080/ (opens new window), the Local URL would be http://192.168.1.10:8080/imperihome/iss (opens new window).
If you have port forwarding or similar set up to access your openHAB from the internet, you can also fill the Remote URL in the same way. For example: http://my-openhab-url.dyndns.org:8080/imperihome/iss (opens new window). Warning: this service provides no authentication mechanism, so anyone could use the API to control your system when accessible from the internet. Add a secure proxy or use the openHAB Cloud proxy to protect your system (more information (opens new window)).
Click Next to let ImperiHome validate the URL. After validation succeeded the system is added and you can continue to configure your Items for use in ImperiHome.
# Device Tagging
This service uses Item tags to determine how to expose your Items to ImperiHome. All tags are formatted like this:
iss:<tagtype>:<value>
For example:
iss:room:Kitchen
If you have defined your Items in .items files, tags can be added using:
[ "mytag" ]
syntax (after the (Groups) and before the {channel}). If you created your items another way, e.g. using the Paper UI, HABmin allows you to modify the tags.
# Tag: type
Specifies the device type to expose to ImperiHome. Take a look at Device types below for the supported device types and how to configure them. If no type is specified, this service will try to auto-detect the type from the Item, based on supported value types (OnOff for a switch, HSB for color light) and Item name.
Required: no
Default: auto-detect
Example:
iss:type:DevSwitch
# Tag: room
Specifies the room the device will show up in in ImperiHome.
Required: no
Default: 'No Room'
Example:
iss:room:Kitchen
# Tag: label
Sets the device label in ImperiHome. If no label is specified, the Item label is used if available. Otherwise the Item name will be used.
Required: no
Default: Item label or name
Example:
iss:label:Kitchen light
# Tag: mapping
Sets the mapping for an ImperiHome MultiSwitch device, just like an openHAB sitemap mapping does. In the example below, 'All off', 'Relax' and 'Reading' will be visible in ImperiHome. Clicking one of the options will send a 0, 1 or 2 value command to the openHAB item.
Required: only for MultiSwitch device
Default: none
Example:
iss:mapping:0=All off,1=Relax,2=Reading
# Tag: link
Links two devices together, using the value from the linked device as an additional value in the device containing the link tag. See Device links for details.
Required: no
Default: none
Example:
iss:link:energy:Kitchen_Current_Consumption
# Tag: unit
Sets the unit for devices with a numeric value, such as DevTemperature and DevGenericSensor. The unit is only used to tell ImperiHome what to display; no conversion is performed.
Required: no
Default: none
Example:
iss:unit:°C
# Tag: invert
Inverts the state of on/off devices such as switches and dimmers.
Required: no
Default: false
Example:
iss:invert:true
# Tag: icon
Sets a custom icon to be shown in ImperiHome. You can use all icon names that are also available for use in your sitemaps, including custom icons. To use this tag you must set the openHAB root URL in your configuration.
Required: no
Default: none
Example:
iss:icon:sofa
# Device types
The following table lists the ImperiHome API device types that you can use in a iss:type tag. Not all device types are currently supported. For those that are supported, the Item types you can use them on are listed.
| Device | Description | Supported | Item types | Link types |
|---|---|---|---|---|
| DevCamera | MJPEG IP Camera | No | - | |
| DevCO2 | CO2 sensor | Yes | Number | - |
| DevCO2Alert | CO2 Alert sensor | Yes | Contact, Number, String(1), Switch | - |
| DevDimmer | Dimmable light | Yes | Dimmer, Number | energy |
| DevDoor | Door / window security sensor | Yes | Contact, Number, String(1), Switch | - |
| DevElectricity | Electricity consumption sensor | Yes | Number | kwh, watt |
| DevFlood | Flood security sensor | Yes | Contact, Number, String(1), Switch | - |
| DevGenericSensor | Generic sensor (any value) | Yes | Number, String | - |
| DevHygrometry | Hygro sensor | Yes | Number | - |
| DevLock | Door lock | Yes | Contact, Switch | - |
| DevLuminosity | Luminance sensor | Yes | Number | - |
| DevMotion | Motion security sensor | Yes | Contact, Number, String(1), Switch | - |
| DevMultiSwitch | Multiple choice actuator | Yes | Number | - |
| DevNoise | Noise sensor | Yes | Number | - |
| DevPlayer | Audio/Video player | No | - | |
| DevPlaylist | Audio/Video playlist | No | - | |
| DevPressure | Pressure sensor | Yes | Number | - |
| DevRain | Rain sensor | Yes | Number | accum |
| DevRGBLight | RGB(W) Light (dimmable) | Yes | Color | energy |
| DevScene | Scene (launchable) | Yes | Switch, Number | - |
| DevShutter | Shutter actuator | Yes | Dimmer, Number | - |
| DevSmoke | Smoke security sensor | Yes | Contact, Number, String(1), Switch | - |
| DevSwitch | Standard on/off switch | Yes | Switch | energy |
| DevTemperature | Temperature sensor | Yes | Number | - |
| DevTempHygro | Temperature and Hygrometry combined sensor | Yes | Number | hygro, temp |
| DevThermostat | Thermostat (2) | Yes | Number | curmode, curtemp |
| DevUV | UV sensor | Yes | Number | - |
| DevWind | Wind sensor | Yes | Number | direction |
(1) When using a String Item for trippable devices, any non-empty value other than 'ok' will set the device to tripped. This makes it compatible with the Nest Protect binding.
(2) Thermostat devices require additional tags. See Thermostat for details.
# Device links
Some devices can be linked to another device. This allows you to create combined devices reporting multiple values, or reporting the energy consumption with a switch device.
The link tag refers to the name of the Item it should link to. The item must be an ImperiHome device itself, so it must have at least one iss tag.
# Switch energy consumption
ImperiHome allows you to show the current energy consumption for a DevDimmer, DevRGBLight and DevSwitch. This example links the MyLightEnergy Number Item to the MyLight Switch Item, so the DevSwitch device will also report the energy consumption value to ImperiHome:
Switch MyLight "My Light" ["iss:type:DevSwitch", "iss:link:energy:MyLight_Energy"] { channel="zwave:device:1:node14:switch_binary1" }
Number MyLightEnergy "My Light Usage [%.1f W]" ["iss:type:DevElectricity"] { channel="zwave:device:1:node14:meter_watts1" }
# Total energy consumption
The DevElectricity devices main value is the current consumption in Watts. To add the total consumption in KWh, link your electricity device to a generic sensor device containing the total energy consumption value:
Number MyLight_Energy "My Light Usage [%.1f W]" ["iss:type:DevElectricity", "iss:link:kwh:MyLight_Total_Energy"] { channel="zwave:device:1:node14:meter_watts1" }
Number MyLight_Total_Energy "My Light Total usage [%.1f KWh]" ["iss:type:DevGenericSensor", "iss:unit:KWh"] { channel="zwave:device:1:node14:sensor_power1" }
# TempHygro
ImperiHome recognizes the special DevTempHygro device, combining a temperature and hydrometry sensor. You can create such a device by linking either from a temperature Item to a hygro Item:
Number MyTemp "Temperature [%.1f °C]" ["iss:type:DevTempHygro", "iss:link:hygro:MyHum"] { channel="zwave:device:1:node8:sensor_temperature" }
Number MyHum "Humidity [%d%%]" ["iss:type:DevHygrometry"] { channel="zwave:device:1:node8:sensor_relhumidity" }
or vise versa:
Number MyTemp "Temperature [%.1f °C]" ["iss:type:DevTemperature"] { channel="zwave:device:1:node8:sensor_temperature" }
Number MyHum "Humidity [%d%%]" ["iss:type:DevTempHygro", "iss:link:temp:MyTemp"] { channel="zwave:device:1:node8:sensor_relhumidity" }
# Rain accumulation
The DevRain devices main value is the current instant rain value (default in mm per hour). To add the total rain accumulation value, link your rain device to a generic sensor device:
Number RainCurrent "Rain current [%.1f mm/h]" ["iss:type:DevRain", "iss:link:accum:RainAccumulation"] { channel="..." }
Number RainAccumulation "Rain accumulation [%.1f mm]" ["iss:type:DevGenericSensor", "iss:unit:mm"] { channel="..." }
# Wind direction
The DevWind devices main value is the current wind speed (default in km per hour). To add the wind direction value (default in degrees), link your wind device to a generic sensor device:
Number WindSpeed "Wind speed [%.1f km/h]" ["iss:type:DevWind", "iss:link:direction:WindDirection"] { channel="..." }
Number WindDirection "Wind direction [%d deg]" ["iss:type:DevGenericSensor", "iss:unit:deg"] { channel="..." }
# Thermostat
The DevThermostat combines a setpoint, current temperature and mode in one ImperiHome device. To accomplish this using openHAB items, it uses a curtemp and curmode link and a few additional tags.
Number Thermos_Setpoint "Thermostat" ["iss:room:Test", "iss:type:DevThermostat", "iss:step:0.5", "iss:minVal:15", "iss:maxVal:24", "iss:modes:Home,Away,Comfort,Sleeping", "iss:link:curmode:Thermos_Mode", "iss:link:curtemp:Thermos_Temp"] { channel="..." }
Number Thermos_Temp "Thermos temp" ["iss:room:Test", "iss:type:DevTemperature", "iss:unit:K"] { channel="..." }
String Thermos_Mode "Thermos mode" ["iss:room:Test", "iss:type:DevGenericSensor"] { channel="..." }
The main DevThermostat device must be the Item holding the setpoint. Using tags, this device specifies the minimum and maximum setpoint value, the setpoint step and the available modes. The two links specify what Items contain the current temperature and current mode. If you want to use a custom unit, set the unit tag on the current temperature device.
# Shutter stopper
The DevShutter device of ImperiHome support a 'stop' action. To use this, link a Switch item to your shutter item, like so:
Dimmer MyShutter "Shutter" ["iss:room:Test", "iss:type:DevShutter", "iss:link:stopper:MyShutterStop"] { channel="..." }
Switch MyShutterStop "Stop shutter" ["iss:room:Test", "iss:type:DevSwitch"] { channel="..." }
Implement a Rule listening for the ON command on the switch to handle the stop action yourself.
# Items example
Color LVR_Billy "Billy" <colorlight> (Lights) ["iss:room:Living room", "iss:type:DevRGBLight"] { channel="hue:0210:001122334455:bulb1:color" }
Switch LVR_TallLamp "Tall lamp" (Lights) ["iss:room:Living room", "iss:type:DevSwitch", "iss:invert:true"] { channel="zwave:device:1:node3:switch_binary" }
Dimmer LVR_DinnerTable "Dinner table" (Lights) ["iss:room:Living room", "iss:type:DevDimmer"] { channel="zwave:device:1:node13:switch_dimmer" }
Number ENT_Entrance_Current "Entrance usage [%.1f W]" (Wattage) ["iss:room:Entrance", "iss:type:DevElectricity", "iss:unit:Watt"] { channel="zwave:device:1:node14:meter_watts1" }
Number ENT_Temperature "Entrance temperature [%.1f °C]" (Temperature) ["iss:room:Entrance", "iss:type:DevTempHygro", "iss:link:hygro:ENT_Humidity"] { channel="zwave:device:1:node8:sensor_temperature" }
Number ENT_Luminance "Entrance light [%d lm]" (Luminance) ["iss:room:Entrance", "iss:type:DevLuminosity", "iss:unit:lux"] { channel="zwave:device:1:node8:sensor_luminance" }
Number ENT_Humidity "Entrance humidity [%d%%]" (Humidity) ["iss:room:Entrance", "iss:type:DevHygrometry"] { channel="zwave:device:1:node8:sensor_relhumidity" }