The OpenTherm Gateway plugin for Vera

Vera plugin to control the OpenTherm Gateway (see ​http://otgw.tclcode.com/) designed by Schelte Bron. Discussion on the hardware and firmware can be found on ​http://www.domoticaforum.eu/viewforum.php?f=75. The OpenTherm Gateway hardware can be ordered via ​http://www.opentherm-gateway.com/.

Supported features

• Monitor OpenTherm settings
  • OpenTherm version 2.3 messages supported
• Thermostat control in Gateway mode
• Override room temperature setpoint
• Get outside temperature from Vera sensor
• Get room humidity from Vera sensor
• Eco mode allows to change setpoint and/or DHW setting based on pre-defined conditions
• Show firmware version of the Gateway
• Send date and time command
• Send free format command
• Monitor protocol errors (and reset error count)
• Change Gateway configuration through the plugin
• Send notifications on boiler events

Version history

• 0.4 October 27, 2013
  • Supports OTG firmware version 4.0(alpha)
  • Option to create child devices for temperature values
  • Eco mode and options added
    • [ADHW] Change DHW setting when alarm is Armed (away)
    • [ATMP] Change setpoint when alarm is Armed (away)
    • [DTMP] Change setpoint when door(s)/window(s) is/are open
    • Function SetEnergyModeTarget added
  • Moved DHW setting to control tab
  • Split Settings tab in Hardware & plugin Settings tab
  • Added option to show (colored) value indication bars
  • Support to show humidity value on thermostat
    • Function SetRoomHumidity added
  • Now supports different levels of debug output
  • OpenTherm version 2.3 messages added
• 0.3 October 5, 2013
  • Added sending of free format commands
  • Get/update configuration of the gateway
  • Added extra values to display
  • Added error counters to display
  • Display firmware version
  • Send date/time or free format command
  • Full support of all OpenTherm messages
  • Separate variables for hb/lb possible
  • Made variable names more consistent
  • Updated monitor display (e.g. bold on value change)
  • Added notifications
• 0.2 September 28, 2013
  • Monitoring of Gateway
  • Control outside temperature value
  • Send TT and TC commands
• 0.1 September 27, 2013
  • Initial version

Monitor screenshot (UI5)

Installation

• Go to Apps -> Develop Apps -> Create device
• Fill out 'D_OpenThermGateway.xml' under 'Upnp Device Filename'
• Fill out the IP address or select the serial parent device
• Press 'Create'
• Press 'Reload'

Configuration

Settings

The following settings are available in the 'Settings' tab.

• Communicate using UART - visible when connected via a serial interface
• Communicate using IP - visible when connected via an IP address
• Generate debug logging & files - select whether messages are logged in otg_msg.txt file and the logging level in the LuaUPnP.log file
• Outside temperature sensor - select an temperature sensor to use for the OT= command; temperature updates will be sent to the Gateway
• Humidity room sensor - select a humidity device to have the value displayed on the thermostat (if the thermostat supports ventilation control; value will be sent via SR=78: command)
• Use child device for temperature - select which messages will create a child device (only temperaturevalues are supported)
• Show monitor bar indicator - Select what type (or none) indicator bar will be used in the monitor tab

Hardware

The following settings are available in the 'Hardware' tab.

• Operating mode - Gateway or Monitor; this should be set to 'Gateway' for all functions to be available.
• Non-significant transitions - Select whether checking for error 01 is on or off
• Reference voltage - Select the reference voltage setting (reference voltage is used as a threshold for the comparators)
• LED A-D or A-F function (A-F as of firmware 4) - Select a function for each LED on the Gateway
  • Receiving an Opentherm message from the thermostat or boiler
  • Transmitting an Opentherm message to the thermostat or boiler
  • Transmitting or receiving a message on the master interface
  • Transmitting or receiving a message on the slave interface
  • Remote setpoint override is active
  • Flame is on
  • Central heating is on
  • Hot water is on
  • Comfort mode (Domestic Hot Water Enable) is on
  • Transmission error has been detected
  • Boiler requires maintenance
  • Thermostat requests a raised power level (firmware 4 only)

Usage

• Changing a temperature setpoint in the UI will send a 'TT=' command to the Gateway. The Gateway will use this to force a 'Remote override room setpoint'.
• Pressing the 'Heat' button will send a 'TC=' command, making the current setpoint constant instead of temporary.
• Pressing the 'Off' button will remove the remote override room setpoint, by sending a TT=0 command.

Please note that the display will show a decimal value, but Vera can only handle integer values (i.e. you can only set the Thermostat to 21°C in the UI and not to 21.5°C. You can set a value of e.g. 21.34°C via the function 'SetCurrentSetpoint'.

Notifications

The following notifications are currently available.

• Central heating goes on or off
• Domestic hot water goes on or off
• Cooling goes on or off
• Central heating 2nd circuit goes on or off
• Flame goes on or off
• Fault indication
• Diagnostic indication
• Ambient temperature goes above
• Ambient temperature goes below

Variables

Plugin

• PluginVersion - version number of the plugin
• PluginDebug - 0: debug off; 1: debug on
• PluginLogPath - path to write log file to
• PluginHaveChildren - empty: none; otherwise list of message IDs that will create a child device
• PluginMonitorBars - 0: none; 1: single color; 2: temperature relative
• PluginOutsideSensor - empty: none; otherwise device ID of temperature sensor
• PluginHumiditySensor - empty: none; otherwise device ID of humidity sensor
• PluginEcoMeasureState - empty: none; otherwise a combination of [ADHW], [ATMP], [DTMP]
• PluginPartitionDevice - empty: none; otherwise device ID of alarm partition device
• PluginArmedAwayDHW - 0: No; 1: disable; 2: automatic
• PluginArmedAwayTemp - 0: no change; x: set to x degrees; -x: lower x degrees
• PluginDoorWindowDevices - empty: none; otherwise comma separated list of door device ID
• PluginDoorWindowTemp - 0: no change; x: set to x degrees; -x: lower x degrees
• PluginDoorWindowMinutes - number of minutes to wait before evaluating conditions
• PluginDoorWindowOutside - 0: ignore; 1: needs to be colder outside than inside

Currently not all OpenTherm messages have associated variables in which the value is stored. The following messages do. If a child device is created, then the value is written to the Gateway variable as well as the 'CurrentTemperature' variable of the child device.

• 1: ControlSetpoint
• 5: FaultCode
• 9: RemoteOverrideRoomSetpoint
• 14: MaxRelativeModulationLevel
• 16: CurrentSetpoint
• 17: RelativeModulationLevel
• 18: CHWaterPressure
• 24: CurrentTemperature
• 25: BoilerWaterTemperature
• 26: DHWTemperature
• 27: OutsideTemperature
• 28: ReturnWaterTemperature
• 32: DHW2Temperature
• 56: DHWSetpoint
• 57: MaxCHWaterSetpoint
• 100: RemoteOverrideFunction

Gateway

• GatewayMode - 0: Monitor; 1: Gateway
• CommandResponse - contains the response of a free format command
• Errors - contains comma separated list of Error 01 - Error 04

OpenTherm

Flag variables (status, config, fault) are always either 0 or 1.

Status variables

• StatusCHEnabled - Central heating enable
• StatusCHEnabled- Central heating enable
• StatusDHWEnabled - Domestic hot water enable
• StatusCoolEnabled - Cooling enable
• StatusOTCActive - Outside temp. comp. active
• StatusCH2Enabled - Central heating 2 enable
• StatusFault - Fault indication
• StatusCHMode - Central heating mode
• StatusDHWMode - Domestic hot water mode
• StatusFlame - Flame status
• StatusCooling - Cooling status
• StatusCH2Mode - Central heating 2 mode
• StatusDiagnostic - Diagnostic indication

Config flag variables

• ConfigDHWpresent - Domestic hot water present
• ConfigControlType - Control type (modulating on/off)
• ConfigCooling - Cooling supported
• ConfigDHW - Domestic hot water storage tank
• ConfigMasterPump - Master low-off & pump control allowed
• ConfigCH2 - Central heating 2 present

Fault flag variables

• FaultServiceRequest - Service request
• FaultLockoutReset - Lockout-reset
• FaultLowWaterPress - Low water pressure
• FaultGasFlame - Gas/flame fault
• FaultAirPress - Air pressure fault
• FaultOverTemp - Water over-temperature