pyotgw

A python library to interface with the OpenTherm Gateway

See http://otgw.tclcode.com for the hardware.

This library is written primarily for use with Home Assistant (https://www.home-assistant.io) but can be used for other purposes as well. Parts of the code have not been thoroughly tested since my thermostat and boiler do not support all OpenTherm features. Feel free to test and contribute where you see fit.

Contents

• Library Reference
  • General
  • Getting Data
  • Methods
• Usage Example
• Development
• Status Dict Structure

Library Reference

General

pyotgw exposes its OpenThermGateway class which uses pyserial-asyncio to connect to the OpenTherm Gateway. After initialization of the object, OpenThermGateway.connect() should be used to establish a connection. The object will maintain the connection in the background, using it to send commands and continuously receive updates. The received information will be cached on the object for instant availability. The OpenThermGateway object implements a watchdog to monitor the connection for inactivity. During OpenThermGateway.connect(), an inactivity timeout can be set for this purpose. Normally, the OpenTherm Gateway will send a message on its serial interface approximately every second. If no messages are received for the duration of the timeout, the watchdog will trigger a reconnection attempt.

Getting Data

There are multiple ways to get information from pyotgw. Calling OpenThermGateway.connect() will request some initial information from the Gateway and return it in a dict. After this, the OpenThermGateway object exposes quite a few methods which return values that are cached on the object. There is also the option to register a callback with OpenThermGateway.subscribe() which will be called when any value changes.

Methods

---

OpenThermGateway()

The OpenThermGateway constructor takes no arguments and returns an empty OpenThermGateway object.

---

OpenThermGateway.add_alternative(self, alt, timeout=OTGW_DEFAULT_TIMEOUT)

Add the specified data-ID to the list of alternative commands to send to the boiler instead of a data-ID that is known to be unsupported by the boiler. Alternative data-IDs will always be sent to the boiler in a Read-Data request message with the data-value set to zero. The table of alternative data-IDs is stored in non-volatile memory so it will persist even if the gateway has been powered off. This method supports the following arguments:

• alt The alternative data-ID to add. Values from 1 to 255 are allowed.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Returns the ID that was added to the list, or None on failure.

This method is a coroutine.

---

OpenThermGateway.add_unknown_id(self, unknown_id, timeout=OTGW_DEFAULT_TIMEOUT)

Inform the gateway that the boiler doesn't support the specified data-ID, even if the boiler doesn't indicate that by returning an unknown-dataID response. Using this command allows the gateway to send an alternative data-ID to the boiler instead. This method supports the following arguments:

• unknown_id The data-ID to mark as unsupported. Values from 1 to 255 are allowed.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Returns the added ID, or None on failure.

This method is a coroutine.

---

OpenThermGateway.connect(self, port, timeout=5, skip_init=None)

Connect to an OpenTherm Gateway and initializes the parameters obtained from the PS and PR commands. If called while connected, reconnect to the gateway. All optional serial-related arguments default to the OpenTherm Gateway default settings. This method supports the following arguments:

• port The port/url on which the OpenTherm Gateway can be reached as supported by pyserial.
• timeout The inactivity timeout in seconds after which the watchdog will trigger a reconnect. Defaults to 5.
• skip_init If set to True, the PS= and PR= commands are skipped and only PS=0 is sent upon the current and future connection attempts. Defaults to None, which keeps the last known setting.

Returns a status dict with all known values.

This method is a coroutine.

---

OpenThermGateway.disconnect(self)

Disconnect from the OpenTherm Gateway and clean up the object.

This method is a coroutine.

---

OpenThermGateway.del_alternative(self, alt, timeout=OTGW_DEFAULT_TIMEOUT)

Remove the specified data-ID from the list of alternative commands. Only one occurrence is deleted. If the data-ID appears multiple times in the list of alternative commands, this command must be repeated to delete all occurrences. The table of alternative data-IDs is stored in non-volatile memory so it will persist even if the gateway has been powered off. This method supports the following arguments:

• alt The alternative data-ID to remove. Values from 1 to 255 are allowed.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Returns the ID that was removed from the list, or None on failure.

This method is a coroutine.

---

OpenThermGateway.del_unknown_id(self, unknown_id, timeout=OTGW_DEFAULT_TIMEOUT)

Start forwarding the specified Data-ID to the boiler again. This command resets the counter used to determine if the specified data-ID is supported by the boiler. This method supports the following arguments:

• unknown_id The data-ID to mark as supported. Values from 1 to 255 are allowed.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Return the ID that was marked as supported, or None on failure.

This method is a coroutine.

---

OpenThermGateway.get_reports(self)

Update the OpenThermGateway object with the information from all of the PR commands. This method is also called from OpenThermGateway.connect() to populate the status dict with initial values.

Returns the full updated status dict.

This method is a coroutine.

---

OpenThermGateway.get_status(self)

Update the OpenThermGateway object with the information from the PS command. This method is also called from OpenThermGateway.connect() to populate the status dict with initial values.

Returns the full updated status dict.

This method is a coroutine.

---

OpenThermGateway.set_ch_enable_bit(self, ch_bit, timeout=OTGW_DEFAULT_TIMEOUT)

Set or unset the Central Heating Enable bit. Control the CH enable status bit when overriding the control setpoint. By default the CH enable bit is set after a call to OpenThermGateway.set_control_setpoint() with a value other than 0. With this method, the bit can be manipulated. This method supports the following arguments:

• ch_bit The new value for the Central Heating Enable bit. Can be either 0 or 1.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Return the newly accepted value (0 or 1), or None on failure.

This method is a coroutine.

---

OpenThermGateway.set_ch2_enable_bit(self, ch_bit, timeout=OTGW_DEFAULT_TIMEOUT)

Set or unset the Central Heating Enable bit for heating circuit 2. Control the CH enable status bit when overriding the control setpoint. By default the CH enable bit is set after a call to OpenThermGateway.set_control_setpoint() with a value other than 0. With this method, the bit can be manipulated. This method supports the following arguments:

• ch_bit The new value for the Central Heating Enable bit. Can be either 0 or 1.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Return the newly accepted value (0 or 1), or None on failure.

This method is a coroutine.

---

OpenThermGateway.set_clock(self, date=datetime.now(), timeout=OTGW_DEFAULT_TIMEOUT)

Set the clock on the thermostat. Change the time and day of the week of the thermostat. The gateway will send the specified time and day of the week in response to the next time and date message from the thermostat. This method supports the following arguments:

• date A datetime object containing the time and day of the week to be sent to the thermostat. Defaults to datetime.now().
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Returns the accepted response from the gateway with format HH:MM/DOW, where DOW is a single digit: 1=Monday, 7=Sunday, or None on failure.

This method is a coroutine.

---

OpenThermGateway.set_connection_options(self, **kwargs)

Set the serial connection parameters before calling connect(). Valid kwargs are 'baudrate', 'bytesize', 'parity' and 'stopbits'. Returns True on success, False on fail or if already connected. For more information on the kwargs see the pyserial documentation.

---

OpenThermGateway.set_control_setpoint(self, setpoint, timeout=OTGW_DEFAULT_TIMEOUT)

Set the control setpoint. The control setpoint is the target temperature for the water in the central heating system. This method will cause the OpenTherm Gateway to manipulate the control setpoint which is sent to the boiler. Set the control setpoint to 0 to pass along the value specified by the thermostat. This method supports the following arguments:

• setpoint The new control setpoint.
• timeout The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).

Returns the newly accepted value, or None on failure.

This method is a coroutine.

---

OpenThermGateway.set_control_setpoint_2(self, setpoint, timeout=OTGW_DEFAULT_TIMEOUT)

Set the control setpoint for central heatin