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.6 January 7, 2014
  • Corrects namespace conflict for HVAC device
  • Changed behavior of EnergyModeStatus; will now be on only if an Eco option is in effect
  • Eco mode and options added
    • [EDHW] Change DHW setting when EnergyModeStatus set to EnergySavingsMode
    • [ETMP] Change setpoint when EnergyModeStatus set to EnergySavingsMode
  • Added configuration options for firmware 4.0
• 0.5 November 20, 2013
  • Bug fix; now correctly shows negative values
• 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
• Remote Override Function flags - Select whether in MsgId 100 the flags are set in only the low byte or both the high and low byte. If you have a Honeywell Chronotherm Vision Modulation make sure it is set to 'High and low byte' (if not, a TT setting will be permanent).
• Reference voltage - Select the reference voltage setting (reference voltage is used as a threshold for the comparators)
• GPIO A-B - Select a function for each GPIO port
• 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'.

Eco features

Default Eco options

The following Eco options are activated when the Eco mode is selected.

• Change domestic hot water: one can select to disable DHW or not
• Change room setpoint: the room setpoint can be lowered compared to the current setpoint; or it can be set to a specific value. The TT command is used to set this setpoint, so a program change will override the setpoint.

The following Eco options are only available in case there is an alarm system connected to Vera and/or door/window sensors.

Alarm partition Eco options

If there is nobody at home, the plugin offers two options to activate. To determine whether nobody is at home, the state of an alarm partition is used. In case there are multiple partitions, one needs to be selected. The two available options are:

• Change domestic hot water: one can select to disable DHW when nobody is home
• Change room setpoint: the room setpoint can be lowered compared to the setpoint when arming the partition; or it can be set to a specific value. The TT command is used to set this setpoint, so a program change will override the setpoint.

Door/window sensor Eco options

If one or multiple door/window sensors is tripped, the plugin can lower the current room setpoint (or set it to a predefined value). Select the available sensors via the multi-select box.

• Change room setpoint: new setpoint when one of the door/window sensors is tripped (set via TT command)
• Option: only when it is open for more than: select the number of minutes that one of the door/windows has to be open before the setpoint is lowered.
• Option: only when it is colder outside than inside: one can select to only set a new setpoint if it is colder outside than inside. A outside temperature sensor has to be selected in the settings for this to work.

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