v4 Documentation Preview

# 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:

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 .items files 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.
Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)