openhab-docs/configuration/index.md

layout	title
documentation	Configuration

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 the 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
• 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 have all the 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 3 provides a single graphical user interface to modify settings, to manage your components, rules and GUI for users.

While there's no full scale starter and migration tutorials available yet, see the recording of the recent 2020 openHAB virtual meetup for a tour of the new Main UI (starting at 26:26).

::: tip 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. The expire binding's functionality is now part of the core (item configuration stays the same).
File based configuration is still available, then again we recommend anyone to start over with a fresh setup using the new Main UI only.
Note there is an option in Main UI to bulk create Things and Items where you can copy'n'paste the contents of your .things/.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	✔️	✔️	(✔️)	items/*.items files
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	✔️	✔️	❌	Main UI for starters: 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

In openHAB 1.x, smart home configuration was done via configuration files only, openHAB 2 added the general administrative web interface "Paper UI" andopenHAB 3 now streamlines input capabilities. Things and Items can still be defined either in configuration files or via GUI. We highly recommend to add them to the system database via Main UI, though. _Note there is an option in Main UI to bulk create Things and Items by copy'n'pasting the contents of existing .things/.items files. Bulk delete is there, too. Watch out for the Semantic Model 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

::: warning Do not mix files and UI for Items (or for Things) to avoid confusion and a loss of overview of your openHAB setup. It would work to mix but you will easily forget about what is your "source of truth" when you add or reconfigure Things or Items at a later stage. :::

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. You cannot change them other than 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 road. Likewise, openHAB settings defined in services/addons.cfg and services/runtime.cfg will take precedence over any settings made via Main UI.

::: warning 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's some hints to avoid some pitfalls in the first place.

• Start by modelling your house along the Semantic Model in Main UI. Use it to create groups for rooms and apply proper semantic tags right away. This will ultimately ease a lot of setup work in the long run as it'll allow for group functions such as "switch off lights in _kitchen" or ground floor or house" and e.g. enables voice assistants to properly execute your instructions. Watch out to apply a consistent naming scheme right in the beginning.
• use Main UI to manage Things - remember once initially configured, their configuration is not changing much over time.
• run autodiscovery for Things whereever offered so 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 e.g. the 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.