This page is part of archived documentation for openHAB 4.3. Go to the current stable version
# Configuration of your Smart Home
openHAB is the center of your home automation. Properties and capabilities of all your devices are available through openHAB to the user interface.
openHAB is a system installed and driven by you, running independently of any online services or proprietary technologies. You as the end-user have full control over every aspect of your smart home, and it will keep working even when your Internet link goes down.
Every device connected to openHAB is functionally and logically different. In order to represent all of these, openHAB defines the following base components:
- Add-ons - The numerous add-ons to communicate with your devices
- Things - Your devices represented in openHAB
- Items - properties and capabilities of your Things
- Groups - collections or categories containing Items
- Transformations - Helper functions to transform your data
- Persistence - Services to store data over time
- Rules - Automation logic, the "smart" in your Smart Home!
- Blockly Rules - Visually define the automation logic of your Smart Home
- JSR223 Scripting - Define rules and other runtime objects using JavaScript (opens new window), Jython (opens new window) or Groovy (opens new window)
The individual articles have all the details needed to understand the concepts behind these building blocks for your Smart Home. For more details on the basic concepts behind openHAB, please visit the Concepts Overview page.
TIP
This section does not cover building user interfaces; this subject has its own section: User Interfaces
# Versatility
openHAB provides a single graphical user interface to modify settings, to manage your components and rules, and to provide a UI for users.
While there are no full-scale starter and migration tutorials available yet, see the recording of the recent 2020 openHAB virtual meetup (opens new window) for a tour of the new Main UI (starting at 26:26).
Important changes for openHAB 2 users
PaperUI and HABmin are no longer supported, they are replaced by the new Main UI.
It also provides flexible charting now so you won't require Grafana or a similar external tool any more.
v1 bindings are no longer available, see this list (opens new window) what has been migrated to OH3.
The expire binding's functionality is now part of the core (item configuration stays the same).
File-based configuration is still available, but we recommend that everyone start over with a fresh setup built using the new Main UI.
Note there is an option in Main UI to bulk create Items where you can copy'n'paste the contents of your .items files.
| Configuration Task | via text files | in Main UI | openHAB console | Recommendation |
|---|---|---|---|---|
| Auto-Discover Things and Items | ❌ | ✔️ | ✔️ | Main UI Do not autocreate Items |
| Define and manage Things | ✔️ | ✔️ | ✔️ | Main UI |
| Define and manage Groups and Items | ✔️ | ✔️ | (✔️) | for starters: Use the semantic model in UI advanced users: import items in UI to use the semantic model only stick with *.items files if you know how to handle tagging and groups for the model |
| Define GUI | sitemaps only | ✔️ includes YAML view | ✔️ | Main UI sitemaps/*.sitemap files |
| Define Transformations | ✔️ | ❌ | ❌ | transform/*.map*.js files |
| Define Persistence | ✔️ | ❌ | ❌ | persistence/*.persist files |
| Define Rules | ✔️ | ✔️ | ❌ | for starters: Main UI and Blockly (graphically create JS code) for advanced users: rules/*.rules files for rules DSL and JSR223 |
| Manage Z-Wave Devices | ❌ | ✔️ | ❌ | Main UI |
| Modify openHAB Settings/Services | ✔️ | ✔️ | ✔️ | Main UI |
| Install Add-ons | ✔️ | ✔️ | ✔️ | Main UI |
# Textual vs. Graphical Configuration
TIP
Don't confuse admin UI and user UI. Happens to many people as you can access both from the common UI entry point running on port 8080. User UI is what can be provided to users of your home so they can interactively command the house. It's the equivalent of sitemaps in older OH versions. This docs section is all about admin UI to create Things and Items, it does not cover building user interfaces. See User Interfaces for that.
openHAB 1 was text only, openHAB 2 added the general administrative web interface "Paper UI", and openHAB 3 replaced that with "Main UI".
Things and Items can still be defined either in configuration files or via the (admin) GUI.
We highly recommend adding them to the system database via Main UI, though.
Note there is an option in Main UI to bulk create Items by copy and pasting the contents of existing .items files.
Bulk delete is there, too.
Be sure to try out Semantic Modeling in Main UI.
Both methods can still be used in parallel, e.g. a Thing can be discovered and created in Main UI and the Items that link to that very same Thing (or that Thing's Channels, actually) can be manually defined in a .items configuration file.
Technically speaking it's even possible to use text and UI config in parallel to maintain components of one type, however this is not recommended.
WARNING
Do not mix file and system database definitions (when created via UI) for Items (or for Things). You can easily forget which is your "source of truth" when you add or reconfigure Things or Items at a later stage.
Also be aware that applying the semantic model means to add configuration (tags, group membership) to items. You must not create an item using files and then make use of it in the model using the UI as this means to mix text and system database configuration for that item, too.
You can configure the model through text only, too. No documentation exists for that however so it is not recommended and you have to figure out yourself. Please contribute to the docs here if you managed to.
Things/Items configured in files will become visible in Main UI if no Thing/Item of the same name is already present in the system database, but a lock will symbolize that you can NOT change them in the GUI. You can only change them by editing the source files.
Note: Things/Items you create via Main UI will be stored in the system database, but those additions or changes will not be written back into any .things / .items file.
Textual configuration is a one-way street.
Likewise, openHAB settings defined in services/addons.cfg and services/runtime.cfg will take precedence over any settings made via Main UI.
Important
All text files must be created with UTF-8 encoding. When using Visual Studio Code, this encoding is already set by default.
# Recommendations for New Users
Here are some hints to avoid some common pitfalls when starting out.
- Start by modelling your house using a Semantic Model in Main UI. Use it to create groups for rooms and apply proper semantic tags right away. This will ultimately save a lot of setup work, as it will allow for group functions such as "switch off lights in kitchen" or ground floor or house and also enable voice assistants to properly execute your instructions. Be careful to apply a consistent naming scheme right in the beginning.
- Use Main UI to manage Things. Remember that once initially configured, their configuration will not change much over time.
- Run autodiscovery for Things wherever offered so that you don't have to enter all of them manually
- Also use Main UI to manage Items.
You can use the import function to import
.itemsfiles or snippets taken from other sources like the openHAB community forum. - Use VS code extensions to edit rules, items and sitemap files. You can also use any text editor or cloud based tool, but VS code extensions will work locally and help you by highlighting and cross-checking the file syntax.