[](https://travis-ci.org/mvn23/pyotgw)
# 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](#library-reference)
- [General](#general)
- [Getting Data](#getting-data)
- [Methods](#methods)
- [Usage Example](#usage-example)
- [Development](#development)
- [Status Dict Structure](#status-dict-structure)
### Library Reference
#### General
pyotgw exposes its OpenThermGateway class which uses [pyserial-asyncio](https://pyserial-asyncio.readthedocs.io/en/latest/) 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](https://pythonhosted.org/pyserial/url_handlers.html).
- __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 heating circuit 2.
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_dhw_setpoint(_self_, temperature, timeout=OTGW_DEFAULT_TIMEOUT)
Set the domestic hot water setpoint.
The domestic hot water setpoint is the target temperature for the hot water system. Not all boilers support this command.
This method supports the following arguments:
- __temperature__ The new domestic hot water setpoint.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the newly accepted setpoint, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_gpio_mode(_self_, gpio_id, mode, timeout=OTGW_DEFAULT_TIMEOUT)
Configure the functions of the two GPIO pins of the gateway.
Possible modes are:
- __0.__ No function, default for both ports on a freshly flashed chip.
- __1.__ Ground - A permanently low output (0V). Could be used for a power LED.
- __2.__ Vcc - A permanently high output (5V). Can be used as a short-proof power supply for some external circuitry used by the other GPIO port.
- __3.__ LED E - An additional LED if you want to present more than 4 LED functions.
- __4.__ LED F - An additional LED if you want to present more than 5 LED functions.
- __5.__ Home - Set thermostat to setback temperature when pulled low.
- __6.__ Away - Set thermostat to setback temperature when pulled high.
- __7.__ DS1820 (GPIO port B only) - Data line for a DS18S20 or DS18B20 temperature sensor used to measure the outside temperature. A 4k7 resistor should be connected between GPIO port B and Vcc.
This method supports the following arguments:
- __gpio_id__ The GPIO pin on which the mode is set. Either `A` or `B`.
- __mode__ The requested mode for the GPIO pin. Values from `0` to `7` are supported (`7` only for GPIO `B`).
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the new mode for the specified gpio, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_hot_water_ovrd(_self_, state, timeout=OTGW_DEFAULT_TIMEOUT)
Control the domestic hot water enable option.
If the boiler has been configured to let the room unit control when to keep a small amount of water preheated, this option can influence that. A state of `0` or `1` will override the domestic hot water option `off` or `on` respectively. Any other single character disables the override and resumes normal operation.
This method supports the following arguments:
- __state__ The requested state for the domestic hot water option.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the accepted value, `A` if the override is disabled or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_led_mode(_self_, led_id, mode, timeout=OTGW_DEFAULT_TIMEOUT)
Set the mode of one of the LEDs.
Configure the functions of the six LEDs (A-F) that can optionally be connected to pins RB3/RB4/RB6/RB7 and the GPIO pins of the PIC.
Possible modes are:
- __R__ Receiving an Opentherm message from the thermostat or boiler
- __X__ Transmitting an Opentherm message to the thermostat or boiler
- __T__ Transmitting or receiving a message on the master interface
- __B__ Transmitting or receiving a message on the slave interface
- __O__ Remote setpoint override is active
- __F__ Flame is on
- __H__ Central heating is on
- __W__ Hot water is on
- __C__ Comfort mode (Domestic Hot Water Enable) is on
- __E__ Transmission error has been detected
- __M__ Boiler requires maintenance
- __P__ Raised power mode active on thermostat interface.
This method supports the following arguments:
- __led_id__ The LED for which the mode is set. Must be a character in the range `A-F`.
- __mode__ The requested state for the LED. Must be one of `R`, `X`, `T`, `B`, `O`, `F`, `H`, `W`, `C`, `E`, `M` or `P`.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the new mode for the specified LED, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_max_ch_setpoint(_self_, temperature, timeout=OTGW_DEFAULT_TIMEOUT)
Set the maximum central heating water setpoint.
Not all boilers support this option.
This method supports the following arguments:
- __temperature__ The new maximum central heating water setpoint.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the newly accepted setpoint, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_max_relative_mod(_self_, max_mod, timeout=OTGW_DEFAULT_TIMEOUT)
Set the maximum relative modulation level.
Override the maximum relative modulation from the thermostat. Valid values are 0 through 100. Clear the setting by specifying a non-numeric value.
This method supports the following arguments:
- __temperature__ The new maximum central heating water setpoint.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the newly accepted value, `-` if a previous value was cleared, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_mode(_self_, mode, timeout=OTGW_DEFAULT_TIMEOUT)
Set the operating mode of the gateway.
The operating mode can be either `gateway` or `monitor` mode. This method can also be used to reset the OpenTherm Gateway.
This method supports the following arguments:
- __mode__ The mode to be set on the gateway. Can be `0` or `OTGW_MODE_MONITOR` for `monitor` mode, `1` or `OTGW_MODE_GATEWAY` for `gateway mode, or `OTGW_MODE_RESET` to reset the gateway.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Return the newly activated mode, or the full renewed status dict after a reset.
This method is a coroutine.
---
##### OpenThermGateway.set_outside_temp(_self_, temp, timeout=OTGW_DEFAULT_TIMEOUT)
Set the outside temperature.
Configure the outside temperature to send to the thermostat. Allowed values are between -40.0 and +64.0, although thermostats may not display the full range. Specify a value above 64 (suggestion: 99) to clear a previously configured value.
This method supports the following arguments:
- __temp__ The outside temperature to provide to the gateway.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the accepted value on success, `-` if a previously configured value has been cleared or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_setback_temp(_self_, sb_temp, timeout=OTGW_DEFAULT_TIMEOUT)
Set the setback temperature.
Configure the setback temperature to use in combination with the GPIO functions `home`(5) and `away`(6).
This method supports the following arguments:
- __sb_temp__ The new setback temperature.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the new setback temperature, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_target_temp(_self_, temp, temporary=True, timeout=OTGW_DEFAULT_TIMEOUT)
Set the room setpoint.
Configure the thermostat setpoint and specify whether or not it may be overridden by a programmed change.
This method supports the following arguments:
- __temp__ The new room setpoint. Will be formatted to 1 decimal.
- __temporary__ Whether or not the thermostat program may override the room setpoint. Either `True` or `False`. Defaults to `True`.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the newly accepted room setpoint, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_temp_sensor_function(_self_, func, timeout=v.OTGW_DEFAULT_TIMEOUT):
Set the function of the temperature sensor that can be attached to the gateway.
This method supports the following arguments:
- __func__ The new temperature sensor function. Either `O` for `Outside Air Temperature` or `R` for `Return Water Temperature`.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Returns the newly accepted temperature sensor function or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.set_ventilation(_self_, pct, timeout=OTGW_DEFAULT_TIMEOUT)
Set the ventilation setpoint.
Configure a ventilation setpoint override value (0-100%).
This method supports the following arguments:
- __pct__ The new ventilation setpoint. Must be between `0` and `100`.
- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).
Return the newly accepted value, or `None` on failure.
This method is a coroutine.
---
##### OpenThermGateway.send_transparent_command(_self_, cmd, state, timeout=OTGW_DEFAULT_TIMEOUT)
Send a transparent command.
Sends custom commands through a transparent interface.
Check https://otgw.tclcode.com/firmware.html for supported commands.
This method supports the following arguments:
- __cmd__ The supported command e.g. `SC` (set time/day).
- __state__ The command argument e.g. `23:59/4` (the current time/day)
Returns the gateway response, which should be equal __state__.
This method is a coroutine.
---
##### OpenThermGateway.subscribe(_self_, coro)
Subscribe to status updates from the Opentherm Gateway.
The subscribed coroutine must have the following signature:
```
async def coro(status)
```
Where `status` will be the full status dict containing the last known information from the OpenTherm Gateway.
This method supports the following arguments:
- __coro__ A coroutine which will be called whenever a status change occurs.
Returns `True` on success, `False` if the coroutine is already subscribed.
---
##### OpenThermGateway.unsubscribe(_self_, coro)
Unsubscribe from status updates from the Opentherm Gateway.
The supplied coroutine must have been subscribed with `OpenThermGateway.subscribe()` before.
This method supports the following arguments:
- __coro__ The coroutine which will be unsubscribed.
Returns `True` on success, `False` if the coroutine was not subscribed before.
---
### Usage Example
```python
import asyncio
from pyotgw import OpenThermGateway
PORT = '/dev/ttyUSB0'
async def print_status(status):
"""Receive and print status."""
print("Received a status update:\n{}".format(status))
async def connect_and_subscribe():
"""Connect to the OpenTherm Gateway and subscribe to status updates."""
# Create the object
gw = OpenThermGateway()
# Connect to OpenTherm Gateway on PORT
status = await gw.connect(PORT)
print("Initial status after connecting:\n{}".format(status))
# Subscribe to updates from the gateway
if not gw.subscribe(print_status):
print("Could not subscribe to status updates.")
# Keep the event loop alive...
while True:
await asyncio.sleep(1)
# Run the connect_and_subscribe coroutine.
try:
asyncio.run(connect_and_subscribe())
except KeyboardInterrupt:
print("Exiting")
```
### Development
We use pre-commit to ensure a consistent code style, so `pip install pre_commit` and run
```
pre-commit install
```
in the repository.
### Status Dict Structure
The full possible status dict with some example values looks like below. Note that not all keys will always be present and that the presence of a key does not guarantee that it contains useful information.
```python
{
vars.BOILER: {
vars.DATA_CH_PUMP_HOURS: 15010,
vars.DATA_CH_PUMP_STARTS: 43832,
vars.DATA_CH_WATER_PRESS: 0.0,
vars.DATA_CH_WATER_TEMP: 47.2,
vars.DATA_CH_WATER_TEMP_2: 0.0,
vars.DATA_CONTROL_SETPOINT: 44.0,
vars.DATA_CONTROL_SETPOINT_2: 0.0,
vars.DATA_COOLING_CONTROL: 0,
vars.DATA_DHW_BURNER_HOURS: 411,
vars.DATA_DHW_BURNER_STARTS: 34296,
vars.DATA_DHW_FLOW_RATE: 0.0,
vars.DATA_DHW_PUMP_HOURS: 250,
vars.DATA_DHW_PUMP_STARTS: 9424,
vars.DATA_DHW_SETPOINT: 0.0,
vars.DATA_DHW_TEMP: 0.0,
vars.DATA_DHW_TEMP_2: 0.0,
vars.DATA_EXHAUST_TEMP: 0,
vars.DATA_MASTER_CH2_ENABLED: 0,
vars.DATA_MASTER_CH_ENABLED: 1,
vars.DATA_MASTER_COOLING_ENABLED: 0,
vars.DATA_MASTER_DHW_ENABLED: 1,
vars.DATA_MASTER_MEMBERID: 0,
vars.DATA_MASTER_OTC_ENABLED: 0,
vars.DATA_MASTER_OT_VERSION: 0.0,
vars.DATA_MASTER_PRODUCT_TYPE: 0,
vars.DATA_MASTER_PRODUCT_VERSION: 0,
vars.DATA_MAX_CH_SETPOINT: 75.0,
vars.DATA_OEM_DIAG: 0,
vars.DATA_OUTSIDE_TEMP: 0.0,
vars.DATA_REL_MOD_LEVEL: 0.0,
vars.DATA_REMOTE_RW_DHW: 1,
vars.DATA_REMOTE_RW_MAX_CH: 1,
vars.DATA_REMOTE_TRANSFER_DHW: 1,
vars.DATA_REMOTE_TRANSFER_MAX_CH: 1,
vars.DATA_RETURN_WATER_TEMP: 0.0,
vars.DATA_ROOM_SETPOINT: 20.0,
vars.DATA_ROOM_SETPOINT_2: 0.0,
vars.DATA_ROOM_SETPOINT_OVRD: 20.0,
vars.DATA_ROOM_TEMP: 19.62,
vars.DATA_ROVRD_AUTO_PRIO: 0,
vars.DATA_ROVRD_MAN_PRIO: 1,
vars.DATA_SLAVE_AIR_PRESS_FAULT: 0,
vars.DATA_SLAVE_CH2_ACTIVE: 0,
vars.DATA_SLAVE_CH2_PRESENT: 0,
vars.DATA_SLAVE_CH_ACTIVE: 1,
vars.DATA_SLAVE_CH_MAX_SETP: 75,
vars.DATA_SLAVE_CH_MIN_SETP: 20,
vars.DATA_SLAVE_CONTROL_TYPE: 1,
vars.DATA_SLAVE_COOLING_ACTIVE: 0,
vars.DATA_SLAVE_COOLING_SUPPORTED: 0,
vars.DATA_SLAVE_DHW_ACTIVE: 0,
vars.DATA_SLAVE_DHW_CONFIG: 0,
vars.DATA_SLAVE_DHW_MAX_SETP: 60,
vars.DATA_SLAVE_DHW_MIN_SETP: 40,
vars.DATA_SLAVE_DHW_PRESENT: 1,
vars.DATA_SLAVE_DIAG_IND: 0,
vars.DATA_SLAVE_FAULT_IND: 0,
vars.DATA_SLAVE_FLAME_ON: 1,
vars.DATA_SLAVE_GAS_FAULT: 0,
vars.DATA_SLAVE_LOW_WATER_PRESS: 0,
vars.DATA_SLAVE_MASTER_LOW_OFF_PUMP: 0,
vars.DATA_SLAVE_MAX_CAPACITY: 0,
vars.DATA_SLAVE_MAX_RELATIVE_MOD: 100.0,
vars.DATA_SLAVE_MEMBERID: 0,
vars.DATA_SLAVE_MIN_MOD_LEVEL: 0,
vars.DATA_SLAVE_OEM_FAULT: 0,
vars.DATA_SLAVE_OT_VERSION: 0.0,
vars.DATA_SLAVE_PRODUCT_TYPE: 0,
vars.DATA_SLAVE_PRODUCT_VERSION: 0,
vars.DATA_SLAVE_REMOTE_RESET: 0,
vars.DATA_SLAVE_SERVICE_REQ: 0,
vars.DATA_SLAVE_WATER_OVERTEMP: 0,
vars.DATA_SOLAR_COLL_TEMP: 0.0,
vars.DATA_SOLAR_STORAGE_TEMP: 0.0,
vars.DATA_TOTAL_BURNER_HOURS: 0,
vars.DATA_TOTAL_BURNER_STARTS: 0,
},
vars.OTGW: {
vars.OTGW_ABOUT: 'OpenTherm Gateway 4.2.5',
vars.OTGW_BUILD: '17:59 20-10-2015',
vars.OTGW_CLOCKMHZ: '4 MHz',
vars.OTGW_DHW_OVRD: '1',
vars.OTGW_GPIO_A: 0,
vars.OTGW_GPIO_A_STATE: 0,
vars.OTGW_GPIO_B: 0,
vars.OTGW_GPIO_B_STATE: 0,
vars.OTGW_IGNORE_TRANSITIONS: 1,
vars.OTGW_LED_A: 'F',
vars.OTGW_LED_B: 'X',
vars.OTGW_LED_C: 'O',
vars.OTGW_LED_D: 'M',
vars.OTGW_LED_E: 'P',
vars.OTGW_LED_F: 'C',
vars.OTGW_MODE: 'G',
vars.OTGW_OVRD_HB: 1,
vars.OTGW_SB_TEMP: 16.0,
vars.OTGW_SETP_OVRD_MODE: 'T',
vars.OTGW_SMART_PWR: 'Low power',
vars.OTGW_THRM_DETECT: 'D',
vars.OTGW_VREF: 3,
},
vars.THERMOSTAT: {
vars.DATA_CH_PUMP_HOURS: 15010,
vars.DATA_CH_PUMP_STARTS: 43832,
vars.DATA_CH_WATER_PRESS: 0.0,
vars.DATA_CH_WATER_TEMP: 47.2,
vars.DATA_CH_WATER_TEMP_2: 0.0,
vars.DATA_CONTROL_SETPOINT: 44.0,
vars.DATA_CONTROL_SETPOINT_2: 0.0,
vars.DATA_COOLING_CONTROL: 0,
vars.DATA_DHW_BURNER_HOURS: 411,
vars.DATA_DHW_BURNER_STARTS: 34296,
vars.DATA_DHW_FLOW_RATE: 0.0,
vars.DATA_DHW_PUMP_HOURS: 250,
vars.DATA_DHW_PUMP_STARTS: 9424,
vars.DATA_DHW_SETPOINT: 0.0,
vars.DATA_DHW_TEMP: 0.0,
vars.DATA_DHW_TEMP_2: 0.0,
vars.DATA_EXHAUST_TEMP: 0,
vars.DATA_MASTER_CH2_ENABLED: 0,
vars.DATA_MASTER_CH_ENABLED: 1,
vars.DATA_MASTER_COOLING_ENABLED: 0,
vars.DATA_MASTER_DHW_ENABLED: 1,
vars.DATA_MASTER_MEMBERID: 0,
vars.DATA_MASTER_OTC_ENABLED: 0,
vars.DATA_MASTER_OT_VERSION: 0.0,
vars.DATA_MASTER_PRODUCT_TYPE: 0,
vars.DATA_MASTER_PRODUCT_VERSION: 0,
vars.DATA_MAX_CH_SETPOINT: 75.0,
vars.DATA_OEM_DIAG: 0,
vars.DATA_OUTSIDE_TEMP: 0.0,
vars.DATA_REL_MOD_LEVEL: 0.0,
vars.DATA_REMOTE_RW_DHW: 1,
vars.DATA_REMOTE_RW_MAX_CH: 1,
vars.DATA_REMOTE_TRANSFER_DHW: 1,
vars.DATA_REMOTE_TRANSFER_MAX_CH: 1,
vars.DATA_RETURN_WATER_TEMP: 0.0,
vars.DATA_ROOM_SETPOINT: 20.0,
vars.DATA_ROOM_SETPOINT_2: 0.0,
vars.DATA_ROOM_SETPOINT_OVRD: 20.0,
vars.DATA_ROOM_TEMP: 19.62,
vars.DATA_ROVRD_AUTO_PRIO: 0,
vars.DATA_ROVRD_MAN_PRIO: 1,
vars.DATA_SLAVE_AIR_PRESS_FAULT: 0,
vars.DATA_SLAVE_CH2_ACTIVE: 0,
vars.DATA_SLAVE_CH2_PRESENT: 0,
vars.DATA_SLAVE_CH_ACTIVE: 1,
vars.DATA_SLAVE_CH_MAX_SETP: 75,
vars.DATA_SLAVE_CH_MIN_SETP: 20,
vars.DATA_SLAVE_CONTROL_TYPE: 1,
vars.DATA_SLAVE_COOLING_ACTIVE: 0,
vars.DATA_SLAVE_COOLING_SUPPORTED: 0,
vars.DATA_SLAVE_DHW_ACTIVE: 0,
vars.DATA_SLAVE_DHW_CONFIG: 0,
vars.DATA_SLAVE_DHW_MAX_SETP: 60,
vars.DATA_SLAVE_DHW_MIN_SETP: 40,
vars.DATA_SLAVE_DHW_PRESENT: 1,
vars.DATA_SLAVE_DIAG_IND: 0,
vars.DATA_SLAVE_FAULT_IND: 0,
vars.DATA_SLAVE_FLAME_ON: 1,
vars.DATA_SLAVE_GAS_FAULT: 0,
vars.DATA_SLAVE_LOW_WATER_PRESS: 0,
vars.DATA_SLAVE_MASTER_LOW_OFF_PUMP: 0,
vars.DATA_SLAVE_MAX_CAPACITY: 0,
vars.DATA_SLAVE_MAX_RELATIVE_MOD: 100.0,
vars.DATA_SLAVE_MEMBERID: 0,
vars.DATA_SLAVE_MIN_MOD_LEVEL: 0,
vars.DATA_SLAVE_OEM_FAULT: 0,
vars.DATA_SLAVE_OT_VERSION: 0.0,
vars.DATA_SLAVE_PRODUCT_TYPE: 0,
vars.DATA_SLAVE_PRODUCT_VERSION: 0,
vars.DATA_SLAVE_REMOTE_RESET: 0,
vars.DATA_SLAVE_SERVICE_REQ: 0,
vars.DATA_SLAVE_WATER_OVERTEMP: 0,
vars.DATA_SOLAR_COLL_TEMP: 0.0,
vars.DATA_SOLAR_STORAGE_TEMP: 0.0,
vars.DATA_TOTAL_BURNER_HOURS: 0,
vars.DATA_TOTAL_BURNER_STARTS: 0,
}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/mvn23/pyotgw",
"name": "pyotgw",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "opentherm gateway otgw",
"author": "Milan van Nugteren",
"author_email": "milan@network23.nl",
"download_url": "https://files.pythonhosted.org/packages/6e/9c/57e450180bd6be6453b8e39dd666e50fa489c33dd63447e79552d14c0cb8/pyotgw-2.2.2.tar.gz",
"platform": null,
"description": "[](https://travis-ci.org/mvn23/pyotgw)\n\n# pyotgw\n\nA python library to interface with the OpenTherm Gateway\n\nSee http://otgw.tclcode.com for the hardware.\n\nThis library is written primarily for use with Home Assistant (https://www.home-assistant.io) but can be used for other purposes as well.\nParts 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.\n\n#### Contents\n- [Library Reference](#library-reference)\n - [General](#general)\n - [Getting Data](#getting-data)\n - [Methods](#methods)\n- [Usage Example](#usage-example)\n- [Development](#development)\n- [Status Dict Structure](#status-dict-structure)\n\n### Library Reference\n\n#### General\npyotgw exposes its OpenThermGateway class which uses [pyserial-asyncio](https://pyserial-asyncio.readthedocs.io/en/latest/) to connect to the OpenTherm Gateway.\nAfter 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.\nThe 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.\n\n#### Getting Data\nThere 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.\n\n#### Methods\n\n---\n##### OpenThermGateway()\nThe OpenThermGateway constructor takes no arguments and returns an empty OpenThermGateway object.\n\n---\n##### OpenThermGateway.add_alternative(_self_, alt, timeout=OTGW_DEFAULT_TIMEOUT)\nAdd 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.\nAlternative 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.\nThis method supports the following arguments:\n- __alt__ The alternative data-ID to add. Values from 1 to 255 are allowed.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the ID that was added to the list, or None on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.add_unknown_id(_self_, unknown_id, timeout=OTGW_DEFAULT_TIMEOUT)\nInform 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.\nUsing this command allows the gateway to send an alternative data-ID to the boiler instead.\nThis method supports the following arguments:\n- __unknown_id__ The data-ID to mark as unsupported. Values from 1 to 255 are allowed.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the added ID, or None on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.connect(_self_, port, timeout=5, skip_init=None)\nConnect to an OpenTherm Gateway and initializes the parameters obtained from the `PS` and `PR` commands.\nIf called while connected, reconnect to the gateway.\nAll optional serial-related arguments default to the OpenTherm Gateway default settings.\nThis method supports the following arguments:\n- __port__ The port/url on which the OpenTherm Gateway can be reached as supported by [pyserial](https://pythonhosted.org/pyserial/url_handlers.html).\n- __timeout__ The inactivity timeout in seconds after which the watchdog will trigger a reconnect. Defaults to 5.\n- __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.\n\nReturns a status dict with all known values.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.disconnect(_self_)\nDisconnect from the OpenTherm Gateway and clean up the object.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.del_alternative(_self_, alt, timeout=OTGW_DEFAULT_TIMEOUT)\nRemove the specified data-ID from the list of alternative commands.\nOnly 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.\nThis method supports the following arguments:\n- __alt__ The alternative data-ID to remove. Values from 1 to 255 are allowed.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the ID that was removed from the list, or None on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.del_unknown_id(_self_, unknown_id, timeout=OTGW_DEFAULT_TIMEOUT)\nStart forwarding the specified Data-ID to the boiler again.\nThis command resets the counter used to determine if the specified data-ID is supported by the boiler.\nThis method supports the following arguments:\n- __unknown_id__ The data-ID to mark as supported. Values from 1 to 255 are allowed.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturn the ID that was marked as supported, or None on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.get_reports(_self_)\nUpdate the OpenThermGateway object with the information from all of the `PR` commands.\nThis method is also called from `OpenThermGateway.connect()` to populate the status dict with initial values.\n\nReturns the full updated status dict.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.get_status(_self_)\nUpdate the OpenThermGateway object with the information from the `PS` command.\nThis method is also called from `OpenThermGateway.connect()` to populate the status dict with initial values.\n\nReturns the full updated status dict.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_ch_enable_bit(_self_, ch_bit, timeout=OTGW_DEFAULT_TIMEOUT)\nSet or unset the `Central Heating Enable` bit.\nControl 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.\nThis method supports the following arguments:\n- __ch_bit__ The new value for the `Central Heating Enable` bit. Can be either `0` or `1`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturn the newly accepted value (`0` or `1`), or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_ch2_enable_bit(_self_, ch_bit, timeout=OTGW_DEFAULT_TIMEOUT)\nSet or unset the `Central Heating Enable` bit for heating circuit 2.\nControl 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.\nThis method supports the following arguments:\n- __ch_bit__ The new value for the `Central Heating Enable` bit. Can be either `0` or `1`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturn the newly accepted value (`0` or `1`), or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_clock(_self_, date=datetime.now(), timeout=OTGW_DEFAULT_TIMEOUT)\nSet the clock on the thermostat.\nChange 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.\nThis method supports the following arguments:\n- __date__ A datetime object containing the time and day of the week to be sent to the thermostat. Defaults to `datetime.now()`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns 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.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_connection_options(_self_, **kwargs)\nSet the serial connection parameters before calling connect().\nValid kwargs are 'baudrate', 'bytesize', 'parity' and 'stopbits'.\nReturns True on success, False on fail or if already connected.\nFor more information on the kwargs see the pyserial documentation.\n\n---\n##### OpenThermGateway.set_control_setpoint(_self_, setpoint, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the control setpoint.\nThe 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.\nThis method supports the following arguments:\n- __setpoint__ The new control setpoint.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted value, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_control_setpoint_2(_self_, setpoint, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the control setpoint for central heating circuit 2.\nThe 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.\nThis method supports the following arguments:\n- __setpoint__ The new control setpoint.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted value, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_dhw_setpoint(_self_, temperature, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the domestic hot water setpoint.\nThe domestic hot water setpoint is the target temperature for the hot water system. Not all boilers support this command.\nThis method supports the following arguments:\n- __temperature__ The new domestic hot water setpoint.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted setpoint, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_gpio_mode(_self_, gpio_id, mode, timeout=OTGW_DEFAULT_TIMEOUT)\nConfigure the functions of the two GPIO pins of the gateway.\nPossible modes are:\n- __0.__ No function, default for both ports on a freshly flashed chip.\n- __1.__ Ground - A permanently low output (0V). Could be used for a power LED.\n- __2.__ Vcc - A permanently high output (5V). Can be used as a short-proof power supply for some external circuitry used by the other GPIO port.\n- __3.__ LED E - An additional LED if you want to present more than 4 LED functions.\n- __4.__ LED F - An additional LED if you want to present more than 5 LED functions.\n- __5.__ Home - Set thermostat to setback temperature when pulled low.\n- __6.__ Away - Set thermostat to setback temperature when pulled high.\n- __7.__ DS1820 (GPIO port B only) - Data line for a DS18S20 or DS18B20 temperature sensor used to measure the outside temperature. A 4k7 resistor should be connected between GPIO port B and Vcc.\n\nThis method supports the following arguments:\n- __gpio_id__ The GPIO pin on which the mode is set. Either `A` or `B`.\n- __mode__ The requested mode for the GPIO pin. Values from `0` to `7` are supported (`7` only for GPIO `B`).\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the new mode for the specified gpio, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_hot_water_ovrd(_self_, state, timeout=OTGW_DEFAULT_TIMEOUT)\nControl the domestic hot water enable option.\nIf the boiler has been configured to let the room unit control when to keep a small amount of water preheated, this option can influence that. A state of `0` or `1` will override the domestic hot water option `off` or `on` respectively. Any other single character disables the override and resumes normal operation.\nThis method supports the following arguments:\n- __state__ The requested state for the domestic hot water option.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the accepted value, `A` if the override is disabled or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_led_mode(_self_, led_id, mode, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the mode of one of the LEDs.\nConfigure the functions of the six LEDs (A-F) that can optionally be connected to pins RB3/RB4/RB6/RB7 and the GPIO pins of the PIC.\nPossible modes are:\n- __R__ Receiving an Opentherm message from the thermostat or boiler\n- __X__ Transmitting an Opentherm message to the thermostat or boiler\n- __T__ Transmitting or receiving a message on the master interface\n- __B__ Transmitting or receiving a message on the slave interface\n- __O__ Remote setpoint override is active\n- __F__ Flame is on\n- __H__ Central heating is on\n- __W__ Hot water is on\n- __C__ Comfort mode (Domestic Hot Water Enable) is on\n- __E__ Transmission error has been detected\n- __M__ Boiler requires maintenance\n- __P__ Raised power mode active on thermostat interface.\n\nThis method supports the following arguments:\n- __led_id__ The LED for which the mode is set. Must be a character in the range `A-F`.\n- __mode__ The requested state for the LED. Must be one of `R`, `X`, `T`, `B`, `O`, `F`, `H`, `W`, `C`, `E`, `M` or `P`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the new mode for the specified LED, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_max_ch_setpoint(_self_, temperature, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the maximum central heating water setpoint.\nNot all boilers support this option.\n\nThis method supports the following arguments:\n- __temperature__ The new maximum central heating water setpoint.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted setpoint, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_max_relative_mod(_self_, max_mod, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the maximum relative modulation level.\nOverride the maximum relative modulation from the thermostat. Valid values are 0 through 100. Clear the setting by specifying a non-numeric value.\nThis method supports the following arguments:\n- __temperature__ The new maximum central heating water setpoint.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted value, `-` if a previous value was cleared, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_mode(_self_, mode, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the operating mode of the gateway.\nThe operating mode can be either `gateway` or `monitor` mode. This method can also be used to reset the OpenTherm Gateway.\nThis method supports the following arguments:\n- __mode__ The mode to be set on the gateway. Can be `0` or `OTGW_MODE_MONITOR` for `monitor` mode, `1` or `OTGW_MODE_GATEWAY` for `gateway mode, or `OTGW_MODE_RESET` to reset the gateway.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturn the newly activated mode, or the full renewed status dict after a reset.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_outside_temp(_self_, temp, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the outside temperature.\nConfigure the outside temperature to send to the thermostat. Allowed values are between -40.0 and +64.0, although thermostats may not display the full range. Specify a value above 64 (suggestion: 99) to clear a previously configured value.\nThis method supports the following arguments:\n- __temp__ The outside temperature to provide to the gateway.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the accepted value on success, `-` if a previously configured value has been cleared or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_setback_temp(_self_, sb_temp, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the setback temperature.\nConfigure the setback temperature to use in combination with the GPIO functions `home`(5) and `away`(6).\nThis method supports the following arguments:\n- __sb_temp__ The new setback temperature.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the new setback temperature, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_target_temp(_self_, temp, temporary=True, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the room setpoint.\nConfigure the thermostat setpoint and specify whether or not it may be overridden by a programmed change.\nThis method supports the following arguments:\n- __temp__ The new room setpoint. Will be formatted to 1 decimal.\n- __temporary__ Whether or not the thermostat program may override the room setpoint. Either `True` or `False`. Defaults to `True`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted room setpoint, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_temp_sensor_function(_self_, func, timeout=v.OTGW_DEFAULT_TIMEOUT):\nSet the function of the temperature sensor that can be attached to the gateway.\nThis method supports the following arguments:\n- __func__ The new temperature sensor function. Either `O` for `Outside Air Temperature` or `R` for `Return Water Temperature`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturns the newly accepted temperature sensor function or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.set_ventilation(_self_, pct, timeout=OTGW_DEFAULT_TIMEOUT)\nSet the ventilation setpoint.\nConfigure a ventilation setpoint override value (0-100%).\nThis method supports the following arguments:\n- __pct__ The new ventilation setpoint. Must be between `0` and `100`.\n- __timeout__ The timeout for the request. Defaults to OTGW_DEFAULT_TIMEOUT (3 seconds).\n\nReturn the newly accepted value, or `None` on failure.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.send_transparent_command(_self_, cmd, state, timeout=OTGW_DEFAULT_TIMEOUT)\nSend a transparent command.\nSends custom commands through a transparent interface.\nCheck https://otgw.tclcode.com/firmware.html for supported commands.\nThis method supports the following arguments:\n- __cmd__ The supported command e.g. `SC` (set time/day).\n- __state__ The command argument e.g. `23:59/4` (the current time/day)\n\nReturns the gateway response, which should be equal __state__.\n\nThis method is a coroutine.\n\n---\n##### OpenThermGateway.subscribe(_self_, coro)\nSubscribe to status updates from the Opentherm Gateway.\nThe subscribed coroutine must have the following signature:\n```\nasync def coro(status)\n```\nWhere `status` will be the full status dict containing the last known information from the OpenTherm Gateway.\nThis method supports the following arguments:\n- __coro__ A coroutine which will be called whenever a status change occurs.\n\nReturns `True` on success, `False` if the coroutine is already subscribed.\n\n---\n##### OpenThermGateway.unsubscribe(_self_, coro)\nUnsubscribe from status updates from the Opentherm Gateway.\nThe supplied coroutine must have been subscribed with `OpenThermGateway.subscribe()` before.\nThis method supports the following arguments:\n- __coro__ The coroutine which will be unsubscribed.\n\nReturns `True` on success, `False` if the coroutine was not subscribed before.\n\n---\n\n\n### Usage Example\n```python\nimport asyncio\nfrom pyotgw import OpenThermGateway\n\nPORT = '/dev/ttyUSB0'\n\n\nasync def print_status(status):\n \"\"\"Receive and print status.\"\"\"\n print(\"Received a status update:\\n{}\".format(status))\n\n\nasync def connect_and_subscribe():\n \"\"\"Connect to the OpenTherm Gateway and subscribe to status updates.\"\"\"\n\n # Create the object\n gw = OpenThermGateway()\n\n # Connect to OpenTherm Gateway on PORT\n status = await gw.connect(PORT)\n print(\"Initial status after connecting:\\n{}\".format(status))\n\n # Subscribe to updates from the gateway\n if not gw.subscribe(print_status):\n print(\"Could not subscribe to status updates.\")\n\n # Keep the event loop alive...\n while True:\n await asyncio.sleep(1)\n\n\n# Run the connect_and_subscribe coroutine.\ntry:\n asyncio.run(connect_and_subscribe())\nexcept KeyboardInterrupt:\n print(\"Exiting\")\n\n```\n\n### Development\nWe use pre-commit to ensure a consistent code style, so `pip install pre_commit` and run\n```\npre-commit install\n```\nin the repository.\n\n### Status Dict Structure\nThe full possible status dict with some example values looks like below. Note that not all keys will always be present and that the presence of a key does not guarantee that it contains useful information.\n\n```python\n{\n vars.BOILER: {\n vars.DATA_CH_PUMP_HOURS: 15010,\n vars.DATA_CH_PUMP_STARTS: 43832,\n vars.DATA_CH_WATER_PRESS: 0.0,\n vars.DATA_CH_WATER_TEMP: 47.2,\n vars.DATA_CH_WATER_TEMP_2: 0.0,\n vars.DATA_CONTROL_SETPOINT: 44.0,\n vars.DATA_CONTROL_SETPOINT_2: 0.0,\n vars.DATA_COOLING_CONTROL: 0,\n vars.DATA_DHW_BURNER_HOURS: 411,\n vars.DATA_DHW_BURNER_STARTS: 34296,\n vars.DATA_DHW_FLOW_RATE: 0.0,\n vars.DATA_DHW_PUMP_HOURS: 250,\n vars.DATA_DHW_PUMP_STARTS: 9424,\n vars.DATA_DHW_SETPOINT: 0.0,\n vars.DATA_DHW_TEMP: 0.0,\n vars.DATA_DHW_TEMP_2: 0.0,\n vars.DATA_EXHAUST_TEMP: 0,\n vars.DATA_MASTER_CH2_ENABLED: 0,\n vars.DATA_MASTER_CH_ENABLED: 1,\n vars.DATA_MASTER_COOLING_ENABLED: 0,\n vars.DATA_MASTER_DHW_ENABLED: 1,\n vars.DATA_MASTER_MEMBERID: 0,\n vars.DATA_MASTER_OTC_ENABLED: 0,\n vars.DATA_MASTER_OT_VERSION: 0.0,\n vars.DATA_MASTER_PRODUCT_TYPE: 0,\n vars.DATA_MASTER_PRODUCT_VERSION: 0,\n vars.DATA_MAX_CH_SETPOINT: 75.0,\n vars.DATA_OEM_DIAG: 0,\n vars.DATA_OUTSIDE_TEMP: 0.0,\n vars.DATA_REL_MOD_LEVEL: 0.0,\n vars.DATA_REMOTE_RW_DHW: 1,\n vars.DATA_REMOTE_RW_MAX_CH: 1,\n vars.DATA_REMOTE_TRANSFER_DHW: 1,\n vars.DATA_REMOTE_TRANSFER_MAX_CH: 1,\n vars.DATA_RETURN_WATER_TEMP: 0.0,\n vars.DATA_ROOM_SETPOINT: 20.0,\n vars.DATA_ROOM_SETPOINT_2: 0.0,\n vars.DATA_ROOM_SETPOINT_OVRD: 20.0,\n vars.DATA_ROOM_TEMP: 19.62,\n vars.DATA_ROVRD_AUTO_PRIO: 0,\n vars.DATA_ROVRD_MAN_PRIO: 1,\n vars.DATA_SLAVE_AIR_PRESS_FAULT: 0,\n vars.DATA_SLAVE_CH2_ACTIVE: 0,\n vars.DATA_SLAVE_CH2_PRESENT: 0,\n vars.DATA_SLAVE_CH_ACTIVE: 1,\n vars.DATA_SLAVE_CH_MAX_SETP: 75,\n vars.DATA_SLAVE_CH_MIN_SETP: 20,\n vars.DATA_SLAVE_CONTROL_TYPE: 1,\n vars.DATA_SLAVE_COOLING_ACTIVE: 0,\n vars.DATA_SLAVE_COOLING_SUPPORTED: 0,\n vars.DATA_SLAVE_DHW_ACTIVE: 0,\n vars.DATA_SLAVE_DHW_CONFIG: 0,\n vars.DATA_SLAVE_DHW_MAX_SETP: 60,\n vars.DATA_SLAVE_DHW_MIN_SETP: 40,\n vars.DATA_SLAVE_DHW_PRESENT: 1,\n vars.DATA_SLAVE_DIAG_IND: 0,\n vars.DATA_SLAVE_FAULT_IND: 0,\n vars.DATA_SLAVE_FLAME_ON: 1,\n vars.DATA_SLAVE_GAS_FAULT: 0,\n vars.DATA_SLAVE_LOW_WATER_PRESS: 0,\n vars.DATA_SLAVE_MASTER_LOW_OFF_PUMP: 0,\n vars.DATA_SLAVE_MAX_CAPACITY: 0,\n vars.DATA_SLAVE_MAX_RELATIVE_MOD: 100.0,\n vars.DATA_SLAVE_MEMBERID: 0,\n vars.DATA_SLAVE_MIN_MOD_LEVEL: 0,\n vars.DATA_SLAVE_OEM_FAULT: 0,\n vars.DATA_SLAVE_OT_VERSION: 0.0,\n vars.DATA_SLAVE_PRODUCT_TYPE: 0,\n vars.DATA_SLAVE_PRODUCT_VERSION: 0,\n vars.DATA_SLAVE_REMOTE_RESET: 0,\n vars.DATA_SLAVE_SERVICE_REQ: 0,\n vars.DATA_SLAVE_WATER_OVERTEMP: 0,\n vars.DATA_SOLAR_COLL_TEMP: 0.0,\n vars.DATA_SOLAR_STORAGE_TEMP: 0.0,\n vars.DATA_TOTAL_BURNER_HOURS: 0,\n vars.DATA_TOTAL_BURNER_STARTS: 0,\n },\n vars.OTGW: {\n vars.OTGW_ABOUT: 'OpenTherm Gateway 4.2.5',\n vars.OTGW_BUILD: '17:59 20-10-2015',\n vars.OTGW_CLOCKMHZ: '4 MHz',\n vars.OTGW_DHW_OVRD: '1',\n vars.OTGW_GPIO_A: 0,\n vars.OTGW_GPIO_A_STATE: 0,\n vars.OTGW_GPIO_B: 0,\n vars.OTGW_GPIO_B_STATE: 0,\n vars.OTGW_IGNORE_TRANSITIONS: 1,\n vars.OTGW_LED_A: 'F',\n vars.OTGW_LED_B: 'X',\n vars.OTGW_LED_C: 'O',\n vars.OTGW_LED_D: 'M',\n vars.OTGW_LED_E: 'P',\n vars.OTGW_LED_F: 'C',\n vars.OTGW_MODE: 'G',\n vars.OTGW_OVRD_HB: 1,\n vars.OTGW_SB_TEMP: 16.0,\n vars.OTGW_SETP_OVRD_MODE: 'T',\n vars.OTGW_SMART_PWR: 'Low power',\n vars.OTGW_THRM_DETECT: 'D',\n vars.OTGW_VREF: 3,\n },\n vars.THERMOSTAT: {\n vars.DATA_CH_PUMP_HOURS: 15010,\n vars.DATA_CH_PUMP_STARTS: 43832,\n vars.DATA_CH_WATER_PRESS: 0.0,\n vars.DATA_CH_WATER_TEMP: 47.2,\n vars.DATA_CH_WATER_TEMP_2: 0.0,\n vars.DATA_CONTROL_SETPOINT: 44.0,\n vars.DATA_CONTROL_SETPOINT_2: 0.0,\n vars.DATA_COOLING_CONTROL: 0,\n vars.DATA_DHW_BURNER_HOURS: 411,\n vars.DATA_DHW_BURNER_STARTS: 34296,\n vars.DATA_DHW_FLOW_RATE: 0.0,\n vars.DATA_DHW_PUMP_HOURS: 250,\n vars.DATA_DHW_PUMP_STARTS: 9424,\n vars.DATA_DHW_SETPOINT: 0.0,\n vars.DATA_DHW_TEMP: 0.0,\n vars.DATA_DHW_TEMP_2: 0.0,\n vars.DATA_EXHAUST_TEMP: 0,\n vars.DATA_MASTER_CH2_ENABLED: 0,\n vars.DATA_MASTER_CH_ENABLED: 1,\n vars.DATA_MASTER_COOLING_ENABLED: 0,\n vars.DATA_MASTER_DHW_ENABLED: 1,\n vars.DATA_MASTER_MEMBERID: 0,\n vars.DATA_MASTER_OTC_ENABLED: 0,\n vars.DATA_MASTER_OT_VERSION: 0.0,\n vars.DATA_MASTER_PRODUCT_TYPE: 0,\n vars.DATA_MASTER_PRODUCT_VERSION: 0,\n vars.DATA_MAX_CH_SETPOINT: 75.0,\n vars.DATA_OEM_DIAG: 0,\n vars.DATA_OUTSIDE_TEMP: 0.0,\n vars.DATA_REL_MOD_LEVEL: 0.0,\n vars.DATA_REMOTE_RW_DHW: 1,\n vars.DATA_REMOTE_RW_MAX_CH: 1,\n vars.DATA_REMOTE_TRANSFER_DHW: 1,\n vars.DATA_REMOTE_TRANSFER_MAX_CH: 1,\n vars.DATA_RETURN_WATER_TEMP: 0.0,\n vars.DATA_ROOM_SETPOINT: 20.0,\n vars.DATA_ROOM_SETPOINT_2: 0.0,\n vars.DATA_ROOM_SETPOINT_OVRD: 20.0,\n vars.DATA_ROOM_TEMP: 19.62,\n vars.DATA_ROVRD_AUTO_PRIO: 0,\n vars.DATA_ROVRD_MAN_PRIO: 1,\n vars.DATA_SLAVE_AIR_PRESS_FAULT: 0,\n vars.DATA_SLAVE_CH2_ACTIVE: 0,\n vars.DATA_SLAVE_CH2_PRESENT: 0,\n vars.DATA_SLAVE_CH_ACTIVE: 1,\n vars.DATA_SLAVE_CH_MAX_SETP: 75,\n vars.DATA_SLAVE_CH_MIN_SETP: 20,\n vars.DATA_SLAVE_CONTROL_TYPE: 1,\n vars.DATA_SLAVE_COOLING_ACTIVE: 0,\n vars.DATA_SLAVE_COOLING_SUPPORTED: 0,\n vars.DATA_SLAVE_DHW_ACTIVE: 0,\n vars.DATA_SLAVE_DHW_CONFIG: 0,\n vars.DATA_SLAVE_DHW_MAX_SETP: 60,\n vars.DATA_SLAVE_DHW_MIN_SETP: 40,\n vars.DATA_SLAVE_DHW_PRESENT: 1,\n vars.DATA_SLAVE_DIAG_IND: 0,\n vars.DATA_SLAVE_FAULT_IND: 0,\n vars.DATA_SLAVE_FLAME_ON: 1,\n vars.DATA_SLAVE_GAS_FAULT: 0,\n vars.DATA_SLAVE_LOW_WATER_PRESS: 0,\n vars.DATA_SLAVE_MASTER_LOW_OFF_PUMP: 0,\n vars.DATA_SLAVE_MAX_CAPACITY: 0,\n vars.DATA_SLAVE_MAX_RELATIVE_MOD: 100.0,\n vars.DATA_SLAVE_MEMBERID: 0,\n vars.DATA_SLAVE_MIN_MOD_LEVEL: 0,\n vars.DATA_SLAVE_OEM_FAULT: 0,\n vars.DATA_SLAVE_OT_VERSION: 0.0,\n vars.DATA_SLAVE_PRODUCT_TYPE: 0,\n vars.DATA_SLAVE_PRODUCT_VERSION: 0,\n vars.DATA_SLAVE_REMOTE_RESET: 0,\n vars.DATA_SLAVE_SERVICE_REQ: 0,\n vars.DATA_SLAVE_WATER_OVERTEMP: 0,\n vars.DATA_SOLAR_COLL_TEMP: 0.0,\n vars.DATA_SOLAR_STORAGE_TEMP: 0.0,\n vars.DATA_TOTAL_BURNER_HOURS: 0,\n vars.DATA_TOTAL_BURNER_STARTS: 0,\n }\n}\n```\n",
"bugtrack_url": null,
"license": "GPLv3+",
"summary": "A library to interface with the opentherm gateway through serial or network connection.",
"version": "2.2.2",
"project_urls": {
"Homepage": "https://github.com/mvn23/pyotgw"
},
"split_keywords": [
"opentherm",
"gateway",
"otgw"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d419713943add3956ec6afb5d4e941fae6a86a787c0907987a6e77a33dd22c46",
"md5": "b66ce33c50661aed5f9e4f7f01e65b35",
"sha256": "d85cc669f80262a28f01967304bdd28a5c01d96b003fb9aadbbfbbdf1382de4d"
},
"downloads": -1,
"filename": "pyotgw-2.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b66ce33c50661aed5f9e4f7f01e65b35",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 42181,
"upload_time": "2024-10-17T14:54:24",
"upload_time_iso_8601": "2024-10-17T14:54:24.441809Z",
"url": "https://files.pythonhosted.org/packages/d4/19/713943add3956ec6afb5d4e941fae6a86a787c0907987a6e77a33dd22c46/pyotgw-2.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6e9c57e450180bd6be6453b8e39dd666e50fa489c33dd63447e79552d14c0cb8",
"md5": "54fef9864e7ab44d1423ca2d8af5741d",
"sha256": "1f82896afb385411e3421076fa7edef49af219e34322d3dbc1ea5e8104161c5b"
},
"downloads": -1,
"filename": "pyotgw-2.2.2.tar.gz",
"has_sig": false,
"md5_digest": "54fef9864e7ab44d1423ca2d8af5741d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 56569,
"upload_time": "2024-10-17T14:54:27",
"upload_time_iso_8601": "2024-10-17T14:54:27.401402Z",
"url": "https://files.pythonhosted.org/packages/6e/9c/57e450180bd6be6453b8e39dd666e50fa489c33dd63447e79552d14c0cb8/pyotgw-2.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 14:54:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mvn23",
"github_project": "pyotgw",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "pyotgw"
}
JSON
