jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-04-25 13:57:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix all headers

Browse Source
This commit is contained in:
Paulus Schoutsen 2018-04-24 11:46:45 -04:00
parent 746e35b7a7
commit 632bc81a20
67 changed files with 240 additions and 655 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/add_new_platform.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Adding support for a new platform"
description: "Hints and tips for when you're adding a new platform to Home Assistant."
date: 2014-12-21 13:27
sidebar: true
comments: false
sharing: true
footer: true
---
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.
@ -18,13 +12,13 @@ If you're planning to add support for a new type of device to an existing compon
- [Example sensor platform](/developers/platform_example_sensor): hello world of platforms.
- [Example light platform](/developers/platform_example_light): showing best practices.
### {% linkable_title Interfacing with devices %}
### Interfacing with devices
One Home Assistant rule is that platform logic should never interface directly with devices. Instead, use a third-party Python 3 library. This way, Home Assistant can share code with the Python community and keep the project maintainable.
To integrate the third-party library, create an [Entity class](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity.py) for your device. Entities are Home Assistant's representations of lights, switches, sensors, etc. and are derived from the [Entity Abstract Class](https://github.com/home-assistant/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 much more.
### {% linkable_title Requirements and dependencies %}
### Requirements and dependencies
Platforms can specify dependencies and requirements [the same way as components](/developers/component_deps_and_reqs):

7
docs/architecture.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Architecture"
description: "Overview of the Home Assistant architecture."
date: 2014-12-18 21:49
sidebar: true
comments: false
sharing: true
footer: true
og_image: /images/architecture/ha_architecture.svg
---
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.

13
docs/architecture_components.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Components Architecture"
description: "Overview of components within the Home Assistant architecture."
date: 2016-04-16 14:24 -07:00
sidebar: true
comments: false
sharing: true
footer: true
og_image: /images/architecture/component_interaction.png
---
Home Assistant can be extended with **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/).
@ -19,7 +12,7 @@ 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!
#### {% linkable_title 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.
@ -27,7 +20,7 @@ For example, the built-in [`switch` component](/components/switch/) is responsib
If you want to add support for a new platform, check out the [add new platform section](/developers/add_new_platform/).
#### {% linkable_title 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.
@ -53,7 +46,7 @@ In the event of the sun setting:
Look [here](/python_component_automation/) for a comprehensive example of a home automation component.
### {% linkable_title 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.

6
docs/asyncio.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Asynchronous Programming"
description: "Introduction to the asynchronous core of Home Assistant."
date: 2016-10-17 21:49
sidebar: true
comments: false
sharing: true
footer: true
---
On September 29, 2016 we released [Home Assistant 0.29][0.29] as part of our bi-weekly release schedule. This release introduced a complete overhaul of the core spearheaded by [Ben Bangert][ben].

6
docs/asyncio_101.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Asyncio 101"
description: "An introduction to asyncio."
date: 2017-04-08 21:49
sidebar: true
comments: false
sharing: true
footer: true
---
If you are not familiar yet with asyncio, please watch the below video. It's a great introduction by [Robert Smallshire][rob] in how and why asyncio works the way it does.

16
docs/asyncio_categorizing_functions.md
View File

@ -1,19 +1,13 @@
---
layout: page
title: "Categorizing Functions"
description: "A categorization of functions to work with the asynchronous core of Home Assistant."
date: 2016-10-17 21:49
sidebar: true
comments: false
sharing: true
footer: true
---
A piece of work within Home Assistant is represented by a function that will be invoked. It will either run inside our event loop or inside our thread pool, depending on if it is async safe.
Home Assistant uses the convention that all functions that must be run from within the event loop are prefixed with `async_`.
## {% linkable_title The coroutine function %}
## The coroutine function
Coroutines are special functions based on Python’s generators syntax which allows them to suspend execution while waiting on a result.
@ -35,7 +29,7 @@ hass.loop.create_task(async_look_my_coroutine("world"))
In this example, we schedule the coroutine by calling `hass.loop.create_task`. This will add the coroutine to the queue of tasks to be run. When the event loop is running `async_look_my_coroutine` it will suspend the task when `yield from entity.async_turn_on()` is called. At that point a new task will be scheduled to execute `entity.async_turn_on()`. When that job has been executed, `async_look_my_coroutine` will resume.
## {% linkable_title The callback function %}
## The callback function
This is a normal function that is considered safe to be run from within the event loop. A callback is unable to suspend itself and thus cannot do any I/O or call a coroutine. A callback is capable of scheduling a new task but it will not be able to wait for the results.
@ -58,19 +52,19 @@ In this example, `entity.async_trigger` is a coroutine function. Invoking the co
To execute the task we have to schedule it for execution on the event loop. This is done by calling `hass.loop.create_task`.
### {% linkable_title Why even have callbacks? %}
### Why even have callbacks?
You might wonder, if a coroutine can do everything a callback can do, why even have a callback. The reason is performance and better state consistency of the core API objects.
When coroutine A waits for coroutine B, it will suspend itself and schedule a new task to run B. This means that the event loop is now running A, B and then A again. If B is a callback, A will never have to suspend itself and thus the event loop is just running A. The consistency implication is that other events queued to run on the event loop continue to wait until callbacks complete, but will be interleaved when yielding to another coroutine.
## {% linkable_title Event loop and thread safe %}
## Event loop and thread safe
These are functions that are safe to run both in a thread and inside the event loop. These functions are usually performing a computation or transform data in memory. Anything that does I/O does not fall under this category. Many standard library functions fall in this category. For example generating the sum of a set of numbers using sum or merging two dictionaries.
There is no special annotation to mark functions as part of this category and care should be taken when using these functions from inside the event loop. When in doubt, look at their implementation.
## {% linkable_title Other functions %}
## Other functions
These are all the functions that did not fit in the previous categories. These functions are either thread-safe or not considered safe to be run within the event loop. These are functions that use sleep, or perform I/O.

10
docs/asyncio_misc.md
View File

@ -1,20 +1,14 @@
---
layout: page
title: "Miscellaneous Async"
description: "A collection of miscellaneous topics about async that didn't fit on the other pages."
date: 2016-10-17 21:49
sidebar: true
comments: false
sharing: true
footer: true
---
## {% linkable_title What about ‘async’ and ‘await’ syntax? %}
## What about ‘async’ and ‘await’ syntax?
Python 3.5 introduced new syntax to formalize the asynchronous pattern. This is however not compatible with Python 3.4. The minimum required Python version for Home Assistant is based on the Python version shipped with Debian stable, which is currently 3.5.3.
For more information, Brett Cannon wrote [an excellent breakdown][brett] on 'async' and 'await' syntax and how asynchronous programming works.
## {% linkable_title Acknowledgements %}
## Acknowledgements
Huge thanks to [Ben Bangert][ben] for starting the conversion of the core to async, guiding other contributors while taking their first steps with async programming and peer reviewing this documentation.

22
docs/asyncio_working_with_async.md
View File

@ -1,23 +1,17 @@
---
layout: page
title: "Working with Async"
description: "A breakdown of all the different ways to work with the asynchronous core of Home Assistant."
date: 2016-10-17 21:49
sidebar: true
comments: false
sharing: true
footer: true
---
Although we have a backwards compatible API, using the async core directly will be a lot faster. Most core components have already been rewritten to leverage the async core. This includes the EntityComponent helper (foundation of light, switch, etc), scripts, groups and automation.
## {% linkable_title Interacting with the core %}
## Interacting with the core
[All methods in the Home Assistant core][dev-docs] are implemented in two flavors: an async version and a version to be called from other threads. The versions for other are merely wrappers that call the async version in a threadsafe manner using [the available async utilities][dev-docs-async].
So if you are making calls to the core (the hass object) from within a callback or coroutine, use the methods that start with async_. If you need to call an async_ function that is a coroutine, your task must also be a coroutine.
## {% linkable_title Implementing an async component %}
## Implementing an async component
To make a component async, implement an async_setup.
@ -36,7 +30,7 @@ def async_setup(hass, config):
# Setup your component inside of the event loop.
```
## {% linkable_title Implementing an async platform %}
## Implementing an async platform
For platforms we support async setup. Instead of setup_platform you need to have a coroutine async_setup_platform.
@ -58,7 +52,7 @@ def async_setup_platform(hass, config, async_add_entities,
The only difference with the original parameters is that the `add_entities` function has been replaced by the async friendly callback `async_add_entities`.
## {% linkable_title Implementing an async entity %}
## Implementing an async entity
You can make your entity async friendly by converting your update method to be async. This requires the dependency of your entities to also be async friendly!
@ -83,7 +77,7 @@ class MyEntity(Entity):
Make sure that all properties defined on your entity do not result in I/O being done. All data has to be fetched inside the update method and cached on the entity. This is because these properties are read from within the event loop and thus doing I/O will result in the core of Home Assistant waiting until your I/O is done.
## {% linkable_title Calling async functions from threads %}
## Calling async functions from threads
Sometimes it will happen that you’re in a thread and you want to call a function that is only available as async. Home Assistant includes a few async helper utilities to help with this.
@ -100,13 +94,13 @@ def async_say_hello(hass, target):
return "Hello {}!".format(target)
```
## {% linkable_title Dealing with passed in functions %}
## Dealing with passed in functions
If your code takes in functions from other code, you will not know which category the function belongs to and how they should be invoked. This usually only occurs if your code supplies an event helper like `mqtt.async_subscribe` or `track_state_change_listener`.
To help with this, there are two helper methods on the hass object that you can call from inside the event loop:
#### {% linkable_title hass.async_run_job %}
#### hass.async_run_job
Use this method if the function should be called as soon as possible. This will call callbacks immediately, schedule coroutines for execution on the event loop and schedule other functions to be run inside the thread pool.
@ -114,7 +108,7 @@ Use this method if the function should be called as soon as possible. This will
| Coroutine | Schedule for execution on the event loop.
| Other functions | Schedule for execution in the thread pool.
#### {% linkable_title hass.async_add_job %}
#### hass.async_add_job
Use this method if the function should be called but not get priority over already scheduled calls.

12
docs/code_review_component.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Checklist for creating a component"
description: "A list of things to pay attention to when code reviewing a component."
date: 2017-01-15 14:09 -0800
sidebar: true
comments: false
sharing: true
footer: true
---
A checklist of things to do when you're adding a new component.
@ -15,13 +9,13 @@ A checklist of things to do when you're adding a new component.
Not all existing platforms follow the requirements in this checklist. This cannot be used as a reason to not follow them!
</p>
### {% linkable_title 1. Requirements %}
### 1. Requirements
1. Requirement version pinned: `REQUIREMENTS = ['phue==0.8.1']`
2. We no longer want requirements hosted on GitHub. Please upload to PyPi.
3. Requirements should only be imported inside functions. This is necessary because requirements are installed on the fly.
### {% linkable_title 2. Configuration %}
### 2. Configuration
1. Voluptuous schema present for config validation
2. Default parameters specified in voluptuous schema, not in `setup(…)`
@ -30,7 +24,7 @@ Not all existing platforms follow the requirements in this checklist. This canno
5. If using a `PLATFORM_SCHEMA` to be used with `EntityComponent`, import base from `homeassistant.helpers.config_validation`
6. Never depend on users adding things to `customize` to configure behavior inside your component.
### {% linkable_title 3. Component/platform communication %}
### 3. Component/platform communication
1. If you need to share global data with platforms, use the dictionary `hass.data`. `hass.data[DATA_XY]` while `XY` is the component is preferred over `hass.data[DOMAIN]`.
2. If the component fetches data that causes its related platform entities to update, you can notify them using the dispatcher code in `homeassistant.helpers.dispatcher`.

18
docs/code_review_platform.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Checklist for creating a platform"
description: "A list of things to pay attention to when code reviewing a platform."
date: 2017-01-15 14:09 -0800
sidebar: true
comments: false
sharing: true
footer: true
---
A checklist of things to do when you're adding a new platform.
@ -15,17 +9,17 @@ 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!
</p>
### {% linkable_title 1. Requirements %}
### 1. Requirements
1. Requirement version should be pinned: `REQUIREMENTS = ['phue==0.8.1']`
2. We no longer want requirements hosted on GitHub. Please upload to PyPi.
3. Requirements should only be imported inside functions. This is necessary because requirements are installed on the fly.
### {% linkable_title 2. Dependencies %}
### 2. Dependencies
1. If you depend on a component for the connection, add it to your dependencies: `DEPENDENCIES = ['nest']`
### {% linkable_title 3. Configuration %}
### 3. Configuration
1. Voluptuous schema present for config validation
2. Voluptuous schema extends schema from component<br>(e.g., `light.hue.PLATFORM_SCHEMA` extends `light.PLATFORM_SCHEMA`)
@ -50,20 +44,20 @@ Not all existing platforms follow the requirements in this checklist. This canno
```
5. Never depend on users adding things to `customize` to configure behavior inside your platform.
### {% linkable_title 4. Setup Platform %}
### 4. Setup Platform
1. Test if passed in info (user/pass/host etc.) works.
2. Group your calls to `add_devices` if possible.
3. If platform adds extra services, format should be `<component>.<platform>_<service name>`.
### {% linkable_title 5. Entity %}
### 5. Entity
1. Extend entity from component, e.g., `class HueLight(Light)`
2. Do not call `update()` in constructor, use `add_devices(devices, True)` instead.
3. Do not do any I/O inside properties. Cache values inside `update()` instead.
4. The state and/or attributes should not contain relative time since something happened. Instead it should store UTC timestamps.
### {% linkable_title 6. Communication with devices/services %}
### 6. Communication with devices/services
1. All API specific code has to be part of a third party library hosted on PyPi. Home Assistant should only interact with objects and not make direct calls to the API.

10
docs/component_deps_and_reqs.md
View File

@ -1,17 +1,11 @@
---
layout: page
title: "Requirements & Dependencies"
description: "Instructions on how to define requirements and dependencies."
date: 2016-04-16 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant allows components and platforms to specify their dependencies and requirements using the variables `DEPENDENCIES` and `REQUIREMENTS`. Both are lists that contain strings.
## {% linkable_title Dependencies %}
## Dependencies
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.
@ -19,7 +13,7 @@ Dependencies are other Home Assistant components that should be setup before the
DEPENDENCIES = ['mqtt']
```
## {% linkable_title Requirements %}
## 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.

12
docs/component_discovery.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Component Discovery"
description: "How to make component discovery work."
date: 2017-11-23 07:27 +02:00
sidebar: true
comments: false
sharing: true
footer: true
---
<p class='note warning'>
@ -15,13 +9,13 @@ 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.
### {% linkable_title Add discovery instructions %}
### Add discovery instructions
Device discovery for Home Assistant has been extracted into an external library called [NetDisco](https://github.com/home-assistant/netdisco). This library is integrated using [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py) and scans the network in intervals for uPnP and zeroconf/mDNS services.
To have your device be discovered, you will have to extend the NetDisco library to be able to find your device. This is done by adding a new discoverable. [See the repository for examples of existing discoverable.](https://github.com/home-assistant/netdisco/tree/master/netdisco/discoverables)
### {% linkable_title Listening to `SERVICE_DISCOVERED` events %}
### Listening to `SERVICE_DISCOVERED` events
From your component, you will have to set up the listening for specific services. Given below is an example how one would listen for a discovered AwesomeDevice:
@ -46,7 +40,7 @@ def setup(hass, config):
return True
```
### {% linkable_title Auto-loading your component upon discovery %}
### Auto-loading your component upon discovery
The `discovery` component is capable of setting up your components before firing the `EVENT_PLATFORM_DISCOVERED` event. To do this you will have to update the [`SERVICE_HANDLERS`](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py#L40) constant in [the `discovery` component](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/discovery.py):

6
docs/component_events.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Handling events"
description: "Instructions on how to handle events with your component."
date: 2016-04-16 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant has different ways of responding to events that occur in Home Assistant. These have been organized in [helper methods](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/event.py). Examples are `track_state_change`, `track_point_in_time`, `track_time_change`.

10
docs/component_generic_discovery.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Generic Platform Discovery"
description: "Using generic platform discovery."
date: 2016-05-12 22:00 -02:00
sidebar: true
comments: false
sharing: true
footer: true
---
New controller or hub components often need to add platforms in sub-components (i.e. Lights & Switches) without additional configuration.
@ -18,7 +12,7 @@ def load_platform(hass, component, platform, discovered=None, hass_config=None)
From more info on how this works, refer to the [load_platform](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/discovery.py#L136) method.
### {% linkable_title Example %}
### Example
Say you need to implement your new MyFlashyHub that controls both Switches & Lights, you can follow these steps:
@ -59,7 +53,7 @@ Add your custom device specific code to the `setup_platform` method in `light/my
```python
import custom_components.myflashyhub as myflashyhub
# 'switch' will receive discovery_info={'optional': 'arguments'}
# 'switch' will receive discovery_info={'optional': 'arguments'}
# as passed in above. 'light' will receive discovery_info=None
def setup_platform(hass, config, add_devices, discovery_info=None):
"""Your switch/light specific code."""

6
docs/component_loading.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Loading your components"
description: "Instructions on how to get your component loaded by Home Assistant."
date: 2016-04-16 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
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:

6
docs/component_states.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Handling states"
description: "Instructions on how to handle states with your component."
date: 2016-07-01 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
It is the responsibility of the component to maintain the states of the devices in your domain. Each device should be a single state and, if possible, a group should be provided that tracks the combined state of the devices.

8
docs/creating_components.md
View File

@ -1,17 +1,11 @@
---
layout: page
title: "Creating components"
description: "Guidelines to get you create your first component for Home Assistant."
date: 2014-12-21 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
Alright, you're ready to make your first component. AWESOME. Don't worry, we've tried hard to keep it as easy as possible.
### {% linkable_title Example component %}
### Example component
Add `hello_state:` to your `configuration.yaml` file and create a file `<config_dir>/custom_components/hello_state.py` with the below code to test it locally.

8
docs/development.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Starting with Development"
description: "Everything to get you started developing for Home Assistant."
date: 2014-12-21 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
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.
@ -16,7 +10,7 @@ Home Assistant is open-source and licensed under [Apache 2.0](http://www.apache.
- [home-assistant](https://github.com/home-assistant/home-assistant): Python server backend.
- [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer): Polymer UI.
For those new to contributing to open source software, make sure you are familiar with all of the tools and concepts used in Home Assistant before you start.
For those new to contributing to open source software, make sure you are familiar with all of the tools and concepts used in Home Assistant before you start.
When contributing Home Assistant code:
- [Github](https://guides.github.com/activities/hello-world/)

6
docs/development_101.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Development 101"
description: "Introduction to the basics of Home Assistant."
date: 2017-05-13 05:40:00 +0000
sidebar: true
comments: false
sharing: true
footer: true
---
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].

6
docs/development_catching_up.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Catching up with Reality"
description: "Update your fork with the latest commit."
date: 2016-07-01 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
If it's taking a while to develop your feature, and you want to catch up with what's in the current Home Assistant `dev` branch, you can use `git rebase`. This will pull the latest Home Assistant changes locally, rewind your commits, bring in the latest changes from Home Assistant, and replay all of your commits on top.

6
docs/development_checklist.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Development Checklist"
description: "Overview of the requirements for an improvement for Home Assistant."
date: 2016-07-01 20:00
sidebar: true
comments: false
sharing: true
footer: true
---

12
docs/development_config.md
View File

@ -1,21 +1,15 @@
---
layout: page
title: "Using Config"
description: "Introduction to the Config object in Home Assistant."
date: 2017-05-13 05:40:00 +0000
sidebar: true
comments: false
sharing: true
footer: true
---
Based on where you are in the code, `config` can mean various things.
### {% linkable_title On the hass object %}
### On the hass object
On the hass object is an instance of the Config class. The Config class contains the users preferred units, the path to the config directory and which components are loaded. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.Config)
### {% linkable_title Config passed into component setup %}
### Config passed into component setup
The `config` parameter passed to a component setup is a dictionary containing all of the user supplied configuration. The keys of the dictionary are the component names and the value is another dictionary with the component configuration.
@ -30,6 +24,6 @@ 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 Passed into platform setup %}
### Passed into platform setup
The `config` parameter passed to a platform setup function is only the config for that specific platform.

20
docs/development_environment.md
View File

@ -1,19 +1,13 @@
---
layout: page
title: "Set up Development Environment"
description: "Set up your environment to start developing for Home Assistant."
date: 2014-12-21 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
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.
### {% linkable_title Preparing your environment %}
### Preparing your environment
#### {% linkable_title Developing on Linux %}
#### Developing on Linux
Install the core dependencies.
@ -33,7 +27,7 @@ Different distributions have different package installation mechanisms and somet
Additional dependencies exist if you plan to perform Frontend Development, please read the [Frontend](/developers/frontend/) section to learn more.
#### {% linkable_title 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.
@ -64,7 +58,7 @@ Also, make sure to install or upgrade the `setuptools` Python package. It contai
$ pip install --upgrade setuptools
```
#### {% linkable_title Developing on OS X %}
#### Developing on OS X
Install [Homebrew](https://brew.sh/), then use that to install Python 3:
@ -72,7 +66,7 @@ Install [Homebrew](https://brew.sh/), then use that to install Python 3:
$ brew install python3
```
### {% linkable_title 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:
@ -83,7 +77,7 @@ $ cd home-assistant
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
```
### {% linkable_title 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.
@ -103,7 +97,7 @@ Invoke your installation.
$ hass
```
### {% linkable_title 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).

12
docs/development_events.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Using Events"
description: "Introduction to using events in Home Assistant."
date: 2017-05-13 05:40:00 +0000
sidebar: true
comments: false
sharing: true
footer: true
---
The core of Home Assistant is driven by events. That means that if you want to respond to something happening, you'll have to respond to events. Most of the times you won't interact directly with the event system but use one of the [event listener helpers][helpers].
@ -15,7 +9,7 @@ The event system is very flexible. There are no limitations on the event type, a
[List of events that Home Assistant fires.][object]
### {% linkable_title 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`.
@ -33,7 +27,7 @@ def setup(hass, config):
})
```
### {% linkable_title 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.
@ -54,7 +48,7 @@ def setup(hass, config):
hass.bus.listen('my_cool_event', handle_event)
```
#### {% linkable_title 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]

16
docs/development_guidelines.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Style guidelines"
description: "Details about styling your code."
date: 2017-04-28 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant enforces strict [PEP8 style](https://www.python.org/dev/peps/pep-0008/) and [PEP 257 (Docstring Conventions)](https://www.python.org/dev/peps/pep-0257/) compliance on all code submitted. We automatically test every pull request as part of the linting process with [Coveralls](https://coveralls.io/github/home-assistant/home-assistant) and [Travis CI](https://travis-ci.org/home-assistant/home-assistant).
@ -25,11 +19,11 @@ The maximum line length comes directly from the [PEP8 style guide](https://www.p
Those points may require that you adjust your IDE or editor settings.
## {% linkable_title Our recommendations %}
## Our recommendations
For some cases [PEPs](https://www.python.org/dev/peps/) don't make a statement. This section covers our recommendations about the code style. Those points were collected from the existing code and based on what contributors and developers were using the most. This is basically a majority decision, thus you may not agree with it. But we would like to encourage you follow those recommendations to keep the code unified.
### {% linkable_title Quotes %}
### Quotes
Use single quotes `'` for single word and `"` for multiple words or sentences.
@ -41,7 +35,7 @@ SENSOR_TYPES = {
}
```
### {% linkable_title File headers %}
### File headers
The docstring in the file header should contain a link to the documentation to make it easy to find further information, especially about the configuration or details which are not mentioned in the code.
@ -54,7 +48,7 @@ https://home-assistant.io/components/light.mqtt/
"""
```
### {% linkable_title Requirements %}
### Requirements
Please place [Platform requirements](/developers/code_review_platform/#1-requirements) right after the imports.
@ -65,7 +59,7 @@ from homeassistant.helpers.entity import Entity
REQUIREMENTS = ['xmltodict==0.11.0']
```
### {% linkable_title Log messages %}
### Log messages
There is no need to add the platform or component name to the log messages. This will be added automatically. Like `syslog` messages there shouldn't be any period at the end. Try to avoid brackets and additional quotes around the output to make it easier for users to parse the log. A widely style is shown below but you are free to compose the messages as you like.

11
docs/development_hass_object.md
View File

@ -1,18 +1,11 @@
---
layout: page
title: "Hass object"
description: "Introduction to developing with the hass object."
date: 2016-04-16 13:32
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /developers/component_initialization/
---
While developing Home Assistant you will see a variable that is everywhere: `hass`. This is the Home Assistant instance that will give you access to all the various parts of the system.
### {% linkable_title The `hass` object %}
### The `hass` object
The Home Assistant instance contains four objects to help you interact with the system.
@ -24,7 +17,7 @@ The Home Assistant instance contains four objects to help you interact with the
| `hass.bus` | This is the EventBus. It allows you to trigger and listen for events. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.EventBus). |
| `hass.services` | This is the ServiceRegistry. It allows you to register services. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.ServiceRegistry). |
### {% linkable_title Where to find `hass` %}
### Where to find `hass`
Depending on what you're writing, there are different ways the `hass` object is made available.

6
docs/development_services.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Using Services"
description: "Introduction to services in Home Assistant."
date: 2017-05-13 05:40:00 +0000
sidebar: true
comments: false
sharing: true
footer: true
---
This is a simple "hello world" example to show the basics of registering a service. To use this example, create the file `<config dir>/custom_components/hello_service.py` and copy the below example code.

8
docs/development_states.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Using States"
description: "Introduction to states in Home Assistant."
date: 2017-05-13 05:40:00 +0000
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant keeps track of the states of entities in a state machine. The state machine has very few requirements:
@ -17,7 +11,7 @@ Home Assistant keeps track of the states of entities in a state machine. The sta
[Description of the state object.](/docs/configuration/state_object/)
### {% linkable_title 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.

30
docs/development_submitting.md
View File

@ -1,47 +1,41 @@
---
layout: page
title: "Submit your work"
description: "Submit your work as Pull Request for Home Assistant."
date: 2016-07-01 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
Submit your improvements, fixes, and new features to Home Assistant one at a time, using GitHub [Pull Requests](https://help.github.com/articles/using-pull-requests). Here are the steps:
1. From your fork's dev branch, create a new branch to hold your changes:
`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).
3. [Test your changes](/developers/development_testing/) and check for style violations.
4. If everything looks good according to these [musts](/developers/development_checklist/), commit your changes:
`git add .`
`git commit -m "Added some-feature"`
* Write a meaningful commit message and not only `Update` or `Fix`.
* Use a capital letter to start with your commit message.
* Don't prefix your commit message with `[bla.bla]` or `platform:`.
* Consider adding tests to ensure that your code works.
5. Push your committed changes back to your fork on GitHub:
`git push origin HEAD`
6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request.
* On GitHub, navigate to the main page of the Home Assistant repository.
* In the "Branch" menu, choose the branch that contains your commits (from your fork).
* To the right of the Branch menu, click **New pull request**.
* Use the base branch dropdown menu to select the branch you'd like to merge your changes into, then use the compare branch drop-down menu to choose the topic branch you made your changes in. Make sure the Home Assistant branch matches with your forked branch (`dev`) else you will propose ALL commits between branches.
* Type a title and complete the provided description for your pull request.
* Type a title and complete the provided description for your pull request.
* Click **Create pull request**.
7. Check for comments and suggestions on your pull request and keep an eye on the [CI output](https://travis-ci.org/home-assistant/home-assistant/).

14
docs/development_testing.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Testing your code"
description: "Make sure that your code passes the checks"
date: 2016-07-01 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
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:
@ -22,7 +16,7 @@ Tox uses virtual environments under the hood to create isolated testing environm
If you are working on tests for a component or platform and you need the dependencies available inside the Tox environment, update the list inside `script/gen_requirements_all.py`. Then run the script and then run `tox -r` to recreate the virtual environments.
### {% linkable_title Running single tests using Tox %}
### Running single tests using Tox
You can pass arguments via Tox to py.test to be able to run single test suites or test files. Replace `py36` with the Python version that you use.
@ -37,7 +31,7 @@ $ tox -e py36 -- tests/test_core.py --timeout 2
$ tox -e py36 -- tests/test_core.py --duration=10
```
### {% linkable_title Testing outside of Tox %}
### Testing outside of Tox
Running tox will invoke the full test suite. Even if you specify which tox target to run, you still run all tests inside that target. That's not very convenient to quickly iterate on your code! To be able to run the specific test suites without Tox, you'll need to install the test dependencies into your Python environment:
@ -60,7 +54,7 @@ You can also run linting tests against all changed files, as reported by `git di
$ script/lint
```
### {% linkable_title Preventing Linter Errors %}
### Preventing Linter Errors
Save yourself the hassle of extra commits just to fix style errors by enabling the Flake8 git commit hook. Flake8 will check your code when you try to commit to the repository and block the commit if there are any style errors, which gives you a chance to fix them!
@ -71,6 +65,6 @@ $ flake8 --install-hook=git
The `flake8-docstrings` extension will check docstrings according to [PEP257](https://www.python.org/dev/peps/pep-0257/) when running Flake8.
### {% linkable_title Notes on PyLint and PEP8 validation %}
### Notes on PyLint and PEP8 validation
If you can't avoid a PyLint warning, add a comment to disable the PyLint check for that line with `# pylint: disable=YOUR-ERROR-NAME`. Example of an unavoidable one is if PyLint incorrectly reports that a certain object doesn't have a certain member.

20
docs/development_validation.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Validate the input"
description: "Validation of entries in configuration.yaml"
date: 2016-08-11 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
The `configuration.yaml` file contains the configuration options for components and platforms. We use [voluptuous](https://pypi.python.org/pypi/voluptuous) to make sure that the configuration provided by the user is valid. Some entries are optional or could be required to set up a platform or a component. Others must be a defined type or from an already-defined list.
@ -20,7 +14,7 @@ Besides [voluptuous](https://pypi.python.org/pypi/voluptuous) default types, man
- Numbers: `small_float` and `positive_int`
- 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.
Some things to keep in mind:
@ -30,11 +24,11 @@ Some things to keep in mind:
- Preferred order is `required` first and `optional` second
- Starting with Home Assistant 0.64 `voluptuous` requires default values for optional configuration keys to be valid values. Don't use a default which is `None` like `vol.Optional(CONF_SOMETHING, default=None): cv.string`, set the default to `default=""` if required.
### {% linkable_title Snippets %}
### Snippets
This section contains snippets for the validation we use.
#### {% linkable_title Default name %}
#### Default name
It's common to set a default for a sensor if the user doesn't provide a name to use.
@ -46,7 +40,7 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,
```
#### {% linkable_title Limit the values %}
#### Limit the values
You might want to limit the user's input to a couple of options.
@ -58,9 +52,9 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(['POST', 'GET']),
```
#### {% linkable_title Port %}
#### Port
All port numbers are from a range of 1 to 65535.
All port numbers are from a range of 1 to 65535.
```python
DEFAULT_PORT = 993
@ -70,7 +64,7 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,
```
#### {% linkable_title Lists %}
#### Lists
If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list.

50
docs/documentation_create_page.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Create a new page"
description: "Create a new page for the documentation"
date: 2015-06-17 08:00
sidebar: true
comments: false
sharing: true
footer: true
---
For a platform or component page, the fastest way is to make a copy of an existing page and edit it. The [Component overview](/components/) and the [Examples section](/cookbook/) are generated automatically, so there is no need to add a link to those pages.
@ -19,19 +13,19 @@ If you start from scratch with a page, you need to add a header. Different secti
---
layout: page
title: "Awesome Sensor"
description: "home-assistant.io web presence"
date: 2015-06-17 08:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: "0.38"
ha_category: Sensor
---
Content...Written in markdown.
Content...Written in markdown.
{% raw %}### {% linkable_title Linkable Header %}{% endraw %}
{% raw %}### Linkable Header %}{% endraw
...
```
@ -43,7 +37,7 @@ A couple of points to remember:
- If you're adding a new component, for the `ha_release` part of the header, just increment of the current release. If the current release is 0.37, make `ha_release` 0.38. If it's 0.30 or 0.40 please quote it with `" "`.
- `ha_category:` is needed to list the platform or component in the appropriate category on the website.
### {% linkable_title Configuration %}
### Configuration
Every platform page should contain a configuration sample. This sample must contain only the **required** variables to make it easy to copy and paste it for users into their `configuration.yaml` file.
@ -53,23 +47,23 @@ The **Configuration Variables** section must use the {% raw %}`{% configuration
```text
{% configuration %}
api_key:
description: The API key to access the service.
required: true
type: string
name:
description: Name to use in the frontend.
required: false
default: The default name to use in the frontend.
type: string
monitored_conditions:
description: Conditions to display in the frontend.
required: true
type: list
keys:
weather:
description: A human-readable text summary.
temperature:
description: The current temperature.
{% endconfiguration %}
```
@ -89,29 +83,29 @@ required: any string here #=> Any string here
- **`type:`**: The type of the variable. Allowed entries: `string`, `int`, `time`, `template` or `map`. For multiple possibilities use `[string, int]`. If you use `map` then you need to define `keys:` (see the [`template` sensor](/components/sensor.template/) for an example).
- **`default:`**: The default value for the variable.
### {% linkable_title Embedding Code %}
### Embedding Code
You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in {% raw %}`{% endraw %}.
You can use the [default markdown syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code) to generate syntax highlighted code. For inline code wrap your code in {% raw %}`{% endraw %}.
When you're writing code that is to be executed on the terminal, prefix it with `$`.
### {% linkable_title Templates %}
### Templates
For the [configuration templating](/topics/templating/) is [Jinja](http://jinja.pocoo.org/) used. Check the [Documentation Standards](/developers/documentation/standards/) for further details.
If you are don't escape templates then they will be rendered and appear blank on the website.
### {% linkable_title HTML %}
### HTML
The direct usage of HTML is supported but not recommended. The note boxes are an exception.
```html
<p class='note warning'>
You need to enable telnet on your router.
You need to enable telnet on your router.
</p>
```
### {% linkable_title Images, icons, and logos %}
### Images, icons, and logos
The images which are displayed on the pages are stored in various directories according to their purpose. If you want to use a logo and placed `logo:` in the file header then this image should be stored in `source/images/supported_brands`. The background must be transparent.
@ -123,5 +117,5 @@ The images which are displayed on the pages are stored in various directories ac
Not everything (product, component, etc.) should have a logo. To show something for internal parts of Home Assistant we are using the [Material Design Icons](https://materialdesignicons.com/).
### {% linkable_title Linking From The Sidebar %}
### Linking From The Sidebar
If you are adding a new page that requires linking from the sidebar you need to edit the `docs_navigation.html` file in `home-assistant.github.io/source/_includes/asides/docs_navigation.html`.

7
docs/documentation_index.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Documentation Home Assistant"
description: "home-assistant.io web presence for the documentation"
date: 2015-06-17 08:00
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /developers/website/
---
The website you are reading now is the home of Home Assistant: [https://www.home-assistant.io](/). This is the place where we provide documentation and additional details about Home Assistant for end users and developers.

28
docs/documentation_standards.md
View File

@ -1,25 +1,19 @@
---
layout: page
title: "Documentation Standards"
description: "Standards for the creation and maintenance of documentation for Home Assistant."
date: 2017-09-16 03:51
sidebar: true
comments: false
sharing: true
footer: true
---
To ensure that the documentation for Home Assistant is consistent and easy to follow for both novice and expert users, we ask that you follow a very strict set of standards for developing the documentation.
## {% linkable_title General Documentation %}
## General Documentation
* The language of the documentation should be American-English.
* Don't put two spaces after a period and avoid the "Oxford comma".
* Be objective and not gender favoring, polarizing, race related or religion inconsiderate.
* The case of brand names, services, protocols, components, and platforms must match its respective counterpart. e.g., "Z-Wave" **not** "Zwave", "Z-wave", "Z Wave" or "ZWave". Also, "Input Select" **not** "input select" or "Input select".
* All headings should use the {% raw %}`{% linkable_title %}`{% endraw %} tag.
* All headings should use the {% raw %}`%}`{% endraw tag.
## {% linkable_title Component and Platform Pages %}
## Component and Platform Pages
* The **Configuration Variables** section must use the {% raw %}`{% configuration %}`{% endraw %} tag.
* Configuration variables must document the requirement status.
@ -32,7 +26,7 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo
* If you know that the API key or value contains [control characters](https://en.wikipedia.org/wiki/YAML#Syntax), e.g., `#`, `[`, `?`, etc., wrap it in quotes and add a note.
* Component and platform names should be a link to their respective documentation pages.
## {% linkable_title Templates %}
## Templates
* All examples containing Jinja2 templates should be wrapped **outside** of the code markdown with the {% raw %}`{% raw %}`{% endraw %} tag.
* Do not use `states.switch.source.state` in templates. Instead use `states()` and `is_state()`.
@ -57,26 +51,26 @@ To ensure that the documentation for Home Assistant is consistent and easy to fo
* `condition`
* `service`
## {% linkable_title Renaming Pages %}
## Renaming Pages
It can happen that a component or platform is renamed, in this case the documentation needs to be updated as well. If you rename a page, add `redirect_from:` to the file header and let it point to the old location/name of the page. Please consider to add details, like release number or old component/platform name, to the page in a [note](/developers/documentation/create_page/#html).
```text
---
...
redirect_from: /getting-started/android/
---
```
Adding a redirect also applies if you move content around in the [documentation](/docs/).
## {% linkable_title Single vs. Double Quotation Marks %}
## Single vs. Double Quotation Marks
Use single quotes (`'`) for strings inside of a template. It is more obvious to escape a single quote when necessary (i.e. `name` is a possessive noun), because the single quotes that wrap the string are closer in position to the apostrophe inside the string. Use double quotes (`"`) outside of a template (unless it is a multi-line template, in which case outside quotes are not required).
### {% linkable_title Examples %}
### Examples
#### {% linkable_title Double Quotes Outside, Single Quotes Inside (Valid) %}
#### Double Quotes Outside, Single Quotes Inside (Valid)
{% raw %}
```yaml
@ -89,7 +83,7 @@ automation:
```
{% endraw %}
#### {% linkable_title Single Quotes Outside, Double Quotes Inside (Invalid) %}
#### Single Quotes Outside, Double Quotes Inside (Invalid)
{% raw %}
```yaml
@ -102,7 +96,7 @@ automation:
```
{% endraw %}
#### {% linkable_title Multi-Line Template (Valid) %}
#### Multi-Line Template (Valid)
{% raw %}
```yaml

40
docs/external_api_python.md
View File

@ -1,19 +1,13 @@
---
layout: page
title: "Python Remote API"
description: "Home Assistant Python Remote API documentation"
date: 2015-05-11 12:00
sidebar: true
comments: false
sharing: true
footer: true
---
See the [developer documentation][devdocs] for a full overview of the documentation. The rest of this page will contain examples on how to use it.
[devdocs]: https://dev-docs.home-assistant.io/en/master/api/homeassistant.html#module-homeassistant.remote
In the package [`homeassistant.remote`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found. 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 to use the Python Remote API.
In the package [`homeassistant.remote`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/remote.py) a Python API on top of the [HTTP API](/developers/api/) can be found. 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 to use the Python Remote API.
A simple way to get all current entities is to visit the "Set State" page in the "Developer Tools". For the examples below just choose one from the available entries. Here the sensor `sensor.office_temperature` and the switch `switch.livingroom_pin_2` are used.
@ -26,7 +20,7 @@ api = remote.API('127.0.0.1', 'password')
print(remote.validate_api(api))
```
### {% linkable_title Get configuration %}
### Get configuration
Get the current configuration of a Home Assistant instance:
@ -38,7 +32,7 @@ api = remote.API('127.0.0.1', 'password')
print(remote.get_config(api))
```
### {% linkable_title Get details about services, events, and entitites %}
### Get details about services, events, and entitites
The output from this is similar to the output you'd find via the frontend, using the [Developer Tools](/docs/tools/dev-tools/).
@ -63,9 +57,9 @@ for entity in entities:
print(entity)
```
### {% linkable_title Get the state of an entity %}
### Get the state of an entity
To get the details of a single entity, use `get_state`:
To get the details of a single entity, use `get_state`:
```python
import homeassistant.remote as remote
@ -96,7 +90,7 @@ print('{} is {}.'.format(
)
```
### {% linkable_title Set the state of an entity %}
### Set the state of an entity
Of course, it's possible to set the state as well:
@ -111,7 +105,7 @@ remote.set_state(api, 'switch.livingroom_pin_2', new_state=STATE_ON)
The state will be set to the new values until the next update occurs.
### {% linkable_title Blinking all entities of a domain %}
### Blinking all entities of a domain
If you want to turn on all entities of a domain, retrieve the service via `get_services` and act on that:
@ -128,7 +122,7 @@ time.sleep(10)
remote.call_service(api, domain, 'turn_off')
```
### {% linkable_title Control a single entity %}
### Control a single entity
To turn on or off a single switch, pass the ID of the entity:
@ -145,7 +139,7 @@ time.sleep(5)
remote.call_service(api, domain, 'turn_off', {'entity_id': '{}'.format(switch_name)})
```
### {% linkable_title Specify a timeout %}
### Specify a timeout
The default timeout for an API call with `call_service` is 5 seconds. Services
taking longer than this to return will raise
@ -169,9 +163,9 @@ remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name},
timeout=11)
```
### {% linkable_title Send a notification %}
### Send a notification
The example uses the Jabber notification platform to send a single message to the given recipient in the `configuration.yaml` file:
The example uses the Jabber notification platform to send a single message to the given recipient in the `configuration.yaml` file:
```python
import homeassistant.remote as remote
@ -183,13 +177,13 @@ data = {"title":"Test", "message":"A simple test message from HA."}
remote.call_service(api, domain, 'jabber', data)
```
## {% linkable_title Examples %}
## Examples
This section contains a couple of sample scripts.
### {% linkable_title List all sensors and their value %}
### List all sensors and their value
If you want to see, export or list all sensor states then an easy way to do it, is to get all entities and filter for the one you are looking for.
If you want to see, export or list all sensor states then an easy way to do it, is to get all entities and filter for the one you are looking for.
```python
import homeassistant.remote as remote
@ -202,10 +196,10 @@ for entity in entities:
print('{}: {}'.format(data.attributes['friendly_name'], data.state))
```
### {% linkable_title Show difference between `last_changed` and `last_updated` %}
### Show difference between `last_changed` and `last_updated`
The documentation about the [State Objects](/docs/configuration/state_object/) describes the
`last_changed` and `last_updated` fields. This example shows how it works in practice.
The documentation about the [State Objects](/docs/configuration/state_object/) describes the
`last_changed` and `last_updated` fields. This example shows how it works in practice.
```python
import time

44
docs/external_api_rest.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "RESTful API"
description: "Home Assistant RESTful API documentation"
date: 2014-12-21 13:27
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant runs a web server accessible on port 8123.
@ -16,7 +10,7 @@ Home Assistant runs a web server accessible on port 8123.
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/)).
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`](/components/frontend/) in your setup then you need to add the [`api` component](/components/api/) to your `configuration.yaml` file.
There are multiple ways to consume the Home Assistant Rest API. One is with `curl`:
@ -51,11 +45,11 @@ Successful calls will return status code 200 or 201. Other status codes that can
- 404 (Not Found)
- 405 (Method not allowed)
### {% linkable_title Actions %}
### Actions
The API supports the following actions:
#### {% linkable_title GET /api/ %}
#### GET /api/
Returns a message if the API is up and running.
@ -72,7 +66,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/
```
#### {% linkable_title GET /api/config %}
#### GET /api/config
Returns the current configuration as JSON.
@ -103,7 +97,7 @@ Returns the current configuration as JSON.
"location_name":"Home",
"longitude":8.458853651,
"time_zone":"Europe/Zurich",
"unit_system":{
"unit_system":{
"length":"km",
"mass":"g",
"temperature":"\u00b0C",
@ -124,7 +118,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/config
```
#### {% linkable_title GET /api/discovery_info %}
#### GET /api/discovery_info
Returns basic information about the Home Assistant instance as JSON.
@ -144,7 +138,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/discovery_info
```
#### {% linkable_title GET /api/events %}
#### GET /api/events
Returns an array of event objects. Each event object contains event name and listener count.
@ -168,7 +162,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/events
```
#### {% linkable_title GET /api/services %}
#### GET /api/services
Returns an array of service objects. Each object contains the domain and which services it contains.
@ -197,7 +191,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/services
```
#### {% linkable_title GET /api/history/period/&lt;timestamp> %}
#### GET /api/history/period/&lt;timestamp>
Returns an array of state changes in the past. Each object contains further details for the entities.
@ -255,7 +249,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?end_time=2016-12-31T00%3A00%3A00%2B02%3A00
```
#### {% linkable_title GET /api/states %}
#### GET /api/states
Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.
@ -283,7 +277,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/states
```
#### {% linkable_title GET /api/states/&lt;entity_id> %}
#### GET /api/states/&lt;entity_id>
Returns a state object for specified entity_id. Returns 404 if not found.
@ -311,7 +305,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
http://localhost:8123/api/states/sensor.kitchen_temperature
```
#### {% linkable_title GET /api/error_log %}
#### GET /api/error_log
Retrieve all errors logged during the current session of Home Assistant as a plaintext response.
@ -329,7 +323,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
http://localhost:8123/api/error_log
```
#### {% linkable_title GET /api/camera_proxy/camera.&lt;entity_id> %}
#### GET /api/camera_proxy/camera.&lt;entity_id>
Returns the data (image) from the specified camera entity_id.
@ -341,7 +335,7 @@ $ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg
```
#### {% linkable_title POST /api/states/&lt;entity_id> %}
#### POST /api/states/&lt;entity_id>
Updates or creates the current state of an entity.
@ -381,7 +375,7 @@ $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
http://localhost:8123/api/states/sensor.kitchen_temperature
```
#### {% linkable_title POST /api/events/&lt;event_type> %}
#### POST /api/events/&lt;event_type>
Fires an event with event_type
@ -401,7 +395,7 @@ Returns a message if successful.
}
```
#### {% linkable_title POST /api/services/&lt;domain>/&lt;service> %}
#### POST /api/services/&lt;domain>/&lt;service>
Calls a service within a specific domain. Will return when the service has been executed or after 10 seconds, whichever comes first.
@ -457,7 +451,7 @@ $ curl -X POST \
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.
</p>
#### {% linkable_title POST /api/template %}
#### POST /api/template
Render a Home Assistant template. [See template docs for more information.](/topics/templating/)
@ -481,7 +475,7 @@ $ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
-d '{"template": "It is {{ now }}!"}' http://localhost:8123/api/template
```
#### {% linkable_title POST /api/event_forwarding %}
#### POST /api/event_forwarding
Set up event forwarding to another Home Assistant instance.
@ -503,7 +497,7 @@ It will return a message if event forwarding was set up successfully.
}
```
#### {% linkable_title DELETE /api/event_forwarding %}
#### DELETE /api/event_forwarding
Cancel event forwarding to another Home Assistant instance.<br>

12
docs/external_api_server_sent_events.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Server-sent events"
description: "Home Assistant Server-sent events documentation"
date: 2016-04-08 07:00
sidebar: true
comments: false
sharing: true
footer: true
---
The [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) feature is a one-way channel from your Home Assistant server to a client which is acting as a consumer. For bi-directional communication check the [RESTful API](/developers/rest_api/) and [Python API](/developers/python_api/).
@ -42,7 +36,7 @@ You can create a convenient view for this by creating an HTML file (`sse.html`)
Visit [http://localhost:8123/local/sse.html](http://localhost:8123/local/sse.html) to see the stream of events.
## {% linkable_title Examples %}
## Examples
A simple way to consume server-sent events is to use a command-line http client like [httpie](https://httpie.org/). Installation info is on the site (if you use Homebrew, it's `brew install httpie`). Once installed, run this snippet from your terminal:
@ -50,11 +44,11 @@ A simple way to consume server-sent events is to use a command-line http client
$ http --stream http://localhost:8123/api/stream x-ha-access:YOUR_PASSWORD content-type:application/json
```
### {% linkable_title Website %}
### Website
The [home-assistant-sse](https://github.com/fabaff/home-assistant-sse) repository contains a more advanced example.
### {% linkable_title Python %}
### Python
If you want to test the server-sent events without creating a website, the Python module [`sseclient` ](https://pypi.python.org/pypi/sseclient/) can help. To install (assuming Python and pip3 are already installed):

34
docs/external_api_websocket.md
View File

@ -1,25 +1,19 @@
---
layout: page
title: "WebSocket API"
description: "Home Assistant WebSocket API documentation"
date: 2016-11-26 13:27
sidebar: true
comments: false
sharing: true
footer: true
---
Home Assistant contains a WebSocket API. This API can be used to stream information from a Home Assistant instance to any client that implements WebSocket. Implementations in different languages:
- [JavaScript](https://github.com/home-assistant/home-assistant-js-websocket) - powers the frontend
- [Python](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket-client.py) - CLI client using [`asyncws`](https://async-websockets.readthedocs.io/en/latest/)
- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser
- [JavaScript/HTML](https://raw.githubusercontent.com/home-assistant/home-assistant-dev-helper/master/ha-websocket.html) - WebSocket connection in your browser
Connect your websocket implementation to `ws://localhost:8123/api/websocket`.
If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`websocket_api` component](/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API.
If you are not using the [`frontend`](/components/frontend/) in your setup then you need to add the [`websocket_api` component](/components/websocket_api/) to your `configuration.yaml` file to use the WebSocket API.
## {% linkable_title Server states %}
## Server states
1. Client connects.
1. Authentication phase starts.
@ -37,7 +31,7 @@ If you are not using the [`frontend`](/components/frontend/) in your setup then
During the command phase, the client attaches a unique identifier to each message. The server will add this identifier to each message so that the client can link each message to its origin.
## {% linkable_title Message format %}
## Message format
Each API message is a JSON serialized object containing a `type` key. After the authentication phase messages also must contain an `id`, an integer that contains the number of interactions.
@ -63,7 +57,7 @@ Example of an auth message:
}
```
## {% linkable_title Authentication phase %}
## Authentication phase
When a client connects to the server, the server will test if the client is authenticated. Authentication will not be necessary if no api_password is set or if the user fulfills one of the other criteria for authentication (trusted network, password in url/header).
@ -109,7 +103,7 @@ If the data is incorrect, the server will reply with `auth_invalid` message and
}
```
## {% linkable_title Command phase %}
## Command phase
During this phase the client can give commands to the server. The server will respond to each command with a `result` message indicating when the command is done and if it was successful.
@ -123,7 +117,7 @@ During this phase the client can give commands to the server. The server will re
}
```
## {% linkable_title Subscribe to events %}
## Subscribe to events
The command `subscribe_events` will subscribe your client to the event bus. You can either listen to all events or to a specific event type. If you want to listen to multiple event types, you will have to send multiple `subscribe_events` commands.
@ -196,7 +190,7 @@ For each event that matches, the server will send a message of type `event`. The
}
```
### {% linkable_title Unsubscribing from events %}
### Unsubscribing from events
You can unsubscribe from previously created subscription events. Pass the id of the original subscription command as value to the subscription field.
@ -219,7 +213,7 @@ The server will respond with a result message to indicate that unsubscribing was
}
```
### {% linkable_title Calling a service %}
### Calling a service
This will call a service in Home Assistant. Right now there is no return value. The client can listen to `state_changed` events if it is interested in changed entities as a result of a service call.
@ -247,7 +241,7 @@ The server will indicate with a message indicating that the service is done exec
}
```
### {% linkable_title Fetching states %}
### Fetching states
This will get a dump of all the current states in Home Assistant.
@ -269,7 +263,7 @@ The server will respond with a result message containing the states.
}
```
### {% linkable_title Fetching config %}
### Fetching config
This will get a dump of the current config in Home Assistant.
@ -291,7 +285,7 @@ The server will respond with a result message containing the config.
}
```
### {% linkable_title Fetching services %}
### Fetching services
This will get a dump of the current services in Home Assistant.
@ -313,7 +307,7 @@ The server will respond with a result message containing the services.
}
```
### {% linkable_title Fetching panels %}
### Fetching panels
This will get a dump of the current registered panels in Home Assistant.
@ -335,7 +329,7 @@ The server will respond with a result message containing the current registered
}
```
## {% linkable_title Error handling %}
## Error handling
If an error occurs, the `success` key in the `result` message will be set to `false`. It will contain an `error` key containing an object with two keys: `code` and `message`.

14
docs/frontend.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Frontend development"
description: "Tips and hints if you are starting on Home Assistant frontend development"
date: 2014-12-21 13:32
sidebar: true
comments: false
sharing: true
footer: true
---
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]
@ -15,7 +9,7 @@ Home Assistant is built on top of the [Polymer](https://www.polymer-project.org/
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.
</p>
## {% linkable_title Setting up the environment %}
## Setting up the environment
<p class='note'>
All commands below need to be run from inside the home-assistant-polymer repository.
@ -61,7 +55,7 @@ $ script/bootstrap
This script will use yarn and bower to install all the necessary dependencies necessary for development and do an initial build.
### {% linkable_title Creating pull requests %}
### Creating pull requests
If you're planning on issuing a PR back to the Home Assistant codebase you need to fork the polymer project and add your fork as a remote to the Home Assistant Polymer repo.
@ -77,7 +71,7 @@ $ git commit -m "Added new feature X"
$ git push -u <remote name> HEAD
```
## {% linkable_title Development %}
## Development
If you are changing `html` files under `/src` or `/panels` - just reload the page in your browser to see changes.
If you are changing javascript files under `/js` you need to have gulp running to watch the source files for changes and build when necessary.
@ -92,7 +86,7 @@ The source code for the frontend can be found in different directories:
- Panels: `/home-assistant-polymer/panels/`
- Javascript code: `/home-assistant-polymer/js/`
# {% linkable_title Building the Polymer frontend %}
# Building the Polymer frontend
Building a new version of the frontend is as simple as running `script/build_frontend`.
To use a built version package it: `python setup.py sdist`

6
docs/frontend_add_card.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Adding state card"
description: "Adding a state card to the frontend"
date: 2016-04-16 14:40 -07:00
sidebar: true
comments: false
sharing: true
footer: true
---
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 an icon, the name of the entity, when the state has last changed and the current state or a control to interact with it.

6
docs/frontend_add_more_info.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Adding more info dialogs"
description: "Adding a more info dialog to the frontend"
date: 2016-04-16 14:40 -07:00
sidebar: true
comments: false
sharing: true
footer: true
---
Whenever the user taps or clicks on one of the cards, a more info dialog will show. The header of this dialog will be the state card, followed by the history of this entity for the last 24 hours. Below this the more info component is rendered for that entity. The more info component can show more information or allow more ways of control.

12
docs/frontend_creating_custom_panels.md
View File

@ -1,19 +1,13 @@
---
layout: page
title: "Creating custom panels"
description: "Introduction to create custom panels for Home Assistant."
date: 2016-07-29 13:00
sidebar: true
comments: false
sharing: true
footer: true
---
Panels are pages within Home Assistant that show information within Home Assistant and can allow controlling it. Panels are linked from the sidebar and rendered full screen. The have have real-time access to the Home Assistant object via JavaScript. Examples of panels in the app are map, logbook and history.
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.
### {% linkable_title 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.
@ -24,7 +18,7 @@ frontend:
javascript_version: latest
```
### {% linkable_title Building your first panel %}
### Building your first panel
Create a file called `hello.html` in your <config dir>/panels/.
@ -45,7 +39,7 @@ The `hello.html` contains the needed building blocks to create the elements insi
<script>
class HaPanelHello extends Polymer.Element {
static get is() { return 'ha-panel-hello'; }
static get properties() {
return {
// Home Assistant object

9
docs/frontend_creating_custom_ui.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Creating custom UI"
description: "Introduction to create custom ui for Home Assistant."
date: 2017-02-04 13:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: 0.38
---
If you would like to use your own [State card](/developers/frontend_add_card/) without merging your code into [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer/) you can create your own implementation.
@ -70,7 +63,7 @@ frontend:
<script>
class StateCardMyCustomLight extends Polymer.Element {
static get is() { return 'state-card-my-custom-light'; }
static get properties() {
return {
// Home Assistant object

13
docs/hassio_addon_communication.md
View File

@ -1,18 +1,11 @@
---
layout: page
title: "Add-On Communication"
description: "Description of the internal communication of Hass.io."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_config/
---
There are different ways for communication between add-ons inside Hass.io.
## {% linkable_title Network %}
## Network
We use an internal network that allows to communicate with every add-on, even to/from Home Assistant, by using its name or alias. Only the add-ons which run on the host network are a bit limited. These can talk with all internal add-ons by their name but all other add-on can't address these add-on by name - using an alias works for both!
@ -21,7 +14,7 @@ The name is generated using the following format: `{REPO}_{SLUG}`, e.g., `local_
Use `hassio` for communication with the internal API.
## {% linkable_title Home Assistant %}
## Home Assistant
An add-on can talk to the [Home Assistant API][hass-api] using the internal proxy. That makes it very easy to communicate with the API without knowing the password, port or any other information of the Home Assistant instance. Use this URL: `http://hassio/homeassistant/api` and internal communication is redirected to the right place. The next stept is to add `homeassistant_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN` and use this as Home-Assistant password.
@ -31,7 +24,7 @@ It is also possible to talk direct to the Home Assistant instance which is named
We have severals services for Hass.io inside Home Assistant to run tasks. To send data over STDIN to an add-on use the `hassio.addon_stdin` service.
## {% linkable_title Hass.io API %}
## Hass.io API
To enables calls to the [Hass.io API][hassio-api], add `hassio_api: true` to `config.json` and read the environment variable `HASSIO_TOKEN`. Now you can use the API over the URL: `http://hassio/`. Use the `HASSIO_TOKEN` with header `X-HASSIO-KEY`.

19
docs/hassio_addon_config.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Add-On Configuration"
description: "Steps on how-to create an add-on for Hass.io."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_config/
---
Each add-on is stored in a folder. The file structure looks like this:
@ -24,7 +17,7 @@ addon_name/
run.sh
```
## {% linkable_title Add-on script %}
## Add-on script
As with every Docker container, you will need a script to run when the container is started. A user might run many add-ons, so it is encouraged to try to stick to Bash scripts if you're doing simple things.
@ -45,7 +38,7 @@ So if your `options` contain
```
then there will be a variable `TARGET` containing `beer` in the environment of your bash file afterwards.
## {% linkable_title Add-on Docker file %}
## Add-on Docker file
All add-ons are based on Alpine Linux 3.6. Hass.io will automatically substitute the right base image based on the machine architecture. Add `tzdata` if you need run in a different timezone. `tzdata` Is is already added to our base images.
@ -72,7 +65,7 @@ LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64
It is possible to use own base image with `build.json` or if you do not need support for automatic multi-arch building you can also use a simple docker `FROM`.
### {% linkable_title Build Args %}
### Build Args
We support the following build arguments by default:
@ -82,7 +75,7 @@ We support the following build arguments by default:
| BUILD_VERSION | Add-on version (read from `config.json`).
| BUILD_ARCH | Hold current build arch inside.
## {% linkable_title Add-on config %}
## Add-on config
The config for an add-on is stored in `config.json`.
@ -140,7 +133,7 @@ The config for an add-on is stored in `config.json`.
| timeout | integer | no | Default 10 (second). The timeout to wait until the docker is done or will be killed.
| tmpfs | string | no | Mount a tmpfs file system in `/tmpfs`. Valide format for this option is : `size=XXXu,uid=N,rw`. Size is mandatory, valid units (`u`) are `k`, `m` and `g` and `XXX` has to be replaced by a number. `uid=N` (with `N` the uid number) and `rw` are optional.
### {% linkable_title Options / Schema %}
### Options / Schema
The `options` dictionary contains all available options and their default value. Set the default value to `null` if the value is required to be given by the user before the add-on can start, and it show it inside default values. Only nested arrays and dictionaries are supported with a deep of two size. If you want make an option optional, put `?` to the end of data type, otherwise it will be a required value.
@ -184,7 +177,7 @@ We support:
- port
- match(REGEX)
## {% linkable_title Add-on extended build %}
## Add-on extended build
Additional build options for an add-on is stored in `build.json`. This file will be read from our build systems.

7
docs/hassio_addon_development.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Developing an add-on"
description: "Steps on how-to create an add-on for Hass.io."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_development/
---
Add-ons for Hass.io allow the user to extend the functionality around Home Assistant. This can be running an application that Home Assistant can integrate with (like an MQTT broker) or to share the configuration via Samba for easy editing from other computers. Add-ons can be configured via the Hass.io panel in Home Assistant.

14
docs/hassio_addon_presentation.md
View File

@ -1,17 +1,11 @@
---
layout: page
title: "Presenting your add-on"
description: "Details on how to present your Hass.io add-on."
date: 2018-01-24 22:15
sidebar: true
comments: false
sharing: true
footer: true
---
If you decide to share your add-on to the public, paying attention to details is recommended. Of course, your add-on should have a proper name and description, but Hass.io also gives you some other tools to present your add-on even nicer.
## {% linkable_title Adding documentation %}
## Adding documentation
Good documentation helps the consumer of your add-on to understand its usage, explains configuration options, points users in the right direction in the case they have questions or issues, and contains the license under which the add-on was published.
@ -21,7 +15,7 @@ Take a look at other projects for inspiration. For example, see the `README.md`
In future versions of Hass.io, the `README.md` file will be displayed in the Home Assistant frontend.
## {% linkable_title Add-on icon & logo %}
## Add-on icon & logo
A picture is worth a thousand words. Therefore, your add-on can be improved by adding a proper image icon and logo. Those images are used when showing your add-on in the Home Assistant Hass.io panel and which will significantly improve the visual representation of your add-on.
@ -38,7 +32,7 @@ Requirements for the icon of your add-on:
- The aspect ratio of the icon must be 1x1 (square).
- It is recommended to use an icon size of 128x128px.
## {% linkable_title Keeping a changelog %}
## Keeping a changelog
It is likely you are going to release newer versions of your add-on in the future. In case that happens, the users of your add-on would see an upgrade notice and probably want to know what changes were made in the latest version.
@ -48,6 +42,6 @@ If you are in need of a guide on keeping a changelog, we would recommend checkin
In future versions of Hass.io, the `CHANGELOG.md` file will be displayed in the Home Assistant frontend.
## {% linkable_title Extended Security %}
## Extended Security
You can use own security profile for you Add-on with Seccomp or AppArmor. Default it is enabled and use the docker default profile. Put `apparmor` or `seccomp.json` file into your Add-on folder and it will load this file as primary profile.

15
docs/hassio_addon_publishing.md
View File

@ -1,30 +1,23 @@
---
layout: page
title: "Publishing your add-on"
description: "Steps on how-to create an add-on for Hass.io."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_publishing/
---
There are two different ways of publishing add-ons. One is to publish pre-build containers to Docker Hub and the other option is to have users build the containers locally on their Hass.io instance.
#### {% linkable_title Pre-build containers %}
#### Pre-build containers
With pre-build containers, the developer is responsible for building the images for each architecture on their machine and push the results out to Docker Hub. This has a lot of advantages for the user. As a user it will only have to download the final container and be up and running once the download finishes. This makes the installation process fast and almost no chance of failure. This is the preferred method.
We have automated the process of building and publishing add-ons. See below for the instructions.
#### {% linkable_title Locally build containers %}
#### Locally build containers
Starting Hass.io 0.26, it is possible to distribute add-ons that will be built on the users machine. The advantage is that as a developer it is easy to test an idea and see if people are interested in your add-ons. This method includes installing and potentially compiling code. This means that installing such an add-on is slow and adds more wear and tear to users SD card/hard drive than the above mentioned pre-build solution. It also has a higher chance of failure if one of the dependencies of the container has changed or is no longer available.
Use this option when you are playing with add-ons and seeing if someone is interested in your work. Once you're an established repository, please migrate to pushing builds to Docker Hub as it greatly improves the user experience. In the future we will mark locally built add-ons in the add-on store to warn users.
## {% linkable_title Build scripts to publish add-ons to Docker Hub %}
## Build scripts to publish add-ons to Docker Hub
All add-ons are simple docker containers. Inside your add-on `config.json` you specify the Docker image that will be installed for your add-on:
@ -42,7 +35,7 @@ You can use `{arch}` inside the image name to support multiple architectures wit
Hass.io assumes that the `master` branch of your add-on repository matches the latest tag on Docker Hub. When you're building a new version, it's suggested that you use another branch, ie `build` or do it with a PR on GitHub. After you push the add-on to [Docker Hub](https://hub.docker.com/), you can merge this branch to master.
## {% linkable_title Custom Add-ons %}
## Custom Add-ons
You need a Docker Hub account to make your own add-ons. You can build your docker images with docker `build` command or use our script that make it simple. Pull our [builder docker engine][builder] and run one of the following commands.

11
docs/hassio_addon_repository.md
View File

@ -1,24 +1,17 @@
---
layout: page
title: "Create an add-on repository"
description: "Add-ons repositories."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_repository/
---
An add-on repository can contain one or more add-ons. Each add-on is stored in its own unique folder. To be indentified as a repository, the repository must contain a configuration file.
Check the [Example add-on repository](https://github.com/home-assistant/hassio-addons-example) for further details.
## {% linkable_title Installing a repository %}
## Installing a repository
A user can add a repository by going to the Hass.io panel in Home Assistant, clicking on the store icon in the top right, copy/paste the URL of your repostory into the repository textarea and click on **Save**.
## {% linkable_title Repository configuration %}
## Repository configuration
Each repository is required to contain `repository.json` at the root in the git repository.

13
docs/hassio_addon_testing.md
View File

@ -1,20 +1,13 @@
---
layout: page
title: "Local add-on testing"
description: "Instructions on how to test your add-on locally."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_testing/
---
The fastest way to develop add-ons is by adding them to your local add-on repository. To access your local add-on repository, install either the [Samba add-on] or [SSH add-on].
Right now add-ons will work with images that are stored on Docker Hub (using `image` from add-on config). Without `image` inside local add-ons repository it to be built on the device.
## {% linkable_title Local build %}
## Local build
You can build and try the addon on your developer machine also. Move all addon stuff into a temp folder. If you use `FROM $BUILD_FROM` you need set a base image with build args. Normally you can use follow base images:
@ -25,11 +18,11 @@ You can build and try the addon on your developer machine also. Move all addon s
Use `docker` to build the test addon: `docker build --build-arg BUILD_FROM="homeassistant/amd64-base:latest" -t local/my-test-addon .`
## {% linkable_title Local run %}
## Local run
Create a new folder for data and add a test _options.json_ file. After that you can run your add-on with: `docker run --rm -v /tmp/my_test_data:/data -p PORT_STUFF_IF_NEEDED local/my-test-addon`
## {% linkable_title Logs %}
## Logs
All stdout and stderr are redirected to the Docker logs. The logs can be fetched from the add-on page inside the Hass.io panel in Home Assistant.

19
docs/hassio_addon_tutorial.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Tutorial: Making your first add-on"
description: "Easy tutorial to get started making your first add-on."
date: 2017-05-12 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/addon_tutorial/
---
So you've got Home Assistant going and you've been enjoying the built-in add-ons but you're missing this one application. Time to make your own add-on! In Hass.io 0.24 we introduced the option to have local add-ons be build on your device. This is great for developing new add-ons locally.
@ -34,7 +27,7 @@ Once you have located your add-on directory, it's time to get started!
[ssh]: /addons/ssh/
## {% linkable_title Step 1: The basics %}
## Step 1: The basics
- Create a new directory called `hello_world`
- Inside that directory create three files.
@ -72,7 +65,7 @@ CMD [ "/run.sh" ]
echo Hello world!
```
## {% linkable_title Step 2: Installing and testing your add-on %}
## Step 2: Installing and testing your add-on
Now comes the fun part, time to open the Hass.io UI and install and run your add-on.
@ -103,7 +96,7 @@ The Hass.io add-on store will list all available local add-ons.
The add-on will print Hello world to the logs and then quit.
</p>
### {% linkable_title I don't see my add-on?! %}
### I don't see my add-on?!
Oops! You clicked refresh in the store and your add-on didn't show up. Or maybe you just updated an option, clicked refresh and saw your add-on disappear.
@ -111,7 +104,7 @@ When this happens, it means that your `config.json` is invalid. It's either inva
Once you fixed the error, go to the add-on store and click refresh again.
## {% linkable_title Step 3: Hosting a server %}
## Step 3: Hosting a server
Until now we've been able to do some basic stuff, but it's not very useful yet. So let's take it one step further and host a server that we expose on a port. For this we're going to use the built-in HTTP server that comes with Python 3.
@ -156,7 +149,7 @@ Update `run.sh` to start the Python 3 server:
python3 -m http.server
```
## {% linkable_title Step 4: Installing the update %}
## Step 4: Installing the update
Since we updated the version number in our `config.json`, Home Assistant will show an update button when looking at the add-on details. You might have to refresh your browser or click the refresh button in the add-on store for it to show up. If you did not update the version number, you can also uninstall and install the add-on again. After installing the add-on again, make sure you start it.
@ -167,7 +160,7 @@ Now navigate to [http://hassio.local:8000](http://hassio.local:8000) to see our
The Python 3 server will allow you to browse the /data folder.
</p>
## {% linkable_title Bonus: Working with add-on options %}
## Bonus: Working with add-on options
In the screenshot you've probably seen that our server only served up 1 file: `options.json`. This file contains the user configuration for this add-on. Because we specified an empty "config" and "schema" in our `config.json`, the file is currently empty.

15
docs/hassio_architecture.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Hass.io Architecture"
description: "The architecture of Hass.io."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/architecture/
---
<p class='img'>
@ -15,7 +8,7 @@ redirect_from: /hassio/architecture/
Architecture overview of Hass.io
</p>
### {% linkable_title Host Control (HC) %}
### Host Control (HC)
This is a daemon running on the host machine that allows the supervisor to control certain aspects of the host OS:
@ -23,15 +16,15 @@ This is a daemon running on the host machine that allows the supervisor to contr
- Manage network settings
- Local updates
### {% linkable_title Host %}
### Host
Our pre-build images are based on [ResinOS]. Any Linux machine can be turned into a Hass.io host by running [the installer][linux].
### {% linkable_title Supervisor %}
### Supervisor
The supervisor offers an API to manage the host and running the Docker containers.
### {% linkable_title Configuration panel %}
### Configuration panel
The configuration panel lives inside the supervisor but is accessible via the Home Assistant user interface. The configuration panel allows the user to manage the installation.

13
docs/hassio_debugging.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Debugging Hass.io"
description: "Tips and tricks for when things go wrong."
date: 2017-04-30 13:28
sidebar: true
comments: false
sharing: true
footer: true
redirect_from: /hassio/debugging/
---
<p class='note warning'>
@ -18,7 +11,7 @@ This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is
The following debug tips and tricks are for people who are running the Hass.io image and are working on the base image. If you use the generic Linux installer script, you should be able to access your host and logs as per your host.
## {% linkable_title SSH access to the host %}
## SSH access to the host
Create an `authorized_keys` file containing your public key, and place it in the root of the boot partition of your SD card. Once the device is booted, you can access your device as root over SSH on port 22222.
@ -32,14 +25,14 @@ Step 3 in the link above, shows the path to the private key file `id_rsa` for yo
<p class='note'>
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.
</p>
</p>
You should then be able to SSH into your Hass.io device. On mac/linux, use:
```
ssh root@hassio.local -p 22222
```
## {% linkable_title Checking the logs %}
## Checking the logs
```bash
# Logs from the supervisor service on the Host OS

7
docs/index.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Developers"
description: "Everything you need to know to get started with Home Assistant development."
date: 2016-04-16 10:28 +07:00
sidebar: true
comments: false
sharing: true
footer: true
og_image: /images/architecture/component_interaction.png
---
Welcome to the Home Assistant development documentation. This is the place to learn all about how Home Assistant works and how you can extend it with support for your devices and services!

6
docs/intent_conversation.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Registering sentences"
description: "Register sentences with the conversation component."
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
The conversation component handles incoming commands from the frontend and converts them to intents. It does this based on registered sentences.

6
docs/intent_firing.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Firing intents"
description: "How to fire intents to be handled by Home Assistant."
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
When you fire an intent, you will get a response back or an error will be raised. It is up to the component to return the result to the user.

6
docs/intent_handling.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Handling intents"
description: "How to handle intents that are fired in Home Assistant."
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
Any component can register to handle intents. This allows a single component to handle intents fired from multiple voice assistants.

6
docs/intent_index.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Intents"
description: "Intents are helping Home Assistant to gather "
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
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.

13
docs/internationalization_backend_localization.md
View File

@ -1,16 +1,9 @@
---
layout: page
title: "Backend Localization"
description: "Translating platforms in Home Assistant"
date: 2018-03-01 18:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: 0.64
---
## {% linkable_title Translation Strings %}
## Translation Strings
Platform translation strings are stored as JSON in the [home-assistant](https://github.com/home-assistant/home-assistant) repository. These files must be located adjacent to the component/platform they belong to. Components must have their own directory, and the file is simply named `strings.json` in that directory. For platforms, they are named `strings.<platform name>.json` in the platform directory. This file will contain the different strings that will be translatable.
In order to test changes to translation files, the translation strings must be compiled into Home Assistant’s translation directories by running the following script:
@ -21,10 +14,10 @@ $ script/translations_develop
After the pull request with the strings file is merged into the `dev` branch, the strings will be automatically uploaded to Lokalise, where contributors can submit translations. The translated strings in Lokalise will be periodically pulled in to the home-assistant repository.
## {% linkable_title States Localization %}
## States Localization
The first step when localizing platform states is to ensure that the states defined in the actual platform code are defined in `snake_case`. The states should not contain capital letters or spaces. Next, the strings file needs to be created. The states should exist under the `state` key, and map the backend state keys to their English translations. [The season sensor localization](https://github.com/home-assistant/home-assistant/pull/12453/commits/bb2f328ce10c3867990e34a88da64e2f8dc7a5c4) is a good example.
## {% linkable_title Configuration Flow Localization %}
## Configuration Flow Localization
The translation strings for the configuration flow handler are defined under the `config` key. An example strings file below describes the different supported keys:
```json

9
docs/internationalization_custom_component_localization.md
View File

@ -1,16 +1,9 @@
---
layout: page
title: "Custom Component Localization"
description: "Translating custom components in Home Assistant"
date: 2018-03-01 18:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: 0.64
---
## {% linkable_title Translation Strings %}
## Translation Strings
Unlike localized strings merged in the home-assistant repository, custom components cannot take advantage of Lokalise for user submitted translations. However, custom component authors can still include translation with their components. These will be read from the `.translations` directory, adjacent to the component source file. They are named `<component/platform name>.<language_code>.json`, unless the custom component exists in its own directory, in which case the file is simply named `<language_code>.json` in the `.translations` directory.
These files follow the same formatting as [backend translation string files](/developers/internationalization/backend_localization/), but a copy will exist for each translated language.

7
docs/internationalization_index.md
View File

@ -1,13 +1,6 @@
---
layout: page
title: "Internationalization"
description: "Home Assistant internationalization summary"
date: 2018-03-01 18:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: 0.64
---
The Home Assistant internationalization project includes preparing platforms and the frontend for localization, as well as the actual translation of localized strings.

18
docs/internationalization_translation.md
View File

@ -1,17 +1,9 @@
---
layout: page
title: "Translation"
description: "How to translate Home Assistant."
date: 2017-10-27 13:00
sidebar: true
comments: false
sharing: true
footer: true
ha_release: 0.57
redirect_from: /developers/frontend_translation/
---
## {% linkable_title How to start %}
## How to start
Translations for Home Assistant are managed through Lokalise, an online translation management tool. Our translations are split between two projects, a backend project for platform-specific translations, and a frontend project for UI translations. Click the links below to join both projects! Even if your language is completely translated, extra proofreading is a big help! Please feel free to review the existing translations, and vote for alternatives that might be more appropriate.
- [Join the frontend translation team](https://lokalise.co/signup/3420425759f6d6d241f598.13594006/all/)
@ -23,11 +15,11 @@ For more information about the translation workflow, please see the [Lokalise tr
The translation of the Home Assistant frontend is still a work in progress. More phrases will be available for translation soon.
</p>
## {% linkable_title Translation placeholders %}
## Translation placeholders
Some translation strings will contain special placeholders that will be replaced later. Placeholders shown in square brackets `[]` are [Lokalise key references](https://docs.lokalise.co/article/KO5SZWLLsy-key-referencing). These are primarily used to link translation strings that will be duplicated. Different languages may not have the same duplicates as English, and are welcome to link duplicate translations that are not linked in English. Placeholders shown in curly brackets `{}` are [translation arguments](https://formatjs.io/guides/message-syntax/) that will be replaced with a live value when Home Assistant is running. Any translation argument placeholders present in the original string must be included in the translated string. These may include special syntax for defining plurals or other replacement rules. The linked format.js guide explains the syntax for adding plural definitions and other rules.
## {% linkable_title Rules %}
## Rules
1. Only native speakers should submit translations.
2. Stick to [Material Design guidelines](https://material.io/guidelines/style/writing.html).
3. Don't translate or change proper nouns like `Home Assistant`, `Hass.io` or `Hue`.
@ -35,7 +27,7 @@ Some translation strings will contain special placeholders that will be replaced
5. Translations under the `state_badge` keys will be used for the notification badge display. These translations should be short enough to fit in the badge label without overflowing. This can be tested in the Home Assistant UI either by editing the label text with your browsers development tools, or by using the States <img src='/images/screenshots/developer-tool-states-icon.png' alt='' class="no-shadow" height="38" /> developer tool in the Home Assistant UI. In the UI, enter a new entity ID (`device_tracker.test`), and enter the text you want to test in state.
6. If text will be duplicated across different translation keys, make use of the Lokalise key reference feature where possible. The base translation provides examples of this underneath the `states` translations. Please see the [Lokalise key referencing](https://docs.lokalise.co/article/KO5SZWLLsy-key-referencing) documentation for more details.
## {% linkable_title Adding a new language %}
## Adding a new language
If your language is not listed you can request it at [GitHub](https://github.com/home-assistant/home-assistant-polymer/issues/new). Please provide both the English name and the native name for your language. For example:
```
English Name: German
@ -46,7 +38,7 @@ 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.
</p>
### {% linkable_title Maintainer steps to add a new language %}
### 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.
2. Add the language tag and native name in `src/translations/translationMetadata.json`. Examples: "Français", "Français (CA)"
3. Add the new language in Lokalize.

18
docs/maintenance.md
View File

@ -1,19 +1,13 @@
---
layout: page
title: "Maintenance"
description: "Steps involved to maintain the current state of Home Assistant."
date: 2016-09-13 17:00
sidebar: true
comments: false
sharing: true
footer: true
---
This page documents a couple of points for maintaining the Home Assistant code. Most of the tasks don't need to be performed on a regular base thus the steps, used tools, or details are preserved here.
## {% linkable_title Source code %}
## Source code
### {% linkable_title Line separator %}
### Line separator
People are using various operating systems to develop components and platforms for Home Assistant. This could lead to different line endings on file. We prefer `LN`. Especially Microsoft Windows tools tend to use `CRLF`.
@ -28,24 +22,24 @@ To fix the line separator, use `dos2unix` or `sed`.
$ dos2unix homeassistant/components/notify/kodi.py
```
### {% linkable_title File permissions %}
### File permissions
Most files don't need to the be executable. `0644` is fine.
### {% linkable_title Dependencies %}
### Dependencies
A lot of components and platforms depends on third-party Python modules. The dependencies which are stored in the `requirements_*.txt` files are tracked by [gemnasium](https://gemnasium.com/github.com/home-assistant/home-assistant) and [Requires.io](https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev).
If you update the requirements of a component/platform through the `REQUIREMENTS = ['modules-xyz==0.3']` entry, run the provided script to update the `requirements_*.txt` file(s).
```bash
$ script/gen_requirements_all.py
$ script/gen_requirements_all.py
```
Start a test run of Home Assistant. If that was successful, include all files in a Pull Request. Add a short summary of the changes, a sample configuration entry, details about the tests you performed to ensure the update works, and other useful information to the description.
## {% linkable_title Documentation %}
## Documentation
- Merge `current` into `next` on a regular base.
- Optimize the images.

8
docs/platform_example_light.md
View File

@ -1,12 +1,6 @@
---
layout: page
title: "Example light platform"
description: "Minimum implementation of a Home Assistant platform."
date: 2016-04-16 14:24 -07:00
sidebar: true
comments: false
sharing: true
footer: true
---
This example is for adding support for the imaginary Awesome Lights. It shows the different best practices for developing a platform.
@ -53,7 +47,7 @@ def setup_platform(hass, config, add_devices, discovery_info=None):
import awesomelights
# Assign configuration variables. The configuration check takes care they are
# present.
# present.
host = config.get(CONF_HOST)
username = config.get(CONF_USERNAME)
password = config.get(CONF_PASSWORD)

10
docs/platform_example_sensor.md
View File

@ -1,17 +1,11 @@
---
layout: page
title: "Example sensor platform"
description: "Minimum implementation of a Home Assistant platform."
date: 2016-04-16 14:24 -07:00
sidebar: true
comments: false
sharing: true
footer: true
---
This is a minimum implementation of a platform for the sensor component.
### {% linkable_title Installation %}
### Installation
Copy the code below and create it as a file in `<config_dir>/custom_components/sensor/example.py`.
@ -23,7 +17,7 @@ sensor:
platform: example
```
### {% linkable_title Code %}
### Code
```python
from homeassistant.const import TEMP_CELSIUS

26
docs/releasing.md
View File

@ -1,36 +1,30 @@
---
layout: page
title: "Releasing"
description: "Steps involved publishing a new Home Assistant release."
date: 2016-07-13 17:00
sidebar: true
comments: false
sharing: true
footer: true
---
This page describes the steps for publishing a new Home Assistant release. Those steps requires that you don't use forks but work with the repositories themself. The [hass-release](https://github.com/home-assistant/hass-release) script is a helper to do a release.
### {% linkable_title Release preparation (3 days before release) %}
### Release preparation (3 days before release)
### {% linkable_title GitHub %}
### GitHub
1. Merge `master` into `dev` to make the PR mergeable.
1. Cut a release branch from `dev`. Example name `release-0-57`.
1. Create a pull request from the release branch to `master` with the upcoming release number as the title.
1. Update `homeassistant/const.py` with the correct version number (remove the `dev` tag) and push that commit to release branch.
### {% linkable_title Website %}
### Website
1. Merge `current` into `next`
1. Cut release branch of `next`. For example `release-0-57`.
1. Open a PR from release branch to `current` with the upcoming release number as the title.
## {% linkable_title Release day %}
## Release day
From creating the release branch till it has been merged, we tag bugfixes with the milestone for the release (create if doesn't exist).
### {% linkable_title GitHub %}
### GitHub
1. Cherry-pick the milestoned PRs that need to get into the release `python3 -m hassrelease milestone_cherry_pick 0.57`
1. Run `python3 -m hassrelease release_notes 0.56` for the release notes.
@ -40,7 +34,7 @@ From creating the release branch till it has been merged, we tag bugfixes with t
1. Merge `master` into `dev`.
1. Update `homeassistant/const.py` with the upcoming version number (including the `dev` tag) and push that commit to the `dev` branch.
### {% linkable_title Website %}
### Website
1. Create a blog post in the release branch and base it on the text of the PR in the main repository. Add images, additional text, links, etc. if it adds value. Tag each platform/component in a message to documentation.
1. Create missing documentation as stubs.
@ -50,19 +44,19 @@ From creating the release branch till it has been merged, we tag bugfixes with t
1. Merge pull request (blog post, updated frontpage, and all new documentation) to `current`. DO NOT SQUASH!
1. Merge `current` into `next`.
### {% linkable_title Docker Hub %}
### Docker Hub
Tags on Docker hub are automatically created when a release has been created on GitHub.
### {% linkable_title Python Package Index %}
### Python Package Index
Checkout the `master` branch and run `script/release` to publish the new release on [Python Package Index](https://pypi.python.org).
### {% linkable_title Social media %}
### Social media
1. Use [hootsuite](https://hootsuite.com/dashboard) to publish a link to the release post on social media.
## {% linkable_title Bugfix Release %}
## Bugfix Release
1. Checkout `master` and update it. `git checkout master && git pull --rebase`
1. Create a new release branch from `master`. `git checkout -b release-0-56-2`

1
website/i18n/en.json
View File

@ -72,6 +72,7 @@
"releasing": "Releasing",
"Developers": "Developers",
"Catch all category": "Catch all category",
"Maintainer docs": "Maintainer docs",
"Creating Platforms": "Creating Platforms",
"Creating Components": "Creating Components",
"Documentation": "Documentation",