Looking for the ultimate beginners guide

Looking for the ultimate beginners guide. I have tried following the guides on the openHAB website but I find I am going around in circles getting overwhelmed with information.

Is there a simple step 1, step 2 guide out there that walks you through setup without taking you off in tangents?

I know that might be a bit of an ask considering there are different platforms etc it can be set up on, but I have it half set up and seem to have fumbled through different steps getting to where I am so far. i.e step 1, step 5, step 3 etc.

Just in case I need to reformat and start again I would like to know what order to set stuff up in.

I am installing it on a RPi3 and I have used the openHabian image which I suspect probably bypassed a few of the steps like setting up Java.

I would not say there is an ‘ultimate’ beginners guide mainly because everyone’s needs, wants, and end goals are different.

The doc’s are actually pretty good in getting OH2 installed and running. But from there, it can become more complex in what you want to actually do with OH2, as well as what type of devices you want to integrated into the system.

Other factors depend on the user and their experience with different Operating Systems. While OH2 works on windows for some, I would ‘think’ that most users set up their OH2 installs with Ubuntu, a raspberry PI, or some other type of headless install.

You will find may here willing to help and guide you. But first we need to some background on what you have done and tried.

I first setup openHAB and Mosquitto on Windows to try and get familiar with an OS I know, but then tried to progress to installing it on the Raspberry Pi, since that is where I want it to ultimately live as the basis of my home automation system.

I have not touched Linux since college days and while extremely rusty I am sort of blundering my way around relearning things like sudo, nano etc.

What I am looking for is more like a check sheet that each and every installation would need to get up and running. For example only through searching online did I see people mentioning trying to setup smb connections.

Later I discovered I needed to do that myself, but don’t know if that needs to be first or tenth. Like anything when you start off you don’t know what you don’t know and while the openHAB instructions seem good I am clicking on links because I think I need to know something prior to continuing but then get lost down a rabbit warren of further links.

Conceptually I don’t know how all of these pieces interconnect, so I don’t yet have a mental picture of what the finished solution looks like so I think at the moment I have multiple configurations that are drawing pieces from all over the place.

Let me try put a post together that outlines what I have as far as I understand it.

I have the openHAB image installed.

Not entirely sure how I did it but I have some smb permissions setup to allow me to access the files on the RPi3.

I have Eclipse smart home designer installed and I can view and edit the various files.

Again not entirely sure how I got to this step or what files I modified to give me these permission and where I found them. Linux is a bit tricky compared to Windows because the home directory is not at the root (C:) directory like Windows, as since “ls” doesn’t show what is actually there when logged in as “root” I am kind of guessing what the file structure of Linux even looks like. So part of my problem is not really knowing from a file structure point of view where the files I modified even live.

I think the /etc folder is right off what would be C:\ in Windows but everything else is a bit of a mystery.

I also have MQTT.fx installed which seems to be handy in checking messages being sent to and from the MQTT broker, and that seems to be working fine.

I have also written / modified some C# code I found to send messages to the MQTT broker.

I have managed to get the android phone app working and a half working layout of the house configured (sort of) and I can see the same thing when I use ClassicUI. Although it’s far from complete.

I am a visual person so a picture showing the relationship between all the elements in openHAB would really help a lot.

I am struggling a bit with understanding the syntax of some of the things I need to do in then openHAB configuration files.

For example I have this in home.items
Switch Patio_Lights “Lights” (gPatio) {mqtt=">[myMQTT:FirstFloor/Patio/light:command:ON:1],>[myMQTT:FirstFloor/Patio/light:command:OFF:0]"}

I think this is ok for sending a message from openHAB to MQTT, but don’t yet know how to get a message from MQTT to update the switch in openHAB. I know I need to use the < for input but don’t know if I need some kind of rule (which I don’t know about yet).

In home.sitemap I have this
Group item= gPatio label= “Back Patio” icon= “terrace” {
Switch item= Patio_Lights

I have configurations setup in both mqtt.cfg and mqtt-eventbus.cfg but strongly suspect I don’t need both since I am getting messages being generated by both of them.

That’s the bulk of where I am up to. I don’t have any “Things” yet (don’t even know what a Thing is) and don’t have any rules yet either.

As I say I got here mostly by fumbling around in the dark and going around in circles.

Would it be fair to say the first couple of steps of a “Dummies guide to setup” might include…

  1. Install an image
  2. Install openHAB / Java if it is not included in the image.
  3. install MQTT (Mosquitto in my case)
  4. Change passwords
  5. Configure SSH from the console somehow to allow remote access
  6. Configure some SMB permissions for some specific files to allow access to them
  7. Install PuTTY on local PC to remote in.
  8. Install MQTT.fx (or some other client) on local PC to access the MQTT broker
  9. Install Eclipse SmartHome Designer on local PC to edit openHAB configuration files

The approach for “dummies” to start with OPENHAB and Linux should be using the openhabian image, that way your OS and openHAB will be installed al, together with the needed surroundings.

1 Like

Yep used the openHABian image but that is only a starting point and is covered by point (1.) above but really doesn’t give you a working openHAB - MQTT setup.

There are numerous steps to getting it to work and so far I only think I know about 80% of them.
Knowing what and when is what I am trying to determine.

Your steps 7 (putty) and 9 (ESH Designer) are independent to the other addons needed. You can start with them right after having the image running on your system, or better have putty available even before starting. The ESH Designer might be replaced by Visual Studio Code soon.
Reference the addons, that all depends on your special needs.

Try MK Smart House. Step by step wirh openhab. He has lots of videos but he has stop for now don’t know why. Google him. He might help

The only reason I left PuTTY so far down the list is I found I needed SSH enabled before I could use PuTTY. I have never used any of this software before attempting this so it is a massive learning curve of what does what. I only proposed that order since I have no idea what order they should be in, but based on my limited experience it would seem like the logical order. I may even still be missing some important software I don’t know and won’t know until I have it finally running and exchanging data in two directions.

I have watched most of his videos but I am still not picking up on a few crucial points. Once I have it running I should be able to look back and work out what I missed until then I am trying to decipher the instructions on the openHAB website but feel like I am going around in circles.

Maybe it the way I absorb information but going from page to page jumping from topic to topic is not the easiest way for me to understand I need a more linear approach.

Something like step 1 install image, step 1.1 prepare the SD card, step 1.2 burn the image, but jumping from page to page from link to link I don’t know where I am in the order of things or even if I have covered everything off.

? If you are using openhabian (like me) ssh should be enabled by default.

The journey has been so all over the place I honestly couldn’t tell you if I had to enable it or not. I know I went into one of the config GUI menus and checked it, but I really have lost track of what I have changed and what I haven’t. That’s why once I have it working I would like to go back to the beginning and redo it all over again, as I have probably messed with setting that didn’t need to be touched. Also it would cement it in my head to do it in a linear order.

Can someone please tell me if I need both mqtt-busevent.cfg and mqtt.cfg because when I switch a light on with either the phone app or the openHAB classicUI it shows in MQTT.fx

FirstFloor/Patio/light with a data value of 1
/Out/Patio_Lights/command with a data value of ON
/Out/Patio_Lights/state with a data value of ON

These lines are in mqtt-busevent.cfg

When available, all status updates which occur on the openHAB event bus are published to the provided topic. The message content will be the status. The variable ${item} will be replaced during publishing with the item name for which the state was received.

statePublishTopic= /Out/${item}/state

When available, all commands which occur on the openHAB event bus are published to the provided topic. The message content will be the command. The variable ${item} will be replaced during publishing with the item name for which the command was received.

commandPublishTopic= /Out/${item}/command

While this appears to be coming from home.items and possibly mqtt.cfg

Switch Patio_Lights “Lights” (gPatio) {mqtt=">[myMQTT:FirstFloor/Patio/light:command:ON:1],>[myMQTT:FirstFloor/Patio/light:command:OFF:0]"}

It would seem to me you either configure one or the other but I need confirmation of that.

Here it talks about Bindings (which I still really don’t understand) http://docs.openhab.org/addons/bindings/mqtt1/readme.html#item-configuration-for-inbound-messages but no where does it mention if I need one or all of these things.

"MQTT Binding

This binding allows openHAB to act as an MQTT client, so that openHAB items can send and receive MQTT messages to/from an MQTT broker. It does not provide MQTT broker functionality, for this you may want to have a look at Mosquitto or others. There are test servers available at m2m.eclipse.org and test.mosquitto.org."

This bit of text leads me to believe that a binding somehow attaches openHAB to MQTT and allow it to talk to the MQTT broker the same way the bit of code I wrote does, but what I am confused about is in paperUI > Addons > Binding I clicked install MQTT Binding and it now says uninstall (hinting that it is installed) however when I go to paerUI > Configuration > Bindings all I see there is a GPIO binding, so I don’t know what is going on and if it is bound or not.

In order to get a response by someone knowing mqtt I suggest to put that into a separate thread using a topic that points to the question. Is said before openHAB has an nearly uncountable number of bindings/addons, no single user will know them all!

But I don’t know if I am even up that stage yet… As I said before you don’t know what you don’t know and I don’t know if I am at the start of the process or the end. I think I am around the 80% mark (gut feeling) but I really don’t know, the point of this thread is to get a clear answer as to what order things should be done in (without looping me in circles) and then perhaps I can drill down into the individual diagnostic problems, but I am taking a shot gun approach at the moment blasting away at everything trying to find my way out of the woods.

I could be trying to configure a piece of software that is dependant on another piece of software being installed and I don’t have it installed, so without some logical step by step process I am in the dark here.

I have stumbled upon some of the stuff necessary to get a result (although have no idea if it is configured right) but I am no closer to knowing where I am at in the process. I am basically looking for a straight forward do A then B then C and by the time you get to Z everything will work.

Using openhabian you should have already setup the OS, openHAB itself and the samba shares in order to even connect to the config files via network-shared folders from another pc/mac or whatever.
At this stage you should be able to configure openHAB via the PaperUI and some cfg files (for OH1 bundings).
Everything beyond that is up to your specific needs. Looking at the topic a person with experience in using mqtt might not look into this thread at all, hence my suggestion.

Trying to get some lights on :wink:


ok for now, but please be aware that Smarthome Designer is outdated and won’t be updated anymore, instead please use VSCode with the openHAB plugin https://code.visualstudio.com/ VSCode is opensource under the MIT license.

:smiley: Well, in GNU/Linux ‘Everything is a file’ and there is one root for the file system:
This is the file system root: /
This is not the file system root, but the user directory of the user root: /root/

The file system is way easier than in windows, as there is only one root / and everything is a child of /
All common users have their home directory in /home/ (just like C:\Users\ in Windows)
All common settings reside in /etc/ (and in question of openHAB2, you will find them in /etc/openhab2/

The syntax should be easy:

Switch      MySwitch    "My switch [%s]" <light> (myGroup) {binding=""}
  /\          /\            /\              /\      /\         /\
Item Type  Item Name    Item Label         Icon    Group(s)  Binding(s)

Everything except Item Type and Item Name is optional.
The Label may or may not contain an variable part [%s] (%s is ‘state as a string’)
If an Item belongs to one or more Group(s), the group will update its state in dependence of the item(s). If the group is used to send a command, this command will be sent to all group members. The group has to be defined independently in the items file.
Now to the binding: The definition of this part is dependent of the binding, so this part is the most complex part, and it should be described in every http://docs.openhab.org/addons/bindings.html documentation, so for mqtt this would be
There are two parts of communication, inbound and outbound. For mqtt these parts are independent, so you have to configure both parts, > for outbound, < for inbound. So you could use

Switch mySwitch {mqtt=">[mybroker:myhouse/office/light:command:ON:1],>[mybroker:myhouse/office/light:command:OFF:0],<[mybroker:myhouse/office/light:state:MAP(light.map,*)]"}

and a map file to transform the received state to ON or OFF.

The problem that everyone is trying to say is there is no straight forward a through z step-by-step process for OH because everyone’s steps are completely different.

openHABian does a fantastic job of doing automatically for you all the step by step tasks to get OH installed and running on a Raspberry Pi. If you start with the image, after about 30 minutes you will have a fully installed OH with samba and all the other settings necessary for OH to work with a variety of technologies.

It takes care of everything and includes installation and configuration of a lot of common ancillary software like Samba and Mosquitto for MQTT.

This is why we recommend openHABian so heavily for new users. Step 1 is just “install openHABian” image.

But after this point step 2 could be one of a thousand different steps depending on what exactly you want to build with OH.

So let’s assume you want to set up MQTT as your first step. If you used openHABian, you would already have Mosquitto installed and configured, or can do so now easily by running openhabian-config and browsing the menus until you find Mosquitto.

Now you need something in OH that can talk to the MQTT broker from OH. These add-ons are called Bindings and they serve as a bridge between OH and whatever technology or API you are interacting with. There are two flavors of bindings, 1.x version bindings which are older bindings written before OH 2 was released and which have not been rewritten to take advantage of 2.x concepts (i.e. Things, Channels, and configuration through PaperUI).

Most everything you need to know to create an Item config for a given binding is documented in the binding’s README. For MQTT you can find that here:


You can also find a lot of information by searching the Forum. There are tons of examples. For MQTT, the best posting is MQTT Binding (v1.11) Getting Started 101.

But to make my point again, step 2 for me when I first set up openHAB was getting Zwave working. Other user’s step 2 could have been getting KNX working, or HomeKit, or something else. This is why there is no step-by-step process to provide. After step 1 everyone is on a different path. So the best I can offer is:

  1. Install using openHABian: http://docs.openhab.org/installation/openhabian.html, though even here, everyone will want to run different. I for one run in Docker on a VM.

  2. Review the Beginner’s Guide and Concepts section of the User’s Guide and make sure you understand some of the key concepts: Items, Things, Channels, Bindings, etc.

  3. Choose the binding you want to configure first. You have over 200 to choose from.

  4. Install the chosen binding.

  5. Configure the binding as documented in the readme

  6. Create or accept Things from the Inbox where applicable as documented in the binding README

  7. Create Items as defined in the binding README.

  8. Start to explore Rules, sitemaps, HABPanel. and Persistence as needed.

I can’t be more specific than this because step 4 onward is going to be specific to the chosen binding.