MQTT devices - general

The function blocks of this group are used to connect devices that communicate via MQTT - above all the devices of the manufacturer Shelly, but also NUKI, ECOWITT weather stations and any other MQTT participants.

MQTT works on the principle of "report and listen in": the devices send their states to a central distributor, the broker. Anyone interested in a value subscribes at the broker and receives every change. The broker runs on the controller itself, an additional server in the network is not required. Every value has an address, the topic. Using the topic the controller determines which function block an incoming message belongs to.

This page describes everything that applies to all blocks of this group. The inputs, outputs and parameters of the individual device are described on the respective page of the function block.

Important: For this function the controller must have an image version 3.034 or higher.

1. Switching on the broker in the controller

In the web interface of the controller the internal broker is switched on under Enable/disable MQTT Broker, see Controller - MQTT broker. The broker works on port 1883 and accepts connections without user and password.

Note: The broker should only be activated if an industrial memory card is installed in the controller, because swapping is activated together with the broker. In addition an active fan is recommended. Both are available as an option.

2. Registering the device with the controller

In the web interface of the Shelly device the IP address of the controller and port 1883 are entered under MQTT. In addition the following options must be enabled:

RPC over MQTT - allows the controller to switch the device.
Status notifications over MQTT - the device reports changes on its own.
Generic status notifications over MQTT - supplies additional values such as power or temperature.

Devices of the first generation do not yet know these three switches; there it is sufficient to switch MQTT on.

So that the values are correct again immediately after a restart of the controller, it is advisable to set a suitable power-on state for the outputs in the device and to give the device a fixed place in the network (fixed IP address or DHCP reservation).

3. Entering the correct topic

Every function block has the parameter MQTT topic. It must match the setting in the device, otherwise all outputs keep their initial value. The following rules apply:

First generation	Devices of the first generation (Shelly 1, 2.5, Dimmer 2, RGBW2, EM, 3EM, H&T, Flood, Motion, i3, Button 1, Plug S, UNI, DW2, TRV) automatically prepend shellies/ to their topic. This part must be entered as well in the parameter, for example shellies/shellybutton1-48551902C7E2. In the settings of the device itself the prefix is only shellybutton1-48551902C7E2.
Second and newer generation	Devices from the second generation onwards (Plus, Pro, Gen 3, Gen 4) do not send this part automatically. The topic must therefore be exactly as in the settings of the device, for example shellyplusi4-a8032ab613b8 - that is without shellies/ at the beginning.
Only one section	The prefix configured in the device may only consist of one section. Names such as livingroom/light are not allowed; they must be entered for example as livingroom-light.
Keep it unique	The controller assigns a message to a block as soon as the configured topic is contained in the topic of the message. Very short or generic names can therefore match several devices. The factory name including the serial number is the safest choice.

Reading the topic from the diagnostics: The exact identifier can be copied from the MQTT diagnostics as soon as the device sends messages. In the message

"shellyddimmerg3-aabbeaaeebec/rpc" = "{"method":"Light.Set","params":{"id":0,"on":true}}"

the topic is shellyddimmerg3-aabbeaaeebec.

4. Generating addresses

All blocks of this group can create their addresses themselves. With the command generate addresses in the context menu of the block, an address in the group "MQTT/WIFI devices" is created and assigned for every input and output. This saves creating them by hand and makes sure that the data types match.

In addition an address named timeout is always created (see next section).

Timeout - monitoring the availability

Every block monitors whether its device is still sending messages. As long as messages arrive, the timeout address is 0. If the messages stop, it is set to 1. This can be used to generate a fault message in the visualisation or in the program.

The monitoring time depends on the type of device:

5 hours for mains-powered devices. They report regularly, even without a change of state.
24 hours for battery-powered sensors such as H&T, Flood, Motion, Door/Window, Button 1 and Presence. They only report on an event and sleep otherwise in order to save battery.
For the weather stations the time can be set with the timeout parameter.

The timeout address is deliberately slow. It reports a permanent failure, not a single lost message.

Switching and status feedback

Blocks with switching outputs have an input for switching and several outputs for the feedback for each channel. The distinction is important:

Outputs named relay ... status report the actual state of the relay in the device - regardless of whether it was switched by the controller, by the Shelly app or by the push-button at the device.
Outputs named switch ... status report the state of the push-button or switch connected to the device.

Depending on the device there is a parameter switch for the switching inputs with two options:

Toggle (rising edge)	For push-buttons. On every change of the input from 0 to 1 the output of the device is toggled. The value 0 at the input has no effect.
Toggle (1/0)	For switches and for control from the program. The input value is applied directly: 1 switches on, 0 switches off. In this mode the input is additionally fed back to the corresponding status output so that both values match.

User and password

Internally the blocks still know the fields user and password. They are not shown in the settings dialog because the broker on the controller works without login. Instead, access is protected by the fact that the broker can only be reached in the local network.

Bluetooth devices (Shelly BLU)

Shelly BLU devices always require a Shelly device as a gateway, because BLU devices have no WLAN and cannot send MQTT messages themselves. Setup, structure of the messages and the script required for this are described on a separate page: Shelly BLU - basics and gateway script.

If no values arrive

1.	Check in the MQTT diagnostics whether any messages of the device arrive at all. If nothing arrives the cause is the device or the network, not the block.
2.	Compare the topic shown in the diagnostics with the parameter MQTT topic. The most frequent mistake is a missing or superfluous shellies/.
3.	Check whether the three MQTT options are enabled in the device. Without "generic status notifications", power and temperature values are missing, for example.
4.	Check whether the outputs of the block are assigned to addresses. Without an assigned address the value is received but not passed on.

Disclaimer

The setup and integration of the devices via MQTT and uni-PRO is at your own responsibility. The manufacturer accepts no liability for damage or malfunctions caused by incorrect configuration or external influences. It is the responsibility of the user to make sure that the control unit uni-PRO, the MQTT broker software and the firmware of the devices are updated regularly. Failure to do so can lead to security gaps and malfunctions for which the manufacturer cannot be held liable.