Looking for the ultimate beginners guide

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.

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

I appreciate that a lot of work goes into openHAB but the kind if statement above (and I use this as an example of many), is basically a complete waste of everyone’s time:

I’m a beginner. I do not know what ‘reach control’ is.
If I google search ‘reach control’ on www.openhab.org I get zero results.

If I google search ‘reach control’ on https://community.openhab.org/ I get one result - namely the above post.

If I google search anywhere for ‘reach control’, I get links to various academic dissertations on complex robotics.

If I go on, ‘Device’ isn’t in the glossary either.

‘Piece of information’ is pretty meaningless too.

The whole statement therefore has no meaning in the context of explaining openHAB.

I don’t agree with everything Mr.Headscratcher has said but he has a got a point.

@HeadScratcher i did not read everything what you wrote but i think i understand you very well.

This is how i would proceed:

  1. Install an image on sd card, enable ssh by addign a file named ssh to the boot partition

  2. start the rpi find its ip with wireshark.

  3. As Windows user i install xmoba https://mobaxterm.mobatek.net/ and http://www.sftpnetdrive.com/
    xmoba for ssh connection terminal and sftp file browser to browse files on your rpi
    additional sftpnetdrive to include your pi´s drive to your windows explorer and enable you to edit them in windows.

  4. Also on your windows host install VScode with openhab extension. With this you will edit the files which are on the rpi.

  5. Connect to rpi with ssh by xmoba

  6. Install openHAB / Java if it is not included in the image.
    1.Start with an easy tutorial for reading temperatures of your pi. But read the 433Mhz example first as it tries to explain how everything works together.
    OpenHAB Exec Binding explained in detail on 433MHz radio transmitter example
    Openhab2 RPI System Temperature and DS18B20 OneWire Chart with persistence

The people from openhab are great people and have accomplished a nice environment, but for the documentational part they somehow can’t understand that this long growing environment is not selfexplaining and unexperienced user have to be fetch from where they are. As it is stated on https://docs.openhab.org/index.html you may help to improve the documentation!
But good look with that.

Try to figure out the basics and ask in the forum when you stuck mostly there is someone willing to guide, which would not be neccessary if the documentation would be somehowe better to grasp.

There actually is a picture, in the Things section of the Concepts section of the User’s Guide.

A typical.

Each piece of information and each control point (i.e actuator) has a channel. For example, I have a power sensor with several different values it reports and an actuator that resets the power counter value. Each and every one is represented with a separate Channel.

When an Item is linked to a Channel it means that updates to that channel get reflected in the state of the Item. Similarly, when a command is sent to an Item, that command gets sent to the Channel where it is concerted to what ever is required to cause an actuator on a device to implement the command. For example, an ON command sent to an Item linked to a Zwave light switch will cause the switch to turn ON.

It’s a freaking typo.

It’s not that we don’t understand. It is that no one is working on it. You have good ideas. Everyone on this forum thread had good ideas. How many of you will actually do something about it? Anyone can make changes to the docs.

All I ever see are complaints about how bad the docs stuck. Rarely do I see complaints that are actually actionable can (I have seen several actionable ideas on this thread which is refreshing) and even more rarely do I see the people complaining bothering to file an issue let alone doing something about it.

The docs will never get better until people start contributing.

File actionable issues. That isn’t so hard.

Make small edits to the docs that are there. You can do it straight from the browser.

Thanks Udo for the diagram just trying to digest what you have there…

I see three actuators on a bus (sounds like the start of a joke) and each actuator uses a physical switch to trigger it,so that would suggest the actuator are controlled by the software system rather than being an input, so that tell me the direction of data travel is outbound towards the actuators.

On the software side of things there is a single binding represented between the software and the physical hardware of the bus. Since it would be bound to something like an I2C chip this is inconclusive as to whether the binding needs to be one to one, or can be one to many (don’t want to make assumptions so will leave that as is).

A bridge is a new one on me but I see three Things inside of it, so it appears to be something like a Group. Don’t want to draw any conclusion as to the functionality of the bridge at this time as there is insufficient information to draw a conclusion.

Now as determined earlier, a Thing is a software representation of a physical object… (hmm I like that definition, I might use it).

Now that changes things… because now we have three logical switches controlling three physical switches through a single Binding.

The bus makes it a little bit tricky because although it is controlling several physical switches it is seen by the software system as a single chip, so that would imply the Binding has a many to one relationship, as in it has many logical switches that are controlling one bus chip.

Although when I look at the diagram again I wonder if it is drawn right… Hmmm assuming the Bridge performs the same kind of functionality it would as in a regular network, it would be used to bridge network segments, which would mean the three Things should all be individually connected to the Bridge instead of being inside of it.

That would change everything because now the Bridge would perform a routing function to funnel the three Things through a single Binding, which would mean the Binding has a one to one relationship.

The two Things below appear to be an exploded view of two of the three Things above. Which would make sense since there is little point in representing the Switch twice. There are only two unique types, Switches and a Dimmer.

Now it gets a bit tricky again… Just trying to think my way through this… Although Switch 1 is a software representation of a physical object, that doesn’t stop it having multiple States or properties… In fact thinking about, it really can have less, the same, or more properties that the physical switch it represents, since it only exists in software.

Ok so looking at the diagram the Channel represents one function or property of the Switch 1, and that one function / property is an Item, therefore that would suggest an Item and a Channel are one and the same thing… That can’t be right.

I think I am getting slightly confused by your terminology… The only actuator I know of is a physical device which is controlled by a motor to move a shaft, you appear to be using the word in a different context, which is probably why I am not getting your meaning https://en.wikipedia.org/wiki/Actuator

I so hate words, they can be so confusing. Give me numbers any day.

Think of it like the TCP/IP stack as an analogy. Like the TCP/IP stack, OH uses layers of abstraction and well defined interfaces between those layers.

At the lowest layer of the stack is the Binding. Bindings understand how to communicate with the actual physical devices or software APIs.

The interface between Bindings and the next later up are Things. OH only interacts with the Bindings through Things.

The next later up in the stack are Items. The interface between Items and Things is through Channels. It is possible for Items to exist that are not linked to any Channels as well as possible for Items to link to multiple Channels. It is also possible to have Channels that do not have any Items linked to them.

The final layer is, for lack of a better term, the Application layer. This is where Rules, Persistence, and the UIs exist. The interface between Items and the Application layer is the Event Bus.

The above is a simplified analogy. There are a lot of concepts not discussed and a number of oversimplifications. Do not treat this analogy too literally not assume it is complete.

That believe it or not makes way more sense… Been nearly 20 years since I learned the OSI model but I remember it well enough to get the gist of what you mean.

Let’s see All Paul Should Trust Now Defies Logic and Physics, so that translates to

Application { openHAB GUI }
Presentation {Rules Persistence or }
Session {Rules Persistence }
Transport (Event Bus?)
Network (Items connected through Channels or straight to Things)
Data Link (Things)
Physical (Binding happens at this level)

Something like that… Hmmm thinking that would be a whole different kind of picture to draw. Will need to revisit what each of the layers do to get that to sink in better.

Ok Those guys don’t obviously line up, but shouldn’t be too hard to work out there proper places…



I’m going to go out on a limb here and say that if the Binding is the last cab in the rank ( or first out the door for the want of a better metaphor) then it probably sits at Layer 4, because Layer 1 is just bit transfer zeros and ones. Layer 2 Contains the MAC address and is still dealing with physical network hardware devices, possibly could be at Layer 3 but I am thinking more like Layer 4 because it is Host to Host control. Yep lock in Layer 4 for $200.

Yep definitely L4 or above… But that still helps because it defines its role in the scheme of things.

Ok that would also tell us the Binding is a one to one relationship and everything for that device to device communication is funneled through that one binding.

Also it is only setting up machine to machine communication, it isn’t performing any other function so definitely L4.

Finally one piece of the puzzle falls firmly into place :smiley:

Be carful to draw too close of a parallel been the OSI model and OH. Like I said, it is an imperfect analogy. I purposely choose the TCP/IP model instead of the OSI middle because it has fewer layers and the analogy is less stained.

But the two work fundamentally differently. The networking stacks work through encapsulation and OH works through messaging.

While it doesn’t explicitly show this, the picture in the very first page of the User’s Guide does show this layered architecture, only it is more complete and less detailed at the same time.

I mainly brought it up as a way to help think about the realistic between the concepts, not to be a literal reflection of how. oOH works. Taking it too literally will lead you to some false conclusions about how certain parts of OH actually work.

And this is part of my point, the binding would probably make up layers 1 through 4, with some intrusions into five. That is why it is an imperfect analogy.

Rather than trying to shoehorn OH into the OSI model, it would be more informative to think up a separate layered model to represent OH.

One important caution is that is only one stack. There is a while other stack built up on bindings and Things. You also have a different stack of you are looking from device to Items verses base to items (i.e. how everything runs on top of ESH).

For some bizarre reason I look at the TCP-IP stack and it rings no bells whatsoever, I know we covered it at College but it doesn’t even look vaguely familiar…

“But the two work fundamentally differently. The networking stacks work through encapsulation and OH works through messaging.”

But wouldn’t messaging still be encapsulated??? I mean after all even if it is just pushing plain messages around the network in order to get from OH to MQTT it would still need to be packaged with all the same header information to know where that simple message packet needs to go.

Any which way whether you use the OSI model or the TCP-IP stack if it sends and receives data it must be pushing up and down each stack to do it…

But putting the complexity of how it aligns (or doesn’t) aside we can still use the same basically methodology to represent it in a drawing.

You said Binding was at the bottom of the stack, regardless of the level or letter we may give it Things sit above it. A picture using a simple layer type arrangement could still be used.


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.