EMS-ESP32/docs/MQTT.md

MQTT configuration options

QOS

The QOS (Quality Of Service) is configurable within telnet (mqtt_qos) and WebUI. Valid options are At most once (0) At least once (1) and Exactly once (2). The default is 0.

Keep Alive

Likewise the Keep Alive (mqtt_keepalive) can be set. Keep alive ensures that the connection between the broker and client is still open and that the broker and the client are aware of being connected. This value is the number of seconds before giving up on a response and default set to 60 (1 minute). The lower the number the more WiFi traffic but greater the stability.

Retain

mqtt_retain sets the MQTT retain flag for all published messages on the broker. It's set to off as default.

HiveMQ has a good explanation of MQTT.

MQTT topics

all topics are prefixed with [base]/[host name]/ where both base and host name are configurable in the Web UI. The default is home/ems-esp/.

If you want to configure the topic names, these can be changed in the file src/my_config.h.

Publishing Topics

All the key information from each of the EMS devices connected (Boilers, Thermostats, Solar Modules etc) are sent periodically on a single MQTT topic. The frequency of these publishes can be adjusted by the publish_time parameter which is set to 2 minutes (120 seconds) as default.

If the data in the payload has not changed since the last publish, it is ignored. Although from version 1.9.4 this can also be configured with the publish_always command and WebUI parameter. For example set publish_always on will always publish MQTT topics regardless if any of the data parameters have changed.

The table below shows examples of the topics being published:

Topic	Description	Payload Example
sensors	temperature readings from any external Dallas sensors attached to the ESP	{"temp_1":"20.18","temp_2":"40.81"}
start	this is the MQTT will and testament messages	online or offline
heartbeat	if enabled send out key system stats in JSON	{"version":"1.9.3b3","IP":"10.10.10.198","rssid":68,"load":100,"uptime":4,"freemem":68,"MQTTdisconnects":0}
tapwater_active	individual message if using a boolean sensor to show if hot tap water is running	0 or 1
heating_active	individual message if using a boolean sensor to show if heating is on	0 or 1
boiler_data	all the key data from the Boiler device	{"wWComfort":"Hot","wWSelTemp":54,.... (see the example in the Monitoring MQTT section below)
thermostat_data	data from each of the Thermometer's Heating Circuits. Default HC is 1. The data sent depends on the model.	{ "hc1":{"seltemp":15,"currtemp":20.6,"mode":"auto"}, "hc2":{"seltemp":8,"currtemp":18.2,"mode":"off"} }
mixing_data	data from The Mixing Module for each of the Thermometer's Heating Circuits.	{"hc1":{"flowTemp":55,"pumpMod":"1","valveStatus":"1"}}
shower_data	the shower timer and alert toggles plus the duration of the last shower taken	{"timer":"0","alert":"0","duration":"4 minutes 32 seconds"}
sm_data	all data from the Solar Module (if connected)	JSON with collectortemp bottomtemp pumpmodulation pump energylasthour energytoday energytotal pumpWorkMin
hp_data	all data from the Heat Pump (if connected)	{"pumpmodulation":"1", "pumpspeed": 20}

Receiving Topics

EMS-ESP subscribes to the following topics used to send commands to the device:

Topic	Description	Payload Format	Example
start	this is the MQTT will and testament messages back from the broker	online or offline	offline
restart	restarts the ESP
thermostat_cmd_temp<n>	sets the thermostat current setpoint temperature to the Heating Circuit n (1-4). This is specific for the Home Assistant climate component	temperature value as a float	20.8
thermostat_cmd_mode<n>	sets the thermostat current mode to the Heating Circuit n (1-4). This is specific for the Home Assistant climate component	auto, day, night, off, manual	auto
thermostat_cmd	send a generic command to control the thermostat	JSON {"cmd":<command>,"data":<value> with command being temp<hc>, mode<hc>, nightemp<hc>, daytemp<hc> or holidaytemp<hc> with hc being empty or the heat controller (1-4) and value being a numeric value	{ "cmd":"temp2", "data": 20 }
shower_data	for setting the shower timer or alert toggle	JSON as `{"timer	alert":"0
generic_cmd	for sending a command to the EMS-ESP, e.g. sending a shot of cold water	coldshot	coldshot
boiler_cmd	for sending generic command to control the Boiler	JSON {"cmd":<command>,"data":<value> with command being comfort and data = [hot,comfort,intelligent] or flowtemp with data being the desired temperature or boiler_cmd_wwonetime	{"cmd":"flowtemp",data:55}
boiler_cmd_wwactivated	for receiving boiler controls from a HA HVAC component	"1" or "0"	"1"
boiler_cmd_wwtemp	for receiving boiler temperature setting from a HA HVAC component	the temperature value	60

Monitoring MQTT

In Telnet the command mqttlog will show you the last messages published as well as which topics are being subscribed to. In the WebUI you also see real-time the last set of published messages in the System Status screen. Below is an example of the telnet command.

[telnet session]
mqttlog

MQTT publish log:
  Topic:start Payload:start
  Topic:heartbeat Payload:version=1.9.2b6, IP=10.10.10.198, rssid=72%, load=1%, uptime=364secs, freemem=52%
  Topic:boiler_data Payload:{"wWComfort":"Hot","wWSelTemp":54,"wWDesiredTemp":70,"selFlowTemp":5,"selBurnPow":0,"curBurnPow":0,"pumpMod":0,"wWCircPump":0,"wWCurTmp":36.7,"wWCurFlow":0,"curFlowTemp":43.4,"retTemp":41,"sysPress":1.7,"boilTemp":45.5,"wWActivated":"on","burnGas":"off","flameCurr":0,"heatPmp":"off","fanWork":"off","ignWork":"off","wWCirc":"off","heating_temp":75,"pump_mod_max":90,"pump_mod_min":60,"wWHeat":"on","wWStarts":206017,"wWWorkM":73890,"UBAuptime":3471966,"burnStarts":229866,"burnWorkMin":368989,"heatWorkMin":295099,"ServiceCode":"0H","ServiceCodeNumber":203}
  Topic:tapwater_active Payload:0
  Topic:heating_active Payload:0
  Topic:thermostat_data Payload:{"hc1":{"seltemp":15,"currtemp":20.6,"mode":"auto"}}

MQTT subscriptions:
  Topic:home/ems-esp/restart
  Topic:home/ems-esp/start
  Topic:home/ems-esp/thermostat_cmd_temp1
  Topic:home/ems-esp/thermostat_cmd_mode1
  Topic:home/ems-esp/thermostat_cmd_temp2
  Topic:home/ems-esp/thermostat_cmd_mode2
  Topic:home/ems-esp/thermostat_cmd_temp3
  Topic:home/ems-esp/thermostat_cmd_mode3
  Topic:home/ems-esp/thermostat_cmd_temp4
  Topic:home/ems-esp/thermostat_cmd_mode4
  Topic:home/ems-esp/thermostat_cmd
  Topic:home/ems-esp/boiler_cmd
  Topic:home/ems-esp/boiler_cmd_wwactivated
  Topic:home/ems-esp/boiler_cmd_wwtemp
  Topic:home/ems-esp/generic_cmd
  Topic:home/ems-esp/shower_data

If you want more precise monitoring of the MQTT traffic I suggest using MQTT Explorer.