Please forgive the topic, I could not resist barrowing the phrase for something constructive.
Having started using MQTT from scratch just yesterday morning, and now having gotten everything to work, I figured I’d write it up make it a bit easier for the next guy while it’s fresh in my mind.
These notes are written at 2019-06-24 and my experience is based on openHAB 2.4. It is current as of now but may not apply to newer versions!
Many, many tutorials and notes on this forum are about MQTT binding in openHAB 1.x and do not apply – it has changed completely.
First of all, to understand MQTT, watch this video. It’s clear, consise, and will show you the basics. Don’t try to follow along – just watch it first. Not every part will apply to you (for example I have no use for Node-RED) but it’s still a good example. It’s actually a good thing that it’s not an openHAB tutorial, because it sticks to the basics.
-
MQTT.fx and MQTT explorer are both excellent tools. I use both.
-
You’ll need your own MQTT broker, which is the hub that interconnects all the devices, and routes messages through. I run “mosquitto” on the same Raspberry Pi that runs my openHAB, and I installed it through openhabian-config.
-
I made sure I was able to post and subscribe to (and receive) messages before I did anything MQTT-related in openHAB! I’m glad I did, because the openHAB part ended up taking much longer than the previous parts, partly because of all the misleading information around.
-
Once I had mosquitto set up, I was able to post and subscribe to messages with MQTT.fx and I was able to monitor everything through MQTT explorer. In MQTT.fx, when publishing, the big white empty window below the “topic” field is NOT as I first thought a graphics bug… it is an edit box where you enter the payload. Tripped me up for a while.
-
The next step for me was to publish MQTT messages from an ESP8266 (NodeMCU). I did so using the PubSubClient library, and it worked great for me.
-
WARNING: openHAB is not designed to subscribe to wildcard topics because inside a rule it will NOT reveal the topic a message came from, only the payload itself. Keep this in mind when you decide how to lay out your messages. You will have a much easier time if you stick to ONE topic for related things (such as different buttons and actions on a remote control) and separate things by payload. If you, like I did, start by separating buttons as topic, you will end up down the rabbit hole of workarounds. Don’t do it. Once I saw how deep it went, I dug myself back out and re-structured my MQTT messages around openHAB’s limitations.
NOT recommended:
topic: home/mcu/LivingRoomMCU/433mhz/CeilingFanRemoteBtn1 payload: pushed
topic: home/mcu/LivingRoomMCU/433mhz/CeilingFanRemoteBtn2 payload: pushed
Recommended:
topic: home/mcu/LivingRoomMCU/433mhz/CeilingFanRemote payload: btn1_pushed
topic: home/mcu/LivingRoomMCU/433mhz/CeilingFanRemote payload: btn2_pushed
This lets you easily get all button actions into ONE openHAB rule.
The topic hierarchy obviously doesn’t need to be this deep but I figured better too deep now than messy later.
-
Once I was able to push the buttons on my remote and see the actions end up in both MQTT.fx (subscribed to topic # which is the mqtt wildcard that means everything from this level down) and MQTT Explorer (which always shows everything as a tree), I decided to tackle openHAB.
-
MQTT in openHAB is a binding, and you’ll find it under Add-ons - Bindings in PaperUI.
Then go Configuration - Things, hit +, MQTT Binding, Add Manually. Choose MQTT Broker.
Now pay attention to the Thing ID. You will have to type this thing ID throughout the life of your openHAB setup so make it descriptive. It’s how openHAB keeps MQTT brokers apart because of course it supports more than one! It doesn’t have to be hexadecimal. I called mine local because it is. Obviously the first time I left it to the default dc12ba34 and had to start over, just trying to save you the pain. -
WARNING WARNING WARNING
There is a BUG in OpenHAB 2.4 which makes the openHAB MQTT Broker Thing not function until you’ve restarted OpenHAB! So, head to your linux terminal and sudo service openhab2 restart. I wasted hours trying different syntaxes in rules and getting a (to me) cryptic error message before I thought to google the error message, and found the explanation. You have to restart openHAB whenever you make ANY change to the MQTT Broker binding. Once it’s up and running it’s fine though, and you can add things at will. -
To make an MQTT subscription, you have to add another Thing – a “Generic MQTT Thing” to be exact. At this point let me reiterate, openHAB will NOT reveal the topic a message came from this way, only the payload itself, so you better not use a wildcard subscription.
On the Generic MQTT Thing (which you should name more descriptively than that, and write your own alphanumeric thing ID) you also select the Bridge (the MQTT broker) you just selected. This is where you see its thing ID: in my case mqtt:broker:local.
Each channel you add is its own MQTT subscription, and multiple items can be linked to each, in the normal openHAB fashion. -
Now, if you DO need to use a wildcard subscription, it can be done, but it is a workaround. You do it by adding a channel to the MQTT Broker Thing itself. The channel type is “Publish Trigger”. The channel gets updated every time something is published, and that something contains both the topic and payload separated by a hash sign (#) provided you entered hash as the separator. After that, the rest is up to scripting logic. It is when I saw this that I backed out of my approach and made my remote buttons publish to the same topic, but I include it here for posterity.
Forget about subscribing to MQTT topics per item, it’s not happening – that’s an openHAB 1.x thing and is unfortunately not available with the openHAB 2.x MQTT binding! -
Finally, if you need to publish MQTT from a JSR223/Jython script, here is how you do it. Please note that “local” is the “Thing ID” of the MQTT Broker Thing which we entered earlier.
actions.get("mqtt", "mqtt:broker:local").publishMQTT(topic, payload)
That’s all I can think of at the moment. Questions below. Corrections welcome!