Looking for the ultimate beginners guide

@HeadScratcher I totally agree with @rlkoshak

I want to add that as a beginner you might want your “step 2” to be something that teaches you about the possibilities of openHAB and how things like “items” and “rules” work. To that goals I’d suggest to look into one of the easier Tutorials and just play around with the results a bit. See here for a list: http://docs.openhab.org/tutorials/index.html#community

My personal favorite in terms of learning different aspects of openHAB without being dependent on certain hardware is: Speedtest-cli Internet Up-/Downlink Measurement Integration - however I have to state that it was written by myself, so I might be biased :smiley:


Thanks for the info on Linux that helped. I thought logging in as root would automatically take me to the root directory, and that was why I was confused when I typed ls and saw nothing, but that is just because the root user home folder is empty, and I had to type cd / to take me to the real file system root, and type ls where I found what was expecting to see.

Ahhh I think I see why my code went into an infinite loop causing MQTT.fx to produce hundreds of entries before I stopped it…
Switch Patio_Lights “Lights” (gPatio) {mqtt=">[myMQTT:FirstFloor/Patio/light:command:ON:1],>[myMQTT:FirstFloor/Patio/light:command:OFF:0],<[myMQTT:FirstFloor/Patio/light:command:ON:1],<[myMQTT:FirstFloor/Patio/light:command:OFF:0]"}

Yours only switches the command on the output, but appears to do a state change on the other through Transform (I came across and made a couple of those when experimenting with fan speed).

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,*)]"}

Ok that makes much more sense. I did actually get my C# code to update the state of the switch in openHAB last night by creating a rule like this.

rule "TurnLightOn"
Item Patio_Lights changed
if((Patio_Lights.state as DecimalType) == ON){
sendCommand(Patio_Lights, ON)
sendCommand(Patio_Lights, OFF)

I used a rule I found on Github and modified it until it worked.

Sometimes though you just want to have a play and may not have any devices to set up, so openHAB is less inclined to play nicely with you because nothing is found automatically.

To this end when I have some time I would like to fully develop the C# program I am writing to simulate some devices like light button, or windows / door contacts, so you can at least have a bit of a play with openHAB / MQTT without ever needing any hardware (other than one PC) to do it.

Take a look at the demo. If installing openHAB from scratch chose “demo” at the start page (http://openhabip:8080/)

This is of course true but it would be great if a consensus were reached acknowledging the basic tasks and scenarios commonly faced when setting up OpenHAB. For example, cookbook examples for controlling lights, setting up a mobile UI, setting up rules, Sonos integration, pitfalls to avoid etc. would be really helpful. For a beginner or casual user who doesn’t spend every day under the hood it can be challenging to stay on top of the elegant but complex abstractions that make up the OpenHAB environment. Being able to fall back on cookbook howtos (or some sort of wizard for lack of a better term) would greatly enhance the OpenHAB experience in my opinion.

1 Like

This is a side effect of the first binding you chose. MQTT is a 1.x version binding (a 2.x version is in work). Consequently, indeed, nothing is found for you. However, if you had chosen something like Zwave, Network, Wunderground, Astro or any number of other 2.x bindings you would have found that your devices more likely than not would have automatically been found and Things generated for you which you would have been able to select from the Inbox.

There are tons of just such cookbooks in the Tutorials and Examples section of the Forum.

We are open to any ideas and/or contributions you or anyone else may have on how exactly this sort of thing could/would be encorporated into docs. Right now the most popular and/or comprehensive tutorials are listed in the docs here:


@ThomDietrich, I notice the MQTT 101 tutorial isn’t in the list. I’ve linked to is so many times maybe it is time to add it. WDYT?

1 Like

@rlkoshak I was under the impression the new MQTT Binding would arrive with openHAB 2.2, that is not the case. :disappointed_relieved: Hence yes I’ll add it to the tutorials list.

1 Like

Not entirely sure why I am having so much trouble following the logic of these tutorials but something is not gelling as well as I would like. Went back to the beginner tutorials and tried to follow the one that sets up the Network Binding (which is probably a reasonable start place for most people with a network) and I got it working to some degree.

I was trying to use the mobile phone presence information, since detecting if our mobile phones are on the network will eventually be part of the home automation system.

This time it found a heap of network devices and it put them in the Inbox. By turning on the Item Linking it created some Things (which appear to be physical devices, and may not be necessary) and then I somehow created some Channels (don’t know if I need them) on our mobile phones, with online and time as Items.

Turned Item Linking back off since it hides all the items I created manually, but I am well and truly lost as to how all these Things, Items, Channels, Groups etc etc interlink with each other.

I have lights semi worked out, but have no idea how to make something practical from this new information as I feel like the tutorial ended without any outcome. Kind of you have now built a car, but have no instructions on how to drive it.

If anyone can post some sections of code to paste into the relevant files to get it going that would be greatly appreciated. Please DO NOT link to more tutorials I can’t follow.

If you can just post this bit goes in this file and this bit goes in that file, once I see it working I should be able to reverse engineer the thinking behind it. Currently I have a mass of scrunched up mess in my head.

What I want it to do is recognise the mobile phones on the network. So obviously the Network Binding is the first step to doing that, but I don’t need the phone or any of it properties (Items?) to act as a switch (I tried to change the Switch to a Image or String but things got ugly).

Basically I want some kind of visual representation to know if the phone is on the network or not (no switch just an icon of full signal or no signal, BUT… if the phone is connected or not connected I want it to perform some kind of action (perhaps send a message to MQTT) to say it has connected or disconnected so that information can actually be used by the system.

Knowing the phone is connected without an outcome is kind of pointless. Hopefully someone can just give me a simple cut and paste without further confusion. TIA.

We could but it would be a link to the documents that we have spent so much time writing but you done want to read. So instead you want us to retype what has already been written much better here.

A simple examples of what to type in here and there will not help you because you don’t understand some really key concepts. Concepts which are documented in the Concepts section of the User Guide (funny that).

A Device is represented in OH as a Thing.

Each piece of information and reach control on a Device is represented as a Channel.

Channels get linked to Items.

Everything in OH, from Rules to sitemaps work with Items.

According to the Network Binding Readme, there is an online channel for a Thing which must be linked to a Switch Item. The state is this Item will be ON when the device is on the network and OFF when it is not.

The Items Documentation and myriad of examples show how to define an icon for an Item. You can see the list of available icons on the docs (use the search if you can’t find it). If defining items in a text file, the icon guess after the label inside <>, e.g <network>. If defined through PaperUI enter the icon name under Category.

As the Sitemap documentation says, you can put tab switch on your sitemap for use in BasicUI or ClassicUI using a Text element.

Now I could have just put a bunch of things and items and sitemaps in this posting but without the knowledge of the difference between a Thing and an Item it would have done you no good.

1 Like

I’ve come to the conclusion that the problem is not me, but the way the instructions are laid out. They simply are not intuitive, nor are they laid out in a way that flows.

For example you would typically arrive at the home page of a website and in this case the item that jumps out most for a beginner is the “Getting Started” right in the middle of the page, so you click that and it takes you to what is supposed to be a Tutorial (Beginner).

You are greeted with:

This part covers all the basics to use openHAB after you installed it: how to perform the first-time setup, add some bindings, discover and configure things for the first time and finally how to create a sitemap and some basic rules.

What is a binding? discover and configure things? are they talking generically about things in general or Things? If they are talking about Things what is a thing? sitemap and rules? huh what are they?

I’ve just arrived on this page as a “beginner” and don’t know the first thing about these things. Where is the page that precedes this page that gently and in very simple language pictures explains what each of these things are?

At this point I know nothing so what is the point of launching into how to configure a Network Binding when you don’t even know what a Network Binding even is.

It is fairly obvious that once you understand the fundamentals of openHAB a lot of the other stuff will fall into place, but within that first little Overview paragraph there are two hyperlinks to take you off to other information without even explaining the most simplest of things about how it all fits together.

There should be a section that in bold print state ‘DON’T PANIC’ in large, friendly letters on the cover.
Then with pictures and text in little words explain each of the individual components and how they relate to one another.

Only after having read that is a beginner ready to move onto the Overview. You will note in menu items
http://docs.openhab.org/tutorials/beginner/index.html that there is no Concepts for a newbie to get there head around, only from clicking through who knows how many hperlinks with the truly unknowing find it.

This is a common problem when written by people who know the system so well, they overlook what to them is the most basic of details, but for the completely newbie this is pivotal information.

When I started using OpenHAB, the steps I took to learn what was needed was read, read, read and read. Mostly in various part of the docs, but also here in the forum.

But reading only takes you so far, at some point you have to start doing something. So I started just playing around, first with simple bindings like Astro and the network binding, which don’t require any special hardware. Just click on everything you see until you understand what it does, at this point you can’t break anything if you do something wrong.

When you think you start to understand how things work (or don’t understand something), then go back and read some more to get a deeper understanding of the concepts. No one (I think) has said that OpenHAB is easy.


I find it very hard to read, not because I can’t (I read very well) just that my mind wanders off onto other tangents if left with too many unfinished ends. For programming I get the most out of reference books where I can just look up an example and work it out, then I do from a long drawn out verbal explanation.

Often the longer something goes on or the more tangents it takes the harder it is for me to follow because I am trying to process everything at once. That why I really like things that take a linear approach, especially on subjects that are hard to grasp.

1 Like

A glossary like this at the very beginning would make a world of difference to me.

Hello @HeadScratcher, I don’t have much time to answer in length right now. I just want to say two things.

  1. Such a glossary exists here and here. I’m not saying they are perfectly placed, I just wanted to point you to them.

  2. The Beginners tutorial is not perfect. A volunteer just as you or me decided to contribute it. Sadly he did never invest more time for a second revised version. I am fully aware of the problems of the Tutorial but it is incredibly complicated to write a good documentation (as you’ve proven) and I (as the documentation lead) am concentrating more on the User Manual part of the documentation, as this is the area every reader will end up eventually when looking for exact details.
    With that said, I would encourage you to help improve the Beginners Tutorial! You could revise the whole article or simply note down all things that bothered you so someone else has a list to work through. “Someone else” is the tricky part as you can imagine.

In general I can only agree with the others. Read the User Manual and experiment with the Tutorials&Examples available. Many volunteers have contributed great things over the last 12 months to make those places a very good source of information for openHAB users.

I’d like to suggest the following example as a starting point to understand a few concepts. Speedtest-cli Internet Up-/Downlink Measurement Integration
Fun fact: It is my first Tutorial I’ve posted here in the community (I’ve improved it over time). The tutorial includes many basic concepts you should know about. Be aware that it does not address Paper UI, Things, Persistence or Transformations - as these are imho advanced topics you can learn after you’ve made your way through the basics. Here’s how you should go at it: Read the tutorial, every time a term comes up you don’t know: Study the respective documentation article about it. The Tutorial for example quickly introduces an Items file -> Read the Items article and make sense of the shown content.

Good luck!

I would love it if you opened up an issue on the openhab-docs repo to express these concerns. You make some very good points and they should be captured.

The way it is supposed to work is the beginners should go through the Beginner’s Tutorial first, then the Concepts section of the User’s Guide, and then move on to the sections of the User’s Guide that are relevant to their next steps.

If you have any suggestions how the docs can be organized, rearranged, or the like to make this progression more obvious to the new users that would be helpful.

And ask ask ask. We love to help. We (and I should really just say I) sometimes get defensive when we see “I can’t figure anything out but don’t you dare point me at the docs for answers.” It doesn’t help us improve the docs and it is asking us to spend time typing for the thousandth time the exact same thing.

I so know you feel. I started with OH1.5 and it took a LOT of reading, experimenting, learning and frustration to get things working. Quite time consuming but it’s kept my brain working and active. I’m now trying to migrate to OH2 but with around 30 ZWave devices, complex rules and multiple sitemaps, it’s going slowly. I’ve already restarted over 3 times and with Christmas coming I don’t plan to have another go till the New Year. My 1.8.3 system is working robustly and I’m in no rush.

I haven’t tried using a Pi but as an engineer of many years, my advice would be this:

Don’t try to learn too much too quick. If you’re comfortable with Windows, use a PC install and learn on that. At least you’ll be in your comfort-zone OS-wise.

Save the RPi for later.

Start simple. MQTT uses an external broker and there are credentials hoops to jump through in both directions. I have managed to get it working for presence purposes but it took a long time while I wasn’t confident about everything else. Now I don’t use it. Come back to that once you have simple things working.

I’d even be tempted to say try using a 1.8 install to play with, just to get a hang of the Items, Sitemaps, Rules and Persistence files which are text-based and as you hoped for, can be reverse engineered to work out how on earth it all hangs together. Plus, there are a ton on examples you can search for that will help you “get it”.

Version 2 uses a database to store information about your things and items, which to me, hides some of the basics you may be looking for. However, it can also also read V1.8 text files to configure itself, so if you get a setup working with 1.8, V2 should mostly work (caveats - some things break).

As an engineer, I like to have as few unknowns or uncertainties as possible, so when I introduce a new one, I know where to look to faultfind. Build the foundation, then add a bit at a time. Most of my errors were syntax.

I think the community is trying to aim for a “Wizard” style setup with V2 but the truth is that it’s a work in progress. It’s not like Microsoft… That said it, I’m a huge fan and my whole house now runs on it, including heating, lights, power, Sonos, alarms and so on. If I get V2 working, I’ll add Alexa to that and when I get old and infirm it’ll remind me to put my pants on when my care-worker is due to arrive, read me bedtime stories when I get fed up of BBC Radio 4 and re-order my Marmite when I run out.

Stick with it. It’s great :slight_smile:


1 Like

Thanks for the suggestions guys… And time permitting once I get my head around this OH2 / MQTT thing I might see if I can offer a different perspective to understanding it.

When it comes to documentation writing there are several ways to approach it depending on how complex the subject matter is. In a former life I was a licensing specialist at Microsoft, so I know about complexity and permutations, hundreds of products through close to a dozen different marketing channels, and rarely did any of them line up.

The one thing that really jumps out at me as a huge need, is pictures. We all start this journey knowing relatively the same amount of nothing. I used to travel around the country doing licensing presentation to partners, and a few simple PowerPoint slides (and sometimes not so simple slides) really help cement a concept or an idea.

Once I get OH, I expect to look back and think that wasn’t all that hard. Thinking that it just tells me that the problem is in the learning, not in the knowing.

I am a very visual and tactile person, so seeing and touching are the best way for me to learn, endless text is not my preferred way to learn and quite often the more that is said the more inclined I am to be confused.

One of the reasons I never did so well at school is because I answered the wrong question. For me I found most questions lacked enough detail to fully answer the question properly, so often I wound up answering the question best I could based on the information I had, whereas often the question they were asking was on a completely different tangent and in most cases far simpler than the question I was trying to answer.

I have a fairly analytical brain so when I get what appears to be conflicting information, it sends my head into a spin trying to work out in an algorithm style thinking how it is possible for all answers to be correct.

That is why for me a simple and complete working examples are the best way for me to learn. Several simple examples allows me to analyse the differences and see how to make the changes I need based purely upon what I see.

From what I understand of OH how I would approach teaching this is to start with the most basic of basics (think of basic, and nope simpler than that). An image just popped into my head… Imagine I was trying teach you how to build an engine (something I did a lot of way back in my youth) I wouldn’t start off by saying Revs x CI x VE / 3456 is the basis for determining air flow. You have only just heard about this “engine” thing the same way you have just heard about openHAB. So Revs or revolutions mean nothing to you, nor does CI or cubic inches, or VE volumetric efficiency and why would I be dividing it by 3456? Already your head would be swimming lost in terms that you not only don’t know, but have no concept of what they do.

If I was trying to take a fresh off the boat newbie who had just heard of OH, knew they needed it but had no idea what it was, I would launch into teaching them nothing… why nothing? because we’re not ready to start explaining what it is or what it does just yet. Instead I would start of with showing them an exploded picture like this. And be very clear that it is not necessary at this point to understand what you are looking at, I was going to explain what each of the parts are and how they fit together as we go along.

All part make up an engine, but some parts play a greater role than others. For example the crankshaft, rods and pistons are the heart of an internal combustion engine (ICE - note I didn’t use the acronym until I typed it out in full and directly after it, and really during a beginner tutorial is best avoided altogether) but I probably wouldn’t want to start there because trying to explain how this reciprocating mass works would get messy, and besides I would have the drill down on things like bearings which I never mentioned. What I might start with is the engine block, as it is a foundation stone in the engine.

Then I might mention the pistons slide up and down inside the bores inside the block. Next I explain that the piston that goes up and down is connected to a connecting rod, so named because that is its function. The rod and piston both travel up and down in the bore (again just reinforcing and building on the concept that rod and piston work in unison) there’s no need to mention at this point that the rod goes through an array of angles pushing the piston up and down, we are still just taking baby steps. Next we can mention that crankshaft is attached to the other end of the connecting rod and the function of the crankshaft is to turn in a circular motion. Probably time for a slightly more advanced picture or gif showing the crankshaft rotating and now you can mention that because the connecting rod is connected to the crankshaft via the big end of the connecting rod (called the big end because of its size relative to other end of the connecting rod which is called the little end or eye), when the crankshaft goes around the rod moves with it causing the connecting rod to also turn in a circular motion (we have now mentioned the rod angles but no mention of relative rod speed changes).

Even if you had no clue how an engine works just reading these few paragraphs and looking at the pictures (that would be there) you have just learned what is at the heart of most internal combustion engines (without being flustered). Doesn’t matter if it is petrol or diesel the fundamental concepts are the same. The same way the relationship between each of the Items, Things, etc etc would have the same conceptual connection regardless of what the final configuration may be.

I would bet money that if first time users could see and touch (metaphorically) Things, Items etc etc and understood in simple terms their relationship to one another without ever seeing a single line of code, when it comes time to introducing the code most people would get it so much easier and with fewer questions.


Now I realise that in software it may not be as easy to show something as easy as it is a physical item like a crankshaft, but that doesn’t matter, simply writing the word crankshaft tells us that there is an item or object named crankshaft. For example I write a list like this:


You may have no idea what any of these items are, but you actually now know several things you didn’t know a few seconds ago… There are three items in that list, and there are three things for you to know about. And when you learn about one of them you’ve just got another piece of the puzzle, in that you now know 1/3 of the puzzle.

But it goes beyond the obvious. Knowing I only have three things in the list to learn about, I can prepare accordingly. Imagine that list had 10,000 things written there… Would you approach how you would go about learning these things in a completely different manner? You might aim to learn a certain amount per day or you might try to learn one group of items within the list and get it down pat first.

This is what I was trying to explain earlier about not knowing what you don’t know. Even a simple list (or maybe a grouped list colourfully laid out so it is visually friendly) tells us something.

Just to add my encouragement: stay with it, it is so worth it; and yes, as all others already wrote: take it slowly and stepwise. It took me ages to get my head around some concepts, and MQTT was last on my list, as I had no use for it and did not want to learn about the complexity of yet another system interacting with OH, as long as I didn’t understand the basics of either. Playing with my hue lights was enough for me. For you MQTT is among the first…this just underlines the point that everyone’s need is different.

You ask for pictures, and you are right, when well done pics are worth a thousand words; and but not well-done pics can also confuse as much as a thousand confusing words could…it goes both ways; not sure about the other contributors here and on github; but my design skills are virtually inexistent. I cannot put pics on paper that look good; so whatever design I could come up with would certainly not help…
As you describe how strong your needs for visual cues are, maybe you can help and create some well-designed pics? I know it takes a lot of work to make them…(which may be another reason why there are so few). Your pic about a combustion engine is a nice example, but keep in my mind, combustion engines are around for a 100y and used on 100s of millions vehicles; I am sure when OH2 eventually becomes that popular somebody will have paid for making nice pictures too.

Just to reiterate what others said already, from personal experience, I can only press the issue of learning slowly. It is tempting to jump around, it is easy to do so too; but it confused me, and I ended to start at the beginning again to get clarity.

Lastly, am following the forum quite regularly and would like to point out that presence detection (that you mentioned as one of your next topics) is not necessarily an easy project; the idea is deceivingly simple, a robust implementation depending on what phones you have can however be mind-bendingly complicated, in particular if the expectations about the absence of falsely indicated presences and absences are high.

But that is my point a picture doesn’t have to be complex to be effective.
I have two groups one contains pets the other group contains tools. There are three items in each group and there are two groups.

Given sufficient thought by someone who really gets it, I don’t think it would take long to produce a picture that while not a masterpiece like mine would convey just as clear a message.