Configuration for Domoticz

Domoticz logo

To use the Gateway with Domoticz you need to install a plugin.

Note

There are so many ongoing changes, its very hard to keep the Domoticz plugin in sync with EMS-ESP32. So there is often a lag in parameters. Also the Domoticz Python plugin framework does not handle plugins with lots of devices very well. I’m going to split up the plugin so more devices are supported.

First check the ‘configuring MQTT’ page to make sure everything is ready.

Installing the plugin

To install the plugin, open a terminal to your Domoticz system. You can use f.i. Putty 1.

If you have Git installed (preferred method):

Go to the domoticz/plugins directory and run

git clone https://github.com/bbqkees/ems-esp-domoticz-plugin.git

Or as an alternative you can do the following (not recommended): Create a new directory ‘ems-gateway’ in the folder domoticz/plugins. Copy the files mqtt.py and plugin.py to this new domoticz/plugins/ems-gateway directory.

Make sure that ‘Accept new Hardware Devices’ is enabled in settings/system. Now start the domoticz service (by typing sudo systemctl start domoticz in the shell). Create a new hardware of the type “EMS bus Wi-Fi Gateway”. (Do not create a hardware of the type ‘MQTT Client Gateway’, this is something different). See the image below.

Domoticz plugin selection

Configuring the plugin

Set the MQTT server and port

Usually the MQTT server is running on the same machine as Domoticz. If so, you can leave the IP and port to its default setting.

Domoticz plugin parameters

Optionally you can set a username and password here. By default this is empty.

Setting the correct topics

The plugin listens to the topics preceded by “ems-esp/”. Don’t forget that / at the end.

Also make sure you don’t change the host name of the Gateway otherwise the topic will change as well! In the latest plugin version you can change the topic string to your own preference.

Setting MQTT format

You need to set the MQTT format to ‘nested’ otherwise the plugin won’t work properly.

Using the plugin

The plugin subscribes and publishes to the default MQTT topics of the Gateway. On the first run the plugin will create several devices and sensors in Domoticz, depending on which parameters it found.

The plugin captures the messages and updates the Domoticz devices and sensors automatically. Go to the ‘Devices’ tab in Domoticz and search for the devices that are created. You can now add each device to Domoticz by clicking on the small green arrow with ‘Add Device’.

Domoticz plugin devices

You can do this for all parameters you find interesting.

Domoticz devices

Heating circuits

The EMS bus supports 4 heating circuit (HC1 to HC4). Depending on your setup one or more heating circuits may be used. It is not always clear which heating circuits are in use. If you have a Nefit boiler with a single thermostat, the heating circuit used will almost always be 1. If you have a f.i. a Buderus boiler with a RC35 thermost, it might be that circuit 2 and 4 are used.

The plugin will only create thermostat devices in Domoticz for heating circuits it detected. You can figure out which one is used by adding all of them and changing the thermostat temperature and see which thermostat device in Domoticz changes.

Counters

In the latest (development) version of the plugin several counters were added like burner starts and UBA uptime. Be default, Domoticz might set these counters as kWh meters. When you have added these devices in Domoticz and the format is incorrect, you have to edit each device and set it to ‘type’ ‘counter’. For the counters that add up time set the ‘Value Units’ to ‘min’.

Updating the plugin

To update the plugin, stop the Domoticz service (by typing sudo systemctl stop domoticz in the shell). Then copy the new plugin.py file to the plugin folder and overwrite the existing file. Or if you used the ‘git clone’ command to initially install the plugin just navigate to the plugin folder and type:

git pull

Now restart the domoticz service:

sudo systemctl restart domoticz

On first run of the plugin (takes a minute maybe) additional devices will be created automatically if they were not defined before. Existing devices will not change.