Looking for the ultimate beginners guide

Or maybe if it is a little less linear than a stack, perhaps it could be represented in a process flow diagram, that way it has the options to take different paths depending on decisions…

In networking, each layer in the stack adds its own stuff to the beginning and ending of each packet. This is what I mean by encapsulation.

In OH, we are just sending messages and making function calls. One doesn’t take an ON command, add some stuff to the beginning and end of ON and pass it to a Thing, then add some stuff to the beginning and end of that and pass it to the Binding. That is how networking works. Instead it is more a process of interpretation and transformation at each layer.

It is important to also be aware of boundaries if what we are talking about. I purposely stop at the Binding and do not talk about how the Binding communicates with the device (in this case the MQTT broker). I do so because:

  • it’s complicated
  • it’s completely different for each and every Binding
  • all of these differences are purposefully hidden from OH by the Binding so we don’t really need to look at that to understand OH

Again, what I’m talking about is strictly internal to OH. How the Binding communicates with MQTT is not part of this discussion. But indeed, yes, the MQTT Binding will use the full TCP/IP networking stack to communicate with the Broker. However, the Zwave Binding will use a direct serial connection to a USB Controller which uses a proprietary mesh networking protocol to communicate with devices.

Again, the stack I’m talking about is strictly internal to OH.

Same methodology yes. But I’m uncomfortable trying to shoehorn the OH stack into the networking stack because the layers do not exactly line up. Trying to do so is more misleading than informative.

Indeed. A layered representation could work. Just don’t spend too much time trying to draw parallels to the TCP/IP or OSI stacks.

It could be but I can say that for the vast majority of OH users, a drawing like that would be more confusing than helpful. The average non-technical userlikely has no idea how to follow a flowchart.

Note the above is not complete nor completely accurate.

  • All detail about how a binding communicates with devices is ignored.
  • All of the core set of services and the glue from ESH and OH that holds everything together is ignored. This includes but is not limited to the Inbox, Binding configuration, Voice, Audio Syncs, etc.
  • Lots of concepts are ignored like Groups,Bridges, Tags, external services like Alexa, etc
  • OH 1.x bindings and how they work with Items are ignored.
  • While I only had room to show three channels, a Binding can have zero or more Channels.
  • There are a couple special cases where a Thing can put events onto the Event Bus without going through an Item: Channel Triggers and Channel Online Status

Key take aways:

  • Each device is represented by a Thing
  • Not all Channels have an Item.
  • Not all Items have a Channel
  • Not shown, but an Item can link to multiple Channels
  • An Item can link to no Channels
  • Some devices can have more than one way to control them with each way represented by a separate Channel (e.g. a Color Bulb that has a Switch, Dimmer, and Color Channel for each of the three ways to control a Color Bulb).
  • The REST API can work with all layers of the architecture
  • The UIs work through the REST API

As I use knx I often refer to the naming.

An actuator is to make something happen, e.g. a relay to switch lights on or off, a dimmer, a set of relays to control a motor to move the roller shutter up and down (and stop…)
A sensor is to get information about a state of something, this may be a wall switch, a motion sensor, temperature, brightness and so on.

In question of knx, this is a bus system. There are actuators and sensors which communicate to each other (each device has its own ‘intelligence’). openHAB gets contact to this bus by using an interface, this may be a serial, USB or IP interface. openHAB needs to know how to communicate with the bus, this is the job of the binding, so one bus -> one binding (configuration).
There are bindings which can be used multiple times to communicate to several similar buses, e.g. you could use two enocean interfaces to talk to different enocean “zones” (maybe otherwise some devices wouldn’t be reachable because of the distance).

Bridge: as openHAB gets contact over an interface, this interface maybe may be called a bridge :wink: in openHAB2.

As @rlkoshak stated, items can be linked to no, one or multiple channels. To make it even more complex… speaking of knx, an actuator has several objects to communicate, communication can be unidirectional or bidirectional (per object…) but every object represents one detail, e.g. a knx dimmer has 5 objects, which are all represented by one item:

knx object 1: Switch Light ON/OFF
knx object 2: Get ON/OFF state of Light
knx object 3: Dimm Light to xx%
knx object 4: Get % state of Light
knx object 5: control relative dimming (UP/DOWN)

The Dimmer Item in openHAB will represent the % state and you could use commands like INCREASE/DECREASE/ON/OFF/xx% to control the dimmer.
Of course a knx dimmer has more objects, e.g. a scene object, forced control, dynamic timer… depends on the dimmer and the ingenuity to the manufacturer :wink:

If there was a knx openHAB2 binding, one dimmer would be represented as one thing, and one object would be represented as one channel. even more confusing… :wink:


Agree I don’t think we need to go to the trouble of trying to align it to either the OSI model or the TCP-IP stack either, I think it would add unnecessary confusion for people not familiar with both, with little benefit, but think conceptually using a “stack like” representation / drawing could be an easy way for people to visualise the relationship

I don’t think I would try and do it with one drawing because there are so many scenarios, so perhaps some of the more common scenarios could be portrayed.

As far as a flow diagram goes I don’t think it would hurt to have both since if you don’t quite understand one way you can use the other for reinforcement.


Ok so you’re using the term “actuator” in a more general sense to mean something like the word “facilitator” That’s fine if I know the context you mean it, I thought you were talking about an actual linear actuator.

I guess because I have a few of them kicking around here waiting for my remote control mower project you meant the real thing.

Guess it is hard when people are from all over the globe because we do tend to have our own local way of saying things.

But that’s fine if there’s a glossary and/or efforts are made to remove any ambiguity.

In a beginners guide - terms that are difficult to understand should be avoided unless they are absolutely needed and then they should be described either directly in the paragraph/page in which they are being used or referred to in a glossary.
Of course links to further reading should be provided but a beginner shouldn’t have to follow a sequence of links when trying to understand a basic concept.

This is why simple examples of Items and rules work so well. They are simple enough for the user to understand and get working on their system without having to follow tens of links to other pages to understand the concepts explained.

The detailed stuff can come later.

The inpatient part of me is inclined to agree. If there was a “cookbook” (and no I’m not talking about a bit of info here and a bit of info there) that had a number of working recipes (every modification to every file needed) in one dedicated place (no hunting links or threads) it would really help the progress of the absolute newbie.

I have yet to put together anything that could be considered complete. It would be really great if there was a dedicated resource where you could try out simple tried and trusted recipes. Although they would need to be version marked to ensure they are being tried on the system they were designed for.

I would especially like to see some recipes where no additional hardware was required, because we all don’t have every device available, so it would be great to see a result with either no hardware or maybe some common hardware that would be typical like a home network or a mobile phone, something 90% of people would have.

Something the newbie can just plug and play to get a taste of it working. I have to wonder how many newbies gave up on OH before ever getting it to work, whereas a working taste would have keep the interest going.


OpenHAB is a volunteer effort. If you want something improved, roll up your sleeves and do it.

Cease speculating about improvements and focus on implementing them. Instead you’ve written dozens of posts about perceived shortcomings in the documentation. When told everything you need to know is already in the documentation, you’ve countered it isn’t presented at a level you can grasp. You then revealed it is difficult for you to remain focused while reading, and you need pictures to learn, and you did poorly in school, and there are few diagrams and no glossary, except they do exist and you simply haven’t read them, etc. We get it; you are “learning challenged”.

Thousands of people have learned how to use OpenHAB (at a time when the documentation was far sketchier than it is now). There are new concepts and terminology to grasp, they are presented in the documentation and tutorials, and have been clearly reiterated in this thread by @rlkoshak @udo_hartmann and others. If this is insufficient, contribute to make the documentation comprehensible to you and others with similar learning needs.

I hope you stick with OpenHAB, and contribute to it constructively, because it is an impressive product built by dedicated volunteers who have given countless hours of their time to its evolution and improvement.

Good luck!

Well, given our difficulty in getting people to contribute to the documents in the first place, any drawings that present the same information in different ways will increase the effort required to update and maintain the docs, effort that we are already falling behind on. So it can indeed hurt.

It is also hard because OH supports such a variety of technologies, sensors, and interfaces, that we have to use generic words when we talk about these things. That is why we have Items and Things.

Great idea. Have you filed an issue or submitted a PR?

So there is a whole Demo package that you can install that includes a complete setup that is intended to provide a fairly complete working example from Things to Sitemaps and Rules.

I’ll just add that filing issues that describe these ideas is one way to contribute to the docs. You don’t have to write a new article or change something, though that type of contribution is more than welcome as well. But if these ideas do not turn into Issues they do not get captured and eventually implemented.