Configuring MQTT

The Gateway will communicate with your home automation system via the MQTT protocol.

The Gateway acts as a MQTT client and communicates with a MQTT server (also called a broker). For this you need a MQTT broker/server installed on your machine. Usually this is Mosquitto 1. If you are using Home Assistant or Domoticz, often this is pre-installed already.

Check if you have a MQTT broker/server

You can check if your machine has mosquitto installed. Open a SSH terminal on the machine your home automation system is running (f.i. a Raspberry Pi). Type in f.i. mosquitto_pub in the terminal. If it says ‘command not found’ you need to install Mosquitto 2 first. If you get a list of options, or an error that it is already running, Mosquitto is installed.

Although usually the MQTT server is running on the same machine as your home automation system, it is also possible it is installed elsewhere.

Configuring MQTT

When you have installed Mosquitto, it’s a good idea to

Note

Mosquitto version 2.0 and up have elevated security. If you get a ‘TCP Disconnected’ status here, check below. If you have installed Mosquitto 2.0 or higher, you need to configure Mosquitto such that it allows connections outside of local host, and you explicitely need to configure an authentication method for each listener. Also in case you don’t want to set a user and password. See: Migrating Mosquitto to 2.0 3.

In case you don’t want to set a user add the following to the mosquitto.conf file:

listener 1883
allow_anonymous true

The following sections are different for EMS-ESP V2 and EMS-ESP32 V3. Please check your version.

Making the appropriate settings for EMS-ESP32 V3

MQTT server address and configuration

Go back to the web interface of the Gateway. Go to ‘Settings’ and click on ‘MQTT settings’.

Usually the only setting you need to change here is the ‘host’. Type in the IP address of the machine your MQTT server is running om in and click on ‘Save’. Normally you can leave all other setting to its default as shown. Optionally set a username and password if your MQTT broker demands authentication.

The Client ID is ‘ems-esp’ by default. You can change this to something else but do not leave it empty. Otherwise the MQTT broker can refuse connection.

Topic/Payload Format

Values:

• Nested on a single topic

• As individual topics

Dallas Sensor Payload Grouping

If you have connected Dallas sensors, you can choose how the topic is formed. This can be grouped by either the unique sensor ID or by the sensor number order as they are detected on the bus.

Values:

• By Sensor ID

• By Number

For the Domoticz plugin use: ‘By Number’.

Example output ‘By Sensor ID’:

{"28-AD1C-2606-0000":45.5,"28-6D91-2706-0000":27.3}

Example output ‘By number’:

{"sensor1":{"id":"28-AD1C-2606-0000","temp":45.6},"sensor2":{"id":"28-6D91-2706-0000","temp":27.3}}

Boolean Format

Some parameters in MQTT are of the type Boolean, which basically means its a parameter that is either on or off. How this on and off is signalled, can be set to your preference.

Values:

• “on”/”off”

• true/false

• 1/0

• “ON”/”OFF”

For the Domoticz plugin it needs to be set to: “on”/”off”.

Subscribe Format

Values:

• General device topic

• individual topics, main heating circuit

• individual topics, all heating circuits

Use Home Assistant Auto Discovery

Enable this checkbox if you want to use Home Assistant Auto discovery feature. Leave it unchecked if you are using f.i. Domoticz or Loxone.

If everything went well, going to ‘MQTT Status’ will show ‘MQTT connected’. If it doesn’t, go to the troubleshooting section.

Note

After every change to MQTT settings, restart the Gateway and the MQTT broker otherwise the changes might not take effect.

../images/firmware/v3-0/webinterface-tab-mqtt.png

Making the appropriate settings for EMS-ESP V2

MQTT server address and configuration

Go back to the web interface of the Gateway. Go to ‘Settings’ and click on ‘MQTT settings’.

Usually the only setting you need to change here is the ‘host’. Type in the IP address of the machine your MQTT server is running om in and click on ‘Save’. Normally you can leave all other setting to its default as shown. Optionally set a username and password if your MQTT broker demands authentication.

The Client ID is ‘ems-esp’ by default. You can change this to something else but do not leave it empty. Otherwise the MQTT broker can refuse connection.

MQTT format

The MQTT format can be set to several types.

Format	Description
Single	Single gives each device its own topic.
Nested	Nested means that all parameters of one device (boiler, solar) will be nested into one topic. If you use Domoticz, set it to nested otherwise the plugin wont work.
Home Assistant	This mode is for Home Assistant auto discovery. This awesome feature will let HA discover all parameters of the Gateway automatically.

If everything went well, going to ‘MQTT Status’ will show ‘MQTT connected’. If it doesn’t, go to the troubleshooting section.

Note

After every change to MQTT settings, restart the Gateway and the MQTT broker otherwise the changes might not take effect.

Go back to the web interface of the Gateway. Go to ‘Settings’ and click on ‘MQTT settings’.

Usually the only setting you need to change here is the ‘host’. Type in the IP address of the machine your MQTT server is running om in and click on ‘Save’. Normally you can leave all other setting to its default as shown. Optionally set a username and password if your MQTT broker demands authentication.

The Client ID is ‘ems-esp’ by default. You can change this to something else but do not leave it empty. Otherwise the MQTT broker can refuse connection.

The MQTT format can be set to several types.

Format	Description
Single	Single gives each device its own topic.
Nested	Nested means that all parameters of one device (boiler, solar) will be nested into one topic. If you use Domoticz, set it to nested otherwise the plugin wont work.
Home Assistant	This mode is for Home Assistant auto discovery. This awesome feature will let HA discover all parameters of the Gateway automatically.

If everything went well, going to ‘MQTT Status’ will show ‘MQTT connected’. If it doesn’t, go to the troubleshooting section.

Note

After every change to MQTT settings, restart the Gateway and the MQTT broker otherwise the changes might not take effect.

1

http://mosquitto.org/

2

https://www.sigmdel.ca/michel/ha/rpi/add_mqtt_en.html

3

https://mosquitto.org/documentation/migrating-to-2-0/