-Diagram showing interaction between components and the Home Assistant core
-
-
-Diagram showing interaction between components and the Home Assistant core
-
There are two types of components within Home Assistant: components that interact with an Internet of Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type!
-#### Components that interact with an Internet-of-Things domain
+## Components that interact with an Internet-of-Things domain
These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices.
-For example, the built-in [`switch` component](/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
+For example, the built-in [`switch` component](https://www.home-assistant.io/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
-If you want to add support for a new platform, check out the [add new platform section](/developers/add_new_platform/).
+If you want to add support for a new platform, check out the [add new platform section](creating_platform_index.md).
-#### Components that respond to events that happen within Home Assistant
+## Components that respond to events that happen within Home Assistant
These components provide small pieces of home automation logic or involve services that do common tasks within your house.
-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 people are home. The component uses logic like this:
+For example, the [`device_sun_light_trigger` component](https://www.home-assistant.io/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 people are home. The component uses logic like this:
```text
In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
@@ -43,17 +40,13 @@ In the event of the sun setting:
Turn on the lights
```
-Look [here](/python_component_automation/) for a comprehensive example of a home automation component.
-
-### The full picture
+## The full picture
When we put all the different pieces of Home Assistant together, it's a close match for the initial home automation overview sketch. The smart home AI has not been implemented yet, so it's not included in this picture.
-
-
- 
-
- Overview of the full Home Assistant architecture with a couple of loaded components and platforms
-
The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.
diff --git a/docs/architecture.md b/docs/architecture_index.md
similarity index 62%
rename from docs/architecture.md
rename to docs/architecture_index.md
index 24750290..c441b6f8 100644
--- a/docs/architecture.md
+++ b/docs/architecture_index.md
@@ -1,22 +1,20 @@
---
title: "Architecture"
+sidebar_label: "Introduction"
---
Before we dive into the Home Assistant architecture, let's get a clear overview of the home automation landscape as a whole. This way, we can show how the different parts of Home Assistant fit into the picture.
-For more information about each part in this overview, check out our blog. Here's the tl;dr version of the blog:
+For more information about each part in this overview, check out our blog. Here's the tl;dr version of the blog:
* Home Control is responsible for collecting information and controlling devices.
* Home Automation triggers commands based on user configurations.
* Smart Home triggers commands based on previous behavior.
-
-
- 
-
- Overview of the home automation landscape
-
The Home Assistant core is responsible for Home Control. Home Assistant contains four parts which make this possible:
@@ -25,9 +23,7 @@ The Home Assistant core is responsible for Home Control. Home Assistant contains
* **Service Registry**: listens on the event bus for `call_service` events and allows other code to register services.
* **Timer**: sends a `time_changed` event every 1 second on the event bus.
-
-
- 
-
- Overview of the Home Assistant core architecture
-
diff --git a/docs/building_integrations.md b/docs/building_integrations.md
new file mode 100644
index 00000000..339e9826
--- /dev/null
+++ b/docs/building_integrations.md
@@ -0,0 +1,5 @@
+---
+title: Building Integrations
+---
+
+Intro on how to build integrations.
diff --git a/docs/component_loading.md b/docs/component_loading.md
deleted file mode 100644
index d2808f1b..00000000
--- a/docs/component_loading.md
+++ /dev/null
@@ -1,18 +0,0 @@
----
-title: "Loading your 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:
-
- * `
-You can override a built-in component by having a component with the same name in your config/custom_components folder. If the built-in component is inside a subfolder, take care to place your customization in a folder with the same name in config/custom_components/*folder*. Note that overriding built-in components is not recommended and will probably break things!
-
-Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/.
-
-Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! -
+> Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! ### 1. Requirements diff --git a/docs/component_deps_and_reqs.md b/docs/creating_component_deps_and_reqs.md similarity index 79% rename from docs/component_deps_and_reqs.md rename to docs/creating_component_deps_and_reqs.md index ec864969..2a46c9df 100644 --- a/docs/component_deps_and_reqs.md +++ b/docs/creating_component_deps_and_reqs.md @@ -14,7 +14,7 @@ DEPENDENCIES = ['mqtt'] ## Requirements -Requirements are Python libraries or modules that you would normally install using `pip` for your component. Home Assistant will try to install the requirements into the `deps` subdirectory of the Home Assistant [configuration directory](/docs/configuration/) if you are not using a `venv` or in something like `path/to/venv/lib/python3.6/site-packages` if you running in a virtual environment. This will make sure that all requirements are present at startup. If steps fails like missing packages for the compilation of a module or other install errors, the component will fail to load. +Requirements are Python libraries or modules that you would normally install using `pip` for your component. Home Assistant will try to install the requirements into the `deps` subdirectory of the Home Assistant [configuration directory](https://www.home-assistant.io/docs/configuration/) if you are not using a `venv` or in something like `path/to/venv/lib/python3.6/site-packages` if you running in a virtual environment. This will make sure that all requirements are present at startup. If steps fails like missing packages for the compilation of a module or other install errors, the component will fail to load. Requirements is a list of strings. Each entry is a `pip` compatible string. For example, the media player Cast platform depends on the Python package PyChromecast v0.6.12: diff --git a/docs/component_discovery.md b/docs/creating_component_discovery.md similarity index 96% rename from docs/component_discovery.md rename to docs/creating_component_discovery.md index 165158fb..a374ab40 100644 --- a/docs/component_discovery.md +++ b/docs/creating_component_discovery.md @@ -2,9 +2,7 @@ title: "Component Discovery" --- --This option is only available for built-in components. -
+> This option is only available for built-in components. Home Assistant has a discovery service running in the background to discover new devices. Whenever a new device is discovered, a `SERVICE_DISCOVERED` event will be fired with the found service and the information. The `discovery` component has some knowledge about which components handle which type of services and will ensure those are loaded and listening before firing the `SERVICE_DISCOVERED` event. diff --git a/docs/component_events.md b/docs/creating_component_events.md similarity index 100% rename from docs/component_events.md rename to docs/creating_component_events.md diff --git a/docs/component_generic_discovery.md b/docs/creating_component_generic_discovery.md similarity index 100% rename from docs/component_generic_discovery.md rename to docs/creating_component_generic_discovery.md diff --git a/docs/creating_components.md b/docs/creating_component_index.md similarity index 78% rename from docs/creating_components.md rename to docs/creating_component_index.md index 31724c4c..fbba2f10 100644 --- a/docs/creating_components.md +++ b/docs/creating_component_index.md @@ -1,5 +1,6 @@ --- title: "Creating components" +sidebar_label: "Introduction" --- Alright, you're ready to make your first component. AWESOME. Don't worry, we've tried hard to keep it as easy as possible. @@ -16,5 +17,3 @@ def setup(hass, config): return True ``` - -For more examples, see the [Custom Python Component Examples](/cookbook/#custom-python-component-examples) on our examples page. diff --git a/docs/creating_component_loading.md b/docs/creating_component_loading.md new file mode 100644 index 00000000..c7cf29ad --- /dev/null +++ b/docs/creating_component_loading.md @@ -0,0 +1,14 @@ +--- +title: "Loading your 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: + + * `config/custom_components folder. If the built-in component is inside a subfolder, take care to place your customization in a folder with the same name in config/custom_components/*folder*. Note that overriding built-in components is not recommended and will probably break things!
+
+> Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the config folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: python3 homeassistant --config /YOUR/CONFIG/PATH/.
diff --git a/docs/component_states.md b/docs/creating_component_states.md
similarity index 100%
rename from docs/component_states.md
rename to docs/creating_component_states.md
diff --git a/docs/code_review_platform.md b/docs/creating_platform_code_review.md
similarity index 94%
rename from docs/code_review_platform.md
rename to docs/creating_platform_code_review.md
index acd20e06..d4be58cc 100644
--- a/docs/code_review_platform.md
+++ b/docs/creating_platform_code_review.md
@@ -4,9 +4,7 @@ title: "Checklist for creating a platform"
A checklist of things to do when you're adding a new platform.
--Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! -
+> Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them! ### 1. Requirements diff --git a/docs/platform_example_light.md b/docs/creating_platform_example_light.md similarity index 100% rename from docs/platform_example_light.md rename to docs/creating_platform_example_light.md diff --git a/docs/platform_example_sensor.md b/docs/creating_platform_example_sensor.md similarity index 100% rename from docs/platform_example_sensor.md rename to docs/creating_platform_example_sensor.md diff --git a/docs/add_new_platform.md b/docs/creating_platform_index.md similarity index 90% rename from docs/add_new_platform.md rename to docs/creating_platform_index.md index 6aea200e..937aae99 100644 --- a/docs/add_new_platform.md +++ b/docs/creating_platform_index.md @@ -1,5 +1,6 @@ --- title: "Adding support for a new platform" +sidebar_label: "Introduction" --- Components that interact with devices are called "[Entity Components](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity_component.py)." They are structured in core and platform logic, which means different brands can use the same logic to handle a light. @@ -8,8 +9,8 @@ For example, the built-in `switch` component consists of various platforms in [` If you're planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you want to add: - - [Example sensor platform](/developers/platform_example_sensor): hello world of platforms. - - [Example light platform](/developers/platform_example_light): showing best practices. + - [Example sensor platform](creating_platform_example_sensor.md): hello world of platforms. + - [Example light platform](creating_platform_example_light.md): showing best practices. ### Interfacing with devices @@ -19,7 +20,7 @@ To integrate the third-party library, create an [Entity class](https://github.co ### Requirements and dependencies -Platforms can specify dependencies and requirements [the same way as components](/developers/component_deps_and_reqs): +Platforms can specify dependencies and requirements [the same way as components](creating_component_deps_and_reqs.md): ```python REQUIREMENTS = ['some-package==2.0.0', 'some-other-package==2.5.0'] diff --git a/docs/development_101.md b/docs/development_101.md index f75f1c10..f04585a3 100644 --- a/docs/development_101.md +++ b/docs/development_101.md @@ -2,15 +2,13 @@ title: "Development 101" --- -The goal of development 101 is to get you familiar with the basics of developing for Home Assistant. Before we start, please make sure you familiarize yourself with the [architecture]. +The goal of development 101 is to get you familiar with the basics of developing for Home Assistant. Before we start, please make sure you familiarize yourself with the [architecture](architecture_index.md). To get our code running inside Home Assistant we're going to create a custom component. The first step is to locate your config folder. You can find the path to your config folder by opening the Home Assistant frontend, click on the
. It's the path after the text "Path to configuration.yaml".
Inside your configuration directory create a new folder called `custom_components`. It might be that one already exists, that's fine too. This is the folder that Home Assistant will look at when looking for custom code.
--The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version. -
+> The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version. To verify that everything is working correctly, let's create a small Hello World component. To do so, create a file called `hello_world.py` in your custom components folder. Copy paste the following content to it: @@ -42,9 +40,7 @@ After running `hass`, we should see log entries stating that `hello_world` compo 2018-04-03 21:44:20 INFO (MainThread) [homeassistant.setup] Setting up hello_world ``` -
-
-State card showing that Hello World component is working as intended.
-
diff --git a/docs/development_checklist.md b/docs/development_checklist.md
index 7459e32e..868703d9 100644
--- a/docs/development_checklist.md
+++ b/docs/development_checklist.md
@@ -9,5 +9,5 @@ Before you commit any changes, check your work against these requirements:
- New dependencies are added to `requirements_all.txt` (if applicable), using `script/gen_requirements_all.py`
- The `.coveragerc` file is updated to exclude your platform if there are no tests available or your new code uses a third-party library for communication with the device, service, or sensor
- Documentation is developed for [home-assistant.io](/)
- * It's OK to start with adding a docstring with configuration details (for example, sample entry for `configuration.yaml` file) to the file header. Visit the [website documentation](/developers/documentation/) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.github.io).
+ * It's OK to start with adding a docstring with configuration details (for example, sample entry for `configuration.yaml` file) to the file header. Visit the [website documentation](documentation_index.md) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.github.io).
diff --git a/docs/development_environment.md b/docs/development_environment.md
index 46a92a22..a8f12aaa 100644
--- a/docs/development_environment.md
+++ b/docs/development_environment.md
@@ -4,9 +4,9 @@ title: "Set up Development Environment"
You'll need to set up a development environment if you want to develop a new feature or component for Home Assistant. Read on to learn how to set up.
-### Preparing your environment
+## Preparing your environment
-#### Developing on Linux
+### Developing on Linux
Install the core dependencies.
@@ -20,13 +20,11 @@ In order to run `script/setup` below you will need some more dependencies.
$ sudo apt-get install libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev
```
--Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: `sudo yum install epel-release && sudo yum install python34 python34-devel mysql-devel` -
+> Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: `sudo yum install epel-release && sudo yum install python34 python34-devel mysql-devel` -Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](/developers/frontend/) section to learn more. +Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](frontend_index.md) section to learn more. -#### Developing on Windows +### Developing on Windows If you are using Windows as a development platform, make sure that you have the correct Microsoft [Visual C++ build tools](http://landinghub.visualstudio.com/visual-cpp-build-tools) installed. The installation of the most requirements and validation using `tox` will fail if this is not done correctly. Check the [Windows Compilers](https://wiki.python.org/moin/WindowsCompilers) section on the [Python website](https://www.python.org/) for details. @@ -57,7 +55,7 @@ Also, make sure to install or upgrade the `setuptools` Python package. It contai $ pip install --upgrade setuptools ``` -#### Developing on OS X +### Developing on OS X Install [Homebrew](https://brew.sh/), then use that to install Python 3: @@ -65,7 +63,7 @@ Install [Homebrew](https://brew.sh/), then use that to install Python 3: $ brew install python3 ``` -### Setup Local Repository +## Setup Local Repository Visit the [Home Assistant repository](https://github.com/home-assistant/home-assistant) and click **Fork**. Once forked, setup your local copy of the source using the commands: @@ -76,7 +74,7 @@ $ cd home-assistant $ git remote add upstream https://github.com/home-assistant/home-assistant.git ``` -### Setting up virtual environment +## Setting up virtual environment To isolate your environment from the rest of the system, set up a [`venv`](https://docs.python.org/3/library/venv.html). Within the `home-assistant` directory, create and activate your virtual environment. @@ -96,8 +94,8 @@ Invoke your installation. $ hass ``` -### Logging +## Logging By default logging in home-assistant is tuned for operating in production (set to INFO by default, with some modules set to even less verbose logging levels). -You can use the [logger](/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on. +You can use the [logger](https://www.home-assistant.io/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on. diff --git a/docs/development_events.md b/docs/development_events.md index 98582599..630a8b7f 100644 --- a/docs/development_events.md +++ b/docs/development_events.md @@ -8,7 +8,7 @@ The event system is very flexible. There are no limitations on the event type, a [List of events that Home Assistant fires.][object] -### Firing events +## Firing events To fire an event, you have to interact with the event bus. The event bus is available on the Home Assistant instance as `hass.bus`. @@ -26,7 +26,7 @@ def setup(hass, config): }) ``` -### Listening to events +## Listening to events Most of the times you'll not be firing events but instead listen to events. For example, the state change of an entity is broadcasted as an event. @@ -47,9 +47,9 @@ def setup(hass, config): hass.bus.listen('my_cool_event', handle_event) ``` -#### Helpers +### Helpers Home Assistant comes with a lot of bundled helpers to listen to specific types of event. There are helpers to track a point in time, to track a time interval, a state change or the sun set. [See available methods.][helpers] [helpers]: https://dev-docs.home-assistant.io/en/master/api/helpers.html#module-homeassistant.helpers.event -[object]: /docs/configuration/events/ +[object]: https://www.home-assistant.io/docs/configuration/events/ diff --git a/docs/development_guidelines.md b/docs/development_guidelines.md index cb15a80e..920e5f17 100644 --- a/docs/development_guidelines.md +++ b/docs/development_guidelines.md @@ -49,7 +49,7 @@ https://home-assistant.io/components/light.mqtt/ ### Requirements -Please place [Platform requirements](/developers/code_review_platform/#1-requirements) right after the imports. +Please place [Platform requirements](creating_platform_code_review.md#1-requirements) right after the imports. ```python [...] diff --git a/docs/development.md b/docs/development_index.md similarity index 98% rename from docs/development.md rename to docs/development_index.md index 79238b11..2750aac7 100644 --- a/docs/development.md +++ b/docs/development_index.md @@ -1,5 +1,6 @@ --- title: "Starting with Development" +sidebar_label: Introduction --- Home Assistant is built from the ground up to be easily extensible using components. Home Assistant uses [Python 3](https://www.python.org/) for the backend and [Polymer (Web components)](https://www.polymer-project.org/) for the frontend. diff --git a/docs/development_states.md b/docs/development_states.md index c6ac2c62..b6e78f10 100644 --- a/docs/development_states.md +++ b/docs/development_states.md @@ -8,9 +8,9 @@ Home Assistant keeps track of the states of entities in a state machine. The sta - Each state has a primary attribute that describes the state of the entity. In the case of a light this could be for example "on" and "off". You can store anything you want in the state, as long as it's a string (will be converted if it's not). - You can store more information about an entity by setting attributes. Attributes is a dictionary that can contain any data that you want. The only requirement is that it's JSON serializable, so you're limited to numbers, strings, dictionaries and lists. -[Description of the state object.](/docs/configuration/state_object/) +[Description of the state object.](https://www.home-assistant.io/docs/configuration/state_object/) -### Using states in your component +## Using states in your component This is a simple tutorial/example on how to create and set states. We will do our work in a component called "hello_state". The purpose of this component is to display a given text in the frontend. @@ -40,7 +40,7 @@ def setup(hass, config): 1. In the file header we decided to add some details: A short description and the link to the documentation. 2. We want to do some logging. This means that we import the Python logging module and create an alias. 3. The component name is equal to the domain name. -4. At the moment this component has no dependencies. For detail check [dependencies](/developers/component_deps_and_reqs/#dependencies) section. +4. At the moment this component has no dependencies. For detail check [dependencies](creating_component_deps_and_reqs.md#dependencies) section. 5. The `setup` function will take care of the initialization of our component. The component will only write a log message. Keep in mind for later that you have several options for the severity: @@ -126,8 +126,6 @@ def device_state_attributes(self): return self._attributes ``` --Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead. -
+> Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead. -To get your component included in the Home Assistant releases, follow the steps described in the [Submit your work](/developers/development_submitting/) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request. +To get your component included in the Home Assistant releases, follow the steps described in the [Submit your work](development_submitting.md) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request. diff --git a/docs/development_submitting.md b/docs/development_submitting.md index d8fa3c24..e832fd50 100644 --- a/docs/development_submitting.md +++ b/docs/development_submitting.md @@ -8,11 +8,11 @@ Submit your improvements, fixes, and new features to Home Assistant one at a tim `git checkout -b some-feature` - 2. Make your changes, create a [new platform](/developers/add_new_platform/), develop a [new component](/developers/creating_components/), or fix [issues](https://github.com/home-assistant/home-assistant/issues). + 2. Make your changes, create a [new platform](creating_platform_index.md), develop a [new component](creating_component_index.md), or fix [issues](https://github.com/home-assistant/home-assistant/issues). - 3. [Test your changes](/developers/development_testing/) and check for style violations. + 3. [Test your changes](development_testing.md) and check for style violations. - 4. If everything looks good according to these [musts](/developers/development_checklist/), commit your changes: + 4. If everything looks good according to these [musts](development_checklist.md), commit your changes: `git add .` diff --git a/docs/development_testing.md b/docs/development_testing.md index a211c378..fbca68be 100644 --- a/docs/development_testing.md +++ b/docs/development_testing.md @@ -2,7 +2,7 @@ title: "Testing your code" --- -As states in the [Style guidelines section](/developers/development_guidelines/) all code is checked to verify all unit tests pass and that the code passes the linting tools. Local testing is done using Tox, which has been installed as part of running `script/setup`. To start the tests, simply run it: +As states in the [Style guidelines section](development_guidelines.md) all code is checked to verify all unit tests pass and that the code passes the linting tools. Local testing is done using Tox, which has been installed as part of running `script/setup`. To start the tests, simply run it: ```bash $ tox diff --git a/docs/development_validation.md b/docs/development_validation.md index 3be196da..1050a14e 100644 --- a/docs/development_validation.md +++ b/docs/development_validation.md @@ -14,7 +14,7 @@ Besides [voluptuous](https://pypi.python.org/pypi/voluptuous) default types, man - Time: `time`, `time_zone` - Misc: `template`, `slug`, `temperature_unit`, `latitude`, `longitude`, `isfile`, `sun_event`, `ensure_list`, `port`, `url`, and `icon` -To validate platforms using [MQTT](/components/mqtt/), `valid_subscribe_topic` and `valid_publish_topic` are available. +To validate platforms using [MQTT](https://www.home-assistant.io/components/mqtt/), `valid_subscribe_topic` and `valid_publish_topic` are available. Some things to keep in mind: diff --git a/docs/documentation_create_page.md b/docs/documentation_create_page.md index 005c645b..9ac716bf 100644 --- a/docs/documentation_create_page.md +++ b/docs/documentation_create_page.md @@ -98,9 +98,8 @@ If you are don't escape templates then they will be rendered and appear blank on The direct usage of HTML is supported but not recommended. The note boxes are an exception. ```html -- You need to enable telnet on your router. -
+Hello-It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview. -
--Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding: -`ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine` -
+> It could be necessary that you run `rake generate` prior to `rake preview` for the very first preview. + +> Site generated by `rake` is only available locally. If you are developing on a headless machine use port forwarding: +`ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine` diff --git a/docs/external_api_rest.md b/docs/external_api_rest.md index a77347c7..263cd2ca 100644 --- a/docs/external_api_rest.md +++ b/docs/external_api_rest.md @@ -7,9 +7,9 @@ Home Assistant runs a web server accessible on port 8123. * http://IP_ADDRESS:8123/ is an interface to control Home Assistant. * http://IP_ADDRESS:8123/api/ is a Rest API. -The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](/components/http/)). +The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](https://www.home-assistant.io/components/http/)). -If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file. +If you are not using the [`frontend`](https://www.home-assistant.io/components/frontend/) in your setup then you need to add the [`api` component](https://www.home-assistant.io/components/api/) to your `configuration.yaml` file. There are multiple ways to consume the Home Assistant Rest API. One is with `curl`: @@ -33,9 +33,7 @@ response = get(url, headers=headers) print(response.text) ``` --You can append `?api_password=YOUR_PASSWORD` to any URL to log in automatically. -
+> You can append `?api_password=YOUR_PASSWORD` to any URL to log in automatically. Successful calls will return status code 200 or 201. Other status codes that can return are: @@ -446,13 +444,11 @@ $ curl -X POST \ http://localhost:8123/api/services/mqtt/publish ``` --The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system. -
+> The result will include any states that changed while the service was being executed, even if their change was the result of something else happening in the system. #### POST /api/template -Render a Home Assistant template. [See template docs for more information.](/topics/templating/) +Render a Home Assistant template. [See template docs for more information.](https://www.home-assistant.io/topics/templating/) ```json { @@ -517,7 +513,3 @@ It will return a message if event forwarding was canceled successfully. "message": "Event forwarding cancelled." } ``` - -
-If your client does not support DELETE HTTP requests you can add an optional attribute _METHOD and set its value to DELETE.
-
- 
- 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`:
diff --git a/docs/frontend_creating_custom_panels.md b/docs/frontend_creating_custom_panels.md
index ccf4feaf..c04b660e 100644
--- a/docs/frontend_creating_custom_panels.md
+++ b/docs/frontend_creating_custom_panels.md
@@ -6,7 +6,7 @@ Panels are pages within Home Assistant that show information within Home Assista
Besides components registering panels, users can also register panels using the `panel_custom` component. This allows users to quickly build their own custom interfaces for Home Assistant.
-### Before you get started
+## Before you get started
The Home Assistant user interface is currently served to browsers in modern JavaScript and older JavaScript (ES5). The older version has a wider browser support but that comes at a cost of size, performance and more difficult to get started building panels for authors.
@@ -17,7 +17,7 @@ frontend:
javascript_version: latest
```
-### Building your first panel
+## Building your first panel
Create a file called `hello.html` in your -Some browsers don't support latest ECMAScript standards, these require a separate ES5 compatible file (`extra_html_url_es5`). -
-For more possibilities, see the [Custom UI section](/cookbook/#user-interface) on our Examples page. +> Some browsers don't support latest ECMAScript standards, these require a separate ES5 compatible file (`extra_html_url_es5`). + +For more possibilities, see the [Custom UI section](https://www.home-assistant.io/cookbook/#user-interface) on our Examples page. diff --git a/docs/frontend.md b/docs/frontend_index.md similarity index 91% rename from docs/frontend.md rename to docs/frontend_index.md index c09736fc..e3fea499 100644 --- a/docs/frontend.md +++ b/docs/frontend_index.md @@ -1,18 +1,15 @@ --- title: "Frontend development" +sidebar_label: "Introduction" --- Home Assistant is built on top of the [Polymer](https://www.polymer-project.org/) webcomponents framework. Polymer allows building encapsulated custom HTML elements. [Home-Assistant-Polymer source code on GitHub.][hass-polymer] --Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes. -
+> Do not use development mode in production. Home Assistant uses aggressive caching to improve the mobile experience. This is disabled during development so that you do not have to restart the server in between changes. ## Setting up the environment --All commands below need to be run from inside the home-assistant-polymer repository. -
+> All commands below need to be run from inside the home-assistant-polymer repository. Home Assistant will by default serve the compiled version of the frontend from the hass_frontend Python package. For development you want to work with the unbundled source files which are in the home-assistant-polymer repository. diff --git a/docs/hassio_addon_publishing.md b/docs/hassio_addon_publishing.md index 49be1660..3bfc74e6 100644 --- a/docs/hassio_addon_publishing.md +++ b/docs/hassio_addon_publishing.md @@ -50,8 +50,6 @@ For a local repository: $ docker run --rm --privileged -v ~/.docker:/root/.docker -v /my_addon:/data homeassistant/amd64-builder --all -t /data ``` -
-If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: error creating aufs mount to /var/lib/docker/aufs/mnt/. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: "storage-driver" : "aufs".
-
error creating aufs mount to /var/lib/docker/aufs/mnt/-init: invalid argument . A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: "storage-driver" : "aufs".
[builder]: https://github.com/home-assistant/hassio-build/tree/master/builder
diff --git a/docs/hassio_debugging.md b/docs/hassio_debugging.md
index db7f3250..f39eb581 100644
--- a/docs/hassio_debugging.md
+++ b/docs/hassio_debugging.md
@@ -2,9 +2,7 @@
title: "Debugging Hass.io"
---
--This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is for developers of Hass.io. Do not ask for support if you are using these options. -
+> This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is for developers of Hass.io. Do not ask for support if you are using these options. [SSH add-on]: /addons/ssh/ @@ -22,9 +20,7 @@ Follow steps 1-4 under 'Generating a new SSH key' (The other sections are not ap Step 3 in the link above, shows the path to the private key file `id_rsa` for your chosen operating system. Your public key, `id_rsa.pub`, is saved in the same folder. Next, select all text from text box "Public key for pasting into OpenSSH authorized_keys file" and save it to the root of your SD card as `authorized_keys`. --Make sure when you are copying the public key to the root of the /resin-boot partition of the SD card that you rename the file correctly to `authorized_keys` with no `.pub` file extension. -
+> Make sure when you are copying the public key to the root of the /resin-boot partition of the SD card that you rename the file correctly to `authorized_keys` with no `.pub` file extension. You should then be able to SSH into your Hass.io device. On mac/linux, use: ``` diff --git a/docs/intent_index.md b/docs/intent_index.md index ba1ee981..29933464 100644 --- a/docs/intent_index.md +++ b/docs/intent_index.md @@ -1,13 +1,17 @@ --- title: "Intents" +sidebar_label: "Introduction" --- An intent is a description of a user's intention. Intents are generated by user actions, like asking Amazon Echo to turn on a light. -
-
-Architectural overview of intents in Home Assistant
-
+
+
Intents are fired by components that receive them from external sources/services. Conversation, Alexa, API.ai and Snips are currently sourcing intents.
diff --git a/docs/internationalization_translation.md b/docs/internationalization_translation.md
index 6371ef39..eb422489 100644
--- a/docs/internationalization_translation.md
+++ b/docs/internationalization_translation.md
@@ -10,9 +10,7 @@ Translations for Home Assistant are managed through Lokalise, an online translat
For more information about the translation workflow, please see the [Lokalise translation workflow documents](https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators).
--The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon. -
+> The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon. ## Translation placeholders @@ -33,9 +31,7 @@ English Name: German Native Name: Deutsch ``` --Region specific translations (`en-US`, `fr-CA`) will only be included if translations for that region need to differ from the base language translation. -
+> Region specific translations (`en-US`, `fr-CA`) will only be included if translations for that region need to differ from the base language translation. ### Maintainer steps to add a new language 1. Language tags have to follow [BCP 47](https://tools.ietf.org/html/bcp47). A list of most language tags can be found here: [IANA sutbtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry). Examples: `fr`, `fr-CA`, `zh-Hans`. Only include the country code if country specific overrides are being included, and the base language is already translated. diff --git a/website/blog-examples-from-docusaurus/2016-03-11-blog-post.md b/website/blog-examples-from-docusaurus/2016-03-11-blog-post.md deleted file mode 100755 index cf2ba296..00000000 --- a/website/blog-examples-from-docusaurus/2016-03-11-blog-post.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Blog Title -author: Blog Author -authorURL: http://twitter.com/ -authorFBID: 100002976521003 ---- - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus elementum massa eget nulla aliquet sagittis. Proin odio tortor, vulputate ut odio in, ultrices ultricies augue. Cras ornare ultrices lorem malesuada iaculis. Etiam sit amet libero tempor, pulvinar mauris sed, sollicitudin sapien. - - - -Mauris vestibulum ullamcorper nibh, ut semper purus pulvinar ut. Donec volutpat orci sit amet mauris malesuada, non pulvinar augue aliquam. Vestibulum ultricies at urna ut suscipit. Morbi iaculis, erat at imperdiet semper, ipsum nulla sodales erat, eget tincidunt justo dui quis justo. Pellentesque dictum bibendum diam at aliquet. Sed pulvinar, dolor quis finibus ornare, eros odio facilisis erat, eu rhoncus nunc dui sed ex. Nunc gravida dui massa, sed ornare arcu tincidunt sit amet. Maecenas efficitur sapien neque, a laoreet libero feugiat ut. - -Nulla facilisi. Maecenas sodales nec purus eget posuere. Sed sapien quam, pretium a risus in, porttitor dapibus erat. Sed sit amet fringilla ipsum, eget iaculis augue. Integer sollicitudin tortor quis ultricies aliquam. Suspendisse fringilla nunc in tellus cursus, at placerat tellus scelerisque. Sed tempus elit a sollicitudin rhoncus. Nulla facilisi. Morbi nec dolor dolor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Cras et aliquet lectus. Pellentesque sit amet eros nisi. Quisque ac sapien in sapien congue accumsan. Nullam in posuere ante. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Proin lacinia leo a nibh fringilla pharetra. - -Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Proin venenatis lectus dui, vel ultrices ante bibendum hendrerit. Aenean egestas feugiat dui id hendrerit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Curabitur in tellus laoreet, eleifend nunc id, viverra leo. Proin vulputate non dolor vel vulputate. Curabitur pretium lobortis felis, sit amet finibus lorem suscipit ut. Sed non mollis risus. Duis sagittis, mi in euismod tincidunt, nunc mauris vestibulum urna, at euismod est elit quis erat. Phasellus accumsan vitae neque eu placerat. In elementum arcu nec tellus imperdiet, eget maximus nulla sodales. Curabitur eu sapien eget nisl sodales fermentum. - -Phasellus pulvinar ex id commodo imperdiet. Praesent odio nibh, sollicitudin sit amet faucibus id, placerat at metus. Donec vitae eros vitae tortor hendrerit finibus. Interdum et malesuada fames ac ante ipsum primis in faucibus. Quisque vitae purus dolor. Duis suscipit ac nulla et finibus. Phasellus ac sem sed dui dictum gravida. Phasellus eleifend vestibulum facilisis. Integer pharetra nec enim vitae mattis. Duis auctor, lectus quis condimentum bibendum, nunc dolor aliquam massa, id bibendum orci velit quis magna. Ut volutpat nulla nunc, sed interdum magna condimentum non. Sed urna metus, scelerisque vitae consectetur a, feugiat quis magna. Donec dignissim ornare nisl, eget tempor risus malesuada quis. diff --git a/website/blog-examples-from-docusaurus/2017-04-10-blog-post-two.md b/website/blog-examples-from-docusaurus/2017-04-10-blog-post-two.md deleted file mode 100644 index 3ab4637b..00000000 --- a/website/blog-examples-from-docusaurus/2017-04-10-blog-post-two.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: New Blog Post -author: Blog Author -authorURL: http://twitter.com/ -authorFBID: 100002976521003 ---- - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vivamus elementum massa eget nulla aliquet sagittis. Proin odio tortor, vulputate ut odio in, ultrices ultricies augue. Cras ornare ultrices lorem malesuada iaculis. Etiam sit amet libero tempor, pulvinar mauris sed, sollicitudin sapien. - - - -Mauris vestibulum ullamcorper nibh, ut semper purus pulvinar ut. Donec volutpat orci sit amet mauris malesuada, non pulvinar augue aliquam. Vestibulum ultricies at urna ut suscipit. Morbi iaculis, erat at imperdiet semper, ipsum nulla sodales erat, eget tincidunt justo dui quis justo. Pellentesque dictum bibendum diam at aliquet. Sed pulvinar, dolor quis finibus ornare, eros odio facilisis erat, eu rhoncus nunc dui sed ex. Nunc gravida dui massa, sed ornare arcu tincidunt sit amet. Maecenas efficitur sapien neque, a laoreet libero feugiat ut. - -Nulla facilisi. Maecenas sodales nec purus eget posuere. Sed sapien quam, pretium a risus in, porttitor dapibus erat. Sed sit amet fringilla ipsum, eget iaculis augue. Integer sollicitudin tortor quis ultricies aliquam. Suspendisse fringilla nunc in tellus cursus, at placerat tellus scelerisque. Sed tempus elit a sollicitudin rhoncus. Nulla facilisi. Morbi nec dolor dolor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Cras et aliquet lectus. Pellentesque sit amet eros nisi. Quisque ac sapien in sapien congue accumsan. Nullam in posuere ante. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Proin lacinia leo a nibh fringilla pharetra. - -Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Proin venenatis lectus dui, vel ultrices ante bibendum hendrerit. Aenean egestas feugiat dui id hendrerit. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Curabitur in tellus laoreet, eleifend nunc id, viverra leo. Proin vulputate non dolor vel vulputate. Curabitur pretium lobortis felis, sit amet finibus lorem suscipit ut. Sed non mollis risus. Duis sagittis, mi in euismod tincidunt, nunc mauris vestibulum urna, at euismod est elit quis erat. Phasellus accumsan vitae neque eu placerat. In elementum arcu nec tellus imperdiet, eget maximus nulla sodales. Curabitur eu sapien eget nisl sodales fermentum. - -Phasellus pulvinar ex id commodo imperdiet. Praesent odio nibh, sollicitudin sit amet faucibus id, placerat at metus. Donec vitae eros vitae tortor hendrerit finibus. Interdum et malesuada fames ac ante ipsum primis in faucibus. Quisque vitae purus dolor. Duis suscipit ac nulla et finibus. Phasellus ac sem sed dui dictum gravida. Phasellus eleifend vestibulum facilisis. Integer pharetra nec enim vitae mattis. Duis auctor, lectus quis condimentum bibendum, nunc dolor aliquam massa, id bibendum orci velit quis magna. Ut volutpat nulla nunc, sed interdum magna condimentum non. Sed urna metus, scelerisque vitae consectetur a, feugiat quis magna. Donec dignissim ornare nisl, eget tempor risus malesuada quis. diff --git a/website/blog-examples-from-docusaurus/2017-09-25-testing-rss.md b/website/blog-examples-from-docusaurus/2017-09-25-testing-rss.md deleted file mode 100644 index b7ff8129..00000000 --- a/website/blog-examples-from-docusaurus/2017-09-25-testing-rss.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Adding RSS Support - RSS Truncation Test -author: Eric Nakagawa -authorURL: http://twitter.com/ericnakagawa -authorFBID: 661277173 ---- -1234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890123456789012345678901234567890 - -This should be truncated. - -This line should never render in XML. diff --git a/website/blog-examples-from-docusaurus/2017-09-26-adding-rss.md b/website/blog-examples-from-docusaurus/2017-09-26-adding-rss.md deleted file mode 100644 index eeb4f047..00000000 --- a/website/blog-examples-from-docusaurus/2017-09-26-adding-rss.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Adding RSS Support -author: Eric Nakagawa -authorURL: http://twitter.com/ericnakagawa -authorFBID: 661277173 ---- - -This is a test post. - -A whole bunch of other information. diff --git a/website/blog-examples-from-docusaurus/2017-10-24-new-version-1.0.0.md b/website/blog-examples-from-docusaurus/2017-10-24-new-version-1.0.0.md deleted file mode 100644 index 60761c02..00000000 --- a/website/blog-examples-from-docusaurus/2017-10-24-new-version-1.0.0.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: New Version 1.0.0 -author: Eric Nakagawa -authorURL: http://twitter.com/ericnakagawa -authorFBID: 661277173 ---- - -This blog post will test file name parsing issues when periods are present. diff --git a/website/core/Footer.js b/website/core/Footer.js index b43f1d6a..3f607d3e 100644 --- a/website/core/Footer.js +++ b/website/core/Footer.js @@ -33,7 +33,7 @@ class Footer extends React.Component { /> )} - */} - -+ Architecture. Discusses the architecture of the various layers that make up Home Assistant. +
++ Frontend. Discusses how to develop the user interface of Home Assistant. +
++ Backend. Discusses how to build new integrations for Home Assistant. +
++ External APIs. Documentation of the various APIs to extract data from Home Assistant. +
++ Misc. Internationalization, asyncio, Hass.io, updating documentation. +
+