How do I make a switch turn on?

A friend of mine wants to start with this whole automation lark. He had a simple question: “How the beep do I make a switch turn on and off?”

It is such a simple question and, while openHAB is such a powerful thing, I feel there is no easy answer that a noob can follow. I remember I could find no such thing.

A comment was made a while back in a post where there was someone struggling to understand how items relate to HABPanel; the response was “Have you read the documentation? All of the documentation?”
While well intentioned, I am sure it was detrimental to that user continuing.

  • I will attempt to explain a starter setup for an individual who is not to unfamiliar with Raspberry Pi, Linux basics and basic code.
  • It will not be the most efficient way of doing it and it won’t be the most recent of everything (looking at you mqtt binding 2.4!)

Hopefully it will give a starting point an a juicy bit help someone understand.


  • You have a working RPi (RPi3B+ onwards is good)
  • Said Pi is up to date on everything (apt-get update pkg-get upgrade
  • You can follow tutorials linked off from here.
  • We will use PaperUI (Used for installing bindings and basic stuff)
  • We will use HABPanel (Used for displaying and interacting with items)
  • We will write minimum code
  • You’ve shared your openhab config using samba

How it works

  1. A smart plug publishes (talks to) your mqtt service running on your PI
  2. openHAB (running on your PI) subscribes to messages on mqtt
  3. You have an item (which is a switch). The switch, uses the mqtt binding to listen to the messages published and acts on them (ON/OFF)
  4. You display that switch on HABPanel as a clicking do-da
  5. You lose the next 6 months to adding more stuff to the system and your wife leaves you :frowning:

Items and actions needed

Install MQTT

  1. SSH into your pi and run the following command
sudo apt-get install mosquitto

You now have mosquitto installed :slight_smile:
Download MQTT Spy to test (You can do this on your Windows machine)

  1. Create a new connection within mqtt spy and use your Pi’s name. It should connect.

  2. Subscribe to a new topic. Let’s call it “home/myswitch”

  3. Configure your smart switch to publish to the same topic. This will vary from device to device so there is no point in me trying to explain it. I can show what I see and hopefully you can work it out.
    Key is though, you can use mqttSpy to “debug” where your messages are landing.

Here I can see that it’s publishing to a topic called home/lights/kitchen/LED_KITCHEN_LANTERN
(The identifier is a keyword in Espurna. You don’t have to use it.)

In mqttSpy you’re want to subscribe to this and include a /# at the end. This is a wild card in mqtt-land

You should not see this:

And, as in my case, you now should see all the messages chatting back and forth.

If you see this you’ve successfully got your smart switch talking to mqtt.

Install the mqtt 1.x binding

  1. Open a browser and go to your openhab installation (http://openhab) might work for you…

  2. Click on Addons -> Bindings and type in mqtt.

  3. Be sure to install the 1.x binding. The 2.4 binding is a) buggy (For me it is :slight_smile: ) and far more intense to understand than the 1.x

  4. You should now see a file in your Services folder called mqtt.cfg
    Edit it to have the URL of the mqtt server (which should just be localhost)

All should now be well.

Setup yout item

  1. In your Items folder, create a new file called test.items.
  2. Open it in your favourite editor (Notepad++ or VSCode)
  3. Paste the following

Switch 		MySwitch 		"This is my first switch and it will work!"	{ 
																			" }

Make sure you change your paths to match what you are seeing in mqttSpy.

Next steps

  1. Finally! Head of to HABPanel and create a new dashboard.
  2. On your blank dashboard add a new widget, a Switch widget would do nicely.
  3. Edit the switch widget and, where it says “openHAB item name” find or type your item MySwitch as above.
  4. Click save and Run.

Now, all being well, you’re done. Clicking the switch sends a message to openHAB which sends a message to the binding which sends a message to mosquitto which gets noticed by your smar switch which turns on. :smiley:

caveat emptor
I’ve done this all from my head. There might be some steps not as clear as they could. Let me know and I can edit the post.
The mqtt binding is marked as obsolete and will be replaced at some point int he future. While the new binding will be better, it has a whole bunch you need to wrap your head around which I think it a bit over the top for a noob.
Getting to understand how this all hangs together is a very steep learning curve. The community is very helpful if a) some effort is shown on your part to solve the problem b) you provide enough information to let them help you.

Hopefully this will help someone (like my friend)
Feedback always welcome :slight_smile:

1 Like

Good write up and humour. Keep it up!

MQTT1 is now deprecated and will hardly get any support on the forum except from a few old timers like myself. And will be advised to move on to MQTTv2.
I strongly suggest that you update this tutorial with MQTTv2


And it most likely will not be supported in OH 3 when it is released next year.

1 Like

run mqqt v2 it’s setup is easy and quick. i am running it with and espuruna. there is som catches. but if you follow the documents and read them carefully it will suddenly work. like mine. and if you battel ask then i will share my setup files so you could see haw i did mine.

I too recommend MQTT 2 for all the reasons already mentioned and one more. You are then able to do everything through the UI which is not a bad approach for getting started. I personally do not find it any more (or less) easy to understand compared to the 1.x version of the binding. And in point of fact, it works more like other bindings so learning how to set up the MQTT 2.x binding will give you skills you can use with lots of other bindings (i.e. setting up a Bridge Thing and then discovering or creating Things under that Bridge).

As for the 2.4 version being buggy, that is true. But all the the bugs that have been reported on the binding have been addressed and are fixed in the 2.5 RC1 version of the binding. Most of the bugs that were reported were fix as early as OH 2.5 M2. And in point of fact, given 2.5 will be released in five days, a tutorial based on 2.4 is probably not the best choice at this time.

I would add the MQTT tags to the tutorial since this tutorial doesn’t answer the more generic question of “How do I make a switch turn on?” but the more specific question of “How do I make an MQTT switch turn on?”

And this is the rub and why it was so hard to answer that seemingly simple question. There isn’t just one answer. There are as many answers as there are different technologies that support switches. The Zwave tutorial of this tutorial would be very different from the KNX version from the Insteon and so on. About 80% of this entire tutorial is MQTT specific with only four scant lines that really talk about anything generic (i.e. how to add the Switch to HABPanel).

I think it’s a great tutorial and it would be useful for a user getting started with MQTT, though the tutorial will be come deprecated far too soon because it uses MQTT 1.x, but it doesn’t really do much for a user who, for example, want to turn on a Zwave Switch.

I knew there would be some comments made about the mqtt1 angle of it but not this many :slight_smile: (Which is good - feed back :slight_smile: )

I tried the mqtt2.4 when it came out and just could not get my head around it. In hind sight, it was probably a culmination of so many differing options, nuances and learning curve which just confused me. After finding out I was chasing bugs and not me being silly, I decided to stay with 1.x because it’s just so simple.

If the GUI matures and is better to use than the code then that would be brilliant. I spent a lot of time early on in the GUI (rules, items, linking etc) and actually found the code version easier. That is, IMHO, a bit like Linux v. Windows. This needs to be more “Windows” so simpler people can use it (and have the power of code underneath should you want to play with it)

Looking forward to 2.5 and will let the dust settle and then install it.

I’ll certainly update the tutorial to highlight mqtt 2.4/5 as well

All I can offer is that there are orders of magnitude more posts on this forum for people asking for help with their attempts to creating MQTT 2.x .things files than those who do so through PaperUI. It’s impossible to have a syntax error when creating Things through PaperUI and all the option are present and well documented right there on the screen.

If you have a lot of similar MQTT Things to create, well you don’t have to use PaperUI to create all of them. Until the PaperUI replacement comes along my recommendation is to build one using PaperUI, then use the REST API docs to query for that Thing, edit the JSON to create your similar Things and submit them back through the REST API. It works quite well. The replacement for PaperUI looks like it will support copy/paste/edit from within the UI.

Well, OH version 2.5 will be released in less than a week. Then development really starts on version 3.0 which is not expected to support version 1 bindings directly.

That means that sometime next year your tutorial, as currently written, will become obsolete.