Create a Graphic(s) showing the relationships between Things, Items, Persistence, Rules, and Sitemap

[rkoshak]

I intend on using Draw.io so we can keep the source with the project. I believe that is what was used to create the existing architectural drawings already in docs.

Discussion on the forum is here:

https://community.openhab.org/t/lets-talk-about-oh-2-drawings/13096

[kubawolanin]

I suggest a Jekyll plugin that would allow to store and edit the graphics in plain text.
jekyll-graphs looks like a good candidate.

[kaikreuzer]

Draw.io is the agreed tool for ESH documentation and it is e.g. used in https://github.com/eclipse/smarthome/blob/master/docs/documentation/concepts/diagrams/event_interfaces_source.xml.

As this issue is about the explanation of core concepts, I would actually encourage you to think about contributing it to https://github.com/eclipse/smarthome/tree/master/docs/documentation/concepts, which is picked up by the concepts menu of docs.openhab.org.

[ThomDietrich]

@rkoshak ping

[rkoshak]

Totally forgot about this one. Looking into it, refreshing my memory.

[LightIsLife]

@rkoshak @ThomDietrich
Found this slightly older issue and got intrigued. I think it is a great idea to have such a graphic and I am not aware that it already exists anywhere. However, I may be wrong and I am not even sure if this is still a "real issue" or just a forgotten one. Let me know. If I more or less captured what you intended, I am happy to develop it a little further.

I developed a chart (using draw.io of course), it is attached here as zip, as native xml is not supported by github.
OH2 principles (9).xml.zip

and here some draft text that could go with it:

Bindings, Things, Items, Persistence, Rules, and Sitemap

To be able to manipulate real objects (e.g., color-changing WIFI connected bulbs) openHAB will need to communicate with these objects and be able to represent them in user interfaces and elsewhere. For this openHAB is using Bindings, Things, Items, Persistence, Rules and Sitemaps. To help the reader understand the most critical elements of how it all works together, the remainder of the text uses a simple example:

Alex has purchased smart WIFI-connected bulbs from two different manufacturers and wants to use openHAB to switch them all automatically on at sunset. Alex has connected the bulbs to the WIFI network and already installed openHAB on a computer in the same networ.

And here a brief overview of how the various elements of openHAB work together.
BINDINGS For openHAB to interact, for example switch on, the bulb in the room, it needs to be able to “translate” the switch on command into a sequence of commands that the bulb will understand; the Binding performs this translation for as many objects as desired that are able to speak the “same language”, typically, this requires one binding per brand of bulbs.
THING is the first representation within openHAB of the real world object; a Thing is specific for the real world object and breaks the various capabilities out into channels; for example, a bulb will have an ON-OFF channel to switch it on and off, and a Color channel to set the color; it may have also channels for the brightness and the color temperature, but for this example we will ignore these for now.
ITEM is the core element that openHAB uses internally to save and change the status (State) of a specific capability of a real-life bulb; an Item carries at least a user-defined name, for example My_SwitchA and a state that represents in the computer the status (State), for example whether the lamp is switched on or off. Items can also receive commands and transmit them to the real-life bulb, for example to switch it off
RULES make home automation work like magic. A Rule is a little program that for examples determines whether the time right now is after sunset, and if so sends commands to switch on the bulbs
PERSISTENCE is the memory of openHAB. Items only carry their current state and have no awareness of past events. Persistence is a queryable database that allows to retrieve state information from previous timepoints. A Persistence Strategy is necessary to define which items are desired to be persisted.
SITEMAP represents any items the user wants to display on a screen (phone, computer or tablet); Each item and its state can be displayed and user friendly names can be defined to be shown, for example that My_SwitchA is displayed as “Living Room Lamp”; sitemaps can group and structure the displays and also display graphs with historic information from the Persistence database

The text above and the graphics give only a very superficial description, however, to fully understand and use openHAB it is important to grasp the difference between the described features.

[rkoshak]

I keep getting distracted and am not a great contributor to GitHub. I am apparently more event-driven these days.

I highly recommend taking Kai's advice above and move this issue to the ESH project. Any change/addition made there will be picked up by OH and will benefit both projects.

I'm not sure if what I'm about to say is even possible but here goes:

• The text above sounds good
• The content of the drawing is there. I can follow it and understand everything even without the text, but I fear it is a little too "engineering" for the average user. I am not sure that many non-programmer types will get much use out of a drawing like this.
• From a look and feel perspective, it probably needs to more closely match the look and feel of the existing drawings in the docs
• An actual screenshot of BasicUI would work better for the Sitemap part.

Some suggestions, which aren't worth a whole lot, given how badly I dropped the ball on this one:

• Replace the text in "My awesome rule" with a cropped screenshot from Designer. When the Experimental Rules Engine matures, we will want to replace that with a screenshot from it.

• Get rid of the text under Persistence and just have the cylinder labeled Persistence. Cover the text part in your accompanying text as you do above.

• Show the bindings talking directly to the bulb and cut out the LAN/Wifi parts. I think the drawing conveys the same meaning more simply without it and it makes the relationship between the binding and the device more explicit.

• Regardless the Astro binding is completely self-contained (its one of the few) and doesn't have an arrow that goes to the LAN.

• It might be worth showing Persistence as a box pointing to an example DB as it is an external interfacing component just like the Bindings are.

• One thing Chris was very interested in showing, though it may be too much to show on one drawing like this, is the REST API and how it interacts with the Things, Items, et al in addition to being the way the UIs interact with OH. Maybe it would be a good thing to show a separate "Administration" drawing showing PaperUI and how it interacts with the various parts of the system.

Great work!

[ThomDietrich]

Hey, just a short comment from me, it's late :)
I agree that an overview is important, a graphic is even more helpful.

I have to add, that I fear a single diagram is hard to get right, complete and updated. We've invested a lot of work into documentation parts like this and all the referenced articles. Not all of them are finished or even presentable at the time but the important ones have reached a good maturity.

The diagram looks great and the comments of @rkoshak are thoughtful, I wonder where to put this diagram in the end!? Because of it's way of explaining everything with examples like the wifi router, I wonder if the best place for it would be inside the Beginner Tutorial, in which a good link to the real world would definitely help to understand the significance of openHAB parts.

How do you think about that idea?

[rkoshak]

I think the Beginner's Tutorial is a great place for it. And instead of vague generic WiFi Bulb A we can actually reference real examples.

[LightIsLife]

Thanks both. I am fine with either of course place. Happy to make it more real, any preferences of brand names to mention in stead o bulb a. Hue should likely be one tp-link the other? Personally, I have no preference whatsoever, which was one of the main reasons to go with bulb a

…

On Mon, Sep 18, 2017 at 11:55 PM Richard Koshak ***@***.***> wrote: I think the Beginner's Tutorial is a great place for it. And instead of vague generic WiFi Bulb A we can actually reference real examples. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#69 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AXtFf9DYvcey9boz90v-NiDrO_wJEF0wks5sjubDgaJpZM4JfrpQ> .

[rkoshak]

Actually, I would rather see something like Hue for one and zwave or something like that for the other. This seems like a great place to subtly emphasize the fact that OH is a bridge connecting multiple technologies.

I don't think the brand names or specific technologies are all that important.