From 39f5813968efc1fca5380bbe4a477d6812f63cec Mon Sep 17 00:00:00 2001
From: Thomas Dietrich <Thomas.Dietrich@tu-ilmenau.de>
Date: Sun, 7 Aug 2016 18:55:01 +0200
Subject: [PATCH] Update installation overview and RPi article (#65)

* Replace Overview article
* Move chapter on service to RPi
---
 _includes/user-menu.html |   1 -
 installation/index.md    | 146 +++++++++++++++-----------
 installation/prereqs.md  |  25 -----
 installation/rasppi.md   | 216 +++++++++++++++++++++++++++++++--------
 4 files changed, 260 insertions(+), 128 deletions(-)
 delete mode 100644 installation/prereqs.md

diff --git a/_includes/user-menu.html b/_includes/user-menu.html
index 5043a8491..cf426314f 100644
--- a/_includes/user-menu.html
+++ b/_includes/user-menu.html
@@ -13,7 +13,6 @@
 	<li><a href="{{docu}}/installation/index.html">Installation</a>
 		<ul>
 			<li><a href="{{docu}}/installation/index.html">Overview</a></li>
-      <li><a href="{{docu}}/installation/prereqs.html">Prerequisites</a></li>
 			<li><a href="{{docu}}/installation/apt.html">Linux (APT)</a></li>
 			<li><a href="{{docu}}/installation/linux.html">Linux (manual)</a></li>
 			<li><a href="{{docu}}/installation/rasppi.html">Raspberry Pi</a></li>
diff --git a/installation/index.md b/installation/index.md
index fcaadde7b..27def9d96 100644
--- a/installation/index.md
+++ b/installation/index.md
@@ -1,14 +1,99 @@
 ---
 layout: documentation
+title: Installation Overwiew
 ---
 
 {% include base.html %}
 
-# Installing openHAB
+# Installation Overview
+
+openHAB 2 is based on the Eclipse SmartHome framework and is fully written in Java.
+As such, it only depends on a [Java Development Kit](http://java.com/de/download/manual.jsp), which is available for many platforms.
+openHAB can be executed on different versions of **Mac OS X** and **Windows** and many different variants of **Linux** (Ubuntu, Raspbian, ...).
+
+Please be aware of the fact, that openHAB 2 is based on a new core and introduces new concepts.
+Therefore, tutorials and help you may find on the internet for openhab 1 **might** be outdated!
+
+## Platform Recommendations
+
+1. You are **new to openHAB 2** and want to give it a try? You are in luck:
+  - Set up openHAB 2 on your local PC or Mac in just a few steps.
+
+2. You gained some experience and want to use openHAB to seriously control your home?
+  Typical hardware and software requirements are:
+    - **24/7 availability:** A dedicated system connected by Ethernet and running continuously.
+    - **Energy and space efficient:** A device capable of performing the task at hand without being exaggerated
+    - **Extendibility:** Your system should be capable of running additional software like an MQTT broker or a persistence and graphing software.
+    - **Peripherals:** Depending on your home automation hardware, you will need additional peripheral devices such as a WiFi interface or a special USB radio module.
+  
+  Many devices are suited to host a continuous installation of openHAB 2.
+  The [Raspberry Pi](rasppi.html) as a minimal sufficient device is quite popular, experiences with many other devices can be found in the [community forum hardware section](https://community.openhab.org/c/hardware/server).
+
+## Prerequisites
+
+Make sure that you have an up to date version of the [Oracle Java Development Kit](http://java.com/de/download/manual.jsp) on your host system installed.
+Oracle Java Version 8 is recommended for openHAB.
+
+A famous alternative to Oracle Java is the OpenJDK.
+Note that openHAB may be unstable and slower executed by OpenJDK, it is therefor **recommended** to switch to Oracle Java if possible.
+
+Check your current Java version by opening a console and typing "java -version":
+
+```
+console$ java -version
+java version "1.8.0 73"
+Java(TM) SE Runtime Environment (build 1.8.0_73-b02)
+Java HotSpot(TM) 64-Bit Server VM (build 25.73-b02, mixed mode)
+```
+
+## Setup variants
+
+Before you can start, three decisions have to be made:
+
+1. openHAB 2 is available as a platform independent archive file or through a package repository:
+  - **Manual setup:** Download and extract a platform independent zip archive: [Mac OS X](macosx.html), [Windows](windows.html), [Linux](linux.html)
+  - **Package setup:** Install though a package repository, including automatic updates.
+    This option is only available for Debian or Ubuntu derivatives: [Linux (apt/deb)](apt.html)
+
+2. Stable release or cutting edge:
+  - **Stable:** Use the latest official release ([hosted on Bintray](https://bintray.com/openhab/mvn/openhab-distro)).
+  - **Snapshot:** Benefit from the latest changes in the daily created snapshot ([hosted on CloudBees](https://openhab.ci.cloudbees.com/job/openHAB-Distribution)).
+   
+  Because openHAB 2 is still under heavy development, it is recommended for experienced users to use the latest snapshot.
+
+3. The distribution is available in two flavors:
+  - **Offline:** This package contains all available add-ons and allows installing them locally, i.e. completely offline.
+  - **Online:** This package only contains the core runtime and downloads any add-on from a remote repository.
+
+  We currently recommend to use the "offline" version and to update regularly.
 
 ## Installation
 
-openHAB comes as a [platform independent zip file](https://openhab.ci.cloudbees.com/job/openHAB-Distribution/lastSuccessfulBuild/artifact/distributions/openhab-offline/target/openhab-offline-2.0.0-SNAPSHOT.zip), which you only need to extract to some folder.
+Please follow the instructions in the installation article matching your platform.
+
+## Additional Steps
+
+After you got openHAB 2 set up and running, there are a few additional setup steps you should consider:
+
+* Configure a network share on your openHAB host device and mount it locally: [Samba Share](rasppi.html) 
+* Install the [Eclipse SmartHome Designer](designer.html) on your local machine, to manage your (remote) configuration files.
+  The designer comes with built-in support for the openHAB syntax and elements.
+
+## Getting started 
+
+With the openHAB 2 distribution up and running, you should now continue with
+the [Demo Tutorial](http://docs.openhab.org/tutorials/demo.html),
+the [Beginner Tutorial](http://docs.openhab.org/tutorials/beginner)
+or by working on your [own configuration](http://docs.openhab.org/configuration).
+
+## Help
+
+The very active [openHAB Community Forum](https://community.openhab.org) provides many more details and hints.
+If you run into any problems, use the search function or open a new thread with your detailed question.
+
+
+
+<!-- That shouldn't be here
 
 You will find the following folders:
 
@@ -126,60 +211,5 @@ openhab:install-service
 
 in the shell and make sure that the folder `<openhab root folder>/runtime/karaf` is writable (only required at this time, you can make it read-only again afterwards).
 The files are then generated for you and a short guide is displayed on what further actions you need to take to register it as a system service.
-
-### Raspberry Pi
-
-If you're running Raspbian Jessie and have systemd installed the following steps will allow you to register openHAB as a service so that it runs at startup and automatically restarts if openHAB crashes.
-
- 1. Make sure openHAB is installed somewhere, for the purpose of this guide it's installed in /opt/openhab2.
- 2. Create the following file called "openhab.service" in /lib/systemd/system/ replacing the username with whichever user runs openHAB on your setup.
- 
-```
-[Unit]
-Description=Starts and stops the openHAB Home Automation Bus
-Documentation=http://www.openhab.org
-Wants=network-online.target
-After=network-online.target
-
-[Service]
-Type=simple
-GuessMainPID=yes
-User=**enter your openhab username here**
-ExecStart=/opt/openhab2/start.sh
-ExecStop=kill -SIGINT $MAINPID
-Restart=on-failure
-WorkingDirectory=/opt/openhab2
-
-[Install]
-WantedBy=multi-user.target
-```
- 
- 3. Run the following commands to enable the service, start the service and check the status of the service respectively.
- 
-```
-sudo systemctl enable openhab
-sudo systemctl start openhab
-sudo systemctl status openhab
-```
-
- 4. Assuming all looks good when you checked the status of the service, i.e. you see something like the below on your command line, then it should now be setup to run as a service.
-
-```
- openhab.service - Starts and stops the openHAB Home Automation Bus
-   Loaded: loaded (/etc/systemd/system/openhab.service; enabled)
-   Active: active (running) since Thu 2016-01-14 01:16:00 GMT; 18h ago
-     Docs: http://www.openhab.org
-```
- 
- 5. If you need to stop openHAB use the following command.
-  
-```
- sudo systemctl stop openhab
-```
- 
- 6. If you need to disable the service so that it doesn't run at startup use the following command.
- 
-```
- sudo systemctl disable openhab
-```
  
+-->
diff --git a/installation/prereqs.md b/installation/prereqs.md
deleted file mode 100644
index 6f9a0c3ef..000000000
--- a/installation/prereqs.md
+++ /dev/null
@@ -1,25 +0,0 @@
----
-layout: documentation
----
-
-{% include base.html %}
-
-# Prerequisites
-
-You require a JDK 8 in order to run openHAB. Note that there are often issues with OpenJDK, therefore it is advised to use the OracleJDK instead.
-
-Check that the correct version of Java has been installed:
-
-* Open the terminal window
-
-* Type the following command `java -version`
-
-* You should see something like this :
-
-```
-cal:~ callas$ java -version
-java version "1.8.0 73"
-Java(TM) SE Runtime Environment (build 1.8.0_73-b02)
-Java HotSpot(TM) 64-Bit Server VM (build 25.73-b02, mixed mode)
-```
-
diff --git a/installation/rasppi.md b/installation/rasppi.md
index bc789e028..8e01077ba 100644
--- a/installation/rasppi.md
+++ b/installation/rasppi.md
@@ -1,81 +1,137 @@
 ---
 layout: documentation
+title: Raspberry Pi
 ---
 
 {% include base.html %}
 
-# Installation on a Raspberry Pi
+# Raspberry Pi
 
-Here you will find some suggestions on how to configure a dedicated [RaspberryPi](https://www.raspberrypi.org) to run as a openHAB server. Your personal preferences and needs may differ.
+Because of it's low price, it's small form factor and the low energy consumption, the [Raspberry Pi](https://www.raspberrypi.org) is a quite popular platform for openHAB.
+Be sure to use a [Raspberry Pi Generation 2](https://en.wikipedia.org/wiki/Raspberry_Pi#Specifications) or newer.
 
-There’s no pre-configured image for openHAB, so installation is done the old fashioned way via a command line.
+![Raspberry Pi 2 Model B](https://www.raspberrypi.org/wp-content/uploads/2015/02/Pi_2_Model_B.png)
 
-Start with the latest (full) [Raspbian SD image](https://www.raspberrypi.org/downloads/raspbian) (not the “lite” version, these don’t include the Java Virtual Machine). Get your network cable plugged in, then boot up, and navigate through SSH. Run:
+## Introduction
+
+In this article you will find **suggestions** on how to configure a dedicated Raspberry Pi to run as openHAB server.
+Your personal preferences and needs may differ!
+
+There’s no pre-configured image for openHAB yet.
+Setting up openHAB shouldn't be a problem following the instructions below.
+
+If you are unfamiliar with Linux, SSH and the Linux console or if you want to improve your skills, read up on these important topics.
+A lot of helpful articles can be found on the internet, including:
+
+* The [raspberrypi.org help articles](https://www.raspberrypi.org/help).
+* Technical in-detail articles at [eLinux.org](http://elinux.org/RPi_Tutorials).
+* "Learn the ways of Linux-fu, for free" interactively with exercises at [linuxjourney.com](https://linuxjourney.com/).
+
+## Recommended Setup
+
+You will need:
+
+* Raspberry Pi (Generation 2 or newer), compare your existing device [here](https://en.wikipedia.org/wiki/Raspberry_Pi#Connectors) if you are unsure.
+* SD card (8GB or more)
+* Power supply
+* Ethernet connection
+
+For the beginning, we recommend to [download](https://www.raspberrypi.org/downloads/raspbian) and [install](https://www.raspberrypi.org/documentation/installation/installing-images/README.md) the latest Raspbian SD card image (not the "lite" version).
+Get your SD card and network cable plugged in, power up, and connect through the SSH remote console.
+
+Execute the Raspbian configuration menu by running: `sudo raspi-config`
+
+* Expand the file system
+* Change your password
+* (Change the host name, default: "raspberrypi")
+* From the advanced menu, change the memory split to "16"
+* Restart
+
+As a good practice, run a full upgrade and install packages you like or need (a set of helpful packages is given as an example):
 
 ```
-sudo raspi-config
+sudo apt-get update
+sudo apt-get full-upgrade
+sudo apt-get install screen mc vim nano curl wget unzip git htop vfu
 ```
 
-Expand the filesystem; and from the advanced menu, change the memory split to 16. When are done, restart, and as good practice, run a full update
+Install openHAB on Linux. This can be done two ways:
 
-Install openHAB on Linux, see [Installation on Linux through APT](http://docs.openhab.org/installation/apt.html)
+* [Installation on Linux manually](linux.html)
+* [Installation on Linux through APT](apt.html) (recommended)
 
-Curiously, everything was installed as owned by “root”. We need to fix that with the following commands.
+### Permissions
 
-```
-sudo chown -hR openhab:openhab /etc/init.d/openhab2
-sudo chown -hR openhab:openhab /usr/share/openhab2
-```
+<!-- Note to author: May be moved to linux.html while you are at it -->
 
-Next, we’ll install Samba and share the configuration and user folders – this will make it easier to install add-ons and change the sitemap remotely.
+Linux file permissions is one of the biggest sources of issues, Linux novices run into.
+If you find yourself in a situation, where you have **no write access** to the openHAB configuration or system files, wrong permissions and/or the incorrect use of `sudo` are often the cause.
+
+Train your understanding of Linux permissions at [linuxjourney.com/lesson/file-permissions](https://linuxjourney.com/lesson/file-permissions).
+
+## Network Share
+
+openHAB depends on configuration files and folders with custom content (details in [Configuration](http://docs.openhab.org/configuration/index.html) articles).
+Because your openHAB installation is stored on a remote device, being able to easily access and modify these files from your local PC or Mac is important.
+The recommended [Eclipse SmartHome Designer](http://docs.openhab.org/installation/designer.html) software does also depend on a mounted share to access the openHAB configuration files.
+
+We will now guide you through the Samba network shares setup process.
+Start by installing Samba. Afterwards open it's config file in your favorite editor:
 
 ```
 sudo apt-get install samba samba-common-bin
 sudo nano /etc/samba/smb.conf
 ```
 
-Change the workgroup name if needed, but otherwise enable WINS support:
+Change the workgroup name if needed, otherwise uncomment and enable WINS support:
 
 ```
 wins support = yes
 ```
 
-(you’ll need to uncomment the line, and change no to yes)
-
-then add the following to the share definitions section (scroll all the way down to the bottom of the long file):
+Next, add the following lines to the end of the file:
 
 ```
 [openHAB]
- comment=openHAB2 application
- path=/usr/share/openhab2
- browseable=Yes
- writeable=Yes
- only guest=no
- create mask=0777
- directory mask=0777
- public=no
- [openHAB-etc]
- comment=openHAB2 site configuration
- path=/etc/openhab2
- browseable=Yes
- writeable=Yes
- only guest=no
- create mask=0777
- directory mask=0777
- public=no
+  comment=openHAB2 application
+  path=/usr/share/openhab2
+  browseable=Yes
+  writeable=Yes
+  only guest=no
+  public=no
+  create mask=0777
+  directory mask=0777
+
+[openHAB-etc]
+  comment=openHAB2 site configuration
+  path=/etc/openhab2
+  browseable=Yes
+  writeable=Yes
+  only guest=no
+  public=no
+  create mask=0777
+  directory mask=0777
 ```
+Save and close the samba configuration file.
 
-Also commented out the Printers section. Made two shares, then the configuration files are actually stored separately to the add-ons.
+As you can see, we are creating two shares, one for the openHAB application files, one for the configuration files.
+Please take note, that the mentioned paths will differ if you did not install through the package repository.
 
-Save and exit. We finally need to set a Samba password for the openhab user:
+The shares are configured to be not open for guests or to the public.
+Let's create an "openhab" samba user and set his password (e.g. "habopen"):
 
 ```
 sudo smbpasswd -a openhab
 ```
 
-Suggest “openhab” as the password just for ease of use, but it doesn’t really matter.
+Be aware, that creating and later using a specific user will ensure, that [permissions](#permissions) are honored.
+Transfer the ownership of all openHAB files to the "openhab" user, making sure you will be able to write them:
 
-The method of restarting Samba has changed in the latest Raspian. Here’s the updated instructions:
+```
+sudo chown -hR openhab:openhab   /etc/openhab2 /usr/share/openhab2
+```
+
+Finally restart Samba:
 
 ```
 sudo update-rc.d smbd enable
@@ -83,20 +139,92 @@ sudo update-rc.d nmbd enable
 sudo service smbd restart
 ```
 
-After restarting Samba (older installs use sudo service samba restart), test you can access the shared drive. It might not be auto-discovered on a Mac; but you can use the Finder -> Go -> Connect to Server and the address
+### Mounting Locally
+
+After setting up and restarting Samba, check your connection to the shared folders and and create permanent mounts.
+The shares might not be auto-discovered on your systems network devices page.
+You'll have to manually connect:
+
+* **On Mac OS X:** Open Finder -> Go -> Connect to Server: `smb://openhab@raspberrypi.local`
+* **On Windows:** Open Windows Explorer -> Address bar: `\\raspberrypi.local` -> Right click a share and assign a drive letter
+
+When asked, authenticate with the username openhab and the chosen password.
+Be sure to use the right host name if you changed it to something different than "raspberrypi".
+If you are not able to connect, try with the IP of your Raspberry Pi (e.g. `smb://openhab@192.168.0.2` or `\\192.168.0.2`).
+
+If everything went well, you are set and ready to start [configuring](http://docs.openhab.org/configuration/index.html) your openHAB system.
+
+## Viewing the Log Messages
+
+<!-- Note to author: This part may be moved to a different article -->
+
+In order to get more insight on what your openHAB system is doing and to see occurring error messages, it is recommended to always have a look on the openHAB log files. These will tell you everything you might need to know. Execute the following command in one session or have both files separated in sessions side by side:
 
 ```
-smb://openhab@raspberrypi.local
+tail -f /var/log/openhab2/openhab.log -f /var/log/openhab2/events.log
 ```
 
-Authenticate with username openhab and the chosen password, then open up both the shares to have a look around. Then should even be able to open http://raspberrypi.local:8080/ in the web browser, but then will be met with an error because don´t haven’t create a sitemap yet. That’s normal.
+You could even set up an SSH configuration (in putty or similar) to automatically connect and execute the commands every time you start working on your setup.
 
+With openHAB 2 you can also [use the Karaf console](http://docs.openhab.org/administration/logging.html#karaf-console) to have a colored glance at the logging information.
 
-Now would be a good time to learn the command to tail the openHAB log so you can keep an eye on errors.
+## Service
 
+The following instructions are only relevant if you did a manual (non-apt) installation!
+
+<!-- Note to author: Please move to linux.html while you are at it ;) -->
+
+Under Raspbian Jessie, the following steps will allow you to register openHAB as a service, so that it runs at startup and automatically restarts if openHAB crashes.
+
+ 1. Make sure openHAB is installed somewhere, for the purpose of this guide it's installed in /opt/openhab2.
+ 2. Create the following file called "openhab.service" in /lib/systemd/system/ replacing the username with whichever user runs openHAB on your setup.
+ 
+```ini
+[Unit]
+Description=Starts and stops the openHAB Home Automation Bus
+Documentation=http://www.openhab.org
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=simple
+GuessMainPID=yes
+User=**enter your openhab username here**
+ExecStart=/opt/openhab2/start.sh
+ExecStop=kill -SIGINT $MAINPID
+Restart=on-failure
+WorkingDirectory=/opt/openhab2
+
+[Install]
+WantedBy=multi-user.target
 ```
-tail -f /var/log/openhab2/openhab.log
+ 
+ 3. Run the following commands to enable the service, start the service and check the status of the service respectively.
+ 
+```
+sudo systemctl enable openhab
+sudo systemctl start openhab
+sudo systemctl status openhab
 ```
 
-Keep that running and open in a separate SSH window at all times.
+ 4. Assuming all looks good when you checked the status of the service, i.e. you see something like the below on your command line, then it should now be setup to run as a service.
+
+```text
+ openhab.service - Starts and stops the openHAB Home Automation Bus
+   Loaded: loaded (/etc/systemd/system/openhab.service; enabled)
+   Active: active (running) since Thu 2016-01-14 01:16:00 GMT; 18h ago
+     Docs: http://www.openhab.org
+```
+ 
+ 5. If you need to stop openHAB use the following command.
+ 
+```
+ sudo systemctl stop openhab
+```
+ 
+ 6. If you need to disable the service so that it doesn't run at startup use the following command.
+ 
+```
+ sudo systemctl disable openhab
+```