****************
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

Making the appropriate settings for EMS-ESP
===========================================

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-4/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.

.. Note::
  Do not leave the broker on test.mosquitto.org. This is only for quick testing. It is not secure.
  You need to change the address to your own MQTT server on you local network.

MQTT Formatting
^^^^^^^^^^^^^^^

MQTT Discovery is supported by Home Assistant and recent Domoticz beta versions.

.. image:: ../images/firmware/v3-4/enable-mqtt-discovery.jpg
  :width: 400
  :alt: Enable MQTT discovery

Turn on MQTT Discovery to have HA or Domoticz detect all entities automatically.
For Domoticz and other systems you can change the topic prefix as well.

Topic/Payload Format
^^^^^^^^^^^^^^^^^^^^

Values:

- Nested on a single topic
- As individual topics

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".

Seeing if it works
==================

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

.. image:: ../images/firmware/v3-4/mqtt-status.png
  :width: 800
  :alt: Web interface MQTT Status tab

.. 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/