Looking for the ultimate beginners guide

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.

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.