[WIP] Getting started tutorial (#1304)

* Removed old no longer needed images

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added intro and first steps.

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added getting starte to concepts, updated build file

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added Getting Started to Concepts, updated build file

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Fixinf the build

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Still trying to fix the build

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added Thing - Simple page

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Separated sentences.

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added things Simple to index

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added Things Intermediate

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added Things Advanced page.

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added Model page.

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Added Persistence - Please review

Signed-off-by: Rich Koshak <rlkoshak@gmail.com>

* Update .vuepress/docs-sidebar.js

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Fixes for a working preview build and existing conflicts.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Fixed wrong image reference.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Fix all hyperlinks due to build folder movements.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Fix page lin kand test different style for page navigation.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Fix model. Reintroduce sidebar.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Remove manual navigation links. Improve sidebar.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Edits to tutorial index.md

Minor edits to wording.

Signed-off-by: Bob Adair <bob.github@att.net>

* Refactor first steps with new setup wizard screenshots.

Signed-off-by: Jerome Luckenbach <github@luckenba.ch>

* Edits to first steps page

Signed-off-by: Bob Adair <bob.github@att.net>

Co-authored-by: Jerome Luckenbach <github@luckenba.ch>
Co-authored-by: Bob A <bobadair@users.noreply.github.com>

.vuepress/docs-sidebar.js

@@ -35,20 +35,26 @@ module.exports = [
       ['installation/security', 'Security']
     ]
   },
-  // {
+  {
-  //   title: 'New User Tutorial',
+    title: 'Beginner Tutorial',
-  //   collapsable: false,
+    collapsable: false,
-  //   children: [
+    children: [
-  //     ['tutorial/', 'Tutorial Overview'],
+      ['tutorial/', 'Tutorial Overview'],
-  //     'tutorial/1sttimesetup',
+      'tutorial/first_steps',
-  //     'tutorial/uis',
+      'tutorial/things_simple',
-  //     'tutorial/configuration',
+      'tutorial/things_intermediate',
-  //     'tutorial/sitemap',
+      'tutorial/things_advanced',
-  //     'tutorial/rules',
+      'tutorial/model',
-  //     'tutorial/logs',
+      'tutorial/persistence',
-  //     ['tutorial/persistence', 'Persistence']
+      /*'tutorial/pages_intro',
-  //   ]
+      'tutorial/pages_widgets',
-  // },
+      'tutorial/pages_types',
+      'tutorial/rules_simple',
+      'tutorial/rules_intermediate',
+      'tutorial/cloud',
+      'tutorial/example'*/
+    ]
+  },
   {
     title: 'Configuration Guide',
     collapsable: false,

.vuepress/process_main_docs.rb

@@ -53,13 +53,13 @@ def process_main_docs(docs_source_dir)
     puts ">>> Migrating the Tutorial section"
 
 
-    Dir.glob("#{docs_source_dir}/tutorials/beginner/*.md") { |path|
+    Dir.glob("#{docs_source_dir}/tutorials/getting_started/*.md") { |path|
         file = File.basename(path)
         puts " -> #{file}"
-        process_file("#{docs_source_dir}/tutorials/beginner", file, "docs/tutorial", "#{$docs_repo_root}/tutorials/beginner/#{file}")
+        process_file("#{docs_source_dir}/tutorials/getting_started", file, "docs/tutorial", "#{$docs_repo_root}/tutorials/getting_started/#{file}")
     }
     puts " -> images"
-    # FileUtils.cp_r("#{docs_source_dir}/tutorials/beginner/images", "docs/tutorial/images")
+     FileUtils.cp_r("#{docs_source_dir}/tutorials/getting_started/images", "docs/tutorial/images")
     # FileUtils.cp_r("#{docs_source_dir}/tutorials/images/*", "docs/tutorial/images")
 
 

tutorials/getting_started/first_steps.md

@@ -0,0 +1,98 @@
+---
+layout: documentation
+title: Getting Started - First Steps
+---
+
+{% include base.html %}
+
+# First Steps
+
+The following instructions will guide you through the initial steps to take after first installing openHAB.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+## Create the Admin User
+Once openHAB is installed and started, launch the user interface by navigating to [http://localhost:8080]() (if not running locally, replace localhost with the server's address or hostname accordingly).
+If you installed from the openHABian image, you can use [http://openhab:8080]().
+
+By default, the administration pages can only be accessed if you are logged in with an administrator account.
+Since there are no users yet, openHAB will ask you to create an administrator account.
+The following screen should appear:
+
+![](images/create_user.png)
+
+After creating a first admin user you will be guided trough a first time setup wizard.
+
+You have to add some geographical information and start (or skip) the setup wizard.
+
+![](images/wizard_geo.png)
+
+![](images/wizard_location.png)
+
+You have the ability to install some addons if you already know that you will need them later.
+
+![](images/wizard_addons.png)
+
+After finishing the wizard you will get a welcome message and be redirected to your dashboard.
+
+![](images/wizard_welcome.png)
+
+![](images/welcome_page.png)
+
+### Log in into dashboard with an existing user
+
+To log in with an existing user you can do the following.
+Click on the shield icon in the lower-left corner of the sidebar:
+
+![](images/shield.png)
+
+If you don't see it, click on the menu icon ![](menu_icon.png) located at the top-left corner to reveal the sidebar.
+Once you have successfully created the admin account, you will be taken back to the previous screen, except the Administration area will now be accessible in the sidebar:
+
+![](images/administrator.png)
+
+Currently the only way to add additional users or manage existing ones (including changing passwords and attributing roles) is with the [Console]({{base}}/administration/console.html).
+
+If you need to sign out, or check what sessions are open with this account with the option to terminate them, click on the account option which has replaced the "Unlock administration" shield:
+
+![](images/account_option.png)
+
+Note that by default, using openHAB doesn't require you to sign in.
+Only administrative operations require a user with an administrator role to be logged in.
+
+## Initial Settings
+Click on Settings.
+
+![](images/initial_settings.png)
+
+Click on Regional Settings under System Services.
+
+![](images/regional_settings.png)
+
+Configure the local language, region and time zone.
+You can also specify the exact location (latitude, longitude, altitude) of your home, which some add-ons can use to preset their configuration.
+For instance, the Astro binding will use the location to determine the time of astrological events like sunrise and sunset in your area.
+
+If you're not using the metric system, click "Show advanced" and change the measurement system.
+
+![](images/units_settings.png)
+
+## Additional Settings
+The following settings are available but not covered by this tutorial.
+
+Setting | Purpose
+-|-
+Network Settings | Configure the default networks OH listens on and broadcasts on, IPV6, etc.
+Audio | Configure the default microphone and audio destination
+Ephemeris | Configure day types (e.g. which days of the week are weekends) and import your locale's holidays. Can be used in rules.
+API Security | Allows Basic Auth to be used for accessing protected parts of the openHAB API. By default an authorization token or OAuth2 is required.
+Addon Management | Choose whether to download add-ons when they are installed or use a locally stored collection of all the add-ons.
+Persistence | Set the system-wide default persistence engine.
+Json Storage | Settings for the automatic backup of UI generated configs.
+Inbox | Settings that affect how Items are shown and approved in the Inbox where discovered Things appear.
+Charts | Default settings for generated charts.
+Voice | Settings for voice-to-text, text-to-voice and human language processing.
+Other Services | The items that appear here will changed based on the set of add-ons installed. These are places to configure those bindings and capabilities (e.g. set up the connection for InfluxDB Persistence).

tutorials/getting_started/index.md

@@ -0,0 +1,97 @@
+---
+layout: documentation
+title: Getting Started - Introduction
+---
+
+{% include base.html %}
+
+# Welcome!
+
+Welcome to openHAB 3!
+We hope that your journey with openHAB is a rewarding one.
+If you encounter problems or simply cannot figure something out on your own, please do not hesitate to post a question on [the forum](https://community.openhab.org).
+There are many fellow openHAB users ready and willing to help as much as possible.
+Most requests for help receive a response within a couple of hours.
+
+First, a word on the order of the sections in the docs.
+This tutorial assumes users have read the concepts and installation guides already.
+Thus it assumes at least a basic knowledge of the concepts of openHAB.
+The tutorial also assumes that the user has already installed openHAB and confirmed it is working.
+
+## File-based vs. UI-driven Configuration
+
+Early on the user must choose between a text file based configuration or a User Interface driven configuration.
+Switching from one approach to the other later on is not trivial.
+
+To help you choose between the two approaches, the following is a summary of the pros & cons for each:
+
+### File-based
+Pros:
+- File based has been the only really practical way to define most objects (things excluded) in previous versions, so a lot of examples in the docs and the forum will assume that approach. However, as time passes there will be more and more UI driven examples.
+- With file based configs it is easier to make bulk changes and bulk updates, to duplicate similar objects, and to separate domains into distinct files.
+- The config files can be treated as source files, easing backups and version control. Though that does not mean that source control, backups, and version control cannot be done with UI driven configs.
+- Files can be synced through any file sync services (e.g. Dropbox, Nextcloud) to the openHAB machine.
+- Easier to share configurations between multiple openHAB instances.
+
+Cons:
+- Config files are more prone to errors. The slightest typo leads to a syntax error that could cause the file to become invalid, which will result in everything defined in that file being removed from the system until you fix it.
+- The syntax for the config files can be a little overwhelming for novice users, as you have to learn and understand the syntax in addition to openHAB concepts and home automation technologies.
+- You will see most objects defined in files in the UI but you won't be able to edit them (those objects will have a lock besides their name/label :lock:).
+- You need to sit in front of a computer with access to the files to make changes.
+
+### UI-driven
+Pros:
+- Easier to understand for novices. The UI assists you with built in documents and help. There's fewer opportunities to make mistakes since the syntax is almost impossible to get wrong.
+- All objects can be altered from anywhere the UI can be reached (including on mobile).
+- Things can be auto-discovered.
+- Items can be auto-created from Things (with a chance to edit).
+- The internal database is somewhat faster, especially on resource-limited devices (e.g. Raspberry Pis) than the file parsing.
+- A backup of the internal database is created on every change.
+
+Cons:
+- Can be slower to reach one's goals if you already know what you're doing and if there's a lot of bulk changes or duplicating required.
+- Harder to remove obsolete stuff.
+- Some things cannot be configured with the UI yet (e.g. persistence).
+- You need to sit in front of a device with access to the UI to make changes.
+
+It's possible to mix the two, for example use the UI for things and files for items, but avoid using both techniques at the same time in other cases.
+This tutorial targets new users.
+Therefore the tutorial will present a purely UI-driven approach.
+Review the reference documentation for details on the text based approach.
+
+When building a configuration through the UI, one still has access to a text based YAML formatted representation of their configs.
+On most of the configuration screens there will be two tabs, a "Design" tab anda  "Code" tab.
+If you run into problems or want to share something you've created through the UI, click on the "Code" tab and post that YAML to the forum using code fences instead of or in addition to screen shots.
+
+## Table of Contents
+
+This tutorial presents a series of steps that build upon one another so please review the tutorial in order.
+There may be concepts or steps that are presented earlier that are required to understand the parts of the tutorial presented later.
+
+[First Steps]({{base}}/tutorial/first_steps.html): Initial configuration
+
+[Adding Things: Simple]({{base}}/tutorial/things_simple.html): Discovering Things
+
+[Adding Things: Intermediate]({{base}}/tutorial/things_intermediate.html): Creating Bridges
+
+[Adding Things: Advanced]({{base}}/tutorial/things_advanced.html): Manual creation of Things
+
+[Items and the Semantic Model]({{base}}/tutorial/model.html): Creating Items and putting them into a semantic model
+
+[Persistence]({{base}}/tutorial/persistence.html): Saving and retrieving historic data
+
+<!--
+[Pages: Introduction]({{base}}//tutorial/pages_intro.html): What are Pages?
+
+[Pages: Widgets]({{base}}/tutorial/pages_widgets.html): Introduction to populating Pages
+
+[Pages: Page Types]({{base}}/tutorial/pages_types.html): Layout, Charts, and Tabbed type Pages
+
+[Rules: Simple]({{base}}/tutorial/rules_simple.html): Introduction to rules and a simple example
+
+[Rules: Intermediate]({{base}}/tutorial/rules_intermediate.html): Rules that involve some scripting
+
+[openHAB Cloud]({{base}}/tutorial/cloud.html): Connecting to the free openHAB Cloud Service
+
+[Putting it all Together]({{base}}/tutorial/example.html) Comprehensive Example
+-->

tutorials/getting_started/model.md

@@ -0,0 +1,174 @@
+---
+layout: documentation
+title:  Semantic Model
+---
+
+{% include base.html %}
+
+# Semantic Model
+
+Things represent devices and the sensors and actuators of those devices.
+But one of the purposes of openHAB is to abstract from the specifics of each of the hundreds of supported technologies and APIs so that a light switch is a light switch whether it's controlling a Hue light bulb, a KNX wall switch, or a custom DIY relay that speaks MQTT.
+To provide that abstraction openHAB uses Items.
+
+There are a fixed set of Item types representing all the different ways that a sensor reading can be represented or ways a device can be interacted.
+The configuration of your Items is where meaning is applied to your devices.
+For example, instead of dealing with `zwave:1231242:node12:switch` we can deal with "Livingroom_Lamp".
+
+Items are the main entity that the rest of openHAB works with including Pages, sitemaps, rules, and persistence.
+
+There are many ways to organize your items, one of which is to make use of the semantic model (descriptions for location, type of equipment and more).
+openHAB 3 makes extensive use of the semantic model to automatically create Pages (see next section) and to provide natural language interaction.
+Therefore we recommend creating the semantic model right from the start and sticking to it.
+This will make your life easier in the long run.
+Taking the time to understand and choose a logical structure for your home will save you from needing to re-do the work a second time in the future.
+
+This section gives a good example of one way to model your home with locations and equipment descriptions.
+The semantic model, when setup correctly, will allow openHAB to turn all lights off in a kitchen when asked, as the framework can understand the kitchen location and what items are lights in that location.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+## Introduction to the Ontology and Relationships
+
+![](images/ontology_relationships.jpeg)
+
+The above drawing shows the relationship between the four main concepts in the model.
+
+- A Location is a Group Item that can contain sub-Locations, Equipment and Points and represents a location (building, room, etc.).
+- An Equipment is normally a Group Item that can contain sub-Equipment, and Points.
+- A Point is not a Group but any other type of Item and is usually linked to a Channel.
+- A Property is an additional tag on a Point Item that indicates what sort of point it is. For example, a thermometer might be a Point of type Measurement with a Property of type Temperature.
+
+Example of an advanced model:
+
+![](images/example_model.png)
+<!--(made with https://www.diagrameditor.com - file here: [Semantic Model.txt|attachment](upload://qEPmmmDomSr4F5dRBHMXajOzO0c.txt) (3.3 KB) change extension to .drawio) -->
+
+We have an Indoor location which has a House.
+The House has a Ground Floor and the Ground Floor has rooms including a Living Room.
+The Living Room has a Rollershutter equipment which in turn has a Control and Power point Item.
+The locations and equipment are Group Items and Control and Power are other types of Items.
+
+One key feature of the this example model is that you are not required to *only* use the semantic model.
+It is possible and encouraged to create Groups and Items that are outside of the model where necessary.
+In this example, the Rollershutter in the Living Room is a member of the AllRollershutters Group which could be used to determine if any are OPEN and send commands to all the rollershutters in the house at once.
+
+You can use as few or as many layers of Locations as you wish to model your home.
+For instance if you live in a flat (apartment) your root Locations might just be the rooms.
+If you only have one building, you can omit the indoor/outdoor layer and the building layer to only have a hierarchy of floors and rooms, etc.
+
+Equipment are often mapped to Things but not always.
+You can represent a single Equipment with several Things - for instance a computer might have points to switch it on (send a wake-on-lan packet), off (shell command), determining if it's online (network polling), how much power it consumes (Z-Wave wall plug).
+All these multiple Things from different bindings can be combined to model a single piece of Equipment.
+
+The `Computer` is the equipment and it could be located in a room called the `study` location.
+The computer is made up of multiple Things, some of which are not physical devices.
+
+A front door can have points to determine if it's open or closed (with a sensor) or locked (with a smart lock), and a camera/motion detector.
+
+Finally, an Equipment can be made up of multiple Equipment.
+Using the example above, the Z-Wave plug might be model as a subequipment of the `Computer` equipment.
+
+## Building the Locations Model
+
+From the Settings screen, click on Model.
+
+![](images/start_model.png)
+
+Let's start with a hierarchy of Locations. Click on Add Location.
+
+![](images/create_location.png)
+
+Add your first item, a Group representing the ground floor: give it a name (choose carefully, you cannot change it afterwards).
+Choose a label, category (it mostly defines the default icon), and specialize the item by choosing a more accurate semantic class than "Location", here "GroundFloor".
+
+Once it's created, make sure it's still selected on the left, and click on "Add Location" again - this will add another location _within_ the first floor.
+Typically rooms are directly under floor locations.
+Add an item representing the living room, call it `Living`, set the `sofa` category and the `LivingRoom` semantic class.
+
+Now let's add the kitchen: make sure to select Ground Floor again and choose Add Location to add the third item (name: `Kitchen`, category: kitchen, semantic class: Kitchen).
+
+To add the first floor to the root level, we need to clear the selection first, click on the white space in the tree, or Clear in the bottom toolbar.
+Add the ground floor, and its rooms (master bedroom, bathroom, etc...) to your model.
+
+You should end up with something resembling this:
+
+![](images/locations_model.png)
+
+## Modeling Equipment
+
+Now let's add some Equipment and Points.
+You could proceed like for the Locations and create them by hand, but there's an easier way.
+If the Equipment you're adding is one of the Things that you already added, you have two options.
+
+### From the Model Page
+
+Select where in the model you want to add the Equipment, for instance, the kitchen, and click on Create Equipment from Thing.
+
+![](images/create_equipment_model.png)
+
+Select the Thing you want to create the Equipment from, and alter the details of the Equipment item that will be created.
+If you don't find an appropriate Equipment class, choose Equipment.
+
+Below are all the Channels defined by the Thing, sometimes Things will have hundreds of channels so here you have the opportunity of choosing which ones will be linked to new Points items.
+Check the channels you're interested in and only those.
+
+![](images/create_equipment_model_channels.png)
+
+For the plant sensor Thing added earlier, we have an opportunity to change the default basic Number types and make them quantifiable.
+Quantity types (Number with a dimension) provide conversion facilities between Units of Measurement, and the default persistence is more granular.
+For percentages like humidity or battery levels, use `Number:Dimensionless`, which a quantity type without a dimension.
+
+Also set the semantic class to Measurement and choose an appropriate related property.
+
+When you're finished, click Add in the title bar: the Equipment and Points should be added to the model where you wanted.
+
+![](images/create_equipment_model_added.png)
+
+The "Plant Sensor" Equipment has been created under the Kitchen location and all the selected Points represent the selected Channels of the Thing.
+
+### From a Thing's Page
+
+From the Settings, click on Things and click on the Thing you wish to add to the model.
+Switch to the Channels tab.
+
+![](images/create_equipment_things_channels.png)
+
+Click on Add Equipment to Model below the list: you'll encounter a similar screen to the one above.
+The difference is, rather than selecting the Thing, you have to select where in the model you want to add the Equipment.
+
+![](images/create_equipment_things_location.png)
+
+Select Pick From Model in the Parent Group section, the treeview of the Locations and Equipments will appear; select the parent group, for instance Living Room, then choose Pick in the top-right corner of the dialog box.
+If this equipment is a part of another equipment, choose that equipment as the parent instead of a location.
+
+![](images/create_equipment_things_parent.png)
+
+Then do the same as above, configure the Equipment item and the Points, then click Add.
+
+Go back to the Model by choosing Model in the sidebar and verify that the Equipment added to the model from the thing page is effectively there as well as its Points.
+
+![](images/create_equipment_things_added.png)
+
+Note how the Channel Links section lists the link to the Thing/Channel, and you also have a control widget to control the item - since it's linked to the Color channel of the Hue bulb, the light will reflect the state of the item.
+
+Finish adding Equipment and Points from your Things.
+
+## Retrofitting Existing Items to the Model
+There may be times where a user needs to add existing Items to their model.
+Perhaps they are migrating from an older version of OH, they did not follow the advice above to start with the model to begin with, or they are following a tutorial or example that doesn't include the model.
+In this case all is not lost.
+Existing Items can be added to the model.
+Browse to the Item in the Items settings, click on Edit and choose an appropriate Semantic Class and Semantic Property.
+Then add the Point as a member of the appropriate Equipment or Location Group.
+If the Equipment Group doesn't exist yet, create a Group and use the appropriate Equipment semantic tag first and add the Equipment to the appropriate Location Group.
+
+## Modifying the Model
+As illustrated here, the model consists mainly of Group membership and tags on Items.
+To change the location of an equipment or room, simply change the parent Group.
+To change the type of an equipment or point, simply edit the tags.
+Some of these edits are possible from the Model Page itself.
+Where that's not supported, you can change these through the Item's Page.

tutorials/getting_started/persistence.md

@@ -0,0 +1,63 @@
+---
+layout: documentation
+title:  Persistence
+---
+
+{% include base.html %}
+
+# Persistence
+
+There are many times in home automation where one wants to keep, chart, and otherwise use the historic states of their Items.
+openHAB has the concept of Persistence to achieve this.
+With Persistence one can:
+
+- chart a temperature sensor's reading over time (more on this later)
+- restore an Item to the state it had prior to openHAB closing down or restarting
+- use the state of an Item in the past, or some aggregate of the state of an Item in the past (e.g. average since one hour ago) in automation rules (more on this later).
+
+There are many different databases, some embedded and others running as an external service that are supported for Persistence.
+Those that are not embedded require the installation and configuration of a separate database server.
+
+Note that Persistence only saves Item states.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+## Persistence Concepts
+As previously mentioned, Persistence saves Item states.
+But the question is, when does it save those Item states?
+- Every time the Item changes?
+- Every time the Item is updates (an update does not necessarily result in the Item changing state)?
+- Only when the Item receives a command?
+- Every minute whether it's received an event or not?
+These are all different *persistence strategies* and they can be combined (e.g. every Item changed and every five minutes.)
+
+One special persistence strategy is `restoreOnStartup` which will update the Item with the most recently saved Item state when openHAB starts up or otherwise refreshes the Item.
+
+The good news here is that if you don't know what you may want to use persistence for, you can just keep the defaults and move to the next step.
+
+## Persistence Configuration
+Each persistence add-on comes with it's own default persistence strategy.
+See the doc for the specific persistence add-on for what the default strategy is.
+This default can be overwritten.
+Unfortunately, configuration of the persistence strategies is still text based.
+See the [Persistence docs]({{base}}/configuration/persistence.html) for the full documentation and see the installation page for the method you used to install openHAB for a table listing file locations.
+At a high level, you will create a file in `$OH_CONF/persistence` with the name of the add-on and a .persist extension (e.g. `influxdb.persist`).
+Edit the file per the docs to define the strategies.
+
+Often, one will not want to use the same persistence strategy for all Items.
+One may not even want to save all their Items or may want to save different Items to different databases using different strategies.
+For example, a common approach would be to use [`MapDB`]({{base}}/addons/persistence/mapdb/) only for those Items that should be restored on startup, [`rrd4j`]({{base}}/addons/persistence/rrd4j) with an `everyChange` and every minute strategy for number and binary (Switch, Contact) type Items that are to be charted, and [`Influxdb`]({{base}}/addons/persistence/influxdb) with an `everyUpdate` strategy for analysis with external tools.
+
+## Default Persistence
+openHAB ships with [`rrdj4`]({{base}}/addons/persistence/rrd4j) as the default persistence database and comes with a default persistence strategy of `everyChange`, `everyMinute`, and `restoreOnStartup` for every supported Item.
+The good thing about `rrd4j` is that the database never grows beyond a given size so you never have to clean it up.
+However, the way it achieves this (replacing ten readings with the average of the ten readings as the data gets older) makes the database not work for all Item types.
+If you need to `restoreOnStartup` unsupported Item types, `MapDB` might be a better choice for you.
+
+## Why Bother with Persitence?
+As with the model, the reason why one would set up the Model discussed in the previous tutorial and Persistence is that it will make creating your user interfaces much easier and much more rich.
+For example, a set of UI pages will be created automatically in MainUI based on the model.
+And just about any place you can interact with an Item in MainUI there will be an "Analyze" button that will generate a chart based on the data saved in persistence.

tutorials/getting_started/things_advanced.md

@@ -0,0 +1,128 @@
+---
+layout: documentation
+title:  Adding Things - Advanced
+---
+
+{% include base.html %}
+
+# Adding Things - Advanced
+
+Some bindings and technologies simply do not support automatic discovery.
+These technologies tend to be the most complicated to understand, configure, and use.
+You the user will need to have at least a working understanding of the underlying technology to be successful.
+For example, if you will use the Exec binding with openHAB running on Linux, you will need a working understanding of how to run commands on the terminal, file permissions, users, etc.
+
+This tutorial will use the MQTT binding as an example.
+Important note, the MQTT Binding also supports automatic discovery of Things for devices that use the Homie or Home Assistant standards in their topic structure and messaging.
+In those cases, the MQTT binding works more like the Intermediate Thing example.
+
+Scenario: You have a [MQTT-enabled plant sensor](https://github.com/ThomDietrich/miflora-mqtt-daemon), and for the purpose of this tutorial let's assume it doesn't respect the Homie or Home Assistant convention, so it cannot be detected and configured automatically by the MQTT binding.
+Instead, it's publishing metrics regularly in a simple JSON structure like the following on a preconfigured MQTT topic:
+
+```json
+{"light": 5424, "moisture": 30, "temperature": 21.4, "conductivity": 1020, "battery": 100}
+```
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+## Prerequisites
+- A basic understanding of how MQTT works (HiveMQ provides a good [tutorial](https://www.hivemq.com/blog/mqtt-essentials-part-3-client-broker-connection-establishment/)
+- An installed and configured MQTT Broker (e.g. Mosquitto which can be installed through openHABian if that is how you installed openHAB)
+- A MiFlora device configured to connect to the MQTT Broker, or an MQTT client application (e.g. [MQTT Explorer](http://mqtt-explorer.com/), [MQTT.fx](http://mqttfx.org/) that allows one to publish and subscribe to MQTT topics
+
+## Install the Binding and Transformation
+This device publishes JSON formatted messages so we need to install an add-on that can process JSON: the JSONPath Transformation.
+A Transformation takes incoming data and transformes is somehow.
+In this case it will extract certain fields from the JSON.
+From Settings, click on Transformations under Add-ons.
+
+![](images/choose_transformation.png)
+
+Click on the blue "+" button, and find JSONPath Transformation. Click on it, then Install.
+
+![](images/install_jsonpath.png)
+
+Wait for it to disappear from the list, then click back twice to go back to Settings.
+
+Next, install the MQTT binding: click on Bindings, then the "+" button, find the MQTT Binding, click on it than Install.
+Wait for it to disappear from the list, then go back twice to return to the main Settings screen.
+
+## Create the Bridge Thing
+First, we need to add the broker, which is a Bridge.
+Click on Things.
+
+Click on the blue "+" button.
+
+Choose "MQTT Binding", then choose "MQTT Broker".
+
+![](images/mqtt_things.png)
+
+Fill in the details to connect to the broker, you may also alter its ID and name.
+If you need credentials to connect to the broker, click on "Show advanced" to reveal additional options, including Username and Password.
+
+![](images/mqtt_bridge_config.png)
+
+## Create the Generic MQTT Thing
+Now we have to add the plant sensor itself as a generic Thing.
+
+On the Things page, first verify that the broker is indeed present and online; if so, click on the blue "+" button then MQTT Binding.
+
+Note that you might have results under "Discovered things" already appearing if you happen to have auto-discoverable devices publishing messages to the broker.
+
+In our case, click on Generic MQTT Thing under "Add manually".
+
+Change the ID and label if you wish.
+
+The important setting is to choose the Bridge that the new Thing will work with.
+Click on Bridge and choose the broker that you configured above in the list.
+Then click "Add" in the top-right corner.
+
+Back on the Things page, choose the Thing you created.
+It should be marked online, but it will not have any Channels on the Channel tab - you have to configure them yourself.
+
+![](images/mqtt_generic_thing.png)
+
+Click on Add Channel.
+
+Let's add the temperature first.
+Fill in the "channel identifier" and "Label" fields accordingly: for instance, `temperature` as the identifier and `Air Temperature` as the label.
+
+This channel will provide numbers, therefore choose the Number value channel type for the new channel.
+Scroll down and enter the MQTT topic receiving the JSON message in the MQTT State Topic field.
+However, we don't want this channel to provide the whole message, only the temperature part.
+
+Click on "Show advanced" above MQTT State Topic to reveal more settings.
+
+Scroll down, find the "Incoming Value Transformations" setting, and specify the transformation to apply there:
+
+```
+JSONPATH:$.temperature
+```
+
+![](images/mqtt_temp_channel.png)
+
+Click Done in the title bar to add the channel, it should now be added to the Channels tab.
+
+![](images/mqtt_temp_channel_created.png)
+
+Repeat the procedure for the other channels:
+
+Value | Label | Type | Incoming value transformation
+-|-|-|-
+light | Light Intensity | Number value | `JSONPATH:$.light`
+moisture | Soil Moisture | Number value | `JSONPATH:$.moisture`
+conductivity | Soil Conductivity | Number value | `JSONPATH:$.conductivity`
+battery | Battery Level | Number value | `JSONPATH:$.battery`
+
+All channels should specify the MQTT topic where the JSON message is published.
+
+If you want to check the configuration for a channel, or made a mistake while adding it, open the channel details by clicking on it, and choose Configure Channel.
+
+![](images/mqtt_config_channel.png)
+
+Note that you cannot change the channel type if you picked the wrong one, in that case, remove the channel by clicking on Remove Channel and add it again.
+
+This concludes the Thing discovery and creation examples.
+Next Items and the model.

tutorials/getting_started/things_intermediate.md

@@ -0,0 +1,68 @@
+---
+layout: documentation
+title:  Adding Things - Intermediate
+---
+
+{% include base.html %}
+Previous: [Adding Things - Simple]({{base}}/tutorial/things_simple.html)
+
+# Adding Things - Intermediate
+
+This section will show an example for dealing with a binding where the bridge Thing cannot be automatically discovered.
+
+Scenario: you have some Z-Wave devices, including a wall plug and a rollershutter module, and a Z-Wave controller stick connected to the computer running openHAB.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+## Install the Binding
+From Settings, go to Things, then click the blue "+" button.
+
+We need to install the Z-Wave binding.
+Click "Install More Bindings".
+
+![](images/install_zwave.png)
+
+Find the Z-Wave binding, click on it then click Install.
+
+![](images/installing_zwave.png)
+
+Wait for it to disappear from the list then go back.
+
+![](images/installed_zwave.png)
+
+## Create the Bridge Thing
+Click on the new option: Z-Wave Binding.
+
+Click on Z-Wave Serial Controller to add the controller.
+
+![](images/zwave_add_controller.png)
+
+We need to specify one required parameter, the serial port.
+In certain cases, depending on your system, you will be provided with a list of options for this setting.
+
+![](images/zwave_port_config.png)
+
+Choose the correct port, alter the name and/or ID of the controller Thing, then click Add in the top-right corner.
+
+## Discover Things
+Once back on the Things screen, click on the "+" button then Z-Wave Binding again.
+Click scan and all the devices already paired with the Zwave controller will be discovered and appear in the Inbox.
+To pair a new device, while on this screen, perform the procedure specific to the device to include it in your network.
+Go to the add-ons section of [this site]({{base}}/addons/bindings/zwave/doc/things.html#things-supported-by-the-z-wave-binding) and search for for the device model in the search bar.
+The page should give you details on the inclusion procedure.
+Alternatively, look in the device's documentation from the vendor.
+
+Once included the device should appear in the Inbox, and on the "Add a new Thing: zwave" page.
+
+Approve it the usual way.
+Repeat the procedure for every Zwave device.
+
+Note: Battery powered devices will be discovered but may remain as an "unknown" type until the device has woken up enough for the binding to discover what it is.
+On it's own this process can take days.
+To speed up the process activate the device several times until the Thing shows the correct device.
+
+As shown, some technologies like Zwave and Zigbee require additional manual steps to add them to openHAB.
+However, there are some technologies and bindings that simply do not support automatic discovery at all.

tutorials/getting_started/things_simple.md

@@ -0,0 +1,120 @@
+---
+layout: documentation
+title:  Adding Things - Simple
+---
+
+{% include base.html %}
+
+# Adding Things - Simple
+
+As covered in the [concepts section]({{base}}/../../../concepts/index.html) of the openHAB Docs, a binding is an add-on to openHAB that understands how to communicate with a home automation technology or API.
+A Thing represents a single device in openHAB. Each sensor (information provided by the device) or actuator (control on the device to cause it to do something) is represented by a Channel on the device.
+Things are the connection between openHAB and your external device or API using the binding.
+
+Some technologies require a special type of Thing called a "bridge".
+A bridge is a device or connection through which openHAB connects to other devices.
+For example, in this tutorial light bulbs are accessed through a hub device.
+That hub device is represented by a bridge Thing.
+
+This tutorial covers an example of the easiest and most common method for adding Things, using automatic discovery.
+
+Scenario: You have some Philips Hue light bulbs connected to an official Hue bridge.
+In this case, the Hue binding supports auto discovery of both the bridge, the bulbs and other devices.
+
+{::options toc_levels="2..4"/}
+
+- TOC
+{:toc}
+
+
+## Install the Binding
+
+After logging in as an administrator click on `Settings` from the sidebar, then click on `Things`.
+
+![](images/empty_things_menu.png)
+
+Click on the blue "+" button located at the bottom-right corner.
+
+Since you have no bindings, this screen will appear:
+
+![](images/choose_binding.png)
+
+Click on `Install Bindings`.
+
+Look for the Hue binding (The search bar at the top can help find bindings quicker by filtering the long list), click on it then on Install:
+
+![](images/install_hue.png)
+
+It will take from a few seconds to a minute for the binding to install...
+
+![](images/installing_hue.png)
+
+Wait for it to disappear from the list, then click < Back (or use the browser controls).
+The Hue binding will now appear on the previous screen.
+You will notice that the auto discovery has already detected something (note the red "1" badge).
+
+![](images/installed_hue.png)
+
+## Accept the Discovered Bridge Thing
+
+Click on the binding.
+
+The bridge has indeed been detected and appears under Discovered Things.
+If not, you can try again by clicking the `Scan Again` button.
+
+![](images/hue_things_discover_bridge.png) Thing
+
+Click on the discovered `Hue Bridge`.
+
+![](images/add_hue_bridge.png)
+
+openHAB will ask you to confirm or change the label/name.
+Click OK after naming the new Thing.
+
+You will be taken back to the Things page, where now the Hue Bridge should now appear:
+
+![](images/hue_bridge_offline.png)
+
+However, we can see that it's marked offline.
+To find out why we can click on the `Hue Bridge`.
+
+![](images/hue_bridge_config_error.png)
+
+The error description below the status gives some more information: You have to press the physical button on the device to let openHAB authenticate to it.
+Once you've done this, the Thing will become online:
+
+![](images/hue_bridge_online.png)
+
+## Accept the Light Bulb Things
+
+Go back to Things.
+You will notice a new red button on that screen:
+
+![](images/hue_inbox.png)
+
+It means that there are newly discovered devices that you can add; since the Hue bridge is now working, the binding has detected all the Hue devices (bulbs, switches and so on) attached to it.
+
+The Inbox is a consolidated view of all the discovery results, alternatively you can also click on the "+" button to get a per-binding view, and the ability to perform a new scan.
+
+Click Inbox.
+
+![](images/discovered_hue_things.png)
+
+You can either click on an individual thing to see actions related to it, or you can click on Select in the top-right corner to add check boxes beside items, which will allow you to perform actions on several inbox entries at once.
+
+![](images/hue_individual_add.png)
+
+![](images/hue_bulk_add.png)
+
+These actions are:
+- Approve: promote the candidate from the Inbox to a Thing
+- Ignore: hide the candidate from the list (you will be able to see it again and un-ignore it by clicking on "Show ignored" above the list
+- Remove: remove the candidate from the Inbox (it might be detected again later).
+
+Go back to Things: the newly approved Hue Things should appear on the list.
+
+![](images/hue_things_added.png)
+
+You now have the Bridge Thing and the two light bulbs added to openHAB.
+Thankfully most of the bindings you will work with in openHAB will work in this simple way.
+However, there are some technologies that require a bit more manual configuration.

tutorials/index.html

@@ -11,9 +11,8 @@ title: Tutorials
   <p>openHAB empowers you to do (nearly) everything in your smart home. Start small, reach high!</p>
   <div class="row center targets">
 
-<!-- Restore with link to the Getting Started Tutorial
     <div class="col s12 m6 l4 offset-l2">
-      <a href="beginner/index.html">
+      <a href="getting_started/intro.html">
         <div class="target target-beginner card">
           <i class="material-icons icon-large">person</i>
           <div class="footer">
@@ -24,7 +23,6 @@ title: Tutorials
         </div>
       </a>
     </div>
--->
 
 <!-- Restore with link to the Migration tutorial. , or remove if one doesn't materialize
     <div class="col s12 m6 l4">