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 communication is supported, but implementing further types is pretty easy. I'm open to pull requests.

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

{
    "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"
    }
}

Installation

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

1. Install dependencies:

   sudo apt install python python-serial

2. Create a new folder, for example:

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

3. Clone this repository into the current directory:

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

4. Change config.json with your favorite text editor
5. 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/

6. Enable the service so it starts up on boot:

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

7. Start up the service

   sudo systemctl start py-otgw-mqtt.service

8. 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
• set/otgw/room_setpoint/constant
• set/otgw/outside_temperature
• set/otgw/hot_water/enable
• set/otgw/hot_water/temperature
• set/otgw/central_heating/enable

TODO: Add description of all topics