HowTo: FHEM – Create MQTT Devices

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 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.


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:

Required materials:

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 RaspberryPi - Controlling the RaspberryPi via SSH.

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 can 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 again asked 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 RasPi 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 saves later 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

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 “”, the port 1883 corresponds to the default port for MQTT, the command for creating the MQTT client is “define mqttClient MQTT”. 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.
define HeizungArbeitszimmerMqtt 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 “heizung/Arbeitszimmer/temperature”.
attr HeizungArbeitszimmerMqtt 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 the reading “Battery” the whole thing would look like this.

attr HeizungArbeitszimmerMqtt 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 attribute.
attr HeizungArbeitszimmerMqtt 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 “heizung/Arbeitszimmer/temperature” and “heizung/Arbeitszimmer/battery”. You also have the option to send the value 25 to the topic “heizung/Arbeitszimmer/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 detail 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 “heizung/Arbeitszimmer/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 “heizung/Arbeitszimmer/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 “heizung/Arbeitszimmer/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 “Umgebungsdaten/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 Umgebungsdaten/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 “Umgebungsdaten/keller/Temp”.

For this you have to set the following attribute:

attr kellerSensor subscribeReading_Temp Umgebungsdaten/keller/Temp

This causes the reading “Temp” to be created in the MQTT_Device “kellerSensor” and linked to the subscribed topic “Umgebungsdaten/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

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 it that I share these information with you, I would be happy about a small donation to the coffee box. 🙂

Buy Me a Coffee at

Leave a Reply

Your email address will not be published. Required fields are marked *