diff --git a/README.markdown b/README.markdown index 32421af2737..3dc2d536518 100644 --- a/README.markdown +++ b/README.markdown @@ -1,28 +1,26 @@ # Home Assistant website -This is the source for the [Home Assistant](https://github.com/balloob/home-assistant) website available at [Home-Assistant.io](https://home-assistant.io). All commits made to the `master` branch will be automatically pushed to production. - -Please point your Pull Request (PR) at the `next` branch. - -## Preview Jekyll website locally - -| Command | Action | -|---|---| -| `rake preview` | Preview site on [http://127.0.0.1:4000](http://127.0.0.1:4000) +This is the source for the [Home-Assistant.io website](https://home-assistant.io) for the [Home Assistant project](https://github.com/balloob/home-assistant) ## Setup -_You need to have Ruby installed._ +Setting up to contribute to documentation and the process for submitting pull requests is [explained here](https://home-assistant.io/developers/website/). -- [Ruby installation instructions](https://www.ruby-lang.org/en/documentation/installation/) -- For Fedora and CentOS check the last section of this file. +## Create a new blog post ```bash -$ git clone --recursive https://github.com/balloob/home-assistant.io.git -$ cd home-assistant.io -$ bundle +$ rake new_post["title"] ``` +## Site preview + +```bash +$ rake preview +``` + +This makes the preview available on [http://127.0.0.1:4000](http://127.0.0.1:4000). + + ### Setup on Fedora and CentOS On Fedora > 22 or CentOS 7.1.1503 Ruby is not available by default. Please take the notes here as a little guide for the Ruby installation process. @@ -42,4 +40,4 @@ The last command will give you something like this `ruby 2.2.3p173 (2015-08-18 r $ gem install bundler ``` -Now please follow the Setup instructions above. +Now you can follow the [setup instructions](https://home-assistant.io/developers/website/). diff --git a/source/developers/index.markdown b/source/developers/index.markdown index 158f32285af..583e5c161a2 100644 --- a/source/developers/index.markdown +++ b/source/developers/index.markdown @@ -9,17 +9,20 @@ sharing: true footer: true --- -Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Webcomponents)](https://www.polymer-project.org/) for the frontend. +Home Assistant is built from the ground up to be easily-extensible by other developers using components. It uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend. Home Assistant is open-source and MIT licensed. The source can be found here: - - [home-assistant](https://github.com/balloob/home-assistant) - Python server-backend - - [home-assistant-js](https://github.com/balloob/home-assistant-js) - javascript-backend powering the client + - [home-assistant](https://github.com/balloob/home-assistant) - Python server backend + - [home-assistant-js](https://github.com/balloob/home-assistant-js) - JavaScript backend powering the client - [home-assistant-polymer](https://github.com/balloob/home-assistant-polymer) - Polymer UI ### {% linkable_title Starting development %} -You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to perform it. Visit the [the Home Assistant repository](https://github.com/balloob/home-assistant) first and click fork in the top right. +You will need to set up a development environment if you want to start developing a new feature or component for Home Assistant. Please follow these steps to get setup. +Visit the [the Home Assistant repository](https://github.com/balloob/home-assistant) first and click fork in the top right. + +We suggest that you setup a [virtual environment](https://docs.python.org/3.4/library/venv.html) aka `venv` before running the setup script. ```bash $ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git @@ -28,13 +31,17 @@ $ git remote add upstream https://github.com/balloob/home-assistant.git $ script/setup ``` -We suggest that you setup a [virtual environment](https://docs.python.org/3.4/library/venv.html) aka `venv` before running the setup script. +Testing your work requires `tox` to be installed: + +```bash +$ pip3 install tox +``` After following these steps, running `hass` will invoke your local installation. ### {% linkable_title Submitting improvements %} -Improvements to Home Assistant should be submitted one feature at a time using Github pull requests. +Improvements to Home Assistant should be submitted one feature at a time using GitHub [pull requests](https://help.github.com/articles/using-pull-requests). 1. From your fork, create a new branch to hold your changes `git checkout -b some-feature` @@ -44,15 +51,10 @@ Improvements to Home Assistant should be submitted one feature at a time using G 4. Commit the changes `git add .` `git commit -m "Added some-feature"` - 5. Push your commited changes back to your fork on GitHub + 5. Push your committed changes back to your fork on GitHub `git push origin HEAD` 6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request. -Note that the above requires `tox` to be installed. If you don't have it, do this: - -```bash -$ pip3 install tox -``` ### {% linkable_title Further reading %} diff --git a/source/developers/website.markdown b/source/developers/website.markdown index fac5d007e18..3a5bead0605 100644 --- a/source/developers/website.markdown +++ b/source/developers/website.markdown @@ -9,19 +9,28 @@ sharing: true footer: true --- -The home of Home Assistant is [https://home-assistant.io](https://home-assistant.io). This is the place where we provide documentation and additional details about Home Assistant for end users and developers. +The website you're reading now is the home of Home Assistant: [https://home-assistant.io](https://home-assistant.io). This is the place where we provide documentation and additional details about Home Assistant for end users and developers. -home-assistant.io is using the [Octopress](http://octopress.org/) framework for [Jekyll](http://github.com/mojombo/jekyll). To get more details, please checkout the [documentation](http://octopress.org/docs/). That means that creating a new page is simple. The pages are written in [markdown](http://daringfireball.net/projects/markdown/), you don't need to care about HTML or alike. +home-assistant.io uses the [Octopress](http://octopress.org/) framework for [Jekyll](http://github.com/mojombo/jekyll). To get more details, please checkout the [Octopress documentation](http://octopress.org/docs/). +That means that creating a new page is simple. The pages are written in [markdown](http://daringfireball.net/projects/markdown/); you don't need to care about HTML or the like. -To work on the website the process is no different to working on Home Assistant itself. +The process for working on the website is no different from working on Home Assistant itself. -- Fork the home-assistant.io [git repository](https://github.com/balloob/home-assistant.io). +To test your changes locally, you need to install the **Ruby** dependencies (gems): + +- [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. +- Install `bundler`, which is a dependency manager for Ruby: `gem install bundler` +- In your home-assistant.io root directory, run `bundle` to install the gems you need. + +Then you can work on the documentation: + +- Fork home-assistant.io [git repository](https://github.com/balloob/home-assistant.io). - Create/edit/update a page in the directory `source/_components/` for your platform/component. -- To test changes to home-assistant.io locally, run ``rake preview`` and navigate to http://127.0.0.1:4000. +- Test your changes to home-assistant.io locally: run ``rake preview`` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000) - Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is for a new feature, platform, or component. - Create a Pull Request (PR) against the **master** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation. -For a platform page it would be the fastest way to make a copy of an existing page and edit it. The [component overview](/components/) is generated automatically, so there is no need to add a link to that your page. +For a platform page, the fastest way is to make a copy of an existing page and edit it. The [component overview](/components/) is generated automatically, so there is no need to add a link to your page. ### {% linkable_title Code %} To take advantage of the built-in features of Octopress to display code snippets, just use the default markdown syntax. Please use `$` and `#` if it's a command and to differ from output. @@ -37,7 +46,7 @@ If you want to display line numbers, add the following snippet somewhere on your ``` ### {% linkable_title Images, icons, and logos %} -The images which are displayed on the pages are stored in various directories according their purpose. +The images which are displayed on the pages are stored in various directories according to their purpose. | Type | Location | | :----------- |:----------------------------------------------| diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index bdf04226678..787f20885b1 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -9,19 +9,75 @@ sharing: true footer: true --- -Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X/Linux it's `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. If you want to use a different folder for configuration, run `hass --config path/to/config`. +Home Assistant will create a configuration folder when it is run for the first time. The location of the folder differs between operating systems: on OS X and Linux it's `~/.homeassistant` and on Windows it's `%APPDATA%/.homeassistant`. If you want to use a different folder for configuration, run `hass --config path/to/config`. -Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is. -This file contains YAML code, which is explained briefly in [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/). An example configuration file is located [here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example). +Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains which components will be loaded and what their configuration is. +This file contains YAML code, which is explained briefly below. +[An example configuration file is located here](https://github.com/balloob/home-assistant/blob/master/config/configuration.yaml.example). -When launched for the first time, Home Assistant will write a default configuration enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the interface. +When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and show up in the user interface. If you run into trouble while configuring Home Assistant, have a look at [the configuration troubleshooting page](/getting-started/troubleshooting-configuration/). +

-You will have to restart Home Assistant for changes in configuration.yaml to take effect. + You will have to restart Home Assistant each time you make changes in configuration.yaml in order for these to take effect.

+### {% linkable_title YAML %} + +Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations. + +For each component that you want to use in Home Assistant, you add code in your `configuraton.yaml` file to specify its settings. +Example, the following code specifies that you want to use the [notify component](/components/notify) with the [pushbullet platform](/components/notify.pushbullet). + + +```yaml +notify: + platform: pushbullet + api_key: "o.1234abcd" + name: pushbullet +``` + +- A **component** provides the core logic for some functionality (like `notify` provides sending notifications). +- A **platform** makes the connection to a specific software or hardware platform (like `pushbullet` works with the service from pushbullet.com). + +The basics of YAML syntax are block collections and mappings containing key-value pairs. +Each item in a collection starts with a `-` while mappings have the format `key: value`. If you specify duplicate keys, the last value for a key is used. + +Note that indentation is an important part of specifying relationships using YAML. Things that are indented are nested "inside" things that are one level higher. So in the above example, `platform: pushbullet` is a property of (nested inside) the `notify` component. +Getting the right indentation can be tricky if you're not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. Convention is to use 2 spaces for each level of indentation. + +Lines that start with **#** are comments and are ignored by the system. + +The next example shows an [input_select](/components/input_select) component that uses a block collection for the options values. +The other properties (like name) are specified using mappings. Note that the second line just has `threat:` with no value on the same line. Here threat is the name of the input_select and the values for it are everything nested below it. + +```yaml +input_select: + threat: + name: Threat level +# A collection is used for options + options: + - 0 + - 1 + - 2 + - 3 + initial: 0 +``` + +The following example shows nesting a collection of mappings in a mapping. +In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their `state_topic` (one of the properties used for MQTT sensors). + +```yaml +sensor: + - platform: mqtt + state_topic: sensor/topic + - platform: mqtt + state_topic: sensor2/topic +``` + + ### {% linkable_title Setting up the basic info %} By default Home Assistant will try to detect your location and will automatically select a temperature unit and time zone based on your location. You can overwrite this by adding the following information to your `configuration.yaml`: @@ -47,7 +103,7 @@ homeassistant: ### {% linkable_title Password protecting the web interface %} -The first thing you want to add is a password for the web interface. Use your favourite text editor to open the file `configuration.yaml` and add the following to the `http` section: +The first thing you will want to add is a password for the web interface. Use your favourite text editor to open `configuration.yaml` and edit the `http` section: ```yaml http: diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index 42225c4f557..12e7ccb7b8d 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -289,15 +289,15 @@ $ python3/pip3 install --upgrade homeassistant If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues. -For additional help, in addition to this site, there are four sources: +In addition to this site, check out these sources for additional help: - - [Forum](https://community.home-assistant.io/) - - [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions. + - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions. + - [Gitter Chat Room](https://gitter.im/balloob/home-assistant) for real-time chat about Home Assistant. - [GitHub Page](https://github.com/balloob/home-assistant/issues) for issue reporting. ### {% linkable_title What's next %} -If you want to have Home Assistant start on boot, autostart instructions can be found [here](/getting-started/autostart/). +If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart/). To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo). diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/getting-started/troubleshooting-configuration.markdown index 5b3420d1462..f21209385c5 100644 --- a/source/getting-started/troubleshooting-configuration.markdown +++ b/source/getting-started/troubleshooting-configuration.markdown @@ -15,49 +15,17 @@ Before we dive into common issues, make sure you know where your configuration d Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log` in the configuration directory. This file is reset on start of Home Assistant. -### {% linkable_title YAML %} - -Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML can be confusing to start with but is really powerful in allowing you to express complex configurations. - -The basics of YAML are block collections and mappings containing key-value pairs. Collections will have each item start with a `-` while mappings will have the format `key: value`. The last value for a key is used in case you specify a duplicate key. -Note that the indentation is an important part of specifying relationships using YAML. - -```yaml -# A collection -- hello -- how -- are -- you - -# Lookup mapping -beer: ice cold # <-- will be ignored because key specified twice -beer: warm -wine: room temperature -water: cold - -# Nesting mappings (note the indentation) -device_tracker: - platform: mqtt - -# Nesting a collection of mappings in a mapping -sensor: - - platform: mqtt - state_topic: sensor/topic - - platform: mqtt - state_topic: sensor2/topic -``` - -Indentation is used to specify which objects are nested under one another. Getting the right indentation can be tricky if you're not using an editor with a fixed width font. Tabs are not allowed to be used for indentation. - - - To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack. - - You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/). - ### {% linkable_title My component does not show up %} When a component does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the `home-assistant.log` file and see if there are any errors related to your component you are trying to set up. #### {% linkable_title Problems with the configuration %} +One of the most common problems with Home Assistant is an invalid `configuration.yaml` file. + + - You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/) or [YAML Lint](http://www.yamllint.com/). + - To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well). + `configuration.yaml` does not allow multiple sections to have the same name. If you want a specific platform to be loaded twice, append a [number or string](/getting-started/devices/#style-2) to the name or nest them using [this style](/getting-started/devices/#style-1). ```yaml @@ -92,7 +60,7 @@ If you are using multiple files for your setup, make sure that the pointers are light: !include devices/lights.yaml sensor: !include devices/sensors.yaml ``` -Contents of `lights.yaml`: +Contents of `lights.yaml` (notice it does not contain `light: `): ```yaml - platform: hyperion diff --git a/source/help/index.markdown b/source/help/index.markdown index c92de072511..740f22d3ec3 100644 --- a/source/help/index.markdown +++ b/source/help/index.markdown @@ -20,7 +20,7 @@ There are various ways to get in touch with the Home Assistant community. It doe ### {% linkable_title Bugs, Feature requests, and alike %} -Have you found an issue in your Home Assistant installation? Please report it in one of the issue trackers. Reporting it there makes it easier to track than in the Mailing list and ensures that it gets fixed. +Have you found an issue in your Home Assistant installation? Please report it in one of the issue trackers. Reporting it there makes it easy to track and ensures that it gets fixed. - [Issue tracker Home Assistant](https://github.com/balloob/home-assistant/issues) - [Issue tracker home-assistant.io](https://github.com/balloob/home-assistant.io/issues) (Website and documentation)