diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 9e39a3de6c34..c4cf8a1c1c44 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,3 +1,10 @@ + ## Proposed change @@ -1528,4 +1538,4 @@ The output of this selector is a list of triggers. For example: - platform: numeric_state entity_id: "sensor.outside_temperature" below: 20 -``` \ No newline at end of file +``` diff --git a/source/_docs/blueprint/tutorial.markdown b/source/_docs/blueprint/tutorial.markdown index 6f988e5465cf..8ee36b28b4c1 100644 --- a/source/_docs/blueprint/tutorial.markdown +++ b/source/_docs/blueprint/tutorial.markdown @@ -19,11 +19,9 @@ related: title: Using automation blueprints --- -
- +{% tip %} While the tutorial only shows how to create an automation blueprint, {% term scripts %} also support blueprints in the same way. - -
+{% endtip %} ## Creating an automation blueprint @@ -51,7 +49,7 @@ trigger: entity_id: binary_sensor.motion_kitchen action: - service: > + action: > {% if trigger.to_state.state == "on" %} light.turn_on {% else %} @@ -65,7 +63,7 @@ action: The options that can be used with the `trigger` object are listed under [automation trigger variables](/docs/automation/templating/#available-trigger-data). In this example, a [state trigger](/docs/automation/templating/#state) is used. -`turn_on` and `turn_off` are [`homeassistant` services](/docs/scripts/service-calls/#homeassistant-services). They are not tied to a specific domain. You can use them on lights, switches, and other domains. +`turn_on` and `turn_off` are [`homeassistant` actions](/docs/scripts/perform-actions/#homeassistant-actions). They are not tied to a specific domain. You can use them on lights, switches, and other domains. ### Creating the blueprint file @@ -98,7 +96,7 @@ trigger: entity_id: !input motion_sensor ``` -For the light, we can offer some more flexibility. We want to allow the user to be able to define any device or area as the target. The `target` property in the service action can contain references to areas, devices and/or entities, so that's what we will use. +For the light, we can offer some more flexibility. We want to allow the user to be able to define any device or area as the target. The `target` property in the action can contain references to areas, devices, and/or entities, so that's what we will use. Inputs are not limited to strings. They can contain complex objects too. So in this case, we're going to mark the whole `target` as input: @@ -106,7 +104,7 @@ Inputs are not limited to strings. They can contain complex objects too. So in t ```yaml action: - service: > + action: > {% if trigger.to_state.state == "on" %} light.turn_on {% else %} @@ -240,7 +238,7 @@ trigger: entity_id: !input motion_sensor action: - - service: > + - action: > {% if trigger.to_state.state == "on" %} light.turn_on {% else %} @@ -256,9 +254,9 @@ action: 1. To configure your blueprint via the UI, go to {% my blueprints title="**Settings** > **Automations & Scenes** > **Blueprints**" %}. 2. Find the **Motion Light Tutorial** blueprint and select **Create Automation**. -
+{% important %} Don't forget to reload automations after you make changes to your blueprint to have the UI and the automation integration pick up the latest blueprint changes. -
+{% endimportant %} ![Screenshot of the blueprint UI](/images/blueprints/tutorial-ui.png) diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown index f93267df57b9..b73bfb1378fc 100644 --- a/source/_docs/configuration.markdown +++ b/source/_docs/configuration.markdown @@ -20,7 +20,9 @@ related: title: Troubleshooting the configuration --- -While you can configure most of Home Assistant from the user interface, for some integrations, you need to edit the `configuration.yaml` file. This file contains {% term integrations %} to be loaded along with their configurations. Throughout the documentation, you will find snippets that you can add to your configuration file to enable specific functionality. +While you can configure most of Home Assistant from the user interface, for some integrations, you need to edit the `configuration.yaml` file. + +This file contains {% term integrations %} to be loaded along with their configurations. Throughout the documentation, you will find snippets that you can add to your configuration file to enable specific functionality.

Screenshot of an example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation. @@ -68,6 +70,12 @@ To set up file access, follow the steps for your [installation method](/installa - {% term "Home Assistant Core" %}: the `configuration.yaml` is in the config folder passed to the `hass` command (default is `~/.homeassistant`). 3. Once you located the config folder, you can edit your `configuration.yaml` file. +{% note %} + +If you have watched any videos about setting up Home Assistant using `configuration.yaml` (particularly ones that are old), you might notice your default configuration file is much smaller than what the videos show. Don't be concerned, you haven't done anything wrong. Many items in the default configuration files shown in those old videos are now included in the `default_config:` line that you see in your configuration file. Refer to the [default config integration](/integrations/default_config/) for more information on what's included in that line. + +{% endnote %} + ## Validating the configuration After changing configuration or automation files, you can check if the configuration is valid. A configuration check is also applied automatically when you reload the configuration or when you restart Home Assistant. @@ -83,7 +91,7 @@ The method for running a configuration check depends on your [installation type] For configuration changes to become effective, the configuration must be reloaded. Most integrations in Home Assistant (that do not interact with {% term devices %} or {% term services %}) can reload changes made to their configuration in `configuration.yaml` without needing to restart Home Assistant. -1. Under **Settings**, select the three dots menu (top right), select **Restart Home Assistant** > **Quick reload**. +1. Under **Settings**, select the three dots menu (top right) {% icon "mdi:dots-vertical" %}, select **Restart Home Assistant** > **Quick reload**. ![Settings, three dot menu, restart Home Assistant](/images/docs/configuration/settings_restart_ha.png) diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown index 179d1a93475c..016a622a5d1b 100644 --- a/source/_docs/configuration/basic.markdown +++ b/source/_docs/configuration/basic.markdown @@ -13,13 +13,19 @@ As part of the default onboarding process, Home Assistant can detect your locati Screenshot showing the General settings page.

-The general settings described here are managed by the [Home Assistant Core integration](/integrations/homeassistant/). If you are interested in the services offered by this integration, check out the integration documentation. +The general settings described here are managed by the [Home Assistant Core integration](/integrations/homeassistant/). If you are interested in the actions offered by this integration, check out the integration documentation. ## Editing the general settings To change the general settings that were defined during onboarding, follow these steps: -1. Go to {% my general title="**Settings** > **System** > **General**" %} and make your changes. +1. Go to {% my general title="**Settings** > **System** > **General**" %}. + - Make your changes. + - To change location or radius, under **Edit location**, select edit. + - Then, adjust location and radius. + Screencast showing how to zoom and pan to change location and radius on the Edit home page + - To add a new zone, select **Add zone**. + - To save your changes, select **Update**. 2. To change network-related configuration, such as the network name, go to {% my network title="**Settings** > **System** > **Network**" %}. 3. If some of the settings are not visible, you may need to enable **Advanced mode**. - In the bottom left, select your username to go to your {% my profile title="**User profile**" %}, and enable **Advanced mode**. @@ -30,3 +36,38 @@ To change the general settings that were defined during onboarding, follow these ![Setting fields are grayed out because the configuration settings stored in configuration.yaml file](/images/docs/configuration/general-settings-stored-in-config-yaml.png) 5. To apply the changes, follow the steps on [reloading the configuration](/docs/configuration/#reloading-configuration-changes). + +## Changing a person's display name + +The display name is the name that is shown in Home Assistant. It can differ from the user name, which is the name used to log in. + +### Prerequisites + +- You need administrator rights to change a display name. + +## To change a display name + +1. To edit the display name of a person using Home Assistant, go to {% my people title="**Settings** > **People**" %} and select the person for which you want to change the display name. +2. Change the display name and select **Update** to save the change. + +## Changing a user name + +The user name is the name that is used to log in. It can differ from the display name. + +### Prerequisites + +- You need owner rights to change a user name. + +### To change a username + +1. To edit the username of a person using Home Assistant, go to {% my people title="**Settings** > **People**" %} and select the person for which you want to change the display name. +2. Change the username and select **Update** to save the change. + - The log in is case-sensitive. + +## Changing authentication settings + +To learn how to edit authentication settings such as password or multi-factor authentication, refer to the following topics: + +- [Authentication](/docs/authentication/) +- [multi-factor authentication](/docs/authentication/multi-factor-auth/) +- [Help, I'm locked out](/docs/locked_out/) diff --git a/source/_docs/configuration/entities_domains.markdown b/source/_docs/configuration/entities_domains.markdown new file mode 100644 index 000000000000..01164ff5193b --- /dev/null +++ b/source/_docs/configuration/entities_domains.markdown @@ -0,0 +1,40 @@ +--- +title: "Entities and domains" +description: "Describes what entities and domains are in Home Assistant." +related: + - docs: /docs/configuration/state_object/ + title: State object, entity state and attributes +--- + +Your devices are represented in Home Assistant as entities. Entities are the basic building blocks to hold data in Home Assistant. An entity represents a {% term sensor %}, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a {% term device %} or a {% term service %}. Entities have [states](/docs/configuration/state_object/) and [state attributes](/docs/configuration/state_object/#about-entity-state-attributes). + +All your entities are listed in the entities table, under {% my entities title="**Settings** > **Devices & services** > **Entities**" %}. + +

Screenshot showing the Entities tableScreenshot of the Entities table. Each line represents an entity.

+ +## Domains + +Each integration in Home Assistant has a unique identifier: a domain. All entities and actions available in Home Assistant are provided by integrations and thus belong to such a domain. The first part of the entity or action, before the `.` shows the domain they belong to. For example, `light.bed_light` is an entity in the light domain. `bed_light` is the ID of the entity. + +The domain provides entities, services, and other functionality that other integrations can use. For example, IKEA and Philips Hue both use functionalities provided by the light integration. This is why the look and feel and behavior is similar in Home Assistant. + +There are different types of domains: integration domains and entity domains: + +- Integration domains provide functionality primarily for itself: examples are Hue, Matter, or Zigbee. +- Entity domains don't use their own functionality as such. But they provide it for other integrations to use. + +The integrations listed below are used as entity domains. They are also referred to as *building block integrations* or *entity integrations*: + + diff --git a/source/_docs/configuration/events.markdown b/source/_docs/configuration/events.markdown index 3d4eb05f3df3..fa2ec1cd0dcc 100644 --- a/source/_docs/configuration/events.markdown +++ b/source/_docs/configuration/events.markdown @@ -1,11 +1,24 @@ --- title: "Events" description: "Describes all there is to know about events in Home Assistant." +related: + - docs: /docs/automation/trigger/#event-trigger + title: Event triggers + - docs: /integrations/event/ + title: Event integration --- -The core of Home Assistant is the event bus. The event bus allows any integration to fire or listen for events. It is the core of everything. For example, any state change will be announced on the event bus as a `state_changed` event containing the previous and the new state of an entity. +The core of Home Assistant is the event bus. The event bus allows any integration to fire or listen for events. -Home Assistant contains a few built-in events that are used to coordinate between various integrations. +## Events and state changes + +All {% term entities %} produce state change events. Every time a {% term state %} changes, a state change event is produced. State change events are just one type of event on the event bus, but there are other kinds of events, such as the [built-in events](#built-in-events-core) that are used to coordinate between various integrations. + +### State change events versus event entity + +State change events are not to be confused with the [event entity](/integrations/event/). The event entity is a specific type of entity that itself produces event state changes, just like all other entities. + +Any state change will be announced on the event bus as a `state_changed` event, containing the previous and the new state of an entity. ## Common fields @@ -24,14 +37,14 @@ In addition, all events contain a `data` dictionary with event-specific informat ### `call_service` -This event is fired when a service is called. +This event is fired when an service action is performed -| Field | Description | -| ----------------- | ------------------------------------------------------------------------------ | -| `domain` | Domain of the service. Example: `light`. | -| `service` | The service to call. Example: `turn_on` | -| `service_data` | Dictionary with the service call parameters. Example: `{ 'brightness': 120 }`. | -| `service_call_id` | String with a unique call id. Example: `23123-4`. | +| Field | Description | +| ----------------- | ---------------------------------------------------------------------- | +| `domain` | Domain of the action. Example: `light`. | +| `service` | The service action that is performed. Example: `turn_on` | +| `service_data` | Dictionary with the call parameters. Example: `{ 'brightness': 120 }`. | +| `service_call_id` | String with a unique call id. Example: `23123-4`. | ### `component_loaded` @@ -94,21 +107,21 @@ If you want to trigger automation on a Home Assistant stop event, we recommend u ### `service_registered` -This event is fired when a new service has been registered within Home Assistant. +This event is fired when a new service action has been registered within Home Assistant. -| Field | Description | -| --------- | ----------------------------------------------------------------------- | -| `domain` | The domain of the integration that offers this service. Example: `light`. | -| `service` | The name of the service. Example: `turn_on` | +| Field | Description | +| --------- | ------------------------------------------------------------------------ | +| `domain` | The domain of the integration that offers this action. Example: `light`. | +| `service` | The name of the service action. Example: `turn_on` | ### `service_removed` -This event is fired when a service has been removed from Home Assistant. +This event is fired when a service action has been removed from Home Assistant. -| Field | Description | -| --------- | ----------------------------------------------------------------------- | -| `domain` | The domain of the integration that offers this service. Example: `light`. | -| `service` | The name of the service. Example: `turn_on` | +| Field | Description | +| --------- | ------------------------------------------------------------------------ | +| `domain` | The domain of the integration that offers this action. Example: `light`. | +| `service` | The name of the service action. Example: `turn_on` | ### `state_changed` diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown index b5b2126b6bf7..5465ddc9968c 100644 --- a/source/_docs/configuration/packages.markdown +++ b/source/_docs/configuration/packages.markdown @@ -68,9 +68,9 @@ There are some rules for packages that will be merged: 3. Any integration that is not a platform [1], or dictionaries with Entity ID keys [2] can only be merged if its keys, except those for lists, are solely defined once. -
+{% tip %} Integrations inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the integration name. -
+{% endtip %} ## Create a packages folder @@ -114,10 +114,8 @@ homeassistant: ``` -
- +{% important %} If you are moving configuration to packages, `auth_providers` must stay within ‘configuration.yaml’. See the general documentation for [Authentication Providers](/docs/authentication/providers/#configuring-auth-providers). This is because Home Assistant processes the authentication provided early in the start-up process, even before packages are processed. - -
+{% endimportant %} diff --git a/source/_docs/configuration/platform_options.markdown b/source/_docs/configuration/platform_options.markdown index 0f0c443d67d9..d7b7e3a39f87 100644 --- a/source/_docs/configuration/platform_options.markdown +++ b/source/_docs/configuration/platform_options.markdown @@ -3,9 +3,9 @@ title: "Entity integration platform options" description: "Shows how to customize polling interval for any integration via configuration.yaml." --- -
+{% important %} These options are being phased out and are only available for single platform integrations. -
+{% endimportant %} Some integrations or platforms (those that are based on the [entity](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity.py) class) allow various extra options to be set. diff --git a/source/_docs/configuration/remote.markdown b/source/_docs/configuration/remote.markdown index c00987c0f93e..e2f3616f15c4 100644 --- a/source/_docs/configuration/remote.markdown +++ b/source/_docs/configuration/remote.markdown @@ -10,11 +10,9 @@ related: If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible. Below are a few options to do this. -
- +{% tip %} Remember to follow the [securing checklist](/docs/configuration/securing/) before doing this. - -
+{% endtip %} ## Home Assistant Cloud @@ -36,11 +34,9 @@ A problem with making a port accessible is that some Internet Service Providers If you cannot access your Home Assistant installation remotely, remember to check if your ISP provides you with a dedicated IP, instead of one shared with other users via a [CG-NAT](https://en.wikipedia.org/wiki/Carrier-grade_NAT). This is becoming fairly common nowadays due to the shortage of IPv4 addresses. Some, if not most ISPs will require you to pay an extra fee to be assigned a dedicated IPv4 address. -
- +{% caution %} Just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details, please check the [set up encryption using Let's Encrypt](/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/) blog post or this [detailed guide](https://community.home-assistant.io/t/certificate-authority-and-self-signed-certificate-for-ssl-tls/196970) to using Let's Encrypt with Home Assistant. - -
+{% endcaution %} ## Adding a remote URL to Home Assistant diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown index e06de57973d8..010db2271ac6 100644 --- a/source/_docs/configuration/secrets.markdown +++ b/source/_docs/configuration/secrets.markdown @@ -10,7 +10,9 @@ related: title: Securing your instance --- -The {% term "`configuration.yaml`" %} file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration. By using `!secret` you can remove any private information from your configuration files. This separation can also help you to keep easier track of your passwords and API keys, as they are all stored at one place and no longer spread across the {% term "`configuration.yaml`" %} file or even multiple YAML files if you [split up your configuration](/docs/configuration/splitting_configuration/). +The {% term "`configuration.yaml`" %} file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration. + +By using `!secret` you can remove any private information from your configuration files. This separation can also help you to keep easier track of your passwords and API keys, as they are all stored at one place and no longer spread across the {% term "`configuration.yaml`" %} file or even multiple YAML files if you [split up your configuration](/docs/configuration/splitting_configuration/). ## Using `secrets.yaml` diff --git a/source/_docs/configuration/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown index 4a4f9576d6e2..229846561703 100644 --- a/source/_docs/configuration/splitting_configuration.markdown +++ b/source/_docs/configuration/splitting_configuration.markdown @@ -272,7 +272,7 @@ automation: entity_id: device_tracker.iphone to: "home" action: - service: light.turn_on + action: light.turn_on target: entity_id: light.entryway - alias: "Automation 2" @@ -281,7 +281,7 @@ automation: entity_id: device_tracker.iphone from: "home" action: - service: light.turn_off + action: light.turn_off target: entity_id: light.entryway ``` @@ -303,7 +303,7 @@ trigger: entity_id: device_tracker.iphone to: "home" action: - service: light.turn_on + action: light.turn_on target: entity_id: light.entryway ``` @@ -317,7 +317,7 @@ trigger: entity_id: device_tracker.iphone from: "home" action: - service: light.turn_off + action: light.turn_off target: entity_id: light.entryway ``` @@ -334,7 +334,7 @@ alexa: intents: LocateIntent: action: - service: notify.pushover + action: notify.pushover data: message: "Your location has been queried via Alexa." speech: @@ -372,7 +372,7 @@ alexa: ```yaml {% raw %} action: - service: notify.pushover + action: notify.pushover data: message: "Your location has been queried via Alexa." speech: @@ -413,7 +413,7 @@ automation: entity_id: device_tracker.iphone to: "home" action: - - service: light.turn_on + - action: light.turn_on target: entity_id: light.entryway - alias: "Automation 2" @@ -422,7 +422,7 @@ automation: entity_id: device_tracker.iphone from: "home" action: - - service: light.turn_off + - action: light.turn_off target: entity_id: light.entryway ``` @@ -444,7 +444,7 @@ automation: !include_dir_merge_list automation/ entity_id: device_tracker.iphone to: "home" action: - - service: light.turn_on + - action: light.turn_on target: entity_id: light.entryway - alias: "Automation 2" @@ -453,7 +453,7 @@ automation: !include_dir_merge_list automation/ entity_id: device_tracker.iphone from: "home" action: - - service: light.turn_off + - action: light.turn_off target: entity_id: light.entryway ``` diff --git a/source/_docs/configuration/state_object.markdown b/source/_docs/configuration/state_object.markdown index 4736c0da719d..7f70fd8a92ea 100644 --- a/source/_docs/configuration/state_object.markdown +++ b/source/_docs/configuration/state_object.markdown @@ -1,49 +1,86 @@ --- -title: "State objects" -description: "Describes all there is to know about state objects in Home Assistant." +title: "State and state object" +description: "Describes all there is to know about state and the state object in Home Assistant." +related: + - docs: /docs/configuration/entities_domains/ + title: Entities and domains --- -Your {% term devices %} are represented in Home Assistant as entities. The {% term entities %} will write their current {% term state %} to the state machine for other entities/templates/frontend to access. States are a current representation of the {% term entity %}. +Devices are represented in Home Assistant as {% term entities %}. The state of an entity (for example, if a light is on, at 50% brightness in orange) can be shown on the dashboard or be used in automations. This page looks at the concepts _state_, _state object_, and _entity state attribute_. -If you overwrite a state via the states dev tool or the API, it will not impact the actual device. If the device state is being polled, it will overwrite the state in the state machine the next polling. +## State versus state object -All states will always have an entity id, a state and a timestamp when last updated and last changed. +In Home Assistant, the state object is the current representation of the {% term entity %} with all its attributes at a given moment in time. This state is recorded as a _state object_. Entities constantly keep track of their state and write it into a state object, so that other entities/templates/frontend can access it. In the example—the light is on, at 50% brightness in orange—_on_ is the actual state of the light. 50% brightness and the color are entity state attributes. -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `state.state` | String representation of the current state of the entity. Example `off`. | -| `state.entity_id` | Entity ID. Format: `.`. Example: `light.kitchen`. | -| `state.domain` | Domain of the entity. Example: `light`. | -| `state.object_id` | Object ID of entity. Example: `kitchen`. | -| `state.name` | Name of the entity. Based on `friendly_name` attribute with fall back to object ID. Example: `Kitchen Ceiling`. | -| `state.last_changed` | Time the state changed in the state machine in UTC time. This is not updated if only state attributes change. Example: `2017-10-28 08:13:36.715874+00:00`. | -| `state.last_reported`| Time the state was written to the state machine in UTC time. This timestamp is updated regardless of any change to the state or a state attribute. Example: `2017-10-28 08:13:36.715874+00:00`. | -| `state.last_updated` | Time the state or state attributes changed in the state machine in UTC time. This is not updated if neither state nor state attributes changed. Example: `2017-10-28 08:13:36.715874+00:00`. | -| `state.attributes` | A dictionary with extra attributes related to the current state. | -| `state.context` | A dictionary with extra attributes related to the context of the state. | +### About the state object -## Attributes +The state object represents the state of an entity with its attributes at a specific point in time. All state objects will always have an entity id, a state, and timestamps when last updated, last changed, and last reported. +The `state` prefix indicates that this information is part of the state object (which is related to the entity). For example, `state.state` is the state of the entity at a given time. -The attributes of an {% term entity %} are optional. There are a few attributes that are used by Home Assistant for representing the entity in a specific way. Each integration will also have its own attributes to represent extra state data about the entity. For example, the light integration has attributes for the current brightness and color of the light. When an attribute is not available, Home Assistant will not write it to the state. +| Field | Description | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `state.state` | String representation of the current state of the entity. Example `off`. | +| `state.entity_id` | Entity ID. Format: `.`. Example: `light.kitchen`. | +| `state.domain` | Domain of the entity. Example: `light`. | +| `state.object_id` | Object ID of entity. Example: `kitchen`. | +| `state.name` | Name of the entity. Based on `friendly_name` attribute with fall back to object ID. Example: `Kitchen ceiling`. | +| `state.last_changed` | Time the state changed in the state machine in UTC time. This is not updated if only state attributes change. Example: `2013-09-17 07:32:51.715874+00:00`. | +| `state.last_reported` | Time the state was written to the state machine in UTC time. This timestamp is updated regardless of any changes to the state or state attributes. Example: `2013-09-17 07:32:51.715874+00:00`. | +| `state.last_updated` | Time the state or state attributes changed in the state machine in UTC time. This is not updated if neither state nor state attributes changed. Example: `2013-09-17 07:32:51.715874+00:00`. | +| `state.attributes` | A dictionary with extra attributes related to the current state. | +| `state.context` | A dictionary with extra attributes related to the context of the state. | + +### About the state + +The screenshot shows three lights in different states (the `state.state`): `on`, `off`, and `unavailable`. Each light comes with its own entity state attributes such as `supported_color_modes`, `supported_features`. These attributes have their own state: the state of `supported_color_modes` is `color_temp` and `hs`, the state of the `supported_features` attribute is `4`. + +

+ Screenshot showing three lights with different states: `on`, `off`, or `unavailable` + Three lights with different states: `on`, `off`, or `unavailable`. +

+ +The `state.state` is the heart of the [state object](#about-the-state-object). State holds the information of interest of an entity. For example, if a +light is on or off, the current temperature, or the amount of energy used. The state object stores 3 +timestamps related to the state: `last_updated`, `last_changed`, and `last_reported`. Each +entity has exactly one state, and the state only holds one value at a time. + +### About entity state attributes + +The state only holds one value at a time. However, entities can store related entity state attributes in the state object. For example, +the state of a light is _on_, and the related attributes could be its +current brightness and color values. [State change events](/docs/configuration/events/#events-and-state-changes) can be used as triggers. +The current state can be used in [conditions](/docs/automation/condition/). The example below shows three lights with different entity state attributes. + +

+ Screenshot showing three lights with different states and attributes + Example showing three lights with different entity state attributes. +

+ +Entities have some attributes that are not related to its state, such as `friendly_name`. A few attributes are available on all entities, such as `friendly_name` or `icon`. In addition to those, each integration has its own attributes to represent extra state data about the entity. For example, the light integration has attributes for the current brightness and color of the light. When an attribute is not available, Home Assistant will not write it to the state. Entity attributes are optional. When using templates, attributes will be available by their name. For example `state.attributes.assumed_state`. -| Attribute | Description | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `friendly_name` | Name of the entity. Example: `Kitchen Ceiling`. | -| `icon` | Icon to use for the entity in the frontend. Example: `mdi:home`. | -| `entity_picture` | URL to a picture that should be used instead of showing the domain icon. Example: `http://example.com/picture.jpg`. | -| `assumed_state` | Boolean if the current state is an assumption. [More info](/blog/2016/02/12/classifying-the-internet-of-things/#classifiers) Example: `True`. | -| `unit_of_measurement` | The unit of measurement the state is expressed in. Used for grouping graphs or understanding the entity. Example: `°C`. | +The table lists common state attributes that may be present, depending on the entity domain. + +| Attribute | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `friendly_name` | Name of the entity. Example: `Kitchen Ceiling`. | +| `icon` | Icon to use for the entity in the frontend. Example: `mdi:home`. | +| `entity_picture` | URL to a picture that should be used instead of showing the domain icon. Example: `http://example.com/picture.jpg`. | +| `assumed_state` | Boolean if the current state is an assumption. [More info](/blog/2016/02/12/classifying-the-internet-of-things/#classifiers) Example: `True`. | +| `unit_of_measurement` | The unit of measurement the state is expressed in. Used for grouping graphs or understanding the entity. Example: `°C`. | +| `attribution` | The provider of the data. For example, "Data provided by rejseplanen.dk", "Data provided by openSenseMap" | +| `device_class` | The type of device that an entity represents. Used to display device specific information in the UI. | +| `supported_features` | The features an entity supports. For covers, for example, it might list `opening`, `closing`, `stopping`, `setting position`. For media players, it might list `play`, `pause`, `stop`, and `volume control` | When an attribute contains spaces, you can retrieve it like this: `state_attr('sensor.livingroom', 'Battery numeric')`. ## Context -Context is used to tie {% term events %} and {% term states %} together in Home Assistant. Whenever an {% term automation %} or user interaction causes states to change, a new context is assigned. This context will be attached to all events and states that happen as result of the change. +Context is a property used in state objects and events. It ties {% term events %} and {% term states %} together in Home Assistant. Whenever an {% term automation %} or user interaction causes a state to change, a new context is assigned in the state object. This context will be attached to all events and states that happen as a result of the change. -| Field | Description | -| ------------ | ------------------------------------------------------------------- | -| `context_id` | Unique identifier for the context. | -| `user_id` | Unique identifier of the user that started the change. Will be `None` if the action was not started by a user (for example, started by an automation). | -| `parent_id` | Unique identifier of the parent context that started the change, if available. For example, if an automation is triggered, the context of the trigger will be set as parent. | +| Field | Description | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `context_id` | Unique identifier for the context. | +| `user_id` | Unique identifier of the user that started the change. Will be `None` if the action was not started by a user (for example, started by an automation). | +| `parent_id` | Unique identifier of the parent context that started the change, if available. For example, if an automation is triggered, the context of the trigger will be set as parent. | diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 727e2f7ccf77..749ca968641e 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -34,7 +34,7 @@ Templates can get big pretty fast. To keep a clear overview, consider using YAML script: msg_who_is_home: sequence: - - service: notify.notify + - action: notify.notify data: message: > {% if is_state('device_tracker.paulus', 'home') %} @@ -70,7 +70,7 @@ extensions: You can write reusable Jinja templates by adding them to a `custom_templates` folder under your configuration directory. All template files must have the `.jinja` extension and be less than 5MiB. Templates in this folder will be loaded at startup. To reload the templates without -restarting Home Assistant, invoke the {% my developer_call_service service="homeassistant.reload_custom_templates" %} service. +restarting Home Assistant, invoke the {% my developer_call_service service="homeassistant.reload_custom_templates" %} action. Once the templates are loaded, Jinja [includes](https://jinja.palletsprojects.com/en/3.0.x/templates/#include) and [imports](https://jinja.palletsprojects.com/en/3.0.x/templates/#import) will work using `config/custom_templates` as the base directory. @@ -121,11 +121,9 @@ Not supported in [limited templates](#limited-templates). - `is_state_attr('device_tracker.paulus', 'battery', 40)` will test if the given entity attribute is the specified state (in this case, a numeric value). Note that the attribute can be `None` and you want to check if it is `None`, you need to use `state_attr('sensor.my_sensor', 'attr') is none` or `state_attr('sensor.my_sensor', 'attr') == None` (note the difference in the capitalization of none in both versions). - `has_value('sensor.my_sensor')` will test if the given entity is not unknown or unavailable. Can be used as a filter or a test. -
- +{% warning %} Avoid using `states.sensor.temperature.state`, instead use `states('sensor.temperature')`. It is strongly advised to use the `states()`, `is_state()`, `state_attr()` and `is_state_attr()` as much as possible, to avoid errors and error message when the entity isn't ready yet (e.g., during Home Assistant startup). - -
+{% endwarning %} #### States examples @@ -447,6 +445,7 @@ The same thing can also be expressed as a test: ### Config entries - `config_entry_id(entity_id)` returns the config entry ID for a given entity ID. Can also be used as a filter. +- `config_entry_attr(config_entry_id, attr)` returns the value of `attr` for the config entry of the given entity ID. Can also be used as a filter. The following attributes are allowed: `domain`, `title`, `state`, `source`, `disabled_by`. Not supported in [limited templates](#limited-templates). #### Config entries examples @@ -456,6 +455,12 @@ The same thing can also be expressed as a test: {{ config_entry_id('sensor.sony') }} # deadbeefdeadbeefdeadbeefdeadbeef ``` +```text +{{ config_entry_attr(config_entry_id('sensor.sony'), 'title') }} # Sony Bravia TV +``` + + + {% endraw %} ### Floors @@ -558,7 +563,7 @@ The same thing can also be expressed as a test: - `integration_entities(integration)` returns a list of entities that are associated with a given integration, such as `hue` or `zwave_js`. - `integration_entities(config_entry_title)` if you have multiple entries set-up for an integration, you can also use the title you've set for the integration in case you only want to target a specific entry. -If there is more than one entry with the same title, the entities for all the matching entries will be returned, even if the entries are for different integrations. It's not possible to search for entities of an untitled integration. +If there is more than one entry with the same title, the entities for all the matching entries will be returned, even if the entries are for different integrations. It's not possible to search for entities of an untitled integration. #### Integrations examples @@ -699,15 +704,13 @@ Examples using `iif`: {{ (states('light.kitchen') == 'on') | iif('Yes', 'No') }} ``` -
+{% endraw %} +{% warning %} The immediate if filter does not short-circuit like you might expect with a typical conditional statement. The `if_true`, `if_false` and `if_none` expressions will all be evaluated and the filter will simply return one of the resulting values. This means you cannot use this filter to prevent executing an expression which would result in an error. For example, if you wanted to select a field from `trigger` in an automation based on the platform you might go to make this template: `trigger.platform == 'event' | iif(trigger.event.data.message, trigger.to_state.state)`. This won't work because both expressions will be evaluated and one will fail since the field doesn't exist. Instead you have to do this `trigger.event.data.message if trigger.platform == 'event' else trigger.to_state.state`. This form of the expression short-circuits so if the platform is `event` the expression `trigger.to_state.state` will never be evaluated and won't cause an error. - -
- -{% endraw %} +{% endwarning%} ### Time @@ -719,7 +722,7 @@ For example, if you wanted to select a field from `trigger` in an automation bas - `utcnow()` returns a datetime object of the current time in the UTC timezone. - For specific values: `utcnow().second`, `utcnow().minute`, `utcnow().hour`, `utcnow().day`, `utcnow().month`, `utcnow().year`, `utcnow().weekday()` and `utcnow().isoweekday()`. - Using `utcnow()` will cause templates to be refreshed at the start of every new minute. -- `today_at(value)` converts a string containing a military time format to a datetime object with today's date in your time zone. +- `today_at(value)` converts a string containing a military time format to a datetime object with today's date in your time zone. Defaults to midnight (`00:00`). - Using `today_at()` will cause templates to be refreshed at the start of every new minute. @@ -733,8 +736,8 @@ For example, if you wanted to select a field from `trigger` in an automation bas {% endraw %} - `as_datetime(value, default)` converts a string containing a timestamp, or valid UNIX timestamp, to a datetime object. If that fails, it returns the `default` value or, if omitted, raises an error. When the input is already a datetime object it will be returned as is. in case the input is a datetime.date object, midnight will be added as time. This function can also be used as a filter. -- `as_timestamp(value, default)` converts datetime object or string to UNIX timestamp. If that fails, returns the `default` value, or if omitted raises an error. This function can also be used as a filter. -- `as_local()` converts datetime object to local time. This function can also be used as a filter. +- `as_timestamp(value, default)` converts a datetime object or string to UNIX timestamp. If that fails, returns the `default` value, or if omitted raises an error. This function can also be used as a filter. +- `as_local()` converts a datetime object to local time. This function can also be used as a filter. - `strptime(string, format, default)` parses a string based on a [format](https://docs.python.org/3.10/library/datetime.html#strftime-and-strptime-behavior) and returns a datetime object. If that fails, it returns the `default` value or, if omitted, raises an error. - `time_since(datetime, precision)` converts a datetime object into its human-readable time string. The time string can be in seconds, minutes, hours, days, months, and years. `precision` takes an integer (full number) and indicates the number of units returned. The last unit is rounded. For example: `precision = 1` could return "2 years" while `precision = 2` could return "1 year 11 months". This function can also be used as a filter. If the datetime is in the future, returns 0 seconds. @@ -742,7 +745,7 @@ A precision of 0 returns all available units, default is 1. - `time_until(datetime, precision)` converts a datetime object into a human-readable time string. The time string can be in seconds, minutes, hours, days, months, and years. `precision` takes an integer (full number) and indicates the number of units returned. The last unit is rounded. For example: `precision = 1` could return "2 years" while `precision = 2` could return "1 year 11 months". This function can also be used as a filter. If the datetime is in the past, returns 0 seconds. A precision of 0 returns all available units, default is 1. -- `timedelta` returns a timedelta object and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks. +- `timedelta` returns a timedelta object, which represents a duration (an amount of time between two datetimes). It accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks. {% raw %} @@ -753,7 +756,7 @@ A precision of 0 returns all available units, default is 1. {% endraw %} -- `as_timedelta(string)` converts a string to a timedelta object. Expects data in the format `DD HH:MM:SS.uuuuuu`, `DD HH:MM:SS,uuuuuu`, or as specified by ISO 8601 (e.g. `P4DT1H15M20S` which is equivalent to `4 1:15:20`) or PostgreSQL’s day-time interval format (e.g. `3 days 04:05:06`) This function can also be used as a filter. +- `as_timedelta(string)` converts a string to a timedelta object, which represents a duration (an amount of time between two datetimes). Expects data in the format `DD HH:MM:SS.uuuuuu`, `DD HH:MM:SS,uuuuuu`, or as specified by ISO 8601 (e.g. `P4DT1H15M20S` which is equivalent to `4 1:15:20`) or PostgreSQL’s day-time interval format (e.g. `3 days 04:05:06`). This function can also be used as a filter. {% raw %} @@ -768,14 +771,11 @@ A precision of 0 returns all available units, default is 1. - Filter `timestamp_utc(default)` converts a UNIX timestamp to the ISO format string representation representation as date/time in UTC timezone. If that fails, returns the `default` value, or if omitted raises an error. If a custom string format is needed in the string, use `timestamp_custom` instead. - Filter `timestamp_custom(format_string, local=True, default)` converts an UNIX timestamp to its string representation based on a custom format, the use of a local timezone is the default. If that fails, returns the `default` value, or if omitted raises an error. Supports the standard [Python time formatting options](https://docs.python.org/3/library/time.html#time.strftime). -
- +{% tip %} [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) is the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. Therefore, if used as a function's argument, it can be substituted with a numeric value (`int` or `float`). +{% endtip %} -
- -
- +{% important %} If your template is returning a timestamp that should be displayed in the frontend (e.g., as a sensor entity with `device_class: timestamp`), you have to ensure that it is the ISO 8601 format (meaning it has the "T" separator between the date and time portion). Otherwise, frontend rendering on macOS and iOS devices will show an error. The following value template would result in such an error: {% raw %} @@ -792,7 +792,7 @@ To fix it, enforce the ISO conversion via `isoformat()`: {% endraw %} -
+{% endimportant %} {% raw %} @@ -1009,7 +1009,7 @@ Some examples: {% set to_remove = extra_ambiance | map(attribute='name') | reject('in', to_add) | list %} {{ (state_attr('input_select.light_theme', 'options') + to_add ) | unique | reject('in', to_remove) | list }} ``` - This more complex example uses the `contains` filter to match the current month with a list. In this case, it's used to generate a list of light theme to give to the `Input select: Set options` service. + This more complex example uses the `contains` filter to match the current month with a list. In this case, it's used to generate a list of light theme to give to the `Input select: Set options` action. {% endraw %} @@ -1017,7 +1017,7 @@ Some examples: Some of these functions can also be used in a [filter](https://jinja.palletsprojects.com/en/latest/templates/#id11). This means they can act as a normal function like this `sqrt(2)`, or as part of a filter like this `2|sqrt`. -
+{% note %} The numeric functions and filters raise an error if the input is not a valid number, optionally a default value can be specified which will be returned instead. The `is_number` function and filter can be used to check if a value is a valid number. Errors can be caught by the `default` filter. @@ -1030,7 +1030,7 @@ The numeric functions and filters raise an error if the input is not a valid num {% endraw %} -
+{% endnote %} - `float(value, default)` function will attempt to convert the input to a `float`. If that fails, returns the `default` value, or if omitted raises an error. - `float(default)` filter will attempt to convert the input to a `float`. If that fails, returns the `default` value, or if omitted raises an error. @@ -1091,6 +1091,38 @@ While Jinja natively supports the conversion of an iterable to a `list`, it does Note that, in Home Assistant, to convert a value to a `list`, a `string`, an `int`, or a `float`, Jinja has built-in functions with names that correspond to each type. +### Iterating multiple objects + +The `zip()` function can be used to iterate over multiple collections in one operation. + +{% raw %} + +```text +{% set names = ['Living Room', 'Dining Room'] %} +{% set entities = ['sensor.living_room_temperature', 'sensor.dining_room_temperature'] %} +{% for name, entity in zip(names, entities) %} + The {{ name }} temperature is {{ states(entity) }} +{% endfor %} +``` + +{% endraw %} + +`zip()` can also unzip lists. + +{% raw %} + +```text +{% set information = [ + ('Living Room', 'sensor.living_room_temperature'), + ('Dining Room', 'sensor.dining_room_temperature') +] %} +{% set names, entities = zip(*information) %} +The names are {{ names | join(', ') }} +The entities are {{ entities | join(', ') }} +``` + +{% endraw %} + ### Functions and filters to process raw data These functions are used to process raw value's in a `bytes` format to values in a native Python type or vice-versa. @@ -1102,7 +1134,7 @@ See: [Python struct library documentation](https://docs.python.org/3/library/str - Filter `value | unpack(format_string, offset=0)` will try to convert a `bytes` object into a native Python object. The `offset` parameter defines the offset position in bytes from the start of the input `bytes` based buffer. This will call function `struct.unpack_from(format_string, value, offset=offset)`. Returns `None` if an error occurs or when `format_string` is invalid. Note that the filter `unpack` will only return the first `bytes` object, despite the function `struct.unpack_from` supporting to return multiple objects (e.g. with `format_string` being `">hh"`. - Function `unpack(value, format_string, offset=0)` will try to convert a `bytes` object into a native Python object. The `offset` parameter defines the offset position in bytes from the start of the input `bytes` based buffer. This will call function `struct.unpack_from(format_string, value, offset=offset)`. Returns `None` if an error occurs or when `format_string` is invalid. Note that the function `unpack` will only return the first `bytes` object, despite the function `struct.unpack_from` supporting to return multiple objects (e.g. with `format_string` being `">hh"`. -
+{% note %} Some examples: {% raw %} @@ -1114,13 +1146,28 @@ Some examples: {% endraw %} -
+{% endnote %} ### String filters - Filter `urlencode` will convert an object to a percent-encoded ASCII text string (e.g., for HTTP requests using `application/x-www-form-urlencoded`). - Filter `slugify(separator="_")` will convert a given string into a "slug". - Filter `ordinal` will convert an integer into a number defining a position in a series (e.g., `1st`, `2nd`, `3rd`, `4th`, etc). +- Filter `value | base64_decode` Decodes a base 64 string to a string, by default utf-8 encoding is used. +- Filter `value | base64_decode("ascii")` Decodes a base 64 string to a string, using ascii encoding. +- Filter `value | base64_decode(None)` Decodes a base 64 string to raw bytes. + +
+ +Some examples: +{% raw %} + +- `{{ "aG9tZWFzc2lzdGFudA==" | base64_decode }}` - renders as `homeassistant` +- `{{ "aG9tZWFzc2lzdGFudA==" | base64_decode(None) }}` - renders as `b'homeassistant'` + +{% endraw %} + +
### Regular expressions @@ -1240,14 +1287,14 @@ To evaluate a response, go to **{% my developer_template title="Developer Tools ### Using templates with the MQTT integration -The [MQTT integration](/integrations/mqtt/) relies heavily on templates. Templates are used to transform incoming payloads (value templates) to status updates or incoming service calls (command templates) to payloads that configure the MQTT device. +The [MQTT integration](/integrations/mqtt/) relies heavily on templates. Templates are used to transform incoming payloads (value templates) to status updates or incoming actions (command templates) to payloads that configure the MQTT device. #### Using value templates with MQTT For incoming data a value template translates incoming JSON or raw data to a valid payload. Incoming payloads are rendered with possible JSON values, so when rendering the `value_json` can be used access the attributes in a JSON based payload. -
+{% note %} Example value template: @@ -1261,15 +1308,15 @@ Template {% raw %}`{{ value_json.temperature | round(1) }}`{% endraw %} renders Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used as variables in the template. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item. -
+{% endnote %} #### Using command templates with MQTT -For service calls command templates are defined to format the outgoing MQTT payload to the device. When a service call is executed `value` can be used to generate the correct payload to the device. +For actions, command templates are defined to format the outgoing MQTT payload to the device. When an action is executed, `value` can be used to generate the correct payload to the device. -
+{% note %} -Example command template: +**Example command template with JSON data:** With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endraw %} renders to: @@ -1281,7 +1328,15 @@ With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endr Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used as variables in the template. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item. -
+{% endnote %} + +**Example command template with raw data:** + +When a command template renders to a valid `bytes` literal, then MQTT will publish this data as raw data. In other cases, a string representation will be published. So: + +- Template {% raw %}`{{ "16" }}`{% endraw %} renders to payload encoded string `"16"`. +- Template {% raw %}`{{ 16 }}`{% endraw %} renders to payload encoded string `"16"`. +- Template {% raw %}`{{ pack(0x10, ">B") }}`{% endraw %} renders to a raw 1 byte payload `0x10`. ## Some more things to keep in mind diff --git a/source/_docs/configuration/troubleshooting.markdown b/source/_docs/configuration/troubleshooting.markdown index 3390d996933e..ad25fd6f0b8c 100644 --- a/source/_docs/configuration/troubleshooting.markdown +++ b/source/_docs/configuration/troubleshooting.markdown @@ -88,9 +88,9 @@ Contents of `sensors.yaml`: ... ``` -
+{% note %} Whenever you report an issue, be aware that we are volunteers who do not have access to every single device in the world nor unlimited time to fix every problem out there. -
+{% endnote %} ### Entity names @@ -110,12 +110,18 @@ The first thing you will need before reporting an issue online is debug logs and ### Enabling debug logging -To enable debug logging for an integration, go to **Settings** > **Devices & Services** > **Integrations** and go to the detail page of the integration. Select the **Enable Debug Logging** button on the left side of the integration detail page. +To enable debug logging for a specific integration, follow these steps: -

- Example of Enable debug logging - Example of Enable debug logging. -

+1. Go to {% my integrations title="**Settings** > **Devices & services**" %}. +2. Select the integration card to open the detail page of the integration for which you want to enable debug logging. +3. On the left side of the integration detail page, select **Enable Debug Logging**. + - The screenshot uses the MQTT integration as an example for illustration purposes. It does not mean you need to install the MQTT integration. + +

+ Screenshot showing the Enable debug logging button on an integration detail page + Screenshot showing the Enable debug logging button on an integration detail page. The MQTT integration is used as an example to show where the button can be found. +

+4. To see the error in the logs, you need to reproduce the error. Continue with the steps on [disabling debug logging and download logs](#disable-debug-logging-and-download-logs). ### Disable debug logging and download logs diff --git a/source/_docs/frontend.markdown b/source/_docs/frontend.markdown index 3320902fbb7a..a0f5b80e7d5f 100644 --- a/source/_docs/frontend.markdown +++ b/source/_docs/frontend.markdown @@ -28,7 +28,7 @@ To learn how to create and style your own dashboards, refer to the following top To learn how to organize and filter your data on an existing dashboard, refer to the following topics: - [Grouping](/docs/organizing/) into [areas](/docs/organizing/areas/), [floors](/docs/organizing/floors/), [labels](/docs/organizing/labels/), and [categories](/docs/organizing/categories/) -- [Filtering](/docs/organizing/filtering) +- [Filtering](/docs/organizing/tables) ## User- or browser-dependent settings, general settings diff --git a/source/_docs/frontend/icons.markdown b/source/_docs/frontend/icons.markdown index ed95d33b1469..3a50a1823678 100644 --- a/source/_docs/frontend/icons.markdown +++ b/source/_docs/frontend/icons.markdown @@ -32,11 +32,9 @@ The most common way you can find icons is by using the icon picker built right i Icon Picker in Home Assistant

-
- - The icon picker will filter by icon name and by aliases applied to the icon by the MDI project. For example, typing "user" will show you most "account"-named icons. - -
+{% tip %} +The icon picker will filter by icon name and by aliases applied to the icon by the MDI project. For example, typing "user" will show you most "account"-named icons. +{% endtip %} For more detailed steps on customizing entities, including their icon, refer to [customizing entities](/docs/configuration/customizing-devices/). @@ -48,31 +46,25 @@ The easiest way to browse and find icons outside of Home Assistant is with the o Material Design Icons Picker

-
- - Not all icons that appear in the MDI Picker Browser Extension may be available in Home Assistant (yet!). While the browser extension is updated as MDI releases new packages, Home Assistant may lag behind until its next release. - -
+{% note %} +Not all icons that appear in the MDI Picker Browser Extension may be available in Home Assistant (yet!). While the browser extension is updated as MDI releases new packages, Home Assistant may lag behind until its next release. +{% endnote %} ### Material design icons on the Pictogrammers website The last way to browse through available icons is by viewing the library on the Pictogrammers website, [https://pictogrammers.com/library/mdi/](https://pictogrammers.com/library/mdi/). Select an icon you'd like to use, then click "Home Assistant" to see an example of its usage. -
- - The Pictogrammers website will always show the latest release of the material design icons library. However, you may find icons that may not yet be available in Home Assistant (yet!). Watch the Home Assistant release notes for announcements on upgrades of the Material Design Icons library. - -
+{% note %} +The Pictogrammers website will always show the latest release of the material design icons library. However, you may find icons that may not yet be available in Home Assistant (yet!). Watch the Home Assistant release notes for announcements on upgrades of the Material Design Icons library. +{% endnote %} ## Suggesting or contributing new icons Being open-source like Home Assistant, the material design icons library is always accepting suggestions and contributions to expand the library. -
- - Before suggesting or creating a new icon, it is very important that you [search the current library](https://pictogrammers.com/library/mdi/) and [search all issues](https://github.com/Templarian/MaterialDesign/issues?q=is%3Aissue), open and closed, on their GitHub. Try searching with different terms that might mean the same thing. (e.g. "user", "person", "account") - -
+{% note %} +Before suggesting or creating a new icon, it is very important that you [search the current library](https://pictogrammers.com/library/mdi/) and [search all issues](https://github.com/Templarian/MaterialDesign/issues?q=is%3Aissue), open and closed, on their GitHub. Try searching with different terms that might mean the same thing. (e.g. "user", "person", "account") +{% endnote %} ### Suggesting a new icon diff --git a/source/_docs/locked_out.md b/source/_docs/locked_out.md index 0132a46419ae..cd40aced017c 100644 --- a/source/_docs/locked_out.md +++ b/source/_docs/locked_out.md @@ -15,19 +15,42 @@ or need to recover your data. ## Forgot username -If you’ve forgotten your username, ask the owner to help you. -If you are using the {% term "Home Assistant Operating System" %} and have access to the Home Assistant server, you can connect a terminal and enter the `auth list` command. This command lists all users that are registered on your Home Assistant. +### Symptom: I'm the owner and I forgot my username + +You are the **owner** of the Home Assistant server and you cannot login because you forgot your username. + +#### Remedy + +1. Check if the following conditions are met: + - you are using the {% term "Home Assistant Operating System" %} + - you have access to the Home Assistant server. +2. Open a terminal connection to Home Assistant: + - If you are using a Home Assistant Green, follow these steps [to access the console](https://green.home-assistant.io/guides/use-terminal/). + - If you are using a Home Assistant Yellow, follow these steps: + - [to access the console from Windows](https://yellow.home-assistant.io/guides/use-serial-console-windows/) + - [to access the console from Linux or macOS](https://yellow.home-assistant.io/guides/use-serial-console-linux-macos/). + - If you are using another system, connect keyboard and monitor. The procedure might be similar the one used for Green. + - If you are using a Home Assistant OVA (virtualization image): + - Access the system console by opening the terminal through your virtualization platform's interface (for example, Proxmox, VMware, VirtualBox). + - Follow the platform-specific steps to interact with the virtual machine's console. +3. In the terminal, enter the `auth list` command. + - This command lists all users that are registered on your Home Assistant. ## Forgot password -If you are not the owner or do not have administrator rights, ask the owner to give you a new password. +### Symptom: I'm the owner and I forgot my password -- In the navigation pane on the left, check if you see the **Settings** menu listed above the **Notifications**. - - If you don't, you do not have administrator rights. +You are the owner or administrator of Home Assistant and forgot your password. -If you are the owner or have administrator, there are different methods to reset a password, depending on your setup: +### Remedy: resetting an owner's password -### To reset a password while still logged in (including Supervised) +If you are the owner or have administrator, there are different methods to reset a password, depending on your situation: + +- [Reset a password while still logged in](#to-reset-a-password-while-still-logged-in-including-supervised) +- [Reset an owner's password when logged out](#to-reset-an-owners-password-via-console) +- [reset a user's password, via the container command line](#to-reset-a-users-password-via-the-container-command-line) + +#### To reset a password while still logged in (including Supervised) The method used to reset a password depends on your user rights: @@ -40,29 +63,30 @@ The method used to reset a password depends on your user rights: 2. Reset your password via this new administrator account (and then [delete this new account](/docs/locked_out/#to-delete-a-user)). - Your configuration will remain, and you don't have to do a new onboarding process. -### To reset an owner's password, via console +#### To reset an owner's password, via console Use this procedure only if the following conditions are met: - You know the username. -- You can access the [Home Assistant console](/hassio/commandline/) **on the device itself** (not via the SSH terminal from the add-ons). +- You can access the Home Assistant console **on the device itself** (not via the SSH terminal from the add-ons). -1. Connect to the console of the Home Assistant server: - - If you are using a virtual machine, connect to your virtual machine console. +1. If you are using a Home Assistant Yellow or Green, refer to their documentation. - If you are using a Home Assistant Yellow, refer to the following procedure: - - [Using the serial console on Windows](https://yellow.home-assistant.io/guides/use-serial-console-windows/) - - [Using the serial console on macOS / Linux](https://yellow.home-assistant.io/guides/use-serial-console-linux-macos/) + - [Resetting the owner password on Home Assistant Yellow](https://yellow.home-assistant.io/faq/#i-forgot-the-owner-password-for-home-assistant-how-can-i-reset-it) - If you are using a Home Assistant Green, refer to the following procedure: - - [Using the terminal](https://green.home-assistant.io/guides/use-terminal/) - - If you are using another board, connect a keyboard and monitor to your device and access the terminal. The procedure is likely very similar to the one described for the Green in the step above. -2. Once you have opened the Home Assistant command line, enter the following command: + - [Resetting the owner password on Home Assistant Green](https://green.home-assistant.io/faq/#i-forgot-the-owner-password-for-the-home-assistant-green-how-can-i-reset-it) +2. If you are not using a Yellow or Green: Connect to the console of the Home Assistant server: + - If you are using a virtual machine, connect to your virtual machine console. + - If you are using another board, connect a keyboard and monitor to your device and access the terminal. The procedure is likely very similar to the one described for the Home Assistant Green. +3. Once you have opened the Home Assistant command line, enter the following command: - Note: `existing_user` is a placeholder. Replace it with your username. - Note: `new_password` is a placeholder. Replace it with your new password. - - **Command**: `ha auth reset --username existing_user --password new_password` + - **Command**: `auth reset --username existing_user --password new_password` + ![Screencast showing how to enter the ha auth reset command](/images/docs/troubleshooting/home-assistant-cli.webp) - **Troubleshooting**: If you see the message `zsh: command not found: auth`, you likely did not enter the command in the serial console connected to the device itself, but in the terminal within Home Assistant. -3. You can now log in to Home Assistant using this new password. +4. You can now log in to Home Assistant using this new password. -### To reset a user's password, via the container command line +#### To reset a user's password, via the container command line If you are running Home Assistant in a container, you can use the command line in the container with the `hass` command to change your password. The steps below refer to a Home Assistant container in Docker named `homeassistant`. Note that while working in the container, commands will take a few moments to execute. @@ -72,7 +96,7 @@ If you are running Home Assistant in a container, you can use the command line i 4. `exit` to exit the container command line 5. `docker restart homeassistant` to restart the container. -### To reset a user's password, as an owner via the web interface +#### To reset a user's password, as an owner via the web interface Only the owner can change other user's passwords. @@ -84,17 +108,7 @@ Only the owner can change other user's passwords. 5. Confirm the new password by entering it again, and select **OK** again. 6. A confirmation box will be displayed with the text **Password was changed successfully**. -### To delete a user - -You need to be an owner or have administrator rights to delete a user. - -1. Go to {% my people title="**Settings** > **People**" %} and select the person which you want to delete. - - Note: you cannot delete the owner. -2. At the bottom of the dialog box, select **Delete**. - - A confirmation dialog box will be displayed. -3. To confirm, select **OK**. - -### To prepare the system to start a new onboarding process +## Preparing the system to start a new onboarding process If you lose the password associated with the owner account and the steps above do not work to reset the password, the only way to resolve this is to start a new onboarding process. @@ -138,3 +152,13 @@ For Windows or macOS you will need third party software. Below are some options. - Windows: (read-only access to the SD) - macOS: + +## Deleting a user + +You need to be an owner or have administrator rights to delete a user. + +1. Go to {% my people title="**Settings** > **People**" %} and select the person which you want to delete. + - Note: you cannot delete the owner. +2. At the bottom of the dialog box, select **Delete**. + - A confirmation dialog box will be displayed. +3. To confirm, select **OK**. diff --git a/source/_docs/organizing.markdown b/source/_docs/organizing.markdown index 5091baaac10a..7a415489bd63 100644 --- a/source/_docs/organizing.markdown +++ b/source/_docs/organizing.markdown @@ -12,21 +12,23 @@ related: title: Categories --- -Once you have more devices, you may want to target entire groups of devices in automations. It also becomes more challenging to find items in lists. There are a few tools to group your assets: [Areas](#areas), [floors](#floors), [labels](#labels), and [categories](#categories). +Once you have more devices, you may want to target entire groups of devices in automations. It also becomes more challenging to find items in lists. -| Taxonomy | Automation target | Entity can have multiple | -| -------- | ----------------- | ------------------------ | -| Area | ✅ | ❌ | -| Floor | ✅ | ❌ | -| Label | ✅ | ✅ | -| Category | ❌ | ❌ | +There are a few tools to group your assets: [Areas](#areas), [floors](#floors), [labels](#labels), and [categories](#categories). + +| Taxonomy | Automation target | Entity can have multiple | +| -------- | -------------------------------- | -------------------------------- | +| Area | {% icon "openmoji:check-mark" %} | {% icon "openmoji:cross-mark" %} | +| Floor | {% icon "openmoji:check-mark" %} | {% icon "openmoji:cross-mark" %} | +| Label | {% icon "openmoji:check-mark" %} | {% icon "openmoji:check-mark" %} | +| Category | {% icon "openmoji:cross-mark" %} | {% icon "openmoji:cross-mark" %} | ## Area - Groups {% term devices %} and {% term entities %}. - Can be assigned to one floor. - Reflects a physical area (or room) in your home. -- Can be used in automations: Allows targeting an entire group of devices with a service call. For example, turning off all the lights in the living room. +- Can be used in automations: Allows targeting an entire group of devices with an action. For example, turning off all the lights in the living room. - Areas can also be used to automatically generate cards, such as the [Area card](/dashboards/area/). @@ -42,7 +44,7 @@ Once you have more devices, you may want to target entire groups of devices in a ## Labels - Can be assigned to areas, devices, entities, automations, scenes, scripts, and helpers. -- Can be used in automations and scripts as a target for actions and services. +- Can be used in automations and scripts as a target for actions. - Labels can also be used to filter data in tables. For example, you can filter the list of devices to show only devices with the label `heavy energy usage` or turn these devices off when there is not a lot of solar energy available. Screenshots showing the new labels assigned to automations. diff --git a/source/_docs/organizing/areas.markdown b/source/_docs/organizing/areas.markdown index 6af4f1434ba7..93eebe783232 100644 --- a/source/_docs/organizing/areas.markdown +++ b/source/_docs/organizing/areas.markdown @@ -13,7 +13,9 @@ related: title: Using areas in template --- -An area in Home Assistant is a logical grouping of {% term devices %} and {% term entities %} that are meant to match areas (or rooms) in the physical world of your home. For example, the "Living room" area groups devices and entities in your living room. Areas allow you to target an entire group of devices with a service call. For example, turning off all the lights in the living room. +An area in Home Assistant is a logical grouping of {% term devices %} and {% term entities %} that are meant to match areas (or rooms) in the physical world of your home. + +For example, the "Living room" area groups devices and entities in your living room. Areas allow you to target an entire group of devices with an action. For example, turning off all the lights in the living room. Areas can be assigned to floors. Areas can also be used to automatically generate cards, such as the [Area card](/dashboards/area/). ## Creating an area @@ -42,7 +44,7 @@ Follow these steps to create a new area from the **Areas** view. If an area has not yet been assigned to a floor, it is shown in the **Unassigned areas** section. Follow these steps to assign an area to a floor. 1. Go to {% my areas title="**Settings** > **Areas, labels & zones**" %} and select **Create area**. -2. On the area card, select the pencil icon. +2. On the area card, select the edit {% icon "mdi:edit" %} button. 3. In the dialog, select the floor and add labels, if you like. ## Assigning an area to multiple items @@ -52,7 +54,7 @@ You can assign an area to multiple items at once in the automation, scene, scrip 1. Depending on what you want to assign, go to one of the following pages: - For automations, scripts, or scenes {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab. - For devices, go to {% my devices title="**Settings** > **Devices & services** > **Devices**" %}. -2. In the list, [select all the items](/docs/organizing/filtering#selecting-multiple-items-in-a-table) you want to assign to an area. +2. In the list, [select all the items](/docs/organizing/tables#selecting-multiple-items-in-a-table) you want to assign to an area. ![Screenshot showing how to assign multiple devices to an area](/images/organizing/area_assign_devices.png) @@ -62,7 +64,7 @@ You can assign an area to multiple items at once in the automation, scene, scrip Follow these steps to edit an area. -1. Go to {% my areas title="**Settings** > **Areas, labels & zones**" %} and on the area card, select the pencil icon. +1. Go to {% my areas title="**Settings** > **Areas, labels & zones**" %} and on the area card, select the edit {% icon "mdi:edit" %} button. 2. In the dialog, adjust the area details you want to change: - Edit the area **Name**. - Add an icon (We use [Material icons](https://pictogrammers.com/library/mdi/)). diff --git a/source/_docs/organizing/categories.markdown b/source/_docs/organizing/categories.markdown index 261332fbc02c..3fd569de1ab8 100644 --- a/source/_docs/organizing/categories.markdown +++ b/source/_docs/organizing/categories.markdown @@ -10,7 +10,9 @@ related: title: Labels --- -Categories let you group and filter items in a table. Like labels, categories allow grouping irrespective of the items physical location. For example, on the automations page, you can create the categories “Notifications” or “NFC tags” to view your automations grouped or filtered. These categories group automations on the automation page, but have no effect anywhere else. Categories are unique for each table. The automations page can have different categories than the scene, scripts, or helpers settings page. +Categories let you group and filter items in a table. Like labels, categories allow grouping irrespective of the items physical location. + +For example, on the automations page, you can create the categories “Notifications” or “NFC tags” to view your automations grouped or filtered. These categories group automations on the automation page, but have no effect anywhere else. Categories are unique for each table. The automations page can have different categories than the scene, scripts, or helpers settings page. ## Creating a category @@ -29,11 +31,11 @@ Follow these steps to create a new category. 1. Go to {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab. 2. To assign a category to a single item: - - Find the item in the list and select the three dots menu. + - Find the item in the list and select the three dots {% icon "mdi:dots-vertical" %} menu. - Select **Assign category** and select the category from the list. - If the category is not in the list, select **Add new category** and make a new one. 3. To assign a category to multiple items: - - Select the Multiselect icon button. + - Select the multi-select {% icon "mdi:order-checkbox-ascending" %} button. - From the list, select all the items to which you want to apply a category. - In the top right corner, select **Move to category**. - Then, select the category from the list. diff --git a/source/_docs/organizing/floors.markdown b/source/_docs/organizing/floors.markdown index 3a39c03ec91e..bb62473b88b8 100644 --- a/source/_docs/organizing/floors.markdown +++ b/source/_docs/organizing/floors.markdown @@ -13,8 +13,9 @@ related: title: Using floor alias for voice assistants --- -A floor in Home Assistant is a logical grouping of areas meant to match your home's physical floors. Devices and entities -cannot be assigned to floors directly but to areas. Floors can be used in automations and scripts as a target for actions. For example, to turn off all the lights on the downstairs floor when you go to bed. +A floor in Home Assistant is a logical grouping of areas meant to match your home's physical floors. + +Devices and entities cannot be assigned to floors directly but to areas. Floors can be used in automations and scripts as a target for actions. For example, to turn off all the lights on the downstairs floor when you go to bed. ## Creating a floor @@ -43,7 +44,7 @@ Follow these steps to create a new floor. Follow these steps to delete a floor. Areas that are assigned to a floor will become unassigned. Automations and scripts or voice assistants that used a floor as a target will no longer work as they no longer have a target. 1. Go to {% my areas title="**Settings** > **Areas, labels & zones**" %}. -2. Next to the floor, select the three dots menu and select **Delete floor**. +2. Next to the floor, select the three dots {% icon "mdi:dots-vertical" %} menu and select **Delete floor**. ![Screenshot showing the dialog to delete a floor](/images/organizing/floor_delete.png) diff --git a/source/_docs/organizing/labels.markdown b/source/_docs/organizing/labels.markdown index 0e95e8dc515b..ba46255f284a 100644 --- a/source/_docs/organizing/labels.markdown +++ b/source/_docs/organizing/labels.markdown @@ -12,7 +12,9 @@ related: title: Using labels in templates --- -Labels in Home Assistant allow grouping elements irrespective of their physical location or type. Labels can be assigned to areas, devices, entities, automations, scenes, scripts, and helpers. Labels can be used in automations and scripts as a target for actions and services. Labels can also be used to filter data. For example, you can filter the list of devices to show only devices with the label `heavy energy usage` or turn these devices off when there is not a lot of solar energy available. +Labels in Home Assistant allow grouping elements irrespective of their physical location or type. Labels can be assigned to areas, devices, entities, automations, scenes, scripts, and helpers. Labels can be used in automations and scripts as a target for actions. Labels can also be used to filter data. + +For example, you can filter the list of devices to show only devices with the label `heavy energy usage` or turn these devices off when there is not a lot of solar energy available. ## Creating a label @@ -36,20 +38,20 @@ Follow these steps to apply a label 1. To apply a label to an area: - Go to {% my areas title="**Settings** > **Areas, labels & zones**" %}. - - On the area card, select the pencil icon. + - On the area card, select the edit {% icon "mdi:edit" %} button. - Select one or more labels or select **Add new label** to create a new one. 2. To apply a label to a device, entity, or helper: - Go to **{% my integrations title="Settings > Devices & Services" %}** and open the respective tab. - - Select the Multiselect icon button. + - Select the {% icon "mdi:order-checkbox-ascending" %} button. - From the list, select all the list entries to which you want to apply a label. - In the top right corner, select **Add label**. Then, select the labels from the list. ![Apply label](/images/organizing/labels_add_05.png) 3. To apply a label to an automation, scene, or script: - Go to {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab. - - Select the Multiselect icon button. + - Select the {% icon "mdi:order-checkbox-ascending" %} button. - From the list, select all the list entries to which you want to apply a label. - - In the top right corner, select the three dots menu, then select **Add label**. Then, select the labels from the list. + - In the top right corner, select the three dots {% icon "mdi:dots-vertical" %} menu, then select **Add label**. Then, select the labels from the list. ## Deleting a label @@ -57,7 +59,7 @@ Follow these steps to delete a label. It will be removed from all the list entri If you used this label in automations or script as targets, you need to adjust those. 1. Go to {% my labels title="**Settings** > **Areas, labels & zones**" %} and on top, select the **Labels** tab. -2. In the list of labels, find the label you want to delete and select the three dots menu. +2. In the list of labels, find the label you want to delete and select the three dots {% icon "mdi:dots-vertical" %} menu. 3. Select **Delete**. 4. If you used this label in automations or script as targets, you need to adjust those. @@ -66,8 +68,7 @@ If you used this label in automations or script as targets, you need to adjust t 1. Go to the data table that contains the element from which you want to remove the label: - Go to **{% my integrations title="Settings > Devices & Services" %}** and open the respective tab. - Or, go to {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab. -2. Select the Multiselect icon button. +2. Select the {% icon "mdi:order-checkbox-ascending" %} button. - From the list, select all the items from which you want to remove a label. - - In the top right corner, select the three dots menu, then select **Add label**. + - In the top right corner, select the three dots {% icon "mdi:dots-vertical" %} menu, then select **Add label**. - Then, deselect the checkbox for the label you want to remove. - diff --git a/source/_docs/organizing/filtering.markdown b/source/_docs/organizing/tables.markdown similarity index 76% rename from source/_docs/organizing/filtering.markdown rename to source/_docs/organizing/tables.markdown index d8fa65532d75..8c6d2d6e6592 100644 --- a/source/_docs/organizing/filtering.markdown +++ b/source/_docs/organizing/tables.markdown @@ -1,5 +1,5 @@ --- -title: "Filtering your assets" +title: "Working with tables" description: "Filter for items in tables." related: - docs: /docs/organizing/floors/ @@ -20,7 +20,7 @@ When working with tables, you can select multiple items to apply an action. If y ## Selecting multiple items in a table -1. In your table, select the Multiselect icon button. +1. In your table, select the {% icon "mdi:order-checkbox-ascending" %} button. ![Screenshots point out the enable selection mode button in the toolbar of the tables in Home Assistant](/images/blog/2024-04/enable-selection-mode.png) @@ -34,6 +34,8 @@ When working with tables, you can select multiple items to apply an action. If y You can filter a table so that only items matching certain criteria are shown. +To filter items in a table, follow these steps: + 1. In the top left corner above the table, select the **Filters** button. ![Select the filter button](/images/organizing/filters_01.png) @@ -48,6 +50,8 @@ You can filter a table so that only items matching certain criteria are shown. You can group items in a table according to certain criteria. The number of shown items stays the same. No items will be hidden. +To group items in a table, follow these steps: + 1. In the top right above the table, select the **Group by** button. 2. The items will be grouped according to the criteria you chose. - The list of available criteria depends on the type of table. @@ -59,4 +63,17 @@ You can group items in a table according to certain criteria. The number of show 3. To sort the items, select the **Sort by** button. 4. To get a better overview, you can collapse groups in the list. - ![Collapse groups](/images/organizing/table_group_collapse.png) \ No newline at end of file + ![Collapse groups](/images/organizing/table_group_collapse.png) + +## Customizing columns + +You can show or hide columns and change the order. Your customized columns are stored in your browser, so you only have to set it up once, and it will be remembered for the next time you visit the page. + +To customize columns, follow these steps: + +1. In the top right corner of the table, select the cog wheel. +2. To hide a column, deselect it. +3. To rearrange the order, grab the column and move it to its new position. +4. To sort, select the column header of interest. + + ![Screencast showing how to show, hide, and rearrange columns](/images/organizing/customize_columns.webp) \ No newline at end of file diff --git a/source/_docs/scene.markdown b/source/_docs/scene.markdown index 058778c517bb..9f23ca2093dc 100644 --- a/source/_docs/scene.markdown +++ b/source/_docs/scene.markdown @@ -52,7 +52,7 @@ As you can see, there are two ways to define the states of each `entity_id`: - Define the `state` directly with the entity. Be aware, that `state` needs to be defined. - Define a complex state with its attributes. You can see all attributes available for a particular entity under `developer-tools -> state`. -Scenes can be activated using the service `scene.turn_on` (there is no 'scene.turn_off' service). +Scenes can be activated using the action `scene.turn_on` (there is no 'scene.turn_off' action). ```yaml # Example automation @@ -63,14 +63,14 @@ automation: from: "not_home" to: "home" action: - service: scene.turn_on + action: scene.turn_on target: entity_id: scene.romantic ``` ## Applying a scene without defining it -With the `scene.apply` service you are able to apply a scene without first defining it via configuration. Instead, you pass the states as part of the service data. The format of the data is the same as the `entities` field in a configuration. +With the `scene.apply` action you are able to apply a scene without first defining it via configuration. Instead, you pass the states as part of the data. The format of the data is the same as the `entities` field in a configuration. ```yaml # Example automation @@ -81,7 +81,7 @@ automation: from: "not_home" to: "home" action: - service: scene.apply + action: scene.apply data: entities: light.tv_back_light: @@ -95,7 +95,7 @@ automation: ## Using scene transitions -Both the `scene.apply` and `scene.turn_on` services support setting a transition, +Both the `scene.apply` and `scene.turn_on` actions support setting a transition, which enables you to smoothen the transition to the scene. This is an example of an automation that sets a romantic scene, in which the @@ -110,7 +110,7 @@ automation: from: "not_home" to: "home" action: - service: scene.turn_on + action: scene.turn_on target: entity_id: scene.romantic data: @@ -123,4 +123,4 @@ only lights to have a transition set. ## Reloading scenes -Whenever you make a change to your scene configuration, you can call the `scene.reload` service to reload the scenes. +Whenever you make a change to your scene configuration, you can call the `scene.reload` action to reload the scenes. diff --git a/source/_docs/scene/editor.markdown b/source/_docs/scene/editor.markdown index cf9ff0fc4f4b..63c2ff87fde9 100644 --- a/source/_docs/scene/editor.markdown +++ b/source/_docs/scene/editor.markdown @@ -16,10 +16,10 @@ On the moment you save the scene, all the states of your devices are stored in t When you leave the editor the states of the devices are restored to the state from before you started editing. The menu on the top-right has options to **Duplicate scene** and **Delete scene**. -A scene can be called in {% term automation %} action and {% term scripts %} using a turn on scene {% term service %}: +A scene can be called in {% term automation %} action and {% term scripts %} using a turn on scene {% term action %}: ```yaml -service: scene.turn_on +action: scene.turn_on target: entity_id: scene.my_unique_id ``` @@ -77,6 +77,6 @@ For example: brightness: 200 ``` -
+{% note %} Any comments in the YAML file will be lost and templates will be reformatted when you update a scene via the editor. -
+{% endnote %} diff --git a/source/_docs/scripts.markdown b/source/_docs/scripts.markdown index 432a8d02b0bf..aefb1391c85d 100644 --- a/source/_docs/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -2,7 +2,6 @@ title: "Script Syntax" description: "Documentation for the Home Assistant Script Syntax." toc: true -no_toc: true --- Scripts are a sequence of {% term actions %} that Home Assistant will execute. Scripts are available as an entity through the standalone [Script integration] but can also be embedded in {% term automations %} and [Alexa/Amazon Echo] configurations. @@ -22,24 +21,24 @@ script: sequence: # This is written using the Script Syntax - alias: "Turn on ceiling light" - service: light.turn_on + action: light.turn_on target: entity_id: light.ceiling - alias: "Notify that ceiling light is turned on" - service: notify.notify + action: notify.notify data: message: "Turned on the ceiling light!" ``` {{ page.content | markdownify | toc_only }} -## Call a service +## Perform an action -The most important one is the action to call a {% term service %}. This can be done in various ways. For all the different possibilities, have a look at the [service calls page]. +Performing an action can be done in various ways. For all the different possibilities, have a look at the [actions page]. ```yaml - alias: "Bedroom lights on" - service: light.turn_on + action: light.turn_on target: entity_id: group.bedroom data: @@ -48,7 +47,7 @@ The most important one is the action to call a {% term service %}. This can be d ### Activate a scene -Scripts may also use a shortcut syntax for activating {% term scenes %} instead of calling the `scene.turn_on` service. +Scripts may also use a shortcut syntax for activating {% term scenes %} instead of calling the `scene.turn_on` action. ```yaml - scene: scene.morning_living_room @@ -68,7 +67,7 @@ The variables {% term action %} allows you to set/override variables that will b - light.living_room brightness: 100 - alias: "Control lights" - service: light.turn_on + action: light.turn_on target: entity_id: "{{ entities }}" data: @@ -86,7 +85,7 @@ Variables can be templated. variables: blind_state_message: "The blind is {{ states('cover.blind') }}." - alias: "Notify about the state of the blind" - service: notify.mobile_app_iphone + action: notify.mobile_app_iphone data: message: "{{ blind_state_message }}" ``` @@ -116,11 +115,11 @@ sequence: - variables: people: "{{ people + 1 }}" # At this scope, people will now be 1 ... - - service: notify.notify + - action: notify.notify data: message: "There are {{ people }} people home" # "There are 1 people home" # ... but at this scope it will still be 0 - - service: notify.notify + - action: notify.notify data: message: "There are {{ people }} people home" # "There are 0 people home" ``` @@ -131,11 +130,9 @@ sequence: While executing a script you can add a condition in the main sequence to stop further execution. When a condition does not return `true`, the script will stop executing. For documentation on the many different conditions refer to the [conditions page]. -
- +{% note %} The `condition` {% term action %} only stops executing the current sequence block. When it is used inside a [repeat](#repeat-a-group-of-actions) action, only the current iteration of the `repeat` loop will stop. When it is used inside a [choose](#choose-a-group-of-actions) action, only the {% term actions %} within that `choose` will stop. - -
+{% endnote %} ```yaml # If paulus is home, continue to execute the script below these lines @@ -282,11 +279,11 @@ Without `continue_on_timeout: false` the script will always continue since the d After each time a wait completes, either because the condition was met, the event happened, or the timeout expired, the variable `wait` will be created/updated to indicate the result. -Variable | Description --|- -`wait.completed` | Exists only after `wait_template`. `true` if the condition was met, `false` otherwise -`wait.trigger` | Exists only after `wait_for_trigger`. Contains information about which trigger fired. (See [Available-Trigger-Data](/docs/automation/templating/#available-trigger-data).) Will be `none` if no trigger happened before timeout expired -`wait.remaining` | Timeout remaining, or `none` if a timeout was not specified +| Variable | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `wait.completed` | Exists only after `wait_template`. `true` if the condition was met, `false` otherwise | +| `wait.trigger` | Exists only after `wait_for_trigger`. Contains information about which trigger fired. (See [Available-Trigger-Data](/docs/automation/templating/#available-trigger-data).) Will be `none` if no trigger happened before timeout expired | +| `wait.remaining` | Timeout remaining, or `none` if a timeout was not specified | This can be used to take different actions based on whether or not the condition was met, or to use more than one wait sequentially while implementing a single timeout overall. @@ -299,9 +296,9 @@ This can be used to take different actions based on whether or not the condition - if: - "{{ not wait.completed }}" then: - - service: script.door_did_not_open + - action: script.door_did_not_open else: - - service: script.turn_on + - action: script.turn_on target: entity_id: - script.door_did_open @@ -311,7 +308,7 @@ This can be used to take different actions based on whether or not the condition - wait_template: "{{ is_state('binary_sensor.door_1', 'on') }}" timeout: 10 continue_on_timeout: false -- service: switch.turn_on +- action: switch.turn_on target: entity_id: switch.some_light - wait_for_trigger: @@ -321,7 +318,7 @@ This can be used to take different actions based on whether or not the condition for: 2 timeout: "{{ wait.remaining }}" continue_on_timeout: false -- service: switch.turn_off +- action: switch.turn_off target: entity_id: switch.some_light ``` @@ -383,7 +380,7 @@ The following {% term automation %} example shows how to capture the custom even - platform: event event_type: event_light_state_changed action: - - service: notify.notify + - action: notify.notify data: message: "kitchen light is turned {{ trigger.event.data.state }}" ``` @@ -407,7 +404,7 @@ script: flash_light: mode: restart sequence: - - service: light.turn_on + - action: light.turn_on target: entity_id: "light.{{ light }}" - alias: "Cycle light 'count' times" @@ -415,13 +412,13 @@ script: count: "{{ count|int * 2 - 1 }}" sequence: - delay: 2 - - service: light.toggle + - action: light.toggle target: entity_id: "light.{{ light }}" flash_hallway_light: sequence: - alias: "Flash hallway light 3 times" - service: script.flash_light + action: script.flash_light data: light: hallway count: 3 @@ -448,7 +445,7 @@ repeat: - "kitchen" - "office" sequence: - - service: light.turn_off + - action: light.turn_off target: entity_id: "light.{{ repeat.item }}" ``` @@ -468,7 +465,7 @@ repeat: - language: Dutch message: Hallo Wereld sequence: - - service: notify.phone + - action: notify.phone data: title: "Message in {{ repeat.item.language }}" message: "{{ repeat.item.message }}!" @@ -487,7 +484,7 @@ is run. The sequence will be run _as long as_ the condition(s) evaluate to true. script: do_something: sequence: - - service: script.get_ready_for_something + - action: script.get_ready_for_something - alias: "Repeat the sequence AS LONG AS the conditions are true" repeat: while: @@ -498,7 +495,7 @@ script: - condition: template value_template: "{{ repeat.index <= 20 }}" sequence: - - service: script.something + - action: script.something ``` {% endraw %} @@ -541,7 +538,7 @@ automation: repeat: sequence: # Run command that for some reason doesn't always work - - service: shell_command.turn_something_on + - action: shell_command.turn_something_on # Give it time to complete - delay: milliseconds: 200 @@ -572,11 +569,11 @@ For example: A variable named `repeat` is defined within the repeat {% term action %} (i.e., it is available inside `sequence`, `while` & `until`.) It contains the following fields: -field | description --|- -`first` | True during the first iteration of the repeat sequence -`index` | The iteration number of the loop: 1, 2, 3, ... -`last` | True during the last iteration of the repeat sequence, which is only valid for counted loops +| field | description | +| ------- | -------------------------------------------------------------------------------------------- | +| `first` | True during the first iteration of the repeat sequence | +| `index` | The iteration number of the loop: 1, 2, 3, ... | +| `last` | True during the last iteration of the repeat sequence, which is only valid for counted loops | ## If-then @@ -593,12 +590,12 @@ script: state: 0 then: - alias: "Then start cleaning already!" - service: vacuum.start + action: vacuum.start target: area_id: living_room # The `else` is fully optional and can be omitted else: - - service: notify.notify + - action: notify.notify data: message: "Skipped cleaning, someone is home!" ``` @@ -636,24 +633,24 @@ automation: - condition: template value_template: "{{ now().hour < 9 }}" sequence: - - service: script.sim_morning + - action: script.sim_morning # ELIF day - conditions: - condition: template value_template: "{{ now().hour < 18 }}" sequence: - - service: light.turn_off + - action: light.turn_off target: entity_id: light.living_room - - service: script.sim_day + - action: script.sim_day # ELSE night default: - - service: light.turn_off + - action: light.turn_off target: entity_id: light.kitchen - delay: minutes: "{{ range(1, 11)|random }}" - - service: light.turn_off + - action: light.turn_off target: entity_id: all ``` @@ -676,22 +673,22 @@ automation: {{ trigger.to_state.state == 'Home' and is_state('binary_sensor.all_clear', 'on') }} sequence: - - service: script.arrive_home + - action: script.arrive_home data: ok: true - conditions: > {{ trigger.to_state.state == 'Home' and is_state('binary_sensor.all_clear', 'off') }} sequence: - - service: script.turn_on + - action: script.turn_on target: entity_id: script.flash_lights - - service: script.arrive_home + - action: script.arrive_home data: ok: false - conditions: "{{ trigger.to_state.state == 'Away' }}" sequence: - - service: script.left_home + - action: script.left_home ``` {% endraw %} @@ -716,7 +713,7 @@ automation: below: 4 action: # This must always apply - - service: light.turn_on + - action: light.turn_on data: brightness: 255 color_temp: 366 @@ -731,7 +728,7 @@ automation: entity_id: binary_sensor.livingroom_tv state: "on" sequence: - - service: light.turn_on + - action: light.turn_on data: brightness: 255 color_temp: 366 @@ -744,7 +741,7 @@ automation: entity_id: binary_sensor.studio_pc state: "on" sequence: - - service: light.turn_on + - action: light.turn_on data: brightness: 255 color_temp: 366 @@ -780,18 +777,18 @@ automation: action: - alias: "Turn on devices" sequence: - - service: light.turn_on + - action: light.turn_on target: entity_id: light.ceiling - - service: siren.turn_on + - action: siren.turn_on target: entity_id: siren.noise_maker - alias: "Send notifications" sequence: - - service: notify.person1 + - action: notify.person1 data: message: "The motion sensor was triggered!" - - service: notify.person2 + - action: notify.person2 data: message: "Oh oh, someone triggered the motion sensor..." ``` @@ -816,10 +813,10 @@ automation: to: "on" action: - parallel: - - service: notify.person1 + - action: notify.person1 data: message: "These messages are sent at the same time!" - - service: notify.person2 + - action: notify.person2 data: message: "These messages are sent at the same time!" ``` @@ -837,16 +834,15 @@ script: - platform: state entity_id: binary_sensor.motion to: "on" - - service: notify.person1 + - action: notify.person1 data: message: "This message awaited the motion trigger" - - service: notify.person2 + - action: notify.person2 data: message: "I am sent immediately and do not await the above action!" ``` -
- +{% warning %} Running {% term actions %} in parallel can be helpful in many cases, but use it with caution and only if you need it. @@ -854,8 +850,7 @@ There are some caveats (see below) when using parallel actions. While it sounds attractive to parallelize, most of the time, just the regular sequential {% term actions %} will work just fine. - -
+{% endwarning %} Some of the caveats of running {% term actions %} in parallel: @@ -906,8 +901,8 @@ By default, a sequence of {% term actions %} will be halted when one of the {% t that sequence encounters an error. The {% term automation %} or script will be halted, an error is logged, and the {% term automation %} or script run is marked as errored. -Sometimes these errors are expected, for example, because you know the service -you call can be problematic at times, and it doesn't matter if it fails. +Sometimes these errors are expected, for example, because you know the action +you perform can be problematic at times, and it doesn't matter if it fails. You can set `continue_on_error` for those cases on such an {% term action %}. The `continue_on_error` is available on all {% term actions %} and is set to @@ -920,12 +915,12 @@ it encounters an error; it will continue to the next {% term action %}. ```yaml - alias: "If this one fails..." continue_on_error: true - service: notify.super_unreliable_service_provider + action: notify.super_unreliable_service_provider data: message: "I'm going to error out..." - alias: "This one will still run!" - service: persistent_notification.create + action: persistent_notification.create data: title: "Hi there!" message: "I'm fine..." @@ -948,13 +943,13 @@ script: # The message will not be sent. - enabled: false alias: "Notify that the ceiling light is being turned on" - service: notify.notify + action: notify.notify data: message: "Turning on the ceiling light!" # This action will run, as it is not disabled - alias: "Turn on the ceiling light" - service: light.turn_on + action: light.turn_on target: entity_id: light.ceiling ``` @@ -1011,7 +1006,7 @@ will not be used by anything. [Script integration]: /integrations/script/ [automations]: /docs/automation/action/ [Alexa/Amazon Echo]: /integrations/alexa/ -[service calls page]: /docs/scripts/service-calls/ +[actions page]: /docs/scripts/perform-actions/ [conditions page]: /docs/scripts/conditions/ [shorthand-template]: /docs/scripts/conditions/#template-condition-shorthand-notation [script variables]: /integrations/script/#configuration-variables diff --git a/source/_docs/scripts/conditions.markdown b/source/_docs/scripts/conditions.markdown index 21f7c96694eb..34c89afb1d26 100644 --- a/source/_docs/scripts/conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -2,7 +2,6 @@ title: "Conditions" description: "Documentation about all available conditions." toc: true -no_toc: true --- Conditions can be used within a {% term script %} or {% term automation %} to prevent further execution. When a condition evaluates true, the script or automation will be executed. If any other value is returned, the script or automation stops executing. A condition will look at the system at that moment. For example, a condition can test if a switch is currently turned on or off. @@ -400,9 +399,9 @@ Note that if only `before` key is used, the condition will be true _from midnigh [sun_trigger]: /docs/automation/trigger/#sun-trigger -
+{% tip %} The sunset/sunrise conditions do not work in locations inside the polar circles, and also not in locations with a highly skewed local time zone. In those cases it is advised to use conditions evaluating the solar elevation instead of the before/after sunset/sunrise conditions. -
+{% endtip %} This is an example of 1 hour offset before sunset: ```yaml @@ -557,11 +556,9 @@ Note that if only `before` key is used, the condition will be `true` *from midni If only `after` key is used, the condition will be `true` from the specified time *until midnight*. Time condition windows can span across the midnight threshold if **both** `after` and `before` keys are used. In the example above, the condition window is from 3pm to 2am. -
- +{% tip %} A better weekday condition could be by using the [Workday Binary Sensor](/integrations/workday/). - -
+{% endtip %} For the `after` and `before` options a time helper (`input_datetime` entity) or another `sensor` entity containing a timestamp with the "timestamp" device @@ -578,13 +575,11 @@ condition: after: sensor.groceries_delivery_time ``` -
- -Please note that the time condition only takes the time into account. If +{% note %} +Note that the time condition only takes the time into account. If a referenced sensor or helper entity contains a timestamp with a date, the date part is fully ignored. - -
+{% endnote %} ## Trigger condition diff --git a/source/_docs/scripts/service-calls.markdown b/source/_docs/scripts/perform-actions.markdown similarity index 59% rename from source/_docs/scripts/service-calls.markdown rename to source/_docs/scripts/perform-actions.markdown index ccd734c536cf..c51c09924168 100644 --- a/source/_docs/scripts/service-calls.markdown +++ b/source/_docs/scripts/perform-actions.markdown @@ -1,24 +1,24 @@ --- -title: "Service calls" -description: "Instructions on how to call services in Home Assistant." +title: "Performing actions" +description: "Instructions on how to perform actions in Home Assistant." --- -Various integrations allow calling {% term services %} when a certain event occurs. The most common one is calling a service when an automation {% term trigger %} happens. But a service can also be called from a {% term script %}, a dashboard or via voice command devices such as Amazon Echo. +Various integrations allow performing {% term actions %} when a certain event occurs. The most common one is performing an action when an automation {% term trigger %} happens. But an action can also be called from a {% term script %}, a dashboard, or via voice command devices such as Amazon Echo. The configuration options to call a configuration are the same between all integrations and are described on this page. Examples on this page will be given as part of an automation integration configuration but different approaches can be used for other integrations too. -
-Use the "Services" tab under Developer Tools to discover available services. -
+{% tip %} +Use the "Actions" tab under **Developer tools** to discover available actions. +{% endtip %} ### The basics -Call the service `homeassistant.turn_on` on the {% term entity %} `group.living_room`. This will turn all members of `group.living_room` on. You can also use `entity_id: all` and it will turn on all possible entities. +Perform the action `homeassistant.turn_on` on the {% term entity %} `group.living_room`. This will turn all members of `group.living_room` on. You can also use `entity_id: all` and it will turn on all possible entities. ```yaml -service: homeassistant.turn_on +action: homeassistant.turn_on entity_id: group.living_room ``` @@ -30,11 +30,11 @@ This is done with the `target` key. A `target` is a map that contains at least one of the following: `area_id`, `device_id`, `entity_id`. Each of these can be a list. The values should be lower-cased. -The following example uses a single service call to turn on the lights in the +The following example uses a single action to turn on the lights in the living room area, 2 additional light devices and 2 additional light entities: ```yaml -service: light.turn_on +action: light.turn_on target: area_id: living_room device_id: @@ -45,28 +45,28 @@ target: - light.landing ``` -### Passing data to the service call +### Passing data to the action -You can also specify other parameters beside the entity to target. For example, the `light.turn_on` service allows specifying the brightness. +You can also specify other parameters beside the entity to target. For example, the `light.turn_on` action allows specifying the brightness. ```yaml -service: light.turn_on +action: light.turn_on entity_id: group.living_room data: brightness: 120 rgb_color: [255, 0, 0] ``` -A full list of the parameters for a service can be found on the documentation page of each integration, in the same way as it's done for the `light.turn_on` [service](/integrations/light/#service-lightturn_on). +A full list of the parameters for an action can be found on the documentation page of each integration, in the same way as it's done for the `light.turn_on` [action](/integrations/light/#action-lightturn_on). -### Use templates to decide which service to call +### Use templates to decide which action to perform -You can use [templating] support to dynamically choose which service to call. For example, you can call a certain service based on if a light is on. +You can use [templating] support to dynamically choose which action to perform. For example, you can perform a certain action based on if a light is on. {% raw %} ```yaml -service: > +action: > {% if states('sensor.temperature') | float > 15 %} switch.turn_on {% else %} @@ -77,25 +77,25 @@ entity_id: switch.ac {% endraw %} -### Using the Services Developer Tool +### Using the Actions developer tool -You can use the Services Developer Tool to test data to pass in a service call. +You can use the **Actions** developer tool to test data to pass in an action. For example, you may test turning on or off a 'group' (See [groups](/integrations/group/) for more info) To turn a group on or off, pass the following info: - Domain: `homeassistant` -- Service: `turn_on` -- Service Data: `{ "entity_id": "group.kitchen" }` +- Action: `turn_on` +- Action data: `{ "entity_id": "group.kitchen" }` ### Use templates to determine the attributes -Templates can also be used for the data that you pass to the service call. +Templates can also be used for the data that you pass to the action. {% raw %} ```yaml -service: thermostat.set_temperature +action: thermostat.set_temperature target: entity_id: > {% if is_state('device_tracker.paulus', 'home') %} @@ -114,7 +114,7 @@ You can use a template returning a native dictionary as well, which is useful if {% raw %} ```yaml -service: climate.set_temperature +action: climate.set_temperature data: > {% if states('sensor.temperature_living') < 19 %} {"hvac_mode": "heat", "temperature": 19 } @@ -127,18 +127,18 @@ data: > ### Use templates to handle response data -Some services may respond with data that can be used in automation. This data is called _service response data_. Service response data +Some actions may respond with data that can be used in automation. This data is called _action response data_. Action response data is typically used for data that is dynamic or large and which may not be suited for use in entity state. -Examples of service response data are upcoming calendar events for the next week or detailed driving directions. +Examples of action response data are upcoming calendar events for the next week or detailed driving directions. -Templates can also be used for handling response data. The service call can specify +Templates can also be used for handling response data. The action can specify a `response_variable`. This is the [variable](/docs/scripts/#variables) -that contains the response data. You can define any name for your `response_variable`. This example calls a service and stores the response in the variable called `agenda`. +that contains the response data. You can define any name for your `response_variable`. This example performs an action and stores the response in the variable called `agenda`. {% raw %} ```yaml -service: calendar.get_events +action: calendar.get_events target: entity_id: calendar.school data: @@ -153,14 +153,14 @@ You may then use the response data in the variable `agenda` in another action in the same script. The example below sends a notification using the response data. -
-Which data fields can be used in a service call depends on the type of notification service that is used. -
+{% important %} +Which data fields can be used in an action depends on the type of notification that is used. +{% endimportant %} {% raw %} ```yaml -service: notify.gmail_com +action: notify.gmail_com data: target: "gduser1@workspacesamples.dev" title: "Daily agenda for {{ now().date() }}" @@ -175,19 +175,19 @@ data: {% endraw %} -### `homeassistant` services +### `homeassistant` actions -There are four `homeassistant` services that aren't tied to any single domain, these are: +There are four `homeassistant` actions that aren't tied to any single domain, these are: - `homeassistant.turn_on` - Turns on an entity (that supports being turned on), for example an `automation`, `switch`, etc. - `homeassistant.turn_off` - Turns off an entity (that supports being turned off), for example an `automation`, `switch`, etc. - `homeassistant.toggle` - Turns off an entity that is on, or turns on an entity that is off (that supports being turned on and off) - `homeassistant.update_entity` - Request the update of an entity, rather than waiting for the next scheduled update, for example [Google travel time] sensor, a [template sensor], or a [light] -Complete service details and examples can be found on the [Home Assistant integration][homeassistant-integration-services] page. +Complete action details and examples can be found on the [Home Assistant integration][homeassistant-integration-actions] page. [templating]: /docs/configuration/templating/ [google travel time]: /integrations/google_travel_time/ [template sensor]: /integrations/template/ [light]: /integrations/light/ -[homeassistant-integration-services]: /integrations/homeassistant#services +[homeassistant-integration-actions]: /integrations/homeassistant#actions diff --git a/source/_docs/tools/dev-tools.markdown b/source/_docs/tools/dev-tools.markdown index bbece8757f52..d43548485192 100644 --- a/source/_docs/tools/dev-tools.markdown +++ b/source/_docs/tools/dev-tools.markdown @@ -14,7 +14,7 @@ Screenshot of Home Assistant's developer tools. | ---------- | ------------------------------------------------------------------- | | YAML | Lets you validate the configuration and trigger a reload or restart | | States | Sets the representation of an entity | -| Services | Calls services from integrations | +| Actions | Performs actions from integrations | | Template | Renders templates | | Events | Fires events | | Statistics | Shows a list of long-term statistic entities | @@ -22,7 +22,7 @@ Screenshot of Home Assistant's developer tools. ## What can I do with Developer Tools? -The Developer Tools is meant for **all** (not just for the developers) to quickly try out things - like calling services, updating states, raising events, and publishing messages in MQTT). It is also a necessary tool for those who write custom automations and scripts by hand. The following describes each of the sections in detail. +The Developer Tools is meant for **all** (not just for the developers) to quickly try out things - like performing actions, updating states, raising events, and publishing messages in MQTT). It is also a necessary tool for those who write custom automations and scripts by hand. The following describes each of the sections in detail. ## YAML tab @@ -48,30 +48,30 @@ For configuration changes to become effective, the configuration must be reloade This section shows all the available entities, their corresponding state and the attribute values. The state and the attribute information is what Home Assistant sees at run time. To update the entity with a new state, or a new attribute value, click on the entity, scroll to the top, and modify the values, and click on “SET STATE” button. -Note that this is the state representation of a device within Home Assistant. That means, it is what Home Assistant sees, and it does not communicate with the actual device in any manner. The updated information can still be used to trigger events, and state changes. To communicate with the actual device, it is recommended to call services in the services section above, instead of updating state. +Note that this is the state representation of a device within Home Assistant. That means, it is what Home Assistant sees, and it does not communicate with the actual device in any manner. The updated information can still be used to trigger events, and state changes. To communicate with the actual device, it is recommended to perform actions in the **Actions** section above, instead of updating state. -For example, changing the `light.bedroom` state from `off` to `on` does not turn on the light. If there is an automation that triggers on the `state` change of the `light.bedroom`, it will be triggered – even though the actual bulb has not turned on. Also, when the bulb state changes – the state information will be overridden (the refresh icon can be used to retrieve the latest information that Home Assistant has). In other words, the changes that are made through the “States” section are temporary, and is recommended to use for testing purposes only. +For example, changing the `light.bedroom` state from `off` to `on` does not turn on the light. If there is an automation that triggers on the `state` change of the `light.bedroom`, it will be triggered – even though the actual bulb has not turned on. Also, when the bulb state changes – the state information will be overridden (the refresh icon can be used to retrieve the latest information that Home Assistant has). In other words, the changes that are made through the “States” section are temporary, and are recommended to use for testing purposes only. The table containing all entities can be filtered for each column. The used search is a wildcard search meaning that if you input "office" in the entity column filter, every entity whose ID matches "\*office\*" will be shown. You can also add your own wildcards in the search input (e.g., "office\*light"). The attribute filter supports separate filters for attribute names and values, separated by a colon ":". So the filter "location:3" will result in the table showing all entities that have an attribute name that contains "location" and whose attribute value contains "3". -## Services tab +## Actions tab -This section is used to call Services that are available in the ServiceRegistry. +This section is used to perform actions that are available in Home Assistant. -The list of services in the “Service” dropdown are automatically populated based on the integrations that are found in the configuration, automation and script files. If a desired service does not exist, it means either the integration is not configured properly or not defined in the configuration, automation or script files. +The list of actions in the **Actions** dropdown are automatically populated based on the integrations that are found in the configuration, automation and script files. If a desired action does not exist, it means either the integration is not configured properly or not defined in the configuration, automation or script files. -When a Service is selected, and if that service requires an `entity_id` to be passed, the “Entity” dropdown will automatically be populated with corresponding entities. +When an action is selected, and if that action requires an `entity_id` to be passed, the **Entity** dropdown will automatically be populated with corresponding entities. -A Service may also require additional input to be passed. It is commonly referred to as “service data”. The service data is accepted in YAML format, and it may be optional depending on the service. +An action may also require additional input to be passed. It is commonly referred to as “action data”. The action data is accepted in YAML format, and it may be optional depending on the action. -When an entity is selected from the Entity dropdown, it automatically populates service data with the corresponding `entity_id`. The service data YAML can then be modified to pass additional \[optional\] parameters. The following is an illustration on how to call a `light.turn_on` service. +When an entity is selected from the Entity dropdown, it automatically populates action data with the corresponding `entity_id`. The action data YAML can then be modified to pass additional \[optional\] parameters. The following is an illustration on how to perform a `light.turn_on` action. To turn on a light bulb, use the following steps: -1. Select `light.turn_on` from the Service dropdown +1. Select `light.turn_on` from the **Action** dropdown. 2. Select the entity (typically the light bulb) from the Entity dropdown (if no entity_id is selected, it turns on ALL lights) -3. If an entity is selected, the service data is populated with basic YAML that will be passed to the service. Additional data can also be passed by updating the YAML as below. +3. If an entity is selected, the action data is populated with basic YAML that will be passed to the action. Additional data can also be passed by updating the YAML as below. ```yaml entity_id: light.bedroom @@ -108,7 +108,7 @@ If there is an automation that handles that event, it will be automatically trig platform: event event_type: event_light_state_changed action: - - service: notify.notify + - action: notify.notify data: message: "Light is turned {{ trigger.event.data.state }}" ``` diff --git a/source/_docs/tools/quick-bar.markdown b/source/_docs/tools/quick-bar.markdown index ba73ba75a75e..df86c08417da 100644 --- a/source/_docs/tools/quick-bar.markdown +++ b/source/_docs/tools/quick-bar.markdown @@ -22,9 +22,9 @@ Type these from anywhere in the application to launch the dialog. | Command Palette | `c` | Remove `>` from start of input to switch to entity filter. | Create [`my`](/integrations/my) link | `m` | Open a new tab to create a my link to the page you are on. -
- The application must have focus for the hotkey to register. If the dialog doesn't launch, try clicking into an empty part of the main content area of Home Assistant and type it again. -
+{% important %} +The application must have focus for the hotkey to register. If the dialog doesn't launch, try clicking into an empty part of the main content area of Home Assistant and type it again. +{% endimportant %} ## Entity filter @@ -57,7 +57,7 @@ Run various commands from anywhere without having to navigate to another view. Type | Available | | ------------- | ------------- | | Navigate | All entries in the sidebar and settings | -| Reload | All currently-supported "Reload {domain}" services.
*(E.g., "Reload Scripts")* | +| Reload | All currently-supported "Reload {domain}" actions.
*(E.g., "Reload Scripts")* | | Server | Restart/Stop | ## My links diff --git a/source/_docs/troubleshooting.markdown b/source/_docs/troubleshooting.markdown deleted file mode 100644 index a6a0d70ec538..000000000000 --- a/source/_docs/troubleshooting.markdown +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: "Troubleshooting installation problems" -description: "Common installation problems and their solutions." ---- - -It can happen that you run into trouble while installing Home Assistant. This page is here to help you solve the most common problems. - -#### pip3: command not found - -This utility should have been installed as part of the Python installation. Check if Python is installed by running `python3 --version`. If it is not installed, [download it here](https://www.python.org/getit/). - -If you are able to successfully run `python3 --version` but not `pip3`, install Home Assistant by running the following command instead: - -```bash -python3 -m pip install homeassistant -``` - -On a Debian system, you can also install python3 by `sudo apt-get install python3`, and pip3 by `sudo apt-get install python3-pip`. - -#### No module named pip - -[Pip](https://pip.pypa.io/en/stable/) should come bundled with the latest Python 3 but is omitted by some distributions. If you are unable to run `python3 -m pip --version` you can install `pip` by [downloading the installer](https://bootstrap.pypa.io/get-pip.py) and running it with Python 3: - -```bash -python3 get-pip.py -``` - -#### No access to the frontend - -In newer Linux distributions the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. - -To fix this you will need to open your machine's firewall for TCP traffic to port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here. - -For UFW systems (Ubuntu, Debian, Raspberry Pi OS, etc.): - -```bash -sudo ufw allow 8123/tcp -``` - -For `iptables` systems (was the default for older distributions): - -```bash -iptables -I INPUT -p tcp --dport 8123 -j ACCEPT -iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere -``` - -### System freezes - -On small systems (such as a Pi2), not directly supported by binaries (Python Wheels) you may run out of memory. -Upon the first run or after an upgrade, Home Assistant uses a lot of resources to (re)compile all the integrations. -If you run out of memory and/or swap memory, your system will freeze. -Increasing swap memory can help: - -```bash -sudo dphys-swapfile swapoff -sudo nano /etc/dphys-swapfile -``` - -Modify the line the sets the swapfile size. Set it equal to your memory or double your current setting: `CONF_SWAPSIZE = 925` then: - -```bash -sudo dphys-swapfile swapon -sudo systemctl restart dphys-swapfile.service -``` diff --git a/source/_docs/troubleshooting_general.markdown b/source/_docs/troubleshooting_general.markdown index 81bdf45a2914..07139cc1a304 100644 --- a/source/_docs/troubleshooting_general.markdown +++ b/source/_docs/troubleshooting_general.markdown @@ -53,7 +53,7 @@ Typically, updates are shown at the top of the **Settings** page. If you don't s ### Resolution -1. On the **System** page, in the top-right corner, select the three dots menu and select **Check for updates**. +1. On the **System** page, in the top-right corner, select the three dots {% icon "mdi:dots-vertical" %} menu and select **Check for updates**. 2. Go to {% my updates title="**System** > **Updates**" %}. - Select the update notification. - - Select the cogwheel, then set **Visible** to active. + - Select the cogwheel {% icon "mdi:cog-outline" %}, then set **Visible** to active. diff --git a/source/_docs/z-wave/controllers.markdown b/source/_docs/z-wave/controllers.markdown index 0028c9083388..bb21087bc5b2 100644 --- a/source/_docs/z-wave/controllers.markdown +++ b/source/_docs/z-wave/controllers.markdown @@ -7,29 +7,50 @@ description: "Extended instructions how to setup Z-Wave." You need to have a compatible Z-Wave stick or module installed. The following devices have been confirmed to work with Z-Wave JS: -
+{% warning %} -Until recently, 700 series Z-Wave Controllers had a bug that could cause the mesh to be flooded on some networks and the controller to become unresponsive. At present, all 700 series controllers share the same firmware and are subject to this bug. It appears that this bug is largely, if not completely, resolved as of firmware version 7.17.2. +The firmwares of 700 and 800 series Z-Wave controllers have several bugs which impact the stability of the mesh and can cause the controller to become unresponsive. Because there is no known firmware version that is completely fixed, it is recommended to choose a firmware based on the following criteria: -Users should upgrade the firmware on all 700 series controllers to version 7.17.2 or greater. Firmware can be upgraded using the below directions: +- 700 series: + - prefer SDK versions 7.17.2 to 7.18.x + - SDK versions 7.19.x are okay + - avoid SDK versions before 7.17.2 + - avoid SDK versions 7.20 to 7.21.3 + +- 800 series + - prefer SDK versions 7.22.x + - SDK versions 7.17.2 to 7.19.x are okay + - avoid SDK versions before 7.17.2 + - avoid SDK versions 7.20 to 7.21.3 + +{% note %} +The SDK version does not have to match the firmware version. If you are unsure which SDK versions a firmware is based on, contact the manufacturer of your device. +{% endnote %} + +{% important %} +You should upgrade the firmware on all 700 and 800 series controllers to a recommended version. +{% endimportant %} + +Firmware can be upgraded using the below directions: - [Upgrade instructions using Linux](https://github.com/kpine/zwave-js-server-docker/wiki/700-series-Controller-Firmware-Updates-(Linux)) - [Upgrade instructions using Windows (Aeotec)](https://aeotec.freshdesk.com/support/solutions/articles/6000252296-update-z-stick-7-with-windows) - [Upgrade instructions using Windows (Zooz)](https://www.support.getzooz.com/kb/article/931-how-to-perform-an-ota-firmware-update-on-your-zst10-700-z-wave-stick/) - [Upgrade instructions using Windows/Linux (Z-Wave.Me)](https://z-wave.me/support/uzbrazberry-firmwares/) -
+{% endwarning %} - 800 series controllers (with some caveats, see notes) - - Zooz 800 Series Z-Wave Long Range S2 Stick (ZST39 LR) - HomeSeer SmartStick G8 + - Zooz 800 Series Z-Wave Long Range S2 Stick (ZST39 LR) - 700 series controllers - Aeotec Z-Stick 7 USB stick (ZWA010) (the EU version is not recommended due to RF performance issues) - - Silicon Labs UZB-7 USB Stick (Silabs SLUSB7000A / SLUSB001A) - - Zooz S2 Stick 700 (ZST10 700) - HomeSeer SmartStick+ G3 - HomeSeer Z-NET G3 + - Silicon Labs UZB-7 USB Stick (Silabs SLUSB7000A / SLUSB001A) + - Zooz S2 Stick 700 (ZST10 700) + - Z-Wave.Me Z-Station - 500 series controllers - Aeotec Z-Stick Gen5 (see note below) @@ -50,9 +71,9 @@ Users should upgrade the firmware on all 700 series controllers to version 7.17. If you are just starting out, we recommend that you purchase a 700 series controller or a Raspberry Pi module. The 700 series controllers are the more recent version (when compared to the 500 series). The 700 series controllers support SmartStart, which allows you to add a device by scanning a QR code. -
- If you're using Home Assistant OS, Supervised, or Container, it's recommended to use a USB stick, not a module. Passing a module through Docker is more complicated than passing a USB stick through. -
+{% tip %} +If you're using Home Assistant OS, Supervised, or Container, it's recommended to use a USB stick, not a module. Passing a module through Docker is more complicated than passing a USB stick through. +{% endtip %} ## Stick alternatives @@ -71,11 +92,9 @@ Z-Wave JS does not support Z-Wave Long Range yet. ### Aeotec Z-Stick -
- -There are [known compatibility issues](https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=245031#p1502030) with older hardware versions of the Aeotec stick not working on the Raspberry Pi 4. Aeotec has released a 2020 hardware revision ZW090-A/B/C Gen5+ with Pi 4 compatibility. Both hardware revisions are still being sold, make informed purchasing decisions if using paired with a Pi 4. - -
+{% note %} +There are [known compatibility issues](https://www.raspberrypi.org/forums/viewtopic.php?f=28&t=245031#p1502030) with older hardware versions of the Aeotec stick not connecting when plugged directly on the Raspberry Pi 4, and requiring a USB Hub to work. Aeotec has released a 2020 hardware revision ZW090-A/B/C Gen5+ with Pi 4 compatibility. Both hardware revisions are still being sold, make informed purchasing decisions if using one paired with a Pi 4. +{% endnote %} It's totally normal for your Z-Wave stick to cycle through its LEDs (Yellow, Blue and Red) while plugged into your system. @@ -127,33 +146,27 @@ sudo systemctl disable hciuart You should also check the README for details on the overlays. You might find it in `/boot/overlays/README` on your SD-card. If it is not there you can find [the official version here](https://github.com/raspberrypi/firmware/blob/master/boot/overlays/README). -
- - It is possible to keep a limited Bluetooth functionality while using Razberry Z-Wave. Check `boot/overlays/README` on `miniuart-bt`. - -
- -
- - `disable-bt` was previously known as `pi3-disable-bt`. If your OS is old, you might need to use this instead. - -
- -
+{% note %} +It is possible to keep a limited Bluetooth functionality while using Razberry Z-Wave. Check `boot/overlays/README` on `miniuart-bt`. +{% endnote %} - If you've installed the Z-Wave.Me Z-Way software. In order to use Z-Wave JS instead of Z-Way, you'll need to ensure you disable it before you install Home Assistant, or you won't be able to access the board. Do this with `sudo /etc/init.d/z-way-server stop; sudo update-rc.d z-way-server disable`. Alternatively, you could use the [Z-Wave.Me](/integrations/zwave_me) integration. +{% note %} +`disable-bt` was previously known as `pi3-disable-bt`. If your OS is old, you might need to use this instead. +{% endnote %} -
+{% note %} +If you've installed the Z-Wave.Me Z-Way software. In order to use Z-Wave JS instead of Z-Way, you'll need to ensure you disable it before you install Home Assistant, or you won't be able to access the board. Do this with `sudo /etc/init.d/z-way-server stop; sudo update-rc.d z-way-server disable`. Alternatively, you could use the [Z-Wave.Me](/integrations/zwave_me) integration. +{% endnote %} #### Setting up a Raspberry Pi Z-Wave module on Home Assistant Yellow This procedure has been tested with the following modules: - - Aeotec Z-Pi 7 Raspberry Pi HAT/Shield - - Z-Wave.Me RaZberry 7 - - Z-Wave.Me RaZberry 7 Pro +- Aeotec Z-Pi 7 Raspberry Pi HAT/Shield +- Z-Wave.Me RaZberry 7 +- Z-Wave.Me RaZberry 7 Pro -1. Make sure the module is properly seated on the Home Assistant Yellow. +1. Make sure the module is properly seated on the Home Assistant Yellow. ![Aeotec Z-Pi 7 on Home Assistant Yellow](/images/docs/z-wave/zpi-7-yellow.jpg). 2. Carefully [close the case](https://yellow.home-assistant.io/guides/add-ssd-existing-installation/#reassembling-top-part) and power up Home Assistant Yellow. 3. Follow the procedure on [setting up a Z-Wave JS server](/integrations/zwave_js/#setting-up-a-z-wave-js-server). diff --git a/source/_faq/python.markdown b/source/_faq/python.markdown deleted file mode 100644 index d46767dd7747..000000000000 --- a/source/_faq/python.markdown +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Python 2" -description: "Support for Python 2" -ha_category: Common ---- - - -There will be no support for Python 2.x. Python 2 will be EOL in [2020](https://www.python.org/dev/peps/pep-0373/#id2) and it doesn't make any sense to support a release which was planned to be retired in 2015. diff --git a/source/_includes/asides/about.html b/source/_includes/asides/about.html index daf0a0ff121a..094a972b38a9 100644 --- a/source/_includes/asides/about.html +++ b/source/_includes/asides/about.html @@ -1,14 +1,13 @@
-

About Home Assistant

+

{% icon "mdi:about-circle-outline" %} About Home Assistant

+

+ Home Assistant is part of the Open Home Foundation {% icon "tabler:external-link" %}. +

diff --git a/source/_includes/asides/categories.html b/source/_includes/asides/categories.html index 639ce3fc038d..94ff7d2fdc81 100644 --- a/source/_includes/asides/categories.html +++ b/source/_includes/asides/categories.html @@ -1,11 +1,11 @@ -
-

Categories

+
+

{% icon "mdi:category" %} Categories

diff --git a/source/_includes/asides/cloud_navigation.html b/source/_includes/asides/cloud_navigation.html index b4d936c0579e..c89e978be9cd 100644 --- a/source/_includes/asides/cloud_navigation.html +++ b/source/_includes/asides/cloud_navigation.html @@ -1,6 +1,6 @@
-

About Home Assistant

+

About Home Assistant