HowTo: FHEM – Create MQTT Devices

Posted on by

In the article RaspberryPi - Install MQTT Server on the RaspberryPi I had written a little to MQTT and explained how to install a separate MQTT server on the RaspberryPi.

In order to be able to use an MQTT server also from FHEM, you still have to install a few FHEM modules. How to do that and what you have to pay attention to, I have described in the following article.

Hints for our lovely english readers: Basically, many of the articles on Nerdiy.de are translations from the original german articles. Therefore, it may happen here and there that some illustrations are not available in english and that some translations are weird/strange/full of mistakes or generally totaly wrong. So if you find some obvious (or also not obvious) mistakes don't hesitate to leave us a hint about that in the comment section. 
Also please don't get confused, that instead of a "dot" often a "comma" is used as decimal separator. 🙂

Safety instructions

I know the following hints are always a bit annoying and seem unnecessary. But unfortunately, many people who knew it "better" from carelessness lost their eyes, fingers or other things or hurt themselves. In comparison, a loss of data is almost not worth mentioning, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Even the coolest project is worth no injury or other annoyance. https://www.nerdiy.de/en/sicherheitshinweise/

Affiliate links / advertising links

The links to online stores listed here are so-called affiliate links. If you click on such an affiliate link and store via this link, Nerdiy.de receives a commission from the online store or provider concerned. The price doesn't change for you. If you do your purchases via these links, you will support Nerdiy.de in being able to offer further useful projects in the future. 🙂

Requirements

Before you start with this article, you should have prepared the RaspberryPi so far that it can be reached via the network and controlled by SSH.

The following three articles describe what to do to prepare the RaspberryPi:
RaspberryPi - Setting up for Nerdiys!
RaspberryPi - The First Configuration!
RaspberryPi - Control the RaspberryPi via SSH
FHEM—Installation and entry into FHEM
RaspberryPi – Install MQTT server on the RaspberryPi

Needed tools:
-none-

Materials required:

In the following list you will find all the parts you need to implement this article.

Log in via SSH on the RaspberryPi

To get started, you first need to log in to RasPi with SSH on Putty. How to do it is described in the article

After entering your username and password you can start to enter the first commands.

Update package management

The package management in Linux is a "central point" over which various software packages can be installed. For this to work reliably, the lists and sources of package management should be updated before installing any new packages.

To start the package management update you have to enter the following command.
sudo apt-get update && sudo apt-get upgrade
Depending on how long your last update of the package management is, this process may take some time. First, the lists are updated in which the individual repositories are referenced.
Then the packages themselves are updated. As this additional memory is occupied, you will be asked again for your consent. You have to confirm this with a "J"(in German) or a "Y" and "Enter".
When the update is complete, you will see a small summary of the duration and scope of the update.

Install Perl MQTT packages

In order for FHEM to communicate with the MQTT server, two Perl packages must be installed.

To do this you must log in with Putty on the Rasp Pi and enter the following command.
sudo apt-get install libmodule-pluggable-perl && sudo cpan install Net::MQTT:Simple && sudo cpan install Net::MQTT:Constants
The warning that this additional memory space is occupied, you acknowledge with a "J"(or "Y") and "Enter".

The question "Would you like to configure as much as possible automatically? [Yes]” is confirmed with “yes” and Enter.
The installation of the two packages took me about five minutes. Time enough to get a new coffee. 🙂

Create MQTT clients

In order to be able to establish a connection with an MQTT device in the next step, an MQTT client must first be created. This later saves all necessary information for the connection to the MQTT server.

To do this, enter the following command in the command prompt of your FHEM instance.
define mqttClient MQTT 192.168.0.1:1883

The command to create an MQTT client is equivalent to the following "define name-of-mqtt-client MQTT host-or-ip-des-mqtt-server: port-des-server". If your MQTT server has the IP address "192.168.0.1", the port 1883 corresponds to the default port for MQTT, the command for creating the MQTT client is "define mqttClient MQTT 192.168.0.1:1883". Of course, any other name can be used for "mqttClient".

Now click on "Save config" in the upper left corner and restart your FHEM server with the following command.
shutdown restart

After the server is restarted, you are ready to create new MQTT bridges and devices.

View of the newly created MQTT client. Here you can see if a connection to the MQTT server could be made. In addition, you will see more information about the connection with the MQTT server.
In order for the made changes to be taken over and permanently saved, you must remember to click on "Save config". This permanently saves the changed settings in the configuration file.

Set up MQTT bridge using the example of a MAX! Heating thermostat

In this example, we create an MQTT bridge. As the name suggests, the MQTT bridge connects something with each other. In this case, the MAX! Heating thermostat with the MQTT world. This link works in principle according to the same scheme with all already installed sensors or actuators. In the case of the MAX! Heating thermostat this works with the following command.

The structure of the command is structured as follows: "define name-the-mqtt-bridge MQTT_BRIDGE name-of-sensor-or-actuator". In the case of the MAX! Heating thermostat with the name "MAX_15504f" is the command as follows.
defineHeatingWorkroomMqtt MQTT_BRIDGE MAX_15504f

This will create the module "HeizungArbeitszimmerMqtt" of type "MQTT_BRIDGE" and link it with the existing module "MAX_15504f".

The created MQTT_BRIDGE is now in the room "Unsorted". Switch to this room and open the detailed view of the created MQTT Bridge.
In the detail view you can now see all information about the created MQTT Bridge. However, before the MQTT bridge can connect data from the MAX! Heating thermostat to the MQTT world, it first needs to know which reading of the heating thermostat should be linked to which MQTT topic.

There is the attribute "publishReading_XYZ" for this. This will cause the MQTT Bridge to automatically forward all updates on the Reading "XYZ" to the specified topic.

So enter the following command in the command prompt of your FHEM instance to automatically forward each update of the reading "temperature" to the topic "heating/workroom/temperature".
attr HeizArbeitszimmerMqtt publishReading_temperature heizung/Arbeitszimmer/temperature

Make sure that "publishReading" and "temperature" (the reading of the Radiator Thermostat (or any other sensor/actuator)) are associated with an underscore. This results in "publishReading_temperature".
For reading "Battery" the whole thing would look like this.

attr HeizArbeitszimmerMqtt publishReading_battery heizung/Arbeitszimmer/battery
However, linking Reading and MQTT topics also works the other way around. For values sent to an MQTT topic to be automatically entered into a reading of the heating thermostat, you must set the following attributes.
attr HeizArbeitszimmerMqtt subscribeSet_desiredTemperature heizung/Arbeitszimmer/desiredTemperature

This causes the topic "heizung/Arbeitszimmer/desiredTemperature" to be subscribed to and any incoming value automatically entered in the reading "desiredTemperature". In this way you can control the desired temperature of the heating thermostat via MQTT message.

The detail view of your MQTT bridge should now look like this. Under Attributes you can see all linked Reading / MQTT Topic combinations. Remember to save this configuration change by clicking on "Save config".

Testing the adjusted MQTT bridge

One way to test the newly created MQTT bridge is described here.

In addition, I have made a mini-MQTT viewer in NodeRed, which shows you the values that are sent to the selected topics "heating/workroom/temperature" and "heating/workroom/battery". You also have the option to send the value 25 to the topic "heating/study/desiredTemperature". As a result, if everything works properly, the associated radiator thermostat will be set to 25 °C.

First, we check whether the reception and acceptance of values received by MQTT works. Change to the room "MAX" and then to the detailed view of the respective heating thermostat.
In the detail view scroll down now until you …

… find the reading “desiredTemperature”. This is the reading that we have linked in the MQTT bridge configuration to the MQTT topic "heating/workroom/desiredTemperature". Here you will also see the current value of the read and the time of the last update.

If you click on the inject node in the self-built MQTT viewer, you send the value 25 to the topic "heating/study/desiredTemperature". This should now also update the reading of your heating thermostat to the value 25. In addition, the time of the last update is set to the current time.

In order to test the opposite way – ie the publication of a modified read to an MQTT topic – it is sufficient to scroll to the very top in the detail view of the MAX! Heating thermostat. Once there, you change the desired temperature of your heating thermostat as shown.

This automatically triggers an update of the reading "battery". Linking the MQTT bridge to the "heating/study/battery” topic will then publish its value through the topic as desired and then be visible through the configured debug node in your NodeRed environment.

Create MQTT device using the example of a temperature sensor

Another possibility of the MQTT module is the creation of MQTT devices. This includes all sensors or devices that send their measured values directly via MQTT. In order to capture these values and summarize them in a virtual sensor, you need to create an MQTT device.

In this example, we have a temperature sensor in our network that periodically sends the measured temperature value via the MQTT topic "Umweltdaten/keller/Temp". In order to detect this, an MQTT device is first created with the following command.

define kellerSensor MQTT_DEVICE
The command is again made up as follows: "define name-of-Mqtt-Device MQTT_DEVICE". Since in this example we include a temperature sensor in the basement we call the MQTT_DEVICE "kellerSensor", so the complete command to create the MQTT_Device is "define kellerSensor MQTT_DEVICE ambient data/keller/Temp".
After you have created the MQTT_Device you will find it in the room "Unsorted". You can also open the detailed view through this.

Of course, before this MQTT_Device can display values, it must first be linked to the desired MQTT topic. In this example we want to show all values in the created MQTT device in the MQTT topic "Umweltdaten/keller/Temp".

For this you have to set the following attributes:

attr kellerSensor subscribeReading_Temp Ambient Data/keller/Temp

This causes the reading "Temp" to be created in the MQTT_Device "kellerSensor" and linked to the subscribed topic "Umweltdaten/keller/Temp".

In the view of the readings, the reading "Temp" appears with the current or last received value and the date of the last update.

To make the view even better, you can specify with the following attribute that the value of the readings Temp should be followed by a "°C".

attr kellerSensor stateFormat Temp °C
To do this, enter the command "attr kellerSensor stateFormat Temp ° C" into the command line of your FHEM instance.
As a result, the current temperature of the "cellar sensor" is now also provided with a "°C" and it can be seen directly that this is a temperature value.

Additional Information

https://wiki.fhem.de/wiki/MQTT_Einf%C3%BChrung

Have fun with the project

I hope everything worked as described. If not or you have any other questions or suggestions, please let me know in the comments. Also, ideas for new projects are always welcome. 🙂

P.S. Many of these projects - especially the hardware projects - cost a lot of time and money. Of course I do this because I enjoy it, but if you appreciate that I share this information with you, I would be happy about a small donation to the coffee box. 🙂

Buy Me a Coffee at ko-fi.com   

One comment

  1. Hi Fab
    Thank you so much for all of the information you have made available here. I have spent many years with home assistant, and no time at all with FHEM which I am now using to try to get better control of my FHT heating devices. If I can get FHEM communicating with an existing MQTT server that would be my dream.

    I have FHEM running on Raspian OS within a docker container, the install went as per your advice with no errors – but when I try to enter the commands via FHEM web front end I get Cannot load module MQTT_BRIDGE or Cannot load module MQTT_CLIENT which makes me think either I've messed up not installing the perl/mqtt from within the docker container or I've not done something within FHEM to invoke the new MQTT capability?

    Kind regards

    Nick

    Reply

Kommentar hinterlassen

Your email address will not be published. Erforderliche Felder sind mit * markiert