The goal of this tutorial is to explain how MQTT works in Gladys Assistant.
MQTT allows you to send a value to Gladys from a connected device (e.g. a temperature sensor taking temperature readings every 10 minutes). You can also use MQTT to send a home automation command from Gladys to a actuator (e.g.: send the command to a rolling handwheel to open).
Gladys therefore implements a MQTT API in both directions:
- "Peripheral -> Gladys"
- "Gladys -> Peripheral"
The MQTT API is described in the MQTT documentation.
Configure an MQTT broker in Gladys Assistant
The following tutorial assumes that you have either (1) installed Gladys Assistant 4 with the official Rasbian image as explained here, or (2) that you have Gladys installed witg Docker.
First, go to Gladys,
Integrations section, and open the MQTT integration:
Then, go to the "Configuration" tab to configure your MQTT broker.
There are 2 optionsat this step:
- EITHER you let Gladys launch an MQTT broker all alone (via Docker). This is the preferred option as it is the easiest way to use MQTT in Gladys.
- OR you configure an MQTT broker yourself (locally or remotely). This option can be useful if you already have an MQTT broker running on a server, or if you want to use an online MQTT broker.
In this tutorial, we will go through option #1 (letting Gladys launch the MQTT broker).
You can therefore launch the creation of the MQTT broker automatically with Gladys.
Depending on your internet connection, and the power of your machine, this can take a few seconds and a few minutes.
You can click on the little eye to see the password that Gladys generated for your MQTT broker.
We recommend that you write this password down somewhere.
We therefore have a running MQTT broker which is connected to Gladys!
Declare an MQTT device in Gladys
In this tutorial, we will use the example of a temperature sensor placed in the kitchen which returns temperature values every 10 minutes to Gladys.
First, go to the "Devices" tab of the MQTT integration, then click on the "New +" button:
Fill out the form with your device information.
For example, let's fill it in with the following information:
- Name: "Temperature sensor"
- External ID:
mqtt:kitchen:temperature-sensor. This must not have spaces and must start with
mqtt:. We recommend that you keep a convention throughout your Gladys installation, such as
- Room: "Kitchen".
Next, we are going to add features to this device.
Indeed, in Gladys, a "physical" device can have several "features". Some manufacturers offer "multi-sensor" peripherals (temperature/humidity/brightness is a classic).
In the search bar, search for "temperature" and select "Temperature / temperature sensor". Click on "Add feature".
You can then fill out the form with the following information:
- Name: "Temperature". It is this name that will be displayed on the dashboard.
- External feature ID:
mqtt:kitchen:temperature-sensor:temperature. We advise you here to also keep a convention, such as for example
- Unit: "° C"
- Minimum value: -50 (Let's assume your temperature sensor goes down to -50°C)
- Maximum value: 200 (Let's assume your temperature sensor goes that high!)
- Is it a sensor ?: This box is used to indicate if your peripheral works in the direction "Peripheral -> Gladys" or "Gladys -> Peripheral". If you put "Yes", then this device is "read-only", it just returns values to Gladys. This is the case with our temperature sensor. If you put "no", this device is an actuator which can be controlled by Gladys.
- MQTT Topic: This is the topic in which Gladys will "listen" to the new values for this device. We advise you to copy it somewhere for later.
Click "Save", you should on a screen like this:
Test the MQTT device
We suggest you use an MQTT client to test this MQTT device.
You can use the MQTT client MQTT.fx.
After installing and launching MQTT.fx, click on the small cogwheel to add the connection information to your MQTT broker.
Fill out the form with the following information:
- Name: "Gladys MQTT". This name is only useful for display in the software.
- Broker Address: The IP address of your Rasperry Pi on the network. You must be on the same network as your Raspberry Pi for this tutorial.
- Broker Port: 1883
Then, go to the "User Credentials" tab, then fill in with the login information.
- User Name:
- Password: The password that Gladys generated in the first part of this tutorial.
If you had not kept the password, you can still find it by going back to the configuration of the MQTT module and clicking on the little eye on the password field.
Save the configuration by clicking on "Ok", then click on "Connect" at the top of the screen to connect to the MQTT broker.
In the bar at the top, put the MQTT topic that you had copied when creating the feature earlier.
In the middle field, enter a temperature, in this case "21.2", then click on "Publish":
On the dashboard, add a new "devices in room" box and select your room.
You should see your device with the temperature we just sent:
To go further
If you want to write a program that sends data to your MQTT broker, there are MQTT libraries in all languages.
For example, in Node.js, you can use the npm mqtt package.
There are plenty of tutorials on the internet for all platforms :)