[wiki] Getting Started with OH3: rewriting the tutorial - 1. Introduction

Tags: #<Tag:0x00007f617ef70b20> #<Tag:0x00007f617ef703a0>

This Wiki topic’s goal is to serve as a working document, in order to provide an up-to-date tutorial for OH3 aimed at new users and novices. Everyone is welcome and encouraged to edit it, when we’re satisfied it will make its way to the official docs. You may reply for the specific purpose of improving the article are allowed, but please, this is NOT a support thread: if you’re stuck while reading this and are simply seeking support please open another thread. Thanks!


First, a word on the order of the sections in the docs. It assumes users read them in order, that is, first the concepts, then the installation guide, and when they reach the tutorial section. I’m not so sure about this so I’d suggest to call the tutorial Getting Started or similar and move it to the top. Then the tutorial intro’s first paragraphs could be a quick overview (or recap) of the concepts and the installation options, with links to the other sections (Concepts and Installation Guide) to go deeper.

Also, I’m not the biggest fan of the content on the entry page at https://openhab.org/docs/, especially the “motivational speak” right at the start (“keep your focus”, “result of hard work” etc.), IMHO that page should go back to describing with a neutral tone how the docs themselves are organized, i.e. what the sections are and what you can find in them. That content could however be a good fit for the introduction of this tutorial/getting started section. The only section I would leave there is the “openHAB community” and maybe the last one about architecture.

An important decision: file-based or UI-driven configuration

Make the reader aware of a decision that has to be taken early because it’s not trivial to walk back from it later: whether to configure their system with files or the UI.

Present the two approaches and their pro & cons:

File-based

Pros:

  • Has been the only really practical way to define most objects (Things excluded) in previous versions so a lot of examples in the docs and the forum will assume that’s the approach you took;
  • Easier to make bulk changes/updates/duplicate similar objects or separate domains into distinct files;
  • Can be treated as source files easing backups & version control.
  • Files can be synced through any file sync servies (e.g. Dropbox, Nextcloud) to the openhab machine
  • Easier to share configurations between multiple openhab instances

Cons:

  • Is more prone to errors i.e. the slightest typo leading to a syntax error causing the file to become invalid will result in everything defined in that file removed from the system until you fix it;
  • Can be a little overwhelming for novice users, as you have to learn and understand the syntax;
  • You’ll see most objects defined in files in the UI but you won’t be able to edit them (those objects will have a lock besides their name/label :lock:);
  • You need to sit in front of a computer with access to the files to make changes.

UI-driven

Pros:

  • Easier to understand for novices, the UI assists you, there’s fewer opportunities to make mistakes or build a bad item model;
  • All objects can be altered from anywhere the UI can be reached (including on mobile);
  • Things can be auto-discovered;
  • The internal database is somewhat faster especially on resource-limited devices (RPi) than the file parsing.

Cons:

  • Can be slower to reach one’s goals if you know what you’re doing, if there’s a lot of changing or duplicating involved etc. (the UI can also add items and sitemaps, perhaps things in the future, in the internal database using the file-based syntax.);
  • Harder to remove obsolete stuff;
  • Some things cannot be configured with the UI yet (e.g. persistence).
  • You need to sit in front of a computer with access to the UI to make changes.

It’s possible to mix the two, for example use the UI for things and files for items, but avoid using both techniques at the same time in other cases. In this tutorial targeting new users we’ll take a purely UI-driven approach.

Next steps

Some intro on what we’ll achieve on each step.
(the following will become links to other pages)

1. First Steps

Wiki

  • unlock the administration area, create the first admin user, configure some regional settings etc. Could change because there might be an initial “welcome wizard” for this stuff.

2. Adding your first Things

  • Use 3 examples with lots of screenshots, of increasing complexity:
    • Simple - a Philips Hue bulb: just install the binding and everything is discovered eventually, show the error message when the user has to push the button on the bridge;
    • Intermediate - a Z-Wave connected rollershutter module/power outlet: install the binding, add the controller manually, go into pairing mode, add the discovered devices from the inbox;
    • Advanced - a generic MQTT-based plant sensor defined manually: install the binding and the JSON transformation, add the broker, add the thing, add some channels and configure them to use the JSON transform.

3. Building a semantic model of Items and linking Channels

  • Describe what the semantic model is (see HABot walkthrough - second topic), why it’s the recommended way to organize items, and start adding some Locations;
  • Use the “Add Equipment to Model” (from a Thing page) or “Add Thing as Equipment” (from the Model page) features to add items and links;
  • Show how cards automatically start appearing on the home page (WIP) based on the semantic model;
  • Install HABot and show how you can already make natural language queries from the home page;
  • Change some metadata (e.g. pattern, options, synonyms…)

4. Creating interaction Pages

  • Explain succintly the different types of pages, including sitemaps;
  • Build a simple sitemap and show the result in Basic UI;
  • Build a simple layout page, add a few widgets, make it visible on the sidebar, build an overview page;
  • Explain what an item’s “default standalone widget” and “default list widget” metadata is for and what’s the impact of changing it;

5. Your first automation Rules

  • Explain what rules are and what you can do with them (not only automation but also for instance scenes);
  • Create 2 simple rules:
    • When luminosity measured with the plant sensor (from 2.) goes above a certain value, or it’s 8 AM, then open the rollershutter, but only on weekdays - show that rule in the Schedule screen;
    • When the power measured by the Z-Wave wall plug goes above/below a certain value, make the Hue bulb flash (involves a little bit of scripting).
  • What to do when things go wrong: logging, debugging, manually updating and commanding Items (REST API or Karaf Console), manually running Rules from the UI (though I’ve noticed running Rules like that don’t get the context so often don’t work)

6. Connect to openHAB Cloud

  • Describe the benefits, install the openHAB Cloud add-on, create an account on myopenhab.org, connect the instance to it.
  • If we move this to 5. than we can use push notifications in the simple rules examples.

7. Persistence

  • When, why and how to configure a persistence service (I know OH 3 now comes with RRD4J preinstalled and configured, so maybe this is just to show how to modify that preconfiguration?)

8. Conclusion

  • Present what we’ve achieved and how to go further.
9 Likes

NOTE: I hope to get OH 3 installed and start playing with it this weekend so some of my comments and edits may be completely off base.

I completely agree.

I also agree with this. However, that content was added in an effort to address some users who came across openHAB and expected a simple point and click experience. I don’t want to lose it entirely but agree it doesn’t have to be on the first page. It is perfectly appropriate for the Getting Started section though, but we can make the verbiage a little more formal and a little less negative.

Should the Getting Started Guide show both text and UI configuration throughout or pick one and stick to it? Obviously choosing both means twice the amount of work to document but it would make the tutorial much more complete.

Given the new import in building the Item model and getting it right, maybe that’s an argument for only presenting the UI approach in Getting started with a link everything one needs to do text based configs. In other words, treat text based configs as an advanced topic.

Do you think it makes sense to present the Items and Item model first? Build the model and Item and then add and link the Things? It’s kind of a catch-22 I think because one doesn’t always know what type is correct for an Item unitl the Thing is created. Similarly, one may not know what information and actuators are available at all until the Thing is created. But I can see a lot of benefit by building the Item model first, at least a first draft of it, and then worrying about the Things. It forces the users to actually think about and plan their home automation. It emphasizes how Items are independent from the devices they link to. And it emphasizes the importance of the Items over all, something that seems to get lost for some users who sometimes seem to get stuck at Things (this may be caused more by the much maligned Simple Mode though).

I wonder if it makes more sense to use examples that do not require the user to have specific hardware. For the simple example maybe using Network instead of Hue. Assuming Network binding’s autodiscovery for that binding doesn’t break again. For the intermediate binding, maybe using the OpenWeatherMap binding would be an OK choice for intermediate. It loses the whole pairing mode detail but it still includes manually creating the bridge Thing first and then discovering the Things in the Inbox.

The advantage of using these is the new users can follow along no matter what hardware they happen to have. But it does miss the nuance with Zwave and Zigbee where you have to go into pairing mode.

I really like having MQTT as the advanced example though. I’ll comment and propose edits on that thread separately on that page.

Of course, if we do that the example rules might not make as much sense. But I think we can come up with reasonable alternatives that show the same thing.

This is a great intro and outline for the Getting Started tutorial. Once I play a bit more with the UIs and such I’ll start adding content to the OP.

2 Likes

I couldn’t agree more strongly with this.

Personally, when starting out, I found the docs super heavy on prose, and fairly light on real world examples.

Switching to a more neutral tone will hopefully help reduce the sometimes off-putting word count!

1 Like

Yes but I still think it’s too long, a little weird for an introduction to a documentation base, and should only be what new users should be reading, not everybody including people who go back to the docs for reference or to look up something. We can put proeminently a “New to openHAB? Read the Getting Started Guide!” (with a link) and then follow with a global table of contents of sorts which will be more useful in the index page.

I state later that the tutorial focuses on the UI only, for simplicity’s sake - it’s the easiest approach for new users I think. Maybe it’s a little dishonest to introduce the two approaches and immediately say “we’re transparent in telling you there’s two ways to do things, but we’re choosing the UI approach here, if you decide to go back to a file-based approach later and want to migrate what you’ve done in the UI you’re going to have a bad time, just so you know”

My approach was, let’s prepare the physical side first, as it’s perhaps the easiest concept to grasp, but keep them just sitting there unlinked while we prepare the functional model". We can probably switch the order of chapters later.

I wondered that too, but ultimately I think real hardware from the smart home world makes more sense. openHAB remains a smart home solution first, it just happens to do network monitoring and tell the weather too, but that shouldn’t be the primary use case. I saw in a poll here somewhere that the vast majority of users use openHAB to control lights, and Hue is probably one the most popular platforms. If readers use another platform I’m sure they can adapt the examples to their situation. Also, I wanted to tell the complete story and reuse the same example Things later in the tutorial when giving interesting real-world examples of how they can be used together in rules (‘flash lights’, ‘open the shutters’).

It does provide a bit of dissonance to emphasize they had better choose wisely to start, but we’re only going to show how to get started one way.

Maybe rather than the long discussion about pros and cons between the two and emphasizing how important it is to make the right decision we just acknowledge the fact that text based config is possible, provide a link to a page that discusses text based config overall which serves as the introduction to the reference material for text based configs and leave it at that. Sure, it shows an implicit bias towards UI based configuration but that bias is there in this tutorial anyway.

For those who are particularly motivated to do text based configs we’ve not hidden that capability from them. We are just not going to get them started with it. :wink:

Ultimately I think it comes down to whether these do a good job of getting all users started. If we have a new user that has KNX and RF433 devices, do these tutorials help them get started?

Conceptually I agree that showing how OH works with real hardware is more appropriate. But I also don’t want to discount the power of providing hands on experience. When I’ve taught classes in the past, the material has always been far more effective if the users are able to actually follow along and perform the steps themselves. It’s even more effective if you can provide some guided exploration.

Users who don’t have Hue or Zwave will not get any hands on experience at all by following the tutorial until they get to MQTT, and perhaps not even then if they don’t think they want to have their first hands on experiences with OH bindings being the advanced one. And MQTT is so unique it’s hard to translate that experience to other bindings. And this lack will continue to flow through the rest of the tutorial because, given the rules examples, if they don’t have the devices they won’t be able to create the same rules and see that they work.

So is it better to provide examples that only a subset of OH users would be able to actually follow along with but are more typical of the sorts of automation they will do later, or is it better to provide examples that all users can click along with on their own system to gain the experience, but doesn’t necessarily map to real world use cases?

Maybe provide an example for at least one binding (and subsequent Items and rules) that doesn’t require any external dependencies so everyone, no matter what hardware they have, will get the physical experience of installing a binding and accepting Things from the Inbox would be sufficient. And also include at least one Rule that operates on the Items for that Thing so they can see their rule actually work.

First, a word on the order of the sections in the docs. It assumes users read them in order, that is, first the concepts, then the installation guide, and when they reach the tutorial section. I’m not so sure about this so I’d suggest to call the tutorial Getting Started or similar and move it to the top. Then the tutorial intro’s first paragraphs could be a quick overview (or recap) of the concepts and the installation options, with links to the other sections (Concepts and Installation Guide) to go deeper.

If a document is short, I think more people are likely to read in order, beginning to end. The longer or more complex a document gets (and that’s just unavoidable depending upon the topic), the less likely people are do this. In an age of hyperlinked documents, I think many people will jump around to what interests them after a certain introductory point.

Also, I’m not the biggest fan of the content on the entry page at https://openhab.org/docs/ , especially the “motivational speak” right at the start (“keep your focus”, “result of hard work” etc.), IMHO that page should go back to describing with a neutral tone how the docs themselves are organized, i.e. what the sections are and what you can find in them. That content could however be a good fit for the introduction of this tutorial/getting started section. The only section I would leave there is the “openHAB community” and maybe the last one about architecture.

I think there may be a good compromise between the two point of views. I too could do without the What You Need to Know Before You Start section. My main objection is that it really doesn’t tell much. From my point of view, the summary is “OpenHAB will take some work to get up and running.” Okay, that’s fair enough, but what does it really mean in terms of time and effort? The short answer is that it’s going to vary tremendously based upon the knowledge and experience of the individual. So, what I’d rather see is a link to another page. Perhaps the link could be titled “Is openHAB Right for Me?” On that page one could go into the motivational discussion, discuss openHAB vs openHABian, and discuss hardware choices.

You need to sit in front of a computer with access to the files to make changes.

Under file-based CONs, I see the above. Isn’t it redundant though. Something similar enough is true of a GUI-based CON.

Maybe it wasn’t clear enough, what I meant is that you don’t need a full development environment or files shares or shell access to the server; in this scenario you can make small adjustments even on your phone - it was in contrast to “All objects can be altered from anywhere the UI can be reached (including on mobile)”

That’s a good compromise.

I think this summirizes the problem. I guess I’m still sitting on the fence on this - providing a representative example of the smart home world, even if it’s only for illustrative purposes vs. a example that can be reproduced while following the tutorial but isn’t really what openHAB is about.

Maybe we ,split the difference and provide two simple and intermediate tutorials, one that is more typical (i.e. what is already there) and two that no matter what the users can follow along with.

Yes, or maybe adapt the language so that we don’t provide detailed instructions for specific hardware, but give some generic instructions (like it’s done in https://support.apple.com/en-us/HT204893#add for instance), i.e. “look for the binding corresponding to your appliance or service and install it, check the binding docs to check if you have to add a bridge manually before things are auto-detected” and so on? The screenshots may give an example of a specific binding as an illustration but the text wouldn’t assume you’re using that one specifically.
For more advanced tutorials, then stating the prerequisites from the start would make these assumptions clear, and the reader would normally (hopefully!) be familiar with the basic tasks anyway so they could adapt if they’re not in that particular scenario.

1 Like

Hi,

I discovered OH2 a few month ago, and here is my feedback on documentation. I consider myself as “power user”, or even “specialist” as I’m an embedded software engineer, and I must admit that I had a lot of troubles to implement some quite simple scenarios (I keep a file-based approach).

  • The given examples do not work “out of the box”, we have to interpret a lot of things, and more have to look on forum (very rich BTW) for a complete working example
  • A lot of bindings does not even include any code extract to start on a first basic scenario
  • Simple things like “I collect the electric meter values through MQTT and I want to compute at midnight the daily consumption” took me like an hour to success : simple math operations are not clearly described (need of local variable etc.)
  • English only. Not a problem for me, but I can help to translate in French :slight_smile:
  • I would also consider to create a tutorial (or a full set of out-of-the-box scenarios maybe ?) which would not need any IoT device, so that anyone can test immediately. Only with software we can image a lot of scenarios based on time, sun position, weather forecast, network devices, MQTT broker, persistance etc.

Anyway thank you very much for this effort to rewrite documentation, this is a huge work (and I can help !)

1 Like

I get what you mean, and that most of the struggle seems to be from “getting the basics in order” to building intermediate-level stuff; but what I wonder though is where we end the “Getting Started” tutorial and directing users who want more to the community to get help and often ready-made examples.

What I’m trying to say in my last few replies is, I’m not sure what the profile of the average reader of this tutorial will be, but I fear if we restrict our examples to “monitoring your local network” and other generic things like the weather, we’re kind of missing the point. There are better tools than openHAB to do these things. If we’re targeting people already educated in what home automation is and how it can help, then sure, they will understand the generic examples; but if they’re not, maybe it’s better to provide examples involving some real hardware.

What I usually reply to neophytes asking about home automation, and what it could do for them, I usually try to focus on easy-to-explain, easy-to-understand examples that might be relatable to them: like the “make the Hue lights and the connected plug you got last Christmas work together to notify you when you have to pick up the laundry from the washing machine” (and without some big-tech cloud service) scenario I offered to include as the last part of the tutorial. It’s perhaps not the quintessential example but I found it had the best “uh, okay, interesting” effect - though I also get “you could simply use a timer” sometimes :laughing:.

But I somewhat I agree that involving more things with no dependency like “when the sun rises” could have the same effect.

One of the weather monitoring systems i used shipped with a driver for a dummy driver to simulate data so that people could play with the UI part without having to have a connected weather station.
So one possibility might be to create a simulate binding that pretends to be a light (maybe with some simple ui somewhere that has light/switch status) but essentially behaves like the Hue binding so you could use the hue binding if you have it or the simulator if you don’t.
Downside is that somehow we would need to create a simulator binding that can be used.

On the temporary testing/sandbox instance I set up, I added the Nibe Heat Pump binding, and found out you have some simulators - they’re easy to add, and provide changing temperatures and simulated failures. That could be an option.

(And, it makes decent visualizations of persisted data:)
https://ohui.azurewebsites.net/#!/page/hourly_combined_chart
https://ohui.azurewebsites.net/#!/page/pump_gas_heatmap
https://ohui.azurewebsites.net/#!/page/pumptemp
https://ohui.azurewebsites.net/#!/page/calendar_brine_temp

Hi @ysc,

You wrote:

I’m not sure what the profile of the average reader of this tutorial will be, but I fear if we restrict our examples to “monitoring your local network” and other generic things like the weather, we’re kind of missing the point. There are better tools than openHAB to do these things. If we’re targeting people already educated in what home automation is and how it can help, then sure, they will understand the generic examples; but if they’re not, maybe it’s better to provide examples involving some real hardware.

Just my two cents, with any technical documentation, I think it’s critical to identify who the target audience is. Perhaps the safest assumption to make is that reader of the tutorials has a vague understanding of home automation and what they want to do, but no prior knowledge of openHAB. (That’s probably not an accurate representation of the user base, but it probably is the lowest common denominator.) In any case, it might be a good idea to preface the tutorial with who it’s intended for and what skills the reader is assumed to have. Also, I wonder if parsing the forum for the last year’s posts would aid in understanding pain points of users.

Regards,
Burzin

I don’t think anyone is arguing any more that we restrict exclusively to those scenarios. I think what is being suggested is that we include some. So don’t get rid of Hue and Zwave but add in something like Network and OpenWeatherMap in addition.

Based on what I’ve seen, those who use the Getting Started tutorial will be those who are completely new to OH. Some are new to home automation completely, others have a specific problem they are looking to solve, and still others are looking to migrate from some other home automation system. We need to support all three types in the Getting Started tutorial. That will mean that those who have a bit more background in home automation might find a lot of stuff that they already know but they should also intuitively know that a Getting Started tutorial needs to support those other two types of users as well.

I think this is the crux of the problem. Let’s take the true new user, doesn’t know much about home automation at all. If we only present Hue, Zwave, and MQTT and that user doesn’t have any of those technologies, we are forcing this user, who doesn’t know anything about home automation yet:

  • figure out which of those three example is most similar to the hardware they do have so they know which one to try and translate to a different binding
  • they have to translate the steps and screen shots to actually use those tutorials because what they see won’t match what’s in the tutorial (this is typically considered an intermediate level tutorial, not a beginners)
  • or if they decide not to try and follow along they gain absolutely zero physical experience operating openHAB by the time they are done with the tutorial; they really haven’t got started.

Also, given the different styles of learning (some learn best by doing) and the psychological importance of achieving small successes along the way to reinforce the content and give the user that feeling of “I can do this!”, I still think it’s important that we present, at least in part, something that the users can actually do regardless of what hardware they may have, even if the use cases are not typical home automation tasks. Otherwise, for many users the tutorial becomes a wall of text and screen shots without meaning; they don’t learn well by reading.

This is a case where there are two competing desires:

  1. make the examples representative of what home automation is
  2. make the examples something anyone can follow along with regardless of hardware.

Both are important but I think we are doing a disservice to truly new users if we completely ignore 2.

I at a minimum at least skim almost every new post to the forum. It’s kind of hard to pinpoint single pain points as most of those who do post for help simply ask for "Where is a setp-by-step tutorial to use <insert specific technology(ies)> to <insert some specific behavior> in <insert some specific manner>. As I usually respond, they won’t find that specific tutorial because everyone’s “insert” in that sentence is different. We’d have to write over 300! (300 factorial) tutorials to cover all possible combinations.

So, since we can’t do that, we need to make the Getting Started tutorial rich and complete enough to teach the stuff that is going to be universal to all use cases:

  • installing and configuring a binding
  • discovering Things
  • manually creating Thing
  • creating Items and linking them with Thing’s Channels
  • creating rules
  • creating the UI (sitemap)
  • setting up and using persistence

Over all, what is presented covers all of these and does so pretty well. But I worry that the great leap (there always seems to be a great leap) will be taking the examples (or is it one unified end-to-end example?) presented in Getting Started and applying it to their unique use case. If we completely exclude using as examples any bindings that are universal (i.e. don’t require any specific hardware or accounts) that great leap is even larger.

For what it’s worth, I agree with you.

But I worry that the great leap (there always seems to be a great leap) will be taking the examples (or is it one unified end-to-end

Regarding the point above, I think a single unified grand end to end example may be counter productive as folks may look at it and say to them selves that’s for “x” and I use “y”. The purpose of the tutorial should be to illustrate and teach concepts that can be applied to the users’ problems and available technologies, so being broad, rather than narrow is probably best.

The counter argument is without an end-to-end example being worked on in Getting Started we lose the ability to demonstrate how all the piece parts of openHAB work together. If each page stands on it’s own than we haven’t demonstrated how it all works together. We would be missing:

  • how Things interact with Items
  • how Items interact with Rules
  • how Items are represented on the UIs
  • how Items interact with Persistence
  • how the Item semantic model helps with creating UIs
  • an end-to-end example going from hardware to rules and UI which is ultimately what the reader of this tutorial is after, how to get started stringing all this stuff together.
                                                     /-> User Interfaces
hardware -> binding -> Things  -> Channels -> Items |-> Rules
                                                     \-> Persistence
                                                      \-> Model

Most of the above becomes implicit and obvious when, for example, you create or discover Thing(s), then use those Thing(s) when linking to Item(s) on the next page that talks about Items, then use those same Items in the discussion about the other concepts. That makes the connection apparent and the repetition reinforces the earlier lessons.

If we go too broad and don’t have that repetition we run the real risk that the Getting Started Tutorial becomes the Getting Started Reference Guide. A reference is great and we need that too but it’s only really useful when you already know enough to know what to look up and where. It’s not so great at teaching the user how it all works together or how to get started. If it did, our current docs for 2.5 would be fantastic.

1 Like

Speaking from the experience of someone who started with OH later in the day than a lot of you (i.e. OH 2.x) even knowing that text based config was possible I still elected for UI based config initially.

I’m a Software Engineer and knew that I’d probably prefer the control of the text based config at some point but it was still, IMHO, the wise decision to go UI based 1st as: 1) it got me up and running quicker 2) it meant I could quickly evaluate OH to see whether it suited me, without the need to learn a lot of text config 3) I was able to learn how OH “worked under the hood” 1st, which proved invaluable and then made the transition to text based config easier as by then I actually understood how Things, Items, Channels, etc all related to each other.

Now I do everything by text based config including setting up my own home made IOT devices, but I wouldn’t have been able to do it as easy without first playing with the UI configs.

Personally I didn’t find migrating from UI to text based that difficult, because by that time I understood OH, which I think is the critical thing.

Going head 1st into text based config I think is harder than the migration from UI to text based.

So in my opinion a bias towards the UI based config for new users isn’t a bad thing, especially if you’re explaining that there is the option to go text based if they choose.

Totally agree, it was initially confusing how everything worked together. Even a simple end to end example would have been useful initially, something like a simple Pingable Network Device which recognised when your phone joined the network and then sent a notification to your phone via the OH app to say “Welcome Home” would do as a start.

Then you could possibly have a more complex example where one of more Things interacted together to alter the state of another Thing.

1 Like