jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-13 20:36:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'current' into rc

Browse Source
This commit is contained in:
Paulus Schoutsen 2018-04-26 11:18:38 -04:00
commit 4dc03338a9
90 changed files with 466 additions and 4185 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
_config.yml
View File

@ -146,7 +146,7 @@ date_released: 2018-04-27
# Either # or the anchor link to latest release notes in the blog post.
# Must be prefixed with a # and have double quotes around it.
# Major release:
patch_version_notes: "#"
patch_version_notes: "#release-0671---april-17"
# Minor release (Example #release-0431---april-25):
# Date we moved to Discourse for comments

32
sass/custom/_paulus.scss
View File

@ -4,6 +4,10 @@ $primary-color: #049cdb;
.site-header {
position: relative;
.site-title {
font-weight: normal;
}
}
.search-container {
@ -377,18 +381,26 @@ p.note {
}
.copyright {
text-align: center;
text-align: left;
i {
font-size: 3em;
margin-right: 8px;
position: relative;
top: -5px;
.company {
.title {
font-size: 1.5em;
}
img {
vertical-align: middle;
}
i {
font-size: 2em;
padding: 0 5px;
}
}
.credit {
text-align: left;
display: inline-block;
font-size: .8em;
ul {
margin: 0;
list-style: none;
}
}

6
source/_components/dyson.markdown
View File

@ -26,9 +26,9 @@ dyson:
password: YOUR_DYSON_PASSWORD
language: YOUR_DYSON_ACCOUNT_LANGUGAGE
devices:
- device_id: DEVICE_ID_1 # eg: Pure Cool Link device
- device_id: DEVICE_ID_1 # eg. Serial number: XXX-XX-XXXXXXXX
device_ip: DEVICE_ID_1
- device_id: DEVICE_ID_2 # eg: Eye 360 robot vacuum
- device_id: DEVICE_ID_2
device_ip: DEVICE_ID_2
```
@ -38,7 +38,7 @@ Configuration variables:
- **password** (*Required*): Dyson account password.
- **language** (*Required*): Dyson account language country code. Known working codes: `FR`, `NL`, `GB`, `AU`. But others codes should work.
- **devices** (*Optional*): List of devices.
- **device_id** (*Required*): Device ID. Available in the mobiles applications (*Settings* page).
- **device_id** (*Required*): Device ID. The Serial Number of the device. Found in the mobiles applications device settings page.
- **device_ip** (*Required*): Device IP address.
`devices` list is optional but you'll have to provide them if discovery is not working (warnings in the logs and the devices are not available in Home Assistant web interface).

8
source/_components/google_assistant.markdown
View File

@ -13,6 +13,10 @@ featured: true
ha_release: 0.56
---
<p class='note'>
Use [Home Assistant Cloud](/cloud/) to integrate with Google Assistant without any effort.
</p>
The `google_assistant` component allows you to control things via Google Assistant (on your mobile or tablet) or a Google Home device.
The Google Assistant component requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.
@ -102,7 +106,7 @@ entity_config:
required: false
type: list
room:
description: Allows for associating this device to a Room in Google Assistant. This is currently non-functional, but will be enabled in the near future.
description: Allows for associating this device to a Room in Google Assistant.
required: false
type: string
{% endconfiguration %}
@ -134,7 +138,7 @@ If you're not using Linux, you can use sites such as [this one](https://www.brow
1. Create a new project in the [developer console](https://console.actions.google.com/).
a. Add/Import project
b. Click on `BUILD` on the `Smart home` card
c. Type in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable.
c. Type in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable.
d. Click `Done`. Then click on `Overview`, which will lead you to the app details screen.
2. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant.
3. The final item on that page `Account linking` is required for your app to interact with Home Assistant.

6
source/_components/homekit.markdown
View File

@ -12,7 +12,7 @@ ha_release: 0.64
logo: apple-homekit.png
---
The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they could be controlled from Apple `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later.
The `HomeKit` component allows you to forward entities from Home Assistant to Apple `HomeKit`, so they can be controlled from Apple's `Home` app and `Siri`. Please make sure that you have read the [considerations](#considerations) listed below to save you some trouble later.
<p class="note warning">
It might be necessary to install an additional package:
@ -87,7 +87,7 @@ To enable the `HomeKit` component in Home Assistant, add the following to your c
homekit:
```
After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if the are [supported](#supported-components). To add them:
After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if they are [supported](#supported-components). To add them:
1. Open the Home Assistant frontend. A new card will display the `pin code`.
1. Open the `Home` app.
2. Choose `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and enter the `pin code`.
@ -107,7 +107,7 @@ Currently this component uses the `entity_id` to generate a unique `accessory id
### {% linkable_title Persistence Storage %}
Unfortunately `HomeKit` doesn't support any kind of persistence storage, only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)
Unfortunately `HomeKit` doesn't support any kind of persistent storage - only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.)
A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable `auto start` and `turn off` the `Start HomeKit` automation (if you have one).

2
source/_components/sensor.sabnzbd.markdown
View File

@ -68,7 +68,7 @@ Note that this will create the following sensors:
- sensor.sabnzbd_left
- sensor.sabnzbd_disk
- sensor.sabnzbd_disk_free
- sensor.sabnzdb_queue_count
- sensor.sabnzbd_queue_count
```
As always, you can determine the names of sensors by looking at the dev-state page `< >` in the web interface.

2
source/_components/switch.raincloud.markdown
View File

@ -25,7 +25,7 @@ switch:
Configuration variables:
- **watering_minutes** (*Optional*): Value in minutes to watering your garden via frontend. Defaults to 15.
- **watering_minutes** (*Optional*): Value in minutes to watering your garden via frontend. Defaults to 15. The values allowed are: 5, 10, 15, 30, 45, 60.
- **monitored_conditions** array (*Optional*): Conditions to display in the frontend. If not specified, all conditions below will be enabled by default. The following conditions can be monitored.
- **auto_watering**: Toggle the watering scheduled per zone.
- **manual_watering**: Toggle manually the watering per zone. It will inherent the value in minutes specified on the RainCloud hub component.

2
source/_components/thethingsnetwork.markdown
View File

@ -20,7 +20,7 @@ The Things network support various integrations to make the data available:
| The Things Network Integration | Home Assistant platform |
|---|---|
| [MQTT](https://www.thethingsnetwork.org/docs/applications/mqtt/) | |
| [Storage](https://www.thethingsnetwork.org/docs/applications/storage/) | [`thethingsnetwork`](/component/sensor.thethingsnetwork/) |
| [Storage](https://www.thethingsnetwork.org/docs/applications/storage/) | [`thethingsnetwork`](/components/sensor.thethingsnetwork/) |
| [HTTP](https://www.thethingsnetwork.org/docs/applications/http/) | |
### {% linkable_title Setup %}

142
source/_includes/asides/developers_navigation.html
View File

@ -1,142 +0,0 @@
<section class="aside-module grid__item one-whole lap-one-half">
{% include edit_github.html %}
<div class='section'>
<h1 class="title delta">Development Guide</h1>
<ul class='divided sidebar-menu'>
<li>
{% active_link /developers/ Introduction %}
<ul>
<li>{% active_link /developers/architecture/ Architecture %}</li>
<li>{% active_link /developers/architecture_components/ Components %}</li>
</ul>
</li>
<li>
{% active_link /developers/development/ Starting with Development %}
<ul>
<li>{% active_link /developers/development_environment/ Setting up Environment %}</li>
<li>{% active_link /developers/development_submitting/ Submit your Work %}</li>
<li>{% active_link /developers/development_checklist/ Checklist %}</li>
<li>{% active_link /developers/development_guidelines/ Style guidelines %}</li>
<li>{% active_link /developers/development_testing/ Testing %}</li>
<li>{% active_link /developers/development_catching_up/ Catching up with Reality %}</li>
<li>{% active_link /developers/development_validation/ Validation %}</li>
</ul>
</li>
<li>
{% active_link /developers/development_101/ Development 101 %}
<ul>
<li>{% active_link /developers/development_hass_object/ Hass object %}</li>
<li>{% active_link /developers/development_events/ Events %}</li>
<li>{% active_link /developers/development_states/ States %}</li>
<li>{% active_link /developers/development_services/ Services %}</li>
<li>{% active_link /developers/development_config/ Config %}</li>
</ul>
</li>
<li>
{% active_link /developers/add_new_platform/ Creating a new platform (to support a new device) %}
<ul>
<li>{% active_link /developers/code_review_platform/ Checklist creating a platform %}</li>
<li>{% active_link /developers/platform_example_sensor/ Example sensor platform %}</li>
<li>{% active_link /developers/platform_example_light/ Example light platform %}</li>
</ul>
</li>
<li>
{% active_link /developers/creating_components/ Adding a new component %}
<ul>
<li>{% active_link /developers/code_review_component/ Checklist creating a component %}</li>
<li>{% active_link /developers/component_loading/ Loading components %}</li>
<li>{% active_link /developers/component_deps_and_reqs/ Requirements & Dependencies %}</li>
<li>{% active_link /developers/component_events/ Handling events %}</li>
<li>{% active_link /developers/component_states/ States %}</li>
<li>{% active_link /developers/component_visibility/ Visibility %}</li>
<li>{% active_link /developers/component_generic_discovery/ Loading Platforms %}</li>
<li>{% active_link /developers/component_discovery/ Component Discovery %}</li>
</ul>
</li>
<li>
{% active_link /developers/intent/ Intents (handling voice responses) %}
<ul>
<li>{% active_link /developers/intent/firing/ Firing intents %}</li>
<li>{% active_link /developers/intent/handling/ Handling intents %}</li>
<li>{% active_link /developers/intent/conversation/ Registering sentences %}</li>
</ul>
</li>
<li>
{% active_link /developers/asyncio/ Asynchronous Programming %}
<ul>
<li>{% active_link /developers/asyncio_101/ Introduction to asyncio %}</li>
<li>{% active_link /developers/asyncio_categorizing_functions/ Categorizing Functions %}</li>
<li>{% active_link /developers/asyncio_working_with_async/ Working with Async %}</li>
<li>{% active_link /developers/asyncio_misc/ Miscellaneous %}</li>
</ul>
</li>
<li>
{% active_link /developers/frontend/ Frontend Development %}
<ul>
<li>{% active_link /developers/frontend_add_card/ Add State Card %}</li>
<li>{% active_link /developers/frontend_add_more_info/ Add More Info Dialog %}</li>
<li>{% active_link /developers/frontend_creating_custom_panels/ Add Custom Panels %}</li>
<li>{% active_link /developers/frontend_creating_custom_ui/ Add Custom UI %}</li>
</ul>
</li>
<li>
{% active_link /developers/internationalization/ Internationalization %}
<ul>
<li>{% active_link /developers/internationalization/backend_localization/ Backend Localization %}</li>
<li>{% active_link /developers/internationalization/custom_component_localization/ Custom Component Localization %}</li>
<li>{% active_link /developers/internationalization/translation/ Translation %}</li>
</ul>
</li>
<li>
{% active_link /developers/hassio/architecture/ Hass.io architecture %}
<ul>
<li>{% active_link /developers/hassio/debugging/ Debugging Hass.io %}</li>
</ul>
</li>
<li>
{% active_link /developers/hassio/addon_development/ Hass.io Add-on Development %}
<ul>
<li>{% active_link /developers/hassio/addon_tutorial/ Tutorial: Making your first add-on %}</li>
<li>{% active_link /developers/hassio/addon_config/ Configuration %}</li>
<li>{% active_link /developers/hassio/addon_communication/ Communication %}</li>
<li>{% active_link /developers/hassio/addon_testing/ Local Testing %}</li>
<li>{% active_link /developers/hassio/addon_publishing/ Publishing %}</li>
<li>{% active_link /developers/hassio/addon_presentation/ Presentation %}</li>
<li>{% active_link /developers/hassio/addon_repository/ Repositories %}</li>
</ul>
</li>
<li>
{% active_link /developers/api/ API %}
<ul>
<li>{% active_link https://dev-docs.home-assistant.io/en/dev/ Python API %}</li>
<li>{% active_link /developers/websocket_api/ Websocket API %}</li>
<li>{% active_link /developers/rest_api/ REST API %}</li>
<li>{% active_link /developers/python_api/ Python REST API %}</li>
<li>{% active_link /developers/server_sent_events/ Server-sent events %}</li>
</ul>
</li>
<li>
{% active_link /developers/documentation/ Website/Documentation %}
<ul>
<li>{% active_link /developers/documentation/standards/ Standards %}</li>
<li>{% active_link /developers/documentation/create_page/ Create a new page %}</li>
</ul>
</li>
<li>{% active_link /developers/helpers/ Online helpers %}</li>
<li>{% active_link /developers/releasing/ Releasing %}</li>
<li>{% active_link /developers/maintenance/ Maintenance %}</li>
<li>
Governance
<ul>
<li>{% active_link /developers/cla/ Contributor License Agreement %}</li>
<li>{% active_link /privacy/ Privacy Policy %}</li>
<li>{% active_link /tos/ Terms of Service %}</li>
<li>{% active_link /code_of_conduct/ Code of Conduct %}</li>
<li>{% active_link /developers/credits/ Credits %}</li>
<li>{% active_link /developers/license/ License %}</li>
</ul>
</li>
</ul>
</div>
</section>

33
source/_includes/asides/help_navigation.html Normal file
View File

@ -0,0 +1,33 @@
<section class="aside-module grid__item one-whole lap-one-half">
{% include edit_github.html %}
<div class='section'>
<h1 class="title delta">&nbsp;</h1>
<ul class='divided sidebar-menu'>
<li>
{% active_link /help/ Help %}
</li>
<li>
<a href='https://developers.home-assistant.io'>Developer documentation <i class='icon-external-link'></i></a>
</li>
<li>
{% active_link /developers/documentation/ Website/Documentation %}
<ul>
<li>{% active_link /developers/documentation/standards/ Standards %}</li>
<li>{% active_link /developers/documentation/create_page/ Create a new page %}</li>
</ul>
</li>
<li>
Governance
<ul>
<li>{% active_link /developers/cla/ Contributor License Agreement %}</li>
<li>{% active_link /privacy/ Privacy Policy %}</li>
<li>{% active_link /tos/ Terms of Service %}</li>
<li>{% active_link /code_of_conduct/ Code of Conduct %}</li>
<li>{% active_link /developers/credits/ Credits %}</li>
<li>{% active_link /developers/license/ License %}</li>
</ul>
</li>
</ul>
</div>
</section>

32
source/_includes/custom/footer.html
View File

@ -1,13 +1,27 @@
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="copyright grid">
<div class='company grid__item one-third lap-one-half palm-one-whole'>
<div class="title">
<img width="40" src="/demo/favicon-192x192.png"> Home Assistant
</div>
<div class="icons">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
</div>
</div>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a> (no support!).<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
<div class='grid__item one-third lap-one-half palm-one-whole'>
<ul>
<li><a href='https://developers.home-assistant.io'>Developers</a></li>
<li><a href='mailto:hello@home-assistant.io'>Contact</a> (no support!)</li>
<li><a href='/privacy/'>Privacy</a></li>
</ul>
</div>
<div class='grid__item one-third lap-one-half palm-one-whole'>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the
<a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.
Hosted by <a href='https://www.netlify.com/'>Netlify</a>.
</div>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</div>

1
source/_includes/custom/navigation.html
View File

@ -13,7 +13,6 @@
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/cookbook/">Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>

4
source/_includes/site/sidebar.html
View File

@ -4,8 +4,8 @@
{% include asides/component_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'cookbook' %}
{% include asides/cookbook_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'developers' %}
{% include asides/developers_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'developers' or url_parts[1] == 'help' %}
{% include asides/help_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'getting-started' %}
{% include asides/getting_started_navigation.html | compact_newlines %}
{% elsif url_parts[1] == 'docs' %}

1
source/_layouts/page.html
View File

@ -7,6 +7,7 @@ layout: default
{% if url_parts[1] != 'components' and
url_parts[1] != 'cookbook' and
url_parts[1] != 'developers' and
url_parts[1] != 'help' and
url_parts[1] != 'getting-started' %}
{% include edit_github.html %}
{% endif %}

49
source/_posts/2018-04-14-release-67.markdown
View File

@ -28,6 +28,23 @@ This release includes a security fix. The error log was accessible via the API w
- Tahoma switches ([@ikucuze] - [#13636]) ([tahoma docs]) ([switch.tahoma docs]) (new-platform)
- Add support for Nanoleaf Aurora Light Panels ([@Oro] - [#13456]) ([light.nanoleaf_aurora docs]) (new-platform)
## {% linkable_title Release 0.67.1 - April 17 %}
- Fix Gogogate2 'available' attribute ([@dlbroadfoot] - [#13728])
- Fix so it is possible to ignore discovered config entry handlers ([@Kane610] - [#13741])
- Prevent vesync doing I/O in event loop ([@balloob] - [#13862]) ([switch.vesync docs])
- Fix #13846 Double underscore in bluetooth address ([@aav7fl] - [#13884]) ([device_tracker docs])
- Fix race condition for component loaded before listening ([@balloob] - [#13887]) ([config docs])
- Missing property decorator added ([@syssi] - [#13889]) ([fan.xiaomi_miio docs])
- Fix call to parent broadlink switch ([@Danielhiversen] - [#13906]) ([switch.broadlink docs])
- Import operation modes from air humidifier ([@syssi] - [#13908]) ([fan.xiaomi_miio docs])
- Upgrade pyqwikswitch to 0.71 ([@kellerza] - [#13920]) ([qwikswitch docs])
- Upgrade somecomfort to 0.5.2 ([@balloob] - [#13940]) ([climate.honeywell docs])
- Update pyhydroquebec to 2.2.2 ([@titilambert] - [#13946]) ([sensor.hydroquebec docs])
- Update pyfido to 2.1.1 ([@titilambert] - [#13947]) ([sensor.fido docs])
- Bumped pypollencom to 1.1.2 ([@bachya] - [#13959]) ([sensor.pollen docs])
- Revert "Upgrade pyqwikswitch to 0.71 ([@balloob] - [#13920]) ([qwikswitch docs])
## {% linkable_title If you need help... %}
...don't hesitate to use our very active [forums](https://community.home-assistant.io/) or join us for a little [chat](https://discord.gg/c5DvZ4e). The release notes have comments enabled but it's preferred if you use the former communication channels. Thanks.
@ -395,3 +412,35 @@ Experiencing issues introduced by this release? Please report them in our [issue
[xiaomi_aqara docs]: /components/xiaomi_aqara/
[zwave docs]: /components/zwave/
[ann-ubiquiti]: /blog/2018/04/12/ubiquiti-and-home-assistant/
[#13728]: https://github.com/home-assistant/home-assistant/pull/13728
[#13741]: https://github.com/home-assistant/home-assistant/pull/13741
[#13862]: https://github.com/home-assistant/home-assistant/pull/13862
[#13884]: https://github.com/home-assistant/home-assistant/pull/13884
[#13887]: https://github.com/home-assistant/home-assistant/pull/13887
[#13889]: https://github.com/home-assistant/home-assistant/pull/13889
[#13906]: https://github.com/home-assistant/home-assistant/pull/13906
[#13908]: https://github.com/home-assistant/home-assistant/pull/13908
[#13920]: https://github.com/home-assistant/home-assistant/pull/13920
[#13940]: https://github.com/home-assistant/home-assistant/pull/13940
[#13946]: https://github.com/home-assistant/home-assistant/pull/13946
[#13947]: https://github.com/home-assistant/home-assistant/pull/13947
[#13959]: https://github.com/home-assistant/home-assistant/pull/13959
[@Danielhiversen]: https://github.com/Danielhiversen
[@Kane610]: https://github.com/Kane610
[@aav7fl]: https://github.com/aav7fl
[@bachya]: https://github.com/bachya
[@balloob]: https://github.com/balloob
[@dlbroadfoot]: https://github.com/dlbroadfoot
[@kellerza]: https://github.com/kellerza
[@syssi]: https://github.com/syssi
[@titilambert]: https://github.com/titilambert
[climate.honeywell docs]: /components/climate.honeywell/
[config docs]: /components/config/
[device_tracker docs]: /components/device_tracker/
[fan.xiaomi_miio docs]: /components/fan.xiaomi_miio/
[qwikswitch docs]: /components/qwikswitch/
[sensor.fido docs]: /components/sensor.fido/
[sensor.hydroquebec docs]: /components/sensor.hydroquebec/
[sensor.pollen docs]: /components/sensor.pollen/
[switch.broadlink docs]: /components/switch.broadlink/
[switch.vesync docs]: /components/switch.vesync/

64
source/_posts/2018-04-22-hassio-2018.markdown Normal file
View File

@ -0,0 +1,64 @@
---
layout: post
title: "Hass.io 2018"
description: "We want to clarify how Hass.io relates to Home Assistant and talk about the roadmap for Hass.io in 2018."
date: 2018-04-22 00:00:00
date_formatted: "April 22, 2018"
author: Pascal Vizeli
author_twitter: pvizeli
comments: true
categories: Announcements
og_image: /images/blog/2018-04-hassio-2018/blogpost.png
---
We noticed that there is some confusion in the community about how Hass.io relates to Home Assistant and what impact the upcoming Hass.io changes will have. We will try to clarify it all in this blog post.
## {% linkable_title What is Hass.io %}
Hass.io is a complete solution to run Home Assistant, by the authors of Home Assistant. The goal of Hass.io is to provide an easy to use and secure system, entirely managed from within the Home Assistant user interface.
Hass.io is a complete solution, which means that it comes with its own highly secure and optimized operating system, a supervisor application to maintain and configure that system, and of course Home Assistant itself.
When using Hass.io, you'll see a new Hass.io panel inside the Home Assistant UI. From here users can configure the system and install Home Assistant updates with a simple click of a button. Users are also able to make snapshots of their system, making it easy to migrate all their configuration to a new system or restore their system to a previous state.
We wanted to be able to provide the convenience of seamless updates and configuration via the UI to other applications too, and so we introduced Hass.io add-ons. Any application can be packaged up as a Hass.io add-on, allowing any user to install and manage it easily. Since the introduction, we’ve seen an amazing growth in users sharing their add-ons with the community. It’s now possible to install an adblocker for your network, an MQTT broker or Tor with a single click.
## {% linkable_title Upcoming changes to Hass.io %}
We’ve introduced Hass.io [last July]. Since then, we’ve noticed some room for improvements in making Hass.io easier to use, lighter to maintain and easier to integrate with other host systems.
Note that the descriptions of upcoming improvements can get quite technical. Feel free to jump to [the conclusion].
### {% linkable_title Automatic add-on configuration %}
Home Assistant has recently introduced configuration entries. We’re going to hook into this new functionality and allow add-ons to configure their related integration in Home Assistant automatically. For example, if a user installs the MQTT broker add-on, we will automatically set up Home Assistant to connect to it.
### {% linkable_title Host management %}
To control the host system, we currently use a custom service called HostControl. This allows the user to manage here host and restart/shutdown the computer from within Home Assistant. Instead of relying on our own system, we’re going to change to use D-Bus. D-Bus is a standardized mechanism for services and applications to communicate. Using a defined standard means that all parts of the host can now be remotely configured: sound, network, etc, etc. We will be extending the Hass.io panel in Home Assistant with controls to configure various parts of the host.
### {% linkable_title Hass.io OS %}
Hass.io is currently using a forked version of ResinOS as our operating system. ResinOS has been designed to run a minimal environment for Docker, simple over the air updates and connect to the ResinIO cloud. Our fork removed the ResinIO logic. Over time, ResinOS has been evolving but not in a direction that is aligned with our goals, resulting in the maintenance of our fork to take up a lot of time.
The ResinOS build system is based on the Yocto Project. This is a very powerful system, but also requires specific support for each hardware platform need to be specifically added and maintained (like each version of Raspberry Pi), which caused long build and development times for Hass.io.
All these factors made us decide to build our own, custom, operating system. We’re obviously not starting from scratch, but instead, are basing it off [Buildroot] as the foundation and use [RAUC] for over the air updates.
Some things that the new operating system will be able to do:
- Easier to add support for new hardware.
- Updating will be atomic and has a Fail-safe. If a system fails to boot after an OS upgrade, it will fallback, by booting the previous working version.
- Updates are required to be securely signed by the Home Assistant team, adding a whole new level of security.
- Compressing the root file system, making it faster on SD cards and slow IO-Interfaces.
- Compressing parts of the memory so that we can store more information.
## {% linkable_title What Hass.io users should do to prepare for these updates %}
At this moment: Nothing.
The new Hass.io supervisor still supports the old ResinOS builds (our official downloads for Raspberry Pi and Intel NUC) and generic Linux installations. If you’re using a generic Linux installation on SUSE Linux or Ubuntu, you have to update your local AppArmor profile if you want to use the new functionality (instructions will be provided upon release).
Once our new installation images with HassioOS are released, you have to reflash your device once. You can do this without losing any configuration by using our Snapshot feature:
- Create a snapshot of your current installation and download it to your PC.
- Flash the SD card with the new Hass.io OS image.
- Restore your snapshot.
- Enjoy a new and improved Hass.io
[last July]: https://www.home-assistant.io/blog/2017/07/25/introducing-hassio/
[the conclusion]: #what-hassio-users-should-do-to-prepare-for-these-updates
[Buildroot]: https://buildroot.org/
[RAUC]: https://www.rauc.io/

44
source/_posts/2018-04-24-launch-google-assistant-support.markdown Normal file
View File

@ -0,0 +1,44 @@
---
layout: post
title: "Our Google Assistant skill is live!"
description: "The Google Assistant integration for Home Assistant Cloud is now available to all."
date: 2018-04-24 00:01:00
date_formatted: "April 24, 2018"
author: Paulus Schoutsen
author_twitter: balloob
comments: true
categories: Announcement
og_image: /images/blog/2018-04-google-assistant/google-assistant-home-assistant.png
---
<p class='img'>
<img
src='/images/blog/2018-04-google-assistant/google-assistant-home-assistant.png'
alt='Home Assistant logo and the Works with the Google Assistant badge'
/>
</p>
Guess what? Yep, our Google Assistant Smart Home skill is live! It's a mouthful but it means that you can now control your Home Assistant devices via any Google Assistant enabled device by simply saying things like "Ok Google, turn on the lights".
To get started:
- [Enable Home Assistant Cloud](/cloud/#enabling-the-cloud)
- Install our skill for Google Assistant. As of this writing, the link is not live yet: you can find it by opening the Google Home app -> Home Control, tap on the blue + at the bottom right and find Hass.io in the list.
- Optional: [Tweak the devices](/cloud/google_assistant/) that are getting exposed to Google Assistant.
Things to note:
- The skill is called Hass.io, but will work with normal Home Assistant too. The name was necessary to avoid confusion between Home Assistant, Google Assistant and Google Home.
- Works with Home Assistant 0.65.6 or later.
- All message handling is done local and is [open source](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/google_assistant/trait.py).
- If you have an Android device with Google Assistant, you can control your devices too.
- Home Assistant 0.68 will introduce a button to the Cloud config panel to trigger a sync of available devices.
Home Assistant Cloud is still in open beta and free to use. Open beta period has been extended to June 1. Many thanks to [Quadflight] for providing the Raspberry Pis that Google used for physical testing and thanks to [Arsaboo] for helping with testing.
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/TQ3CoEHz5Xs" frameborder="0" allowfullscreen></iframe>
</div>
[Quadflight]: https://github.com/quadflight
[Arsaboo]: https://github.com/arsaboo

1
source/cloud/google_assistant.markdown
View File

@ -37,7 +37,6 @@ cloud:
aliases:
- bright lights
- entry lights
type: 'action.devices.types.LIGHT'
```
{% configuration cloud %}

9
source/cloud/index.markdown
View File

@ -15,19 +15,16 @@ ha_iot_class: "Cloud Push"
<p class='note'>The Home Assistant Cloud is currently free and will become part of the upcoming Community Support Package. [Learn more](/blog/2017/12/17/introducing-home-assistant-cloud/)</p>
The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services like Amazon Alexa.
The following integrations are currently available:
The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services. The following integrations are currently available:
- [Amazon Alexa (Amazon Echo)](/cloud/alexa/)
<!-- - [Google Assistant (Google Home)](/cloud/google_assistant/) -->
- [Google Assistant (Google Home)](/cloud/google_assistant/)
### {% linkable_title How does it work? %}
The Home Assistant Cloud has been designed with security in mind. When you activate the Cloud component, your instance will create a secure connection to the Home Assistant Cloud. There is no need for any further configuration or to expose your instance to the internet.
Integrations like Alexa will deliver messages to our cloud which we will forward to your local instance for processing. We just forward the response back to Alexa. This means that we do not have to store the state of your house in our cloud, we’re just the messenger!
Integrations like Alexa or Google will deliver messages to our cloud which we will forward to your local instance for processing. We just forward the response back. This means that we do not have to store the state of your house in our cloud, we’re just the messenger!
You can find a list of frequently asked questions (and their answers) in [this blog post](/blog/2017/12/17/introducing-home-assistant-cloud/#faq).

27
source/developers/add_new_platform.markdown
View File

@ -9,27 +9,6 @@ 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.
For example, the built-in `switch` component consists of various platforms in [`homeassistant/components/switch/`](https://github.com/home-assistant/home-assistant/tree/master/homeassistant/components/switch). The file `__init__.py` contains the core logic of all platforms and the `vendor_name.py` files contain only the relevant platform code.
If you're planning to add support for a new type of device to an existing component, you can get away with only writing platform logic. Have a look at how the component works with other platforms and create a similar file for the platform that you want to add:
- [Example sensor platform](/developers/platform_example_sensor): hello world of platforms.
- [Example light platform](/developers/platform_example_light): showing best practices.
### {% linkable_title 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 %}
Platforms can specify dependencies and requirements [the same way as components](/developers/component_deps_and_reqs):
```python
REQUIREMENTS = ['some-package==2.0.0', 'some-other-package==2.5.0']
DEPENDENCIES = ['mqtt']
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_platform_index.html';
</script>

13
source/developers/api.markdown
View File

@ -9,13 +9,6 @@ sharing: true
footer: true
---
Home Assistant provides various APIs. For detail please refer to [Home Assistant API](https://dev-docs.home-assistant.io/en/dev/) documentation.
* [Python API](https://dev-docs.home-assistant.io/)
* [WebSocket API](/developers/websocket_api/)
* [REST API](/developers/rest_api/)
* [Python REST API](/developers/python_api/)
* [Server-sent events](/developers/server_sent_events/)
If you are not using the [`frontend`](/components/frontend/) in your setup then you need to enable the components by adding them to your `configuration.yaml` file. E.g., [`websocket_api:`](/components/websocket_api/) for the WebSocket API or [`api:`](/components/api/) for the [REST API](/developers/rest_api/) and the [Python REST API](/developers/python_api/).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/external_api_rest.html';
</script>

32
source/developers/architecture.markdown
View File

@ -10,32 +10,6 @@ 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.
For more information about each part in this overview, <a href='/blog/2014/12/26/home-control-home-automation-and-the-smart-home/'>check out our blog</a>. Here's the tl;dr version of the blog:
* Home Control is responsible for collecting information and controlling devices.
* Home Automation triggers commands based on user configurations.
* Smart Home triggers commands based on previous behavior.
<p class='img'>
<a href='{{site_root}}/images/architecture/home_automation_landscape.svg' name='landscape'>
<img alt='Home Automation landscape'
src='{{site_root}}/images/architecture/home_automation_landscape.svg' />
</a>
Overview of the home automation landscape
</p>
The Home Assistant core is responsible for Home Control. Home Assistant contains four parts which make this possible:
* **Event Bus**: facilitates the firing and listening of events -- the beating heart of Home Assistant.
* **State Machine**: keeps track of the states of things and fires a `state_changed` event when a state has been changed.
* **Service Registry**: listens on the event bus for `call_service` events and allows other code to register services.
* **Timer**: sends a `time_changed` event every 1 second on the event bus.
<p class='img'>
<a href='/images/architecture/ha_architecture.svg' name='architecture'>
<img src='/images/architecture/ha_architecture.svg' />
</a>
Overview of the Home Assistant core architecture
</p>
<script>
window.location = 'http://developers.home-assistant.io/docs/en/architecture_index.html';
</script>

58
source/developers/architecture_components.markdown
View File

@ -10,58 +10,6 @@ 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/).
<p class='img'>
<img src='/images/architecture/component_interaction.png' alt='Diagram showing interaction between components and the Home Assistant core.'>
Diagram showing interaction between components and the Home Assistant core
</p>
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 %}
These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices.
For example, the built-in [`switch` component](/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
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 %}
These components provide small pieces of home automation logic or involve services that do common tasks within your house.
For example, the [`device_sun_light_trigger` component](/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:
```text
In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
If the sun has set and the lights are not on:
Turn on the lights
```
```text
In the event that the combined state of all tracked devices changes to 'Not Home':
If the lights are on:
Turn off the lights
```
```text
In the event of the sun setting:
If the lights are off and the combined state of all tracked device equals 'Home':
Turn on the lights
```
Look [here](/python_component_automation/) for a comprehensive example of a home automation component.
### {% linkable_title 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.
<p class='img'>
<a href='/images/architecture/ha_full_architecture.png'>
<img src='/images/architecture/ha_full_architecture.png' />
</a>
Overview of the full Home Assistant architecture with a couple of loaded components and platforms
</p>
The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/architecture_components.html';
</script>

19
source/developers/asyncio.markdown
View File

@ -9,19 +9,6 @@ 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].
The old core was set up like a “traditional” threaded application. Each resource that was not thread safe (ie. the state of entities) would be protected by a lock. This caused a lot of waiting and potential inconsistency because a task could now end up waiting halfway through its job until some resource got freed.
Our new core is based on an Python’s built-in asyncio module. Instead of having all threads have access to the core API objects, access is now limited to a special thread called the event loop. All components will now schedule themselves as a task to be executed by the event loop. This gives us the guarantee that only one task is executed at once, meaning we no longer need any locks.
The only problem with running everything inside the event loop is when a task is doing blocking I/O, what most third-party Python libraries are doing. For example while requesting new information from a device, the core will stop running until we get a response from the device. To handle this, a task is able to suspend itself until the response is available after which it will be enqueued for the event loop to process the result.
For a task to be able to suspend itself, all code that it calls has to have this capability added. This means in practice that each device integration will need a full rewrite of the library that offers the integration! As this is not something that can be achieved, ever, a 100% backwards compatible API has been added so that no platform will require updating.
The backwards compatible API works by scheduling a task from a different thread and blocking that thread until the task has been processed by the event loop.
### [Next step: asyncio 101 &raquo;](/developers/asyncio_101/)
[0.29]: /blog/2016/09/29/async-sleepiq-emoncms-stocks/
[ben]: https://github.com/bbangert/
<script>
window.location = 'http://developers.home-assistant.io/docs/en/asyncio_index.html';
</script>

12
source/developers/asyncio_101.markdown
View File

@ -9,12 +9,6 @@ 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.
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/M-UcUs7IMIM" frameborder="0" allowfullscreen></iframe>
</div>
### [Next step: Categorizing Functions &raquo;](/developers/asyncio_categorizing_functions/)
[rob]: https://github.com/rob-smallshire
<script>
window.location = 'http://developers.home-assistant.io/docs/en/asyncio_101.html';
</script>

71
source/developers/asyncio_categorizing_functions.markdown
View File

@ -9,71 +9,6 @@ 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 %}
Coroutines are special functions based on Python’s generators syntax which allows them to suspend execution while waiting on a result.
Invoking a coroutine function will return a Generator object back, but will not actually begin execution. This object will execute the task when it is either yielded from (from within another coroutine) or it is scheduled on the event loop.
To declare a function a coroutine, import the coroutine annotation from the asyncio package and annotate your function.
```python
import asyncio
@asyncio.coroutine
def async_look_my_coroutine(target):
result = yield from entity.async_turn_on()
if result:
print("hello {}".format(target))
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 %}
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.
To declare a function as a callback, import the callback annotation from the core package and annotate your function.
A common use case for a callback in Home Assistant is as a listener for an event or a service call. It can process the incoming information and then schedule the right calls to be made. Example from the automation component.
```python
from homeassistant.core import callback
@callback
def async_trigger_service_handler(service_call):
"""Handle automation trigger service calls."""
vars = service_call.data.get(ATTR_VARIABLES)
for entity in component.async_extract_from_service(service_call):
hass.loop.create_task(entity.async_trigger(vars, True))
```
In this example, `entity.async_trigger` is a coroutine function. Invoking the coroutine function will return a coroutine task. The passed in parameters will be used when the task gets executed.
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? %}
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 %}
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 %}
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.
There is no special annotation necessary to be considered part of this category.
### [Next step: Working with Async &raquo;](/developers/asyncio_working_with_async/)
<script>
window.location = 'http://developers.home-assistant.io/docs/en/asyncio_categorizing_functions.html';
</script>

14
source/developers/asyncio_misc.markdown
View File

@ -9,14 +9,6 @@ sharing: true
footer: true
---
## {% linkable_title 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 %}
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.
[brett]: http://www.snarky.ca/how-the-heck-does-async-await-work-in-python-3-5
[ben]: https://github.com/bbangert/
<script>
window.location = 'http://developers.home-assistant.io/docs/en/asyncio_index.html';
</script>

120
source/developers/asyncio_working_with_async.markdown
View File

@ -9,120 +9,6 @@ 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 %}
[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 %}
To make a component async, implement an async_setup.
```python
def setup(hass, config):
# Setup your component outside of the event loop.
```
Will turn into:
```python
import asyncio
@asyncio.coroutine
def async_setup(hass, config):
# Setup your component inside of the event loop.
```
## {% linkable_title Implementing an async platform %}
For platforms we support async setup. Instead of setup_platform you need to have a coroutine async_setup_platform.
```python
setup_platform(hass, config, add_entities, discovery_info=None):
# Setup your platform outside of the event loop.
```
Will turn into:
```python
import asyncio
@asyncio.coroutine
def async_setup_platform(hass, config, async_add_entities,
discovery_info=None):
# Setup your platform inside of the event loop
```
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 %}
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!
```python
class MyEntity(Entity):
def update(self):
"""Retrieve latest state."""
self._state = fetch_state()
```
Will turn into:
```python
import asyncio
class MyEntity(Entity):
@asyncio.coroutine
def async_update(self):
"""Retrieve latest state."""
self._state = yield from async_fetch_state()
```
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 %}
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.
In the following example, `say_hello` will schedule `async_say_hello` and block till the function has run and get the result back.
```python
from homeassistant.util.async import run_callback_threadsafe
def say_hello(hass, target):
return run_callback_threadsafe(
hass.loop, async_say_hello, target).result()
def async_say_hello(hass, target):
return "Hello {}!".format(target)
```
## {% linkable_title 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 %}
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.
| Callback | Call immediately.
| Coroutine | Schedule for execution on the event loop.
| Other functions | Schedule for execution in the thread pool.
#### {% linkable_title hass.async_add_job %}
Use this method if the function should be called but not get priority over already scheduled calls.
| Callback | Schedule for execution on the event loop.
| Coroutine | Schedule for execution on the event loop.
| Other functions | Schedule for execution in the thread pool.
### [Next step: Miscellaneous &raquo;](/developers/asyncio_misc/)
[dev-docs]: https://dev-docs.home-assistant.io/en/master/api/core.html
[dev-docs-async]: https://dev-docs.home-assistant.io/en/dev/api/util.html#module-homeassistant.util.async
<script>
window.location = 'http://developers.home-assistant.io/docs/en/asyncio_working_with_async.html';
</script>

28
source/developers/code_review_component.markdown
View File

@ -9,28 +9,6 @@ sharing: true
footer: true
---
A checklist of things to do when you're adding a new component.
<p class='note'>
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. 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 %}
1. Voluptuous schema present for config validation
2. Default parameters specified in voluptuous schema, not in `setup(…)`
3. Schema using as many generic config keys as possible from `homeassistant.const`
4. If your component has platforms, define a `PLATFORM_SCHEMA` instead of a `CONFIG_SCHEMA`.
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 %}
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`.
<script>
window.location = 'http://developers.home-assistant.io/docs/en/creating_component_code_review.html';
</script>

70
source/developers/code_review_platform.markdown
View File

@ -9,70 +9,6 @@ sharing: true
footer: true
---
A checklist of things to do when you're adding a new platform.
<p class='note'>
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. 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 %}
1. If you depend on a component for the connection, add it to your dependencies: `DEPENDENCIES = ['nest']`
### {% linkable_title 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`)
3. Default parameters specified in voluptuous schema, not in `setup_platform(…)`
4. Your `PLATFORM_SCHEMA` should use as many generic config keys as possible from `homeassistant.const`
```python
import voluptuous as vol
from homeassistant.const import CONF_FILENAME, CONF_HOST
from homeassistant.components.light import PLATFORM_SCHEMA
import homeassistant.helpers.config_validation as cv
CONF_ALLOW_UNREACHABLE = 'allow_unreachable'
DEFAULT_UNREACHABLE = False
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
vol.Required(CONF_HOST): cv.string,
vol.Optional(CONF_ALLOW_UNREACHABLE,
default=DEFAULT_UNREACHABLE): cv.boolean,
vol.Optional(CONF_FILENAME): cv.string,
})
```
5. Never depend on users adding things to `customize` to configure behavior inside your platform.
### {% linkable_title 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 %}
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 %}
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.
```python
# bad
status = requests.get(url('/status'))
# good
from phue import Bridge
bridge = Bridge(…)
status = bridge.status()
```
<script>
window.location = 'http://developers.home-assistant.io/docs/en/creating_platform_code_review.html';
</script>

35
source/developers/component_deps_and_reqs.markdown
View File

@ -9,35 +9,6 @@ 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 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.
```python
DEPENDENCIES = ['mqtt']
```
## {% linkable_title Requirements %}
Requirements are Python libraries or modules that you would normally install using `pip` for your component. Home Assistant will try to install the requirements into the `deps` subdirectory of the Home Assistant [configuration directory](/docs/configuration/) if you are not using a `venv` or in something like `path/to/venv/lib/python3.6/site-packages` if you running in a virtual environment. This will make sure that all requirements are present at startup. If steps fails like missing packages for the compilation of a module or other install errors, the component will fail to load.
Requirements is a list of strings. Each entry is a `pip` compatible string. For example, the media player Cast platform depends on the Python package PyChromecast v0.6.12:
```python
REQUIREMENTS = ['pychromecast==0.6.12']
```
During development of a component, it can be useful to test against different versions of a requirement. This can be done in two steps, using pychromecast as an example:
* `pip install pychromecast==0.6.13 --target ~/.homeassistant/deps`
* `hass --skip-pip`
This will use the specified version, and prevent Home Assistant from trying to override it with what is currently in `REQUIREMENTS`.
If you need to make changes to a requirement to support your component, it's also possible to `pip install` from a checkout of the requirement.
* `git clone https://github.com/balloob/pychromecast.git`
* `pip install ./pychromecast`
* `hass --skip-pip`
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_deps_and_reqs.html';
</script>

52
source/developers/component_discovery.markdown
View File

@ -9,52 +9,6 @@ sharing: true
footer: true
---
<p class='note warning'>
This option is only available for built-in components.
</p>
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 %}
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 %}
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:
```python
from homeassistant.components.discovery import SERVICE_AWESOMEDEVICE
from homeassistant.helpers import discovery
DOMAIN = 'awesomedevice'
DEPENDENCIES = ['http']
def setup(hass, config):
cfg = config.get(DOMAIN)
def device_discovered(service, info):
""" Called when a Awesome device has been discovered. """
print("Discovered a new Awesome device: {}".format(info))
discovery.listen(
hass, SERVICE_AWESOMEDEVICE, device_discovered)
return True
```
### {% linkable_title 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):
```python
SERVICE_AWESOMEDEVICE = 'awesomedevice'
SERVICE_HANDLERS = {
...
SERVICE_AWESOMEDEVICE: ('awesomedevice', None),
}
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_discovery.html';
</script>

4
source/developers/component_events.markdown
View File

@ -9,4 +9,6 @@ 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`.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_events.html';
</script>

69
source/developers/component_generic_discovery.markdown
View File

@ -9,69 +9,6 @@ sharing: true
footer: true
---
New controller or hub components often need to add platforms in sub-components (i.e. Lights & Switches) without additional configuration.
This can be achieved using the `load_platform` or `async_load_platform` methods from `homeassistant.helpers.discovery`:
```python
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 %}
Say you need to implement your new MyFlashyHub that controls both Switches & Lights, you can follow these steps:
Configuration required for your new hub component:
```yaml
myflashyhub:
example: setting
```
The source for your component can be located in your configuration directory for now:
```bash
~/.homeassistant/custom_components/myflashyhub.py
~/.homeassistant/custom_components/light/myflashyhub.py
~/.homeassistant/custom_components/switch/myflashyhub.py
```
In the hub component `myflashyhub.py` you can call your light and switch components. To pass any non-serializable information to the platforms in the sub-component, you can use a global variable.
```python
from homeassistant.helpers.discovery import load_platform
DOMAIN = 'myflashyhub'
DATA_MFH = 'MFH'
def setup(hass, config):
"""Your controller/hub specific code."""
hass.data[DATA_MFH] = SomeObjectToInitialiseGlobal()
#--- snip ---
load_platform(hass, 'light', DOMAIN)
load_platform(hass, 'switch', DOMAIN, {'optional': 'arguments'})
```
Add your custom device specific code to the `setup_platform` method in `light/myflashyhub.py` and `switch/myflashyhub`.
```python
import custom_components.myflashyhub as myflashyhub
# '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."""
# You can now use hass.data[myflashyhub.DATA_MFH]
```
The `load_platform` method allows the platforms to be loaded without the need for any additional platform entries in your `configuration.yaml` file, which normally would have been:
```yaml
#light:
# platform: myflashyhub
#switch:
# platform: myflashyhub
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_generic_discovery.html';
</script>

17
source/developers/component_loading.markdown
View File

@ -9,17 +9,6 @@ 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:
* `<config directory>/custom_components/<component name>`
* `homeassistant/components/<component name>` (built-in components)
Once loaded, a component will only be setup if all dependencies can be loaded and are able to setup. Keep an eye on the logs to see if your component could be loaded and initialized.
<p class='note warning'>
You can override a built-in component by having a component with the same name in your <code>config/custom_components</code> folder. If the built-in component is inside a subfolder, take care to place your customization in a folder with the same name in <code>config/custom_components/*folder*</code>. Note that overriding built-in components is not recommended and will probably break things!
</p>
<p class='note'>
Home Assistant will use the directory that contains your config file as the directory that holds your customizations. By default this is the <code>config</code> folder in your current work directory. You can use a different folder by running Home Assistant with the --config argument: <code>python3 homeassistant --config /YOUR/CONFIG/PATH/</code>.
</p>
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_loading.html';
</script>

14
source/developers/component_states.markdown
View File

@ -9,14 +9,6 @@ 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.
A state can have several attributes that will help the frontend in displaying your state:
- `friendly_name`: this name will be used as the name of the device
- `entity_picture`: this picture will be shown instead of the domain icon
- `unit_of_measurement`: this will be appended to the state in the interface
- `hidden`: This is a suggestion to the frontend on if the state should be hidden
These attributes are defined in [homeassistant.helpers.entity](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py#L180).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_states.html';
</script>

13
source/developers/component_visibility.markdown
View File

@ -9,13 +9,6 @@ sharing: true
footer: true
---
Generally, when creating a new entity for Home Assistant you will want it to be a class that inherits the [homeassistant.helpers.entity.Entity](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/entity.py) class. If this is done, visibility will be handled for you.
You can set a suggestion for your entity's visibility by setting the `hidden` property by doing something similar to the following.
```python
self.hidden = True
```
This will SUGGEST that the active frontend hides the entity. This requires that the active frontend support hidden cards (the default frontend does) and that the value of hidden be included in your attributes dictionary (see above). The Entity abstract class will take care of this for you.
Remember: The suggestion set by your component's code will always be overwritten by user settings in the `configuration.yaml` file. This is why you may set hidden to be `False`, but the property may remain `True` (or vice-versa).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_index.html';
</script>

19
source/developers/creating_components.markdown
View File

@ -9,19 +9,6 @@ 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 %}
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.
```python
DOMAIN = 'hello_state'
def setup(hass, config):
hass.states.set('hello.world', 'Paulus')
return True
```
For more examples, see the [Custom Python Component Examples](/cookbook/#custom-python-component-examples) on our examples page.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_component_index.html';
</script>

23
source/developers/development.markdown
View File

@ -9,23 +9,6 @@ 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.
Home Assistant is open-source and licensed under [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0). Here are links to the source:
- [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.
When contributing Home Assistant code:
- [Github](https://guides.github.com/activities/hello-world/)
- [Pip and Virtual Environments](https://www.dabapps.com/blog/introduction-to-pip-and-virtualenv-python/)
- [Python 3](https://www.python.org/)
- [Pylint](https://www.pylint.org)
- [Flake8](http://flake8.pycqa.org/en/latest/)
- [Tox](http://tox.readthedocs.org/en/latest/)
- [TravisCl](https://travis-ci.org/)
When contributing 3rd Party code to be used by Home Assistant:
- [Publishing your own PyPI package](https://jeffknupp.com/blog/2013/08/16/open-sourcing-a-python-project-the-right-way/)
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_index.html';
</script>

49
source/developers/development_101.markdown
View File

@ -9,49 +9,6 @@ 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].
To get our code running inside Home Assistant we're going to create a custom component. The first step is to locate your config folder. You can find the path to your config folder by opening the Home Assistant frontend, click on the <img src='/images/screenshots/developer-tool-about-icon.png' alt='service developer tool icon' class="no-shadow" height="38" />. It's the path after the text "Path to configuration.yaml".
Inside your configuration directory create a new folder called `custom_components`. It might be that one already exists, that's fine too. This is the folder that Home Assistant will look at when looking for custom code.
<p class='note'>
The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version.
</p>
To verify that everything is working correctly, let's create a small Hello World component. To do so, create a file called `hello_world.py` in your custom components folder. Copy paste the following content to it:
```python
# The domain of your component. Equal to the filename of your component.
DOMAIN = "hello_world"
def setup(hass, config):
"""Setup the hello_world component."""
# States are in the format DOMAIN.OBJECT_ID.
hass.states.set('hello_world.Hello_World', 'Works!')
# Return boolean to indicate that initialization was successfully.
return True
```
Last step is to add `hello_world:` entry to your `configuration.yaml` file.
```yaml
# Hello World component
hello_world:
```
After running `hass`, we should see log entries stating that `hello_world` component was loaded. What is more, additional state card shall appear within main panel.
```log
2018-04-03 21:44:20 INFO (MainThread) [homeassistant.loader] Loaded hello_world from custom_components.hello_world
2018-04-03 21:44:20 INFO (MainThread) [homeassistant.setup] Setting up hello_world
```
<p class='img'>
<img src='/images/screenshots/hello-world-state-card.png' />
State card showing that Hello World component is working as intended.
</p>
[architecture]: /developers/architecture/
<script>
window.location = 'https://developers.home-assistant.io/docs/en/dev_101_index.html';
</script>

33
source/developers/development_catching_up.markdown
View File

@ -9,33 +9,6 @@ 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.
```bash
# Run this from your feature branch
$ git fetch upstream dev # to pull the latest changes into a local dev branch
$ git rebase upstream/dev # to put those changes into your feature branch before your changes
```
If rebase detects conflicts, repeat this process until all changes have been resolved:
1. `git status` shows you the file with the conflict; edit the file and resolve the lines between `<<<< | >>>>`
3. Add the modified file: `git add <file>` or `git add .`
4. Continue rebase: `git rebase --continue`
5. Repeat until you've resolved all conflicts
After rebasing your branch, you will have rewritten history relative to your GitHub fork's branch. When you go to push you will see an error that your history has diverged from the original branch. In order to get your GitHub fork up-to-date with your local branch, you will need to force push, using the following command:
```bash
# Run this from your feature branch
$ git push origin --force
```
Other workflows are covered in detail in the [Github documentation](https://help.github.com/articles/fork-a-repo/). Add an additional `remote` after you clone your fork.
```bash
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
```
Then, `git pull --rebase upstream dev`.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_catching_up.html';
</script>

12
source/developers/development_checklist.markdown
View File

@ -9,12 +9,6 @@ sharing: true
footer: true
---
Before you commit any changes, check your work against these requirements:
- All dependencies from [pypi](https://pypi.python.org/pypi) are included via the `REQUIREMENTS` variable in your platform or component and only imported inside functions that use them
- New dependencies are added to `requirements_all.txt` (if applicable), using `script/gen_requirements_all.py`
- The `.coveragerc` file is updated to exclude your platform if there are no tests available or your new code uses a third-party library for communication with the device, service, or sensor
- Documentation is developed for [home-assistant.io](/)
* It's OK to start with adding a docstring with configuration details (for example, sample entry for `configuration.yaml` file) to the file header. Visit the [website documentation](/developers/documentation/) for more information about contributing to [home-assistant.io](https://github.com/home-assistant/home-assistant.github.io).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_checklist.html';
</script>

27
source/developers/development_config.markdown
View File

@ -9,27 +9,6 @@ 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 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 %}
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.
The object will have already been validated using your `CONFIG_SCHEMA` or `PLATFORM_SCHEMA` if available. If you have defined a `PLATFORM_SCHEMA`, all references to your component (ie `light 2:` etc) will have been changed to be accessible as a list under `config[DOMAIN]`.
If your configuration file contains the following lines:
```yaml
example:
host: paulusschoutsen.nl
```
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 %}
The `config` parameter passed to a platform setup function is only the config for that specific platform.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/dev_101_config.html';
</script>

102
source/developers/development_environment.markdown
View File

@ -9,102 +9,6 @@ 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 %}
#### {% linkable_title Developing on Linux %}
Install the core dependencies.
```bash
$ sudo apt-get install python3-pip python3-dev python3-venv
```
In order to run `script/setup` below you will need some more dependencies.
```bash
$ sudo apt-get install libssl-dev libxml2-dev libxslt1-dev libjpeg-dev libffi-dev libudev-dev zlib1g-dev
```
<p class='note'>
Different distributions have different package installation mechanisms and sometimes packages names as well. For example Centos would use: `sudo yum install epel-release && sudo yum install python34 python34-devel mysql-devel`
</p>
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 %}
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.
Due to Home Assistant is mainly designed and developed on Linux distributions it is not recommended to develop on Windows machines. However on Windows 10 machines you should decide to set up a [Linux subsystem](https://docs.microsoft.com/de-de/windows/wsl/install-win10).
Setup Linux subsystem.
```bash
$ apt-get update
$ apt-get upgrade
$ echo 'export DISPLAY=:0' >> ~/.bashrc && . ~/.bashrc
$ sudo apt-get install xubuntu-desktop -y
```
It is recommended using [PyCharm](https://www.jetbrains.com/pycharm/download/) as debugger. Download and start PyCharm.
```bash
$ wget https://download.jetbrains.com/python/pycharm-community-20XX.X.tar.gz
$ tar -xzf pycharm-community-20XX.X
$ ./pycharm.sh
```
In order to display the PyCharm GUI on Windows you need to run a X-Server like [VcXserv](https://sourceforge.net/projects/vcxsrv/).
Also, make sure to install or upgrade the `setuptools` Python package. It contains compatibility improvements and adds automatic use of compilers:
```bash
$ pip install --upgrade setuptools
```
#### {% linkable_title Developing on OS X %}
Install [Homebrew](https://brew.sh/), then use that to install Python 3:
```bash
$ brew install python3
```
### {% linkable_title 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:
```bash
$ git clone https://github.com/YOUR_GIT_USERNAME/home-assistant.git
$ cd home-assistant
$ git remote add upstream https://github.com/home-assistant/home-assistant.git
```
### {% linkable_title 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.
```bash
$ python3 -m venv .
$ source bin/activate
```
Install the requirements with a provided script named `setup`.
```bash
$ script/setup
```
Invoke your installation.
```bash
$ hass
```
### {% linkable_title Logging %}
By default logging in home-assistant is tuned for operating in production (set to INFO by default, with some modules set to even less verbose logging levels).
You can use the [logger](/components/logger/) component to adjust logging to DEBUG to see even more details about what is going on.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_environment.html';
</script>

54
source/developers/development_events.markdown
View File

@ -9,54 +9,6 @@ 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].
The event system is very flexible. There are no limitations on the event type, as long as it's a string. Each event can contain data. The data is a dictionary that can contain any data as long as it's JSON serializable. This means that you can use number, string, dictionary and list.
[List of events that Home Assistant fires.][object]
### {% linkable_title 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`.
Example component that will fire an event when loaded.
```python
DOMAIN = 'hello_event'
def setup(hass, config):
"""Set up is called when Home Assistant is loading our component."""
# Fire event my_cool_event with event data answer=42
hass.bus.fire('my_cool_event', {
'answer': 42
})
```
### {% linkable_title 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.
```python
DOMAIN = 'hello_event'
def setup(hass, config):
"""Set up is called when Home Assistant is loading our component."""
count = 0
# Listener to handle fired events
def handle_event(event):
nonlocal count
count += 1
print('Total events received:', count)
# Listen for when my_cool_event is fired
hass.bus.listen('my_cool_event', handle_event)
```
#### {% linkable_title Helpers %}
Home Assistant comes with a lot of bundled helpers to listen to specific types of event. There are helpers to track a point in time, to track a time interval, a state change or the sun set. [See available methods.][helpers]
[helpers]: https://dev-docs.home-assistant.io/en/master/api/helpers.html#module-homeassistant.helpers.event
[object]: /docs/configuration/events/
<script>
window.location = 'https://developers.home-assistant.io/docs/en/dev_101_events.html';
</script>

73
source/developers/development_guidelines.markdown
View File

@ -9,73 +9,6 @@ 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).
Summary of the most relevant points:
- Line length is limited to 79 characters (see below).
- Use 4 spaces per indentation level. We don't use tabs.
- Comments should be full sentences and end with a period.
- [Imports](https://www.python.org/dev/peps/pep-0008/#imports) should be ordered.
- Constants and the content of lists and dictionaries should be in alphabetical order.
- Avoid trailing whitespace but surround binary operators with a single space.
- Line separator should be set to `LF`.
The maximum line length comes directly from the [PEP8 style guide](https://www.python.org/dev/peps/pep-0008/#maximum-line-length), and is also used by the Python standard library. All code must pass these linting checks, and no exceptions will be made. There have already been numerous requests to increase the maximum line length, but after evaluating the options, the Home Assistant maintainers have decided to stay at 79 characters. This decision is final.
Those points may require that you adjust your IDE or editor settings.
## {% linkable_title 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 %}
Use single quotes `'` for single word and `"` for multiple words or sentences.
```python
ATTR_WATERLEVEL = 'level'
CONF_ATTRIBUTION = "Data provided by the WUnderground weather service"
SENSOR_TYPES = {
'alerts': ['Alerts', None],
}
```
### {% linkable_title 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.
```python
"""
Support for MQTT lights.
For more details about this platform, please refer to the documentation at
https://home-assistant.io/components/light.mqtt/
"""
```
### {% linkable_title Requirements %}
Please place [Platform requirements](/developers/code_review_platform/#1-requirements) right after the imports.
```python
[...]
from homeassistant.helpers.entity import Entity
REQUIREMENTS = ['xmltodict==0.11.0']
```
### {% linkable_title 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.
```python
_LOGGER.error("No route to device: %s", self._resource)
```
```bash
2017-05-01 14:28:07 ERROR [homeassistant.components.sensor.arest] No route to device: 192.168.0.18
```
Don't print out wrong API keys, tokens, usernames, or passwords.
Also note that `_LOGGER.info` is reserved for the core, use `_LOGGER.debug` in anything else.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_guidelines.html';
</script>

29
source/developers/development_hass_object.markdown
View File

@ -10,29 +10,6 @@ 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 Home Assistant instance contains four objects to help you interact with the system.
| Object | Description |
| ------ | ----------- |
| `hass` | This is the instance of Home Assistant. Allows starting, stopping and enqueing new jobs. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.HomeAssistant)
| `hass.config` | This is the core configuration of Home Assistant exposing location, temperature preferences and config directory path. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.Config)
| `hass.states` | This is the StateMachine. It allows you to set states and track when they are changed. [See available methods.](https://dev-docs.home-assistant.io/en/master/api/core.html#homeassistant.core.StateMachine). |
| `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` %}
Depending on what you're writing, there are different ways the `hass` object is made available.
**Component**<br>
Passed into `setup(hass, config)` or `async_setup(hass, config)`.
**Platform**<br>
Passed into `setup_platform(hass, config, add_devices, discovery_info=None)` or `async_setup_platform(hass, config, async_add_devices, discovery_info=None)`.
**Entity**<br>
Available as `self.hass` once the entity has been added via the `add_devices` callback inside a platform.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/dev_101_hass.html';
</script>

47
source/developers/development_services.markdown
View File

@ -9,47 +9,6 @@ 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.
Services can be called from automation and from the service "Developer tools" in the frontend.
```python
# The domain of your component. Should be equal to the name of your component.
DOMAIN = 'hello_service'
ATTR_NAME = 'name'
DEFAULT_NAME = 'World'
def setup(hass, config):
"""Set up is called when Home Assistant is loading our component."""
def handle_hello(call):
name = call.data.get(ATTR_NAME, DEFAULT_NAME)
hass.states.set('hello_service.hello', name)
hass.services.register(DOMAIN, 'hello', handle_hello)
# Return boolean to indicate that initialization was successfully.
return True
```
Load the component by adding the following to your `configuration.yaml`. When your component is loaded, a new service should be available to call.
```yaml
# configuration.yaml entry
hello_service:
```
Open the frontend and in the sidebar, click the first icon in the developer tool section. This will open the Call Service developer tool. On the right, find your service and click on it. This will automatically fill in the correct values.
Pressing "Call Service" will now call your service without any parameters. This will cause your service to create a state with the default name 'World'. If you want to specify the name, you have to specify parameters. Add the following JSON as Service Data and press "Call Service again".
```json
{
"name": "Planet"
}
```
The service will now overwrite the previous state with "Planet".
<script>
window.location = 'https://developers.home-assistant.io/docs/en/dev_101_services.html';
</script>

132
source/developers/development_states.markdown
View File

@ -9,132 +9,6 @@ sharing: true
footer: true
---
Home Assistant keeps track of the states of entities in a state machine. The state machine has very few requirements:
- Each state is related to an entity identified by an entity id. This id is made up of a domain and an object id. For example `light.kitchen_ceiling`. You can make up any combination of domain and object id, even overwriting existing states.
- Each state has a primary attribute that describes the state of the entity. In the case of a light this could be for example "on" and "off". You can store anything you want in the state, as long as it's a string (will be converted if it's not).
- You can store more information about an entity by setting attributes. Attributes is a dictionary that can contain any data that you want. The only requirement is that it's JSON serializable, so you're limited to numbers, strings, dictionaries and lists.
[Description of the state object.](/docs/configuration/state_object/)
### {% linkable_title 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.
To get started, create the file `<config dir>/custom_components/hello_state.py` and copy the below example code.
```python
"""
Support for showing text in the frontend.
For more details about this component, please refer to the documentation at
https://home-assistant.io/cookbook/python_component_basic_state/
"""
import logging
_LOGGER = logging.getLogger(__name__)
DOMAIN = 'hello_state'
DEPENDENCIES = []
def setup(hass, config):
"""Setup the Hello State component. """
_LOGGER.info("The 'hello state' component is ready!")
return True
```
1. In the file header we decided to add some details: A short description and the link to the documentation.
2. We want to do some logging. This means that we import the Python logging module and create an alias.
3. The component name is equal to the domain name.
4. At the moment this component has no dependencies. For detail check [dependencies](/developers/component_deps_and_reqs/#dependencies) section.
5. The `setup` function will take care of the initialization of our component.
The component will only write a log message. Keep in mind for later that you have several options for the severity:
- `_LOGGER.info(msg)`
- `_LOGGER.warning(msg)`
- `_LOGGER.error(msg)`
- `_LOGGER.critical(msg)`
- `_LOGGER.exception(msg)`
7. We return `True` if everything is ok.
Add the component to your `configuration.yaml` file.
```yaml
hello_state:
```
After a start or a restart of Home Assistant the component will create an entry in the log.
```bash
16-03-12 14:16:42 INFO (MainThread) [custom_components.hello_state] The 'hello state' component is ready!
```
The next step is the introduction of configuration options. A user can pass configuration options to our component via `configuration.yaml`. To use them we'll use the passed in `config` variable to our `setup` method.
```python
import logging
_LOGGER = logging.getLogger(__name__)
DOMAIN = 'hello_state'
DEPENDENCIES = []
CONF_TEXT = 'text'
DEFAULT_TEXT = 'No text!'
def setup(hass, config):
"""Set up the Hello State component. """
# Get the text from the configuration. Use DEFAULT_TEXT if no name is provided.
text = config[DOMAIN].get(CONF_TEXT, DEFAULT_TEXT)
# States are in the format DOMAIN.OBJECT_ID
hass.states.set('hello_state.Hello_State', text)
return True
```
To use the latest feature of our component, update the entry in your `configuration.yaml` file.
```yaml
hello_state:
text: 'Hello, World!'
```
Thanks to `DEFAULT_TEXT` variable the component will launch even if no `text:` field is used in the `configuration.yaml` file. Quite often there are variables which are required. It's important to check if all mandatory configuration variables are provided. If not, the setup should fail. We will use `voluptuous` as a helper to achieve this. The next listing shows the essential parts.
```python
import voluptuous as vol
import homeassistant.helpers.config_validation as cv
CONFIG_SCHEMA = vol.Schema({
DOMAIN: vol.Schema({
vol.Required(CONF_TEXT): cv.string,
})
}, extra=vol.ALLOW_EXTRA)
```
Now, when `text:` is missing from the config, Home Assistant will alert the user and not setup your component.
After a start or a restart of Home Assistant the component will be visible in the frontend if the `configuration.yaml` file is up-to-date.
<p class='img'>
<img src='/images/screenshots/create-component01.png' />
</p>
In order to expose attributes for a platform, you will need to define a property called `device_state_attributes` on the entity class, which will return a dictionary of attributes:
```
@property
def device_state_attributes(self):
"""Return device specific state attributes."""
return self._attributes
```
<p class='note'>
Entities also have a similar property `state_attributes`, which normally doesn't need to be defined by new platforms. This property is used by base components to add standard sets of attributes to a state. Example: The light component uses `state_attributes` to add brightness to the state dictionary. If you are designing a new component, you should define `state_attributes` instead.
</p>
To get your component included in the Home Assistant releases, follow the steps described in the [Submit your work](/developers/development_submitting/) section. Basically you only need to move your component in the `homeassistant/component/` directory of your fork and create a Pull Request.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/dev_101_states.html';
</script>

39
source/developers/development_submitting.markdown
View File

@ -9,39 +9,6 @@ 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.
* 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/).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_submitting.html';
</script>

68
source/developers/development_testing.markdown
View File

@ -9,68 +9,6 @@ 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:
```bash
$ tox
```
**Important:** Run `tox` before you create your pull request to avoid annoying fixes.
Running Tox will run unit tests against the locally available Pythons, as well as validate the code and document style using `pycodestyle`, `pydocstyle` and `pylint`. You can run tests on only one tox target -- just use `-e` to select an environment. For example, `tox -e lint` runs the linters only, and `tox -e py36` runs unit tests only on Python 3.6.
Tox uses virtual environments under the hood to create isolated testing environments. The tox virtual environments will get out-of-date when requirements change, causing test errors. Run `tox -r` to tell Tox to recreate the virtual environments.
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 %}
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.
```bash
# Stop after the first test fails
$ tox -e py36 -- tests/test_core.py -x
# Run test with specified name
$ tox -e py36 -- tests/test_core.py -k test_split_entity_id
# Fail a test after it runs for 2 seconds
$ tox -e py36 -- tests/test_core.py --timeout 2
# Show the 10 slowest tests
$ tox -e py36 -- tests/test_core.py --duration=10
```
### {% linkable_title 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:
```bash
$ pip3 install -r requirements_test_all.txt
```
Now that you have all test dependencies installed, you can run tests on individual files:
```bash
$ flake8 homeassistant/core.py
$ pylint homeassistant/core.py
$ pydocstyle homeassistant/core.py
$ py.test tests/test_core.py
```
You can also run linting tests against all changed files, as reported by `git diff upstream/dev... --diff-filter=d --name-only`, using the `lint` script:
```bash
$ script/lint
```
### {% linkable_title 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!
```bash
$ pip3 install flake8 flake8-docstrings
$ 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 %}
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.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_testing.html';
</script>

79
source/developers/development_validation.markdown
View File

@ -9,79 +9,6 @@ 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.
We test the configuration to ensure that users have a great experience and minimize notifications if something is wrong with a platform or component setup before Home Assistant runs.
Besides [voluptuous](https://pypi.python.org/pypi/voluptuous) default types, many custom types are available. For an overview, take a look at the [config_validation.py](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/helpers/config_validation.py) helper.
- Types: `string`, `byte`, and `boolean`
- Entity ID: `entity_id` and `entity_ids`
- 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:
- Use the constants defined in `const.py`
- Import `PLATFORM_SCHEMA` from the parent component and extend it
- 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 %}
This section contains snippets for the validation we use.
#### {% linkable_title Default name %}
It's common to set a default for a sensor if the user doesn't provide a name to use.
```python
DEFAULT_NAME = 'Sensor name'
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,
```
#### {% linkable_title Limit the values %}
You might want to limit the user's input to a couple of options.
```python
DEFAULT_METHOD = 'GET'
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_METHOD, default=DEFAULT_METHOD): vol.In(['POST', 'GET']),
```
#### {% linkable_title Port %}
All port numbers are from a range of 1 to 65535.
```python
DEFAULT_PORT = 993
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_PORT, default=DEFAULT_PORT): cv.port,
```
#### {% linkable_title Lists %}
If a sensor has a pre-defined list of available options, test to make sure the configuration entry matches the list.
```python
SENSOR_TYPES = {
'article_cache': ('Article Cache', 'MB'),
'average_download_rate': ('Average Speed', 'MB/s'),
}
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
...
vol.Optional(CONF_MONITORED_VARIABLES, default=[]):
vol.All(cv.ensure_list, [vol.In(SENSOR_TYPES)]),
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/development_validation.html';
</script>

94
source/developers/frontend.markdown
View File

@ -9,94 +9,6 @@ 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]
<p class='note warning'>
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 %}
<p class='note'>
All commands below need to be run from inside the home-assistant-polymer repository.
</p>
Home Assistant will by default serve the compiled version of the frontend from the hass_frontend Python package. For development you want to work with the unbundled source files which are in the home-assistant-polymer repository.
First step is to configure Home Assistant to use the development mode for the frontend. Do this by updating the frontend config in your `configuration.yaml` and set the path to the polymer repo:
```yaml
frontend:
development_repo: <absolute path to home-assistant-polymer>
```
Next step is to git clone the [home-assistant-polymer repository][hass-polymer]. You can place the repository anywhere on your system but to keep these instructions simple we're cloning the home-assistant-polymer repository as a sibling to the Home Assistant repo.
```bash
$ git clone https://github.com/home-assistant/home-assistant-polymer.git
$ cd home-assistant-polymer
```
After cloning, your folder structure should look like this:
```text
/home-assistant
/home-assistant-polymer
```
Node.js is required to build the frontend. The preferred method of installing node.js is with [nvm](https://github.com/creationix/nvm). Install nvm using the instructions in the [README](https://github.com/creationix/nvm#install-script), and install the correct node.js by running the following command:
```bash
$ nvm install
```
[Yarn](https://yarnpkg.com/en/) is used as the package manager for node modules. [Install yarn using the instructions here.](https://yarnpkg.com/en/docs/install)
Next, development dependencies need to be installed to bootstrap the frontend development environment. First activate the right Node version and then download all the needed modules and do a first build:
```bash
$ nvm use
$ 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 %}
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.
```bash
$ git remote add <remote name> <github URL to your fork>
```
When you've made your changes and are ready to push them change to the working directory for the polymer project and then push your changes
``` bash
$ git add -A
$ git commit -m "Added new feature X"
$ git push -u <remote name> HEAD
```
## {% linkable_title 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.
```bash
$ yarn run dev-watch
```
The source code for the frontend can be found in different directories:
- UI: `/home-assistant-polymer/src/`
- Panels: `/home-assistant-polymer/panels/`
- Javascript code: `/home-assistant-polymer/js/`
# {% linkable_title 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`
Install it: `pip3 install dist/home-assistant-frontend-xxxxxxxx.0.tar.gz --upgrade`
Run Home Assistant without trying to reinstall production package: `hass --skip-pip`
[hass-polymer]: https://github.com/home-assistant/home-assistant-polymer
<script>
window.location = 'https://developers.home-assistant.io/docs/en/frontend_index.html';
</script>

20
source/developers/frontend_add_card.markdown
View File

@ -9,20 +9,6 @@ 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.
![Cards in the frontend](/images/frontend/frontend-cards1.png)
The different card types can be found [here](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
Sensors, when not [grouped](/components/group/), are shown as so-called badges on top of the state cards.
![Badges in the frontend](/images/frontend/frontend-badges.png)
The different badges are located in the file [`/src/components/entity/ha-state-label-badge.html`](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.html).
Adding a custom card type can be done with a few simple steps. For this example we will add a new state card for the domain `camera`:
1. Add `'camera'` to the array `DOMAINS_WITH_CARD` in the file [/util/hass-util.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L11).
2. Create the files `state-card-camera.html` in the folder [/state-summary/](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
4. Add `<link rel="import" href="state-card-camera.html">` to [state-card-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.html).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/frontend_add_card.html';
</script>

15
source/developers/frontend_add_more_info.markdown
View File

@ -9,15 +9,6 @@ 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.
<p class='img' style='max-width: 400px; margin-left: auto; margin-right: auto;'>
<img src='/images/frontend/frontend-more-info-light.png'>
The more info dialog for a light allows the user to control the color and the brightness.
</p>
The instructions to add a more info dialog are very similar to adding a new card type. This example will add a new more info component for the domain `camera`:
1. Add `'camera'` to the array `DOMAINS_WITH_MORE_INFO` in the file [util/hass-util.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/util/hass-util.html#L24).
2. Create the files `more-info-camera.html` in the folder [/more-infos](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/more-infos).
4. Add `<link rel="import" href="more-info-camera.html">` to [more-info-content.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/more-infos/more-info-content.html)
<script>
window.location = 'https://developers.home-assistant.io/docs/en/frontend_add_more_info.html';
</script>

81
source/developers/frontend_creating_custom_panels.markdown
View File

@ -9,83 +9,6 @@ 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 %}
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.
We therefore advice to set up the frontend to serve the modern version of the frontend so that you won't need any build tools while developing. If you realize that your audience requires both, you can add a transpilation step in the future. To set up your frontend to always serve the latest version, add this to your config:
```
frontend:
javascript_version: latest
```
### {% linkable_title Building your first panel %}
Create a file called `hello.html` in your <config dir>/panels/.
The `hello.html` contains the needed building blocks to create the elements inside the view.
```html
<dom-module id='ha-panel-hello'>
<template>
<style>
p {
font-weight: bold;
}
</style>
<p>Hello {% raw %}{{who}}{% endraw %}. Greetings from Home Assistant.</p>
</template>
</dom-module>
<script>
class HaPanelHello extends Polymer.Element {
static get is() { return 'ha-panel-hello'; }
static get properties() {
return {
// Home Assistant object
hass: Object,
// If should render in narrow mode
narrow: {
type: Boolean,
value: false,
},
// If sidebar is currently shown
showMenu: {
type: Boolean,
value: false,
},
// Home Assistant panel info
// panel.config contains config passed to register_panel serverside
panel: Object,
who: {
type: String,
computed: 'computeWho(panel)',
},
};
}
computeWho(panel) {
return panel && panel.config && panel.config.who ? panel.config.who : 'World';
}
}
customElements.define(HaPanelHello.is, HaPanelHello);
</script>
```
Create an entry for the new panel in your `configuration.yaml` file:
```yaml
panel_custom:
- name: hello
sidebar_title: Hello World
sidebar_icon: mdi:hand-pointing-right
url_path: hello
```
For more possibilities, see the [Custom panel section](/cookbook/#user-interface) on our Examples page.
window.location = 'https://developers.home-assistant.io/docs/en/frontend_creating_custom_panels.html';
</script>

88
source/developers/frontend_creating_custom_ui.markdown
View File

@ -10,90 +10,6 @@ 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.
Put the element source file and its dependencies in `www/custom_ui/` directory under your Home Assistant [configuration](/docs/configuration/) directory.
For example if creating a state card for the `light` domain named `state-card-my-custom-light` put `state-card-my-custom-light.html` in `www/custom_ui/`.
That file should implement `<state-card-my-custom-light>` tag with Polymer.
In `state-card-my-custom-light.html` you should use `<link rel="import">` to import all the dependencies **not** used by Home Assistant's UI.
Do not import any dependencies used by the Home Assistant UI.
Importing those will work in `development: 1` mode, but will fail in production mode.
1. In the `customize:` section of the `configuration.yaml` file put `custom_ui_state_card: state-card-my-custom-light`.
2. In the `frontend` section use `extra_html_url` to specify the URL to load.
Example:
`configuration.yaml`:
```yaml
homeassistant:
customize:
light.bedroom:
custom_ui_state_card: state-card-my-custom-light
frontend:
extra_html_url:
- /local/custom_ui/state-card-my-custom-light.html
```
`www/custom_ui/state-card-my-custom-light.html`:
```html
<script>
{
// show the version of your custom UI in the HA dev info panel (HA 0.66.0+):
const _NAME = 'My custom light';
const _URL = 'https://home-assistant.io/developers/frontend_creating_custom_ui/';
const _VERSION = '20180312';
if (!window.CUSTOM_UI_LIST) window.CUSTOM_UI_LIST = [];
window.CUSTOM_UI_LIST.push({
name: _NAME,
url: _URL,
version: _VERSION
});
}
</script>
<dom-module id='state-card-my-custom-light'>
<template>
<style>
</style>
<textarea>[[_toStr(stateObj)]]</textarea>
</template>
</dom-module>
<script>
class StateCardMyCustomLight extends Polymer.Element {
static get is() { return 'state-card-my-custom-light'; }
static get properties() {
return {
// Home Assistant object
hass: Object,
// inDialog is true if shown as more-info-card
inDialog: {
type: Boolean,
value: false,
},
// includes state, config and more information of the entity
stateObj: Object,
};
}
_toStr(obj) {
return JSON.stringify(obj, null, 2);
}
}
customElements.define(StateCardMyCustomLight.is, StateCardMyCustomLight);
</script>
```
<p class='note'>
Some browsers don't support latest ECMAScript standards, these require a separate ES5 compatible file (`extra_html_url_es5`).
</p>
For more possibilities, see the [Custom UI section](/cookbook/#user-interface) on our Examples page.
window.location = 'https://developers.home-assistant.io/docs/en/frontend_creating_custom_ui.html';
</script>

32
source/developers/hassio/addon_communication.markdown
View File

@ -10,32 +10,6 @@ footer: true
redirect_from: /hassio/addon_config/
---
There are different ways for communication between add-ons inside Hass.io.
## {% linkable_title 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!
Name/alias are used for communication inside Hass.io.
The name is generated using the following format: `{REPO}_{SLUG}`, e.g., `local_xy` or `3283fh_myaddon`. In this example, `{SLUG}` is defined in an add-ons `config.json`. You can use this name also as DNS name but you need replace the `_` with `-` to have a valid hostname. If an add-on is installed locally, `{REPO}` will be `local`. If the add-on is installed from a Github repository, `{REPO}` is a hashed identifier generated from the GitHub repository's URL (ex: https://github.com/xy/my_hassio_addons). See [here](https://github.com/home-assistant/hassio/blob/587047f9d648b8491dc8eef17dc6777f81938bfd/hassio/addons/utils.py#L17) to understand how this identifier is generated. Note that this identifier is required in certain service calls that use the [Hass.io add-on API](hassio-addon-api). You can view the repository identifiers for all currently installed add-ons via a GET request to the hassio API `addons` endpoint.
Use `hassio` for communication with the internal API.
## {% linkable_title 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.
There is also a proxy for the [Home Assistant Websocket API][hass-websocket]. It works like the API proxy above and requires `HASSIO_TOKEN` as password. Use this URL: `http://hassio/homeassistant/websocket`.
It is also possible to talk direct to the Home Assistant instance which is named `homeassistant` over the internal network. But you need to know the configuration that is used by the running instance.
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 %}
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`.
[hass-api]: /developers/rest_api/
[hass-websocket]: /developers/websocket_api/
[hassio-api]: https://github.com/home-assistant/hassio/blob/master/API.md
[hassio-addon-api]: https://github.com/home-assistant/hassio/blob/dev/API.md#restful-for-api-addons
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_communication.html';
</script>

198
source/developers/hassio/addon_config.markdown
View File

@ -10,198 +10,6 @@ footer: true
redirect_from: /hassio/addon_config/
---
Each add-on is stored in a folder. The file structure looks like this:
```text
addon_name/
build.json
CHANGELOG.md
config.json
Dockerfile
icon.png
logo.png
README.md
run.sh
```
## {% linkable_title 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.
When developing your script:
- `/data` is a volume for persistent storage.
- `/data/options.json` contains the user configuration. You can use `jq` inside your shell script to parse this data. However, you might have to install `jq` as a separate package in your container (see `Dockerfile` below).
```bash
CONFIG_PATH=/data/options.json
TARGET="$(jq --raw-output '.target' $CONFIG_PATH)"
```
So if your `options` contain
```json
{ "target": "beer" }
```
then there will be a variable `TARGET` containing `beer` in the environment of your bash file afterwards.
## {% linkable_title 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.
```
ARG BUILD_FROM
FROM $BUILD_FROM
ENV LANG C.UTF-8
# Install requirements for add-on
RUN apk add --no-cache jq
# Copy data for add-on
COPY run.sh /
RUN chmod a+x /run.sh
CMD [ "/run.sh" ]
```
If you don't use local build on device or our build script, make sure that the Dockerfile have also a set of labels include:
```
LABEL io.hass.version="VERSION" io.hass.type="addon" io.hass.arch="armhf|aarch64|i386|amd64"
```
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 %}
We support the following build arguments by default:
| ARG | Description |
|-----|-------------|
| BUILD_FROM | Hold image for dynamic builds or buildings over our systems.
| BUILD_VERSION | Add-on version (read from `config.json`).
| BUILD_ARCH | Hold current build arch inside.
## {% linkable_title Add-on config %}
The config for an add-on is stored in `config.json`.
```json
{
"name": "xy",
"version": "1.2",
"slug": "folder",
"description": "long description",
"arch": ["amd64"],
"url": "website with more information about add-on (ie a forum thread for support)",
"startup": "application",
"boot": "auto",
"ports": {
"123/tcp": 123
},
"map": ["config:rw", "ssl"],
"options": {},
"schema": {},
"image": "repo/{arch}-my-custom-addon"
}
```
| Key | Type | Required | Description |
| --- | ---- | -------- | ----------- |
| name | string | yes | Name of the add-on
| version | string | yes | Version of the add-on
| slug | string | yes | Slug of the add-on
| description | string | yes | Description of the add-on
| arch | list | no | List of supported arch: `armhf`, `aarch64`, `amd64`, `i386`. Default all.
| url | url | no | Homepage of the addon. Here you can explain the add-ons and options.
| startup | bool | yes | `initialize` will start addon on setup of Hass.io. `system` is for things like databases and not dependent on other things. `services` will start before Home Assistant, while `application` is started afterwards. Finally `once` is for applications that don't run as a daemon.
| webui | string | no | A URL for web interface of this add-on. Like `http://[HOST]:[PORT:2839]/dashboard`, the port needs the internal port, which will be replaced with the effective port. It is also possible to bind the proto part to a config options with: `[PROTO:option_name]://[HOST]:[PORT:2839]/dashboard` and he lookup if they is True and going to `https`.
| boot | string | yes | `auto` by system and manual or only `manual`
| ports | dict | no | Network ports to expose from the container. Format is `"container-port/type": host-port`.
| host_network | bool | no | If that is True, the add-on run on host network.
| host_ipc | bool | no | Default False. Allow to share the IPC namespace with others.
| host_dbus | bool | no | Default False. Map Host dbus service into add-on.
| devices | list | no | Device list to map into the add-on. Format is: `<path_on_host>:<path_in_container>:<cgroup_permissions>`. i.e. `/dev/ttyAMA0:/dev/ttyAMA0:rwm`
| auto_uart | bool | no | Default False. Auto mapping all UART/Serial device from host into add-on.
| hassio_api | bool | no | This add-on can access to Hass.io REST API. It set the host alias `hassio`.
| homeassistant_api | bool | no | This add-on can access to Hass.io Home-Assistant REST API proxy. Use `http://hassio/homeassistant/api`.
| privileged | list | no | Privilege for access to hardware/system. Available access: `NET_ADMIN`, `SYS_ADMIN`, `SYS_RAWIO`, `SYS_TIME`, `SYS_NICE`
| apparmor | bool | no | Enable or disable AppArmor support. If it is enable, you can also use custom profiles.
| seccomp | bool | no | Enable or disable Seccomp support. If it is enable, you can also use custom profiles.
| map | list | no | List of maps for additional Hass.io folders. Possible values: `config`, `ssl`, `addons`, `backup`, `share`. Defaults to `ro`, which you can change by adding `:rw` to the end of the name.
| environment | dict | no | A dict of environment variable to run add-on.
| audio | bool | no | Boolean. Mark this add-on to use internal an audio system. The ALSA configuration for this add-on will be mount automatic.
| gpio | bool | no | Boolean. If this is set to True, `/sys/class/gpio` will map into add-on for access to GPIO interface from kernel. Some library need also `/dev/mem` and `SYS_RAWIO` for read/write access to this device.
| stdin | bool | no | Boolean. If that is enable, you can use the STDIN with Hass.io API.
| legacy | bool | no | Boolean. If the docker image have no hass.io labels, you can enable the legacy mode to use the config data.
| options | dict | yes | Default options value of the add-on
| schema | dict | yes | Schema for options value of the add-on. It can be `False` to disable schema validation and use custom options.
| image | string | no | For use with Docker Hub.
| 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 %}
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.
```json
{
"message": "custom things",
"logins": [
{ "username": "beer", "password": "123456" },
{ "username": "cheep", "password": "654321" }
],
"random": ["haha", "hihi", "huhu", "hghg"],
"link": "http://example.com/",
"size": 15,
"count": 1.2
}
```
The `schema` looks like `options` but describes how we should validate the user input. For example:
```json
{
"message": "str",
"logins": [
{ "username": "str", "password": "str" }
],
"random": ["match(^\w*$)"],
"link": "url",
"size": "int(5,20)",
"count": "float",
"not_need": "str?"
}
```
We support:
- str
- bool
- int / int(min,) / int(,max) / int(min,max)
- float / float(min,) / float(,max) / float(min,max)
- email
- url
- port
- match(REGEX)
## {% linkable_title 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.
```json
{
"build_from": {
"armhf": "homeassistant/armhf-base:latest"
},
"squash": false,
"args": {
"my_build_arg": "xy"
}
}
```
| Key | Required | Description |
| --- | -------- | ----------- |
| build_from | no | A dictionary with the hardware architecture as the key and the base Docker image as value.
| squash | no | Default `False`. Be carfully with this option, you can not use the image for caching stuff after that!
| args | no | Allow to set additional Docker build arguments as a dictionary.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_config.html';
</script>

14
source/developers/hassio/addon_development.markdown
View File

@ -10,14 +10,6 @@ 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.
Under the hood, add-ons are Docker images published in [Docker Hub](https://hub.docker.com/). Developers can create [GitHub](https://github.com) repositories that contain multiple references to add-ons for easy sharing with the community.
1. [Tutorial: Making your first add-on](/developers/hassio/addon_tutorial/)
1. [Configuration](/developers/hassio/addon_config/)
1. [Communication](/developers/hassio/addon_communication/)
1. [Local Testing](/developers/hassio/addon_testing/)
1. [Publishing](/developers/hassio/addon_publishing/)
1. [Presentation](/developers/hassio/addon_presentation/)
1. [Repositories](/developers/hassio/addon_repository/)
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_index.html';
</script>

45
source/developers/hassio/addon_presentation.markdown
View File

@ -9,45 +9,6 @@ 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 %}
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.
This file containing the documentation is usually referred to as the "README", which is generally published as the `README.md` file.
Take a look at other projects for inspiration. For example, see the `README.md` of the [Community Hass.io Add-ons: Homebridge](https://github.com/hassio-addons/addon-homebridge/blob/master/README.md) add-on.
In future versions of Hass.io, the `README.md` file will be displayed in the Home Assistant frontend.
## {% linkable_title 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.
Requirements for the logo of your add-on:
- The logo must be in the Portable Network Graphics format (`.png`).
- The filename must be `logo.png`.
- It is recommended to keep the logo size around 250x100px. You may choose to use a different size or aspect ratio as you seem fit for your add-on.
Requirements for the icon of your add-on:
- The icon must be in the Portable Network Graphics format (`.png`).
- The filename must be `icon.png`.
- 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 %}
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.
A changelog is a file which contains a curated, chronologically ordered list of notable changes for each version of your add-on and is generally published as the `CHANGELOG.md` file.
If you are in need of a guide on keeping a changelog, we would recommend checking the [keep a changelog](http://keepachangelog.com) website. They have developed a standard that is used by many opensource projects around the world.
In future versions of Hass.io, the `CHANGELOG.md` file will be displayed in the Home Assistant frontend.
## {% linkable_title 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.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_presentation.html';
</script>

56
source/developers/hassio/addon_publishing.markdown
View File

@ -10,56 +10,6 @@ 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 %}
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 %}
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 %}
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:
```json
{
...
"image": "myhub/image-{arch}-addon-name",
...
}
```
You can use `{arch}` inside the image name to support multiple architectures with 1 configuration file. It will be replaced with the architecture of the user when we load the image. If you use `Buildargs` you can use the `build.json` to overwrite our default args.
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 %}
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.
For a git repository:
```bash
$ docker run --rm --privileged -v ~/.docker:/root/.docker homeassistant/amd64-builder --all -t addon-folder -r https://github.com/xy/addons -b branchname
```
For a local repository:
```bash
$ docker run --rm --privileged -v ~/.docker:/root/.docker -v /my_addon:/data homeassistant/amd64-builder --all -t /data
```
<p class='note'>
If you are developing on macOS and using Docker for Mac, you may encounter an error message similar to the following: <code>error creating aufs mount to /var/lib/docker/aufs/mnt/<SOME_ID>-init: invalid argument</code>. A proposed workaround is to add the following to the Advanced Daemon JSON configuration via Docker > Preferences > Daemon > Advanced: <code>"storage-driver" : "aufs"</code>.
</p>
[builder]: https://github.com/home-assistant/hassio-build/tree/master/builder
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_publishing.html';
</script>

28
source/developers/hassio/addon_repository.markdown
View File

@ -10,28 +10,6 @@ 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 %}
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 %}
Each repository is required to contain `repository.json` at the root in the git repository.
```json
{
"name": "Name of repository",
"url": "http://www.example/addons",
"maintainer": "HomeAssistant Team <info@home-assistant.io>"
}
```
| Key | Required | Description |
| --- | -------- | ----------- |
| name | yes | Name of the repository
| url | no | Homepage of the repository. Here you can explain the various add-ons.
| maintainer | no | Contact info of the maintainer.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_repository.html';
</script>

28
source/developers/hassio/addon_testing.markdown
View File

@ -10,28 +10,6 @@ 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 %}
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:
- armhf: `homeassistant/armhf-base:latest`
- aarch64: `homeassistant/aarch64-base:latest`
- amd64: `homeassistant/amd64-base:latest`
- i386: `homeassistant/i386-base:latest`
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 %}
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 %}
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.
[Samba add-on]: /addons/samba/
[SSH add-on]: /addons/ssh/
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_testing.html';
</script>

199
source/developers/hassio/addon_tutorial.markdown
View File

@ -10,199 +10,6 @@ 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.
To get started with developing add-ons, we first need access to where Hass.io looks for local add-ons. For this you can use the Samba add-on or the SSH add-on.
For Samba, once you have enabled and started it, your Hass.io instance will show up in your local network tab and share a folder called "addons". This is the folder to store your custom add-ons.
If you are on macOS and the folder is not showing up automatically, go to Finder and press CMD+K then enter 'smb://hassio.local'
<p class='img'>
<img src='/images/hassio/tutorial/samba.png' />
With Samba add-on enabled, you can browse to your Hass.io server over the local network. It will contain an addons folder to store your local add-ons.
</p>
For SSH, you will have to install it. Before you can start it, you will have to have a private/public key pair and store your public key in the add-on config ([see docs for more info][ssh]). Once started, you can SSH to Hass.io and store your custom add-ons in "/addons".
<p class='img'>
<img src='/images/hassio/tutorial/ssh.png' />
Once you SSH into your Hass.io box, you have access to your add-ons in "/addons".
</p>
Once you have located your add-on directory, it's time to get started!
[ssh]: /addons/ssh/
## {% linkable_title Step 1: The basics %}
- Create a new directory called `hello_world`
- Inside that directory create three files.
`Dockerfile`:
```
ARG BUILD_FROM
FROM $BUILD_FROM
ENV LANG C.UTF-8
# Copy data for add-on
COPY run.sh /
RUN chmod a+x /run.sh
CMD [ "/run.sh" ]
```
`config.json`:
```json
{
"name": "Hello world",
"version": "1",
"slug": "hello_world",
"description": "My first real add-on!",
"startup": "before",
"boot": "auto",
"options": {},
"schema": {}
}
```
`run.sh`:
```bash
echo Hello world!
```
## {% linkable_title 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.
- Open the Home Assistant frontend
- Go to the Hass.io panel
- On the top right click the shopping basket to go to the add-on store.
<p class='img'>
<img src='/images/hassio/screenshots/main_panel_addon_store.png' />
From the Hass.io main panel open the add-on store.
</p>
- On the top right click the refresh button
- You should now see a new card called "Local" that lists your add-on!
<p class='img'>
<img src='/images/hassio/screenshots/local_repository.png' />
The Hass.io add-on store will list all available local add-ons.
</p>
- Click on your add-on to go to the add-on details page.
- Install your add-on
- Start your add-on
- Refresh the logs of your add-on, you should now see "Hello world!" in your logs.
<p class='img'>
<img src='/images/hassio/tutorial/addon_hello_world_logs.png' />
The add-on will print Hello world to the logs and then quit.
</p>
### {% linkable_title 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.
When this happens, it means that your `config.json` is invalid. It's either invalid JSON or one of the specified options is incorrect. To see what went wrong, go to the Hass.io panel and in the supervisor card click on "View logs". This should bring you to a page with the logs of the supervisor. Scroll to the bottom and you should be able to find the validation error.
Once you fixed the error, go to the add-on store and click refresh again.
## {% linkable_title 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.
To do this, we will need to update our files as follows:
- `Dockerfile`: Install Python 3
- `config.json`: Make the port from the container available on the host
- `run.sh`: Run the Python 3 command to start the HTTP server
Add to your `Dockerfile` before `RUN`:
```
# Install requirements for add-on
RUN apk add --no-cache python3
# Python 3 HTTP Server serves the current working dir
# So let's set it to our add-on persistent data directory.
WORKDIR /data
```
Add "ports" to `config.json`. This will make TCP on port 8000 inside the container available on the host on port 8000.
```json
{
"name": "Hello world",
"version": "0.2",
"slug": "hello_world",
"description": "My first real add-on!",
"startup": "before",
"boot": "auto",
"options": {},
"schema": {},
"ports": {
"8000/tcp": 8000
}
}
```
Update `run.sh` to start the Python 3 server:
```
python3 -m http.server
```
## {% linkable_title 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.
Now navigate to [http://hassio.local:8000](http://hassio.local:8000) to see our server in action!
<p class='img'>
<img src='/images/hassio/tutorial/python3-http-server.png' />
The Python 3 server will allow you to browse the /data folder.
</p>
## {% linkable_title 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.
Let's see if we can get some data into that file!
To do this, we need to specify the default options and a schema for the user to change the options.
Change the options and schema entries in your `config.json` with the following:
```json
{
…
"options": {
"beer": true,
"wine": true,
"liquor": false,
"name": "world",
"year": 2017
},
"schema": {
"beer": "bool",
"wine": "bool",
"liquor": "bool",
"name": "str",
"year": "int"
},
…
}
```
Refresh the add-on store and re-install your add-on. You will now see the options available in the add-on config screen. When you now go back to our Python 3 server and download `options.json`, you'll see the options you set.
- [Learn more about the available schema options.](/hassio/addon_config/#options--schema)
- [See how options.json can be used inside `run.sh`](https://github.com/home-assistant/hassio-addons/blob/master/mosquitto/run.sh#L4-L6)
### [Next step: Add-on config reference &raquo;](/developers/hassio/addon_config/)
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_addon_tutorial.html';
</script>

30
source/developers/hassio/architecture.markdown
View File

@ -10,30 +10,6 @@ footer: true
redirect_from: /hassio/architecture/
---
<p class='img'>
<a href='/images/hassio/architecture.png'><img src='/images/hassio/architecture.png' alt='Architecture overview of Hass.io'></a>
Architecture overview of Hass.io
</p>
### {% linkable_title Host Control (HC) %}
This is a daemon running on the host machine that allows the supervisor to control certain aspects of the host OS:
- Power cycle (restart, turn off)
- Manage network settings
- Local updates
### {% linkable_title 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 %}
The supervisor offers an API to manage the host and running the Docker containers.
### {% linkable_title 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.
[ResinOS]: https://resinos.io/
[linux]: /hassio/installation/#alternative-install-on-generic-linux-server
<script>
window.location = 'https://developers.home-assistant.io/docs/en/architecture_hassio.html';
</script>

46
source/developers/hassio/debugging.markdown
View File

@ -10,46 +10,6 @@ footer: true
redirect_from: /hassio/debugging/
---
<p class='note warning'>
This section is not for users. Use the [SSH add-on] to SSH into Hass.io. This is for <b>developers</b> of Hass.io. Do not ask for support if you are using these options.
</p>
[SSH add-on]: /addons/ssh/
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 %}
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.
Windows instructions how to generate and use private/public keys with Putty are [here][windows-keys]. Instead of the droplet instructions, add the public key as per above instructions.
Alternative instructions, for Mac, Windows and Linux can be found [here](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/#platform-mac).
Follow steps 1-4 under 'Generating a new SSH key' (The other sections are not applicable to Hass.io and can be ignored.)
Step 3 in the link above, shows the path to the private key file `id_rsa` for your chosen operating system. Your public key, `id_rsa.pub`, is saved in the same folder. Next, select all text from text box "Public key for pasting into OpenSSH authorized_keys file" and save it to the root of your SD card as `authorized_keys`.
<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>
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 %}
```bash
# Logs from the supervisor service on the Host OS
journalctl -f -u resin-supervisor.service
# Hass.io supervisor logs
docker logs resin_supervisor
# Home Assistant logs
docker logs homeassistant
```
[windows-keys]: https://www.digitalocean.com/community/tutorials/how-to-use-ssh-keys-with-putty-on-digitalocean-droplets-windows-users
<script>
window.location = 'https://developers.home-assistant.io/docs/en/hassio_debugging.html';
</script>

18
source/developers/helpers.markdown
View File

@ -9,18 +9,6 @@ sharing: true
footer: true
---
There are a bunch of online services which can help you if you are developing for Home Assistant or maintaining components. Some of these are directly connected to Pull Requests and the repositories, while others publish details and updates on our [Discord chat server][discord-devs].
- [Coveralls][coveralls]
- [Travis CI][travis-ci]
- [gemnasium][gemnasium]
- [Requires.io][requires-io]
- [Pivotal Tracker][pivotal]
[coveralls]: https://coveralls.io/github/home-assistant/home-assistant
[travis-ci]: https://travis-ci.org/home-assistant/home-assistant
[gemnasium]: https://gemnasium.com/github.com/home-assistant/home-assistant
[requires-io]: https://requires.io/github/home-assistant/home-assistant/requirements/?branch=dev
[pivotal]: https://www.pivotaltracker.com/n/projects/1250084
[discord-devs]: https://discord.gg/8X8DTH4
<script>
window.location = 'https://developers.home-assistant.io/en';
</script>

17
source/developers/index.markdown
View File

@ -10,17 +10,6 @@ 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!
<p class='img'>
<img src='/images/architecture/component_interaction.png' alt='Diagram showing interaction between components and the Home Assistant core.'>
Diagram showing interaction between components and the Home Assistant core.
</p>
The best way to familiarize yourself with Home Assistant is to watch the PyCon 2016 talk about Home Assistant and read through the [Python API docs].
<div class='videoWrapper'>
<iframe width="560" height="315" src="https://www.youtube.com/embed/Cfasc9EgbMU" frameborder="0" allowfullscreen></iframe>
</div>
[Python API docs]: https://dev-docs.home-assistant.io
<script>
window.location = 'https://developers.home-assistant.io/';
</script>

19
source/developers/intent/conversation.markdown
View File

@ -9,19 +9,6 @@ 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.
As a component, you can register sentences with the conversation component to allow it to be remote controlled. Refer to named slots by putting the slot name between curly braces: `{item}`.
Example code:
```python
@asyncio.coroutine
def async_setup(hass, config):
hass.components.conversation.async_register('MyCoolIntent', [
'I think that {object} is very cool',
'Nothing is cooler than {object}'
])
```
If a sentence like "I think that beer is very cool" comes in, the conversation component will generate an intent of type `MyCoolIntent` and with 1 slot, named `object` and value `beer`.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/intent_conversation.html';
</script>

51
source/developers/intent/firing.markdown
View File

@ -9,51 +9,6 @@ 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.
Example code to handle an intent in Home Assistant.
```python
from homeassistant.helpers import intent
intent_type = 'TurnLightOn'
slots = {
'entity': { 'value': 'Kitchen' }
}
try:
intent_response = yield from intent.async_handle(
hass, 'example_component', intent_type, slots
)
except intent.UnknownIntent as err:
_LOGGER.warning('Received unknown intent %s', intent_type)
except intent.InvalidSlotInfo as err:
_LOGGER.error('Received invalid slot data: %s', err)
except intent.IntentError:
_LOGGER.exception('Error handling request for %s', intent_type)
```
The intent response is an instance of `homeassistant.helpers.intent.IntentResponse`.
| Name | Type | Description |
| ---- | ---- | ----------- |
| `intent` | Intent | Instance of intent that triggered response. |
| `speech` | Dictionary | Speech responses. Each key is a type. Allowed types are `plain` and `ssml`. |
| `card` | Dictionary | Card responses. Each key is a type. |
Speech dictionary values:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `speech` | String | The text to say
| `extra_data` | Any | Extra information related to this speech.
Card dictionary values:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `title` | String | The title of the card
| `content` | Any | The content of the card
<script>
window.location = 'https://developers.home-assistant.io/docs/en/intent_firing.html';
</script>

41
source/developers/intent/handling.markdown
View File

@ -9,41 +9,6 @@ sharing: true
footer: true
---
Any component can register to handle intents. This allows a single component to handle intents fired from multiple voice assistants.
A component has to register an intent handler for each type that it wants to handle. Intent handlers have to extend `homeassistant.helpers.intent.IntentHandler`
```python
import asyncio
from homeassistant.helpers import intent
DATA_KEY = 'example_key'
@asyncio.coroutine
def async_setup(hass, config):
hass.data[DATA_KEY] = 0
intent.async_register(hass, CountInvocationIntent())
class CountInvocationIntent(intent.IntentHandler):
"""Handle CountInvocationIntent intents."""
# Type of intent to handle
intent_type = 'CountInvocationIntent'
# Optional. A validation schema for slots
# slot_schema = {
# 'item': cv.string
# }
@asyncio.coroutine
def async_handle(self, intent_obj):
"""Handle the intent."""
intent_obj.hass.data[DATA_KEY] += 1
response = intent_obj.create_response()
response.async_set_speech(
"This intent has been invoked {} times".format(
intent_obj.hass.data[DATA_KEY]))
return response
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/intent_handling.html';
</script>

29
source/developers/intent/index.markdown
View File

@ -9,29 +9,6 @@ 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.
<p class='img'>
<a href='https://docs.google.com/drawings/d/1i9AsOQNCBCaeM14QwEglZizV0lZiWKHZgroZc9izB0E/edit'><img src='/images/architecture/intents.png' /></a>
Architectural overview of intents in Home Assistant
</p>
Intents are fired by components that receive them from external sources/services. Conversation, Alexa, API.ai and Snips are currently sourcing intents.
Any component can handle intents. This makes it very easy for developers to integrate with all voice assistants at once.
Intents are implemented using the `homeassistant.helpers.intent.Intent` class. It contains the following properties:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `hass` | Home Assistant | The Home Assistant instance that fired the intent.
| `platform` | string | The platform that fired the intent
| `intent_type` | string | The type (name) of the intent
| `slots` | dictionary | Contains the slot values keyed by slot name.
| `text_input` | string | Optional. The raw text input that initiated the intent.
Description of the slots dictionary values.
| Name | Type | Description |
| ---- | ---- | ----------- |
| Value | anything | Value of the slot.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/intent_index.html';
</script>

42
source/developers/internationalization/backend_localization.markdown
View File

@ -10,42 +10,6 @@ footer: true
ha_release: 0.64
---
## {% linkable_title 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:
```bash
$ 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 %}
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 %}
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
{
"config": {
"title": "This title is shown in the integrations list",
"step": {
"init": {
"title": "The user visible title of the `init` step.",
"description": "Markdown that is shown with the step.",
"data": {
"api_key": "The label for the `api_key` input field"
}
}
},
"error": {
"invalid_api_key": "This message will be displayed if `invalid_api_key` is returned as a flow error."
},
"abort": {
"stale_api_key": "This message will be displayed if `stale_api_key` is returned as the abort reason."
}
}
}
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/internationalization_backend_localization.html';
</script>

11
source/developers/internationalization/custom_component_localization.markdown
View File

@ -10,11 +10,6 @@ footer: true
ha_release: 0.64
---
## {% linkable_title 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.
The language codes follow the [BCP47](https://tools.ietf.org/html/bcp47) format. The [frontend translation files](https://github.com/home-assistant/home-assistant-polymer/tree/master/translations) can also be referred to if you are unsure of the correct language code to use.
The frontend will serve these files after Home Assistant is restarted.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/internationalization_custom_component_localization.html';
</script>

10
source/developers/internationalization/index.markdown
View File

@ -10,10 +10,6 @@ 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.
Some compmonents and platforms will have strings that need to be localized specifically for that platform. These strings are managed in the core [home-assistant](https://github.com/home-assistant/home-assistant) repository. The Home Assistant backend will serve strings to the clients based on the loaded components in the running instance.
There are also localizable strings that exist only on the frontend. These strings are managed in the [home-assistant-polymer](https://github.com/home-assistant/home-assistant-polymer) repository. These strings are stored with the frontend and don’t depend on the backend configuration.
Our strings are translated by the community using the online translation tool [Lokalise](https://lokalise.co/).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/internationalization_index.html';
</script>

43
source/developers/internationalization/translation.markdown
View File

@ -11,43 +11,6 @@ ha_release: 0.57
redirect_from: /developers/frontend_translation/
---
## {% linkable_title 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/)
- [Join the backend translation team](https://lokalise.co/signup/130246255a974bd3b5e8a1.51616605/all/)
For more information about the translation workflow, please see the [Lokalise translation workflow documents](https://docs.lokalise.co/category/iOzEuQPS53-for-team-leads-and-translators).
<p class='note'>
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 %}
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 %}
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`.
4. For a region specific translation, keys that will be the same as the base translation should be filled with `[VOID]`. These will be replaced during our translation build process.
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 %}
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
Native Name: Deutsch
```
<p class='note'>
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 %}
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.
Note: Sometimes you have to change the tag in Lokalise (Language -> Language settings -> custom ISO code).
<script>
window.location = 'https://developers.home-assistant.io/docs/en/internationalization_translation.html';
</script>

44
source/developers/maintenance.markdown
View File

@ -9,44 +9,6 @@ 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 %}
### {% linkable_title 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`.
```bash
$ find homeassistant -name "*.py" -exec file {} \; | grep BOM
$ find homeassistant -name "*.py" -exec file {} \; | grep CRLF
```
To fix the line separator, use `dos2unix` or `sed`.
```bash
$ dos2unix homeassistant/components/notify/kodi.py
```
### {% linkable_title File permissions %}
Most files don't need to the be executable. `0644` is fine.
### {% linkable_title 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
```
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 %}
- Merge `current` into `next` on a regular base.
- Optimize the images.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/maintenance.html';
</script>

37
source/developers/multiple_instances.markdown
View File

@ -9,37 +9,6 @@ sharing: true
footer: true
---
# {% linkable_title This has been deprecated and is no longer supported. %}
Home Assistant supports running multiple synchronized instances using a master-slave model. Whenever `events.fire` or `states.set` is called on the slave it will forward it to the master. The master will replicate all events and changed states to its slaves.
<p class='img'>
<a href='/images/architecture/architecture-remote.png'>
<img src='/images/architecture/architecture-remote.png' />
</a>
Overview of the Home Assistant architecture for multiple devices.
</p>
A slave instance can be started with the following code and has the same support for components as a master instance.
```python
import homeassistant.remote as remote
import homeassistant.bootstrap as bootstrap
# Location of the Master API: host, password, port.
# Password and port are optional.
remote_api = remote.API("127.0.0.1", "password", 8124)
# Initialize slave
hass = remote.HomeAssistant(remote_api)
# To add an interface to the slave on localhost:8123
bootstrap.setup_component(hass, 'frontend')
hass.start()
hass.block_till_stopped()
```
<p class='note'>
Because each slave maintains its own Service Registry it is possible to have multiple slaves respond to one service call.
</p>
<script>
window.location = 'https://developers.home-assistant.io/';
</script>

116
source/developers/platform_example_light.markdown
View File

@ -9,116 +9,6 @@ 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.
Similar to Example Sensor Platform, copy the code below, and create it as a file in `<config_dir>/custom_components/light/awesomelights.py`.
Add the following to your configuration.yaml:
```yaml
light:
- platform: awesomelights
host: HOST_HERE
username: USERNAME_HERE
password: PASSWORD_HERE_OR_secrets.yaml
```
Note the `platform` name matches the filename for the source code.
```python
import logging
import voluptuous as vol
# Import the device class from the component that you want to support
from homeassistant.components.light import ATTR_BRIGHTNESS, Light, PLATFORM_SCHEMA
from homeassistant.const import CONF_HOST, CONF_USERNAME, CONF_PASSWORD
import homeassistant.helpers.config_validation as cv
# Home Assistant depends on 3rd party packages for API specific code.
REQUIREMENTS = ['awesome_lights==1.2.3']
_LOGGER = logging.getLogger(__name__)
# Validation of the user's configuration
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
vol.Required(CONF_HOST): cv.string,
vol.Optional(CONF_USERNAME, default='admin'): cv.string,
vol.Optional(CONF_PASSWORD): cv.string,
})
def setup_platform(hass, config, add_devices, discovery_info=None):
"""Setup the Awesome Light platform."""
import awesomelights
# Assign configuration variables. The configuration check takes care they are
# present.
host = config.get(CONF_HOST)
username = config.get(CONF_USERNAME)
password = config.get(CONF_PASSWORD)
# Setup connection with devices/cloud
hub = awesomelights.Hub(host, username, password)
# Verify that passed in configuration works
if not hub.is_valid_login():
_LOGGER.error("Could not connect to AwesomeLight hub")
return False
# Add devices
add_devices(AwesomeLight(light) for light in hub.lights())
class AwesomeLight(Light):
"""Representation of an Awesome Light."""
def __init__(self, light):
"""Initialize an AwesomeLight."""
self._light = light
self._name = light.name
self._state = None
self._brightness = None
@property
def name(self):
"""Return the display name of this light."""
return self._name
@property
def brightness(self):
"""Return the brightness of the light.
This method is optional. Removing it indicates to Home Assistant
that brightness is not supported for this light.
"""
return self._brightness
@property
def is_on(self):
"""Return true if light is on."""
return self._state
def turn_on(self, **kwargs):
"""Instruct the light to turn on.
You can skip the brightness part if your light does not support
brightness control.
"""
self._light.brightness = kwargs.get(ATTR_BRIGHTNESS, 255)
self._light.turn_on()
def turn_off(self, **kwargs):
"""Instruct the light to turn off."""
self._light.turn_off()
def update(self):
"""Fetch new state data for this light.
This is the only method that should fetch new data for Home Assistant.
"""
self._light.update()
self._state = self._light.is_on()
self._brightness = self._light.brightness
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_platform_example_light.html';
</script>

58
source/developers/platform_example_sensor.markdown
View File

@ -9,58 +9,6 @@ sharing: true
footer: true
---
This is a minimum implementation of a platform for the sensor component.
### {% linkable_title Installation %}
Copy the code below and create it as a file in `<config_dir>/custom_components/sensor/example.py`.
Add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
platform: example
```
### {% linkable_title Code %}
```python
from homeassistant.const import TEMP_CELSIUS
from homeassistant.helpers.entity import Entity
def setup_platform(hass, config, add_devices, discovery_info=None):
"""Setup the sensor platform."""
add_devices([ExampleSensor()])
class ExampleSensor(Entity):
"""Representation of a Sensor."""
def __init__(self):
"""Initialize the sensor."""
self._state = None
@property
def name(self):
"""Return the name of the sensor."""
return 'Example Temperature'
@property
def state(self):
"""Return the state of the sensor."""
return self._state
@property
def unit_of_measurement(self):
"""Return the unit of measurement."""
return TEMP_CELSIUS
def update(self):
"""Fetch new state data for the sensor.
This is the only method that should fetch new data for Home Assistant.
"""
self._state = 23
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/creating_platform_example_sensor.html';
</script>

228
source/developers/python_api.markdown
View File

@ -9,228 +9,6 @@ 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.
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.
First import the module and setup the basics:
```python
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'password')
print(remote.validate_api(api))
```
### {% linkable_title Get configuration %}
Get the current configuration of a Home Assistant instance:
```python
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'password')
print(remote.get_config(api))
```
### {% linkable_title 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/).
```python
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
print('-- Available services:')
services = remote.get_services(api)
for service in services:
print(service['services'])
print('\n-- Available events:')
events = remote.get_event_listeners(api)
for event in events:
print(event)
print('\n-- Available entities:')
entities = remote.get_states(api)
for entity in entities:
print(entity)
```
### {% linkable_title Get the state of an entity %}
To get the details of a single entity, use `get_state`:
```python
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
office_temp = remote.get_state(api, 'sensor.office_temperature')
print('{} is {} {}.'.format(
office_temp.name, office_temp.state,
office_temp.attributes['unit_of_measurement'])
)
```
This outputs the details which are stored for this entity, ie:
```bash
Office Temperature is 19 °C.
```
Switches work the same way. The only difference is that both entities have different attributes.
```python
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
switch_livingroom = remote.get_state(api, 'switch.livingroom_pin_2')
print('{} is {}.'.format(
switch_livingroom.name, switch_livingroom.state)
)
```
### {% linkable_title Set the state of an entity %}
Of course, it's possible to set the state as well:
```python
import homeassistant.remote as remote
from homeassistant.const import STATE_ON
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
remote.set_state(api, 'sensor.office_temperature', new_state=123)
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 %}
If you want to turn on all entities of a domain, retrieve the service via `get_services` and act on that:
```python
import time
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
domain = 'switch'
remote.call_service(api, domain, 'turn_on')
time.sleep(10)
remote.call_service(api, domain, 'turn_off')
```
### {% linkable_title Control a single entity %}
To turn on or off a single switch, pass the ID of the entity:
```python
import time
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
domain = 'switch'
switch_name = 'switch.livingroom_pin_2'
remote.call_service(api, domain, 'turn_on', {'entity_id': '{}'.format(switch_name)})
time.sleep(5)
remote.call_service(api, domain, 'turn_off', {'entity_id': '{}'.format(switch_name)})
```
### {% linkable_title 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
`homeassistant.exceptions.HomeAssistantError: Timeout`, unless provided with a
longer timeout.
```python
import homeassistant.remote as remote
api = remote.API('host', 'password')
domain = 'switch'
# Assuming switch.timeout_switch takes 10 seconds to return
switch_name = 'switch.timeout_switch'
# Raises homeassistant.exceptions.HomeAssistantError: Timeout when talking to
remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name})
# Runs withous exception
remote.call_service(api, domain, 'turn_on', {'entity_id': switch_name},
timeout=11)
```
### {% linkable_title Send a notification %}
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
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
domain = 'notify'
data = {"title":"Test", "message":"A simple test message from HA."}
remote.call_service(api, domain, 'jabber', data)
```
## {% linkable_title Examples %}
This section contains a couple of sample scripts.
### {% linkable_title 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.
```python
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
entities = remote.get_states(api)
for entity in entities:
if entity.entity_id.startswith('sensor'):
data = remote.get_state(api, entity.entity_id)
print('{}: {}'.format(data.attributes['friendly_name'], data.state))
```
### {% linkable_title 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.
```python
import time
from prettytable import PrettyTable
import homeassistant.remote as remote
api = remote.API('127.0.0.1', 'YOUR_PASSWORD')
ACTIONS = {
'Create sensor': [21, 'Test'],
'No new sensor value': [21, 'Test'],
'New sensor value': [22, 'Test'],
'Update attribute': [22, 'Test1'],
}
output = PrettyTable(['Action', 'Last changed', 'Last updated'])
for key, value in ACTIONS.items():
remote.set_state(api, 'sensor.test', new_state=value[0],
attributes={'friendly_name': value[1]})
data = remote.get_state(api, 'sensor.test')
output.add_row([key, data.last_changed, data.last_updated])
time.sleep(2)
print(output)
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/external_api_rest_python.html';
</script>

66
source/developers/releasing.markdown
View File

@ -9,66 +9,6 @@ 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) %}
### {% linkable_title 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 %}
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 %}
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 %}
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.
1. Once the release notes has been generated, issue `python3 -m hassrelease milestone_close 0.56`
1. Merge pull request (DO NOT SQUASH!). Use `Merge pull request`.
1. Go to [releases](https://github.com/home-assistant/home-assistant/releases), click `Draft a new release` and tag a new release on the `master` branch. "Tag version" and "Release title" are the version number (`O.x` for major version, `0.x.y` for minor and bug fix releases). Release description is the text from PR. Press "Publish release" to finish the process.
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 %}
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.
1. Run `credits_generator`.
1. Update `_config.yml` with a link to the new release blog post and version number (at the bottom of the file).
1. Merge `current` into release branch (`$ git checkout release-0-40 && git merge current`) to make the PR mergeable.
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 %}
Tags on Docker hub are automatically created when a release has been created on GitHub.
### {% linkable_title 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 %}
1. Use [hootsuite](https://hootsuite.com/dashboard) to publish a link to the release post on social media.
## {% linkable_title 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. Cherry-pick the PRs which were milestoned.
1. Update `homeassistant/const.py` with the correct version number (increment `PATCH_VERSION`) and push that commit to release branch.
1. Create a pull request from the release branch to `master` with the upcoming release number as the title.
1. Merge pull request (DO NOT SQUASH!). Use `Merge pull request`.
1. Go to [releases](https://github.com/home-assistant/home-assistant/releases), click `Draft a new release` and tag a new release on the `master` branch. "Tag version" and "Release title" are the version number (`O.x` for major version, `0.x.y` for minor and bug fix releases). Release description is the text from PR. Press "Publish release" to finish the process.
1. [Publish](/developers/releasing/#python-package-index) the new release on PyPI.
<script>
window.location = 'https://developers.home-assistant.io/docs/en/releasing.html';
</script>

522
source/developers/rest_api.markdown
View File

@ -9,522 +9,6 @@ sharing: true
footer: true
---
Home Assistant runs a web server accessible on port 8123.
* http://IP_ADDRESS:8123/ is an interface to control Home Assistant.
* http://IP_ADDRESS:8123/api/ is a Rest API.
The API accepts and returns only JSON encoded objects. All API calls have to be accompanied by the header `X-HA-Access: YOUR_PASSWORD` (YOUR_PASSWORD as specified in your `configuration.yaml` file in the [`http:` section](/components/http/)).
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`:
```bash
curl -X GET \
-H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
http://IP_ADDRESS:8123/ENDPOINT
```
Another option is to use Python and the [Requests](http://docs.python-requests.org/en/latest/) module. =
```python
from requests import get
url = 'http://localhost:8123/ENDPOINT'
headers = {'x-ha-access': 'YOUR_PASSWORD',
'content-type': 'application/json'}
response = get(url, headers=headers)
print(response.text)
```
<p class='note'>
You can append `?api_password=YOUR_PASSWORD` to any URL to log in automatically.
</p>
Successful calls will return status code 200 or 201. Other status codes that can return are:
- 400 (Bad Request)
- 401 (Unauthorized)
- 404 (Not Found)
- 405 (Method not allowed)
### {% linkable_title Actions %}
The API supports the following actions:
#### {% linkable_title GET /api/ %}
Returns a message if the API is up and running.
```json
{
"message": "API running."
}
```
Sample `curl` command:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/
```
#### {% linkable_title GET /api/config %}
Returns the current configuration as JSON.
```json
{
"components":[
"sensor.cpuspeed",
"frontend",
"config.core",
"http",
"map",
"api",
"sun",
"config",
"discovery",
"conversation",
"recorder",
"group",
"sensor",
"websocket_api",
"automation",
"config.automation",
"config.customize"
],
"config_dir":"/home/ha/.homeassistant",
"elevation":510,
"latitude":45.8781529,
"location_name":"Home",
"longitude":8.458853651,
"time_zone":"Europe/Zurich",
"unit_system":{
"length":"km",
"mass":"g",
"temperature":"\u00b0C",
"volume":"L"
},
"version":"0.56.2",
"whitelist_external_dirs":[
"/home/ha/.homeassistant/www",
"/home/ha/.homeassistant/"
]
}
```
Sample `curl` command:
```bash
$ 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 %}
Returns basic information about the Home Assistant instance as JSON.
```json
{
"base_url": "http://192.168.0.2:8123",
"location_name": "Home",
"requires_api_password": true,
"version": "0.56.2"
}
```
Sample `curl` command:
```bash
$ 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 %}
Returns an array of event objects. Each event object contains event name and listener count.
```json
[
{
"event": "state_changed",
"listener_count": 5
},
{
"event": "time_changed",
"listener_count": 2
}
]
```
Sample `curl` command:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/events
```
#### {% linkable_title GET /api/services %}
Returns an array of service objects. Each object contains the domain and which services it contains.
```json
[
{
"domain": "browser",
"services": [
"browse_url"
]
},
{
"domain": "keyboard",
"services": [
"volume_up",
"volume_down"
]
}
]
```
Sample `curl` command:
```bash
$ 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> %}
Returns an array of state changes in the past. Each object contains further details for the entities.
The `<timestamp>` (`YYYY-MM-DDThh:mm:ssTZD`) is optional and defaults to 1 day before the time of the request. It determines the beginning of the period.
You can pass the following optional GET parameters:
- `filter_entity_id=<entity_id>` to filter on a single entity
- `end_time=<timestamp>` to choose the end of the period in URL encoded format (defaults to 1 day).
```json
[
[
{
"attributes": {
"friendly_name": "Weather Temperature",
"unit_of_measurement": "\u00b0C"
},
"entity_id": "sensor.weather_temperature",
"last_changed": "2016-02-06T22:15:00+00:00",
"last_updated": "2016-02-06T22:15:00+00:00",
"state": "-3.9"
},
{
"attributes": {
"friendly_name": "Weather Temperature",
"unit_of_measurement": "\u00b0C"
},
"entity_id": "sensor.weather_temperature",
"last_changed": "2016-02-06T22:15:00+00:00",
"last_updated": "2016-02-06T22:15:00+00:00",
"state": "-1.9"
},
]
]
```
Sample `curl` commands:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00
```
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
http://localhost:8123/api/history/period/2016-12-29T00:00:00+02:00?filter_entity_id=sensor.temperature
```
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
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 %}
Returns an array of state objects. Each state has the following attributes: entity_id, state, last_changed and attributes.
```json
[
{
"attributes": {},
"entity_id": "sun.sun",
"last_changed": "2016-05-30T21:43:32.418320+00:00",
"state": "below_horizon"
},
{
"attributes": {},
"entity_id": "process.Dropbox",
"last_changed": "22016-05-30T21:43:32.418320+00:00",
"state": "on"
}
]
```
Sample `curl` command:
```bash
$ 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> %}
Returns a state object for specified entity_id. Returns 404 if not found.
```json
{
"attributes":{
"azimuth":336.34,
"elevation":-17.67,
"friendly_name":"Sun",
"next_rising":"2016-05-31T03:39:14+00:00",
"next_setting":"2016-05-31T19:16:42+00:00"
},
"entity_id":"sun.sun",
"last_changed":"2016-05-30T21:43:29.204838+00:00",
"last_updated":"2016-05-30T21:50:30.529465+00:00",
"state":"below_horizon"
}
```
Sample `curl` command:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
http://localhost:8123/api/states/sensor.kitchen_temperature
```
#### {% linkable_title GET /api/error_log %}
Retrieve all errors logged during the current session of Home Assistant as a plaintext response.
```text
15-12-20 11:02:50 homeassistant.components.recorder: Found unfinished sessions
15-12-20 11:03:03 netdisco.ssdp: Error fetching description at http://192.168.1.1:8200/rootDesc.xml
15-12-20 11:04:36 homeassistant.components.alexa: Received unknown intent HelpIntent
```
Sample `curl` command:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
http://localhost:8123/api/error_log
```
#### {% linkable_title GET /api/camera_proxy/camera.&lt;entity_id> %}
Returns the data (image) from the specified camera entity_id.
Sample `curl` command:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
http://localhost:8123/api/camera_proxy/camera.my_sample_camera?time=1462653861261 -o image.jpg
```
#### {% linkable_title POST /api/states/&lt;entity_id> %}
Updates or creates the current state of an entity.
Expects a JSON object that has at least a state attribute:
```json
{
"state": "below_horizon",
"attributes": {
"next_rising":"2016-05-31T03:39:14+00:00",
"next_setting":"2016-05-31T19:16:42+00:00"
}
}
```
The return code is 200 if the entity existed, 201 if the state of a new entity was set. A location header will be returned with the URL of the new resource. The response body will contain a JSON encoded State object.
```json
{
"attributes": {
"next_rising":"2016-05-31T03:39:14+00:00",
"next_setting":"2016-05-31T19:16:42+00:00"
},
"entity_id": "sun.sun",
"last_changed": "2016-05-30T21:43:29.204838+00:00",
"last_updated": "2016-05-30T21:47:30.533530+00:00",
"state": "below_horizon"
}
```
Sample `curl` command:
```bash
$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"state": "25", "attributes": {"unit_of_measurement": "°C"}}' \
http://localhost:8123/api/states/sensor.kitchen_temperature
```
#### {% linkable_title POST /api/events/&lt;event_type> %}
Fires an event with event_type
You can pass an optional JSON object to be used as `event_data`.
```json
{
"next_rising":"2016-05-31T03:39:14+00:00",
}
```
Returns a message if successful.
```json
{
"message": "Event download_file fired."
}
```
#### {% linkable_title 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.
You can pass an optional JSON object to be used as `service_data`.
```json
{
"entity_id": "light.Ceiling"
}
```
Returns a list of states that have changed while the service was being executed.
```json
[
{
"attributes": {},
"entity_id": "sun.sun",
"last_changed": "2016-05-30T21:43:32.418320+00:00",
"state": "below_horizon"
},
{
"attributes": {},
"entity_id": "process.Dropbox",
"last_changed": "22016-05-30T21:43:32.418320+00:00",
"state": "on"
}
]
```
Sample `curl` commands:
Turn the light on:
```bash
$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"entity_id": "switch.christmas_lights"}' \
http://localhost:8123/api/services/switch/turn_on
```
Send a MQTT message:
```bash
$ curl -X POST \
-H "Content-Type: application/json" \
-H "x-ha-access:YOUR_PASSWORD" \
-d '{"payload": "OFF", "topic": "home/fridge", "retain": "True"}' \
http://localhost:8123/api/services/mqtt/publish
```
<p class='note'>
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 %}
Render a Home Assistant template. [See template docs for more information.](/topics/templating/)
```json
{
"template": "Paulus is at {% raw %}{{ states('device_tracker.paulus') }}{% endraw %}!"
}
```
Returns the rendered template in plain text.
```text
Paulus is at work!
```
Sample `curl` command:
```bash
$ curl -X POST -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" \
-d '{"template": "It is {{ now }}!"}' http://localhost:8123/api/template
```
#### {% linkable_title POST /api/event_forwarding %}
Set up event forwarding to another Home Assistant instance.
Requires a JSON object that represents the API to forward to.
```javascript
{
"host": "machine",
"api_password": "my_super_secret_password",
"port": 8880 // optional
}
```
It will return a message if event forwarding was set up successfully.
```json
{
"message": "Event forwarding setup."
}
```
#### {% linkable_title DELETE /api/event_forwarding %}
Cancel event forwarding to another Home Assistant instance.<br>
Requires a JSON object that represents the API to cancel forwarding to.
```javascript
{
"host": "machine",
"api_password": "my_super_secret_password",
"port": 8880 // optional
}
```
It will return a message if event forwarding was canceled successfully.
```json
{
"message": "Event forwarding cancelled."
}
```
<p class='note'>
If your client does not support <code>DELETE</code> HTTP requests you can add an optional attribute <code>_METHOD</code> and set its value to <code>DELETE</code>.
</p>
<script>
window.location = 'https://developers.home-assistant.io/docs/en/external_api_rest.html';
</script>

65
source/developers/server_sent_events.markdown
View File

@ -9,65 +9,6 @@ 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/).
The URI that is generating the data is `/api/stream`.
A requirement on the client-side is existing support for the [EventSource](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) interface.
There are various ways to access the stream. If you have not set an `api_password` in the [`http`](/components/http/) section of your `configuration.yaml` file then you use your modern browser to read the messages. A command-line option is `curl`:
```bash
$ curl -X GET -H "x-ha-access: YOUR_PASSWORD" \
-H "Content-Type: application/json" http://localhost:8123/api/stream
```
You can create a convenient view for this by creating an HTML file (`sse.html`) in the `www` folder of your Home Assistant configuration directory (`.homeassistant`). Paste this snippet into the file:
```html
<!DOCTYPE html>
<html>
<body>
<h1>Getting Home Assistant server events</h1>
<div id="events"></div>
<script type="text/javascript">
var source = new EventSource("/api/stream?api_password=YOUR_PASSWORD");
source.onmessage = function(event) {
document.getElementById("events").innerHTML += event.data + "<br>";
};
</script>
</body>
</html>
```
Visit [http://localhost:8123/local/sse.html](http://localhost:8123/local/sse.html) to see the stream of events.
## {% linkable_title 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:
```bash
$ http --stream http://localhost:8123/api/stream x-ha-access:YOUR_PASSWORD content-type:application/json
```
### {% linkable_title Website %}
The [home-assistant-sse](https://github.com/fabaff/home-assistant-sse) repository contains a more advanced example.
### {% linkable_title 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):
```bash
$ pip3 install sseclient
```
A simple script to consume SSE in Python looks like this:
```python
from sseclient import SSEClient
messages = SSEClient('http://localhost:8123/api/stream?api_password=YOUR_PASSWORD')
for msg in messages:
print(msg)
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/external_api_server_sent_events.html';
</script>

350
source/developers/websocket_api.markdown
View File

@ -9,350 +9,6 @@ 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
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.
## {% linkable_title Server states %}
1. Client connects.
1. Authentication phase starts.
- If no further authentication necessary for the user: go to 3.
- Server sends `auth_required` message.
- Client sends `auth` message.
- If `auth` message correct: go to 3.
- Server sends `auth_invalid`. Go to 6.
1. Send `auth_ok` message
1. Authentication phase ends.
1. Command phase starts.
1. Client can send commands.
1. Server can send results of previous commands.
1. Client or server disconnects session.
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 %}
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.
Example of an auth message:
```json
{
"type": "auth",
"api_password": "supersecret"
}
```
```json
{
"id" 5,
"type":"event",
"event":{
"data":{},
"event_type":"test_event",
"time_fired":"2016-11-26T01:37:24.265429+00:00",
"origin":"LOCAL"
}
}
```
## {% linkable_title 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).
If no authentication is needed, the authentication phase will complete and the server will send an `auth_ok` message.
```json
{
"type": "auth_ok"
}
```
If authentication is necessary, the server sends out `auth_required`.
```json
{
"type": "auth_required"
}
```
This means that the next message from the client should be an auth message:
```json
{
"type": "auth",
"api_password": "supersecret"
}
```
If the client supplies valid authentication, the authentication phase will complete by the server sending the `auth_ok` message:
```json
{
"type": "auth_ok"
}
```
If the data is incorrect, the server will reply with `auth_invalid` message and disconnect the session.
```json
{
"type": "auth_invalid",
"message": "Invalid password"
}
```
## {% linkable_title 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.
```json
{
"id": 6.
"type": "result",
"success": true,
// Can contain extra result info
"result": null
}
```
## {% linkable_title 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.
```json
{
"id": 18,
"type": "subscribe_events",
// Optional
"event_type": "state_changed"
}
```
The server will respond with a result message to indicate that the subscription is active.
```json
{
"id": 18,
"type": "result",
"success": true,
"result": null
}
```
For each event that matches, the server will send a message of type `event`. The `id` in the message will point at the original `id` of the `listen_event` command.
```json
{
"id": 18,
"type":"event",
"event":{
"data":{
"entity_id":"light.bed_light",
"new_state":{
"entity_id":"light.bed_light",
"last_changed":"2016-11-26T01:37:24.265390+00:00",
"state":"on",
"attributes":{
"rgb_color":[
254,
208,
0
],
"color_temp":380,
"supported_features":147,
"xy_color":[
0.5,
0.5
],
"brightness":180,
"white_value":200,
"friendly_name":"Bed Light"
},
"last_updated":"2016-11-26T01:37:24.265390+00:00"
},
"old_state":{
"entity_id":"light.bed_light",
"last_changed":"2016-11-26T01:37:10.466994+00:00",
"state":"off",
"attributes":{
"supported_features":147,
"friendly_name":"Bed Light"
},
"last_updated":"2016-11-26T01:37:10.466994+00:00"
}
},
"event_type":"state_changed",
"time_fired":"2016-11-26T01:37:24.265429+00:00",
"origin":"LOCAL"
}
}
```
### {% linkable_title 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.
```json
{
"id": 19,
"type": "unsubscribe_events",
"subscription": 18
}
```
The server will respond with a result message to indicate that unsubscribing was successful.
```json
{
"id": 19,
"type": "result",
"success": true,
"result": null
}
```
### {% linkable_title 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.
```json
{
"id": 24,
"type": "call_service",
"domain": "light",
"service": "turn_on",
// Optional
"service_data": {
"entity_id": "light.kitchen"
}
}
```
The server will indicate with a message indicating that the service is done executing.
```json
{
"id": 24,
"type": "result",
"success": true,
"result": null
}
```
### {% linkable_title Fetching states %}
This will get a dump of all the current states in Home Assistant.
```json
{
"id": 19,
"type": "get_states"
}
```
The server will respond with a result message containing the states.
```json
{
"id": 19,
"type": "result",
"success": true,
"result": [ ... ]
}
```
### {% linkable_title Fetching config %}
This will get a dump of the current config in Home Assistant.
```json
{
"id": 19,
"type": "get_config"
}
```
The server will respond with a result message containing the config.
```json
{
"id": 19,
"type": "result",
"success": true,
"result": { ... }
}
```
### {% linkable_title Fetching services %}
This will get a dump of the current services in Home Assistant.
```json
{
"id": 19,
"type": "get_services"
}
```
The server will respond with a result message containing the services.
```json
{
"id": 19,
"type": "result",
"success": true,
"result": { ... }
}
```
### {% linkable_title Fetching panels %}
This will get a dump of the current registered panels in Home Assistant.
```json
{
"id": 19,
"type": "get_panels"
}
```
The server will respond with a result message containing the current registered panels.
```json
{
"id": 19,
"type": "result",
"success": true,
"result": [ ... ]
}
```
## {% linkable_title 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`.
| Code | Description |
| ----- | ------------ |
| 1 | A non-increasing identifier has been supplied.
| 2 | Received message is not in expected format (voluptuous validation error).
| 3 | Requested item cannot be found
```json
{
"id": 12,
"type":"result",
"success": false,
"error": {
"code": 2,
"message": "Message incorrectly formatted: expected str for dictionary value @ data['event_type']. Got 100"
}
}
```
<script>
window.location = 'https://developers.home-assistant.io/docs/en/external_api_websocket.html';
</script>

8
source/help/index.markdown
View File

@ -3,7 +3,7 @@ layout: page
title: "Help"
description: "If you need help or have a question..."
date: 2015-06-25 12:30
sidebar: false
sidebar: true
comments: false
sharing: true
footer: true
@ -17,7 +17,7 @@ There are various ways to get in touch with the Home Assistant community. It doe
- [Discord Chat Server][discord] for general Home Assistant discussions and questions.
- Follow us on [Twitter][twitter], use [@home_assistant][twitter]
- Join the [Google+ community][google-plus]
- Join the [Reddit subreddit][reddit] in [/r/homeassistant][reddit]
- Join the Reddit in [/r/homeassistant][reddit]
### {% linkable_title Bugs, Feature requests, and alike %}
@ -77,10 +77,6 @@ Don't miss the regular [Home Assistant podcasts](https://hasspodcast.io/).
- [5 open source home automation tools](https://opensource.com/life/16/3/5-open-source-home-automation-tools) by [opensource.com](https://opensource.com) - March 2016
- [Home Assistant – Open Source Python Home Automation Platform](http://www.automatedhome.co.uk/new-products/home-assistant-open-source-python-home-automation-platform.html) - January 2015
### {% linkable_title Roadmap %}
There is no explicit roadmap available, but the public [tracker](https://www.pivotaltracker.com/n/projects/1250084) can give you some insight into what is going on.
[forum]: https://community.home-assistant.io/
[twitter]: https://twitter.com/home_assistant
[google-plus]: https://plus.google.com/u/0/b/110560654828510104551/communities/106562234893511202708

BIN
source/images/blog/2018-04-google-assistant/google-assistant-home-assistant.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 130 KiB

BIN
source/images/blog/2018-04-hassio-2018/blogpost.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 41 KiB

8
source/index.html
View File

@ -41,6 +41,14 @@ description: Open-source home automation platform running on Python 3. Track and
<a href='/cloud/'>LEARN MORE</a>
</div>
</div>
<div class='material-card text'>
<h1>Ok Google, turn on the AC</h1>
Use Google Assistant to control Home Assistant.
<div class='links'>
<a href='/cloud/'>LEARN MORE</a>
</div>
</div>
<a class='material-card highlight-blog-post' href='/blog/2016/01/19/perfect-home-automation/'>
Read our founder's vision for the perfect home automation <i class="icon-arrow-right"></i>