This page is part of archived documentation for openHAB 3.1. Go to the current stable version

# OpenTherm Gateway Binding

This binding is used to integrate the OpenTherm Gateway into openHAB. The OpenTherm Gateway is a module designed by Schelte Bron that is connected in between a boiler and a thermostat and communicates using the OpenTherm protocol.

More information on the OpenTherm Gateway device can be found at https://otgw.tclcode.com/ (opens new window)

# Supported Things

The OpenTherm Gateway binding currently only supports one thing, and that's the gateway itself.

# Discovery

The binding does not support auto discovery.

# Binding Configuration

The binding itself does not require any configuration.

# Thing Configuration

The binding is designed to support various ways of connecting to the OpenTherm Gateway device, but currently only supports a TCP socket connection. The configuration settings for the thing are Hostname/IP address and Port, which are used to connect to the gateway, and an automatic connection retry interval in case the connection to the OpenTherm Gateway device is lost.

Parameter Name Description Required Default
ipaddress Hostname or IP address The hostname or IP address to connect to the OpenTherm Gateway. yes
port Port The port used to connect to the OpenTherm Gateway. yes
connectionRetryInterval Connection Retry Interval The interval in seconds to retry connecting (0 = disabled). yes 60

# Channels

The OpenTherm Gateway binding supports the following channels:

Channel Type ID Item Type Description Access
roomtemp Number:Temperature Current sensed room temperature R
roomsetpoint Number:Temperature Current room temperature setpoint R
temperaturetemporary Number:Temperature Temporary override room temperature setpoint R/W
temperatureconstant Number:Temperature Constant override room temperature setpoint R/W
controlsetpoint Number:Temperature Central heating water setpoint set at boiler R
controlsetpointrequested Number:Temperature Central heating water setpoint requested by thermostat R
controlsetpointoverride Number:Temperature Central heating water setpoint configured at gateway R/W
controlsetpoint2 Number:Temperature Central heating 2 water setpoint set at boiler R
controlsetpoint2requested Number:Temperature Central heating 2 water setpoint requested by thermostat R
controlsetpoint2override Number:Temperature Central heating 2 water setpoint configured at gateway R/W
dhwtemp Number:Temperature Domestic hot water temperature R
tdhwset Number:Temperature Domestic hot water temperature setpoint R
overridedhwsetpoint Number:Temperature Domestic hot water temperature setpoint override R/W
flowtemp Number:Temperature Boiler water temperature R
returntemp Number:Temperature Return water temperature R
outsidetemp Number:Temperature Outside temperature R/W
waterpressure Number:Pressure Central heating water pressure R
ch_enable Switch Central heating enabled set at boiler R
ch_enablerequested Switch Central heating enabled requested by thermostat R
ch_enableoverride Switch Central heating enabled overridden at gateway R
ch2_enable Switch Central heating 2 enabled set at boiler R
ch2_enablerequested Switch Central heating 2 enabled requested by thermostat R
ch2_enableoverride Switch Central heating 2 enabled overridden at gateway R
ch_mode Switch Central heating active R
dhw_enable Switch Domestic hot water enabled R
dhw_mode Switch Domestic hot water active R
flame Switch Burner active R
modulevel Number:Dimensionless Relative modulation level R
maxrelmdulevel Number:Dimensionless Maximum relative modulation level R
fault Switch Fault indication R
servicerequest Switch Service required R
lockout-reset Switch Lockout-reset enabled R
lowwaterpress Switch Low water pressure fault R
gasflamefault Switch Gas or flame fault R
airpressfault Switch Air pressure fault R
waterovtemp Switch Water over-temperature fault R
oemfaultcode Switch OEM fault code R
diag Switch Diagnostics indication R
unsuccessfulburnerstarts Number:Dimensionless Unsuccessful burner starts R
burnerstarts Number:Dimensionless Burner starts R
chpumpstarts Number:Dimensionless Central heating pump starts R
dhwpvstarts Number:Dimensionless Domestic hot water pump/valve starts R
dhwburnerstarts Number:Dimensionless Domestic hot water burner starts R
burnerhours Number:Dimensionless Burner hours R
chpumphours Number:Dimensionless Central heating pump hours R
dhwpvhours Number:Dimensionless Domestic hot water pump/valve hours R
dhwburnerhours Number:Dimensionless Domestic hot water burner hours R
sendcommand Text Channel to send commands to the OpenTherm Gateway device W

# Full Example

# demo.things

Thing openthermgateway:otgw:1 [ ipaddress="192.168.1.100", port=8000, connectionRetryInterval=60 ]

# demo.items

Number:Temperature RoomTemperature "Room temperature [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:roomtemp" }
Number:Temperature RoomSetpoint "Room setpoint [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:roomsetpoint" }
Number:Temperature TemporaryRoomSetpointOverride "Temporary room setpoint override [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:temperaturetemporary" }
Number:Temperature ConstantRoomSetpointOverride "Constant room setpoint override [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:temperatureconstant" }
Number:Temperature ControlSetpoint "Control setpoint [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:controlsetpoint" }
Number:Temperature ControlSetpointRequested "Control setpoint requested [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:controlsetpointrequested" }
Number:Temperature ControlSetpointOverride "Control setpoint override [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:controlsetpointoverride" }
Number:Temperature ControlSetpoint2 "Control setpoint 2 [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:controlsetpoint2" }
Number:Temperature ControlSetpoint2Requested "Control setpoint 2 requested [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:controlsetpoint2requested" }
Number:Temperature ControlSetpoint2Override "Control setpoint 2 override [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:controlsetpoint2override" }
Number:Temperature DomesticHotWaterTemperature "Domestic hot water temperature [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:dhwtemp" }
Number:Temperature DomesticHotWaterSetpoint "Domestic hot water setpoint [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:tdhwset" }
Number:Temperature DomesticHotWaterSetpointOverride "Domestic hot water setpoint override [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:overridedhwsetpoint" }
Number:Temperature BoilerWaterTemperature "Boiler water temperature [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:flowtemp" }
Number:Temperature ReturnWaterTemperature "Return water temperature [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:returntemp" }
Number:Temperature OutsideTemperature "Outside temperature [%.1f °C]" <temperature> { channel="openthermgateway:otgw:1:outsidetemp" }
Number:Pressure CentralHeatingWaterPressure "Central heating water pressure [%.1f bar]" { channel="openthermgateway:otgw:1:waterpressure" }
Switch CentralHeatingEnabled "Central heating enabled" <switch> { channel="openthermgateway:otgw:1:ch_enable" }
Switch CentralHeatingEnabledRequested "Central heating enabled requested" <switch> { channel="openthermgateway:otgw:1:ch_enablerequested" }
Switch CentralHeatingEnabledOverride "Central heating enabled override" <switch> { channel="openthermgateway:otgw:1:ch_enableoverride" }
Switch CentralHeating2Enabled "Central heating 2 enabled" <switch> { channel="openthermgateway:otgw:1:ch2_enable" }
Switch CentralHeating2EnabledRequested "Central 2 heating enabled requested" <switch> { channel="openthermgateway:otgw:1:ch2_enablerequested" }
Switch CentralHeating2EnabledOverride "Central 2 heating enabled override" <switch> { channel="openthermgateway:otgw:1:ch2_enableoverride" }
Switch CentralHeatingActive "Central heating active" <switch> { channel="openthermgateway:otgw:1:ch_mode" }
Switch DomesticHotWaterEnabled "Domestic hot water enabled" <switch> { channel="openthermgateway:otgw:1:dhw_enable" }
Switch DomesticHotWaterActive "Domestic hot water active" <switch> { channel="openthermgateway:otgw:1:dhw_mode" }
Switch BurnerActive "Burner active" <switch> { channel="openthermgateway:otgw:1:flame" }
Number:Dimensionless RelativeModulationLevel "Relative modulation level [%.1f %%]" { channel="openthermgateway:otgw:1:modulevel" }
Number:Dimensionless MaximumRelativeModulationLevel "Maximum relative modulation level [%.1f %%]" { channel="openthermgateway:otgw:1:maxrelmdulevel" }
Switch Fault "Fault indication" <switch> { channel="openthermgateway:otgw:1:fault" }
Switch ServiceRequest "Service required" <switch> { channel="openthermgateway:otgw:1:servicerequest" }
Switch LockoutReset "Lockout-reset" <switch> { channel="openthermgateway:otgw:1:lockout-reset" }
Switch LowWaterPress "Low water pressure fault" <switch> { channel="openthermgateway:otgw:1:lowwaterpress" }
Switch GasFlameFault "Gas or flame fault" <switch> { channel="openthermgateway:otgw:1:gasflamefault" }
Switch AirPressFault "Air pressure fault" <switch> { channel="openthermgateway:otgw:1:airpressfault" }
Switch WaterOvTemp "Water over-temperature fault" <switch> { channel="openthermgateway:otgw:1:waterovtemp" }
Number OemFaultCode "OEM fault code" { channel="openthermgateway:otgw:1:oemfaultcode" }
Switch Diagnostics "Diagnostics indication" { channel="openthermgateway:otgw:1:diag" }
Number:Dimensionless UnsuccessfulBurnerStarts "Unsuccessful burner starts" { channel="openthermgateway:otgw:1:unsuccessfulburnerstarts" }
Number:Dimensionless BurnerStarts "Burner starts" { channel="openthermgateway:otgw:1:burnerstarts" }
Number:Dimensionless CentralHeatingPumpStarts "Central heating pump starts" { channel="openthermgateway:otgw:1:chpumpstarts" }
Number:Dimensionless DomesticHotWaterPumpValveStarts "Domestic hot water pump/valve starts" { channel="openthermgateway:otgw:1:dhwpvstarts" }
Number:Dimensionless DomesticHotWaterBurnerStarts "Domestic hot water burner starts" { channel="openthermgateway:otgw:1:dhwburnerstarts" }
Number:Time BurnerHours "Burner hours" { channel="openthermgateway:otgw:1:burnerhours" }
Number:Time CentralHeatingPumpHours "Central heating pump hours" { channel="openthermgateway:otgw:1:chpumphours" }
Number:Time DomesticHotWaterPumpValveHours "Domestic hot water pump/valve hours" { channel="openthermgateway:otgw:1:dhwpvhours" }
Number:Time DomesticHotWaterBurnerHours "Domestic hot water burner hours" { channel="openthermgateway:otgw:1:dhwburnerhours" }
Text SendCommand "Send command channel" { channel="openthermgateway:otgw:1:sendcommand" }

# demo.sitemap

sitemap demo label="Main Menu" {
    Frame label="OpenTherm Gateway" {
        Text item="RoomTemperature" icon="temperature" label="Room temperature [%.1f °C]"
        Text item="RoomSetpoint" icon="temperature" label="Room setpoint [%.1f °C]"
        Setpoint item="TemporaryRoomSetpointOverride" icon="temperature" label="Temporary room setpoint override [%.1f °C]" minValue="0" maxValue="30" step="0.1"
        Setpoint item="ConstantRoomSetpointOverride" icon="temperature" label="Constant room setpoint override [%.1f °C]" minValue="0" maxValue="30" step="0.1"
        Text item="ControlSetpoint" icon="temperature" label="Control setpoint [%.1f °C]"
        Text item="ControlSetpointRequested" icon="temperature" label="Control setpoint requested [%.1f °C]"
        Setpoint item="ControlSetpointOverride" icon="temperature" label="Control setpoint override [%.1f °C]" minValue="0" maxValue="100" step="1"
        Text item="DomesticHotWaterTemperature" icon="temperature" label="Domestic hot water temperature [%.1f °C]"
        Text item="DomesticHotWaterSetpoint" icon="temperature" label="Domestic hot water setpoint [%.1f °C]"
        Setpoint item="DomesticHotWaterSetpointOverride" icon="temperature" label="Domestic hot water setpoint override [%.1f °C]" minValue="0" maxValue="100" step="0.1"
        Text item="BoilerWaterTemperature" icon="temperature" label="Boiler water temperature [%.1f °C]"
        Text item="ReturnWaterTemperature" icon="temperature" label="Return water temperature [%.1f °C]"
        Setpoint item="OutsideTemperature" icon="temperature" label="Outside temperature [%.1f °C]" minValue="-40" maxValue="100" step="0.1"
        Text item="CentralHeatingWaterPressure" icon="" label="Central heating water pressure [%.1f bar]"
        Switch item="CentralHeatingEnabled" icon="switch" label="Central heating enabled"
        Switch item="CentralHeatingEnabledRequested" icon="switch" label="Central heating enabled requested"
        Switch item="CentralHeatingEnabledOverride" icon="switch" label="Central heating enabled override"
        Switch item="CentralHeatingActive" icon="switch" label="Central heating active"
        Switch item="DomesticHotWaterEnabled" icon="switch" label="Domestic hot water enabled"
        Switch item="DomesticHotWaterActive" icon="switch" label="Domestic hot water active"
        Switch item="BurnerActive" icon="switch" label="Burner active"
        Text item="RelativeModulationLevel" icon="" label="Relative modulation level [%.1f %%]"
        Text item="MaximumRelativeModulationLevel" icon="" label="Maximum relative modulation level [%.1f %%]"
        Switch item="Fault" icon="" label="Fault indication"
        Switch item="ServiceRequest" icon="" label="Service required"
        Switch item="LockoutReset" icon="" label="Lockout-reset"
        Switch item="LowWaterPress" icon="" label="Low water pressure fault"
        Switch item="GasFlameFault" icon="" label="Gas or flame fault"
        Switch item="AirPressFault" icon="" label="Air pressure fault"
        Switch item="waterOvTemp" icon="" label="Water over-temperature fault"
        Text item="OemFaultCode" icon="" label="OEM fault code"
        Switch item="Diagnostics" icon="" label="Diagnostics indication"
        Text item="UnsuccessfulBurnerStarts" icon="" label="Unsuccessful burner starts"
        Text item="BurnerStarts" icon="" label="Burner starts"
        Text item="CentralHeatingPumpStarts" icon="" label="Central heating pump starts"
        Text item="DomesticHotWaterPumpValveStarts" icon="" label="Domestic hot water pump/valve starts"
        Text item="DomesticHotWaterBurnerStarts" icon="" label="Domestic hot water burner starts"
        Text item="BurnerHours" icon="" label="Burner hours"
        Text item="CentralHeatingPumpHours" icon="" label="Central heating pump hours"
        Text item="DomesticHotWaterPumpValveHours" icon="" label="Domestic hot water pump/valve hours"
        Text item="DomesticHotWaterBurnerHours" icon="" label="Domestic hot water burner hours"
    }
}