diff --git a/_config.yml b/_config.yml index 873dbd5302b..351647d8582 100644 --- a/_config.yml +++ b/_config.yml @@ -41,6 +41,7 @@ kramdown: entity_output: as_char toc_levels: 1..6 smart_quotes: lsquo,rsquo,ldquo,rdquo + parse_block_html: true enable_coderay: true coderay: @@ -56,7 +57,6 @@ highlighter: rouge gems: - jekyll-time-to-read - octopress-filters - # - octopress-solarized - octopress-codefence - octopress-include-tag diff --git a/source/developers/add_new_platform.markdown b/source/developers/add_new_platform.markdown index fe2c2414f02..d1d3c540046 100644 --- a/source/developers/add_new_platform.markdown +++ b/source/developers/add_new_platform.markdown @@ -23,35 +23,21 @@ If you are planning to add support for a new type of device to an existing compo ### {% linkable_title Interfacing with devices %} -One of the rules for Home Assistant is that platform logic should never interface directly with -devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share -code with the Python community and we can keep the project maintainable. +One of the rules for Home Assistant is that platform logic should never interface directly with devices but use a third-party Python 3 library to do so. This way Home Assistant is able to share code with the Python community and we can keep the project maintainable. -Platforms can specify dependencies and requirements the same way as a component does. Please see -[the component page](/developers/creating_components/#dependencies) for more information. +Platforms can specify dependencies and requirements the same way as a component does. Please see [the component page](/developers/creating_components/#dependencies) for more information. ### {% linkable_title Creating Entities %} -Home Assistant will call a function with the following signature to initialize -your new platform. This function must exist in the platform module you create. +Home Assistant will call a function with the following signature to initialize your new platform. This function must exist in the platform module you create. ```python def setup_platform(hass, config, add_devices, discovery_info=None) ``` -In this function, your platform should create the appropriate entities and -register them with the Home Assistant core. Entities are Home Assistant's -representation of lights, switches, sensors, etc. and are derived from the -[Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py). -This abstract class contains logic for integrating most standard features into -your entities, such as visibility, entity IDs, updates, and many more. +In this function, your platform should create the appropriate entities and register them with the Home Assistant core. Entities are Home Assistant's representation of lights, switches, sensors, etc. and are derived from the [Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py). This abstract class contains logic for integrating most standard features into your entities, such as visibility, entity IDs, updates, and many more. -A list of entities can be registered with Home Assistant using the *add_devices* -function that is provided as an input to *setup_platform*. Once entities are -registered with with Home Assistant their updates will be provided to the core -and the core will have control over them. For more information on how Entities -can be customized, take a look at the [Entity Abstract -Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18). +A list of entities can be registered with Home Assistant using the *add_devices* function that is provided as an input to *setup_platform*. Once entities are registered with with Home Assistant their updates will be provided to the core and the core will have control over them. For more information on how Entities can be customized, take a look at the [Entity Abstract Class](https://github.com/balloob/home-assistant/blob/master/homeassistant/helpers/entity.py#L18). ## {% linkable_title Allowing your platform to be discovered %} diff --git a/source/developers/architecture.markdown b/source/developers/architecture.markdown index 99ca5a1f297..974cc312990 100644 --- a/source/developers/architecture.markdown +++ b/source/developers/architecture.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Before we dive into the Home Assistant architecture, it is important to get a clear overview of the home automation landscape as a whole. This will allow us to show how the different parts of Home Assistant fit in the picture. For a more lengthy discussion about what each part in this overview is responsible for, check out our blog. A tl;dr version of the blog: +Before we dive into the Home Assistant architecture, it is important to get a clear overview of the home automation landscape as a whole. This will allow us to show how the different parts of Home Assistant fit in the picture. For a more lengthy discussion about what each part in this overview is responsible for, check out our blog. A tl;dr version of the blog: * Home Control is responsible for collecting information on- and controlling devices. * Home Automation triggers commands based on user configurations. @@ -31,18 +31,18 @@ The Home Assistant core is responsible for Home Control. It has four parts to ma * The **Timer** will send every 1 second a `time_changed` event on the event bus.

- - + + Overview of the Home Assistant core architecture

Home Assistant can be extended by **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for- or trigger events, offer services and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components]({{site_root}}/components/). -We can differentiate between two different types of -components within Home Assistant. +We can differentiate between two different types ofcomponents within Home Assistant. #### {% linkable_title Components that interact with an Internet of Things domain %} + These components will track devices within a specific domain and exist of a core part and platform specific logic. These components make their information available via the State Machine and the Event Bus. The component will also register services in the Service Registry to expose control of the devices. For example, one of the built-in components is the `switch` component. This component is responsible for interaction with different types of switches. @@ -50,35 +50,38 @@ For example, one of the built-in components is the `switch` component. This comp If you are planning to add support for a new platform, please check out the [add new platform section]({{root_url}}/developers/add_new_platform/). #### {% linkable_title Components that respond to events that happen within Home Assistant %} + These components provide small pieces of home automation logic or services that do common tasks within your house. -For example the `device_sun_light_trigger` component tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines: +For example the [`device_sun_light_trigger` component](/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and there are people home. The component uses logic along the following lines: +```plain In the event that device 'Paulus Nexus 5' changes to the 'Home' state: If the sun has set and the lights are not on: Turn on the lights +``` - - +```plain In the event that the combined state of all tracked devices changes to 'Not Home': If the lights are on: Turn off the lights +``` - - +```plain In the event of the sun setting: If the lights are off and the combined state of all tracked device equals 'Home': Turn on the lights +``` -Another example of a home automation component can be found in [`/config/custom_components/example.py`](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py). +An extended example of a home automation component can be found [here](https://github.com/balloob/home-assistant/blob/master/config/custom_components/example.py). ### {% linkable_title The full picture %} When we put all the different pieces of Home Assistant together we see that we match pretty close to the initial sketched home automation overview. The smart home AI is not implemented yet and therefore omitted from the following picture.

- - + + Overview of the full Home Assistant architecture with a couple of loaded components and platforms.

@@ -90,8 +93,8 @@ Component's platform logic uses 3rd party Python libraries to communicate with t Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever `events.fire` or `states.set` is called on the salve it will forward it to the master. The master will replicate all events and changed states to its slaves.

- - + + Overview of the Home Assistant architecture for multiple devices.

diff --git a/source/developers/creating_components.markdown b/source/developers/creating_components.markdown index 438ad20ac75..57ce55700ae 100644 --- a/source/developers/creating_components.markdown +++ b/source/developers/creating_components.markdown @@ -26,10 +26,10 @@ example: ## {% linkable_title Loading components %} -A component will be loaded on start if a section (ie. `[light]`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths: +A component will be loaded on start if a section (ie. `light:`) for it exists in the config file. A component can also be loaded if another component is loaded that depends on it. When loading a component Home Assistant will check the following paths: - * <config directory>/custom_components/<component name> - * homeassistant/components/<component name> (built-in components) + * `/custom_components/` + * `homeassistant/components/` (built-in components) Once loaded, a component will only be setup if all dependencies can be loaded and are able to setup. Keep an eye on the logs to see if your component could be loaded and initialized. @@ -47,28 +47,27 @@ Home Assistant allows components and platforms to specify their dependencies and Dependencies are other Home Assistant components that should be setup before the platform is loaded. An example is the MQTT sensor component, which requires an active connection to an MQTT broker. If Home Assistant is unable to load and setup the MQTT component, it will not setup the MQTT sensor component. -Requirements are Python libraries that you would normally install using `pip`. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus `REQUIREMENTS = ['pychromecast==0.6.12']`. If Home Assistant is unable to install the package or verify it is installed, the component will fail to -load. +Requirements are Python libraries that you would normally install using `pip`. Each entry in a requirement list is a pip compatible string. For example, the media player Cast platform depends on the Python package PyChromecast thus `REQUIREMENTS = ['pychromecast==0.6.12']`. If Home Assistant is unable to install the package or verify it is installed, the component will fail to load. ## {% linkable_title Initializing components %} -After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. The following parameters are passed in: +After loading, the bootstrapper will call `setup(hass, config)` method on the component to initialize it. -| Parameter | Description | -| --------- | ----------- | -| hass | The Home Assistant object. Call its methods to track time, register services, listen for events or track states: [Overview of available methods.](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L55) | -| config | A dict containing the configuration. The keys of the config-dict are component names and the value is another dict with the component configuration.: [Details](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687) | +### {% linkable_title `hass`: the Home Assistant instance %} -### {% linkable_title Guidance on using the Home Assistant object %} -The Home Assistant object contains three objects to help you interact with the system. +The Home Assistant instace contains three objects to help you interact with the system. | Object | Description | | ------ | ----------- | -| hass.states | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434). | -| hass.bus | This is the EventBus. It allows you to trigger and listen for events.
[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229). | -| hass.services | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568). | +| `hass.config` | This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. [Details](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L687) +| `hass.states` | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L434). | +| `hass.bus` | This is the EventBus. It allows you to trigger and listen for events.
[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L229). | +| `hass.services` | This is the ServiceRegistry. It allows you to register services.
[See available methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/core.py#L568). | + +### {% linkable_title `config`: User given configuration. %} + +The `config` paramter is a dictionary containing the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration. -### {% linkable_title Example on using the configuration parameter %} If your configuration file contains the following lines: ```yaml @@ -77,3 +76,7 @@ example: ``` Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`. + +## {% linkable_title Responding to events %} + +Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in [helper methods](https://github.com/balloob/home-assistant/blob/dev/homeassistant/helpers/event.py). Examples are `track_state_change`, `track_point_in_time`, `track_time_change`. \ No newline at end of file diff --git a/source/developers/frontend.markdown b/source/developers/frontend.markdown index 64f7a696c1e..d6c0e70b500 100644 --- a/source/developers/frontend.markdown +++ b/source/developers/frontend.markdown @@ -11,9 +11,9 @@ footer: true Home Assistant uses [Polymer](https://www.polymer-project.org/) for the UI and [NuclearJS](http://optimizely.github.io/nuclear-js/) for all data management. - * Polymer allows building encapsulated custom HTML elements. + * Polymer allows building encapsulated custom HTML elements. [Home-Assistant-Polymer source code on GitHub.](https://github.com/balloob/home-assistant-polymer) - * NuclearJS is a reactive flux built with ImmutableJS data structures. + * NuclearJS is a reactive flux built with ImmutableJS data structures. [Home-Assistant-JS source code on GitHub.](https://github.com/balloob/home-assistant-js)

@@ -28,39 +28,29 @@ http: development: 1 ``` -Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend -repository is not cloned by default. You will have to trigger this manually by running from the -command line: +Next step is to get the frontend code. When you clone the Home Assistant repository, the frontend repository is not cloned by default. You will have to do this by running from the command line: ```bash -git submodule update --init +$ git submodule update --init ``` -After checking out the frontend code, you will have to install the frontend dependencies. Firing off -a build of the frontend by running `script/build_frontend` will ensure they get installed. +After checking out the frontend code, you will have to install the frontend dependencies. Firing off a build of the frontend by running `script/build_frontend` will ensure they get installed. -Once this is done, you can start editting the webcomponents in the folder -`homeassistant/components/frontend/www_static/home-assistant-polymer/src`. To see the changes you've -made, simply refresh your browser. +Once this is done, you can start editting the webcomponents in the folder `homeassistant/components/frontend/www_static/home-assistant-polymer/src`. To see the changes you've made, simply refresh your browser. ## {% linkable_title Enabling JavaScript backend development %} -Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with -the server is done by `home-assistant-js` leveraging NuclearJS. To enable JavaScript development: +Polymer is only providing a UI toolkit for Home Assistant. All data management and interaction with the server is done by `home-assistant-js` leveraging NuclearJS. To enable JavaScript development: ```bash -cd homeassistant/components/frontend/www_static/home-assistant-polymer/ -npm run setup_js_dev -npm run js_dev +$ cd homeassistant/components/frontend/www_static/home-assistant-polymer/ +$ npm run setup_js_dev +$ npm run js_dev ``` -`npm run js_dev` will start the process that will ensure that your latest changes to the JavaScript -files will be loaded when you refresh the page. This command has to be always running while working -on home-assistant-js. +`npm run js_dev` will start the process that will ensure that your latest changes to the JavaScript files will be loaded when you refresh the page. This command has to be always running while working on home-assistant-js. -After your changes have been accepted into the `home-assistant-js` repository, we'll have to update -Home Assistant Polymer to use the latest version. This can be done by updating `package.json`. Look -for the line that contains `home-assistant-js` and update the SHA to the SHA of your commit. +After your changes have been accepted into the `home-assistant-js` repository, we'll have to update Home Assistant Polymer to use the latest version. This can be done by updating `package.json`. Look for the line that contains `home-assistant-js` and update the SHA to the SHA of your commit. # {% linkable_title Building the Polymer frontend %} @@ -78,21 +68,18 @@ Building a new version of the frontend is as simple as running `script/build_fro

Polymer build architecture diagram +Polymer build architecture diagram

# {% linkable_title Adding state cards %} The main interface of Home Assistant is a list of the current entities and their states. For each entity in the system, a state card will be rendered. State cards will show a state badge, the name of the entity, when the state has last changed and the current state or a control to interact with it. - - -Some domains will be filtered out of the main view and are available through separate menu options. Examples are `group`, `script`, `scene`. +![Cards in the frontend](/images/frontend/frontend-cards.png) The different card types can be found [here](https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary). -Adding a custom card type can be done with a few simple steps. For this example we will add a new -state card for the domain `camera`: -_(All files in this example link to their source-code)_ +Adding a custom card type can be done with a few simple steps. For this example we will add a new state card for the domain `camera`: _(All files in this example link to their source-code)_ 1. Add `'camera'` to the array `DOMAINS_WITH_CARD` in the file [`/util/state-card-type.js`](https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-card-type.js#L3-L4). 2. Create the files `state-card-camera.html` and `state-card-camera.js` in the folder [`/state-summary/`](https://github.com/balloob/home-assistant-polymer/tree/master/src/state-summary). @@ -108,7 +95,7 @@ Whenever the user taps or clicks on one of the cards, a more info dialog will sh The more info dialog for a light allows the user to control the color and the brightness.

-The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain `camera`: +The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain `camera`: _(All files in this example link to their source-code)_ 1. Add `'camera'` to the array `DOMAINS_WITH_MORE_INFO` in the file [`util/state-more-info-type.js`](https://github.com/balloob/home-assistant-polymer/blob/master/src/util/state-more-info-type.js#L1). diff --git a/source/getting-started/autostart.html b/source/getting-started/autostart.html deleted file mode 100644 index 5a2e6412fd9..00000000000 --- a/source/getting-started/autostart.html +++ /dev/null @@ -1,116 +0,0 @@ ---- -layout: page -title: "Launch Home Assistant on boot" -description: "Instructions how to setup Home Assistant to launch on boot on various platforms.." -date: 2015-9-1 22:57 -sidebar: false -comments: false -sharing: true -footer: true ---- - -
- - - - - - - - -
-

Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command:

- -
$ ps -p 1 -o comm=
- -

If the preceding command returns the string init, you are likely using Upstart.

- -

Upstart will launch init scripts that are located in the directory /etc/init.d/. A sample init script for systems using Upstart is maintained by this project.

- -

To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands:

- -
$ sudo service hass-daemon start
-$ sudo service hass-daemon stop
-
- -

When running Home Assistant with this script, the configuration directory will be located at /var/opt/homeassistant. This directory will contain a verbose log rather than simply an error log.

- -

When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document.

-
- - - -
-

Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command:

- -
$ ps -p 1 -o comm=
- -

If the preceding command returns the string systemd, you are likely using systemd.

- -

If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd.

- -
$ su -c 'cat <<EOF >> /lib/systemd/system/home-assistant.service
-[Unit]
-Description=Home Assistant
-After=network.target
-
-[Service]
-Type=simple
-ExecStart=/usr/local/bin/hass
-# Next line is to run as a specific user
-# for Raspberry Pi users, keep it at 'pi'
-User=pi
-
-[Install]
-WantedBy=multi-user.target
-EOF'
-
- -

You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that.

- -
$ sudo systemctl --system daemon-reload
-$ sudo systemctl enable home-assistant
-$ sudo systemctl start home-assistant
-
- -

If everything went well, sudo systemctl start home-assistant should give you a positive feedback.

- -
$ sudo systemctl status home-assistant -l
-● home-assistant.service - Home Assistant
-   Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled)
-   Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago
- Main PID: 8557 (python3.4)
-   CGroup: /system.slice/home-assistant.service
-           └─8557 /usr/bin/python3.4 -m homeassistant
-[...]
-
- -

To get Home Assistant's logging output, simple use journalctl.

- -
$ sudo journalctl -f -u home-assistant
- -
- -
-

Setting up Home Assistant to run as a background service is simple. OS X will -start it on boot and make sure it's always running.

- -

To get Home Assistant installed as a background service, run:

- -
$ hass --install-osx
-
-Home Assistant has been installed.         Open it here: http://localhost:8123
-
- -

Home Assistant will log to ~/Library/Logs/homeassistant.log

- -

To uninstall the service, run:

- -
$ hass --uninstall-osx
-
-Home Assistant has been uninstalled.
-
- -
- -

« Back to Getting Started

diff --git a/source/getting-started/autostart.markdown b/source/getting-started/autostart.markdown new file mode 100644 index 00000000000..6aa3e3b2e7e --- /dev/null +++ b/source/getting-started/autostart.markdown @@ -0,0 +1,135 @@ +--- +layout: page +title: "Launch Home Assistant on boot" +description: "Instructions how to setup Home Assistant to launch on boot on various platforms.." +date: 2015-9-1 22:57 +sidebar: false +comments: false +sharing: true +footer: true +--- + +
+ + + + + + + +
+Many linux distributions use the Upstart system (or similar) for managing daemons. Typically, systems based on Debian 7 or previous use Upstart. This includes Ubuntu releases before 15.04 and all current Raspian releases. If you are unsure if your system is using Upstart, you may check with the following command: + +```bash +$ ps -p 1 -o comm= +``` + +If the preceding command returns the string `init`, you are likely using Upstart. + +Upstart will launch init scripts that are located in the directory `/etc/init.d/`. A sample init script for systems using Upstart is maintained by this project. + +To install this script, download it, tweak it to you liking, and install it by following the directions in the header. This script will setup Home Assistant to run when the system boots. To start/stop Home Assistant manually, issue the following commands: + + +```bash +$ sudo service hass-daemon start +$ sudo service hass-daemon stop +``` + +When running Home Assistant with this script, the configuration directory will be located at `/var/opt/homeassistant`. This directory will contain a verbose log rather than simply an error log. + +When running daemons, it is good practice to have the daemon run under its own user name rather than the default user's name. Instructions for setting this up are outside the scope of this document. +
+ +
+Newer linux distributions are trending towards using systemd for managing daemons. Typically, systems based on Fedora or Debian 8 or later use systemd. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using systemd, you may check with the following command: + + +```bash +$ ps -p 1 -o comm= +``` + +If the preceding command returns the string `systemd`, you are likely using systemd. + +If you want Home Assistant to be launched automatically, an extra step is needed to setup systemd. You need a service file to control Home Assistant with systemd. + + +```bash +$ su -c 'cat <> /lib/systemd/system/home-assistant.service +[Unit] +Description=Home Assistant +After=network.target + +[Service] +Type=simple +ExecStart=/usr/local/bin/hass +# Next line is to run as a specific user +# for Raspberry Pi users, keep it at 'pi' +User=pi + +[Install] +WantedBy=multi-user.target +EOF' + +``` + +You need to reload systemd to make the daemon aware of the new configuration. Enable and launch Home Assistant after that. + + +```bash +$ sudo systemctl --system daemon-reload +$ sudo systemctl enable home-assistant +$ sudo systemctl start home-assistant + +``` + +If everything went well, `sudo systemctl start home-assistant` should give you a positive feedback. + + +```bash +$ sudo systemctl status home-assistant -l +● home-assistant.service - Home Assistant + Loaded: loaded (/usr/lib/systemd/system/home-assistant.service; disabled; vendor preset: disabled) + Active: active (running) since Thu 2015-06-25 23:38:37 CEST; 3min 13s ago + Main PID: 8557 (python3.4) + CGroup: /system.slice/home-assistant.service + └─8557 /usr/bin/python3.4 -m homeassistant +[...] + +``` + +To get Home Assistant's logging output, simple use `journalctl`. + + +```bash +$ sudo journalctl -f -u home-assistant +``` + +
+ +
+Setting up Home Assistant to run as a background service is simple. OS X will start it on boot and make sure it's always running. + +To get Home Assistant installed as a background service, run: + + +```bash +$ hass --install-osx + +Home Assistant has been installed. Open it here: http://localhost:8123 +``` + +Home Assistant will log to `~/Library/Logs/homeassistant.log` + +To uninstall the service, run: + +```bash +$ hass --uninstall-osx + +Home Assistant has been uninstalled. +``` + +
+
+ +### [« Back to Getting Started](/getting-started/) diff --git a/source/getting-started/index.html b/source/getting-started/index.html deleted file mode 100644 index d796cc8ba2d..00000000000 --- a/source/getting-started/index.html +++ /dev/null @@ -1,89 +0,0 @@ ---- -layout: page -title: "Getting Started" -description: "Step by step guide to get started with Home Assistant." -date: 2014-12-18 22:57 -sidebar: false -comments: false -sharing: true -footer: true ---- - -
- - - - - - - - -
-

Installing and running Home Assistant on your local machine is easy. Make sure you have Python 3.4 installed and execute the following code in a console:

- -
$ pip3 install homeassistant
-$ hass --open-ui
-
- -

Running these commands will:

-
    -
  1. Install Home Assistant
    2. -
  2. Launch Home Assistant and serve web interface on -http://localhost:8123
    3. -
-
- - -
- -

Installation with Docker is straightforward. Adjust the following command so that /path/to/your/config/ points at the folder where you want to store your config and run it:

- -
$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant
-
- -

This will launch Home Assistant and serve its web interface from port 8123 on your Docker host.

- -

-When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace -v /etc/localtime:/etc/localtime:ro with -e "TZ=America/Los_Angeles" (replacing America/Los_Angeles with your timezone) -

- -
- - -
- -

Home Assistant requires the Raspberry Pi to run Raspbian Jessie. This version has been released on September 24, 2015 and comes by default with Python 3.4 which is required for Home Assistant.

- -

Execute the following code in a console:

- -
$ pip3 install homeassistant
-$ hass --open-ui
-
- -

Running these commands will:

-
    -
  1. Install Home Assistant
    2. -
  2. Launch Home Assistant and serve web interface on http://localhost:8123
    3. -
- -
- -

Troubleshooting

- -

If you run into any issues, please see the troubleshooting page. It contains solutions to many of the more commonly encountered issues.

- -

For additional help, in addition to this site, there are three sources:

-
    -
  1. Gitter Chatroom for general Home Assistant discussions and questions.
    2. -
  2. Development Mailing List for development related questions and discussing new features.
    3. -
  3. GitHub Page for issue reporting.
    4. -
- -

What's next

-

If you want to have Home Assistant start on boot, autostart instructions can be found here.

- -

To see what Home Assistant can do, launch demo mode: hass --demo-mode

- -

To update Home Assistant to the latest release: pip3 install --upgrade homeassistant

- -

Next step: Configuring Home Assistant »

diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown new file mode 100644 index 00000000000..07efdba7857 --- /dev/null +++ b/source/getting-started/index.markdown @@ -0,0 +1,89 @@ +--- +layout: page +title: "Getting Started" +description: "Step by step guide to get started with Home Assistant." +date: 2014-12-18 22:57 +sidebar: false +comments: false +sharing: true +footer: true +--- + +
+ + + + + + + +
+Installing and running Home Assistant on your local machine is easy. Make sure you have [Python 3.4](https://www.python.org/downloads/) installed and execute the following code in a console: + +```bash +$ pip3 install homeassistant +$ hass --open-ui +``` + +Running these commands will: + + - Install Home Assistant + - Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123) + +
+ + +
+ +Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/` points at the folder where you want to store your config and run it: + +```bash +$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host balloob/home-assistant +``` + +This will launch Home Assistant and serve its web interface from port 8123 on your Docker host. + +

+When using boot2docker on OS X you are unable to map the local time to your Docker container. Replace `-v /etc/localtime:/etc/localtime:ro` with `-e "TZ=America/Los_Angeles"` (replacing America/Los_Angeles with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) +

+ +
+ + +
+ +Home Assistant requires the Raspberry Pi to run [Raspbian Jessie](https://www.raspberrypi.org/downloads/raspbian/). This version has been released on September 24, 2015 and comes by default with Python 3.4 which is required for Home Assistant. + +Execute the following code in a console: + +```bash +$ pip3 install homeassistant +$ hass --open-ui +``` + +Running these commands will: + + - Install Home Assistant + - Launch Home Assistant and serve web interface on [http://localhost:8123](http://localhost:8123) + +
+
+ +### {% linkable_title Troubleshooting %} + +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 three sources: + + - [Gitter Chatroom](https://gitter.im/balloob/home-assistant) for general Home Assistant discussions and questions. + - [Development Mailing List](https://groups.google.com/forum/#!forum/home-assistant-dev) for development related questions and discussing new features. + - [GitHub Page](https://github.com/balloob/home-assistant/issues) for issue reporting. + +### What's next +If you want to have Home Assistant start on boot, [autostart instructions](/getting-started/autostart/) can be found here. + +To see what Home Assistant can do, launch demo mode: `hass --demo-mode` + +To update Home Assistant to the latest release: `pip3 install --upgrade homeassistant` + +### [Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/getting-started/troubleshooting-configuration.markdown index a434cd86964..69e5de8b6cf 100644 --- a/source/getting-started/troubleshooting-configuration.markdown +++ b/source/getting-started/troubleshooting-configuration.markdown @@ -9,23 +9,17 @@ sharing: true footer: true --- -It can happen that you run into trouble while configuring Home Assistant. A component is not -showing up or is acting weird. This page will discuss a few of the most common problems. +It can happen that you run into trouble while configuring Home Assistant. A component is not showing up or is acting weird. This page will discuss a few of the most common problems. -Before we dive into common issues, make sure you know where your configuration directory is. -Home Assistant will print out the configuration directory it is using when starting up. +Before we dive into common issues, make sure you know where your configuration directory is. Home Assistant will print out the configuration directory it is using when starting up. -Whenever a component or configuration option results in a warning, it will be stored in -`home-assistant.log`. This file is reset on start of Home Assistant. +Whenever a component or configuration option results in a warning, it will be stored in `home-assistant.log`. This file is reset on start of Home Assistant. ### {% linkable_title YAML %} -Home Assistant uses the YAML syntax for configuration. YAML can be confusing at start but it is really -powerful in allowing you to express complex configurations. +Home Assistant uses the YAML syntax for configuration. YAML can be confusing at start but it is really powerful in allowing you to express complex configurations. -The basics of YAML are lists and lookup tables containing key-value pairs. Lists will have each item -start with a `-` while lookup tables will have the format `key: value`. The last value for a key is -used in case you specify a duplicate key. +The basics of YAML are lists and lookup tables containing key-value pairs. Lists will have each item start with a `-` while lookup tables will have the format `key: value`. The last value for a key is used in case you specify a duplicate key. ```yaml # A list @@ -52,26 +46,20 @@ sensor: state_topic: sensor2/topic ``` -Indentation is used to specify which objects are nested under one anohter. Getting the right indentation -can be tricky if you're not using an editor with a fixed width font. You can test your -configuration using [this online YAML parser](http://yaml-online-parser.appspot.com/). +Indentation is used to specify which objects are nested under one anohter. Getting the right indentation can be tricky if you're not using an editor with a fixed width font. You can test your configuration using [this online YAML parser](http://yaml-online-parser.appspot.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. +To learn more about the quirks of YAML, read [YAML IDIOSYNCRASIES](https://docs.saltstack.com/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack. ### {% 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. -**Problems with the configuration
** -`configuration.yaml` does not allow multiple sections to have the same name. If you want a - specific component to be loaded twice, append a number to the name. +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. + +**Problems with the configuration** +`configuration.yaml` does not allow multiple sections to have the same name. If you want a specific component to be loaded twice, append a number to the name. ```yaml sensor: - platform: mqtt + platform: forecast […] sensor 2: @@ -79,27 +67,18 @@ sensor 2: […] ``` -Another common problem is that a required configuration setting is missing. If this is the -case, the component will report this to `home-assistant.log`. You can have a look at -[the component page](/components/) for instructions how to setup the components. +Another common problem is that a required configuration setting is missing. If this is the case, the component will report this to `home-assistant.log`. You can have a look at [the component page](/components/) for instructions how to setup the components. -If you find any errors or want to expand the documentation, please -[let us know](https://github.com/balloob/home-assistant.io/issues). +If you find any errors or want to expand the documentation, please [let us know](https://github.com/balloob/home-assistant.io/issues). -**Problems with dependencies
** -Almost all components have external dependencies to communicate with your devices and services. -Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it -should show up in `home-assistant.log`. +**Problems with dependencies** +Almost all components have external dependencies to communicate with your devices and services. Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it should show up in `home-assistant.log`. -First step is trying to restart Home Assistant and see if the problem persists. If it does, please -[report it](https://github.com/balloob/home-assistant/issues) so we can investigate what is going on. +First step is trying to restart Home Assistant and see if the problem persists. If it does, please [report it](https://github.com/balloob/home-assistant/issues) so we can investigate what is going on. -**Problems with components
** -It can happen that some components either do not work right away or stop working after Home -Assistant has been running for a while. If this happens to you, please -[report it](https://github.com/balloob/home-assistant/issues) so that we can have a look. +**Problems with components** +It can happen that some components either do not work right away or stop working after Home Assistant has been running for a while. If this happens to you, please [report it](https://github.com/balloob/home-assistant/issues) so that we can have a look.

-Whenever you report an issue, be aware that we are a group of volunteers that do not have access to -every single device in the world nor unlimited time to fix every problem out there. +Whenever you report an issue, be aware that we are a group of volunteers that do not have access to every single device in the world nor unlimited time to fix every problem out there.