/www` directory, it will be accessible in your browser via the url `/local/` (if you have recently added the www folder you will need to re-start Home Assistant for files to be picked up).
+
+Add a resource to your dashboard configuration with URL `/local/text-badge.js` and type `module` ([resource docs](/docs/frontend/custom-ui/registering-resources)).
+
+You can then use your badge in your dashboard configuration:
+
+```yaml
+# Example dashboard configuration
+views:
+ - name: Example
+ badges:
+ - type: "custom:text-badge"
+ entity: light.bedside_lamp
+```
+
+## API
+
+Custom badges are defined as a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Polymer, Angular, Preact or any other popular framework (except for React – [more info on React here](https://custom-elements-everywhere.com/#react)).
+
+Home Assistant will call `setConfig(config)` when the configuration changes (rare). If you throw an exception if the configuration is invalid, Home Assistant will render an error badge to notify the user.
+
+Home Assistant will set [the `hass` property](/docs/frontend/data/) when the state of Home Assistant changes (frequent). Whenever the state changes, the component will have to update itself to represent the latest state.
+
+## Graphical badge configuration
+
+Your badge can define a `getConfigElement` method that returns a custom element for editing the user configuration. Home Assistant will display this element in the badge editor in the dashboard.
+
+Your badge can also define a `getStubConfig` method that returns a default badge configuration (without the `type:` parameter) in json form for use by the badge type picker in the dashboard.
+
+Home Assistant will call the `setConfig` method of the config element on setup.
+Home Assistant will update the `hass` property of the config element on state changes, and the `lovelace` element, which contains information about the dashboard configuration.
+
+Changes to the configuration are communicated back to the dashboard by dispatching a `config-changed` event with the new configuration in its detail.
+
+To have your badge displayed in the badge picker dialog in the dashboard, add an object describing it to the array `window.customBadges`. Required properties of the object are `type` and `name` (see example below).
+
+```js
+import "./text-badge-editor.js";
+
+class TextBadge extends HTMLElement {
+
+ ...
+
+ static getConfigElement() {
+ return document.createElement("text-badge-editor");
+ }
+
+ static getStubConfig() {
+ return { entity: "sun.sun" };
+ }
+}
+
+customElements.define("text-badge", TextBadge);
+```
+
+```js
+class TextBadgeEditor extends HTMLElement {
+ setConfig(config) {
+ this._config = config;
+ }
+
+ configChanged(newConfig) {
+ const event = new Event("config-changed", {
+ bubbles: true,
+ composed: true,
+ });
+ event.detail = { config: newConfig };
+ this.dispatchEvent(event);
+ }
+}
+
+customElements.define("text-badge-editor", TextBadgeEditor);
+window.customBadges = window.customBadges || [];
+window.customBadges.push({
+ type: "text-badge",
+ name: "Text badge",
+ preview: false, // Optional - defaults to false
+ description: "A custom badge made by me!", // Optional
+ documentationURL:
+ "https://developers.home-assistant.io/docs/frontend/custom-ui/custom-badge", // Adds a help link in the frontend badge editor
+});
+```
diff --git a/docs/frontend/custom-ui/custom-card-feature.md b/docs/frontend/custom-ui/custom-card-feature.md
new file mode 100644
index 00000000..f294fb5a
--- /dev/null
+++ b/docs/frontend/custom-ui/custom-card-feature.md
@@ -0,0 +1,116 @@
+---
+title: "Custom card feature"
+---
+
+Some dashboard cards have support for [features](https://www.home-assistant.io/dashboards/features/). These widgets add quick controls to the card. We offer a lot of built-in features, but you're not just limited to the ones that we decided to include in Home Assistant. You can build and use your own in the same way as defining [custom cards](/docs/frontend/custom-ui/custom-card).
+
+## Defining your card feature
+
+Below is an example of a custom card feature for [button entity](/docs/core/entity/button/).
+
+
+
+```js
+import {
+ LitElement,
+ html,
+ css,
+} from "https://unpkg.com/lit-element@2.0.1/lit-element.js?module";
+
+const supportsButtonPressCardFeature = (stateObj) => {
+ const domain = stateObj.entity_id.split(".")[0];
+ return domain === "button";
+};
+
+class ButtonPressCardFeature extends LitElement {
+ static get properties() {
+ return {
+ hass: undefined,
+ config: undefined,
+ stateObj: undefined,
+ };
+ }
+
+ static getStubConfig() {
+ return {
+ type: "custom:button-press-card-feature",
+ label: "Press",
+ };
+ }
+
+ setConfig(config) {
+ if (!config) {
+ throw new Error("Invalid configuration");
+ }
+ this.config = config;
+ }
+
+ _press(ev) {
+ ev.stopPropagation();
+ this.hass.callService("button", "press", {
+ entity_id: this.stateObj.entity_id,
+ });
+ }
+
+ render() {
+ if (
+ !this.config ||
+ !this.hass ||
+ !this.stateObj ||
+ !supportsButtonPressCardFeature(this.stateObj)
+ ) {
+ return null;
+ }
+
+ return html`
+
+ ${this.config.label || "Press"}
+
+ `;
+ }
+
+ static get styles() {
+ return css`
+ .button {
+ display: block;
+ height: var(--feature-height, 42px);
+ width: 100%;
+ border-radius: var(--feature-border-radius, 12px);
+ border: none;
+ background-color: #eeeeee;
+ cursor: pointer;
+ transition: background-color 180ms ease-in-out;
+ }
+ .button:hover {
+ background-color: #dddddd;
+ }
+ .button:focus {
+ background-color: #cdcdcd;
+ }
+ `;
+ }
+}
+
+customElements.define("button-press-card-feature", ButtonPressCardFeature);
+
+window.customCardFeatures = window.customCardFeatures || [];
+window.customCardFeatures.push({
+ type: "button-press-card-feature",
+ name: "Button press",
+ supported: supportsButtonPressCardFeature, // Optional
+ configurable: true, // Optional - defaults to false
+});
+```
+
+If you want your feature to better integrate with the default design of home assistant, you can use these CSS variables:
+
+- `--feature-height`: Recommended height (42px).
+- `--feature-border-radius`: Recommended border radius (12px). It be can useful to set button or slider border radius.
+- `--feature-button-spacing`: Recommended space between buttons (12px). It can be useful if you have multiple buttons in your feature.
+
+The main difference with custom cards is the graphical configuration option.
+To have it displayed in the card editor, you must add an object describing it to the array `window.customCardFeatures`.
+
+Required properties of the object are `type` and `name`. It is recommended to define the `supported` option with a function, so the editor can only propose the feature if it is compatible with the selected entity in the card. Set `configurable` to `true` if your entity has additional configuration (e.g. `label` option in the example above) so the editor.
+
+Also, the static functions `getConfigElement` and `getStubConfig` work the same as with normal custom cards.
diff --git a/docs/frontend/custom-ui/custom-card.md b/docs/frontend/custom-ui/custom-card.md
index 51ce5942..04dd556e 100644
--- a/docs/frontend/custom-ui/custom-card.md
+++ b/docs/frontend/custom-ui/custom-card.md
@@ -1,5 +1,5 @@
---
-title: "Custom Cards"
+title: "Custom card"
---
[Dashboards](https://www.home-assistant.io/dashboards/) are our approach to defining your user interface for Home Assistant. We offer a lot of built-in cards, but you're not just limited to the ones that we decided to include in Home Assistant. You can build and use your own!
@@ -46,10 +46,20 @@ class ContentCardExample extends HTMLElement {
}
// The height of your card. Home Assistant uses this to automatically
- // distribute all cards over the available columns.
+ // distribute all cards over the available columns in masonry view
getCardSize() {
return 3;
}
+
+ // The rules for your card for sizing your card if the grid in section view
+ getLayoutOptions() {
+ return {
+ grid_rows: 3,
+ grid_columns: 2,
+ grid_min_rows: 3,
+ grid_max_rows: 3,
+ };
+ }
}
customElements.define("content-card-example", ContentCardExample);
@@ -76,11 +86,15 @@ views:
Custom cards are defined as a [custom element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements). It's up to you to decide how to render your DOM inside your element. You can use Polymer, Angular, Preact or any other popular framework (except for React – [more info on React here](https://custom-elements-everywhere.com/#react)).
+### Configuration
+
Home Assistant will call `setConfig(config)` when the configuration changes (rare). If you throw an exception if the configuration is invalid, Home Assistant will render an error card to notify the user.
Home Assistant will set [the `hass` property](/docs/frontend/data/) when the state of Home Assistant changes (frequent). Whenever the state changes, the component will have to update itself to represent the latest state.
-Your card can define a `getCardSize` method that returns the size of your card as a number or a promise that will resolve to a number. A height of 1 is equivalent to 50 pixels. This will help Home Assistant distribute the cards evenly over the columns. A card size of `1` will be assumed if the method is not defined.
+### Sizing in masonry view
+
+Your card can define a `getCardSize` method that returns the size of your card as a number or a promise that will resolve to a number. A height of 1 is equivalent to 50 pixels. This will help Home Assistant distribute the cards evenly over the columns in the [masonry view](https://www.home-assistant.io/dashboards/masonry/). A card size of `1` will be assumed if the method is not defined.
Since some elements can be lazy loaded, if you want to get the card size of another element, you should first check it is defined.
@@ -90,7 +104,39 @@ return customElements
.then(() => element.getCardSize());
```
-Your card can define a `getConfigElement` method that returns a custom element for editing the user configuration. Home Assistant will display this element in the card editor in the dashboard.
+### Sizing in sections view
+
+You card can define a `getLayoutOptions` method that returns the min, max and default number of cells your card will take in the grid if your card is used if the [sections view](https://www.home-assistant.io/dashboards/masonry/)
+If you don't define this method, the card will take 4 columns (full width) and will ignore the rows of the grid.
+
+A cell of the grid is defined with the following dimension:
+
+- width: between `80px` and `120px` depending on the screen size
+- height: `56px`
+- gap between cells: `8px`
+
+The different layout options are:
+
+- `grid_rows`: Default number of rows the card takes
+- `grid_min_rows`: Minimal number of rows the card takes
+- `grid_max_rows`: Maximal number of rows the card takes
+- `grid_columns`: Default number of columns the card takes
+- `grid_min_columns`: Minimal number of columns the card takes
+- `grid_max_columns`: Maximal number of columns the card takes
+
+Example of implementation:
+
+```js
+public getLayoutOptions() {
+ return {
+ grid_rows: 2,
+ grid_columns: 2,
+ grid_min_rows: 2,
+ };
+}
+```
+
+In this example, the card will take 2 x 2 cells by default. The height of the card cannot be smaller than 2 rows. According to the cell dimension, the card will have a height of `120px` (`2` * `56px` + `8px`).
## Advanced example
@@ -267,121 +313,7 @@ window.customCards.push({
name: "Content Card",
preview: false, // Optional - defaults to false
description: "A custom card made by me!", // Optional
- documentationURL: "https://developers.home-assistant.io/docs/frontend/custom-ui/custom-card/", // Adds a help link in the frontend card editor
+ documentationURL:
+ "https://developers.home-assistant.io/docs/frontend/custom-ui/custom-card", // Adds a help link in the frontend card editor
});
```
-
-## Tile features
-
-The tile card has support for "features" to add quick actions to control the entity. We offer some built-in features, but you can build and use your own using similar way than defining custom cards.
-
-Below is an example of a custom tile feature for [button entity](/docs/core/entity/button/).
-
-
-
-```js
-import {
- LitElement,
- html,
- css,
-} from "https://unpkg.com/lit-element@2.0.1/lit-element.js?module";
-
-const supportsButtonPressTileFeature = (stateObj) => {
- const domain = stateObj.entity_id.split(".")[0];
- return domain === "button";
-};
-
-class ButtonPressTileFeature extends LitElement {
- static get properties() {
- return {
- hass: undefined,
- config: undefined,
- stateObj: undefined,
- };
- }
-
- static getStubConfig() {
- return {
- type: "custom:button-press-tile-feature",
- label: "Press",
- };
- }
-
- setConfig(config) {
- if (!config) {
- throw new Error("Invalid configuration");
- }
- this.config = config;
- }
-
- _press(ev) {
- ev.stopPropagation();
- this.hass.callService("button", "press", {
- entity_id: this.stateObj.entity_id,
- });
- }
-
- render() {
- if (
- !this.config ||
- !this.hass ||
- !this.stateObj ||
- !supportsButtonPressTileFeature(this.stateObj)
- ) {
- return null;
- }
-
- return html`
-
-
- ${this.config.label || "Press"}
-
-
- `;
- }
-
- static get styles() {
- return css`
- .container {
- display: flex;
- flex-direction: row;
- padding: 0 12px 12px 12px;
- width: auto;
- }
- .button {
- display: block;
- width: 100%;
- height: 40px;
- border-radius: 6px;
- border: none;
- background-color: #eeeeee;
- cursor: pointer;
- transition: background-color 180ms ease-in-out;
- }
- .button:hover {
- background-color: #dddddd;
- }
- .button:focus {
- background-color: #cdcdcd;
- }
- `;
- }
-}
-
-customElements.define("button-press-tile-feature", ButtonPressTileFeature);
-
-window.customTileFeatures = window.customTileFeatures || [];
-window.customTileFeatures.push({
- type: "button-press-tile-feature",
- name: "Button press",
- supported: supportsButtonPressTileFeature, // Optional
- configurable: true, // Optional - defaults to false
-});
-```
-
-The only difference with custom cards is the graphical configuration option.
-To have it displayed in the tile card editor, you must add an object describing it to the array `window.customTileFeatures`.
-
-Required properties of the object are `type` and `name`. It is recommended to define the `supported` option with a function so the editor can only propose the feature if it is compatible with the selected entity in the tile card. Set `configurable` to `true` if your entity has additional configuration (e.g. `label` option in the example above) so the editor.
-
-Also, the static functions `getConfigElement` and `getStubConfig` work the same as with normal custom maps.
diff --git a/docs/frontend/custom-ui/custom-strategy.md b/docs/frontend/custom-ui/custom-strategy.md
index f4dd5baa..a9406be9 100644
--- a/docs/frontend/custom-ui/custom-strategy.md
+++ b/docs/frontend/custom-ui/custom-strategy.md
@@ -1,5 +1,5 @@
---
-title: "Custom Strategies"
+title: "Custom strategies"
---
_Introduced in Home Assistant 2021.5._
@@ -12,7 +12,7 @@ A strategy can be applied to the whole configuration or to a specific view.
Strategies are defined as a custom element in a JavaScript file, and included [via dashboard resources](./registering-resources.md). Home Assistant will call static functions on the class instead of rendering it as a custom element.
-## Dashboard Strategies
+## Dashboard strategies
A dashboard strategy is responsible for generating a full dashboard configuration. This can either be from scratch, or based on an existing dashboard configuration that is passed in.
@@ -52,7 +52,7 @@ strategy:
type: custom:my-demo
```
-## View Strategies
+## View strategies
A view strategy is responsible for generating the configuration of a specific dashboard view. The strategy is invoked when the user opens the specific view.
@@ -88,7 +88,7 @@ views:
type: custom:my-demo
```
-## Full Example
+## Full example
It's recommended for a dashboard strategy to leave as much work to be done to the view strategies. That way the dashboard will show up for the user as fast as possible. This can be done by having the dashboard generate a configuration with views that rely on its own strategy.
diff --git a/docs/frontend/custom-ui/custom-view.md b/docs/frontend/custom-ui/custom-view.md
index c7065cd7..1ce731b0 100644
--- a/docs/frontend/custom-ui/custom-view.md
+++ b/docs/frontend/custom-ui/custom-view.md
@@ -1,8 +1,8 @@
---
-title: "Custom View Layout"
+title: "Custom view layout"
---
-By default Home Assistant will try to show the cards in a masonry layout (like Pinterest). A Custom View Layout allows developers to override this and define the layout mechanism (like a grid).
+By default Home Assistant will try to show the cards in a masonry layout (like Pinterest). A custom view layout allows developers to override this and define the layout mechanism (like a grid).
## API
@@ -63,7 +63,7 @@ A custom view can be used by adding the following to the definition of your view
The default masonry view is an example of a layout element. ([source](https://github.com/home-assistant/frontend/blob/master/src/panels/lovelace/views/hui-masonry-view.ts)).
-## Store Custom Data
+## Store custom data
If your view requires data to persist at a card level, there is a `view_layout` in the card configuration that can be used to store information. Example: Key, X and Y coordinates, width and height, etc. This can be useful when you need to store the location or dimensions of a card for your view.
@@ -75,7 +75,7 @@ If your view requires data to persist at a card level, there is a `view_layout`
entity: weather.my_weather
```
-## Edit, Delete, or Add a Card
+## Edit, delete, or add a card
To call the core frontend dialogs to edit, delete or add a card, you can simply call these three events:
diff --git a/docs/frontend/custom-ui/registering-resources.md b/docs/frontend/custom-ui/registering-resources.md
index 841f3712..d81a6166 100644
--- a/docs/frontend/custom-ui/registering-resources.md
+++ b/docs/frontend/custom-ui/registering-resources.md
@@ -1,5 +1,5 @@
---
-title: "Registering Resources"
+title: "Registering resources"
---
If you want to extend the Home Assistant interface with custom cards, strategies or views you need to load external resources.
diff --git a/docs/frontend/data.md b/docs/frontend/data.md
index 9ad5a3e2..fbeaeab1 100644
--- a/docs/frontend/data.md
+++ b/docs/frontend/data.md
@@ -108,7 +108,7 @@ All methods starting with `call` are async methods. This means that they will re
### `hass.callService(domain, service, data)`
-Call a service on the backend.
+Call a service action on the backend.
```js
hass.callService('light', 'turn_on', {
diff --git a/docs/frontend/design.md b/docs/frontend/design.md
index dbc8f49e..01841031 100644
--- a/docs/frontend/design.md
+++ b/docs/frontend/design.md
@@ -3,14 +3,14 @@ title: "Frontend design"
sidebar_label: "Design"
---
-We maintain a design portal at that provides information about various frontend aspects such as:
+We maintain a design portal at [https://design.home-assistant.io](https://design.home-assistant.io) that provides information about various frontend aspects such as:
* UI components that can be reused.
* Dashboard cards in various configurations and states.
* Easy way to compare components and cards between light and dark themes.
* Notes about specific wording in Home Assistant.
-When new components or features are added to the frontend, those need to be added to the design portal. This portal page explains the details on how to do so:
+When new components or features are added to the frontend, those need to be added to the design portal. This portal page explains the details on how to do so: [https://design.home-assistant.io/#design.home-assistant.io/editing](https://design.home-assistant.io/#design.home-assistant.io/editing)
:::note
While the portal is publically named "design", it is referred to as "gallery" in the frontend repository. That is why the script to run the gallery locally in your development environment can be found at `gallery/script/develop_gallery` and the source code in `gallery/src`.
diff --git a/docs/frontend/development.md b/docs/frontend/development.md
index 59248906..2f0dd764 100644
--- a/docs/frontend/development.md
+++ b/docs/frontend/development.md
@@ -67,6 +67,7 @@ Next, development dependencies need to be installed to bootstrap the frontend de
```shell
nvm use
script/bootstrap
+script/setup_translations
```
## Development
diff --git a/docs/frontend/extending/adding-state-card.md b/docs/frontend/extending/adding-state-card.md
index a694c8df..96190c2b 100644
--- a/docs/frontend/extending/adding-state-card.md
+++ b/docs/frontend/extending/adding-state-card.md
@@ -17,5 +17,5 @@ The different badges are located in the file [`/src/components/entity/ha-state-l
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 [/common/const.ts](https://github.com/home-assistant/frontend/blob/dev/src/common/const.ts).
- 2. Create the files `state-card-camera.js` in the folder [/state-summary/](https://github.com/home-assistant/frontend/tree/dev/src/state-summary).
- 3. Add `import './state-card-camera.js';` to [state-card-content.js](https://github.com/home-assistant/frontend/blob/dev/src/state-summary/state-card-content.js).
+ 2. Create the files `state-card-camera.ts` in the folder [/state-summary/](https://github.com/home-assistant/frontend/tree/dev/src/state-summary).
+ 3. Add `import './state-card-camera.ts';` to [state-card-content.ts](https://github.com/home-assistant/frontend/blob/dev/src/state-summary/state-card-content.ts).
diff --git a/docs/frontend/external-authentication.md b/docs/frontend/external-authentication.md
index 94506e06..47ca3632 100644
--- a/docs/frontend/external-authentication.md
+++ b/docs/frontend/external-authentication.md
@@ -1,5 +1,5 @@
---
-title: "External Authentication"
+title: "External authentication"
---
By default, the frontend will take care of its own authentication tokens. If none are found, it will redirect the user to the login page and it will take care of updating the token.
@@ -8,7 +8,7 @@ If you want to embed the Home Assistant frontend in an external app, you will wa
To activate this API, load the frontend with `?external_auth=1` appended to the URL. If this is passed in, Home Assistant will expect either `window.externalApp` (for Android) or `window.webkit.messageHandlers` (for iOS) to be defined containing the methods described below.
-## Get Access Token
+## Get access token
_This API has been introduced in Home Assistant 0.78._
@@ -43,7 +43,7 @@ window.externalAuthSetToken(false);
The frontend will call this method when the page first loads and whenever it needs a valid token but the previous received token has expired.
-## Revoke Token
+## Revoke token
_This API has been introduced in Home Assistant 0.78._
diff --git a/docs/frontend/external-bus.md b/docs/frontend/external-bus.md
index 2bb0ba67..4316fba1 100644
--- a/docs/frontend/external-bus.md
+++ b/docs/frontend/external-bus.md
@@ -1,5 +1,5 @@
---
-title: "External Bus"
+title: "External bus"
---
The frontend is able to set up a message bus with an external app that is embedding the Home Assistant frontend. This system is a generalization of the [external authentication](frontend/external-authentication.md), making it easier to add more commands in the future without extensive plumbing on either the app or frontend side.
@@ -32,7 +32,7 @@ window.externalBus(message: string)
The message describes an action or a piece of information that the sender wants the receiver to do or know about. If it's an action, the sender will expect a response with the result of that action. A response to a command can either be successful or failed.
-### Action and Info Message format
+### Action and info message format
The format of a message that contains or provides information is the same. It contains an identifier, a type and an optional payload (depending on the type).
@@ -57,7 +57,7 @@ An example message:
}
```
-### Result Message Format
+### Result message format
If the message was an action, the sender will expect a response with the result. The response is either success or failure.
@@ -86,7 +86,7 @@ interface ErrorResult {
## Supported messages
-### Get External Config
+### Get external config
Available in: Home Assistant 0.92
Type: `config/get`
@@ -107,7 +107,7 @@ Expected response payload:
- `hasSettingsScreen` set to true if the external app will show a configuration screen when it receives the command `config_screen/show`. If so, a new option will be added to the sidebar to trigger the configuration screen.
- `canWriteTag` set to true if the external app is able to write tags and so can support the `tag/write` command.
-### Show Config Screen `config_screen/show`
+### Show config screen `config_screen/show`
Available in: Home Assistant 0.92
Type: `config_screen/show`
@@ -116,7 +116,7 @@ Expect answer: no
Show the configuration screen of the external app.
-### Connection Status update `connection-status`
+### Connection status update `connection-status`
Available in: Home Assistant 0.92
Type: `connection-status`
@@ -133,7 +133,7 @@ Payload structure:
}
```
-### Trigger Haptic `haptic`
+### Trigger haptic `haptic`
Available in: Home Assistant 0.92
Type: `haptic`
@@ -158,7 +158,7 @@ Payload structure:
}
```
-### Write Tag `tag/write`
+### Write tag `tag/write`
Available in: Home Assistant 0.115
Type: `tag/write`
diff --git a/docs/integration_fetching_data.md b/docs/integration_fetching_data.md
index 92946e6c..fa7b205c 100644
--- a/docs/integration_fetching_data.md
+++ b/docs/integration_fetching_data.md
@@ -1,10 +1,10 @@
---
-title: "Fetching Data"
+title: "Fetching data"
---
Your integration will need to fetch data from an API to be able to provide this to Home Assistant. This API can be available over the web (local or cloud), sockets, serial ports exposed via USB sticks, etc.
-## Push vs Poll
+## Push vs poll
APIs come in many different shapes and forms but at its core they fall in two categories: push and poll.
@@ -27,6 +27,8 @@ This API will have a single method to fetch data for all the entities that you h
Home Assistant provides a DataUpdateCoordinator class to help you manage this as efficiently as possible.
+When using the DataUpdateCoordinator, the data being polled is often expected to stay mostly the same. For example, if you are polling a light that is only turned on once a week, that data may be the same nearly all the time. The default behavior is always calling back listeners when the data is updated, even if it does not change. If the data returned from the API can be compared for changes with the Python `__eq__` method, set `always_update=False` when creating the DataUpdateCoordinator to avoid unnecessary callbacks and writes to the state machine.
+
```python
"""Example integration using DataUpdateCoordinator."""
@@ -82,6 +84,10 @@ class MyCoordinator(DataUpdateCoordinator):
name="My sensor",
# Polling interval. Will only be polled if there are subscribers.
update_interval=timedelta(seconds=30),
+ # Set always_update to `False` if the data returned from the
+ # api can be compared via `__eq__` to avoid duplicate updates
+ # being dispatched to listeners
+ always_update=True
)
self.my_api = my_api
@@ -164,15 +170,15 @@ If you have an API endpoint that pushes data, you can still use the data update
When new data arrives, use `coordinator.async_set_updated_data(data)` to pass the data to the entities. If this method is used on a coordinator that polls, it will reset the time until the next time it will poll for data.
-## Request Parallelism
+## Request parallelism
:::info
This is an advanced topic.
:::
-Home Assistant has built-in logic to make sure that integrations do not hammer APIs and consume all available resources in Home Assistant. This logic is built around limiting the number of parallel requests. This logic is automatically used during service calls and entity updates.
+Home Assistant has built-in logic to make sure that integrations do not hammer APIs and consume all available resources in Home Assistant. This logic is built around limiting the number of parallel requests. This logic is automatically used during service action calls and entity updates.
-Home Assistant controls the number of parallel updates (calls to `update()`) by maintaining a [semaphore](https://docs.python.org/3/library/asyncio-sync.html#asyncio.Semaphore) per integration. For example, if the semaphore allows 1 parallel connection, updates and service calls will wait if one is in progress. If the value is 0, the integration is itself responsible for limiting the number of parallel requests if necessary.
+Home Assistant controls the number of parallel updates (calls to `update()`) by maintaining a [semaphore](https://docs.python.org/3/library/asyncio-sync.html#asyncio.Semaphore) per integration. For example, if the semaphore allows 1 parallel connection, updates and service action calls will wait if one is in progress. If the value is 0, the integration is itself responsible for limiting the number of parallel requests if necessary.
The default value for parallel requests for a platform is decided based on the first entity that is added to Home Assistant. It's 0 if the entity defines the `async_update` method, else it's 1. (this is a legacy decision)
diff --git a/docs/integration_quality_scale_index.md b/docs/integration_quality_scale_index.md
index 1c89c96a..3830a572 100644
--- a/docs/integration_quality_scale_index.md
+++ b/docs/integration_quality_scale_index.md
@@ -1,5 +1,5 @@
---
-title: "Integration Quality Scale"
+title: "Integration quality scale"
---
The Integration Quality Scale scores each integration based on the code quality and user experience. Each level of the quality scale consists of a list of requirements. If an integration matches all requirements, it's considered to have reached that level.
@@ -22,11 +22,11 @@ This integration is able to cope when things go wrong. It will not print any exc
- Satisfying all No score level requirements.
- Connection/configuration is handled via a component.
- Set an appropriate `SCAN_INTERVAL` (if a polling integration)
-- Raise [`PlatformNotReady`](integration_setup_failures.md/#integrations-using-async_setup_platform) if unable to connect during platform setup (if appropriate)
+- Raise [`PlatformNotReady`](integration_setup_failures.md#integrations-using-async_setup_platform) if unable to connect during platform setup (if appropriate)
- Handles expiration of auth credentials. Refresh if possible or print correct error and fail setup. If based on a config entry, should trigger a new config entry flow to re-authorize. ([docs](config_entries_config_flow_handler.md#reauthentication))
- Handles internet unavailable. Log a warning once when unavailable, log once when reconnected.
- Handles device/service unavailable. Log a warning once when unavailable, log once when reconnected.
-- Operations like service calls and entity methods (e.g. *Set HVAC Mode*) have proper exception handling. Raise `ServiceValidationError` on invalid user input and raise `HomeAssistantError` for other failures such as a problem communicating with a device. [Read more](/docs/core/platform/raising_exceptions) about raising exceptions.
+- Operations like service action calls and entity methods (e.g. *Set HVAC Mode*) have proper exception handling. Raise `ServiceValidationError` on invalid user input and raise `HomeAssistantError` for other failures such as a problem communicating with a device. [Read more](/docs/core/platform/raising_exceptions) about raising exceptions.
- Set `available` property to `False` if appropriate ([docs](core/entity.md#generic-properties))
- Entities have unique ID (if available) ([docs](entity_registry_index.md#unique-id-requirements))
@@ -39,7 +39,7 @@ This is a solid integration that is able to survive poor conditions and can be c
- Don't allow configuring already configured device/service (example: no 2 entries for same hub)
- Discoverable (if available)
- Set unique ID in config flow (if available)
- - Raise [`ConfigEntryNotReady`](integration_setup_failures.md/#integrations-using-async_setup_entry) if unable to connect during entry setup (if appropriate)
+ - Raise [`ConfigEntryNotReady`](integration_setup_failures.md#integrations-using-async_setup_entry) if unable to connect during entry setup (if appropriate)
- Entities have device info (if available) ([docs](device_registry_index.md#defining-devices))
- Tests
- Full test coverage for the config flow
@@ -61,7 +61,7 @@ Best of the best. The integration is completely async, meaning it's super fast.
- Support config entry unloading (called when config entry is removed)
- Integration + dependency are async ([docs](asyncio_working_with_async.md))
- Uses aiohttp or httpx and allows passing in websession (if making HTTP requests)
-- [Handles expired credentials](integration_setup_failures.md/#handling-expired-credentials) (if appropriate)
+- [Handles expired credentials](integration_setup_failures.md#handling-expired-credentials) (if appropriate)
## Internal 🏠
diff --git a/docs/integration_setup_failures.md b/docs/integration_setup_failures.md
index 5496cd3c..3a274f6e 100644
--- a/docs/integration_setup_failures.md
+++ b/docs/integration_setup_failures.md
@@ -1,5 +1,5 @@
---
-title: "Handling Setup Failures"
+title: "Handling setup failures"
---
Your integration may not be able to be set up for a variety of reasons. The most common cases are because the device or service is offline or the credentials are no longer valid. Your integration must retry setup so it can recover as soon as reasonably possible when the device or service is back online without the user having to restart Home Assistant.
diff --git a/docs/intent_conversation_api.md b/docs/intent_conversation_api.md
index 7692dad1..c54c6904 100644
--- a/docs/intent_conversation_api.md
+++ b/docs/intent_conversation_api.md
@@ -5,7 +5,7 @@ sidebar_label: "Conversation API"
Intents can be recognized from text and fired using the [conversation integration](https://www.home-assistant.io/integrations/conversation/).
-An API endpoint is available which receives an input sentence and produces an [intent response](#intent-response). A "conversation" is tracked across multiple inputs and responses by passing a [conversation id](#conversation-id) generated by Home Assistant.
+An API endpoint is available which receives an input sentence and produces an [conversation response](#conversation-response). A "conversation" is tracked across multiple inputs and responses by passing a [conversation id](#conversation-id) generated by Home Assistant.
The API is available via the Rest API and Websocket API.
@@ -37,7 +37,7 @@ The following input fields are available:
| `conversation_id` | string | Optional. Unique id to [track conversation](#conversation-id). Generated by Home Assistant. |
-## Conversation Response
+## Conversation response
The JSON response from `/api/conversation/process` contains information about the effect of the fired intent, for example:
@@ -80,20 +80,20 @@ The JSON response from `/api/conversation/process` contains information about th
The following properties are available in the `"response"` object:
-| Name | Type | Description |
-|-----------------|------------|------------------------------------------------------------------------------------------------------------------|
+| Name | Type | Description |
+| --------------- | ---------- | ----------------------------------------------------------------------------------------- |
| `response_type` | string | One of `action_done`, `query_answer`, or `error` (see [response types](#response-types)). |
-| `data` | dictionary | Relevant data for each [response type](#response_types). |
-| `language` | string | The language of the intent and response. |
-| `speech` | dictionary | Optional. Response text to speak to the user (see [speech](#speech)). |
+| `data` | dictionary | Relevant data for each [response type](#response_types). |
+| `language` | string | The language of the intent and response. |
+| `speech` | dictionary | Optional. Response text to speak to the user (see [speech](#speech)). |
-The [conversation id](#conversation-id) is returned alongside the intent response.
+The [conversation id](#conversation-id) is returned alongside the conversation response.
-## Response Types
+## Response types
-### Action Done
+### Action done
The intent produced an action in Home Assistant, such as turning on a light. The `data` property of the response contains a `targets` list, where each target looks like:
@@ -149,7 +149,7 @@ Most intents end up with 0, 1 or 2 targets. 3 targets currenly only happens when
* 3 targets: `area:kitchen`, `domain:cover`, `device_class:blind`
-### Query Answer
+### Query answer
The response is an answer to a question, such as "what is the temperature?". See the [speech](#speech) property for the answer text.
@@ -255,7 +255,7 @@ If the speech is [SSML](https://www.w3.org/TR/speech-synthesis11/), it will inst
## Conversation Id
-Conversations can be tracked by a unique id generated from within Home Assistant if supported by the answering conversation agent. To continue a conversation, retrieve the `conversation_id` from the HTTP API response (alongside the [intent response](#intent-response)) and add it to the next [input sentence](#input-sentence):
+Conversations can be tracked by a unique id generated from within Home Assistant if supported by the answering conversation agent. To continue a conversation, retrieve the `conversation_id` from the HTTP API response (alongside the [conversation response](#conversation-response)) and add it to the next input sentence:
Initial input sentence:
@@ -271,7 +271,7 @@ JSON response contains conversation id:
{
"conversation_id": "",
"response": {
- (intent response)
+ (conversation response)
}
}
```
@@ -286,7 +286,7 @@ POST with the next input sentence:
```
-## Pre-loading Sentences
+## Pre-loading sentences
Sentences for a language can be pre-loaded using the WebSocket API:
diff --git a/docs/intent_handling.md b/docs/intent_handling.md
index f16e8f8d..80211a34 100644
--- a/docs/intent_handling.md
+++ b/docs/intent_handling.md
@@ -23,6 +23,8 @@ class CountInvocationIntent(intent.IntentHandler):
# Type of intent to handle
intent_type = "CountInvocationIntent"
+ description = "Count how often it has been called"
+
# Optional. A validation schema for slots
# slot_schema = {
# 'item': cv.string
diff --git a/docs/internationalization/core.md b/docs/internationalization/core.md
index 67119d3a..bb0bae2b 100644
--- a/docs/internationalization/core.md
+++ b/docs/internationalization/core.md
@@ -1,8 +1,8 @@
---
-title: "Backend Localization"
+title: "Backend localization"
---
-## Translation Strings
+## Translation strings
Platform translation strings are stored as JSON in the [core](https://github.com/home-assistant/core) 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. This file will contain the different strings that will be translatable.
@@ -11,6 +11,7 @@ The `strings.json` contains translations for different things that the integrati
| Category | Description |
| ------------------- | ------------------------------------------------- |
| `title` | Title of the integration. |
+| `common` | Shared strings. |
| `config` | Translations for the config flow. |
| `device` | Translations for devices. |
| `device_automation` | Translations for device automations. |
@@ -20,12 +21,39 @@ The `strings.json` contains translations for different things that the integrati
| `issues` | Translations for repairs issues. |
| `options` | Translations for the options flow. |
| `selectors` | Selectors of the integration. |
-| `services` | Services of the integration. |
+| `services` | Service actions of the integration. |
### Title
This category is just a string: the translation of the integration name. This key is optional and Home Assistant will fallback to the integration name if it is omitted. Only include this if it's not a product brand.
+### Shared strings
+
+Strings which are used more than once should be not be duplicated, instead references should be used to refer to the single definition. The reference can be any valid translation key. Optionally, shared strings can be placed in a `common` section.
+
+```json
+{
+ "common": {
+ "error_stale_api_key": "This message will be displayed if `stale_api_key` is returned as the abort reason."
+ },
+ "config": {
+ "error": {
+ "invalid_api_key": "This message will be displayed if `invalid_api_key` is returned as a flow error.",
+ // Reference to the common section
+ "stale_api_key": "[%key:component::new_integration::common::error_stale_api_key%]"
+ },
+ }
+ "options": {
+ "error": {
+ // Reference to another section in the same file
+ "invalid_api_key": "[%key:component::new_integration::config::error::invalid_api_key%]",
+ // Reference to the common section in the same file
+ "stale_api_key": "[%key:component::new_integration::common::error_stale_api_key%]"
+ },
+ }
+}
+```
+
### Config / Options
The translation strings for the configuration flow handler and the option flow handler are defined under the `config` and `options` keys respectively. An example strings file below describes the different supported keys. Although the example shows translations for a configuration flow, the translations for an option flow is exactly the same.
@@ -95,12 +123,12 @@ The translation for selectors are defined under the `selector` key. It supports
```
-### Services
+### Service Actions
-The translations of service strings are defined under the `services` key.
+The translations of service actions strings are defined under the `services` key.
-It supports translating the `name` and `description` of each service,
-and the `name` and `description` of each service's `fields`.
+It supports translating the `name` and `description` of each action,
+and the `name` and `description` of each action's `fields`.
```json
{
@@ -130,7 +158,7 @@ and the `name` and `description` of each service's `fields`.
```
:::note
-Services may use selectors in their `fields`. The translation of those selectors can be provided using the `translation_key` property on the selector definition in the services.yaml file. See the [Selectors](#selectors) section and the [Service description](/docs/dev_101_services.md#service-descriptions) page for more information.
+Service actions may use selectors in their `fields`. The translation of those selectors can be provided using the `translation_key` property on the selector definition in the services.yaml file. See the [Selectors](#selectors) section and the [Service action description](/docs/dev_101_services.md#service-action-descriptions) page for more information.
:::
### Device automations
@@ -179,7 +207,7 @@ The translation strings for exceptions are defined under the `exception` key in
```
-Example of raising an exception with localization during a service call:
+Example of raising an exception with localization during a service action call:
```python
async def async_select_index(hass: HomeAssistant, index: int) -> None:
diff --git a/docs/internationalization/custom_integration.md b/docs/internationalization/custom_integration.md
index 5cbdd578..2ae78fda 100644
--- a/docs/internationalization/custom_integration.md
+++ b/docs/internationalization/custom_integration.md
@@ -1,8 +1,8 @@
---
-title: "Custom Integration Localization"
+title: "Custom integration localization"
---
-## Translation Strings
+## Translation strings
Unlike localized strings merged in the `home-assistant` repository, custom integrations cannot take advantage of Lokalise for user-submitted translations. However, custom integration authors can still include translations with their integrations. These will be read from the `translations` directory, adjacent to the integration source. They are named `.json` in the `translations` directory, e.g., for the German translation `de.json`.
diff --git a/docs/network_discovery.md b/docs/network_discovery.md
index cdc8dc0a..7c3ae91d 100644
--- a/docs/network_discovery.md
+++ b/docs/network_discovery.md
@@ -1,6 +1,6 @@
---
-title: "Networking and Discovery"
-sidebar_label: "Networking and Discovery"
+title: "Networking and discovery"
+sidebar_label: "Networking and discovery"
---
Some integrations may need to discover devices on the network via [mDNS/Zeroconf](https://en.wikipedia.org/wiki/Zero-configuration_networking), [SSDP](https://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol), or another method once they have been enabled. The primary use case is to find devices that do not have a known fixed IP Address or for integrations that can dynamically add and remove any number of compatible discoverable devices.
diff --git a/docs/operating-system.md b/docs/operating-system.md
index 31b28f13..8b968d5f 100644
--- a/docs/operating-system.md
+++ b/docs/operating-system.md
@@ -10,7 +10,7 @@ Home Assistant Operating System (HAOS) is using the [Buildroot](https://buildroo
### Components
- **Bootloader:**
- - [Barebox](https://barebox.org/) for devices that support EFI
+ - [GRUB](https://www.gnu.org/software/grub/) for devices that support UEFI
- [U-Boot](https://www.denx.de/wiki/U-Boot) for devices that don't support EFI
- **Operating System:**
- [Buildroot](https://buildroot.org/) build system to generate Linux distributions
diff --git a/docs/operating-system/board-metadata.md b/docs/operating-system/board-metadata.md
index 867b3923..f6e34bab 100644
--- a/docs/operating-system/board-metadata.md
+++ b/docs/operating-system/board-metadata.md
@@ -1,5 +1,5 @@
---
-title: "Board Metadata"
+title: "Board metadata"
sidebar_label: Metadata
---
@@ -40,10 +40,10 @@ Enable SPL (secondary program loader) handling. Some U-Boot targets generate a s
`BOOTLOADER`:
+- grub
- uboot
-- barebox
-HAOS uses mainly [U-Boot](https://www.denx.de/wiki/U-Boot). For UEFI systems [barebox](https://barebox.org/) is used.
+HAOS uses mainly [U-Boot](https://www.denx.de/wiki/U-Boot). For UEFI systems [GRUB](https://www.gnu.org/software/grub/) is used.
`DISK_SIZE`:
diff --git a/docs/operating-system/debugging.md b/docs/operating-system/debugging.md
index a97073df..93db4dd6 100644
--- a/docs/operating-system/debugging.md
+++ b/docs/operating-system/debugging.md
@@ -9,37 +9,40 @@ This section is not for end users. End users should use the [SSH add-on] to SSH
[SSH add-on]: https://github.com/home-assistant/addons/tree/master/ssh
-## SSH access to the host
+## Enabling SSH access to the host
:::info
-SSH access through the [SSH add-on] (which will give you SSH access through port 22) will not provide you with all the necessary privileges, and you will be asked for a username and password when typing the 'login' command. You need to follow the steps below, which will setup a separate SSH access through port 22222 with all necessary privileges.
+SSH access through the [SSH add-on] (on port 22 by default) only grants limited privileges, and you will be asked for a username and password when typing the 'login' command. Follow the steps below to enable a separate SSH access on port 22222 that works independently of the add-on and gives you direct access to the Home Assistant OS (the "host") with full privileges.
:::
-### Home Assistant Operating System
+1. Use a USB drive with a partition named `CONFIG` (case sensitive) formatted as FAT, ext4, or NTFS. Create an `authorized_keys` text file (without a file extension) containing your public key(s), one per line, and place it in the root of the USB drive's `CONFIG` partition. The file must use POSIX-standard newline control characters (LF), not Windows ones (CR LF), and needs to be ASCII character encoded (i.e. mustn't contain any special characters in the comments).
-Use a USB drive formatted with FAT, ext4, or NTFS and name it CONFIG (case sensitive). Create an `authorized_keys` file (no extension) containing your public key, and place it in the root of the USB drive. File needs to be ANSI encoded (not UTF-8) and must have Unix line ends (LF), not Windows (CR LF). See [Generating SSH Keys](#generating-ssh-keys) section below if you need help generating keys. Use the CLI (eg. SSH to the [SSH add-on] on port 22) and import the `authorized_keys` file with the `ha os import` command. You can now access your device as root over SSH on port 22222. Alternatively, the file will be imported from the USB when the Home Assistant OS device is rebooted.
+ See [Generating SSH Keys](#generating-ssh-keys) section below if you need help generating keys.
+
+1. Connect the USB drive to your Home Assistant OS device and either explicitly import the drive's contents using the `ha os import` command (e.g. via SSH to the [SSH add-on] on port 22) or reboot the device leaving the drive attached, which automatically triggers the import.
:::tip
-Make sure when you are copying the public key to the root of the USB drive that you rename the file correctly to `authorized_keys` with no `.pub` file extension.
+Make sure when you are copying the public key(s) to the root of the USB drive that you correctly name the file `authorized_keys` without a `.pub` file extension.
:::
-You should then be able to SSH into your Home Assistant device. On Mac/Linux, use:
+You should now be able to connect to your device as root over SSH on port 22222. On Mac/Linux, use:
```shell
ssh root@homeassistant.local -p 22222
```
-If you have an older installation or have changed your hostname, you may need to use a different hostname in the command above. You can check the correct hostname to use in the System page of the Supervisor interface in Home Assistant.
+If you have an older installation or have changed your hostname, you may need to adjust the command above accordingly. You can alternatively use the device's IP address instead of the hostname.
-You will be logged in as root in the ```/root``` folder. [Home Assistant OS] is a hypervisor for Docker. See the [Supervisor Architecture] documentation for information regarding the Supervisor. The Supervisor offers an API to manage the host and running the Docker containers. Home Assistant itself and all installed addons run in separate Docker containers.
+You will be logged in as root with the `/root` folder set as the working directory. [Home Assistant OS] is a hypervisor for Docker. See the [Supervisor Architecture] documentation for information regarding the Supervisor. The Supervisor offers an API to manage the host and running the Docker containers. Home Assistant itself and all installed addons run in separate Docker containers.
-[CLI tasks]: https://www.home-assistant.io/common-tasks/os#home-assistant-via-the-command-line
[Home Assistant OS]: https://github.com/home-assistant/operating-system
[Supervisor Architecture]: /architecture_index.md
-### Turning off SSH access to the host
+## Disabling SSH access to the host
-Use a USB drive formatted with FAT, ext4, or NTFS and name it CONFIG (case sensitive). Remove any existing `authorized_keys` file from the drive and leave the drive empty. When the Home Assistant OS device is rebooted with this drive inserted, any existing keys will be removed and the SSH service will be stopped.
+1. Use a USB drive with a partition named `CONFIG` (case sensitive) formatted as FAT, ext4, or NTFS. Remove any existing `authorized_keys` file from the root of that partition.
+
+1. When the Home Assistant OS device is rebooted with this drive inserted, any existing SSH public keys will be removed and SSH access on port 22222 will be disabled.
## Checking the logs
@@ -64,10 +67,8 @@ docker exec -it homeassistant /bin/bash
### Generating SSH Keys
-Windows instructions for 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.
+Windows instructions on how to generate and use private/public keys with Putty are found [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://docs.github.com/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent#platform-mac).
+Alternative instructions for Mac, Windows and Linux can be found [here](https://docs.github.com/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). Follow the steps under *Generating a new SSH key* (the other sections are not applicable to Home Assistant and can be ignored).
-Follow steps 1-4 under 'Generating a new SSH key' (The other sections are not applicable to Home Assistant 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 the authorized_keys file" and save it to the root of your USB drive as `authorized_keys`.
+Make sure to copy the ***public*** key of the SSH key pair you just created. By default, the public key file is named `id_ed25519.pub` (in case of the Ed25519 elliptic curve algorithm) or `id_rsa.pub` (in case of the older RSA algorithm), i.e. it should have a `.pub` filename suffix. It is saved to the same folder as the private key (which is named `id_ed25519` or `id_rsa` by default).
diff --git a/docs/operating-system/deployment.md b/docs/operating-system/deployment.md
index efa315c7..42ec507c 100644
--- a/docs/operating-system/deployment.md
+++ b/docs/operating-system/deployment.md
@@ -14,7 +14,7 @@ Home Assistant Operating System releases are built from the release branch. GitH
The format of version is *MAJOR.BUILD*. Every time a new release is released the BUILD number gets incremented (stored in `buildroot-external/meta`). The MAJOR number is inherited from the development branch, and gets bumped right after the release branch has been created.
-The build system by default automatically adds a *dev{DATE}* suffix to mark development builds.
+The build system by default automatically adds a *dev\{DATE\}* suffix to mark development builds.
Before a new major release, release candidates can be built on the development branch. A release candidate suffix is used to mark them, e.g. *MAJOR.0.rc1*.
diff --git a/docs/operating-system/getting-started.md b/docs/operating-system/getting-started.md
index 900209ed..b49be2ec 100644
--- a/docs/operating-system/getting-started.md
+++ b/docs/operating-system/getting-started.md
@@ -1,11 +1,11 @@
---
-title: "Getting Started with Home Assistant Operating System Development"
-sidebar_label: Getting Started
+title: "Getting started with Home Assistant Operating System development"
+sidebar_label: Getting started
---
-## Prepare Development Environment
+## Prepare development environment
-### Check-out Source Code
+### Check-out source code
The main repository located at [github.com/home-assistant/operating-system/](https://github.com/home-assistant/operating-system/) contains Buildroot customizations via the [br2-external mechanism](https://buildroot.org/downloads/manual/manual.html#outside-br-custom) as well as helper scripts and GitHub Action CI scripts. The main repository uses the Git Submodule mechanism to point to Buildroot itself. While most customizations can be done by the br2-mechanism, some modifications are made to Buildroot itself. For that reason we also maintain a fork of Buildroot under [github.com/home-assistant/buildroot/](https://github.com/home-assistant/buildroot/). The aim is to keep the amount of patches on-top of upstream Buildroot minimal.
@@ -41,7 +41,7 @@ While Buildroot can run on most Linux distributions natively, its strongly recom
The build container needs to get started with privileges since at some point during the build process a new loopback device-backed filesystem image will be mounted inside a Docker container. Hence rootless containers won't work to build HAOS.
:::
-## Build Images using Build Container
+## Build images using build container
The script `scripts/enter.sh` builds the build container image and starts a container using that image. Arguments passed to the script get executed inside the container.
@@ -76,7 +76,7 @@ rm -rf output/build/linux-custom/
You can check `output/build/packages-file-list.txt` to learn which file in the final image belongs to what package. This makes it easier to find the package you would like to change.
:::
-### Build for Multiple Targets
+### Build for multiple targets
To build for multiple targets in a single source directory, separate output directories must be used. The output directory can be specified with the `O=` argument. A recommended pattern is to just use an output directory named after the targets configuration file:
@@ -85,7 +85,7 @@ To build for multiple targets in a single source directory, separate output dire
sudo scripts/enter.sh make O=output_rpi4_64 rpi4_64
```
-### Use the Build Container Interactively
+### Use the build container interactively
If no argument to `scripts/enter.sh` is passed, a shell will be presented.
@@ -112,7 +112,7 @@ dot -Tpdf \
builder@c6dfb4cd4036:/build$
```
-## Use Qemu to Test Images
+## Use Qemu to test images
The target OVA (Open Virtual Appliance) contains images for various virtual machines. One of the image format is QCOW2, the native image format for QEMU. It can be used to test a new HAOS build using QEMU.
diff --git a/docs/operating-system/partition.md b/docs/operating-system/partition.md
index 59e12eda..5e5dcaf2 100644
--- a/docs/operating-system/partition.md
+++ b/docs/operating-system/partition.md
@@ -5,7 +5,7 @@ sidebar_label: Partitions
The Home Assistant Operating System (HAOS) partition layout is a bit different than what is typically used on a Linux system.
-## Partition Table
+## Partition table
HAOS prefers GPT (GUID Partition Table) whenever possible. Boot ROMs of some SoCs don't support GPT, in that case a hybrid GPT/MBR is used if possible and legacy MBR otherwise (see also [Metadata](board-metadata.md) documentation).
@@ -40,7 +40,7 @@ HAOS prefers GPT (GUID Partition Table) whenever possible. Boot ROMs of some SoC
### System partitions
-The boot partition is typically a FAT partition and contains system specific content to enable booting. On x86-64 systems this is the EFI system partition containing Barebox.
+The boot partition is typically a FAT partition and contains system-specific content to enable booting. On UEFI systems this is the EFI system partition containing GRUB binaries, configuration and its environment file.
Next two versions of the Linux kernel and the main operating systems are stored (Kernel A/B and System A/B, a total of 4 partitions). This allows the system to fall back to the previous release in case booting on the new release fails (A/B update method). The system partitions are only written to during an update and are read-only under regular operation.
diff --git a/docs/operating-system/update-system.md b/docs/operating-system/update-system.md
index 8843ad74..c85f8464 100644
--- a/docs/operating-system/update-system.md
+++ b/docs/operating-system/update-system.md
@@ -1,6 +1,6 @@
---
-title: "Update System"
-sidebar_label: Update System
+title: "Update system"
+sidebar_label: Update system
---
Home Assistant Operating System uses [RAUC](https://rauc.io/) as the update system. RAUC is an image based update system designed for embedded systems. It has support for multiple boot slots thus supporting A/B style update mechanism. The update system integrates with popular bootloaders such as U-Boot but also allows integration with custom boot flows via scripts. It uses X.509 cryptography to sign and verify update bundles.
diff --git a/docs/review-process.md b/docs/review-process.md
index 2098c74d..0bd2f686 100644
--- a/docs/review-process.md
+++ b/docs/review-process.md
@@ -33,7 +33,7 @@ Home Assistant.
## Before creating your PR
-**Comply with Architectural Decisions.**
+**Comply with architectural decisions.**
All architectural decisions around the Home Assistant project are recorded in
the [ADR folder](https://github.com/home-assistant/architecture/tree/master/adr).
@@ -82,9 +82,8 @@ the end-user getting your improvement faster.
branch, and it makes it easier to delete the branch after the PR
has been merged.
-6. **Motivate your PR by adding a clear title & extensive description.**
- When you open up a PR, you will be provided a PR template. Use the template,
- fill out as many fields as possible, take your time to write a good,
+6. **Follow the PR template and add a clear title & an extensive description.**
+ When you open up a PR, you will be provided with a PR template. Use the template and fill out as many fields as possible. Take your time to write a good,
clear, and concise title, and add an extensive description of your change.
Be sure to add a motivation (or use case) to your PR, so the reviewer can
understand why you are making this change (or why you make certain decisions).
diff --git a/docs/supervisor/development.md b/docs/supervisor/development.md
index d8a030df..c5771f0a 100644
--- a/docs/supervisor/development.md
+++ b/docs/supervisor/development.md
@@ -1,5 +1,5 @@
---
-title: "Supervisor Development"
+title: "Supervisor development"
sidebar_label: "Development"
---
@@ -46,7 +46,7 @@ docker run --rm \
--privileged \
-v /run/docker.sock:/run/docker.sock \
-v "$(pwd):/data" \
- homeassistant/amd64-builder:dev \
+ ghcr.io/home-assistant/amd64-builder:dev \
--generic latest \
--target /data \
--aarch64 \
@@ -111,14 +111,14 @@ script/develop
While `script/develop` is running, the Supervisor panel will be rebuilt whenever you make changes to the source files.
-## Supervisor API Access
+## Supervisor API access
To develop for the `hassio` integration and the Supervisor panel, we're going to need API access to the supervisor. This API is protected by a token that we can extract using a special add-on. This can be done on a running system or with the [devcontainer](#local-testing).
[](https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2Fhome-assistant%2Faddons-development)
[](https://my.home-assistant.io/redirect/supervisor_addon/?addon=ae6e943c_remote_api)
-1. Add our developer Add-on repository:
+1. Add our developer Add-on repository: [https://github.com/home-assistant/addons-development](https://github.com/home-assistant/addons-development)
2. Install the Add-on "Remote API proxy"
3. Click Start
4. The token will be printed in the logs
diff --git a/docs/translations.md b/docs/translations.md
index bbd63451..3e74995d 100644
--- a/docs/translations.md
+++ b/docs/translations.md
@@ -1,5 +1,5 @@
---
-title: "Contributing Translation"
+title: "Contributing translation"
---
Translations for Home Assistant are managed through [Lokalise](https://lokalise.com/), an online translation management tool. Our translations are split between four projects: a backend project for platform-specific translations, a frontend project for UI translations, and two for the official companion apps. Click the links below to join the 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.
@@ -51,13 +51,16 @@ Region specific translations (`en-US`, `fr-CA`) will only be included if transla
Note: Sometimes you have to change the tag in Lokalise (Language -> Language settings -> custom ISO code).
## Language specific guidelines
+
Most languages have multiple possible translations of a sentence. Please take a look at the guidelines for your language here, where you can also find some typical mistakes to prevent.
The sections are written in their corresponding languages, as this makes explaining the grammar easier and only native speakers should submit translations (see [Rules](#rules)).
### German
+
- Du/Sie: Duze in den Übersetzungen, und verwende nicht das formale "Sie".
#### Typische Fehler
+
- Achte auf den richtigen Imperativ. Der Imperativ ist die Befehlsform, z. B. "Gib mir das Wasser". Falsch wäre hier: "Gebe mir das Wasser" (siehe [Bildung des Imperativs](https://www.duden.de/sprachwissen/sprachratgeber/Bildung-des-Imperativs)).
### French
diff --git a/docs/voice/contributing-your-voice.md b/docs/voice/contributing-your-voice.md
index ee2754bf..dce4e676 100644
--- a/docs/voice/contributing-your-voice.md
+++ b/docs/voice/contributing-your-voice.md
@@ -1,25 +1,24 @@
---
-title: "Contributing Your Voice"
+title: "Contributing your voice"
---
-You can help us and the rest of the open voice community develop **Speech-to-Text** and **Text-to-Speech** models for your language.
+You can help us and the rest of the open voice community develop **speech-to-text** and **text-to-speech** models for your language.
-
-## Speech to Text
+## Speech-to-text
When you speak to a computer, it **transcribes** the audio from your voice into text. There are many ways to do this, but they all rely on recordings of people speaking.
-For speech to text, it is important to have:
+For speech-to-text, it is important to have:
* Many different speakers and accents
* A variety of recording devices and quality levels
* Typically 16Khz audio with 16-bit samples
* Multiple recording environments, including different rooms and noise levels
-We recommend that users contribute to [Mozilla's Common Voice](https://commonvoice.mozilla.org) project for speech to text. This free and open dataset crowd sources spoken sentences from people around the world. Contributors may also help by validating existing recordings.
+We recommend that users contribute to [Mozilla's Common Voice](https://commonvoice.mozilla.org) project for speech-to-text. This free and open dataset crowd sources spoken sentences from people around the world. Contributors may also help by validating existing recordings.
-## Text to Speech
+## Text-to-speech
When a computer speaks to you, it **synthesizes** audio from text. This has different requirements than a speech to text dataset:
diff --git a/docs/voice/intent-recognition/style-guide.md b/docs/voice/intent-recognition/style-guide.md
index 925a6eae..6729ec08 100644
--- a/docs/voice/intent-recognition/style-guide.md
+++ b/docs/voice/intent-recognition/style-guide.md
@@ -38,5 +38,5 @@ Responses should be in the present tense. For example, "The light is on" instead
## Use the correct voice
-Responses should be in the active voice. For example, "The light is on" instead of "The light is being turned on".
+Responses should be in the active voice. For example, "The light is on" instead of "The light is being turned on". Exception here is for the `cover` domain, as the actions take considerable time to complete.
diff --git a/docs/voice/intent-recognition/supported-languages.md b/docs/voice/intent-recognition/supported-languages.md
index 9ec655e8..c4db099d 100644
--- a/docs/voice/intent-recognition/supported-languages.md
+++ b/docs/voice/intent-recognition/supported-languages.md
@@ -1,11 +1,11 @@
---
-title: "Supported Languages"
+title: "Supported languages"
---
import languages from '!!yaml-loader!../../../intents/languages.yaml';
import intents from '!!yaml-loader!../../../intents/intents.yaml';
-If you don't see your language below, [help us translate!](./contributing)
+If you don't see your language below, [help us translate!](contributing)
For a full progress report per language, [click here.](https://home-assistant.github.io/intents/)
diff --git a/docs/voice/intent-recognition/template-sentence-syntax.md b/docs/voice/intent-recognition/template-sentence-syntax.md
index ab132e39..f983b999 100644
--- a/docs/voice/intent-recognition/template-sentence-syntax.md
+++ b/docs/voice/intent-recognition/template-sentence-syntax.md
@@ -1,5 +1,5 @@
---
-title: "Template Sentence Syntax"
+title: "Template sentence syntax"
---
Template sentences are defined in YAML files using the format of [Hassil, our template matcher](https://github.com/home-assistant/hassil). Our template sentences are stored [on GitHub](https://github.com/home-assistant/intents/tree/main/sentences) and are organized by having for each language a directory of files in `sentences//`:
@@ -59,7 +59,7 @@ Response templates uses [Jinja2 syntax](https://jinja.palletsprojects.com/en/lat
See all [translated responses](https://github.com/home-assistant/intents/tree/main/responses) for more examples.
-## Sentence Templates Syntax
+## Sentence templates syntax
* Alternative word, phrases, or parts of a word
* `(red | green | blue)`
@@ -78,6 +78,10 @@ See all [translated responses](https://github.com/home-assistant/intents/tree/ma
* ``
* The body of the rule is substituted for ``
* In YAML, `rule_name` should be under `expansion_rules`. If the `rule_name` wraps a slot name, it should match the slot name. Otherwise it should be in the native language.
+* [Permutations](https://en.wikipedia.org/wiki/Permutation) of 2 or more items
+ * `(patience;you must have)`
+ * Permutation items are always padded with spaces to prevent new word formations
+ * Limit the number of items to 2-4, as the number of permutations for `n` items increases very quickly with `n`, this number being `n! == 1 * 2 * ... * n`
## The common file
@@ -167,7 +171,7 @@ intents:
wildcard: true
```
-### Expansion Rules
+### Expansion rules
A lot of template sentences can be written in a similar way. To avoid having to repeat the same matching structure multiple times, we can define expansion rules. For example, a user might add "the" in front of the area name, or they might not. We can define an expansion rule to match both cases.
@@ -182,7 +186,7 @@ expansion_rules:
turn: "(turn | switch)"
```
-#### Local Expansion Rules
+#### Local expansion rules
Expansion rules can also be defined locally next to a list of sentences, and will only be available within those templates. This allows you to write similar templates for different situations. For example:
@@ -221,7 +225,7 @@ lists:
The same template `is the door ` is used for both binary sensors and regular locks, but the local `state` expansion rules refer to different lists.
-### Skip Words
+### Skip words
Skip words are words that the intent recognizer will skip during recognition. This is useful for words that are not part of the intent, but are commonly used in sentences. For example, a user might use the word "please" in a sentence, but it is not part of the intent.
@@ -231,7 +235,7 @@ skip_words:
- "can you"
```
-### Requires/Excludes Context
+### Requires/excludes context
Hassil returns the first intent match it can find, so additional **context** may be required if the same sentence could produce multiple matches.
diff --git a/docs/voice/intent-recognition/test-syntax.md b/docs/voice/intent-recognition/test-syntax.md
index 717fda06..cdb1aedc 100644
--- a/docs/voice/intent-recognition/test-syntax.md
+++ b/docs/voice/intent-recognition/test-syntax.md
@@ -1,6 +1,6 @@
---
-title: "Intent Matching Test Syntax"
-sidebar_label: "Test Syntax"
+title: "Intent matching test syntax"
+sidebar_label: "Test syntax"
---
To ensure that the template sentences work as expected, we have an extensive test suite. This test suite is based on YAML files that contain a list of input sentences and the expected matched intent and slots.
diff --git a/docs/voice/language-leaders.md b/docs/voice/language-leaders.md
index 9363a201..dfbc8f95 100644
--- a/docs/voice/language-leaders.md
+++ b/docs/voice/language-leaders.md
@@ -1,5 +1,5 @@
---
-title: "Language Leaders"
+title: "Language leaders"
---
Home Assistant is a global project. We want to make sure that everyone can use Home Assistant in their native language. For that reason, we have language leaders for each language to lead the maintenance.
diff --git a/docs/voice/pipelines/index.md b/docs/voice/pipelines/index.md
index fcab7a3c..df196e85 100644
--- a/docs/voice/pipelines/index.md
+++ b/docs/voice/pipelines/index.md
@@ -1,5 +1,5 @@
---
-title: "Assist Pipelines"
+title: "Assist pipelines"
---
The [Assist pipeline](https://www.home-assistant.io/integrations/assist_pipeline) integration runs the common steps of a voice assistant:
@@ -31,6 +31,7 @@ The following input fields are available:
| `input` | dict | Depends on `start_stage`: `wake_word` only:`timeout` - seconds before wake word detection times out (int, default: 3) `noise_suppression_level` - amount of noise suppression (int, 0 = disabled, 4 = max) `auto_gain_dbfs` - automatic gain (int, 0 = disabled, 31 = max) `volume_multiplier` - fixed volume amplification (float, 1.0 = no change, 2.0 = twice as loud) `wake_word` and `stt`:`sample_rate` - sample rate of incoming audio (int, hertz) `intent` and `tts`:`text` - input text (string) 
None:
+ """Entity has been added to hass."""
+ self.async_on_remove(
+ async_track_state_change_event(
+ self.hass,
+ ["light.other"],
+ self.async_update_event_state_callback,
+ )
+ )
+
+ @callback
+ def async_update_event_state_callback(self, event: Event[EventStateChangedData]) -> None:
+ """Call when entity state changes."""
+ new_state = event.data["new_state"]
+ if new_state is None or new_state.state in (STATE_UNAVAILABLE, STATE_UNKNOWN):
+ return
+ self.async_write_ha_state()
+
+```
+
+### Specific API calls
+
+You may find you need to call one of the async API calls from a thread other than the event loop thread. In most cases, `hass.add_job` can safely call an async API from another thread. Some helpers have specific sync APIs to use when calling from another thread. Below is a list of the most commonly called async APIs and the method to call them from another thread.
+
+#### hass.async_create_task
+
+When creating a task from a thread other than the event loop thread, instead use `hass.create_task`
+
+#### hass.bus.async_fire
+
+When firing an event from a thread other than the event loop thread, instead use `hass.bus.fire`
+
+#### hass.services.async_register
+
+When registering a service action from a thread other than the event loop thread, instead use `hass.services.register`
+
+#### hass.services.async_remove
+
+When removing a service action from a thread other than the event loop thread, instead use `hass.services.remove`
+
+#### async_write_ha_state
+
+When writing the state of an entity from a thread other than the event loop thread, instead use `self.schedule_update_ha_state`
+
+#### hass.config_entries.async_update_entry
+
+Updating config entry must be done in the event loop thread. There is no sync API to update config entries. If it is not a mistake that the calling function is running in another thread, use `hass.add_job` to schedule a function in the event loop that calls `hass.config_entries.async_update_entry`.
+
+#### async_dispatcher_send
+
+When calling the dispatcher from a thread other than the event loop thread, instead use `dispatcher_send`.
+
+#### async_render_to_info
+
+Templates must be rendered in the event loop thread. There is no sync API to render templates. Use `hass.add_job` to schedule a function in the event loop that calls `async_render_to_info`.
+
+#### area_registry.async_create
+
+The area registry must be modified in the event loop thread. There is no sync API for the area registry. Use `hass.add_job` to schedule a function in the event loop that calls `area_registry.async_create`.
+
+#### area_registry.async_delete
+
+The area registry must be modified in the event loop thread. There is no sync API for the area registry. Use `hass.add_job` to schedule a function in the event loop that calls `area_registry.async_delete`.
+
+#### area_registry.async_update
+
+The area registry must be modified in the event loop thread. There is no sync API for the area registry. Use `hass.add_job` to schedule a function in the event loop that calls `area_registry.async_update`.
+
+#### category_registry.async_create
+
+The category registry must be modified in the event loop thread. There is no sync API for the category registry. Use `hass.add_job` to schedule a function in the event loop that calls `category_registry.async_create`.
+
+#### category_registry.async_delete
+
+The category registry must be modified in the event loop thread. There is no sync API for the category registry. Use `hass.add_job` to schedule a function in the event loop that calls `category_registry.async_delete`.
+
+#### category_registry.async_update
+
+The category registry must be modified in the event loop thread. There is no sync API for the category registry. Use `hass.add_job` to schedule a function in the event loop that calls `category_registry.async_update`.
+
+#### device_registry.async_update_device
+
+The device registry must be modified in the event loop thread. There is no sync API for the device registry. Use `hass.add_job` to schedule a function in the event loop that calls `device_registry.async_update_device`.
+
+#### device_registry.async_remove_device
+
+The device registry must be modified in the event loop thread. There is no sync API for the device registry. Use `hass.add_job` to schedule a function in the event loop that calls `device_registry.async_remove_device`.
+
+#### entity_registry.async_get_or_create
+
+The entity registry must be modified in the event loop thread. There is no sync API for the entity registry. Use `hass.add_job` to schedule a function in the event loop that calls `entity_registry.async_get_or_create`.
+
+#### entity_registry.async_remove
+
+The entity registry must be modified in the event loop thread. There is no sync API for the entity registry. Use `hass.add_job` to schedule a function in the event loop that calls `entity_registry.async_remove`.
+
+#### entity_registry.async_update_entity
+
+The entity registry must be modified in the event loop thread. There is no sync API for the entity registry. Use `hass.add_job` to schedule a function in the event loop that calls `entity_registry.async_update_entity`.
+
+#### floor_registry.async_create
+
+The floor registry must be modified in the event loop thread. There is no sync API for the floor registry. Use `hass.add_job` to schedule a function in the event loop that calls `floor_registry.async_create`.
+
+#### floor_registry.async_delete
+
+The floor registry must be modified in the event loop thread. There is no sync API for the floor registry. Use `hass.add_job` to schedule a function in the event loop that calls `floor_registry.async_delete`.
+
+#### floor_registry.async_update
+
+The floor registry must be modified in the event loop thread. There is no sync API for the floor registry. Use `hass.add_job` to schedule a function in the event loop that calls `floor_registry.async_update`.
+
+#### issue_registry.async_get_or_create
+
+The issue registry must be modified in the event loop thread. Call `issue_registry.create_issue` instead.
+
+#### issue_registry.async_delete
+
+The issue registry must be modified in the event loop thread. Call `issue_registry.delete_issue` instead.
+
+#### issue_registry.async_ignore
+
+The issue registry must be modified in the event loop thread. There is no sync API to ignore an issue in the issue registry. Use `hass.add_job` to schedule a function in the event loop that calls `issue_registry.async_ignore_issue`.
+
+#### label_registry.async_create
+
+The label registry must be modified in the event loop thread. There is no sync API for the label registry. Use `hass.add_job` to schedule a function in the event loop that calls `label_registry.async_create`.
+
+#### label_registry.async_delete
+
+The label registry must be modified in the event loop thread. There is no sync API for the label registry. Use `hass.add_job` to schedule a function in the event loop that calls `label_registry.async_delete`.
+
+#### label_registry.async_update
+
+The label registry must be modified in the event loop thread. There is no sync API for the label registry. Use `hass.add_job` to schedule a function in the event loop that calls `label_registry.async_update`.
diff --git a/docs/auth_api.md b/docs/auth_api.md
index c3b3ac29..18caca57 100644
--- a/docs/auth_api.md
+++ b/docs/auth_api.md
@@ -54,7 +54,7 @@ http://your-instance.com/auth/authorize?
The user will navigate to this link and be presented with instructions to log in and authorize your application. Once authorized, the user will be redirected back to the passed in redirect uri with the authorization code and state as part of the query parameters. Example:
```txt
-https://hass-auth-demo.glitch.me/auth_callback
+https://hass-auth-demo.glitch.me/auth_callback?
code=12345&
state=http%3A%2F%2Fhassio.local%3A8123
```
diff --git a/docs/auth_auth_module.md b/docs/auth_auth_module.md
index 4a075971..c86f0a8a 100644
--- a/docs/auth_auth_module.md
+++ b/docs/auth_auth_module.md
@@ -1,5 +1,5 @@
---
-title: "Multi-factor Authentication Modules"
+title: "Multi-factor authentication modules"
---
Multi-factor Authentication Modules are used in conjunction with [Authentication Provider](auth_auth_provider.md) to provide a fully configurable authentication framework. Each MFA module may provide one multi-factor authentication function. User can enable multiple mfa modules, but can only select one module in login process.
@@ -26,7 +26,7 @@ Multi-factor Auth modules shall extend the following methods of `MultiFactorAuth
| `async def async_validate(self, user_id, user_input)` | Yes | Given a user_id and user input, return validation result.
| `async def async_initialize_login_mfa_step(self, user_id)` | No | Will be called once before display the mfa step of login flow. This is not initialization for the MFA module but the mfa step in login flow.
-## Setup Flow
+## Setup flow
Before user can use a multi-factor auth module, it has to be enabled or set up. All available modules will be listed in user profile page, user can enable the module he/she wants to use. A setup data entry flow will guide user finish the necessary steps.
diff --git a/docs/auth_auth_provider.md b/docs/auth_auth_provider.md
index 1980db2b..fd14c134 100644
--- a/docs/auth_auth_provider.md
+++ b/docs/auth_auth_provider.md
@@ -1,5 +1,5 @@
---
-title: "Authentication Providers"
+title: "Authentication providers"
---
Authentication providers confirm the identity of users. The user proofs their identity by going through the login flow for an auth provider. The auth provider defines the login flow and can ask the user all information this needs. This will commonly be username and password but could also include a 2FA token or other challenges.
diff --git a/docs/auth_index.md b/docs/auth_index.md
index d2b366bb..64494e34 100644
--- a/docs/auth_index.md
+++ b/docs/auth_index.md
@@ -32,7 +32,7 @@ The user that is created during onboarding will be marked as "owner". The owner
Users are a member of one or more groups. Group membership is how a user is granted permissions.
-## Permission Policy
+## Permission policy
This is the permission policy that describes to which resources a group has access. For more information about permissions and policies, see [Permissions](auth_permissions.md).
diff --git a/docs/auth_permissions.md b/docs/auth_permissions.md
index e76da25c..a27cbcd7 100644
--- a/docs/auth_permissions.md
+++ b/docs/auth_permissions.md
@@ -128,9 +128,9 @@ if not user.permissions.check_entity(entity_id, POLICY_CONTROL):
### The context object
-All service calls, fired events and states in Home Assistant have a context object. This object allows us to attribute changes to events and services. These context objects also contain a user id, which is used for checking the permissions.
+All service actions, fired events and states in Home Assistant have a context object. This object allows us to attribute changes to events and actions. These context objects also contain a user id, which is used for checking the permissions.
-It's crucial for permission checking that actions taken on behalf of the user are done with a context containing the user ID. If you are in a service handler, you should re-use the incoming context `call.context`. If you are inside a WebSocket API or Rest API endpoint, you should create a context with the correct user:
+It's crucial for permission checking that actions taken on behalf of the user are done with a context containing the user ID. If you are in a service action handler, you should re-use the incoming context `call.context`. If you are inside a WebSocket API or Rest API endpoint, you should create a context with the correct user:
```python
from homeassistant.core import Context
@@ -158,15 +158,15 @@ The `Unauthorized` exception has various parameters, to identify the permission
| perm_category | The permission category that we tested. Only necessary if we don't have an object ID that the user tried to operate on (like when we create a config entry).
| permission | The permission that we tested, ie `POLICY_READ`.
-### Securing a service call handler
+### Securing a service action handler
-Service calls allow a user to control entities or with the integration as a whole. A service call uses the attached context to see which user invoked the command. Because context is used, it is important that you also pass the call context to all service calls.
+Actions allow a user to control entities or with the integration as a whole. A service action uses the attached context to see which user invoked the command. Because context is used, it is important that you also pass the call context to all service action.
-All services that are registered via the entity component (`component.async_register_entity_service()`) will automatically have their permissions checked.
+All service actions that are registered via the entity component (`component.async_register_entity_service()`) will automatically have their permissions checked.
#### Checking entity permissions
-Your service call handler will need to check the permissions for each entity that it will act on.
+Your service action handler will need to check the permissions for each entity that it will act on.
```python
from homeassistant.exceptions import Unauthorized, UnknownUser
@@ -174,7 +174,7 @@ from homeassistant.auth.permissions.const import POLICY_CONTROL
async def handle_entity_service(call):
- """Handle a service call."""
+ """Handle a service action call."""
entity_ids = call.data["entity_id"]
for entity_id in entity_ids:
@@ -206,12 +206,12 @@ async def async_setup(hass, config):
#### Checking admin permission
Starting Home Assistant 0.90, there is a special decorator to help protect
-services that require admin access.
+service actions that require admin access.
```python
# New in Home Assistant 0.90
async def handle_admin_service(call):
- """Handle a service call."""
+ """Handle a service action call."""
# Do admin action
diff --git a/docs/bluetooth.md b/docs/bluetooth.md
index d61a726a..6e2a36d8 100644
--- a/docs/bluetooth.md
+++ b/docs/bluetooth.md
@@ -1,6 +1,6 @@
---
title: "Bluetooth"
-sidebar_label: "Building a Bluetooth Integration"
+sidebar_label: "Building a Bluetooth integration"
---
### Best practices for integration authors
diff --git a/docs/config_entries_config_flow_handler.md b/docs/config_entries_config_flow_handler.md
index 107f3cde..9f4fb2bb 100644
--- a/docs/config_entries_config_flow_handler.md
+++ b/docs/config_entries_config_flow_handler.md
@@ -1,10 +1,10 @@
---
-title: Config Flow
+title: Config flow
---
Integrations can be set up via the user interface by adding support for a config flow to create a config entry. Components that want to support config entries will need to define a Config Flow Handler. This handler will manage the creation of entries from user input, discovery or other sources (like Home Assistant OS).
-Config Flow Handlers control the data that is stored in a config entry. This means that there is no need to validate that the config is correct when Home Assistant starts up. It will also prevent breaking changes, because we will be able to migrate configuration entries to new formats if the version changes.
+Config Flow Handlers control the data that is stored in a config entry. This means that there is no need to validate that the config is correct when Home Assistant starts up. It will also prevent breaking changes because we will be able to migrate configuration entries to new formats if the version changes.
When instantiating the handler, Home Assistant will make sure to load all dependencies and install the requirements of the component.
@@ -14,7 +14,7 @@ You need to update your integrations manifest to inform Home Assistant that your
## Defining your config flow
-Config entries uses the [data flow entry framework](data_entry_flow_index.md) to define their config flows. The config flow needs to be defined in the file `config_flow.py` in your integration folder, extend `homeassistant.config_entries.ConfigFlow` and pass a `domain` key as part of inheriting `ConfigFlow`.
+Config entries use the [data flow entry framework](data_entry_flow_index.md) to define their config flows. The config flow needs to be defined in the file `config_flow.py` in your integration folder, extend `homeassistant.config_entries.ConfigFlow` and pass a `domain` key as part of inheriting `ConfigFlow`.
```python
from homeassistant import config_entries
@@ -63,6 +63,8 @@ There are a few step names reserved for system use:
| `user` | Invoked when a user initiates a flow via the user interface or when discovered and the matching and discovery step are not defined. |
| `reconfigure` | Invoked when a user initiates a flow to reconfigure an existing config entry via the user interface. |
| `zeroconf` | Invoked if your integration has been discovered via Zeroconf/mDNS as specified [using `zeroconf` in the manifest](creating_integration_manifest.md#zeroconf). |
+| `reauth` | Invoked if your integration indicates it [requires reauthentication, e.g., due to expired credentials](#reauthentication). |
+| `import` | Reserved for migrating from YAML configuration to config entries. |
## Unique IDs
@@ -98,11 +100,11 @@ that still allows for discovery, as long as there aren't any instances of the in
```python
if device_unique_id:
- await self.async_set_unique_id(device_unique_id)
+ await self.async_set_unique_id(device_unique_id)
await self._async_handle_discovery_without_unique_id()
```
-### Unique ID Requirements
+### Unique ID requirements
A unique ID is used to match a config entry to the underlying device or API. The unique ID must be stable, should not be able to be changed by the user and must be a string.
@@ -215,7 +217,7 @@ Translations for the config flow handlers are defined under the `config` key in
When the translations are merged into Home Assistant, they will be automatically uploaded to [Lokalise](https://lokalise.co/) where the translation team will help to translate them in other languages. While developing locally, you will need to run `python3 -m script.translations develop` to see changes made to `strings.json` [More info on translating Home Assistant.](translations.md)
-## Config Entry Migration
+## Config entry migration
As mentioned above - each Config Entry has a version assigned to it. This is to be able to migrate Config Entry data to new formats when Config Entry schema changes.
@@ -227,25 +229,25 @@ The version is made of a major and minor version. If minor versions differ but m
# Example migration function
async def async_migrate_entry(hass, config_entry: ConfigEntry):
"""Migrate old entry."""
- _LOGGER.debug("Migrating from version %s", config_entry.version)
+ _LOGGER.debug("Migrating configuration from version %s.%s", config_entry.version, config_entry.minor_version)
if config_entry.version > 1:
- # This means the user has downgraded from a future version
- return False
+ # This means the user has downgraded from a future version
+ return False
if config_entry.version == 1:
- new = {**config_entry.data}
- config_entry.minor_version < 2:
+ new_data = {**config_entry.data}
+ if config_entry.minor_version < 2:
# TODO: modify Config Entry data with changes in version 1.2
pass
- config_entry.minor_version < 3:
+ if config_entry.minor_version < 3:
# TODO: modify Config Entry data with changes in version 1.3
pass
- hass.config_entries.async_update_entry(config_entry, data=new, minor_version=3, version=1)
+ hass.config_entries.async_update_entry(config_entry, data=new_data, minor_version=3, version=1)
- _LOGGER.debug("Migration to version %s.%s successful", config_entry.version, config_entry.minor_version)
+ _LOGGER.debug("Migration to configuration version %s.%s successful", config_entry.version, config_entry.minor_version)
return True
```
@@ -274,7 +276,8 @@ class ExampleConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
## Reauthentication
-Gracefully handling authentication errors such as invalid, expired, or revoked tokens is needed to advance on the [Integration Qualily Scale](integration_quality_scale_index.md). This example of how to add reauth to the OAuth flow created by `script.scaffold` following the pattern in [Building a Python library](api_lib_auth.md#oauth2).
+Gracefully handling authentication errors such as invalid, expired, or revoked tokens is needed to advance on the [Integration Quality Scale](integration_quality_scale_index.md). This example of how to add reauth to the OAuth flow created by `script.scaffold` following the pattern in [Building a Python library](api_lib_auth.md#oauth2).
+If you are looking for how to trigger the reauthentication flow, see [handling expired credentials](integration_setup_failures#handling-expired-credentials).
This example catches an authentication exception in config entry setup in `__init__.py` and instructs the user to visit the integrations page in order to reconfigure the integration.
@@ -335,7 +338,8 @@ class OAuth2FlowHandler(
)
return await super().async_oauth_create_entry(data)
```
-By default, the `async_update_reload_and_abort` helper method aborts the flow with `reauth_successful` after update and reload.
+
+By default, the `async_update_reload_and_abort` helper method aborts the flow with `reauth_successful` after update and reload. By default, the entry will always be reloaded. If the config entry only should be reloaded in case the config entry was updated, specify `reload_even_if_entry_is_unchanged=False`.
Depending on the details of the integration, there may be additional considerations such as ensuring the same account is used across reauth, or handling multiple config entries.
diff --git a/docs/config_entries_index.md b/docs/config_entries_index.md
index cc867ea8..eb953689 100644
--- a/docs/config_entries_index.md
+++ b/docs/config_entries_index.md
@@ -1,5 +1,5 @@
---
-title: Config Entries
+title: Config entries
---
Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a [config flow handler](config_entries_config_flow_handler.md) as defined by the component. Config entries can also have an extra [options flow handler](config_entries_options_flow_handler.md), also defined by the component.
@@ -15,65 +15,79 @@ Config Entries are configuration data that are persistently stored by Home Assis
| migration error | The config entry had to be migrated to a newer version, but the migration failed.
| failed unload | The config entry was attempted to be unloaded, but this was either not supported or it raised an exception.
-More information about surfacing errors and requesting a retry are in [Handling Setup Failures](integration_setup_failures.md/#integrations-using-async_setup_entry).
+More information about surfacing errors and requesting a retry are in [Handling Setup Failures](integration_setup_failures.md#integrations-using-async_setup_entry).