Here is a first attempt at creating something that I’m thinking about for a kind of visual “You are Here” drawing we can use in each of the sections. I would have the full drawing on the overview page and then each section would highlight on the same drawing what is being discussed. I’ve often wished I had a drawing like this to point newcomers to when explaining how all the pieces work together.
Here is the first shot at something to discuss. I don’t know if it is complete (e.g. is there a line between the Sitemap and/or rules and Things or do Things only interact with Items? It isn’t super attractive but I’m no designer. I tried to take my visual cues from the existing drawings.
I’ve attached the base file from draw.io as well if someone wants to mess with it before it gets checked in. This XML file is what will be checked in. I’ll have to see how the existing drawing works (i.e. does it generate the image from source as part of the build or do we just put an image in there and any changes require changing both the XML and PNG).
[quote=“rlkoshak, post:1, topic:13096”]
is there a line between the Sitemap and/or rules and Things or do Things only interact with Items?
[/quote]I don’t think so. The sitemap interacts with the items, which interact with the rules. There’s no direct line between the two. A rule interacts with items/groups which interact with the sitemap.
But that makes me wonder, perhaps the Items cell should have mention of Groups, too?
Wow there are so many different ways to explain something. I had an inside-out idea in my head:
The user in the middle, his client devices around him, the openHAB host with peripherals on the bottom, connected devices all over.
Bindings between host and the outside world
Sitemap on client devices
Things and Items next to a light bulb acting as an example
Rules create a “control circle”
Persistence on an arrow to a Database
…
Your idea is a great systematic approach and I love the idea of having this diagram in each sub article. My approach would probably fit nicely into the beginners tutorial @luotaus?
Regarding drawing: I looked into draw.io. It’s a nice tool indeed. I’m a bit worried to see that the xml file is just one big encoded junk of code. My personal preference would be to work with svg. How are you going to highlight one part of the png for each article? Do you intend to export many slightly modified pngs?
I really like the idea of the drawing, and I’m sure it will help people considerably. However, I’m personally not completely sure this is the best representation - I guess it depends on your point of view, and there’s always lots of ways of looking at things ;).
A few thoughts / comments / discrepancies…
The REST interface doesn’t just go into items - it goes separately into things/items/persistence/sitemap/etc - each have separate APIs and endpoints.
Charting doesn’t go from persistence to sitemaps. The charts are available via a separate servlet that can be called from the sitemap, or anywhere else - it’s kind of a separate interface. The charting servlet calls the standard methods to query data from the persistence database - the same one shown in your diagram for HistoricStates.
There are no “Commands and Updates” that go to a sitemap. A sitemap doesn’t really exist as a function - the system provides a REST interfaces to represent a sitemap, but item updates etc is performed through the items REST interface.
I would be tempted to show channels between things and items - this might help explain these concepts to people
draw.io is the system used for ESH documentation, so rightly or wrongly, it’s probably the best option.
I did think of that but a Group is just a special type of Item and I want to keep this drawing as simple as possible. If we make it “complete” I fear it will become too busy and difficult to read.
But I could be convinced otherwise. It would just take renaming that bubble “Items and Groups”.
This does sound like a good overview diagram. The drawing on the Overview page of the Guide is a nice view of how the OH 2 architecture is layered upon ESH. Your proposal is more of, what we would call in my field, a high level System View.
I like the idea of having such a drawing a lot, though I fear it may become too complicated. Maybe I’ll take a shot at drawing something this evening if someone else doesn’t run with it.
I would create a different drawing for each page. To indicate which page is being highlighted I would probably gray out/mute the colors of the other bubbles and make the one under discussion larger. Updating and maintenance can be a pain if the drawing changes a lot, but once we get this one where we want it I don’t foresee it changing much.
That is why I posted it here for discussion.
I mainly put in the REST line because there was room without really thinking about it. I’m not sure if even referencing it in this drawing makes sense.
I debated this with myself, and perhaps breaking things down a little lower would make sense. In my mind the “Sitemap” bubble was supposed to represent the UI over all not just Sitemaps. As such it would include the charting servlet. I can see having larger blocks with smaller blocks inside showing how many of these components are made up many parts. At a minimum a rename of the bubbles should probably be considered to make them more a topic than referring to a specific technical thing in openHAB.
Of course now that I’ve read what I just wrote, labeling that arrow “Charting” still doesn’t make sense.
Let’s just call it my mistake.
I struggled with what to label that arrow and decided just to post “something” than make it right.
So perhaps it make sense to represent a REST layer and put the UI on the other side of it and showing how REST does interact with all the parts.
I’m a little ambivalent about that though as this drawing is intended for the User’s Manual, not the Developers Manual. I don’t want to go too far down the path of being technically correct and complete at the cost of a drawing that users can not understand. I don’t think adding REST to the drawing goes that far but it is a concern keep in the back of my mind. Let’s add it and see.
I mainly didn’t add them because I frankly have no idea how they work yet (I’m woefully behind on actually playing with OH 2). So I chickened out and just labeled the line “commands and updates”. If someone can give me some background a little on how that works I’ll add that detail in.
Also, should the line from Items to Rules maybe be renamed “Events” and then a line from Rules to Items labeled “Commands and Updates”?
Thanks for all the feedback! This is what I had hoped would happen. I’ll take a shot at updating the drawing this evening and apply these suggestions and post it back here for further discussion.
Yes, I would clearly show this. If your diagram was meant to represent the “Sitemap” as the UI, then I would make this clear as it’s not at the moment.
Sure - but IMHO you should clearly differentiate the different elements of the system. If you generalise to much the user won’t understand how things work. I think it should be clear what the interfaces are - the detail I would agree can be glossed over quite a bit
Just add another element between things and items. In a nutshell, things expose channels, and items link to channels. The binding knows nothing about items - only exposing the channels it wants to describe.
I’m not so sure. You can either send a command on the bus, or post an update - an update is effectively an event (ie there aren’t 3 actions).
I didn’t mean add Events in addition to commands and updates so much as just label the incoming line Events, with commands and updates, from the Rule’s engine’s perspective, being events. Though clearly there is more information passing between Rules and Items as each Item’s state is also available within rules.
It is probably more confusing than enlightening to call that line Events.
After a bit of a hiatus I’m now back and can spend some more time on the OH 2 docs again. Here is a new version of the Diagram that I’ve put together based on the excellent suggestions above and some more thinking and learning on my part.
I think I have addressed almost all of the comments and probably introduced some new glaring errors.
I’ve removed the labels on the arrows for now largely because I don’t really know the best way to label them.
Ignore the colors, spacing and such for now. Once the content is right I’ll make it pretty.
I did not. I deliberately left them out and replaced them with “User Interfaces”. I also deliberately didn’t put it in a bubble because the UIs seem to be a thing apart, though I can see arguments for why I would put it into a bubble.
The intent is for the User Interfaces bubble to represent Basic UI, Classic UI, Habdroid, and openHAB iOS. I think the sitemap makes up a part of that whole system rather than being a system unto itself. At least that is how I interpret the comments from @chris above.
Arguments for why I may be wrong are welcome though.
What about a line between the REST API and Things?
Also wondering if you should represent the inbox somewhere in the diagram.
It’s probably a matter of personal preference, but I would tend to think of the REST API being a “layer” above the Things, Rules, Channels, etc. And the UI(s) would be a layer above the REST API. Charting, I suppose, would be in the same layer as the REST API?
If you’re going to include bindings, don’t you need a line between the REST API and bindings?
Just like the REST API and UI layers, I’d be inclined to show the databases as a layer at the bottom.
I added that line based on the following comment from chris:
I know nothing more than that. I can surmise that there is a REST API that PaperUI uses to work with Things directly. I was actually wondering if the REST API actually should point to Channels instead or in addition to Things.
I don’t think so. The Inbox must be discussed of course and the next level down drawing (if one is desired) that shows Things/Channels/Items in more detail would show the Inbox. But IMHO it doesn’t belong at this level as a separate box. I almost left the Charting servlet off as well and may still do so if there isn’t a lot of pushback.
I deliberately chose not to depict this part as a layers architecture. Layers are a great way to show an architecture when one must traverse all the way down the stack (or all the way up) to get over to another component. I don’t know if that is the case here. And even if it is, layered architectural drawings are great for showing which parts of the system need/are build upon what but not so great in showing which parts actually talk to the other parts.
Unfortunately this is the major drawback to having someone who knows how it works from the outside creating the drawing for how it works on the inside. I don’t have time to delve into the code right now though.
But switching to a layered view could be useful as it allows the Event Bus to be brought into the picture. Unfortunately I don’t know how the Event Bus fully fits in with relation to the REST API and everything else. I would guess, based on how I would build it, that Rules, Persistence, and the REST API all hang off the Bus and that is how they all communicate.
Also, we already have a layered architectural view on the Overview page, though its focus is more to show how OH 2 is built on top of ESH which is build on Karaf and Jetty.
These kinds of drawings are never complete nor do they ever answer all the questions in one drawing. Sigh…
My primary intent with this drawing is to provide something that will help new users understand which major parts of OH interact with which other major parts so it is easier to write about and explain these interactions in the text. I chose a bubble data flow type drawing to show this. I can be convinced some other view is more appropriate.
Honestly, if I were doing this for work I’d be generating use cases and sequence diagrams but those are a bit arcane for the intended audience.
Do I? Does the REST API talk directly to bindings or does it talk to bindings through Things and Channels? I assumed the latter (I’m hoping someone who knows better can tell me if I’m right or wrong).
See above for layers discussion.
As for putting it at the bottom, that is indeed traditionally where the data layer usually goes. However, despite my championing of persistence, persistence and therefore the databases are almost optional (this excludes the MapDB where configs get stored which I assume doesn’t go through Persistence and instead saves it directly to the DB). I’m hesitant to make something that is optional be the base layer of a layered architectural drawing.
Maybe just my misunderstanding. The REST API gives you access to information about the bindings that are installed (e.g. http://localhost:8080/rest/bindings). Probably not relevant for what you are trying to do with this drawing…
I’d then say that the REST API is talking with the core (not shown in the drawing) and not the bindings themselves. It’s kind of meta and makes the head hurt. I’d only show the arrow to the bindings if you can actually directly access code running inside a binding straight through the defined REST API, bypassing Items, Things, Channels and all the rest.
I think of it kind of like running top on Linux or Task Manager on Windows. It shows the list of all running applications but neither talks directly with those running applications to generate the list, they talk with the OS upon which they are running.
