HowTo: FHEM – Create MQTT devices

Posted on by

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

In order to be able to use an MQTT server from FHEM, you 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.

Safety instructions

I know the following notes are always kind of annoying and seem unnecessary. Unfortunately, many people who knew "better" have lost eyes, fingers or other things due to carelessness or injured themselves. Data loss is almost negligible in comparison, but even these can be really annoying. Therefore, please take five minutes to read the safety instructions. Because even the coolest project is not worth injury or other trouble.
https://www.nerdiy.de/sicherheitshinweise/

Affiliate links/advertising links

The links to online shops listed here are so-called affiliate links. If you click on such an affiliate link and make a purchase via this link, Nerdiy.de will receive a commission from the relevant online shop or provider. The price does not change for you. If you make your purchases via these links, you support Nerdiy.de in being able to offer other useful projects in the future. 🙂 

Requirements

Before you start with this article you should have prepared the RaspberryPi so that it is accessible via the network and controllable via SSH.

The following three articles describe what needs to be done to prepare the RaspberryPi:
RaspberryPi – setup for nerdiys!
RaspberryPi – The first configuration!
RaspberryPi – Control the RaspberryPi via SSH
Your own smart home - installation and getting started with FHEM
Mosquitto on the Raspberry - Install MQTT Server on the RaspberryPi

Tools needed:
-no-

Materials needed:

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

Log in to the RaspberryPi via SSH

To start, you must first log in to the Rasp Pi with Putty via SSH. How to do this is in the article RaspberryPi - Control the RaspberryPi via SSH described.

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

Update package management

The package management in Linux is a "central place" through which various software packages can be installed. In order for this to work reliably, the lists and sources of the package management should be updated before each installation of new packages.

To start the update of the package management you have to enter the following command.
sudo apt-get update && sudo apt-get upgrade
Depending on how long ago your last update of the package management was, this process can now take a while. The lists that refer to the individual package sources are updated first.
After that, the packages themselves are updated. Since additional memory is occupied, you will be asked again for your consent. You have to confirm this with a "J" and "Enter".
Once 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.

For this you have to 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
You acknowledge the warning that this will occupy additional memory with a "J" and "Enter".

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

Create MQTT clients

In order to establish a connection with an MQTT device in the next step, an MQTT client must first be created. This will later save the necessary data for the connection with 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 a MQTT client corresponds to the following "define name-of-mqtt-client MQTT host-or-ip-of-mqtt-server:port-of-the-server". So if your MQTT server has the IP address "192.168.0.1", the port 1883 which is the default port for MQTT) the command to create 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 using 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 established. In addition, more information about the connection to the MQTT server is displayed.
In order for the changes made to be applied and permanently saved, you must remember to click on "Save config". This will save the changed settings permanently in the configuration file.

Setting up the 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 to each other. In this case the MAX! heating thermostat with the MQTT world. In principle, this link works 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 as follows: "define name-of-mqtt-bridge MQTT_BRIDGE name-of-sensor-or-actuator". In the case of the MAX! heating thermostat with the name "MAX_15504f", the command is thus as follows.
defineHeatingWorkroomMqtt MQTT_BRIDGE MAX_15504f

This creates the module "HeizungArbeitszimmerMqtt" of type "MQTT_BRIDGE" and links it to the already existing module "MAX_15504f".

The created MQTT_BRIDGE is now in the "Unsorted" room. 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 with the MQTT world, it must first know which reading of the heating thermostat is to be linked with which MQTT topic.

For this purpose there is the attribute "publishReading_XYZ". This causes 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 every 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)) must be connected with an underscore. This results in "publishReading_temperature".
For the reading "Battery" the whole thing would look like this.

attr HeizArbeitszimmerMqtt publishReading_battery heizung/Arbeitszimmer/battery
This linking of reading and MQTT topics also works the other way around. So that values sent to an MQTT topic are automatically entered into a reading of the heating thermostat, you must set the following attribute.
attr HeizArbeitszimmerMqtt subscribeSet_desiredTemperature heizung/Arbeitszimmer/desiredTemperature

This causes the topic "heating/study/desiredTemperature" to be subscribed and every value received on it is automatically entered into the reading "desiredTemperature". 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. You can see all linked Reading/MQTT-Topic combinations under Attributes. Remember again to save this configuration change by clicking on "Save config".

Testing the set MQTT bridge

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

For this purpose I built a mini MQTT viewer in NodeRed, which shows you the values that are sent to the set topics. "heating/study/temperature" and "heating/study/battery" can be sent. You also have the possibility to send to the topic "heating/study/desiredTemperature" to send the value 25. This has the consequence that - if everything works correctly - the linked radiator thermostat is set to 25°C.

First, we check whether the reception and transfer of values received via MQTT works. To do this, switch to the "MAX" room and then to the detailed view of the respective heating thermostat.
In the detail view you scroll down until you see the Reading ...

... "desiredTemperature" is found. This is the reading that we used in the configuration of the MQTT bridge with the MQTT topic "heating/study/desiredTemperature" have linked. Here you will also see the current value of the reading 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". So 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.

To test the opposite way - i.e. the publication of a changed reading on an MQTT topic - just scroll to the top of the detailed view of the MAX! heating thermostat. There you change the desired temperature of your heating thermostat as shown.

This automatically triggers an update of the reading "battery". By linking the MQTT bridge with the Topic "heating/study/battery" its value is then published via the topic as desired and is then visible via the configured debug node in your NodeRed environment.

Creating an 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 collect these values and combine them in a virtual sensor, you must create an MQTT device.

In this example, we have a temperature sensor in our network that sends the measured temperature value at regular intervals via the MQTT topic "Ambient data/basement/temp". In order to capture this, an MQTT device is first created with the following command.

define kellerSensor MQTT_DEVICE
The command is again composed as follows: "define Name-of-Mqtt-Device MQTT_DEVICE". Since we include a temperature sensor in this example that is located in the basement, we call the MQTT_DEVICE "kellerSensor. So the complete command to create the MQTT_Device is "environment_data/basement/temp".
After you have created the MQTT_Device you will find it in the room "Unsorted". You can also open the detailed view shown here.

Before this MQTT_Device can display values, it must of course first be linked to the desired MQTT topic. In this example, we want to display all incoming values on the MQTT topic "Ambient data/basement/temp" in the created MQTT device.

To do this, you need to set the following attribute:

attr kellerSensor subscribeReading_Temp Ambient Data/keller/Temp

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

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

To brighten up the view you can use the following attribute to add a "°C" to the value of the reading Temp.

attr kellerSensor stateFormat Temp °C
To do this, enter the command "attr kellerSensor stateFormat Temp °C" in the command line of your FHEM instance.
This means that the current temperature of the "kellerSensor" is now also provided with a "°C" and it is directly apparent that this is a temperature value.

More information

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

Have fun with the project

I hope everything worked as described for you. If not or you have questions or suggestions please let me know in the comments. I will then add this to the article if necessary.
Ideas for new projects are always welcome. 🙂

PS 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 think it's cool that I share the information with you, I would be happy about a small donation to the coffee fund. 🙂

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.