**************** 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`_. 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`_ 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`_. In case you don't want to set a user add the following to the mosquitto.conf file: .. code-block:: none 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'. .. image:: ../images/firmware/v3-0/webinterface-tab-mqtt.png :width: 800 :alt: Web interface 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': .. code-block:: javascript {"28-AD1C-2606-0000":45.5,"28-6D91-2706-0000":27.3} Example output 'By number': .. code-block:: javascript {"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. .. image:: ../images/firmware/mqtt-mqtt-status.JPG :width: 800 :alt: Web interface mqtt status .. 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'. .. image:: ../images/firmware/mqtt-mqtt-settings.png :width: 800 :alt: Web interface 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. .. list-table:: :header-rows: 1 * - 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. .. image:: ../images/firmware/mqtt-mqtt-status.JPG :width: 800 :alt: Web interface mqtt status .. note:: After every change to MQTT settings, restart the Gateway and the MQTT broker otherwise the changes might not take effect. 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'. .. image:: ../images/firmware/mqtt-mqtt-settings.png :width: 800 :alt: Web interface 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. .. list-table:: :header-rows: 1 * - 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. .. image:: ../images/firmware/mqtt-mqtt-status.JPG :width: 800 :alt: Web interface mqtt status .. Note:: After every change to MQTT settings, restart the Gateway and the MQTT broker otherwise the changes might not take effect. .. target-notes:: .. _`Mosquitto`: http://mosquitto.org/ .. _`install Mosquitto`: https://www.sigmdel.ca/michel/ha/rpi/add_mqtt_en.html .. _`Migrating Mosquitto to 2.0`: https://mosquitto.org/documentation/migrating-to-2-0/