reworked for OH3 (openhab#1298)

* improved wording, added OH3 teaser Signed-off-by: Markus Storm <[email protected]> * major changes to match OH3 Signed-off-by: Markus Storm <[email protected]> * major changes to match OH3 Signed-off-by: Markus Storm <[email protected]> * Add link to meetup recording Signed-off-by: Markus Storm <[email protected]> * Update index.md Signed-off-by: Markus Storm <[email protected]> * Update index.md Signed-off-by: Markus Storm <[email protected]> * Update index.md Signed-off-by: Markus Storm <[email protected]> * Update index.md Signed-off-by: Markus Storm <[email protected]> * Small edit to test preview build tooling Signed-off-by: Jerome Luckenbach <[email protected]> * Update configuration/index.md Co-authored-by: Jerome Luckenbach <[email protected]> * Update index.md Signed-off-by: Markus Storm <[email protected]> Co-authored-by: Jerome Luckenbach <[email protected]>
Rosi2143 · Dec 10, 2020 · bea378b · bea378b
1 parent 4e755c2
commit bea378b
Showing 1 changed file with 63 additions and 91 deletions.
diff --git a/configuration/index.md b/configuration/index.md
@@ -6,10 +6,10 @@ title: 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 frontend, the rule engine and other parts and connected systems.
+Properties and capabilities of all your devices are available through openHAB to the user interface.
 
-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.
+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:
@@ -24,26 +24,30 @@ In order to represent all of these, openHAB defines the following base component
 - [Rules](rules-dsl.html) - Automation logic, the "smart" in your Smart Home!
 - [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/)
 
-The individual articles hold all details needed to understand the concepts behind these building bricks for your Smart Home.
+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](/docs/concepts/index.html).
 
 ## 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.**
+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](https://www.youtube.com/watch?v=pwZ8AOwRDEk) for a tour of the new Main UI (starting at 26:26).
+
+::: tip Important changes for openHAB 2 users<br>
+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.<br>
+v1 bindings are no longer available. The expire binding's functionality is now part of the core (item configuration stays the same).<br>
+File based configuration is still available, then again we recommend anyone to start over with a fresh setup using the new Main UI only.<br>
+_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._
+:::
 
 <table class="centered highlight">
   <thead>
     <tr>
-      <th data-field="task">Task</th>
-      <th data-field="files">Textual Configuration</th>
-      <th data-field="paperui">Paper UI</th>
-      <th data-field="habmin">HABmin</th>
-      <th data-field="homebuilder">Homebuilder</th>
-      <th data-field="karaf">Console</th>
+      <th data-field="task">Configuration Task</th>
+      <th data-field="files">via text files</th>
+      <th data-field="mainui">in Main UI</th>
+      <th data-field="karaf">openHAB console</th>
       <th data-field="recommendation">Recommendation</th>
     </tr>
   </thead>
@@ -52,146 +56,114 @@ For a recommendation to new users which one(s) to use, see the section below. In
     <tr>
       <td>Auto-Discover Things and Items</td>
       <td>❌</td>
-      <td>✔️R</td>
-      <td>✔️R</td>
-      <td>❌</td>
       <td>✔️</td>
-      <td>Paper UI or HABmin<br/>Do not autocreate Items</td>
-    </tr>
-    <tr>
-      <td>Define and manage Things</td>
-      <td>(✔️)<br/>not for all bindings</td>
-      <td>✔️R</td>
-      <td>✔️R</td>
-      <td>❌</td>
       <td>✔️</td>
-      <td>Paper UI or HABmin</td>
+      <td>Main UI<br/>Do not autocreate Items</td>
     </tr>
     <tr>
-      <td>Define and manage Items</td>
-      <td>✔️R</td>
+      <td>Define and manage Things</td>
       <td>✔️</td>
-      <td>❌</td>
       <td>✔️</td>
       <td>✔️</td>
-      <td>items/*.items files</td>
+      <td>Main UI</td>
     </tr>
     <tr>
-      <td>Define Groups</td>
-      <td>✔️R</td>
-      <td>✔️</td>
-      <td>❌</td>
+      <td>Define and manage Groups and Items</td>
       <td>✔️</td>
       <td>✔️</td>
+      <td>(✔️)</td>
       <td>items/*.items files</td>
     </tr>
     <tr>
-      <td>Define Sitemaps</td>
-      <td>✔️R</td>
-      <td>❌</td>
-      <td>❌</td>
-      <td>✔️R</td>
-      <td>❌</td>
-      <td>Homebuilder or sitemaps/*.sitemap files</td>
+      <td>Define GUI</td>
+      <td>sitemaps only</td>
+      <td>✔️<br>includes YAML view</td>
+      <td>✔️</td>
+      <td>Main UI<br>sitemaps/*.sitemap files</td>
     </tr>
     <tr>
       <td>Define Transformations</td>
       <td>✔️</td>
       <td>❌</td>
       <td>❌</td>
-      <td>❌</td>
-      <td>❌</td>
-      <td>transform/*.map files</td>
+      <td>transform/*.map *.js files</td>
     </tr>
     <tr>
       <td>Define Persistence</td>
       <td>✔️</td>
       <td>❌</td>
       <td>❌</td>
-      <td>❌</td>
-      <td>❌</td>
       <td>persistence/*.persist files</td>
     </tr>
     <tr>
       <td>Define Rules</td>
-      <td>✔️R</td>
-      <td>(❌)<br/>only for the experimental rules engine</td>
-      <td>(❌)<br/>not functional</td>
-      <td>❌</td>
+      <td>✔️</td>
+      <td>✔️</td>
       <td>❌</td>
-      <td>rules/*.rules files</td>
+      <td>Main UI<br>for starters: Blockly<br>(graphically create JS code)<br>for advanced users:<br>rules/*.rules files<br>for rules DSL and JSR223</td>
     </tr>
     <tr>
       <td>Manage Z-Wave Devices</td>
       <td>❌</td>
       <td>✔️</td>
-      <td>✔️R</td>
-      <td>❌</td>
       <td>❌</td>
-      <td>HABmin</td>
+      <td>Main UI</td>
     </tr>
     <tr>
       <td>Modify openHAB Settings/Services</td>
       <td>✔️</td>
-      <td>✔️R</td>
       <td>✔️</td>
-      <td>❌</td>
       <td>✔️</td>
-      <td>Paper UI</td>
+      <td>Main UI</td>
     </tr>
     <tr>
       <td>Install Add-ons</td>
-      <td>✔️R<br/>mandatory for OH1 bindings to require config</td>
-      <td>✔️R</td>
       <td>✔️</td>
-      <td>❌</td>
       <td>✔️</td>
-      <td>services/addons.cfg or Paper UI<br/>services/*.cfg for OH1 bindings</td>
+      <td>✔️</td>
+      <td>Main UI</td>
     </tr>
   </tbody>
 </table>
 
 ### 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.
+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](/docs/administration/jsondb.html) 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_.
 
-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).
-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.
+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
-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.
+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.
 :::
 
-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.
+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
 
-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 `.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.
-* 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.<br/>
-  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](sitemaps.html). Start with the demo sitemap as a template.
+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](editors.html).
-  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.
+  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.
+