Looking for the ultimate beginners guide

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.

Maybe the best way to represent OH might be something like this to show the relationships between the different objects… Or several different ways showing the same thing since people pick up things differently.

There is no amount of words that could express how much I agree with you!!!

The same holds true in every aspect: science (this is where I come from), economy, philosophy. In my experience simple requires a huge amount of work and a LOT of input from all stakeholders; I had numerous cases where simple for me, was not so simple for others and vice versa. But, once done it is enormously successful and extremely helpful.

It seems that you could really add to the docs of OH2 as you seem to have a clear vision of how a graphical aid needs to look like in order to be helpful; personally, I do not have that amount of creativity or visual imagination, so I am always a little confused when people ask me to draw something on the whiteboard (and what I draw really does not look good). It is so bad, that I would not even know how or where to start in order to make your frenemy graphic. Your talents seem to be much greater here, and I am sure that a lot of people would be very grateful if you could translate the docs in a more pictorial “language”; as you noted already earlier: everybody learns differently and currently visual learners are less well supported by the way the docs are written.

Thinking about it, the interconnecting circles is definitely the best way to define the schema (paint the picture). Only problem is knowing the relationships.

I know Items fit inside Groups and I know there is a relationship between Items and Things (not exactly sure if Items are inside Things, or if they overlap, or if they’re separate), no idea how Channels fit into the picture, but they contain Items so that would probably mean that Channels, Things and Item are going to overlap somehow but really not sure what that would look like.

Sitemaps, Bindings, Rules, Scripts, Persistence, Transforms are mostly just words to me but I’m sure they each have a relationship with at least one other object in the grand scheme of things.

My memory is so fuzzy but in the late 90’s I learned about relational schema in college, I’m sure if I could remember how that worked it could help represent the relationship of all of these entities. Perhaps even help draw what we need.

It’s vaguely coming back to me, but it went something along the lines of a person has one first name, but many people can have that same name. So somethings were one to one, something were one to many, and I think there was a many to one, and a many to many.

I imagine this would somehow relate since whatever uses Rules or Transforms (might be Items) can probably use many Rules, or maybe a single Rule might be used by many Items… I don’t know getting a bit over my head.

Unfortunately I lent a friend my relational schema book but just looked this up on wiki https://en.wikipedia.org/wiki/One-to-many_(data_model)

Between interconnecting circles model and the relational schema drawn out I really think these two pictures would answer a bucket load of questions,

Unfortunately this has again turned into a circular argument

you can find the info In a previous post further above

The relationship between things, channels and items is more like mapping and less like overlapping circles. Hope that helps

The Device is represented as a Thing, made sense because I think I said something to that effect before this comment was made, but this made no sense to me at all.

I bet if I saw that as a picture I would get it in nothing flat.

Although reading it over and over it still makes no sense to me… What is a reach control is it physical or logical or just a term being used? I don’t understand the context in which “information” is being used. I look at this and all I see are jumbled words, I’m sure others would look at this and it would make sense, or possibly if the words were arranged in a different order it might make sense to me.

What I do know from my own observations were that as soon as I installed the Network Binding IP addresses showed up in the Things, which told me that Things are in at least part made up of physical objects like computers (although this doesn’t necessarily exclude Things from being non tangible items as well, just because there are none showing up doesn’t exclude them).

If I went back through the instructions (because I can’t remember what I did) but when Channels showed up Items were in them, and while I could just ASSUME that Item were indeed inside Channels, that would be a stupid assumption to make without further information especially since Items has other relationships.

And what exactly does linked mean? I don’t want to assume it is what I understand it to mean and store wrong information in my head to then later have to be cleaned out.

Linking to me could me anything from an exact copy of information used as a delegate, to some kind of permanent and binding connection between the two, or even a temporary non binding connection. Without understand their relationship I can’t fathom linking. This is why I need to see the big picture then many things like the concept of binding would automatically fall into place.

Did I mention if I don’t understand something the chances of me retaining it are less than zero… I don’t have the greatest of memories so if I don’t understand something I forget it almost instantly (by the time I have finished reading it). If I get something and it sticks it can stay anywhere from a short time to a very long time.

Funny thing is I remember numbers and formulas much better than I do words.

I can get to the last five minutes of a movie and realise I have seen it before. Annoying to have such a crap memory but great if you like watching movies for the first time (over and over).

Just a try to enlighten this Things and Items:
The left part represents the hardware. The right part ist the software.

There might be a bridge or not, that depends on the sort of things to represent (e.g. there is no need for a bridge for a bunch of TVs, even if they are the same model)

You may want to link some channels to Items to use them at rules or in the UI, others might stay unlinked.

One thing to keep in mind is, the Things model is newly introduced to openHAB since OH2, in OH1 there were only items. The Things were invented to make an additional abstraction layer.