How Shelly devices work with MQTT

Introduction to Shelly devices with MQTT protocol on the Ilevia system: concepts, configuration in Ilevia Manager and operation test.

How Shelly devices work with MQTT

MQTT is a lightweight publish-subscribe protocol.

This protocol consists of two parts:

The client (the one that connects to the broker).
The broker (manages connections and user credentials and allows you to exchange information with components that work with the MQTT protocol).

You can find more information about the MQTT protocol here.

The image below explains how the MQTT protocol works with the Ilevia system.

All our systems (X1 server, virtual machine and Raspberry Pi) can operate as broker and server.

How the MQTT protocol works on the Ilevia home automation system

How to set up MQTT in Ilevia Manager

Before starting, check these parameters for a correct configuration:

Create a gateway and set it to MQTT broker.
The default client ID must be set to “eve-mqtt-client”. If you need to create more than one client, make sure to change the name.
The default port is 1883.
The default parameter used to keep instances alive is “keep alive” (even when no commands are being sent).
Set the Quality of Service (QoS) to “exactly once” (this option ensures that each message is received once).

Step 1:

Add a component within the My components section and make sure it has the MQTT protocol selected, as shown in the image below.

Automation software | How to set up the MQTT gateway inside Ilevia manager supervision software

How do payloads and topics work?

TOPICS

The topics are: read, event, write and response.
Each topic has a different message type that the MQTT broker uses to filter messages for each connected Client; topics are made up of levels separated by a “slash” (“/”).

Example: home/livingroom/light

Here is a brief description of the four topics:

Read topic: It is used to receive the MQTT device status.

Response topic: It is the device response to the automation server's read request.

Write topic: This topic is used to set the value of a device parameter.

Event topic: This topic shows the device status in case of changes.

PAYLOAD

A payload is a piece of code that contains a JavaScript function.
For each topic, a JavaScript function is executed to process the topic payload.

Example JSON string:

var data = JSON.parse(payload);var color = {“mode”:”color”,”red”:data.r,”green”:data.g,”blue”:data.b}; return JSON.stringify(color);

Step 2:

Response topic: Here you must enter the correct topic according to the device you want to control (you can find more information about topics on the Shelly website).

Step 3:

“Write topic“: Here you must enter the correct topic based on the device you want to control (you can find all Shelly device topics on this page).

How the write topic works inside Ilevia manager supervision software

Step 4:

Event topic: Here you must enter the correct topic according to the device you want to control (you can find more information about topics on the Shelly website).

How the event topic works inside Ilevia manager supervision software

Step 5:

To check whether the device works correctly, download the open source software MQTT-fx,

this will allow you to check the information the broker is receiving from the device.

Install the software on your computer.

The next step is to set up the broker within the software settings, click the gear icon, enter your X1 server IP address and port 1883.

How to set up the MQTT fx debugging software

Step 6:

To subscribe to all topics, enter the # symbol (hash).

Click the “subscribe” button and, if a connection has been established, you will see a series of messages: these messages show that your device has established a connection with the broker.

Step 7:

Check whether the component works within the automation application.

Load the project we just created and test it.

How to set up the home automation application through Ilevia manager

Here you can download the test project we created to test the Shelly Plug.

Download the test here.

Note: All Shelly devices have a different ID and different configuration methods, so we recommend consulting the Shelly website to make sure you are using the correct commands and topics.