Python OTGW MQTT bridge

This package allows for communication between an OpenTherm Gateway, running the firmware by Schelte Bron and an MQTT service. It was tested using Home Assistant's built-in MQTT broker.

Supported OTGW gateway communication protocols

Currently, only direct serial and TCP communication are supported, but implementing further types is pretty easy. I'm open to pull requests.

NOTE: TCP connections are, as yet, untested. Please open an issue if you're experiencing difficulties.

Supported MQTT brokers

The MQTT client used is paho. It's one of the most widely-used MQTT clients for Python, so it should work on most brokers. If you're having problems with a certain type, please open an issue or send me a pull request with a fix.

Configuration

The configuration for the bridge is located in config.json.

Example configuration

To use the serial connection to the OTGW, use a config.json like the following:

{
    "otgw" : {
        "type": "serial",
        "device": "/dev/ttyUSB0",
        "baudrate": 9600
    },
    "mqtt" : {
        "client_id": "otgw",
        "host": "127.0.0.1",
        "port": 1883,
        "keepalive": 60,
        "bind_address": "",
        "username": null,
        "password": null,
        "qos": 0,
        "pub_topic_namespace": "value/otgw",
        "sub_topic_namespace": "set/otgw"
    }
}

To use a TCP connection, replace the OTGW section with this:

    "otgw" : {
        "type": "tcp",
        "host": "<OTGW HOSTNAME OR IP>",
        "port": 2323
    },

Installation

To install this script as a daemon, run the following commands (on a Debian-based distribution):

Install dependencies:
```
sudo apt install python python-serial
```

Create a new folder, for example:

sudo mkdir -p /usr/lib/py-otgw-mqtt
cd /usr/lib/py-otgw-mqtt

Clone this repository into the current directory:

sudo git clone https://github.com/martenjacobs/py-otgw-mqtt.git .

Change config.json with your favorite text editor
Copy the service file to the systemd directory. If you used a different folder name than /usr/lib/py-otgw-mqtt you will need to change the WorkingDirectory in the file first.
```
sudo cp ./py-otgw-mqtt.service /etc/systemd/system/
```

Enable the service so it starts up on boot:

sudo systemctl daemon-reload
sudo systemctl enable py-otgw-mqtt.service

Start up the service

sudo systemctl start py-otgw-mqtt.service

View the log to see if everything works
```
journalctl -u py-otgw-mqtt.service -f
```

Topics

Publish topics

By default, the service publishes messages to the following MQTT topics:

value/otgw => The status of the service
value/otgw/flame_status
value/otgw/flame_status_ch
value/otgw/flame_status_dhw
value/otgw/flame_status_bit
value/otgw/control_setpoint
value/otgw/remote_override_setpoint
value/otgw/max_relative_modulation_level
value/otgw/room_setpoint
value/otgw/relative_modulation_level
value/otgw/ch_water_pressure
value/otgw/room_temperature
value/otgw/boiler_water_temperature
value/otgw/dhw_temperature
value/otgw/outside_temperature
value/otgw/return_water_temperature
value/otgw/dhw_setpoint
value/otgw/max_ch_water_setpoint
value/otgw/burner_starts
value/otgw/ch_pump_starts
value/otgw/dhw_pump_starts
value/otgw/dhw_burner_starts
value/otgw/burner_operation_hours
value/otgw/ch_pump_operation_hours
value/otgw/dhw_pump_valve_operation_hours
value/otgw/dhw_burner_operation_hours

If you've changed the pub_topic_namespace value in the configuration, replace value/otgw with your configured value. TODO: Add description of all topics

Subscription topics

By default, the service listens to messages from the following MQTT topics:

set/otgw/room_setpoint/temporary - TT - Float
set/otgw/room_setpoint/constant - TC - Float
set/otgw/outside_temperature - OT - Float
set/otgw/hot_water/enable - HW - Boolean
set/otgw/hot_water/temperature - SW - Float
set/otgw/central_heating/enable - CH - Boolean
set/central_heating/temperature - SH - Float
set/control_setpoint - CS - Float
set/max_modulation - MM - Integer 0-100

TODO: Add description of all topics

choeflake/py-otgw-mqtt