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!
This tutorial has transitioned to the official docs. Please see Getting Started - Introduction | openHAB.
Welcome to openHAB 3. We hope that your journey with openHAB is a rewarding one. If you encounter problems or simply cannot figure something out on your own, please do not hesitate to post a question on the forum. There are many fellow openHAB users ready and willing to help as much as possible. Most requests for help have a response within a couple of hours.
First, a word on the order of the sections in the docs. This tutorial assumes users have read the concepts and installation guide already. It assumes at least a basic knowledge of the concepts of openHAB and that the user has already installed and confirmed openHAB is working.
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 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.
- Items can be auto-created from Things (with a chance to edit)
- The internal database is somewhat faster especially on resource-limited devices (RPi) than the file parsing.
- A backup of the internal database is created on every change.
- 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 import .items files definitions and sitemaps to 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. Review the reference documentation for details on the text based approach.
If you run into problems or want to share something you’ve created through the UI, click on the “Code” tab that is at the top of almost every configuration page to reveal a YAML formatted version of that entity (e.g. a Rule). Post that YAML to the forum using code fences instead of screen shots.
This tutorial presents a series of steps that build upon one another so it is important to at least review the tutorial in order. There may be concepts or steps that occur earlier that are required to complete the parts of the tutorial presented later.
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
- Uses 3 examples of increasing complexity for the discovery and manual creation of Things:
- 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, 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 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
- Intro Explain the different types of pages, including sitemaps;
- [TBD] Build a simple sitemap and show the result in Basic UI;
- Pages Build a simple layout page, add a few widgets, make it visible on the sidebar, build an overview page;
- Pages Explain what an item’s “default standalone widget” and “default list widget” metadata is for and what’s the impact of changing it;
- Layout Building layout pages, chart pages, tabbed pages, etc.
5. Your first automation Rules
- [TBD] Explains 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
- [TBD] 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.
[RLK Note: Maybe this should be moved up before Pages given all those Analyze buttons everywhere]
- [TBD] 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?)
- [TBD] Present what we’ve achieved and how to go further.