-
-
Notifications
You must be signed in to change notification settings - Fork 1.7k
MiOS Binding
Documentation for the MiOS Bridge Binding.
This binding exposes read, and read-command, access to Devices controlled by a MiOS Home Automation controller, such as those seen at http://getvera.com.
It exposes the ability to do the following things in the MiOS HA Controller
-
Devices
- Read State Variables & Device Attributes, and invoke (single parameter) UPnP Commands to control the Device. -
Scenes
- Read the current execution state of a Scene, and invoke those Scenes within the remote HA Controller -
System
- Read System-level Attributes. It uses the remote control interfaces (aka "UI Simple" JSON Calls, and HTTP Long-polling) of the MiOS HA Controller to keep the bound openHAB Items in sync with their counterparts in the MiOS HA Controller.
The binding uses the openHAB Transformation Service extensively to "map" the Data & Commands between the two systems. A set of example MAP transform files is provided and these can readily be augmented without needing to tweak the code.
Original code was used from the XBMC Binding, and then heavily modified. Snippets included from the HTTP Binding for the various datatype mapping functions.
- 1.6 - First release
- 1.8 - Extend the MiOS Item Generator for the common use-cases.
- MiOS Unit configuration
- Transformations
- Logging/Logger
- Item configuration (Reading)
-
Item Commands (Reacting)
- [MiOS - Device Binding - Commands (Reacting)] (MiOS-Binding#item--mios-device-binding---commands-reacting)
- [Device Command Binding Examples (Parameterless)] (MiOS-Binding#device-command-binding-examples-parameterless)
- A Switch ...
- An Armed Sensor ...
- [A Lock ...] (MiOS-Binding#a-lock)
-
Device Command Binding Examples (Parameterized)
- A Dimmer, Volume Control, Speed controlled Fan ...
- [A Thermostat ...] (MiOS-Binding#a-thermostat)
- [Device Command Binding Examples (Parameterless)] (MiOS-Binding#device-command-binding-examples-parameterless)
- [MiOS Scene Binding - Commands (Reacting)] (MiOS-Binding#item--mios-scene-binding---commands-reacting)
- [Scene Command Binding Examples] (MiOS-Binding#scene-command-binding-examples)
- [MiOS - Device Binding - Commands (Reacting)] (MiOS-Binding#item--mios-device-binding---commands-reacting)
In order for the MiOS openHAB Binding to talk to your MiOS Unit, it needs configuration indicating where it lives. This information is specified within the openhab.cfg
file.
Each MiOS Unit is identified by a Unit name, which is user-supplied. This name will be used throughout the subsequent setup steps, and permits you to connect to more than one MiOS Unit that you might have within your environment.
The binding will only talk you MiOS Units living on the same LAN as your MiOS Unit and/or are directly reachable from your LAN where openHAB is running.
The MiOS gateway services, such as http://cp.mios.com
and http://home.getvera.com
, are not supported.
🚨🔧 The simplest configuration entry for openhab.cfg
contains a Unit name, house
, and a hostname, 192.168.1.22
, to use for the MiOS Unit connection:
mios:house.host=192.168.1.22
If you have local DNS setup correctly, then use this form instead:
mios:house.host=ha.myhouse.example.com
Optionally, you can specify the port
and timeout
to use. These default to 3480
and 60000
(ms) respectively. These have reasonable defaults, so you shouldn't need to make adjustments.
mios:house.host=ha.myhouse.example.com
mios:house.port=3480
mios:house.timeout=30000
You can also declare multiple MiOS Units, as illustrated in this example.
mios:houseUpstairs.host=ha-upstairs.myhouse.example.com
mios:houseDownstairs.host=ha-downstairs.myhouse.example.com
🔦 The MiOS Unit name is case-sensitive, and may only contain AlphaNumeric characters. The leading character must be an [ASCII] alpha.
Internally, the MiOS Binding uses the openHAB Transformation Service. The MiOS Binding supplies a number of pre-configured MAP Transformation for the common use-cases.
🚨🔧 These transformations must be copied from the source-code repository:
features/openhab-addons-external/src/main/resources/transform/mios*.map
and placed into your openHAB installation under the directory:
{openHAB Home}/configurations/transform/
If you have a Unix machine, the MAP files can also be downloaded using:
sudo apt-get install subversion
svn checkout https://github.com/openhab/openhab/trunk/features/openhab-addons-external/src/main/resources/transform/
🔦 These transformations can be readily extended by the user, for any use-cases that aren't covered by those pre-configured & shipped with the Binding.
During setup of the binding, log information can provide you valuable information. By default openHAB will log diagnostic information, from all installed bindings, into a single log file (openhab.log
).
Through custom configuration, as an advanced configuration, you can separate out where specific bindings log their diagnostic information.
There are two configuration files to configure the log subsystem of openHAB:
configurations/logback.xml
-
configurations/logback_debug.xml
(if you start in debug mode)
If you need to obtain TRACE level diagnostics, the following can be added to your logback configuration file.
Any MiOS Binding Trace output will be intermingled with your regular openHAB logs:
...
<logger name="org.openhab.binding.mios" level="TRACE" />
...
To simplify analysis and to keep things structured you can also configure a dedicated logfile.
<!-- log appender to be used for MIOS binding -->
<appender
name = "MIOSFILE"
class = "ch.qos.logback.core.rolling.RollingFileAppender">
<!-- target file -->
<file>logs/mios.log</file>
<!-- settings how to archive old logs and how long to rentain them [days] -->
<rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>logs/mios-%d{yyyy-ww}.log.zip</fileNamePattern>
<maxHistory>7</maxHistory>
</rollingPolicy>
<!-- encoder rule (how to format the messages in the log file ) -->
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%-5level] [%-30.30logger{36}] - %msg%n</pattern>
</encoder>
</appender>
Next we configure the actual logger:
<!-- valid log levels: OFF | ERROR | INFO | DEBUG | TRACE -->
<logger
name = "org.openhab.binding.mios"
level = "TRACE"
additivity = "FALSE">
<appender-ref ref="MIOSFILE" />
</logger>
Below how it should look if the configuration is correct (TRACE):
...
2015-01-18 16:37:18.971 [DEBUG] [.o.b.mios.internal.MiosBinding] - internalPropertyUpdate: BOUND {mios="unit:vera,device:1/service/urn:micasaverde-com:serviceId:ZWaveNetwork1/Role"}, value=Master SIS:NO PRI:YES, bound 1 time(s)
2015-01-18 16:37:18.971 [TRACE] [.o.b.mios.internal.MiosBinding] - internalPropertyUpdate: NOT BOUND {mios="unit:vera,device:1/service/urn:micasaverde-com:serviceId:ZWaveNetwork1/LastDongleBackup"}, value=2015-01-14T23:30:57
2015-01-18 16:37:18.971 [TRACE] [.o.b.mios.internal.MiosBinding] - internalPropertyUpdate: NOT BOUND {mios="unit:vera,device:1/service/urn:micasaverde-com:serviceId:ZWaveNetwork1/LastError"}, value=Poll failed
2015-01-18 16:37:18.971 [TRACE] [.o.b.mios.internal.MiosBinding] - internalPropertyUpdate: NOT BOUND {mios="unit:vera,device:1/service/urn:micasaverde-com:serviceId:ZWaveNetwork1/LastHeal"}, value=2015-01-14T05:16:26
2015-01-18 16:37:18.971 [TRACE] [.o.b.mios.internal.MiosBinding] - internalPropertyUpdate: NOT BOUND {mios="unit:vera,device:1/service/urn:micasaverde-com:serviceId:ZWaveNetwork1/LastRouteFailure"}, value=2015-01-14T04:11:33
...
The MiOS Binding provides a few sources of data from the target MiOS Unit. These can be categorized into the following data values:
- MiOS Device UPnP State Variables
- MiOS Device Attributes
- MiOS Scene Attributes
- MiOS System Attributes
The examples below illustrates the form of each.
The general form of these bindings is:
mios="unit:<unitName>,<miosThing>{,command:<commandTransform>}{,in:<inTransform>}{,out:<outTransform>}"
In many cases, only a subset of these parameters need to be specified/used, with internal defaults applied for the common use-cases.
The sections below describe the types of things that can be bound, in addition to the transformations that are permitted, and any default transformations that may be applied for you.
🚨🔧The MiOS Item Generator is a free-standing tool that generates an initial openHAB Items file for a MiOS Unit.
After the initial generation the openHAB Items file can be customized, or can be regenerated, as Devices are added/removed from the MiOS Unit.
🔦 The Item Generator examples use a MiOS Unit name of "house
". This name must match the MiOS Unit name declared in the MiOS Unit configuration.
Any name can be used, as long as they're in sync across the configuration files.
Device Bindings can be read-only, with data flowing from the MiOS Unit into openHAB. Device Bindings have the form:
mios="unit:<unitName>,device:<deviceId>/service/<serviceURN>/<serviceVariable>
or
mios="unit:<unitName>,device:<deviceId>/service/<serviceAlias>/<serviceVariable>
With examples like:
Number MiOSMemoryUsed "Used [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/urn:cd-jackson-com:serviceId:SystemMonitor/memoryUsed"}
Number MiOSMemoryAvailable "Available [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/urn:cd-jackson-com:serviceId:SystemMonitor/memoryAvailable"}
Number MiOSMemoryCached "Cached [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/urn:cd-jackson-com:serviceId:SystemMonitor/memoryCached"}
Number MiOSMemoryBuffers "Buffers [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/urn:cd-jackson-com:serviceId:SystemMonitor/memoryBuffers"}
String MiOSCMHLastRebootLinux "Reboot [%s]" (BindingDemo) {mios="unit:house,device:382/service/urn:cd-jackson-com:serviceId:SystemMonitor/cmhLastRebootTime"}
String MiOSMemoryUsedString "Memory Used [%s KB]" (BindingDemo) {mios="unit:house,device:382/service/urn:cd-jackson-com:serviceId:SystemMonitor/memoryUsed"}
or, since we've internally Alias'd the UPnP Service Id that Chris used, you can also use:
Number MiOSMemoryUsed "Used [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/SystemMonitor/memoryUsed"}
Number MiOSMemoryAvailable "Available [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/SystemMonitor/memoryAvailable"}
Number MiOSMemoryCached "Cached [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/SystemMonitor/memoryCached"}
Number MiOSMemoryBuffers "Buffers [%.0f KB]" (BindingDemo) {mios="unit:house,device:382/service/SystemMonitor/memoryBuffers"}
String MiOSCMHLastRebootLinux "Reboot [%s]" (BindingDemo) {mios="unit:house,device:382/service/SystemMonitor/cmhLastRebootTime"}
String MiOSMemoryUsedString "Memory Used [%s KB]" (BindingDemo) {mios="unit:house,device:382/service/SystemMonitor/memoryUsed"}
Or you can replace the Weather information, from the openHAB demo.items
file, with contents from the Weather Underground (WUI) Plugin from MiOS:
Number Weather_Temperature "Outside Temperature [%.1f °F]" <temperature> (Weather_Chart) {mios="unit:house,device:318/service/TemperatureSensor1/CurrentTemperature"}
or, you can track the status of a Light Switch or perhaps a Dimmer:
Number HallLightAsSwitch "On/Off [%1d]" (BindingDemo) {mios="unit:house,device:11/service/SwitchPower1/Status"}
Number HallLightAsDimmer "Level [%3d]" (BindingDemo) {mios="unit:house,device:11/service/Dimming1/LoadLevelStatus"}
The serviceAliases are built into the MiOS Binding and may be expanded over time, as feedback is received. Each Alias is case-sensitive, and there can be multiple Aliases for a single UPnP ServiceId:
Core UPnP Service Id | Aliases |
---|---|
urn:upnp-org:serviceId:SwitchPower1 |
SwitchPower1 , Switch
|
urn:upnp-org:serviceId:Dimming1 |
Dimming1 ,Dimming ,Dimmer
|
urn:upnp-org:serviceId:TemperatureSensor1 |
TemperatureSensor1 ,Temperature
|
urn:upnp-org:serviceId:HVAC_FanOperatingMode1 |
HVAC_FanOperatingMode1 ,HVACFan
|
urn:upnp-org:serviceId:HVAC_UserOperatingMode1 |
HVAC_UserOperatingMode1 ,HVACUser
|
urn:upnp-org:serviceId:TemperatureSetpoint1_Heat |
TemperatureSetpoint1_Heat ,Heat
|
urn:upnp-org:serviceId:TemperatureSetpoint1_Cool |
TemperatureSetpoint1_Cool ,Cool
|
urn:upnp-org:serviceId:AVTransport |
AVTransport |
urn:upnp-org:serviceId:RenderingControl |
RenderingControl |
urn:upnp-org:serviceId:DeviceProperties |
DeviceProperties |
urn:upnp-org:serviceId:HouseStatus1 |
HouseStatus1 ,HouseStatus
|
urn:upnp-org:serviceId:ContentDirectory |
ContentDirectory |
urn:upnp-org:serviceId:AudioIn |
AudioIn |
urn:upnp-org:serviceId:ZoneGroupTopology |
ZoneGroupTopology |
MiCasaVerde UPnP Service Id | Aliases |
---|---|
urn:micasaverde-com:serviceId:ZWaveDevice1 |
ZWaveDevice1 ,ZWaveDevice
|
urn:micasaverde-com:serviceId:ZWaveNetwork1 |
ZWaveNetwork1 ,ZWaveNetwork
|
urn:micasaverde-com:serviceId:HaDevice1 |
HaDevice1 ,HaDevice
|
urn:micasaverde-com:serviceId:SceneControllerLED1 |
SceneControllerLED1 ,SceneControllerLED
|
urn:micasaverde-com:serviceId:SecuritySensor1 |
SecuritySensor1 ,Security
|
urn:micasaverde-com:serviceId:HumiditySensor1 |
HumiditySensor1 ,Humidity
|
urn:micasaverde-com:serviceId:EnergyMetering1 |
EnergyMetering1 ,EnergyMeter
|
urn:micasaverde-com:serviceId:SceneController1 |
SceneController1 ,SceneController
|
urn:micasaverde-com:serviceId:HVAC_OperatingState1 |
HVAC_OperatingState1 ,HVACState
|
urn:micasaverde-org:serviceId:SerialPort1 |
SerialPort1 ,Serial
|
urn:micasaverde-com:serviceId:DoorLock1 |
DoorLock1 ,DoorLock
|
urn:micasaverde-com:serviceId:AlarmPartition2 |
AlarmPartition2 ,Alarm
|
urn:micasaverde-com:serviceId:Camera1 |
Camera1 ,Camera
|
urn:micasaverde-com:serviceId:MiosUpdater1 |
MiosUpdater1 ,MiosUpdater
|
urn:micasaverde-com:serviceId:HouseModes1 |
HouseModes1 ,HouseModes
|
Plugin-specific UPnP Service Id | Aliases |
---|---|
urn:cd-jackson-com:serviceId:SystemMonitor |
SystemMonitor |
urn:cd-jackson-com:serviceId:Config |
CDJConfig |
urn:garrettwp-com:serviceId:WPSwitch1 |
WPSwitch1 ,WPSwitch
|
urn:watou-com:serviceId:Nest1 |
Nest1 ,Nest
|
urn:watou-com:serviceId:NestStructure1 |
NestStructure1 ,NestStructure
|
urn:upnp-micasaverde-com:serviceId:Weather1 |
Weather1 ,Weather
|
urn:demo-ted-striker:serviceId:PingSensor1 |
PingSensor1 ,PingSensor
|
urn:micasaverde-com:serviceId:Sonos1 |
Sonos1 ,Sonos
|
urn:demo-paradox-com:serviceId:ParadoxSecurityEVO1 |
ParadoxSecurityEVO1 ,Paradox
|
urn:macrho-com:serviceId:LiftMasterOpener1 |
LiftMasterOpener1 ,LiftMaster
|
urn:directv-com:serviceId:DVR1 |
DirecTVDVR1 ,DirecTV
|
urn:futzle-com:serviceId:UPnPProxy1 |
UPnPProxy1 ,UPnPProxy
|
urn:rfxcom-com:serviceId:rfxtrx1 |
RfxtrxNew |
upnp-rfxcom-com:serviceId:rfxtrx1 |
Rfxtrx |
urn:upnp-arduino-cc:serviceId:arduinonode1 |
ArduinoNode1 ,ArduinoNode
|
urn:upnp-arduino-cc:serviceId:arduino1 |
Arduino1 ,Arduino
|
urn:akbooer-com:serviceId:DataYours1 |
DataYours1 ,DataYours
|
urn:richardgreen:serviceId:VeraAlert1 |
VeraAlert1 ,VeraAlert
|
urn:upnp-org:serviceId:VSwitch1 |
VSwitch1 ,VSwitch
|
Scene Bindings are read-only, with data flowing from the MiOS Unit into openHAB. Scene Bindings have the form:
mios="unit:<unitName>,scene:<sceneId>/<attributeName>
With examples like:
Number SceneGarageOpenId (GScene) {mios="unit:house,scene:109/id"}
Number SceneGarageOpenStatus (GScene) {mios="unit:house,scene:109/status"}
String SceneGarageOpenActive (GScene) {mios="unit:house,scene:109/active"}
System Bindings are read-only, with data flowing from the MiOS Unit into openHAB. System Bindings have the form:
mios="unit:<unitName>,system:/<attributeName>
With examples like:
Number SystemZWaveStatus "[%d]" (GSystem) {mios="unit:house,system:/ZWaveStatus"}
String SystemLocalTime "[%s]" (GSystem) {mios="unit:house,system:/LocalTime"}
String SystemTimeStamp "[%s]" (GSystem) {mios="unit:house,system:/TimeStamp"}
String SystemUserDataDataVersion "[%s]" (GSystem) {mios="unit:house,system:/UserData_DataVersion"}
Number SystemDataVersion "[%d]" (GSystem) {mios="unit:house,system:/DataVersion"}
String SystemLoadTime "[%s]" (GSystem) {mios="unit:house,system:/LoadTime"}
Sometimes the value presented by the binding isn't in the format that you require for your Item. For these cases, the binding provides access to the standard openHAB Transformation Service.
To utilize the Transformation Service, you need to declare additional settings on your bindings.
These take the form of the in:
and out:
declarations at the end of the binding. The in:
declaration is used when values are received from the MiOS Unit, but before it places the value into openHAB. The out:
declaration is used when values are taken from the openHAB system for delivered to the MiOS Unit (in Command execution, for example).
mios="unit:<unitName>,<miosThing>{,in:<inTransform>}{,out:<outTransform>}"
As you can see by the above declaration, the input and output transformations are optional. If they aren't declared, then an internal, automated, transformation will be attempted based upon the Type of the Item being bound and, in some cases, the type of MiOS Attribute and/or State Variable involved in the binding.
With examples like:
String SystemZWaveStatusString "ZWave Status String [%d]" (GSystem) {mios="unit:house,system:/ZWaveStatus,in:MAP(miosZWaveStatusIn.map)"}
Contact LivingRoomZoneTripped "Living Room (Zone 2) [%s]" <contact> (GContact,GWindow,GPersist) {mios="unit:house,device:117/service/SecuritySensor1/Tripped,in:MAP(miosContactIn.map)"}
and a map transform file like configurations/transform/miosZWaveStatusIn.map
:
1=Cool Bananas
0=In the Dog house
-=Your guess is as good as mine!
and a map transform file like configurations/transform/miosSwitchIn.map
:
1=OPEN
0=CLOSED
Then as data flows from the MiOS system, data for these items will be transformed into the new [String] format for display and/or rule purposes.
To ease the setup process, the common MiOS entities have internal defaults for these parameters. This aids in keeping the binding string simple for typical use-case scenarios. The defaults are as follows:
For Devices, the defaults are as follows:
State Variable / Attribute | Default Parameters |
---|---|
service/urn:micasaverde-com:serviceId:DoorLock1/Status |
command:MAP(miosLockCommand.map) in:MAP(miosSwitchIn.map) out:MAP(miosSwitchOut.map)
|
service/urn:watou-com:serviceId:Nest1/status |
in:MAP(miosContactIn.map) out:MAP(miosContactOut.map)
|
service/urn:upnp-org:serviceId:RenderingControl/Mute |
command:MAP(miosUPnPRenderingControlMuteCommand.map) in:MAP(miosSwitchIn.map) out:MAP(miosSwitchOut.map)
|
service/urn:micasaverde-com:serviceId:SecuritySensor1/Armed |
command:MAP(miosArmedCommand.map) in:MAP(miosSwitchIn.map) out:MAP(miosSwitchOut.map)
|
service/urn:micasaverde-com:serviceId:SecuritySensor1/Tripped |
in:MAP(miosContactIn.map) out:MAP(miosContactOut.map)
|
service/urn:upnp-org:serviceId:SwitchPower1/Status |
command:ON/OFF in:MAP(miosSwitchIn.map) out:MAP(miosSwitchOut.map)
|
service/urn:upnp-org:serviceId:Dimming1/LoadLevelStatus |
command:MAP(miosDimmerCommand.map) |
service/urn:upnp-org:serviceId:TemperatureSetpoint1_Heat/CurrentSetpoint |
command:MAP(miosTStatSetpointHeatCommand.map) |
service/urn:upnp-org:serviceId:TemperatureSetpoint1_Cool/CurrentSetpoint |
command:MAP(miosTStatSetpointCoolCommand.map) |
service/urn:upnp-org:serviceId:HVAC_UserOperatingMode1/ModeStatus |
command:MAP(miosTStatModeStatusCommand.map) |
service/urn:upnp-org:serviceId:HVAC_FanOperatingMode1/Mode |
command:MAP(miosTStatFanOperatingModeCommand.map) |
service/urn:upnp-org:serviceId:RenderingControl/Volume |
command:MAP(miosUPnPRenderingControlVolumeCommand.map) |
service/urn:upnp-org:serviceId:AVTransport/TransportState |
command:MAP(miosUPnPTransportStatePlayModeCommand.map) |
status |
in:MAP(miosStatusIn.map) |
For Scenes, they look like:
State Variable / Attribute | Default Parameters |
---|---|
active |
in:MAP(miosSceneActiveIn.map) |
status |
command: in:MAP(miosStatusIn.map)
|
For users wanting more advanced configurations, the openHAB Transformation Service provides a number of other transforms that may be of interest:
-
JS(example.js)
- run the Javascript to perform the conversion. -
MAP (example.map)
- Transform using the static, file-based, conversion. -
XSLT(example.xslt)
- Transform using an XSLT transformation. -
EXEC(...)
- Transform using the OS-level script. -
REGEX(...)
- Transform using the supplied Regular Expression and use Capture markers(
and)
around the value to be extracted. -
XPATH(...)
- Transform using the supplied XPath Expression.
More reading on these is available in the openHAB Wiki.
By default, openHAB will send Commands to the Controls that have been outlined in the associated configurations/sitemaps/*.sitemap
file. The Commands sent depend upon the type of Control that's been bound to the Item.
Through observation, the following commands are commonly sent:
- Switch -
ON
,OFF
(When Bound to a Switch Item) - Switch -
TOGGLE
(When Bound to a Contact Item) - Switch -
ON
(Whenautoupdate="false"
is also present in the binding list) - Slider -
INCREASE
,DECREASE
, <PCTNumber>
MiOS Units don't natively handle these Commands so a mapping step must occur before openHAB Commands can be executed by a MiOS Unit. Additionally, since MiOS Bindings are read-only by default, we must add a parameter to indicate we want data to flow back to the MiOS Unit.
The command:
Binding parameter is used to specify that we want data to flow back to the MiOS unit as well as how to perform the required mapping. For most Items bound using the MiOS Binding, internal defaults will take care of the correct command:
, in:
and out:
parameters. These need only be specified if you have something not handled by the internal defaults, or wish to override them with custom behavior.
For MiOS Devices, this parameter can take one of several forms:
mios="unit:<unitName>,device:<deviceId>/service/<UPnPVariable>,command:{<CommandMap>}"
With definitions as:
<CommandMap> is <blank> OR;
<CommandMap> is <InlineCommandMap> OR;
<CommandMap> is <openHABTransform> (
<TransformParams> )
<InlineCommandMap> is <openHABCommandMap> { |
<openHABCommandMap> }*
<openHABCommandMap> is <openHABCommand> { =
<UPnPAction> }
<openHABCommand> is ON
, OFF
, INCREASE
, DECREASE
, etc or the special value _defaultCommand
<UPnPAction> is <ServiceName> /
<ServiceAction> (
{ <ServiceParam> { =
<ServiceValue> | =
<BoundValue>} } )
OR;
<UPnPAction> is <ServiceAlias> /
<ServiceAction> (
{ <ServiceParam> { =
<ServiceValue> | =
<BoundValue>} } )
<UPnPVariable> is <ServiceName> /
<ServiceVariable> OR;
<UPnPVariable> is <ServiceAlias> /
<ServiceVariable>
<openHABTransform> is MAP
, XSLT
, EXEC
, XPATH
, etc
<BoundValue> is ?
, ??
, ?++
, ?--
In practice, when discrete commands are being sent by openHAB, the map is fairly simple. In the examples listed below, the *.map
files are provided and can be downloaded per the Transformations setup descriptions.
You might start off with an inline definition of the mapping:
Switch FamilyTheatreLightsStatus "Family Theatre Lights" (GSwitch) {mios="unit:house,device:13/service/SwitchPower1/Status,command:ON=SwitchPower1/SetTarget(newTargetValue=1)|OFF=SwitchPower1/SetTarget(newTargetValue=0),in:MAP(miosSwitchIn.map)"}
And then reduce it to the internal default map, but specify that you only want to handle ON
and OFF
Commands:
Switch FamilyTheatreLightsStatus "Family Theatre Lights" (GSwitch) {mios="unit:house,device:13/service/SwitchPower1/Status,command:ON|OFF,in:MAP(miosSwitchIn.map)"}
or, more simply, use the internal defaults altogether:
Switch FamilyTheatreLightsStatus "Family Theatre Lights" (GSwitch) {mios="unit:house,device:13/service/SwitchPower1/Status"}
The simple version, using internal defaults for the SecuritySensor1/Armed
service state of the Device:
Switch LivingRoomZoneArmed "Zone Armed [%s]" {mios="unit:house,device:117/service/SecuritySensor1/Armed"}
or the fully spelled out version:
Switch LivingRoomZoneArmed "Zone Armed [%s]" {mios="unit:house,device:117/service/SecuritySensor1/Armed,command:MAP(miosArmedCommand.map),in:MAP(miosSwitchIn.map)"}
The simple version, using internal defaults for the DoorLock1/Status
service state of the Device:
Switch GarageDeadboltDStatus "Garage Deadbolt" (GLock,GSwitch) {mios="unit:house,device:189/service/DoorLock1/Status"}
or the full version:
Switch GarageDeadboltDStatus "Garage Deadbolt" (GLock,GSwitch) {mios="unit:house,device:189/service/DoorLock1/Status,command:MAP(miosLockCommand.map),in:MAP(miosSwitchIn.map)"}
For some Commands, in order to pass this information to the remote MiOS Unit, we need to know either the current value of the Item, or we need to know the current value of the Command.
To do this, we introduce the <BoundValue> parameter that, when present in the mapped-command, will be expanded prior to being sent to the MiOS Unit:
-
?++
- Item Value + 10 -
?--
- Item Value - 10 -
?
- Item Value -
??
- Command Value
Additionally, since <PCTNumber> is just a value, it won't match any of the entries in our Mapping file, so we introduce a magic key _defaultCommand
. We first attempt to do a literal mapping and, if that doesn't find a match, we go look for this magic key and use it's entry.
The simple version, using internal defaults for the Dimming1/LoadLevelStatus
service state of the Device:
Dimmer MasterCeilingFanLoadLevelStatus "Master Ceiling Fan [%d]%" <slider> (GDimmer) {mios="unit:house,device:101/service/Dimming1/LoadLevelStatus"}
or the full version:
Dimmer MasterCeilingFanLoadLevelStatus "Master Ceiling Fan [%d]%" <slider> (GDimmer) {mios="unit:house,device:101/service/Dimming1/LoadLevelStatus,command:MAP(miosDimmerCommand.map)"}
Since Dimmer Items in openHAB can be sent INCREASE
, DECREASE
or <PCTNumber> as the command, the mapping file must account for both the static commands (INCREASE
, DECREASE
) as well as the possibility of a Command Value being sent.
The miosDimmerCommand.map
file has a definition that handles this situation:
INCREASE=urn:upnp-org:serviceId:Dimming1/SetLoadLevelTarget(newLoadlevelTarget=?++)
DECREASE=urn:upnp-org:serviceId:Dimming1/SetLoadLevelTarget(newLoadlevelTarget=?--)
_defaultCommand=urn:upnp-org:serviceId:Dimming1/SetLoadLevelTarget(newLoadlevelTarget=??)
A Thermostat is composed of a number of pieces. Each piece must be first bound to openHAB Items, and then a number of mappings must be put in place.
Since all the components of a Thermostat have reasonable internal defaults, we'll use the simpler form for our Item definitions in openHAB:
/* Thermostat Upstairs */
Number ThermostatUpstairsId "ID [%d]" {mios="unit:house,device:335/id"}
String ThermostatUpstairsDeviceStatus "Device Status [%s]" (GThermostatUpstairs) {mios="unit:house,device:335/status"}
Number ThermostatUpstairsCurrentTemperature "Upstairs Temperature [%.1f °F]" <temperature> (GThermostatUpstairs, GTemperature) {mios="unit:house,device:335/service/TemperatureSensor1/CurrentTemperature"}
Number ThermostatUpstairsHeatCurrentSetpoint "Heat Setpoint [%.1f °F]" <temperature> (GThermostatUpstairs) {mios="unit:house,device:335/service/TemperatureSetpoint1_Heat/CurrentSetpoint"}
Number ThermostatUpstairsCoolCurrentSetpoint "Cool Setpoint [%.1f °F]" <temperature> (GThermostatUpstairs) {mios="unit:house,device:335/service/TemperatureSetpoint1_Cool/CurrentSetpoint"}
String ThermostatUpstairsFanMode "Fan Mode" (GThermostatUpstairs) {mios="unit:house,device:335/service/HVAC_FanOperatingMode1/Mode"}
String ThermostatUpstairsFanStatus "Fan Status [%s]" (GThermostatUpstairs) {mios="unit:house,device:335/service/HVAC_FanOperatingMode1/FanStatus"}
String ThermostatUpstairsModeStatus "Mode Status" (GThermostatUpstairs) {mios="unit:house,device:335/service/HVAC_UserOperatingMode1/ModeStatus"}
String ThermostatUpstairsModeState "Mode State [%s]" (GThermostatUpstairs) {mios="unit:house,device:335/service/HVAC_OperatingState1/ModeState"}
Number ThermostatUpstairsBatteryLevel "Battery Level [%d] %" (GThermostatUpstairs) {mios="unit:house,device:335/service/HaDevice1/BatteryLevel"}
DateTime ThermostatUpstairsBatteryDate "Battery Date [%1$ta, %1$tm/%1$te %1$tR]" <calendar> (GThermostatUpstairs) {mios="unit:house,device:335/service/HaDevice1/BatteryDate"}
DateTime ThermostatUpstairsLastUpdate "Last Update [%1$ta, %1$tm/%1$te %1$tR]" <calendar> (GThermostatUpstairs) {mios="unit:house,device:335/service/HaDevice1/LastUpdate"}
and these need to be paired with similar items in the *.sitemap
file:
Text item=ThermostatUpstairsCurrentTemperature {
Text item=ThermostatHumidityUpstairsCurrentLevel
Setpoint item=ThermostatUpstairsHeatCurrentSetpoint minValue=40 maxValue=80
Setpoint item=ThermostatUpstairsCoolCurrentSetpoint minValue=40 maxValue=80
Switch item=ThermostatUpstairsFanMode mappings=[ContinuousOn="On", Auto="Auto"]
Text item=ThermostatUpstairsFanStatus
Switch item=ThermostatUpstairsModeStatus mappings=[HeatOn="Heat", CoolOn="Cool", AutoChangeOver="Auto", Off="Off"]
Text item=ThermostatUpstairsModeState
Text item=ThermostatUpstairsBatteryLevel
Text item=ThermostatUpstairsBatteryDate
}
MiOS Scenes are parameterless. They can only be requested to execute, and they provide status updates as attribute values during their execution (status
) or if they're currently active (active
).
For MiOS Scenes, the command:
parameter has a simpler form:
mios="unit:<unitName>,scene:<sceneId>{/<SceneAttribute>},command:{<CommandMap>}{,in:<inTransform>}"
With definitions as:
<CommandList> is <blank> OR;
<CommandList> is <openHABCommand> { |
<openHABCommand> }*
<openHABCommand> is ON
, OFF
, INCREASE
, DECREASE
, TOGGLE
etc
<SceneAttribute> is status
| active
In general Scenes tend to look like:
String SceneMasterClosetLights "Master Closet Lights Scene" <sofa> (GScene) {mios="unit:house,scene:109/status, autoupdate="false"}
Or if you want the Scene executed upon receipt of ON
or TOGGLE
Commands:
String SceneMasterClosetLights "Master Closet Lights Scene" <sofa> (GScene) {mios="unit:house,scene:109/status,command:ON|TOGGLE", autoupdate="false"}
🔦 Here we've added an additional configuration to the binding declaration, autoupdate="false"
, to ensure the Switch no longer has the ON
and OFF
States automatically managed. In openHAB, this declaration ensures that the UI rendition appears like a Button.
ℹ Please find all documentation for openHAB 2 under http://docs.openhab.org.
The wiki pages here contain (outdated) documentation for the older openHAB 1.x version. Please be aware that a lot of core details changed with openHAB 2.0 and this wiki as well as all tutorials found for openHAB 1.x might be misleading. Check http://docs.openhab.org for more details and consult the community forum for all remaining questions.
- Classic UI
- iOS Client
- Android Client
- Windows Phone Client
- GreenT UI
- CometVisu
- Kodi
- Chrome Extension
- Alfred Workflow
- Cosm Persistence
- db4o Persistence
- Amazon DynamoDB Persistence
- Exec Persistence
- Google Calendar Presence Simulator
- InfluxDB Persistence
- JDBC Persistence
- JPA Persistence
- Logging Persistence
- mapdb Persistence
- MongoDB Persistence
- MQTT Persistence
- my.openHAB Persistence
- MySQL Persistence
- rrd4j Persistence
- Sen.Se Persistence
- SiteWhere Persistence
- AKM868 Binding
- AlarmDecoder Binding
- Anel Binding
- Arduino SmartHome Souliss Binding
- Asterisk Binding
- Astro Binding
- Autelis Pool Control Binding
- BenQ Projector Binding
- Bluetooth Binding
- Bticino Binding
- CalDAV Binding
- Chamberlain MyQ Binding
- Comfo Air Binding
- Config Admin Binding
- CUL Transport
- CUL Intertechno Binding
- CUPS Binding
- DAIKIN Binding
- Davis Binding
- DD-WRT Binding
- Denon Binding
- digitalSTROM Binding
- DIY on XBee Binding
- DMX512 Binding
- DSC Alarm Binding
- DSMR Binding
- eBUS Binding
- Ecobee Binding
- EDS OWSever Binding
- eKey Binding
- Energenie Binding
- EnOcean Binding
- Enphase Energy Binding
- Epson Projector Binding
- Exec Binding
- Expire Binding
- Fatek PLC Binding
- Freebox Binding
- Freeswitch Binding
- Frontier Silicon Radio Binding
- Fritz AHA Binding
- Fritz!Box Binding
- FritzBox-TR064-Binding
- FS20 Binding
- Garadget Binding
- Global Caché IR Binding
- GPIO Binding
- HAI/Leviton OmniLink Binding
- HDAnywhere Binding
- Heatmiser Binding
- Homematic / Homegear Binding
- Horizon Mediabox Binding
- HTTP Binding
- IEC 62056-21 Binding
- IHC / ELKO Binding
- ImperiHome Binding
- Insteon Hub Binding
- Insteon PLM Binding
- IPX800 Binding
- IRtrans Binding
- jointSPACE-Binding
- KM200 Binding
- KNX Binding
- Koubachi Binding
- LCN Binding
- LightwaveRF Binding
- Leviton/HAI Omnilink Binding
- Lg TV Binding
- Logitech Harmony Hub
- MailControl Binding
- MAX!Cube-Binding
- MAX! CUL Binding
- MCP23017 I/O Expander Binding
- MCP3424 ADC Binding
- MiLight Binding
- MiOS Binding
- Mochad X10 Binding
- Modbus Binding
- MPD Binding
- MQTT Binding
- MQTTitude binding
- MystromEcoPower Binding
- Neohub Binding
- Nest Binding
- Netatmo Binding
- Network Health Binding
- Network UPS Tools Binding
- Nibe Heatpump Binding
- Nikobus Binding
- Novelan/Luxtronic Heatpump Binding
- NTP Binding
- One-Wire Binding
- Onkyo AV Receiver Binding
- Open Energy Monitor Binding
- OpenPaths presence detection binding
- OpenSprinkler Binding
- OSGi Configuration Admin Binding
- Panasonic TV Binding
- panStamp Binding
- Philips Hue Binding
- Picnet Binding
- Piface Binding
- PiXtend Binding
- pilight Binding
- Pioneer-AVR-Binding
- Plex Binding
- Plugwise Binding
- PLCBus Binding
- PowerDog Local API Binding
- Powermax alarm Binding
- Primare Binding
- Pulseaudio Binding
- Raspberry Pi RC Switch Binding
- RFXCOM Binding
- RWE Smarthome Binding
- Sager WeatherCaster Binding
- Samsung AC Binding
- Samsung TV Binding
- Serial Binding
- Sallegra Binding
- Satel Alarm Binding
- Siemens Logo! Binding
- SimpleBinary Binding
- Sinthesi Sapp Binding
- Smarthomatic Binding
- Snmp Binding
- Somfy URTSI II Binding
- Sonance Binding
- Sonos Binding
- Souliss Binding
- Squeezebox Binding
- Stiebel Eltron Heatpump
- Swegon ventilation Binding
- System Info Binding
- TA CMI Binding
- TCP/UDP Binding
- Tellstick Binding
- TinkerForge Binding
- Tivo Binding
- UCProjects.eu Relay Board Binding
- UPB Binding
- VDR Binding
- Velleman-K8055-Binding
- Wago Binding
- Wake-on-LAN Binding
- Waterkotte EcoTouch Heatpump Binding
- Weather Binding
- Wemo Binding
- Withings Binding
- XBMC Binding
- xPL Binding
- Yamahareceiver Binding
- Zibase Binding
- Z-Wave Binding
- Asterisk
- DoorBird
- FIND
- Foscam IP Cameras
- LG Hombot
- Worx Landroid
- Heatmiser PRT Thermostat
- Google Calendar
- Linux Media Players
- Osram Lightify
- Rainforest EAGLE Energy Access Gateway
- Roku Integration
- ROS Robot Operating System
- Slack
- Telldus Tellstick
- Zoneminder
- Wink Hub (rooted)
- Wink Monitoring
- openHAB Cloud Connector
- Google Calendar Scheduler
- Transformations
- XSLT
- JSON
- REST-API
- Security
- Service Discovery
- Voice Control
- BritishGasHive-Using-Ruby
- Dropbox Bundle
A good source of inspiration and tips from users gathered over the years. Be aware that things may have changed since they were written and some examples might not work correctly.
Please update the wiki if you do come across any out of date information.
- Rollershutter Bindings
- Squeezebox
- WAC Binding
- WebSolarLog
- Alarm Clock
- Convert Fahrenheit to Celsius
- The mother of all lighting rules
- Reusable Rules via Functions
- Combining different Items
- Items, Rules and more Examples of a SmartHome
- Google Map
- Controlling openHAB with Android
- Usecase examples
- B-Control Manager
- Spell checking for foreign languages
- Flic via Tasker
- Chromecast via castnow
- Speedtest.net integration