Re-organisation Documentation and Getting started (#2055)

* Split MQTT documentation * Add more details * Move content to /docs * Enable sidebar * Move content to /docs * Enable sidebar * Move content * Update links * Remove wizard stuff * Enable sidebar * Minor changes * Move MQTT parts to /docs * update links * Update links and sync content * Fix link * Enable sidebar * Remove navigation * Remove navigation and other minor updates * Update links * Add overview page * Make title linkable * Update * Plit content * Update links * Rearrange content * New getting-started section * Add icons for docs * Update for new structure * Update for new structure * Add docs navigation * Add docs overview page * Remove ecosystem navigation * Add docs and remove other collections * Move ecosystem to docs * Remove duplicate files * Re-add ecosystem overview * Move to ecosystem * Fix permission * Update navigation * Remove collection * Move overview to right folder * Move mqtt to upper level * Move notebook to ecosystem * Remove un-used files * Add one more rectangle for iOS * Move two parts back from docs and rename Run step * Remove colon * update getting-started section * Add redirect * Update * Update navigation
2017-02-23 11:09:41 +01:00 · 2017-02-23 11:09:41 +01:00 · 481320128f
commit 481320128f
parent 0677895b5b
138 changed files with 1309 additions and 909 deletions
--- a/source/_docs/hassbian/common-tasks.markdown
+++ b/source/_docs/hassbian/common-tasks.markdown
@ -0,0 +1,130 @@
+---
+layout: page
+title: "Common tasks on Hassbian"
+description: "Instructions how to do common tasks on Hassbian."
+date: 2016-09-26 21:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/hassbian-common-tasks/
+---
+
+### {% linkable_title Login to the Raspberry Pi %}
+To login to your Raspberry Pi running HASSbian your going to be using a ssh client. Depending on your platform there are several alternatives for doing this. Linux and Max OS generally have a ssh client installed. Windows users are recommended to download and install the ssh client [Putty][ssh-putty].
+
+Connect to the Raspberry Pi over ssh. Default user name is `pi` and password is `raspberry`.  
+Linux and Mac OS users execute the following command in a terminal.
+
+```bash
+$ ssh pi@ip-address-of-pi
+```
+
+Windows users start [Putty][ssh-putty], enter the IP address of the Raspberry Pi in the *Host name* field and port 22 in the *Port* field. Then click *Open* and a terminal window will open. Enter the credentials. Default user name is `pi` and password is `raspberry`.
+
+Optionally, starting with Windows 10 anniversary update, you can use the built-in '[Bash on Windows][bash-windows]' to use SSH if you have enabled Developer mode and have installed the "Windows Subsystem for Linux (beta)" feature.
+
+### {% linkable_title Start/Stop/Restart Home Assistant %}
+Log in as the `pi` account account and execute the following commands:
+
+```bash
+$ sudo systemctl stop home-assistant@homeassistant.service 
+```
+
+Replace `stop` with `start` or `restart` to get the desired functionality.
+To get the current state of the `homeassistant.service` replace `stop` with `status`. 
+
+### {% linkable_title Update Home Assistant %}
+
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo systemctl stop home-assistant@homeassistant.service 
+$ sudo su -s /bin/bash homeassistant
+$ source /srv/homeassistant/bin/activate
+$ pip3 install --upgrade homeassistant
+$ exit
+$ sudo systemctl start home-assistant@homeassistant.service
+```
+
+This will in order do the following:
+
+- Stop the Home Assistant service running on HASSbian
+- Open a shell as the `homeassistant` user running the Homeassistant service and that has ownership over the Home Assistant installation.
+- Change into the virtual Python environment at `/srv/homeassistant/` containing the Home Assistant installation.
+- Upgrade the Home Assistant installation to the latest release.
+- Exit the shell and return to the `pi` user.
+- Restart the Home Assistant service.
+
+### {% linkable_title Manually launch Home Assistant %}
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ source /srv/homeassistant/bin/activate
+$ hass
+```
+
+This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first.
+
+### {% linkable_title Check your configuration %}
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ source /srv/homeassistant/bin/activate
+$ hass --script check_config
+```
+
+This will output any errors in your configuration files to console.
+
+### {% linkable_title Read the Home Assistant log file %}
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ cd /home/homeassistant/.homeassistant
+$ nano homeassistant.log
+```
+
+This will in order do the following:
+
+- Open a shell as the `homeassistant` user.
+- Change directory to the Home Assistant configuration directory.
+- Open the log file in the nano editor.
+
+Optionaly, you can also view the log with `journalctl`.
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo journalctl -fu home-assistant@homeassistant.service
+```
+
+### {% linkable_title Edit the Home Assistant configuration %}
+
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo su -s /bin/bash homeassistant
+$ cd /home/homeassistant/.homeassistant
+$ nano configuration.yaml
+```
+
+This will in order do the following:
+
+- Open a shell as the `homeassistant` user.
+- Change directory to the Home Assistant configuration directory.
+- Open the configuration file in the nano editor.
+
+It's generally recommended that you read the [Getting started][configuring-homeassistant] guide for how to configure Home Assistant.
+
+### {% linkable_title Change locale, timezone and keyboard layout %}
+
+```bash
+$ sudo raspi-config
+```
+
+[configuring-homeassistant]: /getting-started/configuration/
+[ssh-putty]: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
+[stop-homeassistant]: /getting-started/installation-raspberry-pi-image/#startstoprestart-home-assistant-on-hassbian
+[bash-windows]: https://msdn.microsoft.com/en-us/commandline/wsl/about
--- a/source/_docs/hassbian/customization.markdown
+++ b/source/_docs/hassbian/customization.markdown
@ -0,0 +1,23 @@
+---
+layout: page
+title: "Customization"
+description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
+date: 2016-09-26 21:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/hassbian-customization/
+---
+
+To allow you to customize your installation further, we have included a set of Hassbian scripts.
+
+  - Install Samba. Allows anyone on your network to edit your configuration from any computer. This share is unsecured and it's usage is not recommended if you share your network with others.
+  - Install Libcec. Adds local [HDMI CEC support][cec].
+  - Install Mossquitto MQTT server. Installs the latest Mosquitto package and client tools from the Mosquitto projects offical repository. Now includes websocket support.
+  - Install Open Z-Wave. Installs Open Z-Wave and prepares for using a USB or GPIO ZWave controller.
+
+All of these scripts are available in the directory `/home/pi/hassbian-scripts/`. For more information about these scripts have a look at the [hassbian-scripts repository][hassbian-repo].
+
+[hassbian-repo]: https://github.com/home-assistant/hassbian-scripts#the-included-scripts
+[cec]: /components/hdmi_cec/
--- a/source/_docs/hassbian/installation.markdown
+++ b/source/_docs/hassbian/installation.markdown
@ -0,0 +1,37 @@
+---
+layout: page
+title: "Installing Hassbian"
+description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
+date: 2016-09-26 21:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-raspberry-pi-image/
+---
+
+The easiest way to install Home Assistant on your Raspberry Pi is by using HASSbian: a Raspberry Pi image with Home Assistant built-in. The image will install the latest version of Home Assistant on initial boot (~10 minutes).
+
+ 1. [Download the Hassbian 1.1 image][image-download] (359 MB)
+ 2. Use [Etcher][etcher] to flash the image to your SD card
+ 3. Ensure your Raspberry Pi has access to the internet.
+ 4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes.
+
+These instructions are also available as a [video](https://www.youtube.com/watch?v=iIz6XqDwHEk).
+
+After initial boot, you can reach Home Assistant in your browser at [http://hassbian.local:8123]. If you want to login via SSH, the default username is `pi` and password is `raspberry` (please change this by running `passwd`). The Home Assistant configuration is located at `/home/homeassistant/.homeassistant/`.
+
+The following extras are included on the image:
+
+ - GPIO pins are ready to use.
+ - Bluetooth is ready to use (supported models only, no Bluetooth LE).
+
+### {% linkable_title Technical Details %}
+
+ - Home Assistant is installed in a virtual Python environment at `/srv/homeassistant/`
+ - Home Assistant will be started as a service run by the user `homeassistant`
+ - The configuration is located at `/home/homeassistant/.homeassistant`
+
+[image-download]: https://github.com/home-assistant/pi-gen/releases/download/v1.1/image_2017-02-03-HASSbian.zip
+[etcher]: https://etcher.io/
+[http://hassbian.local:8123]: http://hassbian.local:8123
--- a/source/_docs/hassbian/integrations.markdown
+++ b/source/_docs/hassbian/integrations.markdown
@ -0,0 +1,101 @@
+---
+layout: page
+title: "Raspberry Pi integrations"
+description: "Home Assistant integrations specific to the Raspberry Pi."
+date: 2016-09-26 21:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/hassbian-installation/
+---
+
+Some components that are specific for the Raspberry Pi can require some further configuration outside of Home Assistant. All commands below are assumed to be executed with the `pi` account. For full documentation of these components refer to the [components](/components) page.
+
+### {% linkable_title Bluetooth Tracker %}
+
+The Bluetooth tracker will work on a Raspberry Pi 3 with the built-in Bluetooth module or with a USB Bluetooth device on any of the other Raspberry Pi's.
+
+Install the following external dependencies.
+```bash
+$ sudo apt-get install bluetooth libbluetooth-dev
+```
+After this follow the [Bluetooth Tracker component](/components/device_tracker.bluetooth_tracker/) and [Device Tracker page](/components/device_tracker/) pages.
+
+### {% linkable_title Raspberry Pi Camera %}
+
+The Raspberry Pi Camera is a specific camera for the Raspberry Pi boards. For more information about the camera I suggest reading the [documentation](https://www.raspberrypi.org/documentation/usage/camera/) from the Raspberry Pi foundation.
+
+To use the camera it needs to be enabled with the `raspi-config` utility.
+
+```bash
+$ sudo raspi-config
+```
+
+Select `Enable camera` choose `<Yes>` and hit `Enter`, then go to `Finish` and you'll be prompted to reboot.
+
+After reboot add your `homeassistant` account to the `video` group.
+
+```bash
+$ sudo adduser homeassistant video
+```
+
+After this follow the [Raspberry Pi Camera component](/components/camera.rpi_camera/) page.
+
+### {% linkable_title Raspberry Pi GPIO %}
+
+Each of the following devices are connected to the GPIO pins on the Raspberry Pi.
+For more details about the GPIO layout, visit the [documentation](https://www.raspberrypi.org/documentation/usage/gpio/) from the Raspberry Pi foundation.
+
+Since these are not normally used some extra permission will need to be added.
+In general the permission that is needed is granted by adding the `homeassistant` account to the `gpio` group.
+
+### {% linkable_title Raspberry Pi Cover %}
+
+Add your `homeassistant` account to the `gpio` group
+```bash
+$ sudo adduser homeassistant gpio
+```
+After this follow the [Raspberry Pi Cover component](/components/cover.rpi_gpio/) page.
+
+### {% linkable_title DHT Sensor %}
+
+Add your `homeassistant` account to the `gpio` group
+```bash
+$ sudo adduser homeassistant gpio
+```
+After this follow the [DHT Sensor component](/components/sensor.dht/) page.
+
+
+### {% linkable_title Raspberry PI GPIO Binary Sensor %}
+
+Add your `homeassistant` account to the `gpio` group
+```bash
+$ sudo adduser homeassistant gpio
+```
+After this follow the [Raspberry PI GPIO Binary Sensor component](/components/binary_sensor.rpi_gpio/) page.
+
+### {% linkable_title Raspberry PI GPIO Switch %}
+
+Add your `homeassistant` account to the `gpio` group.
+```bash
+$ sudo adduser homeassistant gpio
+```
+After this follow the [Raspberry PI GPIO Switch component](/components/switch.rpi_gpio/) page.
+
+### {% linkable_title Raspberry Pi RF Switch %}
+
+Add your `homeassistant` account to the `gpio` group
+```bash
+$ sudo adduser homeassistant gpio
+```
+After this follow the [Raspberry Pi RF Switch component](/components/switch.rpi_rf/) page.
+
+### {% linkable_title One wire Sensor %}
+
+The One wire sensor requires that support for it is enabled on the Raspberry Pi and that the One Wire device is connected to GPIO pin 4.
+To enable One Wire support add the following line to the end of `/boot/config.txt`
+```yaml
+dtoverlay=w1-gpio
+```
+After this follow the [One Wire Sensor component](/components/sensor.onewire/) page.
--- a/source/_docs/hassbian/upgrading.markdown
+++ b/source/_docs/hassbian/upgrading.markdown
@ -0,0 +1,30 @@
+---
+layout: page
+title: "Upgrading Hassbian"
+description: "Instructions how to upgrade Hasbian to the latest version."
+date: 2016-09-26 21:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/hassbian-upgrading/
+---
+
+HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following.
+Log in as the `pi` account and execute the following commands:
+
+```bash
+$ sudo apt-get update
+$ sudo apt-get upgrade
+```
+
+Press `Y` to confirm that you would like to continue.
+
+#### {% linkable_title Upgrading the hassbian-scripts %}
+
+To update the hassbian-scripts directory execute the following command as the `pi` user.
+
+```bash
+$ cd hassbian-scripts
+$ git pull
+```