You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: configuration/index.md
+81-35Lines changed: 81 additions & 35 deletions
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,6 @@ layout: documentation
3
3
title: Configuration
4
4
---
5
5
6
-
{% include base.html %}
7
-
8
6
# Configuration of your Smart Home
9
7
10
8
openHAB is the center of your home automation.
@@ -14,7 +12,7 @@ openHAB is a system installed and executed by you, **running independently** fro
14
12
You as the end-user have the **full control** over every aspect of your smart home.
15
13
16
14
Every device connected to openHAB is functionally and logically different.
17
-
In order to represent all of these, openHAB defines the following few base components:
15
+
In order to represent all of these, openHAB defines the following base components:
18
16
19
17
-[Add-ons](addons.html) - The numerous Add-ons to communicate with your devices
20
18
-[Things](things.html) - Your devices represented in openHAB
@@ -24,17 +22,18 @@ In order to represent all of these, openHAB defines the following few base compo
24
22
-[Transformations](transform.html) - Helper functions to transform your data
25
23
-[Persistence](persistence.html) - Services to store data over time
26
24
-[Rules](rules-dsl.html) - Automation logic, the "smart" in your Smart Home!
27
-
-[JSR223 Scripting](jsr223.html) - Define rules and other runtime objects using [Javascript](http://openjdk.java.net/projects/nashorn/), [Jython](http://www.jython.org) or [Groovy](http://www.groovy-lang.org/).
25
+
-[JSR223 Scripting](jsr223.html) - Define rules and other runtime objects using [Javascript](http://openjdk.java.net/projects/nashorn/), [Jython](http://www.jython.org) or [Groovy](http://www.groovy-lang.org/)
28
26
29
27
The individual articles hold all details needed to understand the concepts behind these building bricks for your Smart Home.
30
-
For more details on the base concept behind openHAB, please visit the [Concepts Overview page]({{base}}/concepts/index.html).
28
+
For more details on the base concept behind openHAB, please visit the [Concepts Overview page](/docs/concepts/index.html).
31
29
32
30
## Versatility
33
31
34
32
openHAB provides different user interfaces to modify settings, manage your things and items, build rules and access the sitemap results.
35
-
Every interface has it's own strong points.
36
-
37
-
### Comparison
33
+
HABmin provides a set of features to now overlap with Paper UI (which came later).
34
+
Every interface still has its own strong points.
35
+
The following table shows what the user interfaces can be used for.
36
+
For a recommendation to new users which one(s) to use, see the section below. "*" means recommended.
38
37
39
38
<tableclass="centered highlight">
40
39
<thead>
@@ -43,99 +42,146 @@ Every interface has it's own strong points.
<td>Paper UI or HABmin<br/>Do not autocreate Items</td>
57
60
</tr>
58
61
<tr>
59
-
<td>Define Things</td>
60
-
<td>✔️</td>
61
-
<td>✔️</td>
62
-
<td>✔️</td>
62
+
<td>Define and manage Things</td>
63
+
<td>(✔️)<br/>not for all bindings</td>
64
+
<td>✔️*</td>
65
+
<td>✔️*</td>
66
+
<td>❌</td>
63
67
<td>✔️</td>
68
+
<td>Paper UI or HABmin</td>
64
69
</tr>
65
70
<tr>
66
-
<td>Define Items</td>
67
-
<td>✔️</td>
71
+
<td>Define and manage Items</td>
72
+
<td>✔️*</td>
68
73
<td>✔️</td>
74
+
<td>❌</td>
69
75
<td>✔️</td>
70
76
<td>✔️</td>
77
+
<td>items/*.items files</td>
71
78
</tr>
72
79
<tr>
73
80
<td>Define Groups</td>
81
+
<td>✔️*</td>
74
82
<td>✔️</td>
83
+
<td>❌</td>
75
84
<td>✔️</td>
76
85
<td>✔️</td>
77
-
<td>✔️</td>
86
+
<td>items/*.items files</td>
78
87
</tr>
79
88
<tr>
80
89
<td>Define Sitemaps</td>
81
-
<td>✔️</td>
90
+
<td>✔️*</td>
82
91
<td>❌</td>
83
92
<td>❌</td>
93
+
<td>✔️*</td>
84
94
<td>❌</td>
95
+
<td>Homebuilder or sitemaps/*.sitemap files</td>
85
96
</tr>
86
97
<tr>
87
98
<td>Define Transformations</td>
88
99
<td>✔️</td>
89
100
<td>❌</td>
90
101
<td>❌</td>
91
102
<td>❌</td>
103
+
<td>❌</td>
104
+
<td>transform/*.map files</td>
92
105
</tr>
93
106
<tr>
94
107
<td>Define Persistence</td>
95
108
<td>✔️</td>
96
109
<td>❌</td>
97
110
<td>❌</td>
98
111
<td>❌</td>
112
+
<td>❌</td>
113
+
<td>persistence/*.persist files</td>
99
114
</tr>
100
115
<tr>
101
116
<td>Define Rules</td>
102
-
<td>✔️</td>
103
-
<td>✔️<br />(Experimental)</td>
104
-
<td>✔️<br />(Graphical)</td>
117
+
<td>✔️*</td>
118
+
<td>(❌)<br/>only for the experimental rules engine</td>
119
+
<td>(❌)<br/>not functional</td>
105
120
<td>❌</td>
121
+
<td>❌</td>
122
+
<td>rules/*.rules files</td>
106
123
</tr>
107
124
<tr>
108
125
<td>Manage Z-Wave Devices</td>
109
-
<td>✔️<br />(Not Recommended)</td>
110
-
<td>✔️<br />(Limited)</td>
126
+
<td>❌</td>
111
127
<td>✔️</td>
128
+
<td>✔️*</td>
129
+
<td>❌</td>
112
130
<td>❌</td>
131
+
<td>HABmin</td>
113
132
</tr>
114
133
<tr>
115
-
<td>Modify openHAB Settings</td>
116
-
<td>✔️</td>
134
+
<td>Modify openHAB Settings/Services</td>
117
135
<td>✔️</td>
136
+
<td>✔️*</td>
118
137
<td>✔️</td>
138
+
<td>❌</td>
119
139
<td>✔️</td>
140
+
<td>Paper UI</td>
120
141
</tr>
121
142
<tr>
122
143
<td>Install Add-ons</td>
123
-
<td>✔️</td>
144
+
<td>✔️*<br/>mandatory for most OH1 bindings</td>
145
+
<td>✔️*</td>
124
146
<td>✔️</td>
125
147
<td>❌</td>
126
148
<td>✔️</td>
149
+
<td>services/addons.cfg or Paper UI<br/>services/*.cfg for OH1 bindings</td>
127
150
</tr>
128
151
</tbody>
129
152
</table>
130
153
131
-
{: #text-vs-ui}
132
154
### Textual vs. Graphical Configuration
133
155
134
-
With openHAB 1.x the smart home configuration was done via configuration files only.
135
-
One of the most visible additions to openHAB 2 is the administrative web interface Paper UI.
136
-
137
-
Things and Items can either be defined and managed in configuration files or handled by Paper UI in a [system-side database]({{base}}/administration/jsondb.html).
138
-
139
-
Both methods can be used **side-by-side or even mixed**, e.g. a Thing is discovered by Paper UI and linked Items are defined in a `.items` configuration file.
140
-
141
-
Configuration done in files will be synced to the database but configuration done in the database will not be written to files.
156
+
In openHAB 1.x, smart home configuration was done via configuration files only.
157
+
openHAB 2 added the administrative web interface "Paper UI".
158
+
It allows for configuration of the base system and setup of openHAB 2 add-ons.
159
+
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.
160
+
You can still run these but you need to use file configuration for them.
161
+
162
+
Things and Items can either be defined and managed in configuration files or handled by Paper UI in a [system-side database](/docs/administration/jsondb.html).
163
+
For Things and Items, both methods can be used **side-by-side**, 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.
164
+
Configuration done in files will be used (and they 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 redefine or change it. Those changes will not be accepted.
165
+
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 into any `.things` file.
166
+
openHAB settings as defined in `services/addons.cfg` and `services/runtime.cfg` will override any settings made in PaperUI's Configuration/System pane.
167
+
168
+
## Recommendations for New Users
169
+
170
+
All interface options are supposed to work, still some of the more advanced settings might work better in one or the other setup.
171
+
You have the full freedom of choice. On the other hand, this can be very confusing at times, particularly for new users.
172
+
To help starters in narrowing down choices, here is some guidance that might also help to avoid some future pitfalls:
173
+
174
+
* 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).
175
+
* Create items and groups in `.items` files. You can also use [Homebuilder]{homebuilder.html} to create your initial set of [.items](items.html) and [sitemap](sitemaps.html) 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.
176
+
* Use Paper UI to manage configuration of each and every openHAB 2 add-on and binding.
177
+
* Use file configuration or Paper UI to manage configuration of openHAB 1 add-ons and bindings.
178
+
* Use Paper UI or habmin to manage ZWave things, but use configuration files to manage ZWave items.<br/>
179
+
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).
180
+
_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.
181
+
On the other hand, you will keep changing _items_ rather often.
182
+
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.
183
+
* Use the editor of your choice to edit [sitemaps](sitemaps.html). Start with the demo sitemap as a template.
184
+
* Use VS code extensions to [edit rules, items and sitemap files](editors.html).
185
+
You can also use any text editor, but VS code extensions will help you by highlighting and cross-checking the file syntax.
186
+
Either way, be aware that any 'save' results in openHAB reloading the rules file.
187
+
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.
0 commit comments