11 |
12 | 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`:
13 |
14 | 1. Add `'camera'` to the array `DOMAINS_WITH_MORE_INFO` in the file [/common/const.ts](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/common/const.ts).
15 | 2. Create the files `more-info-camera.js` in the folder [/dialogs/more-info/controls](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/dialogs/more-info/controls).
16 | 3. Add `import './more-info-camera.js';` to [/dialogs/more-info/controls/more-info-content.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/dialogs/more-info/controls/more-info-content.js)
17 |
--------------------------------------------------------------------------------
/docs/intent_handling.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Handling intents"
3 | ---
4 |
5 | Any component can register to handle intents. This allows a single component to handle intents fired from multiple voice assistants.
6 |
7 | 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`
8 |
9 | ```python
10 | import asyncio
11 | from homeassistant.helpers import intent
12 |
13 | DATA_KEY = "example_key"
14 |
15 |
16 | @asyncio.coroutine
17 | def async_setup(hass, config):
18 | hass.data[DATA_KEY] = 0
19 | intent.async_register(hass, CountInvocationIntent())
20 |
21 |
22 | class CountInvocationIntent(intent.IntentHandler):
23 | """Handle CountInvocationIntent intents."""
24 |
25 | # Type of intent to handle
26 | intent_type = "CountInvocationIntent"
27 |
28 | # Optional. A validation schema for slots
29 | # slot_schema = {
30 | # 'item': cv.string
31 | # }
32 |
33 | @asyncio.coroutine
34 | def async_handle(self, intent_obj):
35 | """Handle the intent."""
36 | intent_obj.hass.data[DATA_KEY] += 1
37 |
38 | response = intent_obj.create_response()
39 | response.async_set_speech(
40 | f"This intent has been invoked {intent_obj.hass.data[DATA_KEY]} times"
41 | )
42 | return response
43 | ```
44 |
--------------------------------------------------------------------------------
/docs/core/entity/air-quality.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Air Quality Entity
3 | sidebar_label: Air Quality
4 | ---
5 |
6 | ## Properties
7 |
8 | :::tip
9 | Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
10 | :::
11 |
12 | | Name | Type | Default | Description
13 | | ---- | ---- | ------- | -----------
14 | | particulate_matter_2_5 | float | **Required** | The particulate matter 2.5 (<= 2.5 μm) level.
15 | | particulate_matter_10 | float | **Required** | The particulate matter 10 (<= 10 μm) level.
16 | | particulate_matter_0_1 | float | `None` | The particulate matter 0.1 (<= 0.1 μm) level.
17 | | air_quality_index | float | `None` | The Air Quality Index (AQI).
18 | | ozone | float | `None` | The O3 (ozone) level.
19 | | carbon_monoxide | float | `None` | The CO (carbon monoxide) level.
20 | | carbon_dioxide | float | `None` | The CO2 (carbon dioxide) level.
21 | | sulphur_dioxide | float | `None` | The SO2 (sulphur dioxide) level.
22 | | nitrogen_oxide | float | `None` | The N2O (nitrogen oxide) level.
23 | | nitrogen_monoxide | float | `None` | The NO (nitrogen monoxide) level.
24 | | nitrogen_dioxide | float | `None` | The NO2 (nitrogen dioxide) level.
25 | | volatile_organic_compounds | float | `None` | The volatile organic compounds (VOC) level.
26 |
27 | Properties have to follow the units defined in the `unit_system`.
28 |
--------------------------------------------------------------------------------
/docs/core/entity/sensor.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Sensor Entity
3 | sidebar_label: Sensor
4 | ---
5 |
6 | A sensor is a read-only entity that provides some information. Information has a value and optionally, a unit of measurement.
7 |
8 | ## Properties
9 |
10 | :::tip
11 | Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
12 | :::
13 |
14 | | Name | Type | Default | Description
15 | | ---- | ---- | ------- | -----------
16 | | state | string | **Required** | The value of the sensor.
17 | | unit_of_measurement | string | `None` | The unit of measurement that the sensor is expressed in.
18 | | device_class | string | `None` | Type of sensor.
19 |
20 | ### Available device classes
21 |
22 | If specifying a device class, your sensor entity will need to also return the correct unit of measurement.
23 |
24 | | Type | Unit | Description
25 | | ---- | ---- | -----------
26 | | battery | % | % of battery that is left.
27 | | humidity | % | % of humidity in the air.
28 | | illuminance | lx/lm | Light level.
29 | | signal_strength | dB/dBm | Signal strength.
30 | | temperature | °C/°F | Temperature.
31 | | timestamp | ISO8601 | Timestamp.
32 | | power | W,kW | Power.
33 | | pressure | hPa,mbar | Pressure.
34 | | current | A | Current.
35 | | energy | Wh,kWh | Energy.
36 | | power_factor | % | Power Factor.
37 | | voltage | V | Voltage.
38 |
--------------------------------------------------------------------------------
/docs/supervisor.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Home Assistant Supervisor
3 | sidebar_label: Introduction
4 | ---
5 |
6 | The Supervisor allows the user to manage their Home Assistant installation from Home Assistant. The Supervisor has the following responsibilities:
7 |
8 | - Run Home Assistant Core
9 | - Update Home Assistant Core. Automatically roll back if the update fails.
10 | - Make and restore backups
11 | - Add-ons
12 | - Unified audio system
13 | - Update the Home Assistant operating system (disabled in a Supervised installation)
14 |
15 | ## Architecture
16 |
17 | 
19 |
20 |
23 |
24 | - **Home Assistant Core**: home automation platform
25 | - **Add-ons**: extra applications that the user wants to run on their server
26 | - **DNS**: allows core and add-ons to communicate among one another
27 | - **Audio**: allows core and add-ons to play audio
28 | - **mDNS**: help discover and connect to devices and services in the network
29 | - **Supervisor**: manages all parts of the system and keeps it up to date
30 | - **Docker**: container service to run applications.
31 | - **Operating System**: Linux based operating system
32 | - **D-Bus**: communication system to control parts of the operating system like the network manager
33 |
--------------------------------------------------------------------------------
/static/js/api_endpoint.jsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 |
3 | // Styles for this element is defined in src/css/custom.css
4 |
5 | export default class ApiEndpoint extends React.Component {
6 | constructor(props){
7 | super(props);
8 | this.state = {
9 | open: false
10 | }
11 | this.toggleInfo = this.toggleInfo.bind(this);
12 | }
13 |
14 | toggleInfo(e){
15 | this.setState({open: !this.state.open})
16 | }
17 |
18 | render() {
19 | return (
20 |
21 |
45 | );
46 | }
47 | }
--------------------------------------------------------------------------------
/docs/dev_101_config.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Using Config"
3 | ---
4 |
5 | Based on where you are in the code, `config` can mean various things.
6 |
7 | ### On the hass object
8 |
9 | On the hass object it 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)
10 |
11 | ### Config passed into component setup
12 |
13 | 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.
14 |
15 | 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]`.
16 |
17 | If your configuration file contains the following lines:
18 |
19 | ```yaml
20 | example:
21 | host: paulusschoutsen.nl
22 | ```
23 |
24 | Then in the setup method of your component you will be able to refer to `config['example']['host']` to get the value `paulusschoutsen.nl`.
25 |
26 | ### Passed into platform setup
27 |
28 | The `config` parameter passed to a platform setup function is only the config for that specific platform.
29 |
--------------------------------------------------------------------------------
/docs/device_automation_action.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Device Actions"
3 | sidebar_label: Actions
4 | ---
5 |
6 | Device actions allow a user to have a device do something. Examples are to turn a light on or open a door.
7 |
8 | Device actions are defined as dictionaries. These dictionaries are created by your integration and are passed to your integration to create a function that performs the action.
9 |
10 | Device actions can be provided by the integration that provides the device (e.g. ZHA, deCONZ) or the entity integrations that the device has entities with (e.g. light, switch).
11 | An example of the former could be to reboot the device, while an example of the latter could be to turn a light on.
12 |
13 | Home Assistant includes a template to get started with device actions. To get started, run inside a development environment `python3 -m script.scaffold device_action`.
14 |
15 | The template will create a new file `device_action.py` in your integration folder and a matching test file. The file contains the following functions and constants:
16 |
17 | #### `ACTION_SCHEMA`
18 |
19 | This is the schema for actions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_ACTION_BASE_SCHEMA`.
20 |
21 | #### `async def async_get_actions(hass, device_id)`
22 |
23 | Return a list of actions that this device supports.
24 |
25 | #### `async def async_call_action_from_config(hass, config, variables, context)`
26 |
27 | Execute the passed in action.
28 |
--------------------------------------------------------------------------------
/docs/creating_component_generic_discovery.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Integration with Multiple Platforms"
3 | sidebar_label: Multiple platforms
4 | ---
5 |
6 | Most integrations consist of a single platform. And in that case, it's fine to just define that one platform. However, if you are going to add a second platform, you will want to centralize your connection logic. This is done inside the component (`__init__.py`).
7 |
8 | If your integration is configurable via `configuration.yaml`, it will cause the entry point of your configuration to change, as now users will need to set up your integration directly, and it is up to your integration to set up the platforms.
9 |
10 | ## Loading platforms when configured via a config entry
11 |
12 | If your integration is set up via a config entry, you will need to forward the config entry to the appropriate integration to set up your platform. For more info, see the [config entry documentation](config_entries_index.md#for-platforms).
13 |
14 | ## Loading platforms when configured via configuration.yaml
15 |
16 | If your integration is not using config entries, it will have to use our discovery helpers to set up its platforms. Note, this approach does not support unloading.
17 |
18 | To do this, you will need to use the `load_platform` and `async_load_platform` methods from the discovery helper.
19 |
20 | - See also a [full example that implements this logic](https://github.com/home-assistant/example-custom-config/tree/master/custom_components/example_load_platform/)
21 |
--------------------------------------------------------------------------------
/docs/entity_registry_index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Entity Registry
3 | sidebar_label: Introduction
4 | ---
5 |
6 | The entity registry is a registry where Home Assistant keeps track of entities. Any entity that is added to Home Assistant which specifies the [`unique_id` attribute](/core/entity.md#generic-properties) will be registered in the registry.
7 |
8 | Being registered has the advantage that the same entity will always get the same entity ID. It will also prevent other entities from using that entity ID.
9 |
10 | A user is also able to override the name of an entity in the entity registry. When set, the name of the entity registry is used in favor of the name the device might give itself.
11 |
12 | ## Unique ID requirements
13 |
14 | An entity is looked up in the registry based on a combination of the platform type (e.g., `light`), and the integration name (domain) (e.g. hue) and the unique ID of the entity. It is therefore very important that the unique ID is unique! It is also important that it is not possible for the user to change the unique ID, because that means it will lose all its settings related to it.
15 |
16 | Good sources for a unique ID:
17 |
18 | - Serial number of a device
19 | - MAC address of a device
20 | - latitude/longitude
21 |
22 | If a device has a single serial but provides multiple entities, combine the serial with unique identifiers for the entities. For example, if a device measures both temperature and humidity, you can uniquely identify the entities using `{serial}-{sensor_type}`.
23 |
--------------------------------------------------------------------------------
/docs/intent_index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Intents"
3 | sidebar_label: "Introduction"
4 | ---
5 |
6 | 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.
7 |
8 |
9 |
25 |
39 | {this.state.open ? (
40 |
26 | {this.props.method}
27 |
28 | {this.props.path}
29 |
36 | {this.props.unprotected ? ("🔓") : ("🔒")}
37 |
38 |
41 | {this.props.children}
42 |
43 | ): null}
44 | 
13 |
14 |
15 | Intents are fired by components that receive them from external sources/services. Conversation, Alexa, API.ai and Snips are currently sourcing intents.
16 |
17 | Any component can handle intents. This makes it very easy for developers to integrate with all voice assistants at once.
18 |
19 | Intents are implemented using the `homeassistant.helpers.intent.Intent` class. It contains the following properties:
20 |
21 | | Name | Type | Description |
22 | | ---- | ---- | ----------- |
23 | | `hass` | Home Assistant | The Home Assistant instance that fired the intent.
24 | | `platform` | string | The platform that fired the intent
25 | | `intent_type` | string | The type (name) of the intent
26 | | `slots` | dictionary | Contains the slot values keyed by slot name.
27 | | `text_input` | string | Optional. The raw text input that initiated the intent.
28 |
29 | Description of the slots dictionary values.
30 |
31 | | Name | Type | Description |
32 | | ---- | ---- | ----------- |
33 | | Value | anything | Value of the slot.
34 |
--------------------------------------------------------------------------------
/blog/2020-04-16-hassfest.md:
--------------------------------------------------------------------------------
1 | ---
2 | author: Paulus Schoutsen
3 | authorURL: https://twitter.com/balloob
4 | authorImageURL: /img/profile/paulus.jpg
5 | authorTwitter: balloob
6 | title: Hassfest for custom components
7 | ---
8 |
9 | Hassfest is an internal tool that we use in Home Assistant to make sure that all integrations have valid data. We've now made Hassfest able to validate any integration, including custom integrations. To make it easy to get started with this, [@ludeeus](https://www.github.com/ludeeus) has created a GitHub Action that gets you up and running in less than a minute.
10 |
11 | To install it, follow these steps:
12 |
13 | 1. Go to your custom component repository on GitHub
14 | 2. Click on "Create new file"
15 | 3. For filename, paste `.github/workflows/hassfest.yaml`
16 | 4. Paste the following contents:
17 |
18 | ```yaml
19 | name: Validate with hassfest
20 |
21 | on:
22 | push:
23 | pull_request:
24 | schedule:
25 | - cron: "0 0 * * *"
26 |
27 | jobs:
28 | validate:
29 | runs-on: "ubuntu-latest"
30 | steps:
31 | - uses: "actions/checkout@v2"
32 | - uses: home-assistant/actions/hassfest@master
33 | ```
34 |
35 | GitHub will now lint all incoming PRs and commits with hassfest, and will also run it once every night to check against the latest requirements.
36 |
37 | The Hassfest action will track the beta release channel. That way you will be notified if your integration is incompatible with newer versions of Home Assistant.
38 |
--------------------------------------------------------------------------------
/docs/add-ons.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Developing an add-on"
3 | sidebar_label: Introduction
4 | ---
5 |
6 | Add-ons for Home Assistant 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 Supervisor panel in Home Assistant.
7 |
8 | 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.
9 |
10 | - [Tutorial: Making your first add-on](add-ons/tutorial.md)
11 | - [Configuration](add-ons/configuration.md)
12 | - [Communication](add-ons/communication.md)
13 | - [Local Testing](add-ons/testing.md)
14 | - [Publishing](add-ons/publishing.md)
15 | - [Presentation](add-ons/presentation.md)
16 | - [Repositories](add-ons/repository.md)
17 | - [Security](add-ons/security.md)
18 |
19 | Useful links:
20 |
21 | - [Supervisor](https://github.com/home-assistant/supervisor)
22 | - [Core Add-ons](https://github.com/home-assistant/hassio-addons)
23 | - [Docker base images](https://github.com/home-assistant/docker-base)
24 | - [Builder](https://github.com/home-assistant/hassio-builder)
25 | - [Home Assistant community Add-ons](https://github.com/hassio-addons)
26 | - [Home Assistant Operating System](https://github.com/home-assistant/operating-system)
27 | - [Home Assistant Docker](https://github.com/home-assistant/docker)
28 |
--------------------------------------------------------------------------------
/blog/2020-05-08-instance-url-helper.md:
--------------------------------------------------------------------------------
1 | ---
2 | author: Franck Nijhof
3 | authorURL: https://twitter.com/frenck
4 | authorImageURL: /img/profile/frenck.png
5 | authorTwitter: frenck
6 | title: Instance URL helper
7 | ---
8 |
9 | If you are an integration developer and came across the problem of getting the
10 | URL of the users' Home Assistant instance, you probably know, this wasn't always
11 | easy.
12 |
13 | The main problem is that a Home Assistant instance is generally installed, at home.
14 | Meaning the internal and external address can be different and even those can
15 | have variations (for example, if a user has a Home Assistant Cloud subscription).
16 |
17 | Matters become worse if the integration has specific requirements for the URL;
18 | for example, it must be externally available and requires SSL.
19 |
20 | As of Home Assistant Core 0.110, a new instance URL helper is introduced to
21 | ease that. We started out with the following flow chart to solve this issue:
22 |
23 | [](/img/en/blog/2020-05-instance-url-helper/flowchart.png)
24 |
25 | As a result of this, the previously available `base_url` is now replaced by two
26 | new core configuration settings for the user: the internal and external URL.
27 |
28 | From a development perspective, the use of `hass.config.api.base_url` is now
29 | deprecated in favor of the new `get_url` helper method.
30 |
31 | For more information on using and implementing this new URL helper method,
32 | consult our documentation [here](/docs/instance_url).
33 |
--------------------------------------------------------------------------------
/docs/architecture_index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Architecture"
3 | sidebar_label: "Introduction"
4 | ---
5 |
6 | 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.
7 |
8 | For more information about each part in this overview, [check out our blog](https://www.home-assistant.io/blog/2014/12/26/home-control-home-automation-and-the-smart-home). Here's the tl;dr version of the blog:
9 |
10 | - Home Control is responsible for collecting information and controlling devices.
11 | - Home Automation triggers commands based on user configurations.
12 | - Smart Home triggers commands based on previous behavior.
13 |
14 | 
18 |
19 | The Home Assistant core is responsible for Home Control. Home Assistant contains four parts which make this possible:
20 |
21 | - **Event Bus**: facilitates the firing and listening of events -- the beating heart of Home Assistant.
22 | - **State Machine**: keeps track of the states of things and fires a `state_changed` event when a state has been changed.
23 | - **Service Registry**: listens on the event bus for `call_service` events and allows other code to register services.
24 | - **Timer**: sends a `time_changed` event every 1 second on the event bus.
25 |
26 | 
30 |
--------------------------------------------------------------------------------
/docs/device_automation_condition.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Device Conditions"
3 | sidebar_label: Conditions
4 | ---
5 |
6 | Device conditions allow a user to check if a certain condition is met. Examples are is a light on or is the floor wet.
7 |
8 | Device conditions are defined as dictionaries. These dictionaries are created by your integration and are passed to your integration to create a function that checks the condition.
9 |
10 | Device conditions can be provided by the integration that provides the device (e.g. ZHA, deCONZ) or the entity integrations that the device has entities with (e.g. light, humidity sensor).
11 | An example of the latter could be to check if a light is on or the floor is wet.
12 |
13 | Home Assistant includes a template to get started with device conditions. To get started, run inside a development environment `python3 -m script.scaffold device_condition`.
14 |
15 | The template will create a new file `device_condition.py` in your integration folder and a matching test file. The file contains the following functions and constants:
16 |
17 | #### `CONDITION_SCHEMA`
18 |
19 | This is the schema for conditions. The base schema should be extended from `homeassistant.helpers.config_validation.DEVICE_CONDITION_BASE_SCHEMA`.
20 |
21 | #### `async def async_get_conditions(hass, device_id)`
22 |
23 | Return a list of conditions that this device supports.
24 |
25 | #### `async def async_condition_from_config(config, config_validation)`
26 |
27 | Create a condition function from a function. The condition functions should be an async-friendly callback that evaluates the condition and returns a `bool`.
28 |
--------------------------------------------------------------------------------
/docs/frontend/extending/adding-state-card.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Adding state card"
3 | ---
4 |
5 | The main interface of Home Assistant is a list of the current entities and their states. For each entity in the system, a state card will be rendered. State cards will show an icon, the name of the entity, when the state has last changed and the current state or a control to interact with it.
6 |
7 | 
8 |
9 | The different card types can be found [here](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
10 |
11 | Sensors, when not grouped, are shown as so-called badges on top of the state cards.
12 |
13 | 
14 |
15 | The different badges are located in the file [`/src/components/entity/ha-state-label-badge.ts`](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/components/entity/ha-state-label-badge.ts).
16 |
17 | 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`:
18 |
19 | 1. Add `'camera'` to the array `DOMAINS_WITH_CARD` in the file [/common/const.ts](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/common/const.ts).
20 | 2. Create the files `state-card-camera.js` in the folder [/state-summary/](https://github.com/home-assistant/home-assistant-polymer/tree/master/src/state-summary).
21 | 3. Add `import './state-card-camera.js';` to [state-card-content.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/state-summary/state-card-content.js).
22 |
--------------------------------------------------------------------------------
/blog/2020-05-14-entity-class-names.md:
--------------------------------------------------------------------------------
1 | ---
2 | author: Paulus Schoutsen
3 | authorURL: https://github.com/balloob
4 | authorTwitter: balloob
5 | title: Entity class names
6 | ---
7 |
8 | Ever wondered when implementing entities for our entity integrations why you had to extend `BinarySensorDevice` and not `BinarySensorEntity`? Wonder no longer, as we have addressed the situation in Home Assistant 0.110 by renaming all classes that incorrectly had Device in their name. The old classes are still around but will log a warning when used.
9 |
10 | All integrations in Home Assistant have been upgraded. Custom component authors need to do the migration themselves. You can do this while keeping backwards compatibility by using the following snippet:
11 |
12 | ```python
13 | try:
14 | from homeassistant.components.binary_sensor import BinarySensorEntity
15 | except ImportError:
16 | from homeassistant.components.binary_sensor import BinarySensorDevice as BinarySensorEntity
17 | ```
18 |
19 | The following classes have been renamed:
20 |
21 | | Old Class Name | New Class Name |
22 | | -------------------- | -------------------- |
23 | | `BinarySensorDevice` | `BinarySensorEntity` |
24 | | `MediaPlayerDevice` | `MediaPlayerEntity` |
25 | | `LockDevice` | `LockEntity` |
26 | | `ClimateDevice` | `ClimateEntity` |
27 | | `CoverDevice` | `CoverEntity` |
28 | | `VacuumDevice` | `VacuumEntity` |
29 | | `RemoteDevice` | `RemoteEntity` |
30 | | `Light` | `LightEntity` |
31 | | `SwitchDevice` | `SwitchEntity` |
32 | | `WaterHeaterDevice` | `WaterHeaterEntity` |
33 |
--------------------------------------------------------------------------------
/docs/integration_events.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Firing events"
3 | ---
4 |
5 | Some integrations represent devices or services that have events, like when motion is detected or a momentary button is pushed. An integration can make these available to users by firing them as events in Home Assistant.
6 |
7 | Your integration should fire events of type `
. It's the path after the text "Path to configuration.yaml".
9 |
10 | 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.
11 |
12 | :::info
13 | The Home Assistant API has two variants: a synchronous and an asynchronous version (asyncio). This development course will focus on the synchronous version.
14 | :::
15 |
16 | 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:
17 |
18 | ```python
19 | # The domain of your component. Equal to the filename of your component.
20 | DOMAIN = "hello_world"
21 |
22 |
23 | def setup(hass, config):
24 | """Setup the hello_world component."""
25 | # States are in the format DOMAIN.OBJECT_ID.
26 | hass.states.set("hello_world.Hello_World", "Works!")
27 |
28 | # Return boolean to indicate that initialization was successfully.
29 | return True
30 | ```
31 |
32 | Last step is to add `hello_world:` entry to your `configuration.yaml` file.
33 |
34 | ```yaml
35 | # Hello World component
36 | hello_world:
37 | ```
38 |
39 | After running `hass`, we should see log entries stating that `hello_world` component was loaded. What is more, an additional state card will appear within the main panel.
40 |
41 | ```log
42 | 2018-04-03 21:44:20 INFO (MainThread) [homeassistant.loader] Loaded hello_world from custom_components.hello_world
43 | 2018-04-03 21:44:20 INFO (MainThread) [homeassistant.setup] Setting up hello_world
44 | ```
45 |
46 | 
50 |
--------------------------------------------------------------------------------
/docs/config_entries_options_flow_handler.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Integration Configuration Options
3 | sidebar_label: Configuration Options
4 | ---
5 |
6 | An integration that is configured via a config entry can expose options to the user to allow tweaking behavior of the integration, like which devices or locations should be integrated.
7 |
8 | Config Entry Options uses the [Data Flow Entry framework](data_entry_flow_index.md) to allow users to update a config entries options. Components that want to support config entry options will need to define an Options Flow Handler.
9 |
10 | ## Options support
11 |
12 | For an integration to support options it needs to have an `async_get_options_flow` method in its config flow handler. Calling it will return an instance of the components options flow handler.
13 |
14 | ```python
15 | @staticmethod
16 | @callback
17 | def async_get_options_flow(config_entry):
18 | return OptionsFlowHandler()
19 | ```
20 |
21 | ## Flow handler
22 |
23 | The Flow handler works just like the config flow handler, except that the first step in the flow will always be `async_step_init`.
24 |
25 | ```python
26 | class OptionsFlowHandler(config_entries.OptionsFlow):
27 | async def async_step_init(self, user_input=None):
28 | """Manage the options."""
29 | if user_input is not None:
30 | return self.async_create_entry(title="", data=user_input)
31 |
32 | return self.async_show_form(
33 | step_id="init",
34 | data_schema=vol.Schema(
35 | {
36 | vol.Required(
37 | "show_things",
38 | default=self.config_entry.options.get("show_things"),
39 | ): bool
40 | }
41 | ),
42 | )
43 | ```
44 |
45 | ## Signal updates
46 |
47 | If the component should act on updated options, you can register an update listener to the config entry that will be called when the entry is updated.
48 |
49 | ```python
50 | unsub = entry.add_update_listener(update_listener)
51 | ```
52 |
53 | The Listener shall be an async function that takes the same input as async_setup_entry. Options can then be accessed from `entry.options`.
54 |
55 | ```python
56 | async def update_listener(hass, entry):
57 | """Handle options update."""
58 | ```
59 |
60 | Don't forget to unsubscribe the update listener when your config entry is unloaded. You can do this by calling the unsubscribe function returned from adding the listener:
61 |
62 | ```python
63 | unsub()
64 | ```
65 |
--------------------------------------------------------------------------------
/docs/development_submitting.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Submit your work"
3 | ---
4 |
5 | :::tip
6 | Always base your Pull Requests off of the current **`dev`** branch, not `master`.
7 | :::
8 |
9 | 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:
10 |
11 | 1. From your fork's dev branch, create a new branch to hold your changes:
12 |
13 | `git checkout -b some-feature`
14 |
15 | 2. Make your changes, create a [new platform](creating_platform_index.md), develop a [new integration](creating_component_index.md), or fix [issues](https://github.com/home-assistant/home-assistant/issues).
16 |
17 | 3. [Test your changes](development_testing.md) and check for style violations.
18 | Consider adding tests to ensure that your code works.
19 |
20 | 4. If everything looks good according to these [musts](development_checklist.md), commit your changes:
21 |
22 | `git add .`
23 |
24 | `git commit -m "Add some feature"`
25 |
26 | - Write a meaningful commit message and not only something like `Update` or `Fix`.
27 | - Use a capital letter to start with your commit message and do not finish with a full-stop (period).
28 | - Don't prefix your commit message with `[bla.bla]` or `platform:`.
29 | - Write your commit message using the imperative voice, e.g. `Add some feature` not `Adds some feature`.
30 |
31 |
32 | 5. Push your committed changes back to your fork on GitHub:
33 |
34 | `git push origin HEAD`
35 |
36 | 6. Follow [these steps](https://help.github.com/articles/creating-a-pull-request/) to create your pull request.
37 |
38 | - On GitHub, navigate to the [main page of the Home Assistant repository](https://github.com/home-assistant/core).
39 | - In the "Branch" menu, choose the branch that contains your commits (from your fork).
40 | - To the right of the Branch menu, click **New pull request**.
41 | - 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.
42 | - Type a title and complete the provided template for your pull request.
43 | - Click **Create pull request**.
44 |
45 | 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/).
46 |
--------------------------------------------------------------------------------
/docs/core/entity/lock.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Lock Entity
3 | sidebar_label: Lock
4 | ---
5 |
6 | A lock entity is able to be locked and unlocked. Locking and unlocking can optionally be secured with a user code. Some locks also allow for opening of latches, this may also be secured with a user code. Derive a platform entity from [`homeassistant.components.lock.LockEntity`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/lock/__init__.py).
7 |
8 | ## Properties
9 |
10 | :::tip
11 | Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
12 | :::
13 |
14 | | Name | Type | Default | Description
15 | | ---- | ---- | ------- | -----------
16 | | changed_by | string | None | Describes what the last change was triggered by.
17 | | code_format | string | None | Regex for code format or None if no code is required.
18 | | is_locked | bool | None | Indication of whether the lock is currently locked. Used to determine `state`.
19 |
20 | ### Supported Features
21 |
22 | Supported features constants are combined using the bitwise or (`|`) operator.
23 |
24 | | Constant | Description |
25 | |----------|--------------------------------------|
26 | | `SUPPORT_OPEN` | This lock supports opening the door latch.
27 |
28 | ## Methods
29 |
30 | ### Lock
31 |
32 | ```python
33 | class MyLock(LockEntity):
34 |
35 | def lock(self, **kwargs):
36 | """Lock all or specified locks. A code to lock the lock with may optionally be specified."""
37 |
38 | async def async_lock(self, **kwargs):
39 | """Lock all or specified locks. A code to lock the lock with may optionally be specified."""
40 | ```
41 |
42 | ### Unlock
43 |
44 | ```python
45 | class MyLock(LockEntity):
46 |
47 | def unlock(self, **kwargs):
48 | """Unlock all or specified locks. A code to unlock the lock with may optionally be specified."""
49 |
50 | async def async_unlock(self, **kwargs):
51 | """Unlock all or specified locks. A code to unlock the lock with may optionally be specified."""
52 | ```
53 |
54 | ### Open
55 |
56 | Only implement this method if the flag `SUPPORT_OPEN` is set.
57 |
58 | ```python
59 | class MyLock(LockEntity):
60 |
61 | def open(self, **kwargs):
62 | """Open (unlatch) all or specified locks. A code to open the lock with may optionally be specified."""
63 |
64 | async def async_open(self, **kwargs):
65 | """Open (unlatch) all or specified locks. A code to open the lock with may optionally be specified."""
66 | ```
67 |
--------------------------------------------------------------------------------
/docs/core/entity/switch.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Switch Entity
3 | sidebar_label: Switch
4 | ---
5 |
6 | A switch entity turns on or off something, for example a relay. Derive a platform entity from [`homeassistant.components.switch.SwitchEntity`](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/switch/__init__.py).
7 | To represent something which can be turned on or off but can't be controlled, for example a wall switch which transmits its state but can't be turned on or off from Home Assistant, a Binary Sensor is a better choice.
8 | To represent something which doesn't have a state, for example a door bell push button, a custom event or a Device Trigger is a better choice.
9 |
10 | ## Properties
11 |
12 | :::tip
13 | Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
14 | :::
15 |
16 | | Name | Type | Default | Description
17 | | ---- | ---- | ------- | -----------
18 | | is_on | boolean | **Required** | If the switch is currently on or off.
19 | | current_power_w | float | `None` | The current power usage in W.
20 | | today_energy_kwh | float | `None` | Total energy usage in kWh.
21 | | is_standby | boolean | `None` | Indicate if the device connected to the switch is currently in standby.
22 |
23 | ## Methods
24 |
25 | ### Turn On
26 |
27 | Turn the switch on.
28 |
29 | ```python
30 | class MySwitch(SwitchEntity):
31 | # Implement one of these methods.
32 |
33 | def turn_on(self, **kwargs) -> None:
34 | """Turn the entity on."""
35 |
36 | async def async_turn_on(self, **kwargs):
37 | """Turn the entity on."""
38 | ```
39 |
40 | ### Turn Off
41 |
42 | Turn the switch off.
43 |
44 | ```python
45 | class MySwitch(SwitchEntity):
46 | # Implement one of these methods.
47 |
48 | def turn_off(self, **kwargs):
49 | """Turn the entity off."""
50 |
51 | async def async_turn_off(self, **kwargs):
52 | """Turn the entity off."""
53 | ```
54 |
55 | ### Toggle
56 |
57 | Optional. If not implemented will default to checking what method to call using the `is_on` property.
58 |
59 | ```python
60 | class MySwitch(SwitchEntity):
61 | # Implement one of these methods.
62 |
63 | def toggle(self, **kwargs):
64 | """Toggle the entity."""
65 |
66 | async def async_toggle(self, **kwargs):
67 | """Toggle the entity."""
68 | ```
69 |
70 | ### Available device classes
71 |
72 | Optional. What type of device this. It will possibly map to google device types.
73 |
74 | | Value | Description
75 | | ----- | -----------
76 | | outlet | Device is an outlet for power.
77 | | switch | Device is switch for some type of entity.
78 |
--------------------------------------------------------------------------------
/docs/api_lib_index.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Building a Python library for an API"
3 | sidebar_label: "Introduction"
4 | ---
5 |
6 | One of the foundational rules of Home Assistant is that we do not include any protocol specific code. Instead, this code should be put into a standalone Python library and published to PyPI. This guide will describe how to get started with this!
7 |
8 | For this guide we're going to assume that we're building a library for a Rest API that is accessible over HTTP and returning data structured as JSON objects. This is the most common type of API that we see. These APIs can either be accessible on the device itself, or in the cloud.
9 |
10 | This guide is not a perfect fit for every API. You might have to tweak the examples.
11 |
12 | :::info
13 | If you are a manufacturer designing a new API for your product, [please read about the best type of API to add to your products here](https://www.home-assistant.io/blog/2016/02/12/classifying-the-internet-of-things/#local-device-pushing-new-state).
14 | :::
15 |
16 | HTTP API requests consist of four different parts:
17 |
18 | - The URL. This is the path that we fetch data from. With a Rest API the URL will uniquely identify the resource. Examples of urls are `http://example.com/api/lights` and `http://example.com/api/light/1234`.
19 | - The HTTP method. This defines what we want from the API. The most common ones are:
20 | - `GET` for when we want to get information like the state of a light
21 | - `POST` for if we want something to be done (ie turn on a light)
22 | - The body. This is the data that we sent to the server to identify what needs to be done. This is how we send the command in the case of a `POST` request.
23 | - The headers. This contains metadata to describe your request. This will used to attach the authorization to the request.
24 |
25 | ## Structuring the library
26 |
27 | Our library will consist of two different parts:
28 |
29 | - **Authentication:** Responsible for making authenticated HTTP requests to the API endpoint and returning the results. This is the only piece of code that will actually interact with the API.
30 | - **Data models:** Represent the data and offer commands to interact with the data.
31 |
32 | ## Trying your library inside Home Assistant
33 |
34 | You will need to run an editable version of your library if you want to try your library in Home Assistant before it is published to PyPI.
35 |
36 | Do so by going to your Home Assistant development environment, activating the virtual environment and typing:
37 |
38 | ```shell
39 | pip3 install -e ../my_lib_folder
40 | ```
41 |
42 | Now run Home Assistant without installing dependencies from PyPI to avoid overriding your package.
43 |
44 | ```shell
45 | hass --skip-pip
46 | ```
47 |
--------------------------------------------------------------------------------
/docs/dev_101_events.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Using Events"
3 | ---
4 |
5 | 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].
6 |
7 | 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.
8 |
9 | [List of events that Home Assistant fires.][object]
10 |
11 | ## Firing events
12 |
13 | 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`. Please be mindful of the data structure as documented on our [Data Science portal](https://data.home-assistant.io/docs/events/#database-table).
14 |
15 | Example component that will fire an event when loaded. Note that custom event names are prefixed with the component name.
16 |
17 | ```python
18 | DOMAIN = "example_component"
19 |
20 |
21 | def setup(hass, config):
22 | """Set up is called when Home Assistant is loading our component."""
23 |
24 | # Fire event example_component_my_cool_event with event data answer=42
25 | hass.bus.fire("example_component_my_cool_event", {"answer": 42})
26 |
27 | # Return successful setup
28 | return True
29 | ```
30 |
31 | ## Listening to events
32 |
33 | 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.
34 |
35 | ```python
36 | DOMAIN = "example_component"
37 |
38 |
39 | def setup(hass, config):
40 | """Set up is called when Home Assistant is loading our component."""
41 | count = 0
42 |
43 | # Listener to handle fired events
44 | def handle_event(event):
45 | nonlocal count
46 | count += 1
47 | print(f"Answer {count} is: {event.data.get('answer')}")
48 |
49 | # Listen for when example_component_my_cool_event is fired
50 | hass.bus.listen("example_component_my_cool_event", handle_event)
51 |
52 | # Return successful setup
53 | return True
54 | ```
55 |
56 | ### Helpers
57 |
58 | 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]
59 |
60 | [helpers]: https://dev-docs.home-assistant.io/en/master/api/helpers.html#module-homeassistant.helpers.event
61 | [object]: https://www.home-assistant.io/docs/configuration/events/
62 |
--------------------------------------------------------------------------------
/docs/frontend/architecture.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Frontend Architecture"
3 | sidebar_label: "Architecture"
4 | ---
5 |
6 | The Home Assistant frontend is built using web components. This is a modern web technology allowing us to encapsulate templates, styling and logic into a single file and expose it as an HTML tag in the browser. These components are composable, allowing a very dynamic and powerful foundation of our application.
7 |
8 | ## Structure
9 |
10 | The Home Assistant frontend can be broken up in 4 parts:
11 |
12 | ### Bootstrap
13 |
14 | File: `src/entrypoints/core.js`
15 |
16 | This is a very tiny script which is the first thing that is loaded on the page. It is responsible for checking for authentication credentials and setting up the websocket connection with the backend.
17 |
18 | The script allows us to start downloading the data while also downloading the rest of the UI in parallel.
19 |
20 | ### App shell
21 |
22 | File: `src/entrypoints/app.js`
23 |
24 | This is everything that is required to render the sidebar and handle the routing.
25 |
26 | ### Panels
27 |
28 | Folder: `src/panels/`
29 |
30 | Each page in Home Assistant is a panel. Components can register extra panels to be shown to the user. Examples of panels are "states", "map", "logbook" and "history".
31 |
32 | ### Dialogs
33 |
34 | Folder: `src/dialogs`
35 |
36 | Certain information and data entry is presented to users in flows. Dialogs can be triggered on any page. The most common one is the entity more info dialog, which allows users to dig into an entity state, history and setting.s
37 |
38 | ## Data Flow
39 |
40 | The frontend leverages the [Websocket API](api/websocket.md) and the [Rest API](api/rest.md) to interact with Home Assistant.
41 |
42 | The data is made available as the `hass` property which is passed down to every component. The `hass` property contains the core state and has methods to call APIs.
43 |
44 | Components can subscribe to information that is not available in the core state. Subscriptions run through the websocket API which keeps the data in sync with the backend.
45 |
46 | We use a unidirectional data flow. When you make a change in the backend (like turning on a light), the `hass` object will be updated at the root of the application and will be made available to every component that needs it.
47 |
48 | ## Routing
49 |
50 | The frontend uses decentralized routing. Each component only knows enough about the routing to know how to handle the part it's responsible for. Further routing is passed down the component tree.
51 |
52 | For example, the `${card}
`)}`;
44 | }
45 | }
46 | ```
47 |
48 | And you can define this element in the Custom Element Registry just as you would with a Custom Card:
49 |
50 | ```js
51 | customElements.define("my-new-view", MyNewView);
52 | ```
53 |
54 | You can find an example of this in our default view: `Masonry View` Located here: [frontend/src/panels/lovelace/views/hui-masonry-view.ts](https://github.com/home-assistant/frontend/blob/master/src/panels/lovelace/views/hui-masonry-view.ts)
55 |
56 | A user who downloads and installs your new Custom View can then use it via editing the YAML configuration of their view to be:
57 |
58 | ```yaml
59 | - title: Home View
60 | type: custom:my-new-view
61 | badges: [...]
62 | cards: [...]
63 | ```
64 |
65 | Custom Developers can add a `layout` property to each card that can store a key, position info, width, height, etc:
66 |
67 | ```yaml
68 | - type: weather-card
69 | layout:
70 | key: 1234
71 | width: 54px
72 | entity: weather.my_weather
73 | ```
74 |
75 | ### Breaking Change
76 |
77 | For Custom Card developers that use something like this:
78 |
79 | ```js
80 | const LitElement = Object.getPrototypeOf(customElements.get("hui-view"));
81 | ```
82 |
83 | You will no longer be able to use the `hui-view` element to retrieve LitElement as it has been changed to be an `updatingElement`. Instead you can use:
84 |
85 | ```js
86 | const LitElement = Object.getPrototypeOf(customElements.get("hui-masonry-view"));
87 | ```
88 |
89 | But Note! This is not supported by HA. In the future, this may not work to import LitElement.
90 |
--------------------------------------------------------------------------------
/static/js/discourse_discussion.jsx:
--------------------------------------------------------------------------------
1 | import React from 'react';
2 | import PropTypes from 'prop-types';
3 |
4 | export default class DiscussionBox extends React.Component {
5 |
6 | constructor(props) {
7 | super(props);
8 | this.postMessageReceived = this.postMessageReceived.bind(this);
9 | }
10 |
11 | componentDidMount() {
12 | this.DiscourseEmbed = {
13 | discourseUrl: this.props.discourseUrl,
14 | discourseEmbedUrl: this.props.discourseEmbedUrl,
15 | };
16 | window.addEventListener('message', this.postMessageReceived, false);
17 | }
18 |
19 | componentWillUnmount() {
20 | window.removeEventListener('message', this.postMessageReceived);
21 | }
22 |
23 | getIframeSource() {
24 | const { discourseUrl, discourseEmbedUrl, discourseUserName } = this.props;
25 | const queryParams = {};
26 |
27 | if (discourseEmbedUrl) {
28 | if (discourseEmbedUrl.indexOf('/') === 0) {
29 | console.error('discourseEmbedUrl must be a full URL, not a relative path');
30 | }
31 |
32 | queryParams.embed_url = encodeURIComponent(discourseEmbedUrl);
33 | }
34 |
35 | if (discourseUserName) {
36 | queryParams.discourse_username = discourseUserName;
37 | }
38 |
39 | let src = discourseUrl + 'embed/comments';
40 | const keys = Object.keys(queryParams);
41 | if (keys.length > 0) {
42 | src += '?';
43 |
44 | for (let i = 0; i < keys.length; i++) {
45 | if (i > 0) { src += '&'; }
46 |
47 | const k = keys[i];
48 | src += k + '=' + queryParams[k];
49 | }
50 | }
51 |
52 | return src;
53 | }
54 |
55 | postMessageReceived(e) {
56 | if (!e) { return; }
57 |
58 | const iframe = this.iframe;
59 | const { discourseUrl } = this.props;
60 |
61 | if (normalizeUrl(discourseUrl).indexOf(normalizeUrl(e.origin)) === -1) { return; }
62 |
63 | if (e.data) {
64 | if (e.data.type === 'discourse-resize' && e.data.height) {
65 | iframe.height = e.data.height + 'px';
66 | }
67 |
68 | if (e.data.type === 'discourse-scroll' && e.data.top) {
69 | // find iframe offset
70 | const destY = findPosY(iframe) + e.data.top;
71 | window.scrollTo(0, destY);
72 | }
73 | }
74 | }
75 |
76 | render() {
77 | return (
78 |
81 |