ImperiHome integration service

This IO service exposes openHAB Items to the Evertygo ImperiHome dashboard app for Android and iOS. It creates a REST service at /imperihome/iss that implements the ImperiHome Standard System API (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 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/, the Local URL would be http://192.168.1.10:8080/imperihome/iss.

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. 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).

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’ve defined your Items in .items files, tags can be added using the

[ "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 a 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

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.

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" }