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

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)