Step-by-step how-to guide install and use MQTT with the latest Domoticz.

For this how-to we will be using the Mosquitto MQTT instance in combination with Linux Raspbian (we assume you are using a Raspberry Pi but this guide will work on most other Linux distro’s).

MQTT is a simple messaging protocol, designed for constrained devices with low-bandwidth. So, it’s the perfect solution for Internet of Things applications and Domoticz. It allows you to send commands to control outputs, read and publish data from sensor nodes and much more.

If you are new to MQTT or if you want to know more about it, this video is a very clear and complete explanation (thanks Opto 22!). For Domoticz, you can disregard the ‘keep alive timer’ part, this is less relevant for us.

In this guide we do not further protect the broker and make it accessible for the complete network. We do it this way because the information shared is not that secret and if you are new to MQTT, this can help you to get it working and gain some knowledge and experience with this technology. By default, the Mosquitto broker is not protected.

Also, when we connect the MQTT broker to Domoticz, Domoticz also publishes it’s own device update to the broker. You can switch this off but it can be very useful to debug any issues. And it does not do any harm as MQTT is very lightweight technology.

Domoticz works a bit different with MQTT than other home automation platforms. It only uses 2 channels for MQTT communication, one for receiving updates and one for updating it’s own device changes.
With that, it does not follow the conventional “Homie” standard like OpenHab or Home Assistant. Domoticz makes MQTT it incompatible this way, really a missed opportunity for Domoticz (I hope this changes in the future)…
More information about the Homie standard:
https://homieiot.github.io/

Prerequisites

Tested with

  • Raspberry Pi 4 (MEM 2GB with 16GB sd-card)
  • Raspbian Buster Lite 4.19, Februari 2020
  • Domoticz Stable 2020.1 (compile date 22-3-2020)

Step 1: Install the MQTT broker

To install the Mosquitto broker and client run the following commands:

sudo apt update -y && sudo apt install mosquitto mosquitto-clients -y && sudo reboot

After these commands, the raspberry pi reboots and the new MQTT broker should be up and running. To check if Domoticz is properly running after the reboot, run the following command:

sudo systemctl status mosquitto.service

You should see something similar like this:

The Mosquitto MQTT broker is up and running
The Mosquitto MQTT broker is up and running

Step 2: Link MQTT to Domoticz

Next is to connect the MQTT broker to Domoticz. You can add the MQTT broker by going to the Domoticz menu and then the Hardware menu.

Add the broker with the following settings:

  • Name: MQTT Gateway
  • Type: MQTT Client Gateway with LAN interface
  • Date Timeout: Disabled
  • Remote Address: localhost
  • Port: 1883
  • Username: Leave this empty
  • Password: Leave this empty
  • Prevent Loop: True
  • Publish Topic: Out
    You can also set this to ‘none’ if you do not want Domoticz to publish changes back to the domoticz/out channel on the MQTT broker.
  • CA Filename: Leave this empty
  • TLS Version: tlsv1

Like this for example:

Adding the MQTT Broker in Domoticz...
Adding the MQTT Broker in Domoticz…

Step 3: Adding a MQTT device

Once you have configured the MQTT hardware device in Domoticz, it’s time to add some devices to Domoticz that we can use. For this, we use Dummy devices. Dummy devices are not directly linked to any hardware or plugin, not even to the new installed MQTT broker. Instead, it makes it possible to update values true the MQTT broker. You’ll understand this process a bit better after the following steps. Don’t worry, we’ll get there…

Create a new Dummy hardware devices with the following settings:

  • Name: MQTT Devices
  • Type: Dummy (Does nothing, use for virtual switches only)
  • Date Timeout: Disabled
Add new Dummy hardware for the virtual devices
Add new Dummy hardware for the virtual devices

Next is to create a specific virtual sensor:

Create a new virtual sensor
Create a new virtual sensor

For this example, we create a temperature sensor called “temp01”:

Creating a virtual temperature sensor that we can use with MQTT
Creating a virtual temperature sensor that we can use with MQTT

Step 4: Test the MQTT sensor from the command line

Now that we have set up the broker and connected it to Domoticz with a dummy device, let’s update that sensor true Domoticz. To do so, we need to know the IDX value of the sensor. Look it up in the Domoticz menu under devices. In our case, the IDX value of the newly created device is “1”

Look up the IDX value of your created device
Look up the IDX value of your created device

As we also installed the Mosquitto client, we can now update the sensor with a new value from the console. Use the following command for that, but change the value for IDX for the value of your own sensor. In this example, we use the IDX value 1 that we looked up in Domoticz. We set the temperature to 27 ℃.

mosquitto_pub -h localhost -m '{ "idx" : 1, "nvalue" : 0, "svalue" : "27.0" }' -t 'domoticz/in'

As you can see in Domoticz, the sensor has now been updated with a temperature of 27.0 ℃.

Other Clients

As we can connect multiple MQTT clients to the broker and subscribe to topics, this can be extremely useful if you want to see what’s going on with the broker. And there are multiple different clients, for different scenarios.

With all options, you can subscribe to the # channel. This will give you a complete overview of all MQTT messages going true the broker. Including the messages that Domoticz will publish itself with device updates. With this information you can further identify and analyze your Domoticz configuration. Of course you can also subscribe to specific topics, that’s up to you.

Keep in mind:

  • MQTT Gateway or broker: IP address of your Raspberry Pi
  • Port: 1883
  • No username or password necessary
  • Channel # for all MQTT messages on the broker
  • Channel domoticz/in for messages from anything to Domoticz
    This is the channel you publish to, to update Domoticz sensors.
  • Channel domoticz/out from messages from Domoticz to broker
    This is where Domoticz publishes it’s own updates to the broker, for other MQTT subscribers or clients to read.

Linux console

As we also installed the Mosquitto client you can subscribe to channels from the MQTT broker with the command below. Keep in mind that if you want to both publish and subscribe to a MQTT channel, you are going to need 2 SSH sessions. One to publish and one to read the results.

mosquitto_sub -v -t '#'
Example Mosquitto_sub command output
Example Mosquitto_sub command output

Windows (or Linux)

One MQTT client that I really like in particular is the MQTT.fx client by Jens Deters. It has a clean and intuitive interface and is also available for the Linux Desktop.

Direct download link for the latest 64-bit Windows version:
http://www.jensd.de/apps/mqttfx/1.7.1/mqttfx-1.7.1-windows-x64.exe

More information can be found on the corresponding website:
https://mqttfx.jensd.de/

MQTT.fx client in action
MQTT.fx client in action

Android

For the Android phone I found the the MyMQTT app extremely useful. Not only does this give a quick and easy insight in all messages and the app is very intuitive.

https://play.google.com/store/apps/details?id=in.dc297.mqttclpro

MyMQTT for Android
MyMQTT for Android

Apple iPone

MQTTool for Apple iPhone by Brent Petit
MQTTool for Apple iPhone by Brent Petit

For the Apple iPhone I found the MQTTool from Brent Petit.
Unfortunately I did not have an Apple product at hand when I wrote this to take it out for a test drive. But it seems rather complete by the looks of it.

https://apps.apple.com/us/app/mqttool/id1085976398