*****************
How does it work?
*****************

All EMS compatible Bosch brand boilers and most heat pumps have an EMS bus (Sometimes also called Heatronic).
This is the same 2-wire bus as your thermostat connects to. Its a 16V DC bidirectional data bus with integrated power supply for peripherals.
The EMS bus is available via the thermostat wires and on a lot of boilers and heat pumps also via a service jack on the front panel or under the cover.
You can connect the Gateway to the bus via either method withj the same performance.

Bosch brands or Bosch OEM brands include:

* Bosch
* Buderus
* Nefit
* Junkers
* Sieger
* Worcester
* elm.leblanc
* iVT

There are several versions of the EMS bus like:

* EMS
* EMS+
* EMS Plus
* EMS2
* Heatronic 3
* '2 wire bus' it's also sometimes called.

All these will work with the EMS Gateway.

Devices on the EMS bus communicate via telegrams.
Each device on the bus has an address. The boiler f.i. sends telegrams to the thermostat by using the thermostats’ address. There are multiple EMS devices possible on the same bus.
The Gateway identifies itself as a ‘service key’ module on the bus. 

The Gateway ‘knows’ most of the telegram types of a lot of EMS devices (currently more than 100).
So it knows how to interpret for instance the broadcast telegram of the boiler status.
It also knows how to instruct thermostats to change its temperature etc.

Depending on the connected EMS devices the Gateway can monitor almost everything but it can also set a lot of boiler, heat pump, mixer module and thermostat parameters.

.. note::
   The Gateway does not emulate a thermostat, so although the Gateway can instruct the thermostat to change the room temperature, it cannot start the burner of the boiler by itself.
   This remains the task of the thermostat, which has complicated algorithms to determine the boiler modulation.
   
   For a number of boilers it's possible to turn on the heating by regulating the flow temperature, however this does only work on a few boilers, not all.
   Some boilers will not accept these commands, or the thermostat may override them after a few seconds.

So on one side the Gateway connects to the EMS bus, and it connects via Wi-Fi and your home network to your home automation like Domoticz or Home Assistant.
You can configure the Gateway via an easy to use web interface like below.

.. image:: ../images/firmware/v3-4/dashboard-devices-and-sensors.jpg
  :width: 800
  :alt: Web interface main page

For both Domoticz and for Home Assistant the awesome MQTT auto discovery has been implemented, so that with a few clicks you have everything into Home Assistant!.
You get at least 60 parameters/entities of the boiler or heat pump available.
If you have added the configuration to Home Assistant it will look something like this:

.. image:: ../images/home-assistant/ha_lovelace.png
  :width: 800
  :alt: Home Assistant interface.

So now if you change setpoint value in Home Assistant, Home Assistant will send a MQTT command to the Gateway with the instruction to change the setpoint of the thermostat.
Because the Gateway knows the address of the thermostat and in which telegram type the new setpoint value goes, it sends an EMS telegram on the bus directed at the thermostat encoded with the new setpoint value.

The Gateway supports all heating circuits simultaneously.

In Domoticz your dashboard will be similar to this:

.. image:: ../images/domoticz/domoticz-ems-dashboard-1.jpg
  :width: 800
  :alt: Domoticz devices

Also for other home automations like Loxone, iO Broker, OpenHab, NodeRED etc you can interface with the Gateway via a HTTP Rest API or MQTT.