# 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 frontend, the rule engine and other parts and connected systems.
openHAB is a system installed and executed by you, running independently from any online services or proprietary technologies. You as the end-user have the full control over every aspect of your smart home.
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
- Sitemaps - User-defined frontend interfaces to arrange Groups, Items and more
- Transformations - Helper functions to transform your data
- Persistence - Services to store data over time
- Rules - Automation logic, the "smart" in your Smart Home!
- JSR223 Scripting - Define rules and other runtime objects using Javascript, Jython or Groovy
The individual articles hold all details needed to understand the concepts behind these building bricks for your Smart Home. For more details on the base concept behind openHAB, please visit the Concepts Overview page.
# Versatility
openHAB provides different user interfaces to modify settings, manage your things and items and to build rules and sitemaps. HABmin provides a set of features to now overlap with Paper UI (which came later). Every interface still has its own strong points. The following table shows what the user interfaces can be used for. For a recommendation to new users which one(s) to use, see the section below. In the table, "R" means recommended.
| Task | Textual Configuration | Paper UI | HABmin | Homebuilder | Console | Recommendation |
|---|---|---|---|---|---|---|
| Auto-Discover Things and Items | ❌ | ✔️R | ✔️R | ❌ | ✔️ | Paper UI or HABmin Do not autocreate Items |
| Define and manage Things | (✔️) not for all bindings | ✔️R | ✔️R | ❌ | ✔️ | Paper UI or HABmin |
| Define and manage Items | ✔️R | ✔️ | ❌ | ✔️ | ✔️ | items/*.items files |
| Define Groups | ✔️R | ✔️ | ❌ | ✔️ | ✔️ | items/*.items files |
| Define Sitemaps | ✔️R | ❌ | ❌ | ✔️R | ❌ | Homebuilder or sitemaps/*.sitemap files |
| Define Transformations | ✔️ | ❌ | ❌ | ❌ | ❌ | transform/*.map files |
| Define Persistence | ✔️ | ❌ | ❌ | ❌ | ❌ | persistence/*.persist files |
| Define Rules | ✔️R | (❌) only for the experimental rules engine | (❌) not functional | ❌ | ❌ | rules/*.rules files |
| Manage Z-Wave Devices | ❌ | ✔️ | ✔️R | ❌ | ❌ | HABmin |
| Modify openHAB Settings/Services | ✔️ | ✔️R | ✔️ | ❌ | ✔️ | Paper UI |
| Install Add-ons | ✔️R mandatory for OH1 bindings to require config | ✔️R | ✔️ | ❌ | ✔️ | services/addons.cfg or Paper UI services/*.cfg for OH1 bindings |
# Textual vs. Graphical Configuration
In openHAB 1.x, smart home configuration was done via configuration files only. openHAB 2 added the administrative web interface "Paper UI". It allows for configuration of the base system and setup of openHAB 2 add-ons. Please be aware that not every addon/binding of openHAB version 1.x has been updated to version 2 and thus to work with Paper UI. You can still run these but you need to use file configuration for them.
Things and Items can either be defined and managed in configuration files or handled by Paper UI in a system-side database.
Both of the above described methods could be used parallel, e.g. a Thing can be discovered and created by Paper UI and the Items that link to that very same Thing (that Thing's Channels, actually) can be manually defined in a .items configuration file.
WARNING
While it's technically possible to use both methods in parallel, we recommend to choose only one of them to avoid confusion and a loss of overview of your openHAB environment. It would work to mix but you may easily forget about what is your "source of truth" when you reconfigure Things or Items at a later stage.
Configuration done in files will be used (and Things/Items become visible and even changeable in Paper UI) if no Thing/Item of the same name was already created in PaperUI, but you can NOT create a Thing or Item using files and then use Paper UI to permanently change it.
Configuration done in PaperUI will be used and permanently stored in the internal database if no Thing/Item of the same name already exists in files, but those additions or changes will not be copied back into any .things file.
openHAB settings as defined in services/addons.cfg and services/runtime.cfg will override any settings made in PaperUI's Configuration/System pane.
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
All interface options are supposed to work, still some of the more advanced settings might work better in one or the other setup. You have the full freedom of choice. On the other hand, this can be very confusing at times, particularly for new users. To help starters in narrowing down choices, here is some guidance that might also help to avoid some future pitfalls:
- Use Paper UI to setup and maintain the openHAB base system. Use it to define which addons and bindings you want to install and to assign basic, static configuration (such as the device name of a ZWave stick or the IP address of a KNX gateway).
- Create items and groups in
.itemsfiles. You can also use Homebuilder to create your initial set of .items and .sitemap files. It is a separate GUI tool to assist you with the creation of these components to represent your home, however it does not provide GUI support for all the functionality that is available for use in .items, so it is not recommended to keep using Homebuilder to maintain these files. - Use Paper UI to manage configuration of each and every openHAB 2 add-on and binding.
- Use file configuration or Paper UI to manage configuration of openHAB 1 add-ons and bindings.
- Use Paper UI or habmin to manage ZWave things, but use configuration files to manage ZWave items.
There is a rationale to this: to use a GUI is comfortable for one-time actions, but you get any repetitive task easier and faster done using a text editor (e.g. search-and-replace names and parameters). Things can be autodiscovered so you don't have to enter all of them manually. Once initially configured, their configuration is not changing much over time. On the other hand, you will keep changing items rather often. If you are new to openHAB, you will e.g. keep changing all of your item names as you keep learning what is a naming scheme you like best to work with in your rules. And once you are a pro, you will want to keep using files anyway. You can configure items via Paper UI, too, and you can use HABmin as well for both but remember once you use files, this will override any UI-made changes on next openHAB startup. - Use the editor of your choice to edit sitemaps. Start with the demo sitemap as a template.
- Use VS code extensions to edit rules, items and sitemap files. You can also use any text editor, but VS code extensions will help you by highlighting and cross-checking the file syntax. Either way, be aware that any 'save' results in openHAB reloading the rules file. This can take more than a minute on a slow box such as a Raspberry Pi, so better to not edit rules files in place.