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 vs UI-driven configuration
An important decision has to be taken early on because it’s not trivial to change later on. The choice is between configuring with traditional text files, or to use the new UI.
To help you choose between the two approaches the following is a summary of the pros & cons for each:
- 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 services (e.g. Dropbox, Nextcloud) to the openHAB machine.
- Easier to share configurations between multiple openHAB instances.
- 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 ).
- You need to sit in front of a computer with access to the files to make changes.
- 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.
- 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.
Some intro on what we’ll achieve on each step.
(the following will become links to other pages)
1. First Steps
- 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 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 example rules:
- GUI only: when luminosity measured with the plant sensor (from 2.) goes above a certain value, or it’s 8 AM, then open the roller shutter, but only on weekdays - show that rule in the Schedule screen
- with scripting: when the power measured by the Z-Wave wall plug on your washing machine 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.
- 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 pre-configuration?)
- Present what we’ve achieved and how to go further.