MQTT for Domoticz

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

READ MORE
domoticz

Install Domoticz 2020 on Raspberry Pi OS

Step-by-step how-to guide install Domoticz on Raspberry Pi with the latest Raspberry image. With the new Raspberry Pi OS (previously know as Raspbian) this guide has been updated to reflect the latest changes.

Please do not use the Raspberry imager, is still rather buggy at the moment.
Working with Win32 Disk Imager gives better results and is proven to be a reliable way to image your Micro SD card…

This how-to is part of a bigger series of Domoticz how-to’s on sancla.com!

This tutorial has been verified with the latest Domoticz 2020.2

Prerequisites

  • Raspberry Pi 4 with 2GB or 4GB of memory
    – 32GB Micro SD card (16GB works just fine to!)
    Class 10 from a good brand, such as Kingston, Transcend or Samsung.
    Pay attention to the Read/Write speeds…
    – Original or equivalent USB-C Power supply
    – Active or passive cooling
    Try the Flirc passive cooling case, you won’t be disappointed!
  • Network cable
  • Micro-SD card reader
  • Windows 10 installation with win32 disk imager
  • Free IP address in your network

Tested with

  • Raspberry Pi 4 (4GB model with 16GB sd-card)
  • Raspberry Pi OS Lite 4.19 (release date 2020-05-27)
  • Domoticz Stable 2020.2 (compile date Apr 27 2020)
  • Windows 10 ver 1909
  • Win32 Disk Imager

Step 1 – Prepare your Micro SD card

Assuming you work with Windows 10, let’s start by downloading everything we need:

To be sure the SD card is in perfect shape, format the SD 
card before you begin (source: raspberrypi.org):
- Download SD Formatter for Windows
- Follow the instructions and install
- Format your card with SD Formatter

Load the Raspbian image with WIn32 Disk Imager:
– Start Win32 Disk Imager (assuming your already have this application installed)
– Select the Raspbian image file (*.img, unpack the *.zip file first if you have to already done so)
– Select the drive letter of the SD card
– Click on “write” to start imaging your SD card

To enable SSH for a headless configuration you have to add a file named “ssh” to the “boot” partition/disk of the SD card. Make sure you add this file without any extension!!!

Once all these steps have bee taken, put the SD card into your Raspberry Pi, connect power and let it boot for a couple of minutes.

Step 2 – Find the IP adres of your Raspberry Pi

To be able to connect to the Raspberry Pi we need to know the IP adres that has been supplied by your router. Please be aware that we assume your connect your pi with a network cable. You can connect your pi wirelessly but this is not part of this how-to…

There are a couple of ways we can do this and the raspberrypi.org website published a great article about how to do this:
https://www.raspberrypi.org/documentation/remote-access/ip-address.md
For most home environments I believe the easiest way to do this is by installing the Find app on your phone:

Getting the IP address of a Pi using your smartphone

The Fing app is a free network scanner for smartphones. It is available for Android and iOS.

Your phone and your Raspberry Pi have to be on the same network, so connect your phone to the correct wireless network.

When you open the Fing app, touch the refresh button in the upper right-hand corner of the screen. After a few seconds you will get a list with all the devices connected to your network. Scroll down to the entry with the manufacturer “Raspberry Pi”. You will see the IP address in the bottom left-hand corner, and the MAC address in the bottom right-hand corner of the entry.

Source: https://www.raspberrypi.org/documentation/remote-access/ip-address.md

Step 3 – Connect with SSH

Once you have found the IP adres of your Raspberry Pi, connect to it with a tool called Putty. It is a standalone SSH tool and by far an industry standard application for SSH on Windows.

Start the Putty application, fill in the IP address and press Enter. You get a warning “Putty Security Alert” about the host key which you can safely ignore, continue and connect to the Raspberry Pi.
The default username and password are pi and raspberry.

Should you receive an error instead such as “Network error: Connection refused”, you probably did not correctly configure the SSH file on your SD card, most times caused by using a extension with the SSH file, such as SSH.txt for example.
Follow this YouTube video for more help on this matter:
https://www.youtube.com/watch?v=Q1jWk_nu3Ds

Step 4 – raspi-config

Once connected we start with setting up your Raspberry Pi. We can do so by connecting to the Raspberry pi with SSH/putty and running the following command:

sudo raspi-config

raspi-config

2 steps are important here:
– Setting the “Localisation Options”, so the time zone and date are correctly configured
– Setting a fixed IP address with “Network Options”, so we can always find back the Raspberry Pi in our network.

To do so, check the Raspberry Pi documentation, there are also plenty of YouTube video’s that can assist you with this step.
https://www.raspberrypi.org/documentation/configuration/raspi-config.md

Step 5 – Update, upgrade and reboot

To make sure we have the latest software versions, run the following command on your Raspberry Pi:

sudo apt update -y && sudo apt upgrade -y && sudo reboot

Your Raspberry pi will start updating and upgrading automatically.
Once done it will reboot your Raspberry Pi, your SSH connection terminates during reboot so you know when it’s finished. Rebooting can take a 1-2 minutes is my experience.

Step 6 – Install Domoticz

Once the Raspbian setup and preperation has been completed, it’s finally time to install Domoticz on your Raspberry Pi 4! Connect to your Raspberry with SSH/Putty if you have not already done so and execute the following command to automatically install Domoticz for you:

curl -L https://install.domoticz.com | bash

Source: https://www.domoticz.com/wiki/Raspberry_Pi

During installation you are able to configure the HTTP port, by default configured on port 8080.

You could change this to port 80, the default port for HTTP traffic. This way, you do not need to write “:8080” every time to connect to your Domoticz installation. However, should you wish to install Dashticz later on, port 80 could become conflicted.
My advise, stick to the default port 8080!

After this, you are all done and Domoticz should be up and running!

READ MORE