Configuration for Domoticz

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

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: 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 “home/ems-esp/”. In the latest EMS-ESP firmware versions the default topic is just “ems-esp”. To change this go to the Gateway web interface and to the MQTT settings. Now set the Base parameter to “home”.

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.

Set the right MQTT update frequency

By default the Gateway will publish the set of MQTT messages every 60 or 120 seconds. For temperature and general logging this is a good update frequency. However, this is too slow if you also want to capture short events like turning on the warm water for 30 seconds. If needed you can change the frequency in the web interface in ‘Custom Settings’ -> ‘Publish Time’. Don’t set it too low as it will bombard Domoticz with messages.

Web interface custom status

If you set this to zero, MQTT messages will be sent as soon as an EMS bus message has been received. However, this function is still under development.

Using the plugin

On the first run the plugin will create several devices and sensors in Domoticz. The plugin then subscribes and publishes to the default MQTT topics of the Gateway. 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 create thermostat devices in Domoticz for all 4 heating circuits. 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 will set these counters as kWh meters. When you have added these devices in Domoticz 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.

More info

For more details please consult EMS-ESP Domoticz plugin repository [2].