# Table of Contents - [Authentication - Home Assistant](#authentication-home-assistant) - [Authentication providers - Home Assistant](#authentication-providers-home-assistant) - [Multi-factor authentication - Home Assistant](#multi-factor-authentication-home-assistant) - [Automating Home Assistant - Home Assistant](#automating-home-assistant-home-assistant) - [Automation actions - Home Assistant](#automation-actions-home-assistant) - [Automation conditions - Home Assistant](#automation-conditions-home-assistant) - [Backend of Home Assistant - Home Assistant](#backend-of-home-assistant-home-assistant) - [Automation editor - Home Assistant](#automation-editor-home-assistant) - [Automation actions - Home Assistant](#automation-actions-home-assistant) - [Automation modes - Home Assistant](#automation-modes-home-assistant) - [Understanding automations - Home Assistant](#understanding-automations-home-assistant) - [Database - Home Assistant](#database-home-assistant) - [I'm locked out! - Home Assistant](#i-m-locked-out-home-assistant) - [About blueprints - Home Assistant](#about-blueprints-home-assistant) - [Integrating your home batteries - Home Assistant](#integrating-your-home-batteries-home-assistant) - [Quality scale - Home Assistant](#quality-scale-home-assistant) - [Troubleshooting automations - Home Assistant](#troubleshooting-automations-home-assistant) - [Icons - Home Assistant](#icons-home-assistant) - [Integrating your electricity grid - Home Assistant](#integrating-your-electricity-grid-home-assistant) - [Frequently Asked Questions about home energy management - Home Assistant](#frequently-asked-questions-about-home-energy-management-home-assistant) - [Integrating your solar panels - Home Assistant](#integrating-your-solar-panels-home-assistant) - [Tools - Home Assistant](#tools-home-assistant) - [About the blueprint schema - Home Assistant](#about-the-blueprint-schema-home-assistant) - [Integrating individual device energy usage - Home Assistant](#integrating-individual-device-energy-usage-home-assistant) - [Integrating your water usage - Home Assistant](#integrating-your-water-usage-home-assistant) - [Integrating your gas usage - Home Assistant](#integrating-your-gas-usage-home-assistant) - [Understanding Home Energy Management - Home Assistant](#understanding-home-energy-management-home-assistant) - [check_config - Home Assistant](#check-config-home-assistant) - [Creating an automation blueprint - Home Assistant](#creating-an-automation-blueprint-home-assistant) - [Using automation blueprints - Home Assistant](#using-automation-blueprints-home-assistant) - [Labels - Home Assistant](#labels-home-assistant) - [Frontend of Home Assistant - Home Assistant](#frontend-of-home-assistant-home-assistant) - [Grouping your assets - Home Assistant](#grouping-your-assets-home-assistant) - [Categories - Home Assistant](#categories-home-assistant) - [General troubleshooting - Home Assistant](#general-troubleshooting-home-assistant) - [Scenes - Home Assistant](#scenes-home-assistant) - [Quick bar - Home Assistant](#quick-bar-home-assistant) - [Areas - Home Assistant](#areas-home-assistant) - [Developer tools - Home Assistant](#developer-tools-home-assistant) - [Scenes editor - Home Assistant](#scenes-editor-home-assistant) - [Z-Wave adapters - Home Assistant](#z-wave-adapters-home-assistant) - [Entities and domains - Home Assistant](#entities-and-domains-home-assistant) - [Configuration.yaml - Home Assistant](#configuration-yaml-home-assistant) - [Selectors - Home Assistant](#selectors-home-assistant) - [Entity integration platform options - Home Assistant](#entity-integration-platform-options-home-assistant) - [Customizing entities - Home Assistant](#customizing-entities-home-assistant) - [Automation YAML - Home Assistant](#automation-yaml-home-assistant) - [Events - Home Assistant](#events-home-assistant) - [Remote access - Home Assistant](#remote-access-home-assistant) - [Storing secrets - Home Assistant](#storing-secrets-home-assistant) - [Floors - Home Assistant](#floors-home-assistant) - [Automation Templates - Home Assistant](#automation-templates-home-assistant) - [Packages - Home Assistant](#packages-home-assistant) - [Automation Trigger - Home Assistant](#automation-trigger-home-assistant) - [Securing - Home Assistant](#securing-home-assistant) - [Setup basic information - Home Assistant](#setup-basic-information-home-assistant) - [Performing actions - Home Assistant](#performing-actions-home-assistant) - [Working with tables - Home Assistant](#working-with-tables-home-assistant) - [YAML syntax - Home Assistant](#yaml-syntax-home-assistant) - [Conditions - Home Assistant](#conditions-home-assistant) - [Troubleshooting your configuration - Home Assistant](#troubleshooting-your-configuration-home-assistant) - [State and state object - Home Assistant](#state-and-state-object-home-assistant) - [Splitting up the configuration - Home Assistant](#splitting-up-the-configuration-home-assistant) - [Script Syntax - Home Assistant](#script-syntax-home-assistant) - [Glossary - Home Assistant](#glossary-home-assistant) - [Templating - Home Assistant](#templating-home-assistant) - [Documentation - Home Assistant](#documentation-home-assistant) - [Z-Wave - Home Assistant](#z-wave-home-assistant) --- # Authentication - Home Assistant The authentication system secures access to Home Assistant. Login screen[](https://www.home-assistant.io/docs/authentication/#login-screen) -------------------------------------------------------------------------------- You are greeted with a log in screen, asking you for username and password. ![Screenshot of the login screen, when logging in from within the local network](https://www.home-assistant.io/images/docs/authentication/login-outside-local-network.png) User accounts[](https://www.home-assistant.io/docs/authentication/#user-accounts) ---------------------------------------------------------------------------------- When you start Home Assistant for the first time, the _owner_ user account is created. This account has some special privileges and can: * Create and manage other user accounts. * Configure integrations and other settings (coming soon). Warning For the moment, other user accounts will have the same access as the owner account. In the future, non-owner accounts will be able to have restrictions applied. Note If you want to manage users and you’re an owner but you do not see “Users” in your main configuration menu, make sure that **Advanced Mode** is enabled for your user in your profile. ### Your account profile[](https://www.home-assistant.io/docs/authentication/#your-account-profile) Once you’re logged in, you can see the details of your account on the [**User profile**](https://my.home-assistant.io/redirect/profile) page by selecting on the circular at the very bottom of the sidebar. ![Screenshot of the profile page](https://www.home-assistant.io/images/docs/authentication/profile.png) You can: * Change your password. * Enable or disable [multi-factor authentication](https://www.home-assistant.io/docs/authentication/multi-factor-auth/) . * Delete _Refresh Tokens_. These are created when you log in from a device. Delete them if you want to force the device to log out. * Create [Long Lived Access Tokens](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token) so scripts can securely interact with Home Assistant. * Define language and other locale settings. * Log out of Home Assistant. Note Unused refresh tokens will be automatically removed. A refresh token is considered unused if it has not been used for a login within 90 days. If you need a permanent token, then we recommend using [Long Lived Access Tokens](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token) . ### Securing your login[](https://www.home-assistant.io/docs/authentication/#securing-your-login) _Make sure to choose a secure password!_ At some time in the future, you will probably want to access Home Assistant from outside your local network. This means you are also exposed to random black-hats trying to do the same. Treat the password like the key to your house. As an extra level of security, you can turn on [multi-factor authentication](https://www.home-assistant.io/docs/authentication/multi-factor-auth/) . Adding a person to Home Assistant[](https://www.home-assistant.io/docs/authentication/#adding-a-person-to-home-assistant) -------------------------------------------------------------------------------------------------------------------------- If you have administrator rights, you can [add a person to Home Assistant](https://www.home-assistant.io/integrations/person/#adding-a-person-to-home-assistant) and create them a user account. Changing display or username[](https://www.home-assistant.io/docs/authentication/#changing-display-or-username) ---------------------------------------------------------------------------------------------------------------- To learn how to change a display or username, refer to [setting up basic information](https://www.home-assistant.io/docs/configuration/basic/) . Other authentication techniques[](https://www.home-assistant.io/docs/authentication/#other-authentication-techniques) ---------------------------------------------------------------------------------------------------------------------- Home Assistant provides several ways to authenticate. See the [Auth providers](https://www.home-assistant.io/docs/authentication/providers/) section. Troubleshooting[](https://www.home-assistant.io/docs/authentication/#troubleshooting) -------------------------------------------------------------------------------------- ### Authentication failures from 127.0.0.1[](https://www.home-assistant.io/docs/authentication/#authentication-failures-from-127001) If you’re seeing authentication failures from `127.0.0.1` and you’re using the `nmap` device tracker, you should [exclude the Home Assistant IP](https://www.home-assistant.io/integrations/nmap_tracker#exclude) from being scanned. ### Bearer token warnings[](https://www.home-assistant.io/docs/authentication/#bearer-token-warnings) Under the new authentication system you’ll see the following warning logged when the [legacy API password](https://www.home-assistant.io/docs/authentication/providers/#legacy-api-password) is supplied, but not configured in Home Assistant: WARNING (MainThread) [homeassistant.components.http.auth] You need to use a bearer token to access /blah/blah from 192.0.2.4 If you see this, you need to add an [`api_password`](https://www.home-assistant.io/integrations/http/#api_password) to your `http:` configuration. ### Bearer token informational messages[](https://www.home-assistant.io/docs/authentication/#bearer-token-informational-messages) If you see the following, then this is a message for integration developers, to tell them they need to update how they authenticate to Home Assistant. As an end user you don’t need to do anything: INFO (MainThread) [homeassistant.components.http.auth] You need to use a bearer token to access /blah/blah from 192.0.2.4 ### Lost owner password[](https://www.home-assistant.io/docs/authentication/#lost-owner-password) If you lose the password associated with the owner account, you need to [start a new onboarding process](https://www.home-assistant.io/docs/locked_out/#to-prepare-the-system-to-start-a-new-onboarding-process) . ### Error: invalid client id or redirect URL[](https://www.home-assistant.io/docs/authentication/#error-invalid-client-id-or-redirect-url) ![Screenshot of Error: invalid client id or redirect url](https://www.home-assistant.io/images/docs/authentication/error-invalid-client-id.png) You have to use a domain name, not IP address, to remote access Home Assistant otherwise you will get `Error: invalid client id or redirect url` error on the login form. However, you can use the IP address to access Home Assistant in your home network. This is because we only allow an IP address as a client ID when your IP address is an internal network address (e.g., `192.168.0.1`) or loopback address (e.g., `127.0.0.1`). If you don’t have a valid domain name for your Home Assistant instance, you can modify the `hosts` file on your computer to fake one. On Linux edit the `/etc/hosts` file, and add following entry: 12.34.56.78 homeassistant.home Replace `12.34.56.78` with your Home Assistant’s public IP address. This will allow you to open Home Assistant at `http://homeassistant.home:8123/` ### Stuck on loading data[](https://www.home-assistant.io/docs/authentication/#stuck-on-loading-data) Some ad blocking software, such as Wipr, also blocks WebSockets. If you’re stuck on the Loading data screen, try disabling your ad blocker. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/authentication/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/authentication.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fauthentication%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fauthentication%2F%22&in=body "View given feedback for this page") --- # Authentication providers - Home Assistant Caution This is an advanced feature. When you log in, an _auth provider_ checks your credentials to make sure you are an authorized user. Configuring auth providers[](https://www.home-assistant.io/docs/authentication/providers/#configuring-auth-providers) ---------------------------------------------------------------------------------------------------------------------- Warning Home Assistant automatically configures the standard auth providers so you don’t need to specify `auth_providers` in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file unless you are configuring more than one. Specifying `auth_providers` will disable all auth providers that are not listed, so you could reduce your security or create difficulties logging in if it is not configured correctly. If you decide to use `trusted_networks` as your `auth_provider` there won’t be a way to authenticate for a device outside of your listed trusted network. To overcome this ensure you add the default `auth_provider` with `type: homeassistant` back in manually. This will then present you with the default auth login screen when trusted network authentication fails as expected from outside your LAN. Authentication providers are configured in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file under the `homeassistant:` block. If you are moving configuration to packages, this particular configuration must stay within ‘configuration.yaml’. See Issue 16441 in the warning block at the bottom of this page. You can supply more than one, for example: homeassistant: auth_providers: - type: homeassistant - type: trusted_networks trusted_networks: - 192.168.0.0/24 Available auth providers[](https://www.home-assistant.io/docs/authentication/providers/#available-auth-providers) ------------------------------------------------------------------------------------------------------------------ ### Home Assistant auth provider[](https://www.home-assistant.io/docs/authentication/providers/#home-assistant-auth-provider) This is the default auth provider. The first user created is designated as the _owner_ and can create other users. User details are stored in the `[your config]/.storage` directory. All passwords are stored hashed and with a salt, making it almost impossible for an attacker to figure out the password even if they have access to the file. Users can be managed in Home Assistant by the owner. Go to the configuration panel and click on _[Users](https://my.home-assistant.io/redirect/users) _. This is the entry in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) for Home Assistant auth: homeassistant: auth_providers: - type: homeassistant If you don’t specify any `auth_providers` section in the `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file then this provider will be set up automatically. ### Trusted networks[](https://www.home-assistant.io/docs/authentication/providers/#trusted-networks) The trusted networks auth provider defines a range of IP addresses for which no authentication will be required (also known as “allowlisting”). For example, you can allowlist your local network so you won’t be prompted for a password if you access Home Assistant from inside your home. When you log in from one of these networks, you will be asked which user account to use and won’t need to enter a password. Note The [multi-factor authentication module](https://www.home-assistant.io/docs/authentication/multi-factor-auth/) will not participate in the login process if you are using this auth provider. Important You cannot trust a network that you are using in any [trusted\_proxies](https://www.home-assistant.io/integrations/http/#reverse-proxies) . The `trusted_networks` authentication will fail with the message: Your computer is not allowed Here is an example in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) to set up Trusted Networks: homeassistant: auth_providers: - type: trusted_networks trusted_networks: - 192.168.0.0/24 - fd00::/8 #### Configuration Variables[](https://www.home-assistant.io/docs/authentication/providers/#providers-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) trusted\_networks list Required[](https://www.home-assistant.io/docs/authentication/providers/#trusted_networks) A list of IP addresses or an IP network you want allowlisted. It accepts both IPv4 and IPv6 IP address or network trusted\_users map (Optional)[](https://www.home-assistant.io/docs/authentication/providers/#trusted_users) You can also assign which users are available to select when user access login page from certain IP address or network. USER\_ID list | string (Optional)[](https://www.home-assistant.io/docs/authentication/providers/#user_id) List of user ids available to select on this IP address or network. allow\_bypass\_login boolean (Optional, default: false)[](https://www.home-assistant.io/docs/authentication/providers/#allow_bypass_login) You can bypass login page if you have only one user available for selection. #### Trusted users examples[](https://www.home-assistant.io/docs/authentication/providers/#trusted-users-examples) homeassistant: auth_providers: - type: trusted_networks trusted_networks: - 192.168.0.0/24 - 192.168.10.0/24 - fd00::/8 trusted_users: 192.168.0.1: user1_id 192.168.0.0/24: - user1_id - user2_id "fd00::/8": - user1_id - group: system-users First note, for `trusted_users` configuration you need to use `user id`. 1. To find the user ID, in your browser, make sure the URL of your Home Assistant ends in `config/users/`. * For example: `homeassistant:8123/config/users`. 2. Select the user from the list, and copy the ID. * For example: `acbbff56461748718f3650fb914b88c9`. 3. The `trusted_users` configuration will not validate the existence of the user, so please make sure you have put in the correct user id. 4. A trusted user with an IPv6 address must put the IPv6 address in quotes as shown. In the above example, if user try to access Home Assistant from 192.168.0.1, they will have only one user available to choose. They will have two users available if access from 192.168.0.38 (from 192.168.0.0/24 network). If they access from 192.168.10.0/24 network, they can choose from all available users (non-system and active users). Specially, you can use `group: GROUP_ID` to assign all users in certain `user group` to be available to choose. Group and users can be mix and match. #### Skip login page examples[](https://www.home-assistant.io/docs/authentication/providers/#skip-login-page-examples) This is a feature to allow you to bring back some of the experience before the user system was implemented. You can directly jump to the main page if you are accessing from trusted networks, the `allow_bypass_login` is on, and you have ONLY ONE available user to choose from in the login form. If you allow bypass login then your cookie will not be stored and every time you refresh the page in Home Assistant a new login will be created. This is because bypassing the login does not give you the option to save the login. # assuming you have only one non-system user homeassistant: auth_providers: - type: trusted_networks trusted_networks: - 192.168.0.0/24 - 127.0.0.1 - ::1 allow_bypass_login: true - type: homeassistant Assuming you have only the owner created though onboarding process, no other users ever created. The above example configuration will allow you directly access Home Assistant main page if you access from your internal network (192.168.0.0/24) or from localhost (127.0.0.1). If you get a login abort error, then you can change to use Home Assistant Authentication Provider to login, if you access your Home Assistant instance from outside network. ### Command line[](https://www.home-assistant.io/docs/authentication/providers/#command-line) The command line auth provider executes a configurable shell command to perform user authentication. Two environment variables, `username` and `password`, are passed to the command. Access is granted when the command exits successfully (with exit code 0). This provider can be used to integrate Home Assistant with arbitrary external authentication services, from plaintext databases over LDAP to RADIUS. Here is a configuration example: homeassistant: auth_providers: - type: command_line command: /absolute/path/to/command # Optionally, define a list of arguments to pass to the command. #args: ["--first", "--second"] # Uncomment to enable parsing of meta variables (see below). #meta: true When `meta: true` is set in the auth provider’s configuration, your command can write some variables to standard output to populate the user account created in Home Assistant with additional data. These variables have to be printed in the form: name = John Doe group = system-users local_only = true Leading and trailing whitespace, as well as lines starting with `#` are ignored. The following variables are supported. More may be added in the future. * `name`: The real name of the user to be displayed in their profile. * `group`: The user group uses the value `system-admin` for administrator (this is the default) or `system-users` for regular users. * `local_only`: The user can only log in from the local network if you set the value to `true`. If you do not define this variable, the user can log in from anywhere. Stderr is not read at all and just passed through to that of the Home Assistant process, hence you can use it for status messages or suchlike. Note Any leading and trailing whitespace is stripped from usernames before they’re passed to the configured command. For instance, “ hello “ will be rewritten to just “hello”. Note For now, meta variables are only respected the first time a particular user is authenticated. Upon subsequent authentications of the same user, the previously created user object with the old values is reused. Related topics[](https://www.home-assistant.io/docs/authentication/providers/#related-topics) ---------------------------------------------------------------------------------------------- * [Configuration.yaml file](https://www.home-assistant.io/docs/configuration/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/authentication/providers/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/authentication/providers.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fauthentication%2Fproviders%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fauthentication%2Fproviders%2F%22&in=body "View given feedback for this page") --- # Multi-factor authentication - Home Assistant The Multi-factor Authentication (MFA) modules require you to solve a second challenge after you provide your password. A password can be compromised in a number of ways, for example, it can be guessed if it is a simple password. MFA provides a second level of defense by requiring: * something you know, like your username and password, and * something you have, like a one-time password sent to your phone. You can use MFA with any of the other authentication providers. If more than one MFA module is enabled, you can choose one when you log in. You can turn MFA on and off in the [profile page](https://www.home-assistant.io/docs/authentication/#your-account-profile) for your user account. Available MFA modules[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#available-mfa-modules) -------------------------------------------------------------------------------------------------------------------- ### Time-based One-Time Password MFA module[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#time-based-one-time-password-mfa-module) [Time-based One-Time Password](https://en.wikipedia.org/wiki/Time-based_One-time_Password_algorithm) (TOTP) is widely adopted in modern authentication systems. Home Assistant generates a secret key which is synchronized with an app on your phone. Every thirty seconds or so the phone app generates a random six digit number. Because Home Assistant knows the secret key, it knows which number will be generated. If you enter the correct digits, then you’re in. #### Setting up TOTP[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#setting-up-totp) Enable TOTP in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) like this: homeassistant: auth_mfa_modules: - type: totp If no `auth_mfa_modules` configuration section is defined in `configuration.yaml` a TOTP module named “Authenticator app” will be autoloaded. You will need an authenticator app on your phone. We recommend either [Google Authenticator](https://support.google.com/accounts/answer/1066447) or [Authy](https://authy.com/) . Both are available for iOS or Android. After restarting Home Assistant, go to your [Profile](https://my.home-assistant.io/redirect/profile) and there should be a “Multi-factor Authentication Modules” section. Click _Enable_ and a new secret key will be generated. Go to your phone app and enter the key, either by scanning the QR code or typing in the key below the QR code manually. ![Screenshot of setting up multi-factor authentication](https://www.home-assistant.io/images/docs/authentication/mfa.png) Caution Please treat the secret key like a password - never expose it to others. Your phone app will now start generating a different six-digit code every thirty seconds or so. Enter one of these into Home Assistant under the QR code where it asks for a _Code_. Home Assistant and your phone app are now in sync and you can now use the code displayed in the app to log in. #### Using TOTP[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#using-totp) Once TOTP is enabled, Home Assistant requires the latest code from your phone app before you can log in. Note TOTP is _time based_ so it relies on your Home Assistant clock being accurate. If the verification keeps failing, make sure the clock on Home Assistant is correct. ### Notify multi-factor authentication module[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#notify-multi-factor-authentication-module) The Notify MFA module uses the [notify integration](https://www.home-assistant.io/integrations/notify/) to send you an [HMAC-based One-Time Password](https://en.wikipedia.org/wiki/HMAC-based_One-time_Password_algorithm) . It is typically sent to your phone, but can be sent to any destination supported by a `notify` action. You use this password to log in. #### Setting up MFA notify[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#setting-up-mfa-notify) Add Notify MFA to your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file like this: homeassistant: auth_mfa_modules: - type: notify include: - notify_entity #### Configuration Variables[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#multi-factor-auth-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) exclude list (Optional)[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#exclude) The list of notifying entities you want to exclude. include list (Optional)[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#include) The list of notifying entities you want to include. message [template](https://www.home-assistant.io/docs/configuration/templating/) (Optional)[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#message) The message template. # Example configuration, with a message template. homeassistant: auth_mfa_modules: - type: totp name: "Authenticator app" - type: notify message: "I almost forget, to get into my clubhouse, you need to say {}" After restarting Home Assistant, go to your [Profile](https://my.home-assistant.io/redirect/profile) and there should be a “Multi-factor Authentication Modules” section. Click _Enable_ on the _Notify One-Time Password_ option. Try logging out, then logging in again. You will be asked for the six-digit one-time password that was sent to your notify entity. Enter the password to log in. If the validation failed, a new one-time password will be sent again. Note The Notify MFA module can’t tell if the one-time password was delivered successfully. If you don’t get the notification, you won’t be able to log in. You can disable the Notify MFA module by editing or removing the file `[your_config_dir]/.storage/auth_module.notify`. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/authentication/multi-factor-auth/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/authentication/multi-factor-auth.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fauthentication%2Fmulti-factor-auth%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fauthentication%2Fmulti-factor-auth%2F%22&in=body "View given feedback for this page") --- # Automating Home Assistant - Home Assistant Home Assistant contains information about all your devicesA device is a model representing a physical or logical unit that contains entities. and servicesThe term “service” in Home Assistant is used in the sense of an **information service**. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called _service_ to avoid confusion, as it does not come with a piece of hardware.. This information is available for the user in the dashboard and it can be used to trigger automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) . And that’s fun! Automations in Home Assistant allow you to automatically respond to things that happen. You can turn the lights on at sunset or pause the music when you receive a call. If you are just starting out, we recommend that you start with blueprint automations. These are ready-made automations by the community that you only need to configure. ### [Learn about automation blueprints »](https://www.home-assistant.io/docs/automation/using_blueprints/) If you have got the hang of blueprints and would like to explore more, it’s time for the next step. But before you start creating automations, you will need to learn about the automation basics. ### [Learn about automation basics »](https://www.home-assistant.io/docs/automation/basics/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2F%22&in=body "View given feedback for this page") --- # Automation actions - Home Assistant The action of an automation is what is being executed when an automation fires. The action part follows the [script syntax](https://www.home-assistant.io/docs/scripts/) which can be used to interact with anything via other actions or events. For actions, you can specify the `entity_id` that it should apply to and optional parameters (to specify for example the brightness). You can also perform the action to activate [a scene](https://www.home-assistant.io/integrations/scene/) which will allow you to define how you want your devices to be and have Home Assistant perform the right action. automation: # Change the light in the kitchen and living room to 150 brightness and color red. triggers: - trigger: sun event: sunset actions: - action: light.turn_on target: entity_id: - light.kitchen - light.living_room data: brightness: 150 rgb_color: [255, 0, 0] automation 2: # Notify me on my mobile phone of an event triggers: - trigger: sun event: sunset offset: -00:30 variables: notification_action: notify.paulus_iphone actions: # Actions are scripts so can also be a list of actions - action: "{{ notification_action }}" data: message: "Beautiful sunset!" - delay: 0:35 - action: notify.notify data: message: "Oh wow you really missed something great." Conditions can also be part of an action. You can combine multiple actions and conditions in a single action, and they will be processed in the order you put them in. If the result of a condition is false, the action will stop there so any action after that condition will not be executed. automation: - alias: "Office at evening" triggers: - trigger: state entity_id: sensor.office_occupancy to: "on" actions: - action: notify.notify data: message: "Testing conditional actions" - condition: or conditions: - condition: numeric_state entity_id: sun.sun attribute: elevation below: 4 - condition: state entity_id: sensor.office_illuminance below: 10 - action: scene.turn_on target: entity_id: scene.office_at_evening - action: light.turn_on target: "{{ {'entity_id': ['light.office', 'light.office_2']} }}" - action: switch.turn_on target: label_id: "{{ ['office_evening', 'office_after_15'] }}" #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/action/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/action.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Faction%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Faction%2F%22&in=body "View given feedback for this page") --- # Automation conditions - Home Assistant Conditions are an optional part of an automation rule. They can be used to prevent the automation’s actions from being run. After a triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) occurred, all conditions will be checked. The automation will be executed if all conditions return `true`. If any of the conditions returns `false`, the automation won’t start. Conditions look very similar to triggers, but they are very different — a trigger can observe events that may have happened and start an automation. A condition will only see the current state after the automation is started from the trigger. Take the example of a switch being turned on and then off in quick succession. That switch turned on event will start an automation regardless the fact is now off again. By the time the automation checks the conditions from the switch on event, it may already be off again as its current state. This scenario is also known as a race condition. The available conditions for an automation are the same as for the script syntax so see that page for a [full list of available conditions](https://www.home-assistant.io/docs/scripts/conditions/) . Example of using condition: automation: - alias: "Turn on office lights" triggers: - trigger: state entity_id: sensor.office_motion_sensor to: "on" conditions: - or: - condition: numeric_state entity_id: sun.sun attribute: elevation below: 4 - condition: numeric_state entity_id: sensor.office_lux_sensor below: 10 actions: - action: scene.turn_on target: entity_id: scene.office_lights The `condition` option of an automation, also accepts a single condition template directly. For example: automation: - alias: "Turn on office lights" triggers: - trigger: state entity_id: sensor.office_motion_sensor to: "on" conditions: "{{ state_attr('sun.sun', 'elevation') < 4 }}" actions: - action: scene.turn_on target: entity_id: scene.office_lights #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/condition/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/condition.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Fcondition%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Fcondition%2F%22&in=body "View given feedback for this page") --- # Backend of Home Assistant - Home Assistant The backend of Home Assistant is running with [Python 3](https://www.python.org/) . The [Architecture page](https://www.home-assistant.io/developers/architecture/) show the details about the elements running in the background of Home Assistant. To implement a new platform or component, please refer to the [Development documentation](https://www.home-assistant.io/developers/development/) . #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/backend/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/backend.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fbackend%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fbackend%2F%22&in=body "View given feedback for this page") --- # Automation editor - Home Assistant The automation editor is an easy way of creating and editing automations from the UI. This tutorial uses the [Random sensor](https://www.home-assistant.io/integrations/random#sensor) because it generates data (by default, values between 0 and 20). This enables us to walk through the example, even if you do not have any actual sensors connected yet. You could use any other sensor that outputs a numeric value. 1. Go to [**Settings** > **Automations & scenes**](https://my.home-assistant.io/redirect/automations) and in the lower right corner, select the **Create Automation** button. 2. Select **Create new automation**. ![Create automation dialogue box](https://www.home-assistant.io/images/docs/automation-editor/create-automation.png) 3. Select **Add Trigger**, and in the **Search trigger** field, type “num”. * Select **Numeric state**. ![Add trigger](https://www.home-assistant.io/images/docs/automation-editor/add-trigger-to-automation.png) 4. Enter the trigger conditions: * Define the sensor: Under **Entity**, enter “sensor.random\_sensor”. * If the sensor value is above 10, we want the automation to trigger. * In the **Above** field, enter “10”. ![Automation trigger](https://www.home-assistant.io/images/docs/automation-editor/new-trigger.png) 5. Define the action that should happen: * In the **Then do** section, select **Add Action**. ![Add action](https://www.home-assistant.io/images/docs/automation-editor/add_action.png) 6. We want to create a [persistent notification](https://www.home-assistant.io/integrations/persistent_notification/) . * Enter “No” and select **Notifications: send a persistent notification**. ![Automation action](https://www.home-assistant.io/images/docs/automation-editor/send-notification.png) 7. As the message, we want a simple text that is shown as part of the notification. message: Sensor value greater than 10 8. Select **Save**, give your automation a meaningful name, and **Save** again. ![New automation editor](https://www.home-assistant.io/images/docs/automation-editor/new-automation.png) * **Result**: Automations created or edited via the user interface are activated immediately after saving the automation. * To learn more about automations, read the documentation for [Automating Home Assistant](https://www.home-assistant.io/getting-started/automation/) . Troubleshooting missing automations[](https://www.home-assistant.io/docs/automation/editor/#troubleshooting-missing-automations) --------------------------------------------------------------------------------------------------------------------------------- When you’re creating automations using the GUI and they don’t appear in the UI, make sure that you add back `automation: !include automations.yaml` from the default configuration to your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) . Related topics[](https://www.home-assistant.io/docs/automation/editor/#related-topics) --------------------------------------------------------------------------------------- * [Automating home assistant](https://www.home-assistant.io/getting-started/automation/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/editor/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/editor.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Feditor%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Feditor%2F%22&in=body "View given feedback for this page") --- # Automation actions - Home Assistant The automation integration has actions to control automations, like turning automations on and off. This can be useful if you want to disable an automation from another automation. Action [`automation.turn_on`](https://my.home-assistant.io/redirect/developer_call_service?service=automation.turn_on) ----------------------------------------------------------------------------------------------------------------------- This action enables the automation’s triggersA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) . | Data attribute | Optional | Description | | --- | --- | --- | | `entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted. | Action [`automation.turn_off`](https://my.home-assistant.io/redirect/developer_call_service?service=automation.turn_off) ------------------------------------------------------------------------------------------------------------------------- This action disables the automation’s triggersA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) , and optionally stops any currently active actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . | Data attribute | Optional | Description | | --- | --- | --- | | `entity_id` | no | Entity ID of automation to turn off. Can be a list. `none` or `all` are also accepted. | | `stop_actions` | yes | Stop any currently active actions (defaults to true). | Action [`automation.toggle`](https://my.home-assistant.io/redirect/developer_call_service?service=automation.toggle) --------------------------------------------------------------------------------------------------------------------- This action enables the automation’s triggers if they were disabled, or disables the automation’s triggers, and stops any currently active actions, if the triggers were enabled. | Data attribute | Optional | Description | | --- | --- | --- | | `entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted. | Action [`automation.trigger`](https://my.home-assistant.io/redirect/developer_call_service?service=automation.trigger) ----------------------------------------------------------------------------------------------------------------------- This action will trigger the actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) of an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) . By default it bypasses any conditions, though that can be changed via the `skip_condition` attribute. | Data attribute | Optional | Description | | --- | --- | --- | | `entity_id` | no | Entity ID of automation to trigger. Can be a list. `none` or `all` are also accepted. | | `skip_condition` | yes | Whether or not the condition will be skipped (defaults to true). | Action [`automation.reload`](https://my.home-assistant.io/redirect/developer_call_service?service=automation.reload) --------------------------------------------------------------------------------------------------------------------- _This action is only required if you create/edit automations in YAML. Automations via the UI do this automatically._ This action reloads all automations, stopping all currently active automation actions. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/services/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/services.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Fservices%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Fservices%2F%22&in=body "View given feedback for this page") --- # Automation modes - Home Assistant An automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) can be triggered while it is already running. The automation’s `mode` configuration option controls what happens when the automation is triggered while the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) are still running from a previous triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) . | Mode | Description | | --- | --- | | `single` | (Default) Do not start a new run. Issue a warning. | | `restart` | Start a new run after first stopping the previous run. The automation only restarts if the conditions are met. | | `queued` | Start a new run after all previous runs complete. Runs are guaranteed to execute in the order they were queued. Note that subsequent queued automations will only join the queue if any conditions it may have are met at the time it is triggered. | | `parallel` | Start a new, independent run in parallel with previous runs. | ![](https://www.home-assistant.io/images/integrations/script/script_modes.jpg) For both `queued` and `parallel` modes, configuration option `max` controls the maximum number of runs that can be executing and/or queued up at a time. The default is 10. When `max` is exceeded (which is effectively 1 for `single` mode) a log message will be emitted to indicate this has happened. Configuration option `max_exceeded` controls the severity level of that log message. Set it to `silent` to ignore warnings or set it to a [log level](https://www.home-assistant.io/integrations/logger/#log-levels) . The default is `warning`. Example throttled automation[](https://www.home-assistant.io/docs/automation/modes/#example-throttled-automation) ------------------------------------------------------------------------------------------------------------------ Some automations you only want to run every 5 minutes. This can be achieved using the `single` mode and silencing the warnings when the automation is triggered while it’s running. automation: - mode: single max_exceeded: silent triggers: - ... actions: - ... - delay: 300 # seconds (=5 minutes) Example queued[](https://www.home-assistant.io/docs/automation/modes/#example-queued) -------------------------------------------------------------------------------------- Sometimes an automation is doing an action on a device that does not support multiple simultaneous actions. In such cases, a queue can be used. In that case, the automation will be executed once it’s current invocation and queue are done. automation: - mode: queued max: 25 triggers: - ... actions: - ... #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/modes/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/modes.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Fmodes%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Fmodes%2F%22&in=body "View given feedback for this page") --- # Understanding automations - Home Assistant All automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) are made up of a triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) and an actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . Optionally combined with a conditionConditions are an optional part of an automation that will prevent an action from firing if they are not met. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/conditions/) . Take for example the automation: > When Paulus arrives home and it is after sunset: Turn the lights on in the living room. We can break up this automation into the following three parts: (trigger) When Paulus arrives home (condition) and it is after sunset: (action) Turn the lights on in the living room The first part is the [trigger](https://www.home-assistant.io/docs/automation/trigger/) of the automation. Triggers describe eventsEvery time something happens in Home Assistant, an event is fired. There are different types of events, such as state change events, when an action was triggered, or the time changed. All entities produce state change events. Every time a state changes, a state change event is produced. Events can be used to trigger automations or scripts. For example, you can trigger an automation when a light is turned on, then a speaker turns on in that room. Events can also be used to trigger actions in the frontend. For example, you can trigger an action when a button is pressed. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/events/) that should trigger the automation. In this case, it is a person arriving home, which can be observed in Home Assistant using devicesA device is a model representing a physical or logical unit that contains entities./sensorsSensors return information about a thing, for instance the level of water in a tank. [\[Learn more\]](https://www.home-assistant.io/integrations/sensor/) by observing the state of Paulus changing from `not_home` to `home`. The second part is the [condition](https://www.home-assistant.io/docs/automation/condition/) . Conditions are optional tests that can limit an automation to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set. The third part is the [action](https://www.home-assistant.io/docs/automation/action/) , which will be performed when an automation is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene. Note The difference between a trigger and a condition can be confusing as they are very similar. Triggers require an event to happen for the conditions to be evaluated using current state information. Event: Arrive home Condition: After Sunset? Action: Turn lights on Exploring the internal state[](https://www.home-assistant.io/docs/automation/basics/#exploring-the-internal-state) ------------------------------------------------------------------------------------------------------------------- Automations interact directly with the internal state of Home Assistant, so you’ll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. **[Developer Tools > States](https://my.home-assistant.io/redirect/developer_states) ** will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts: | Name | Description | Example | | --- | --- | --- | | Entity ID | Unique identifier for the entity. | `light.living_room` | | State | The current state of the device. | `off` | | Attributes | Extra data related to the device and/or current state. | `brightness` | State changes can be used as the source of triggers and the current state can be used in conditions. To explore the available _actions_ open the [**Developer tools** > **Actions**](https://my.home-assistant.io/redirect/developer_services) . _Actions_ allow changing anything. For example, turn on a light, run a script, or enable a scene. Each _action_ has a domain and a name. For example, the _action_ [`light.turn_on`](https://my.home-assistant.io/redirect/developer_call_service?service=light.turn_on) is capable of turning on any light in your system. Parameters can be passed to an _action_ to indicate, for example, which device to activate or which color to use. Creating automations[](https://www.home-assistant.io/docs/automation/basics/#creating-automations) --------------------------------------------------------------------------------------------------- Now that you’ve got a sneak peek of what is possible, it’s time to get your feet wet and create your first automation. ### [Using the automation editor »](https://www.home-assistant.io/docs/automation/editor/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/basics/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/basics.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Fbasics%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Fbasics%2F%22&in=body "View given feedback for this page") --- # Database - Home Assistant Home Assistant uses databases to store eventsEvery time something happens in Home Assistant, an event is fired. There are different types of events, such as state change events, when an action was triggered, or the time changed. All entities produce state change events. Every time a state changes, a state change event is produced. Events can be used to trigger automations or scripts. For example, you can trigger an automation when a light is turned on, then a speaker turns on in that room. Events can also be used to trigger actions in the frontend. For example, you can trigger an action when a button is pressed. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/events/) and parameters for history and tracking. The default database used is [SQLite](https://www.sqlite.org/) . The database file is stored in your [configuration directory](https://www.home-assistant.io/docs/configuration/#to-find-the-configuration-directory) (e.g., `/home-assistant_v2.db`); however, other databases can be used. If you prefer to run a database server (e.g., PostgreSQL), use the [`recorder`](https://www.home-assistant.io/integrations/recorder/) integration. To work with SQLite database manually from the command-line, you will need an [installation](https://www.sqlitetutorial.net/download-install-sqlite/) of `sqlite3`. Alternatively [DB Browser for SQLite](https://sqlitebrowser.org/) provides a viewer for exploring the database data and an editor for executing SQL commands. First load your database with `sqlite3`: $ sqlite3 home-assistant_v2.db SQLite version 3.13.0 2016-05-18 10:57:30 Enter ".help" for usage hints. sqlite> It helps to set some options to make the output more readable: sqlite> .header on sqlite> .mode column You could also start `sqlite3` and attach the database later. Not sure what database you are working with? Check it, especially if you are going to delete data. sqlite> .databases seq name file --- --------------- ---------------------------------------------------------- 0 main /home/fab/.homeassistant/home-assistant_v2.db ### Schema[](https://www.home-assistant.io/docs/backend/database/#schema) Get all available tables from your current Home Assistant database: sqlite> SELECT sql FROM sqlite_master; ------------------------------------------------------------------------------------- CREATE TABLE event_data ( data_id INTEGER NOT NULL, hash BIGINT, shared_data TEXT, PRIMARY KEY (data_id) ) CREATE TABLE event_types ( event_type_id INTEGER NOT NULL, event_type VARCHAR(64), PRIMARY KEY (event_type_id) ) CREATE TABLE state_attributes ( attributes_id INTEGER NOT NULL, hash BIGINT, shared_attrs TEXT, PRIMARY KEY (attributes_id) ) CREATE TABLE states_meta ( metadata_id INTEGER NOT NULL, entity_id VARCHAR(255), PRIMARY KEY (metadata_id) ) CREATE TABLE statistics_meta ( id INTEGER NOT NULL, statistic_id VARCHAR(255), source VARCHAR(32), unit_of_measurement VARCHAR(255), has_mean BOOLEAN, has_sum BOOLEAN, name VARCHAR(255), mean_type INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (id) ) CREATE TABLE recorder_runs ( run_id INTEGER NOT NULL, start DATETIME NOT NULL, "end" DATETIME, closed_incorrect BOOLEAN NOT NULL, created DATETIME NOT NULL, PRIMARY KEY (run_id) ) CREATE TABLE schema_changes ( change_id INTEGER NOT NULL, schema_version INTEGER, changed DATETIME NOT NULL, PRIMARY KEY (change_id) ) CREATE TABLE statistics_runs ( run_id INTEGER NOT NULL, start DATETIME NOT NULL, PRIMARY KEY (run_id) ) CREATE TABLE events ( event_id INTEGER NOT NULL, event_type CHAR(0), event_data CHAR(0), origin CHAR(0), origin_idx SMALLINT, time_fired CHAR(0), time_fired_ts FLOAT, context_id CHAR(0), context_user_id CHAR(0), context_parent_id CHAR(0), data_id INTEGER, context_id_bin BLOB, context_user_id_bin BLOB, context_parent_id_bin BLOB, event_type_id INTEGER, PRIMARY KEY (event_id), FOREIGN KEY(data_id) REFERENCES event_data (data_id), FOREIGN KEY(event_type_id) REFERENCES event_types (event_type_id) ) CREATE TABLE states ( state_id INTEGER NOT NULL, entity_id CHAR(0), state VARCHAR(255), attributes CHAR(0), event_id SMALLINT, last_changed CHAR(0), last_changed_ts FLOAT, last_updated CHAR(0), last_updated_ts FLOAT, old_state_id INTEGER, attributes_id INTEGER, context_id CHAR(0), context_user_id CHAR(0), context_parent_id CHAR(0), origin_idx SMALLINT, context_id_bin BLOB, context_user_id_bin BLOB, context_parent_id_bin BLOB, metadata_id INTEGER, last_reported_ts FLOAT, PRIMARY KEY (state_id), FOREIGN KEY(old_state_id) REFERENCES states (state_id), FOREIGN KEY(attributes_id) REFERENCES state_attributes (attributes_id), FOREIGN KEY(metadata_id) REFERENCES states_meta (metadata_id) ) CREATE TABLE statistics ( id INTEGER NOT NULL, created CHAR(0), created_ts FLOAT, metadata_id INTEGER, start CHAR(0), start_ts FLOAT, mean FLOAT, min FLOAT, max FLOAT, last_reset CHAR(0), last_reset_ts FLOAT, state FLOAT, sum FLOAT, mean_weight FLOAT, PRIMARY KEY (id), FOREIGN KEY(metadata_id) REFERENCES statistics_meta (id) ON DELETE CASCADE ) CREATE TABLE statistics_short_term ( id INTEGER NOT NULL, created CHAR(0), created_ts FLOAT, metadata_id INTEGER, start CHAR(0), start_ts FLOAT, mean FLOAT, min FLOAT, max FLOAT, last_reset CHAR(0), last_reset_ts FLOAT, state FLOAT, sum FLOAT, mean_weight FLOAT, PRIMARY KEY (id), FOREIGN KEY(metadata_id) REFERENCES statistics_meta (id) ON DELETE CASCADE ) CREATE TABLE sqlite_stat1(tbl,idx,stat) CREATE INDEX ix_event_data_hash ON event_data (hash) CREATE UNIQUE INDEX ix_event_types_event_type ON event_types (event_type) CREATE INDEX ix_state_attributes_hash ON state_attributes (hash) CREATE UNIQUE INDEX ix_states_meta_entity_id ON states_meta (entity_id) CREATE UNIQUE INDEX ix_statistics_meta_statistic_id ON statistics_meta (statistic_id) CREATE INDEX ix_recorder_runs_start_end ON recorder_runs (start, "end") CREATE INDEX ix_statistics_runs_start ON statistics_runs (start) CREATE INDEX ix_events_data_id ON events (data_id) CREATE INDEX ix_events_event_type_id_time_fired_ts ON events (event_type_id, time_fired_ts) CREATE INDEX ix_events_time_fired_ts ON events (time_fired_ts) CREATE INDEX ix_events_context_id_bin ON events (context_id_bin) CREATE INDEX ix_states_context_id_bin ON states (context_id_bin) CREATE INDEX ix_states_attributes_id ON states (attributes_id) CREATE INDEX ix_states_last_updated_ts ON states (last_updated_ts) CREATE INDEX ix_states_metadata_id_last_updated_ts ON states (metadata_id, last_updated_ts) CREATE INDEX ix_states_old_state_id ON states (old_state_id) CREATE INDEX ix_statistics_start_ts ON statistics (start_ts) CREATE UNIQUE INDEX ix_statistics_statistic_id_start_ts ON statistics (metadata_id, start_ts) CREATE UNIQUE INDEX ix_statistics_short_term_statistic_id_start_ts ON statistics_short_term (metadata_id, start_ts) CREATE INDEX ix_statistics_short_term_start_ts ON statistics_short_term (start_ts) CREATE TABLE migration_changes ( migration_id VARCHAR(255) NOT NULL, version SMALLINT NOT NULL, PRIMARY KEY (migration_id) ) To only show the details about the `states` table (since we are using that one in the next examples): sqlite> SELECT sql FROM sqlite_master WHERE type = 'table' AND tbl_name = 'states'; ### Query[](https://www.home-assistant.io/docs/backend/database/#query) The identification of the available columns in the table is done and we are now able to create a query. Let’s list your Top 10 entities: sqlite> .width 30, 10, sqlite> SELECT states_meta.entity_id, COUNT(*) as count FROM states INNER JOIN states_meta ON states.metadata_id = states_meta.metadata_id GROUP BY states_meta.entity_id ORDER BY count DESC LIMIT 10; entity_id count ------------------------------ ---------- sensor.cpu 28874 sun.sun 21238 sensor.time 18415 sensor.new_york 18393 cover.kitchen_cover 17811 switch.mystrom_switch 14101 sensor.internet_time 12963 sensor.solar_angle1 11397 sensor.solar_angle 10440 group.all_switches 8018 ### Delete[](https://www.home-assistant.io/docs/backend/database/#delete) If you don’t want to keep certain entities, you can delete them permanently by using the [actions provided by the recorder](https://www.home-assistant.io/integrations/recorder/#action-purge_entities) . For a more interactive way of working with the database, check the [Data Science Portal](https://data.home-assistant.io/) . #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/backend/database/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/backend/database.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fbackend%2Fdatabase%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fbackend%2Fdatabase%2F%22&in=body "View given feedback for this page") --- # I'm locked out! - Home Assistant The sections below deal with recovering from a situation where you are not able to sign in, or need to recover your data. Forgot username[](https://www.home-assistant.io/docs/locked_out/#forgot-username) ---------------------------------------------------------------------------------- ### Symptom: I’m the owner and I forgot my username[](https://www.home-assistant.io/docs/locked_out/#symptom-im-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[](https://www.home-assistant.io/docs/locked_out/#remedy) 1. Check if the following conditions are met: * you are using the Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users. * 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://support.nabucasa.com/hc/articles/25153288092829) . * If you are using a Home Assistant Yellow, follow these steps: * [to access the console from Windows](https://support.nabucasa.com/hc/articles/25454894609693) * [to access the console from Linux or macOS](https://support.nabucasa.com/hc/articles/25454972435357) . * 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[](https://www.home-assistant.io/docs/locked_out/#forgot-password) ---------------------------------------------------------------------------------- ### Symptom: I’m the owner and I forgot my password[](https://www.home-assistant.io/docs/locked_out/#symptom-im-the-owner-and-i-forgot-my-password) You are the owner or administrator of Home Assistant and forgot your password. ### Remedy: resetting an owner’s password[](https://www.home-assistant.io/docs/locked_out/#remedy-resetting-an-owners-password) 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](https://www.home-assistant.io/docs/locked_out/#to-reset-a-password-while-still-logged-in) * [Reset an owner’s password when logged out](https://www.home-assistant.io/docs/locked_out/#to-reset-an-owners-password-via-console) * [Reset a user’s password, via the container command line](https://www.home-assistant.io/docs/locked_out/#to-reset-a-users-password-via-the-container-command-line) #### To reset a password while still logged in[](https://www.home-assistant.io/docs/locked_out/#to-reset-a-password-while-still-logged-in) The method used to reset a password depends on your user rights: * If you are a regular user without administrator rights, ask the owner to [give you a new password](https://www.home-assistant.io/docs/locked_out/#to-reset-a-users-password-as-an-owner-via-the-web-interface) . * If you are the owner, choose one of the procedures below to reset your password. * You cannot recover an owner password from within Home Assistant. * There is only one owner per system. You cannot add a new owner. * If you are an administrator, add a new user as an administrator and give the new user a password you can remember. 1. Then log out, and log in with this new user. 2. Reset your password via this new administrator account (and then [delete this new account](https://www.home-assistant.io/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[](https://www.home-assistant.io/docs/locked_out/#to-reset-an-owners-password-via-console) Use this procedure only if the following conditions are met: * You can access the Home Assistant console **on the device itself** (not via the SSH terminal from the add-ons). 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: * [Resetting the owner password on Home Assistant Yellow](https://support.nabucasa.com/hc/articles/25455301907997) * If you are using a Home Assistant Green, refer to the following procedure: * [Resetting the owner password on Home Assistant Green](https://support.nabucasa.com/hc/articles/25142896227357) 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: * **Command**: `auth reset --interactive` * This will display a list of users. Select your user and enter a new password when prompted. * **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. 4. You can now log in to Home Assistant using this new password. #### To reset a user’s password, via the container command line[](https://www.home-assistant.io/docs/locked_out/#to-reset-a-users-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. 1. `docker exec -it homeassistant bash` to open to the container command line 2. `hass` to create a default user, if this is your first time using the tool 3. `hass --script auth --config /config change_password existing_user new_password` to change the password 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[](https://www.home-assistant.io/docs/locked_out/#to-reset-a-users-password-as-an-owner-via-the-web-interface) Only the owner can change other user’s passwords. 1. In the bottom left, select your user to go to the [**Profile**](https://my.home-assistant.io/redirect/profile) page and make sure **Advanced Mode** is activated. 2. Go to [**Settings** > **People**](https://my.home-assistant.io/redirect/people) and select the person for which you want to change the password. 3. At the bottom of the dialog box, select **Change Password**. * Note: this is available as the owner, not administrator. 4. Enter the new password, and select **OK**. 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**. Preparing the system to start a new onboarding process[](https://www.home-assistant.io/docs/locked_out/#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. * If you have an external backup with an administrator account of which you still know the login credentials, you can restore that backup. * If you do not have a backup, resetting the device will erase all data. * If you have a Home Assistant Green, [reset the Green](https://support.nabucasa.com/hc/articles/25161225495837) . * If you have a Home Assistant Yellow, [reset the Yellow](https://support.nabucasa.com/hc/articles/25463622043165) . Recovering data for Home Assistant[](https://www.home-assistant.io/docs/locked_out/#recovering-data-for-home-assistant) ------------------------------------------------------------------------------------------------------------------------ Unless your SD card/data is corrupted, you can still get to your files or troubleshoot further. There are a few routes: * Connect a USB keyboard and HDMI monitor directly to the Raspberry Pi. * Remove the SD and access the files from another machine (preferably one running Linux). Connect directly[](https://www.home-assistant.io/docs/locked_out/#connect-directly) ------------------------------------------------------------------------------------ If you’re using a Raspberry Pi, you’re likely going to have to pull the power in order to get your monitor recognized at boot. Pulling power has a risk of corrupting the SD, but you may not have another option. Most standard USB keyboards should be recognized easily. Once you’re connected, you’ll see a running dmesg log. Hit the enter key to interrupt the log. Sign in as “root”. There is no password. You will then be at the Home Assistant CLI, where you can run the custom commands. These are the same as you would run using the SSH add-on but without using `ha` in front of it. For example: * `core logs` for Home Assistant Core log * `supervisor logs` for supervisor logs * `host reboot` to reboot the host * `dns logs` for checking DNS * etc (typing `help` will show more) Accessing files from the SD/HDD[](https://www.home-assistant.io/docs/locked_out/#accessing-files-from-the-sdhdd) ----------------------------------------------------------------------------------------------------------------- ### Remove the SD and access the files from another computer[](https://www.home-assistant.io/docs/locked_out/#remove-the-sd-and-access-the-files-from-another-computer) The files are on an EXT4 partition (`hassos-data`) and the path is `/mnt/data/supervisor`. These are easily accessed using another Linux machine with EXT support. For Windows or macOS you will need third party software. Below are some options. * Windows: [https://www.diskinternals.com/linux-reader/](https://www.diskinternals.com/linux-reader/) (read-only access to the SD) * macOS: [https://osxfuse.github.io/](https://osxfuse.github.io/) Deleting a user[](https://www.home-assistant.io/docs/locked_out/#deleting-a-user) ---------------------------------------------------------------------------------- You need to be an owner or have administrator rights to delete a user. 1. Go to [**Settings** > **People**](https://my.home-assistant.io/redirect/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**. Related topics[](https://www.home-assistant.io/docs/locked_out/#related-topics) -------------------------------------------------------------------------------- * [Listing all usernames via command line](https://www.home-assistant.io/common-tasks/os/#listing-all-users-from-the-command-line) Related links[](https://www.home-assistant.io/docs/locked_out/#related-links) ------------------------------------------------------------------------------ * [Reset the Yellow](https://support.nabucasa.com/hc/articles/25463622043165) * [Reset the Green](https://support.nabucasa.com/hc/articles/25161225495837) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/locked_out/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/locked_out.md "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Flocked_out%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Flocked_out%2F%22&in=body "View given feedback for this page") --- # About blueprints - Home Assistant This section gives a high-level introduction to blueprints. To view a description of the YAML-schema used to create a valid blueprint, refer to the section [About the blueprint schema](https://www.home-assistant.io/docs/blueprint/schema/) . What is a blueprint?[](https://www.home-assistant.io/docs/blueprint/#what-is-a-blueprint) ------------------------------------------------------------------------------------------ A blueprint is a scriptScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) , automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) or [template entity](https://www.home-assistant.io/integrations/template/) configuration with certain parts marked as configurable. This allows you to create different scripts, automations or template entities based on the same blueprint. Imagine you want to control lights based on motion. A blueprint provides the generic automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) framework, while letting you select one specific motion sensor as a triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) , and the exact light to control. This blueprint makes it possible to create two automations. Each automation has their own configuration and act completely independently. Yet, they share some basic automation configuration so that you do not have to set this up every time. Automations inherit from blueprints, which means that changes made to a blueprint will be reflected in all automations based on that blueprint the next time the automations are reloaded. This occurs as part of Home Assistant starting. To manually reload the automations, go to [**Developer tools** > **YAML**](https://my.home-assistant.io/redirect/server_controls) and reload the automations. Blueprints are shared by the community in the [blueprint community forum](https://www.home-assistant.io/get-blueprints) . Related topics[](https://www.home-assistant.io/docs/blueprint/#related-topics) ------------------------------------------------------------------------------- * [About the blueprint schema](https://www.home-assistant.io/docs/blueprint/schema/) * [About the blueprint selectors](https://www.home-assistant.io/docs/blueprint/selectors/) * [Using blueprints in automations](https://www.home-assistant.io/docs/automation/using_blueprints/) * [Tutorial: create an automation blueprint](https://www.home-assistant.io/docs/blueprint/tutorial/) Related links[](https://www.home-assistant.io/docs/blueprint/#related-links) ----------------------------------------------------------------------------- * [Blueprint community forum](https://www.home-assistant.io/get-blueprints) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/blueprint/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/blueprint.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fblueprint%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fblueprint%2F%22&in=body "View given feedback for this page") --- # Integrating your home batteries - Home Assistant A home battery allows homes to store energy when you are either producing more solar power than you’re using, or store energy from the grid if the current price is low. Home Assistant allows you to track how much energy flows from/to your battery. Hardware[](https://www.home-assistant.io/docs/energy/battery/#hardware) ------------------------------------------------------------------------ Home Assistant will need to know the amount of energy flowing from/to your batteries. This data can be tracked in various ways. ### Provided by the battery[](https://www.home-assistant.io/docs/energy/battery/#provided-by-the-battery) Some battery vendors have an API to integrate the data into your Home Assistant instance. An example is [Tesla Powerwall](https://www.home-assistant.io/integrations/powerwall/) . ### Using a CT clamp sensor[](https://www.home-assistant.io/docs/energy/battery/#using-a-ct-clamp-sensor) Current transformer (CT) clamp sensors measure your energy usage by looking at the current passing through an electrical wire. This makes it possible to calculate the energy usage. In Home Assistant we have support for off-the-shelf CT clamp sensors or you can build your own. * The off-the-shelf solution that we advise is the [Shelly EM](https://www.shelly.com/products/shelly-em-50a-clamp-1?tracking=A7FsiPIfUWsFpnfKHa8SRyUYLXjr2hPq) . The device has a local API, updates are pushed to Home Assistant and it has a high quality [integration](https://www.home-assistant.io/integrations/shelly/) . * You can build your own using ESPHome’s [CT Clamp Current sensor](https://esphome.io/components/sensor/ct_clamp/) or energy meter sensors like the [ATM90E32](https://esphome.io/components/sensor/atm90e32/) . For the DIY route, check out [this video by digiblur](https://www.youtube.com/watch?v=n2XZzciz0s4) to get started. * Using a Raspberry Pi, you can use a CT clamp HAT from LeChacal called [RPICT hats](https://lechacal.com/docs/RPICT/Raspberrypi_Current_and_Temperature_Sensor_Adaptor/) . They can be stacked to expand the number of lines to monitor. They also provide Active, Apparent, and Reactive power and power factor for single-phase and three-phase installations. They integrate with Home Assistant using MQTT. _Attention! Installing CT clamp sensor devices requires opening your electrical cabinet. This work should be done by someone familiar with electrical wiring and may require a licensed professional in some regions. Your qualified installer will know how to do this._ _Disclaimer: Some links in this section are affiliate links._ #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/battery/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/battery.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Fbattery%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Fbattery%2F%22&in=body "View given feedback for this page") --- # Quality scale - Home Assistant The integration quality scale is a framework for Home Assistant to grade integrations based on user experience, features, code quality, and developer experience. To grade this, the project has come up with a set of tiers, each with its own set of criteria. Scaled tiers[](https://www.home-assistant.io/docs/quality_scale/#scaled-tiers) ------------------------------------------------------------------------------- There are 4 scaled tiers, bronze, silver, gold, and platinum. To reach a tier, the integration must fulfill all rules of that tier and the tiers below. These tiers are defined as follows. ### 🥉 Bronze[](https://www.home-assistant.io/docs/quality_scale/#-bronze) The bronze tier is the baseline standard and requirement for all new integrations. It meets the minimum requirements in code quality, functionality, and user experience. It complies with the fundamental expectations and provides a reliable foundation for users to interact with their devices and services. The documentation provides guidelines for setting up the integration directly from the Home Assistant user interface. From a technical perspective, this integration has been reviewed to comply with all baseline standards, which we require for all new integrations, including automated tests for setting up the integration. The bronze tier has the following characteristics: * Can be easily set up through the UI. * The source code adheres to basic coding standards and development guidelines. * Automated tests that guard this integration can be configured correctly. * Offers basic end-user documentation that is enough to get users started step-by-step easily. ### 🥈 Silver[](https://www.home-assistant.io/docs/quality_scale/#-silver) The silver tier builds upon the _Bronze_ level by improving the reliability and robustness of integrations, ensuring a solid runtime experience. It ensures an integration handles errors properly, such as when authentication to a device or service fails, handles offline devices, and other errors. The documentation for these integrations provides information on what is available in Home Assistant when this integration is used, as well as troubleshooting information when issues occur. This integration has one or more active code owners who help maintain it to ensure the experience on this level lasts now and in the future. The silver tier has the following characteristics: * Provides everything the _Bronze_ tier has. * Provides a stable user experience under various conditions. * Has one or more active code owners who help maintain the integration. * Correctly and automatically recover from connection errors or offline devices, without filling log files and without unnecessary messages. * Automatically triggers re-authentication if authentication with the device or service fails. * Offers detailed documentation of what the integration provides and instructions for troubleshooting issues. ### 🥇 Gold[](https://www.home-assistant.io/docs/quality_scale/#-gold) The gold standard in integration user experience, providing extensive and comprehensive support for the integrated devices & services. A gold-tier integration aims to be user-friendly, fully featured, and accessible to a wider audience. When possible, devices are automatically discovered for an easy and seamless setup, and their firmware/software can be directly updated from Home Assistant. All provided devices and entities are named logically and fully translatable, and they have been properly categorized and enabled for long-term statistical use. The documentation for these integrations is extensive, and primarily aimed toward end-users and understandable by non-technical consumers. Besides providing general information on the integration, the documentation provides possible example use cases, a list of compatible devices, a list of described entities the integration provides, and extensive descriptions and usage examples of available actions provided by the integration. The use of example automations, dashboards, available Blueprints, and links to additional external resources, is highly encouraged as well. The integration provides means for debugging issues, including downloading diagnostic information and documenting troubleshooting instructions. If needed, the integration can be reconfigured via the UI. From a technical perspective, the integration needs to have full automated test coverage of its codebase to ensure the set integration quality is maintained now and in the future. All integrations that have devices in the Works with Home Assistant program are at least required to have this tier. The gold tier has the following characteristics: * Provides everything the _Silver_ tier has. * Has the best end-user experience an integration can offer; streamlined and intuitive. * Can be automatically discovered, simplifying the integration setup. * Integration can be reconfigured and adjusted. * Supports translations. * Extensive documentation, aimed at non-technical users. * It supports updating the software/firmware of devices through Home Assistant when possible. * The integration has automated tests covering the entire integration. * Required level for integrations providing devices in the Works with Home Assistant program. ### 🏆 Platinum[](https://www.home-assistant.io/docs/quality_scale/#-platinum) Platinum is the highest tier an integration can reach, the epitome of quality within Home Assistant. It not only provides the best user experience but also achieves technical excellence by adhering to the highest standards, supreme code quality, and well-optimized performance and efficiency. The platinum tier has the following characteristics: * Provides everything the _Gold_ tier has. * All source code follows all coding and Home Assistant integration standards and best practices and is fully typed with type annotations and clear code comments for better code clarity and maintenance. * A fully asynchronous integration code base ensures efficient operation. * Implements efficient data handling, reducing network and CPU usage. Special tiers[](https://www.home-assistant.io/docs/quality_scale/#special-tiers) --------------------------------------------------------------------------------- There are 4 special tiers that are used for integrations that don’t have a place on the scaled tier list. This is because they are either an internal part of Home Assistant CoreHome Assistant Core is the Python program at the heart of Home Assistant. It is part of all installation types. It can be installed standalone (without Home Assistant Supervisor) as a container using Docker (this is typically referred to as the Home Assistant Container installation type). For development, Core can also be run using a Virtual Environment (previously referred as the Home Assistant Core installation type). For production setup, the Home Assistant Core installation type is deprecated., they are not in Home Assistant CoreHome Assistant Core is the Python program at the heart of Home Assistant. It is part of all installation types. It can be installed standalone (without Home Assistant Supervisor) as a container using Docker (this is typically referred to as the Home Assistant Container installation type). For development, Core can also be run using a Virtual Environment (previously referred as the Home Assistant Core installation type). For production setup, the Home Assistant Core installation type is deprecated. at all, or they don’t meet the minimum requirements to be graded against the scaled tiers. The special tiers are defined as follows. ### ❓ No score[](https://www.home-assistant.io/docs/quality_scale/#-no-score) These integrations can be set up through the Home Assistant user interface. The _No score_ designation doesn’t imply that they are bad or buggy, instead, it indicates that they haven’t been assessed according to the quality scale or that they need some maintenance to reach the now-considered minimum _Bronze_ standard. The _No score_ tier cannot be assigned to new integrations, as they are required to have at least a _Bronze_ level when introduced. The Home Assistant project encourages the community to help update these integrations without a score to meet at least the _Bronze_ level requirements. Characteristics: * Not yet scored or lacks sufficient information for scoring. * Can be set up via the UI, but may need enhancements for a better experience. * May function correctly, but hasn’t been verified against current standards. * Documentation most often provides only basic setup steps. ### 🏠 Internal[](https://www.home-assistant.io/docs/quality_scale/#-internal) The internal tier is assigned to integrations used internally by Home Assistant. These integrations provide basic components and building blocks for the Home Assistant Core program or for other integrations to build on top of it. Internal integrations are maintained by the Home Assistant project and subjected to strict architectural design procedures. Characteristics: * Internal, built-in building blocks of the Home Assistant Core program. * Provides building blocks for other integrations to use and build on top of. * Maintained by the Home Assistant project. ### 💾 Legacy[](https://www.home-assistant.io/docs/quality_scale/#-legacy) Legacy integrations are older integrations that have been part of Home Assistant for many years, possibly since its inception. They can only be configured through YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) files and often lack active maintainers (code owners). These integrations might be complex to set up and do not adhere to current/modern end-user expectations in their use and features. The Home Assistant project encourages the community to help migrate these integrations to the UI and update them to meet modern standards, making these integrations accessible to everyone. Characteristics: * Complex setup process; only configurable via YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) , without UI-based setup. * May lack active code ownership and maintenance. * Could be missing recent updates or bug fixes. * Documentation may still be aimed at developers. ### 📦 Custom[](https://www.home-assistant.io/docs/quality_scale/#-custom) Custom integrations are developed and distributed by the community, and offer additional functionalities and support for devices and services to Home Assistant. These integrations are not included in the official Home Assistant releases and can be installed manually or via third-party tools like HACS (Home Assistant Community Store). The Home Assistant project does not review, security audit, maintain, or support third-party custom integrations. Users are encouraged to exercise caution and review the custom integration’s source and community feedback before installation. Developers are encouraged and invited to contribute their custom integration to the Home Assistant project by aligning them with the integration quality scale and submitting them for inclusion. Characteristics: * Not included in the official Home Assistant releases. * Manually installable or installable via community tools, like HACS. * Maintained by individual developers or community members. * User experience may vary widely. * Functionality, security, and stability can vary widely. * Documentation may be limited. Related links[](https://www.home-assistant.io/docs/quality_scale/#related-links) --------------------------------------------------------------------------------- * [Developer documentation on the integration quality scale](https://developers.home-assistant.io/docs/core/integration-quality-scale/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/quality_scale/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/quality_scale.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fquality_scale%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fquality_scale%2F%22&in=body "View given feedback for this page") --- # Troubleshooting automations - Home Assistant Automations and scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) can be debugged in a few different ways. You can [test run](https://www.home-assistant.io/docs/automation/troubleshooting/#testing-your-automation) the full sequence of actions, or test each condition and action separately. [Traces](https://www.home-assistant.io/docs/automation/troubleshooting/#traces) let you see details of every step after an automation is run. For complicated automations with templatesA template is an automation definition that can include variables for the action or data from the trigger values. This allows automations to generate dynamic actions. [\[Learn more\]](https://www.home-assistant.io/docs/automation/templating/) , see the section [testing templates](https://www.home-assistant.io/docs/automation/troubleshooting/#testing-templates) . Testing your automation[](https://www.home-assistant.io/docs/automation/troubleshooting/#testing-your-automation) ------------------------------------------------------------------------------------------------------------------ Many automations can be tested directly in the automation editor UI. ### Running the entire automation[](https://www.home-assistant.io/docs/automation/troubleshooting/#running-the-entire-automation) In the three dots menu in the automation list or automation editor UI, select the **Run actions** button. This will execute all of the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) , while skipping all triggersA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) and conditionsConditions are an optional part of an automation that will prevent an action from firing if they are not met. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/conditions/) . This lets you test the full sequence of actions, as if the automation was triggered and all conditions were true. Note that any [trigger ID](https://www.home-assistant.io/docs/automation/trigger/#trigger-id) used in your triggers will not be active when you test this way. The Trigger ID or any data passed by in the `trigger` data in conditions or actions can’t be tested directly this way. You can also trigger an automation manually. This can test the conditions as if the automation was triggered by an event. Navigate to [**Developer tools** > **Actions**](https://my.home-assistant.io/redirect/developer_services) . In the **Action** drop-down, select **Automation: Trigger**, then **Choose entity** to select the automation you are testing. Toggle whether to skip the conditions, then **Perform action**. If needed, additional `trigger` or other data can be added in the YAML view for testing. The [trigger](https://www.home-assistant.io/docs/automation/trigger/) page has more information about data within the trigger. Testing with complex triggers, conditions, and variables can be difficult. Note that using the **Run actions** button will skip all triggers and conditions, while **Developer Tools** can be used with or without checking conditions. ### Running individual actions or conditions[](https://www.home-assistant.io/docs/automation/troubleshooting/#running-individual-actions-or-conditions) In the automation editor UI, each conditionConditions are an optional part of an automation that will prevent an action from firing if they are not met. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/conditions/) and actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) can be tested individually. Select the three dots menu, then the **Test** button. * Testing a condition will highlight it to show whether the condition passed at the moment it was tested. If all conditions pass, then the automation will run when triggered. Testing building blocks like an **and** condition will report whether the whole block registers as true or false, or you can test individual conditions within the building block. * Testing an action block will run that block immediately. Note that complex automations that depend on previous blocks, such as trigger IDs, variables in templates, or action calls that return data to use in subsequent blocks, cannot be tested this way. If you are writing automations in YAML, it is also useful to go to [**Developer tools** > **YAML**](https://my.home-assistant.io/redirect/server_controls) \*\* and in the Configuration validation section, select the **Check configuration** button. This is to make sure there are no syntax errors before restarting Home Assistant. In order for **Check configuration** to be visible, you must enable **Advanced Mode** on [your user profile](https://my.home-assistant.io/redirect/profile) . Traces[](https://www.home-assistant.io/docs/automation/troubleshooting/#traces) -------------------------------------------------------------------------------- When an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) is run, all steps are recorded and a trace is made. From the UI, open **Settings**, which is located in the sidebar, then select **Automations & Scenes** to go to the automation editor or click this button directly: [![](https://my.home-assistant.io/badges/automations.svg)](https://my.home-assistant.io/redirect/automations) From the automation editor UI, or in the automations list in the three dots menu, select **Traces**. Alternatively, select an automation entry shown under **Activity**. ![Automation tracing example](https://www.home-assistant.io/images/integrations/automation/automation-tracing.png) The above screenshot shows a previous run of an automation. The automation is displayed using an interactive graph, highlighting which path the automation took. Each node in the graph can be clicked to view the details on what happened with the automation during that specific step. It traces the complete run of an automation. The right side of the trace screen has tabs with more information: * **Step Details** shows data and results of the step that is currently highlighted. * **Automation Config** shows the full YAML configuration at the time the automation was run. * **Trace Timeline**, shown in the screenshot above, lists the steps that were executed and their timing. * **Related activity**, shows the activity for all the entries related to the specific trace. * **Blueprint Config** will only be shown if the automation was created from a blueprintA blueprint is a [script](https://www.home-assistant.io/getting-started/concepts-terminology/#scripts) , [automation](https://www.home-assistant.io/getting-started/concepts-terminology/#automation) , or [template](https://www.home-assistant.io/integrations/template/) entity configuration with certain parts marked as configurable. This allows users to create multiple scripts, automations or template entities based on the same blueprint, with each having its own configuration-specific settings. Blueprints are shared by the community on the [blueprints exchange](https://community.home-assistant.io/c/53) in the forum. [\[Learn more\]](https://www.home-assistant.io/docs/blueprint/) . The top bar shows the date and time the automation was triggered. Use the left and right arrows to view previous runs of the automation. Automations created in YAML must have an [`id`](https://www.home-assistant.io/docs/automation/yaml/#migrating-your-yaml-automations-to-automationsyaml) assigned in order for debugging traces to be stored. ### Trace configuration[](https://www.home-assistant.io/docs/automation/troubleshooting/#trace-configuration) The last 5 traces are recorded for all automations. It is possible to change this by adding the following code to your automation. trace: stored_traces: 20 Testing templates[](https://www.home-assistant.io/docs/automation/troubleshooting/#testing-templates) ------------------------------------------------------------------------------------------------------ If your automation uses [templates](https://www.home-assistant.io/docs/configuration/templating/) in any part, you can do the following to make sure it works as expected: 1. Go to [**Developer tools** > **Template**](https://my.home-assistant.io/redirect/developer_template) tab. 2. Create all variables (sources) required for your template as described at the end of [this](https://www.home-assistant.io/docs/configuration/templating/#processing-incoming-data) paragraph. 3. Copy your template code and paste it in Template editor straight after your variables. 4. If necessary, change your sources’ value and check if the template works as you want and does not generate any errors. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/troubleshooting/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/troubleshooting.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Ftroubleshooting%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Ftroubleshooting%2F%22&in=body "View given feedback for this page") --- # Icons - Home Assistant ![Material Design Icons](https://www.home-assistant.io/images/frontend/mdi.png) Home Assistant utilizes the community-driven [Material Design Icons](https://pictogrammers.com/library/mdi/) (MDI) project for icons in the frontend. The icon library is a superset of the base icon library provided by Google and contains thousands of community-made icons for very specific applications, industries, and use-cases. Default icons[](https://www.home-assistant.io/docs/frontend/icons/#default-icons) ---------------------------------------------------------------------------------- Every entity in Home Assistant has a default icon assigned to it. There are way too many to list out here, but you’ll see them in your dashboard. You can [customize any of your entities](https://www.home-assistant.io/docs/configuration/customizing-devices/) to change the icons displayed to you. Finding icons[](https://www.home-assistant.io/docs/frontend/icons/#finding-icons) ---------------------------------------------------------------------------------- ### Icon picker[](https://www.home-assistant.io/docs/frontend/icons/#icon-picker) The most common way you can find icons is by using the icon picker built right into Home Assistant. Select the **Icon** field when customizing an entity and start typing. The list will filter to icons that match your search criteria. You can also scroll through all available icons when the field is empty. ![Icon Picker in Home Assistant](https://www.home-assistant.io/images/screenshots/icon-picker.png) 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. For more detailed steps on customizing entities, including their icon, refer to [customizing entities](https://www.home-assistant.io/docs/configuration/customizing-devices/) . ### Material design icons picker browser extension[](https://www.home-assistant.io/docs/frontend/icons/#material-design-icons-picker-browser-extension) The easiest way to browse and find icons outside of Home Assistant is with the official [Material Design Icons Picker](https://github.com/Pictogrammers/MaterialDesignIcons-Picker) browser extension. The extension is available for Chrome, Firefox, and Edge and is maintained by the MDI team. ![Material Design Icons Picker](https://www.home-assistant.io/images/screenshots/mdi-picker.png) 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. ### Material design icons on the Pictogrammers website[](https://www.home-assistant.io/docs/frontend/icons/#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. 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. Suggesting or contributing new icons[](https://www.home-assistant.io/docs/frontend/icons/#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. 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”) ### Suggesting a new icon[](https://www.home-assistant.io/docs/frontend/icons/#suggesting-a-new-icon) If you have an idea for an icon that isn’t currently in the library, but are not interested in creating it yourself, [open a new icon suggestion](https://github.com/Templarian/MaterialDesign/issues/new?assignees=&labels=Icon+Request&template=1_icon_request.yml) . ### Contributing a New Icon[](https://www.home-assistant.io/docs/frontend/icons/#contributing-a-new-icon) If you want to contribute a new icon to the library, familiarize yourself with the [System icons guidelines](https://material.io/design/iconography/system-icons.html#design-principles) in the Material Design system. Then create your icon and [submit it to the Pictogrammers team for review](https://github.com/Templarian/MaterialDesign/issues/new?assignees=&labels=Icon+Request%2CContribution&template=2_contribution.yml) . #### Tips for creating new icons[](https://www.home-assistant.io/docs/frontend/icons/#tips-for-creating-new-icons) * Really pay attention to [Material Design guidelines](https://material.io/design/iconography/system-icons.html#design-principles) . * Keep in mind that icons are meant to be contextual, not literal. * When it comes to little details, less is more. * If you’re unsure, open an issue on their GitHub. They’re more than happy to help you! * Not all icons make it into the library and that is okay! ### Suggesting an icon alias[](https://www.home-assistant.io/docs/frontend/icons/#suggesting-an-icon-alias) Sometimes an icon exists, but you aren’t able to find it with the terms you were searching for. If this has ever happened to you, please [open an issue with the Pictogrammers team to suggest new aliases](https://github.com/Templarian/MaterialDesign/issues/new?assignees=&labels=Alias&template=4_alias.yml) that can be added to existing icons. Related topics[](https://www.home-assistant.io/docs/frontend/icons/#related-topics) ------------------------------------------------------------------------------------ * [Frontend](https://www.home-assistant.io/docs/frontend/) * [Dashboard cards](https://www.home-assistant.io/dashboards/cards/) * [Customizing entities](https://www.home-assistant.io/docs/configuration/customizing-devices/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/frontend/icons/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/frontend/icons.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ffrontend%2Ficons%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ffrontend%2Ficons%2F%22&in=body "View given feedback for this page") --- # Integrating your electricity grid - Home Assistant Energy management is all about knowing how much energy you’re consuming, where it’s coming from and where it’s going. Almost all houses are connected to the electricity grid which provides the energy your home will need. The energy usage is being tracked by your energy meter and is billed to you by your energy provider. Energy prices can differ based on a schedule or change according to market price. ![Graphic showing energy flowing from the grid to Home Assistant.](https://www.home-assistant.io/images/docs/energy/grid.png) Tariffs[](https://www.home-assistant.io/docs/energy/electricity-grid/#tariffs) ------------------------------------------------------------------------------- It has become popular for energy utilities to split the price of energy based on time of the day; this is done in order to incentivise consumers to shift their power needs towards times where the grid has lower loads. These periods of time are commonly referred to as Peak and Off Peak, exactly because they match periods of time where everyone is consuming energy (Peak) and periods of time where the energy is abundant but no one is using it (Off Peak). Therefore Peak energy is more expensive then Off Peak energy. If you want to split energy usage into multiple tariffs, [read this](https://www.home-assistant.io/docs/energy/faq/#split-consumption-by-tariffs) . Hardware[](https://www.home-assistant.io/docs/energy/electricity-grid/#hardware) --------------------------------------------------------------------------------- Home Assistant will need to know the amount of energy flowing through your meter. This data can be tracked in various ways. ### Connect to your meter[](https://www.home-assistant.io/docs/energy/electricity-grid/#connect-to-your-meter) The best way to get this data is directly from your electricity meter that sits between your house and the grid. In certain countries these meters contain standardized ways of reading out the information locally. #### Connect using a P1 port[](https://www.home-assistant.io/docs/energy/electricity-grid/#connect-using-a-p1-port) The P1 port is a standardized port in the Netherlands, Belgium and Luxembourg. A P1 reader can connect to this port and receive real-time information. We have worked with creator [Marcel Zuidwijk](https://www.zuidwijk.com/) to develop [SlimmeLezer+](https://www.zuidwijk.com/product/slimmelezer-plus/) . It’s an affordable P1 reader powered by [ESPHome](https://esphome.io/) that will seamlessly integrate this information in Home Assistant. It is being sold on [his website](https://www.zuidwijk.com/product/slimmelezer-plus/) and the firmware is open source [on GitHub](https://github.com/zuidwijk/dsmr) . ![Photo of SlimmeLezer attached to a smart electricity meter](https://www.home-assistant.io/images/docs/energy/slimmelezer.jpg) #### Connect via Zigbee Energy Profile[](https://www.home-assistant.io/docs/energy/electricity-grid/#connect-via-zigbee-energy-profile) The Zigbee Energy Profile is a wireless energy standard to provide real-time information about electricity usage. This standard is available in some meters in the US, UK, Canada, and Australia. This is not “normal” Zigbee as implemented by Home Assistant but requires special certified hardware and often requires that the Zigbee connection be provisioned by your utility. As such, your utility, assuming they support this at all, will have a list of currently supported hardware. The [Rainforest Automation Eagle](https://www.home-assistant.io/integrations/rainforest_eagle) is one such device that implements this which supports a local API and is compatible with Home Assistant. #### Reading the meter via a pulse counter[](https://www.home-assistant.io/docs/energy/electricity-grid/#reading-the-meter-via-a-pulse-counter) Many meters, including older ones, have an LED that will flash whenever energy passes through it. For example, each flash is a 1/1000th kWh. By monitoring the time between flashes it’s possible to determine the energy consumption. We have developed [Home Assistant Glow](https://github.com/klaasnicolaas/home-assistant-glow) , an open source solution powered by ESPHome’s [pulse meter sensor](https://esphome.io/components/sensor/pulse_meter/) . You put it on top of the activity LED of your electricity meter and it will bring your consumption into Home Assistant. ![Photo of Home Assistant Glow attached to an electricity meter](https://www.home-assistant.io/images/docs/energy/home-assistant-glow.jpg) #### Reading the meter via a IEC62056-21[](https://www.home-assistant.io/docs/energy/electricity-grid/#reading-the-meter-via-a-iec62056-21) The IEC62056-21 is a common protocol not only for electric meters. It uses an infrared port to read data. [Aquaticus](https://github.com/aquaticus) has created an [ESPHome component](https://community.home-assistant.io/t/555236) for reading this data. [PiggyMeter](https://aquaticus.info/meter.html) is a complete project that allows easy installation. ![Photo of PiggyMeter attached to an electricity meter](https://aquaticus.info/_images/meter_and_probe.png) #### Using (Smart Message Language) interface[](https://www.home-assistant.io/docs/energy/electricity-grid/#using-smart-message-language-interface) In countries like Germany, SML (Smart Message Language) is used typically. ESPHome’s [SML (Smart Message Language)](https://esphome.io/components/sml/) is one way to integrate it. If you prefer to integrate it via MQTT, [sml2mqtt](https://github.com/spacemanspiff2007/sml2mqtt) is another open source option. #### Read the meter using an AI-on-the-edge-device[](https://www.home-assistant.io/docs/energy/electricity-grid/#read-the-meter-using-an-ai-on-the-edge-device) [AI-on-the-edge-device](https://github.com/jomjol/AI-on-the-edge-device) is a project running on an ESP32-CAM and can be fully integrated into Home Assistant using the Home Assistant discovery functionality of MQTT. It digitalizes your gas/water/electricity meter display and provides its data in various ways. ![Photo of the AI-on-the-edge-device Workflow](https://www.home-assistant.io/images/docs/energy/ai-on-the-edge-device.jpg) ### Using a CT clamp sensor[](https://www.home-assistant.io/docs/energy/electricity-grid/#using-a-ct-clamp-sensor) Current transformer (CT) clamp sensors measure your energy usage by looking at the current passing through an electrical wire. This makes it possible to calculate the energy usage. In Home Assistant we have support for off-the-shelf CT clamp sensors or you can build your own. * The off-the-shelf solution that we advise is the [Shelly EM](https://www.shelly.com/products/shelly-em-50a-clamp-1?tracking=A7FsiPIfUWsFpnfKHa8SRyUYLXjr2hPq) . The device has a local API, updates are pushed to Home Assistant and it has a high quality [integration](https://www.home-assistant.io/integrations/shelly/) . * You can build your own using ESPHome’s [CT Clamp Current sensor](https://esphome.io/components/sensor/ct_clamp/) or energy meter sensors like the [ATM90E32](https://esphome.io/components/sensor/atm90e32/) . For the DIY route, check out [this video by digiblur](https://www.youtube.com/watch?v=n2XZzciz0s4) to get started. * Using a Raspberry Pi, you can use a CT clamp HAT from LeChacal called [RPICT hats](https://lechacal.com/docs/RPICT/Raspberrypi_Current_and_Temperature_Sensor_Adaptor/) . They can be stacked to expand the number of lines to monitor. They also provide Active, Apparent, and Reactive power and power factor for single-phase and three-phase installations. They integrate with Home Assistant using MQTT. _Attention! Installing CT clamp sensor devices requires opening your electrical cabinet. This work should be done by someone familiar with electrical wiring and may require a licensed professional in some regions. Your qualified installer will know how to do this._ _Disclaimer: Some links in this section are affiliate links._ ### Data provided by your energy provider[](https://www.home-assistant.io/docs/energy/electricity-grid/#data-provided-by-your-energy-provider) Some energy providers will provide you real-time information about your usage and have this data integrated into Home Assistant. ### Manual integration[](https://www.home-assistant.io/docs/energy/electricity-grid/#manual-integration) If you manually integrate your sensors, for example, using the [MQTT](https://www.home-assistant.io/integrations/mqtt) or [Template](https://www.home-assistant.io/integrations/template) integrations: Make sure you set and provide the `device_class`, `state_class`, and `unit_of_measurement` for those sensors. ### Troubleshooting[](https://www.home-assistant.io/docs/energy/electricity-grid/#troubleshooting) If you are unable to select your energy or power sensor in the grid consumption drop-down, make sure that its value is being recorded in the Recorder settings. [Energy integrations](https://www.home-assistant.io/integrations/#energy) _Disclaimer: Some links on this page are affiliate links helping support the Home Assistant project._ #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/electricity-grid/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/electricity-grid.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Felectricity-grid%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Felectricity-grid%2F%22&in=body "View given feedback for this page") --- # Frequently Asked Questions about home energy management - Home Assistant Energy vs Power[](https://www.home-assistant.io/docs/energy/faq/#energy-vs-power) ---------------------------------------------------------------------------------- It’s a common mistake to take Power as an Energy value, but the two are not alike. [Energy](https://en.wikipedia.org/wiki/Energy) is a quantitative measurement of what it takes to produce work (e.g. heat water) while [Power](https://en.wikipedia.org/wiki/Electric_power) measures the speed at which energy is transferred. Electrical Power is measured in Watts (W) and Electrical Energy is measured in kiloWatt-hour (kWh). Think of this in a parallel to speed and distance: Power is the speed you are going and Energy is the distance driven. Therefore Energy (kiloWatt-hour) is not an average of the Power you are consuming over a given period of time (the unit of the average power would be Watt or kiloWatt again). Energy is the integral (mathematical operation) of the Power function. This difference is very important as you need to use the proper entities in our Energy dashboard. Creating an Energy Sensor out of a Power Sensor[](https://www.home-assistant.io/docs/energy/faq/#creating-an-energy-sensor-out-of-a-power-sensor) -------------------------------------------------------------------------------------------------------------------------------------------------- Since in Home Assistant, we don’t deal with Power functions but with samples of the power being used, we can’t do the integral (mathematical operation) directly and get the true amount of energy consumed/produced. That said, if you can sample Power values fast enough (every few seconds) you can reliably measure energy transferred through mathematic approximations called [Riemann Sum](https://en.wikipedia.org/wiki/Riemann_sum) . Home Assistant provides this mathematical operation through the [integration](https://www.home-assistant.io/integrations/integration/#energy) . Split consumption by tariffs[](https://www.home-assistant.io/docs/energy/faq/#split-consumption-by-tariffs) ------------------------------------------------------------------------------------------------------------ If you are using a 3rd party device (e.g. not reading directly from your utility meter device or from the utility provider cloud service) you need HA to split your energy measurements into 2 (or more) tariffs, in order to track these energy consumptions separately. To accomplish such, you can use the [utility\_meter integration](https://www.home-assistant.io/integrations/utility_meter/) . With this integration, you define as many tariffs as required (in accordance with your utility provider contract) and HA will be able to differentiate energy consumptions in each of the tariffs. Please note that each utility provider has its own time schedules for peak and off-peak and you are required to create an automation that switches the utility\_meter entity from one tariff to the other. The energy dashboard is not visible[](https://www.home-assistant.io/docs/energy/faq/#the-energy-dashboard-is-not-visible) -------------------------------------------------------------------------------------------------------------------------- If you do not see the Energy dashboard in the sidebar, make sure you have not removed [`default_config:`](https://www.home-assistant.io/integrations/default_config/) from your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) . If you have, you will need to add the `energy:` integration manually. Troubleshooting missing entities[](https://www.home-assistant.io/docs/energy/faq/#troubleshooting-missing-entities) -------------------------------------------------------------------------------------------------------------------- ### Condition[](https://www.home-assistant.io/docs/energy/faq/#condition) You are trying to add a sensor to the energy dashboard, but it does not appear in the selection list. ### Resolution[](https://www.home-assistant.io/docs/energy/faq/#resolution) To find out why the sensor is not showing, check the following points: * The sensor must have the appropriate attributes. Check your entity attributes in [**Developer Tools** > **States**](https://my.home-assistant.io/redirect/developer_states) to confirm the following: * `device_class` must be `energy` or `power` for electricity grid, solar, or battery categories. It must be `gas` for gas, or `water` for water. * `state_class` must be `measurement` for power sensors and `total` or `total_increasing` for all others. * The sensor must have an appropriate `unit_of_measurement`. See the help text for each category to see which units are accepted. Units containing an exponent must match superscript characters exactly as defined, e.g. `m³` is accepted, `m3` is not. If any of the attributes are not correct, please open an issue against the integration that provides your sensor, or if you are developing custom template sensors, make sure the templates have the correct settings. * The entity must be a `sensor`. If you are trying to add something from another domain (for example an `input_number`), then you must first create a template sensor from it. * The entity must not have any statistics errors. Go to [**Developer Tools** > **Statistics**](https://my.home-assistant.io/redirect/developer_statistics) to check your specific entity. If your unit has a listed issue here, you must fix the issue before it can be added to the dashboard. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/faq/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/faq.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Ffaq%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Ffaq%2F%22&in=body "View given feedback for this page") --- # Integrating your solar panels - Home Assistant Gain insight into your energy production by integrating your solar panels into Home Assistant. If you also set up [the Solar Forecast integration](https://www.home-assistant.io/integrations/forecast_solar) , you will be able to see expected solar production and automate based on planned production. ![Graphic showing energy flowing from the solar panels to Home Assistant and back to the grid.](https://www.home-assistant.io/images/docs/energy/solar.png) Hardware[](https://www.home-assistant.io/docs/energy/solar-panels/#hardware) ----------------------------------------------------------------------------- Home Assistant will need to know the amount of energy that is being produced. This can be done in various ways. ### Using a CT clamp sensor[](https://www.home-assistant.io/docs/energy/solar-panels/#using-a-ct-clamp-sensor) Current transformer (CT) clamp sensors measure your energy usage by looking at the current passing through an electrical wire. This makes it possible to calculate the energy usage. In Home Assistant we have support for off-the-shelf CT clamp sensors or you can build your own. * The off-the-shelf solution that we advise is the [Shelly EM](https://www.shelly.com/products/shelly-em-50a-clamp-1?tracking=A7FsiPIfUWsFpnfKHa8SRyUYLXjr2hPq) . The device has a local API, updates are pushed to Home Assistant and it has a high quality [integration](https://www.home-assistant.io/integrations/shelly/) . * You can build your own using ESPHome’s [CT Clamp Current sensor](https://esphome.io/components/sensor/ct_clamp/) or energy meter sensors like the [ATM90E32](https://esphome.io/components/sensor/atm90e32/) . For the DIY route, check out [this video by digiblur](https://www.youtube.com/watch?v=n2XZzciz0s4) to get started. * Using a Raspberry Pi, you can use a CT clamp HAT from LeChacal called [RPICT hats](https://lechacal.com/docs/RPICT/Raspberrypi_Current_and_Temperature_Sensor_Adaptor/) . They can be stacked to expand the number of lines to monitor. They also provide Active, Apparent, and Reactive power and power factor for single-phase and three-phase installations. They integrate with Home Assistant using MQTT. _Attention! Installing CT clamp sensor devices requires opening your electrical cabinet. This work should be done by someone familiar with electrical wiring and may require a licensed professional in some regions. Your qualified installer will know how to do this._ _Disclaimer: Some links in this section are affiliate links._ ### Connecting to your inverter[](https://www.home-assistant.io/docs/energy/solar-panels/#connecting-to-your-inverter) Some solar inverters have APIs that can be read by Home Assistant. [Energy integrations](https://www.home-assistant.io/integrations/#energy) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/solar-panels/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/solar-panels.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Fsolar-panels%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Fsolar-panels%2F%22&in=body "View given feedback for this page") --- # Tools - Home Assistant Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/tools/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/tools.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ftools%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ftools%2F%22&in=body "View given feedback for this page") --- # About the blueprint schema - Home Assistant The blueprint schema[](https://www.home-assistant.io/docs/blueprint/schema/#the-blueprint-schema) -------------------------------------------------------------------------------------------------- Blueprint schemas currently supports three types of schema depending on its domain: [`automation`](https://www.home-assistant.io/docs/automation/yaml/) ; `script`; and [`template`](https://www.home-assistant.io/integrations/template/#using-blueprints) . The configuration schema of a blueprint consists of 2 parts: 1. The blueprint’s high-level metadata: name, domain and, optionally, any input required from the user. 2. The schema for the blueprint domain it describes. The first part is referred to as the _blueprint schema_. It contains the blueprint’s metadata. Minimum required metadata for a blueprint is its name and domain. In its most basic form, a blueprint looks like: blueprint: name: Example blueprint domain: automation Although this is a valid blueprint, it is not very useful. The second part depends on its domain, the type of blueprint. For example, when creating a blueprint for an automation, the full schema for an [automation](https://www.home-assistant.io/docs/automation/yaml/) applies. This is the full blueprint schema: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/schema/#schema-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) name string Required[](https://www.home-assistant.io/docs/blueprint/schema/#name) The name of the blueprint. Keep this short and descriptive. description string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#description) The description of the blueprint. While optional, this field is highly recommended. Describe what the blueprint does and describe the inputs the blueprint requires. The description can include [Markdown](https://commonmark.org/help/) . domain string Required[](https://www.home-assistant.io/docs/blueprint/schema/#domain) The domain in which this blueprint is used. Currently, only three types, [`automation`](https://www.home-assistant.io/docs/automation/yaml/) , `script` and [`template`](https://www.home-assistant.io/integrations/template/#using-blueprints) are supported. author string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#author) The name of the blueprint author. homeassistant map (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#homeassistant) Home Assistant version required for the blueprint to work successfully. min\_version string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#min_version) Minimum required version of Home Assistant to use the blueprint in the format of _major_._minor_._patch_ (all parts are required). For example, `2022.4.0`. It is important to set this if the blueprint uses any features introduced in recent releases to head off issues. input map (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#input) A dictionary of defined user inputs or sections. These are the input fields that the consumer of your blueprint can provide using YAML definition, or via a configuration form in the UI. Sections provide a way to visually group a set of related inputs (see below). ### Blueprint inputs[](https://www.home-assistant.io/docs/blueprint/schema/#blueprint-inputs) A blueprint can accept one or multiple inputs from the user, but does not require any input. These inputs can be of any type (string, boolean, list, map). They can have a default value and also provide a [selector](https://www.home-assistant.io/docs/blueprint/selectors/) that ensures a matching input field in the user interface. A blueprint input has the following configuration: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/schema/#schema-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) name string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#name) The name of the input field. description string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#description) A short description of the input field. Keep this short and descriptive. The description can include [Markdown](https://commonmark.org/help/) . selector [selector](https://www.home-assistant.io/docs/blueprint/selectors/) (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#selector) The [selector](https://www.home-assistant.io/docs/blueprint/selectors/) to use for this input. A selector defines how the input is displayed in the frontend UI. default any (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#default) The default value of this input, in case the input is not provided by the user of this blueprint. Each input field can be referred to, outside of the blueprint metadata, using the `!input` custom YAML tag before its name. The following example shows a minimal _blueprint schema_ with a single input: blueprint: name: Example blueprint description: Example showing an input domain: automation input: my_input: name: Example input In the above example, `my_input` is the identifier of the input. It can be referenced by using the `!input my_input` custom tag. In this example, no [`selector`](https://www.home-assistant.io/docs/blueprint/selectors/) was provided. In the user interface, a text input field would be shown to the user. It is then up to the user to find out what to enter there. Blueprints that come with [selectors](https://www.home-assistant.io/docs/blueprint/selectors/) are easier to use. A blueprint can have as many inputs as you like. ### Blueprint input sections[](https://www.home-assistant.io/docs/blueprint/schema/#blueprint-input-sections) One or more input sections can be added under the main `input` key. Each section visually groups the inputs in that section, allows an optional description, and optionally allows for collapsing those inputs. Note that the section only impacts how inputs are displayed to the user when they fill in the blueprint. Inputs must have unique names and be referenced directly by their name; not by section and name. A section is differentiated from an input by the presence of an additional `input` key within that section. Caution Input sections are a new feature in version 2024.6.0. Set the `min_version` for the blueprint to at least this version if using input sections. Otherwise, the blueprint will generate errors on older versions. See [this section](https://www.home-assistant.io/docs/blueprint/schema/#min_version) for more details. The full configuration for an input section is below: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/schema/#schema-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) name string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#name) A name for the section. If omitted the key of the section is used. icon string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#icon) An icon to display next to the name of the section. description string (Optional)[](https://www.home-assistant.io/docs/blueprint/schema/#description) An optional description of this section, which will be displayed at the top of the section. The description can include [Markdown](https://commonmark.org/help/) . collapsed boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/schema/#collapsed) If `true`, the section will be collapsed by default. Useful for optional or less important inputs. All collapsed inputs must also have a defined `default` before they can be hidden. input map Required[](https://www.home-assistant.io/docs/blueprint/schema/#input) A dictionary of defined user inputs within this section. The following example shows a _blueprint schema_ with some inputs in a section: blueprint: name: Example sections blueprint description: Example showing a section input: base_input: name: An input not in the section my_section: name: My Section icon: mdi:cog description: These options control a specific feature of this blueprint input: my_input: name: Example input my_input_2: name: 2nd example input ### Blueprint inputs in templates[](https://www.home-assistant.io/docs/blueprint/schema/#blueprint-inputs-in-templates) The inputs are available as custom YAML tags, but not as template variables. To use a blueprint input in a template, it first needs to be exposed as either a [script level variable](https://www.home-assistant.io/integrations/script/#configuration-variables) or in a [variable script step](https://www.home-assistant.io/docs/scripts/#variables) . variables: # Make input my_input available as a script level variable my_input: !input my_input ### Example blueprints[](https://www.home-assistant.io/docs/blueprint/schema/#example-blueprints) The [built-in blueprints](https://github.com/home-assistant/core/tree/dev/homeassistant/components/automation/blueprints) are great examples to get a bit of a feeling of how blueprints work. Here is the built-in motion light automation blueprint. Note the _blueprint schema_ under the blueprint key is followed by its domain schema. In this example, an automation schema. blueprint: name: Motion-activated Light description: Turn on a light when motion is detected. domain: automation input: motion_entity: name: Motion Sensor selector: entity: filter: device_class: motion domain: binary_sensor light_target: name: Light selector: target: entity: domain: light no_motion_wait: name: Wait time description: Time to leave the light on after last motion is detected. default: 120 selector: number: min: 0 max: 3600 unit_of_measurement: seconds # If motion is detected within the delay, # we restart the script. mode: restart max_exceeded: silent triggers: - trigger: state entity_id: !input motion_entity from: "off" to: "on" actions: - action: light.turn_on target: !input light_target - wait_for_trigger: - trigger: state entity_id: !input motion_entity from: "on" to: "off" - delay: !input no_motion_wait - action: light.turn_off target: !input light_target Related topics[](https://www.home-assistant.io/docs/blueprint/schema/#related-topics) -------------------------------------------------------------------------------------- * [About blueprints](https://www.home-assistant.io/docs/blueprint/) * [Blueprint selectors](https://www.home-assistant.io/docs/blueprint/selectors/) * [Using blueprints in automations](https://www.home-assistant.io/docs/automation/using_blueprints/) * [Tutorial: create an automation blueprint](https://www.home-assistant.io/docs/blueprint/tutorial/) Related links[](https://www.home-assistant.io/docs/blueprint/schema/#related-links) ------------------------------------------------------------------------------------ * [Blueprint community forum](https://www.home-assistant.io/get-blueprints) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/blueprint/schema/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/blueprint/schema.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fblueprint%2Fschema%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fblueprint%2Fschema%2F%22&in=body "View given feedback for this page") --- # Integrating individual device energy usage - Home Assistant Home Assistant can integrate the energy usage of individual devices into Home Assistant. That way you can see the impact of individual devices on your total energy consumption. In addition to energy usage, Home Assistant also supports tracking individual water device usage, allowing you to monitor water consumption of specific devices in your home. Hardware for energy monitoring[](https://www.home-assistant.io/docs/energy/individual-devices/#hardware-for-energy-monitoring) ------------------------------------------------------------------------------------------------------------------------------- ### Smart plugs[](https://www.home-assistant.io/docs/energy/individual-devices/#smart-plugs) Smart plugs sit between the device and the outlet and measure the energy flowing through the device. Depending on what protocols you use at home, you can use Zigbee, Z-Wave or Wi-Fi based plugs. ### Smart relays[](https://www.home-assistant.io/docs/energy/individual-devices/#smart-relays) Smart relays sit behind your “normal” switches and make them smart. It allows you to control the devices via Home Assistant and via the connected buttons/switches. Hardware for water monitoring[](https://www.home-assistant.io/docs/energy/individual-devices/#hardware-for-water-monitoring) ----------------------------------------------------------------------------------------------------------------------------- For tracking individual water devices, you can use: * Smart water meters with device-level monitoring capabilities. * Inline flow meters that measure water flowing to specific appliances. * Smart appliances (washing machines, dishwashers, etc.) that report their own water consumption. For more information on water metering hardware and integrations, see the [water usage documentation](https://www.home-assistant.io/docs/energy/water/) . Devices with power (W) sensors[](https://www.home-assistant.io/docs/energy/individual-devices/#devices-with-power-w-sensors) ----------------------------------------------------------------------------------------------------------------------------- Some smart devices, such as air conditioning, boilers, and others, may provide a power sensor, measured in Watts. You can use the [Integration (Riemann sum integral) integration](https://www.home-assistant.io/integrations/integration/#energy) to calculate the energy your device is using. You can then use the energy sensor in the Energy Dashboard, as individual devices. You can add the power sensor directly if it has the appropriate attributes. For information on setting up an entity for use in the **Energy** dashboard, refer to the [energy FAQ](https://www.home-assistant.io/docs/energy/faq/#troubleshooting-missing-entities) . ![Graphic showing energy flowing from the home to individual devices.](https://www.home-assistant.io/images/docs/energy/devices.png) Upstream devices and hierarchies[](https://www.home-assistant.io/docs/energy/individual-devices/#upstream-devices-and-hierarchies) ----------------------------------------------------------------------------------------------------------------------------------- You can create a hierarchy of devices by setting one device as an “upstream device” of another. This means you can now establish parent-child relationships between devices within your energy configuration. This works for both energy and water devices. For example, imagine having a breaker monitoring the total energy consumption of a circuit, but also separately tracking individual devices connected to that circuit. For water usage, you might have a main water line meter and individual meters for appliances like washing machines or dishwashers. Without setting the device hierarchies, Home Assistant might double-count this usage. By setting the hierarchy, it understands these relationships and accurately shows the individual device usage without duplication. To set up an upstream device relationship: 1. Add an energy or water consumption entity as an individual device. 2. Then, when configuring other individual devices, you can select the previously added individual entity as their upstream device. This hierarchical view helps you understand which devices are consuming energy or water from which sources and prevents usage from being counted multiple times. Important To set up a hierarchy, you must first add all related entities as individual devices in the energy dashboard. Only devices that are already listed under individual devices can be selected as “upstream device” for other devices. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/individual-devices/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/individual-devices.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Findividual-devices%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Findividual-devices%2F%22&in=body "View given feedback for this page") --- # Integrating your water usage - Home Assistant Home Assistant allows you to track your water usage in the home energy management too. Although water usage is not strictly “energy”, it is still a valuable resource to track and monitor as it is often tightly coupled with energy usage (like gas). Additionally, it can help you reduce your ecological footprint by using less water. ### Home water meters[](https://www.home-assistant.io/docs/energy/water/#home-water-meters) There are several ways to measure water usage in your home. Multiple methods exist for reading your water usage. Older water meters typically feature a common arrow or only display total consumption. For these meters, you may require an [AI-on-the-edge-device](https://github.com/jomjol/AI-on-the-edge-device) with an ESP32 camera. While effective, this solution can be tedious to set up as it leans towards a DIY approach. Newer water meters are equipped with a rotary disk that can be read using two methods. The first method utilizes light sensors, while the second method employs proximity sensors. The proximity sensor detects changes in the magnetic field, with each rotation of the disk representing one liter of water used. Meanwhile, the light sensor method operates on an autocorrelation technique, providing accuracy down to 100 milliliters instead of the traditional one-liter step. For most water meters, the rotary encoder disk suffices the light sensor version. However, some older or specialized meters may necessitate the use of a proximity meter instead. Home Assistant also has integrations build into the platform that connect with existing products Home Assistant integrations[](https://www.home-assistant.io/docs/energy/water/#home-assistant-integrations) ------------------------------------------------------------------------------------------------------------ Home Assistant will need to know the amount of water that is being consumed to be able to track usage. Several [water metering (fluid flow rate sensor device)](https://en.wikipedia.org/wiki/Water_metering) hardware options are available to do this. Depending on your setup, the required hardware is provided by your public water utility company, or you may need to buy your own. Some hardware with water meters may also provide additional practical functions or sensors, such as [valve](https://www.home-assistant.io/integrations/valve) , for example, for controlling water shutoff, or temperature and pressure (to enable freeze alarms). We have the following integrations available for existing products that can provide information about water usage: * [Droplet](https://www.home-assistant.io/integrations/droplet) * [Flo](https://www.home-assistant.io/integrations/flo) * [Flume](https://www.home-assistant.io/integrations/flume) * [HomeWizard Energy](https://www.home-assistant.io/integrations/homewizard) * [StreamLabs](https://www.home-assistant.io/integrations/streamlabswater) * [Suez Water](https://www.home-assistant.io/integrations/suez_water) * [Watergate](https://www.home-assistant.io/integrations/watergate) There are also products for water usage monitoring that are based on existing common IoT protocol standards: * [Z-Wave](https://www.home-assistant.io/integrations/zwave_js) * [Zigbee](https://www.home-assistant.io/integrations/zha) * [Matter](https://www.home-assistant.io/integrations/matter) Individual water devices[](https://www.home-assistant.io/docs/energy/water/#individual-water-devices) ------------------------------------------------------------------------------------------------------ Similar to tracking individual energy devices, Home Assistant supports tracking water usage of individual devices. This feature allows you to monitor water consumption from specific appliances or fixtures in your home, such as washing machines, dishwashers, or individual faucets. You can create hierarchies of water devices by setting one device as an “upstream device” of another. This prevents double-counting when you have, for example, a main water meter and individual device meters. For more details on setting up device hierarchies and preventing double-counting, see the [individual devices documentation](https://www.home-assistant.io/docs/energy/individual-devices/) . Community-made sensors[](https://www.home-assistant.io/docs/energy/water/#community-made-sensors) -------------------------------------------------------------------------------------------------- If your water meter lacks a rotary disk, magnetic disk, or coil. There are alternative solutions available to seamlessly integrate water monitoring into your smart home setup: * [AI-on-the-edge-device](https://github.com/jomjol/AI-on-the-edge-device) is a project running on an ESP32-CAM and can be fully integrated into Home Assistant using the Home Assistant Discovery Functionality of MQTT. It digitalizes your gas/water/electricity meter display and provides its data in various ways.![Photo of the AI-on-the-edge-device Workflow](https://www.home-assistant.io/images/docs/energy/ai-on-the-edge-device.jpg) If you have a Culligan Water Softener, you may be able to interface with the inbuilt `DEBUG PORT` and receive water usage stats including `Gallons` (gal), `Gallons Per Minute` (gal/min), and `Gallons to Recharge` (gal): * [cullAssistant](https://github.com/LelandSindt/cullAssistant) (ESPHome) Alternatively, the following shops sell ESPHome-based devices that use a 3-phase light sensor to detect a rotating disk in your water meter and convert this to the amount of water used in milliliters (ml): * [Muino water meter reader](https://watermeter.muino.nl/) (ESPHome) Alternatively, the following shops sell ESPHome-based devices, that use a proximity sensor to detect a rotating magnet in your water meter and use that pulse to count each liter of water used: * [S0tool](https://s0tool.nl/) (“Made for ESPHome” approved) * [Waterlezer dongle](https://smart-stuff.nl/product/esphome-waterlezer-dongle/) (Dutch) * [Slimme Watermeter Gateway](https://smartgateways.nl/product/slimme-watermeter-gateway/) (Dutch) * [watermeterkit.nl](https://watermeterkit.nl/) (Dutch) DIY[](https://www.home-assistant.io/docs/energy/water/#diy) ------------------------------------------------------------ Maybe you like to build one yourself? * Pieter Brinkman has quite a [nice blog article on how to create your own water sensor](https://www.pieterbrinkman.com/2022/02/02/build-a-cheap-water-usage-sensor-using-esphome-home-assistant-and-a-proximity-sensor/) using ESPHome, or [build a water meter](https://www.ztatz.nl/p1-monitor-watermeter/) that works with the [P1 Monitor](https://www.home-assistant.io/integrations/p1_monitor) integration. * [AI-on-the-edge-device](https://github.com/jomjol/AI-on-the-edge-device) is a project running on an ESP32-CAM and can be fully integrated into Home Assistant using the Home Assistant Discovery Functionality of MQTT. It digitalizes your gas/water/electricity meter display and provides its data in various ways.![Photo of the AI-on-the-edge-device Workflow](https://www.home-assistant.io/images/docs/energy/ai-on-the-edge-device.jpg) * [watermeter](https://github.com/nohn/watermeter) running classic OCR and statistical pattern recognition on any system supporting Docker * [Muino water meter reader 3-phase](https://muino.nl/product/3-phase-muino-light-sensor-encoder/) Using the 3-phase sensor technique, a battery-powered version can be possible with this sensor. * [Read water meter with magnetometer](https://github.com/tronikos/esphome-magnetometer-water-gas-meter) using [QMC5883L](https://esphome.io/components/sensor/qmc5883l/) or [HMC5883L](https://esphome.io/components/sensor/hmc5883l/) , common and inexpensive magnetometers. This should be compatible with all the water meters the Flume water sensor is compatible with, which is [compatible](https://help.flumewater.com/articles/1618594) with about 95% of water meters in the United States. * Some watermeters use [Wireless M-Bus](https://en.wikipedia.org/wiki/Meter-Bus) for remote metering. [wmbusmeters project](https://github.com/wmbusmeters/wmbusmeters/) can automatically capture, decode, decrypt and convert M-Bus packets to MQTT. It supports several M-Bus receivers, including RTL-SDR using [rtl-wmbus library](https://github.com/xaelsouth/rtl-wmbus) . You can also build a WMBus [ESPHome-based receiver](https://github.com/SzczepanLeon/esphome-components) . An [add-on](https://github.com/wmbusmeters/wmbusmeters-ha-addon) for Home Assistant exists for easy installation and configuration. See the [community page](https://community.home-assistant.io/t/228988) for more. * Read water (or gas) usage data from the Itron EverBlu Cyble Enhanced RF meters using the RADIAN protocol over 433 MHz [everblu-meters-esp8266/esp32](https://github.com/genestealer/everblu-meters-esp8266-improved) , via an ESP32/ESP8266 and a CC1101 transceiver. Used across the UK and Europe. Fully integrates with Home Assistant using MQTT AutoDiscovery. According to available documentation, this method may also work with AnyQuest Cyble Enhanced, EverBlu Cyble, and AnyQuest Cyble Basic, but these remain untested. If you manually integrate your sensors, for example, using the [MQTT](https://www.home-assistant.io/integrations/mqtt) or [RESTful](https://www.home-assistant.io/integrations/rest) integrations: Make sure you set and provide the `device_class`, `state_class`, and `unit_of_measurement` for those sensors. For any of the above-listed options, make sure it actually works with the type of water meter you have before getting one. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/water/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/water.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Fwater%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Fwater%2F%22&in=body "View given feedback for this page") --- # Integrating your gas usage - Home Assistant Some homes are connected to gas. Gas is being used to heat water, cook and heat up the home. Home Assistant allows you to track your gas usage and easily compare it against your energy usage for the same period of time. Hardware[](https://www.home-assistant.io/docs/energy/gas/#hardware) -------------------------------------------------------------------- Home Assistant will need to know the amount of gas that is being consumed. ### Connect to your meter[](https://www.home-assistant.io/docs/energy/gas/#connect-to-your-meter) The best way to get this data is directly from your gas meter that sits between your house and the grid. In certain countries these meters contain standardized ways of reading out the information locally or provide this information via the electricity meter. #### Connect using a P1 port[](https://www.home-assistant.io/docs/energy/gas/#connect-using-a-p1-port) The P1 port is a standardized port on electricity meters in the Netherlands, Belgium and Luxembourg which also provides gas consumption information. A P1 reader can connect to this port and receive real-time information. We have worked with creator [Marcel Zuidwijk](https://www.zuidwijk.com/) to develop [SlimmeLezer+](https://www.zuidwijk.com/product/slimmelezer-plus/) . It’s an affordable P1 reader powered by [ESPHome](https://esphome.io/) that will seamlessly integrate this information in Home Assistant. It is being sold on [his website](https://www.zuidwijk.com/product/slimmelezer-plus/) and the firmware is open source [on GitHub](https://github.com/zuidwijk/dsmr) . ![Photo of SlimmeLezer attached to a smart electricity meter](https://www.home-assistant.io/images/docs/energy/slimmelezer.jpg) #### Read the Gas Meter using an AI-on-the-edge-device[](https://www.home-assistant.io/docs/energy/gas/#read-the-gas-meter-using-an-ai-on-the-edge-device) [AI-on-the-edge-device](https://github.com/jomjol/AI-on-the-edge-device) is a project running on an ESP32-CAM and can be fully integrated into Home Assistant using the Home Assistant Discovery Functionality of MQTT. It digitalizes your gas/water/electricity meter display and provides its data in various ways. ![Photo of the AI-on-the-edge-device Workflow](https://www.home-assistant.io/images/docs/energy/ai-on-the-edge-device.jpg) #### Read the Gas Meter using a magnetometer[](https://www.home-assistant.io/docs/energy/gas/#read-the-gas-meter-using-a-magnetometer) [Diaphragm/bellows gas meters](https://en.wikipedia.org/wiki/Gas_meter#Diaphragm/bellows_meters) are the most common type of gas meter, seen in almost all residential installations, and their movement can frequently be observed with a magnetometer. The [QMC5883L](https://esphome.io/components/sensor/qmc5883l/) and [HMC5883L](https://esphome.io/components/sensor/hmc5883l/) are common and inexpensive options that ESPHome supports. A project that makes it easy to use these magnetometers and calibrate them is [this water-gas-meter project on GitHub](https://github.com/tronikos/esphome-magnetometer-water-gas-meter) . #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/gas/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy/gas.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2Fgas%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2Fgas%2F%22&in=body "View given feedback for this page") --- # Understanding Home Energy Management - Home Assistant Home Assistant allows you to get on top of your energy use with its home energy management feature. Gain new insights, optimize your solar panel production, plan energy usage and save money. [![](https://my.home-assistant.io/badges/energy.svg)](https://my.home-assistant.io/redirect/energy) [![](https://my.home-assistant.io/badges/config_energy.svg)](https://my.home-assistant.io/redirect/config_energy) Home energy management works with three different types of information sources. You can start using it even if you just have one source connected to Home Assistant. Every source you add will complement the other sources, giving you even more insight into energy in your home. Home Assistant is an open platform and so home energy management is not restricted to specific hardware. Any energy monitoring hardware that integrates with Home Assistant can be used as a data source. Check out the following sections for in-depth explanations and hardware recommendations. * [Integrate your energy use from the electricity grid](https://www.home-assistant.io/docs/energy/electricity-grid/) * [Integrate your solar panels](https://www.home-assistant.io/docs/energy/solar-panels/) * [Integrate your home batteries](https://www.home-assistant.io/docs/energy/battery/) * [Integrate your gas consumption](https://www.home-assistant.io/docs/energy/gas/) * [Integrate your water consumption](https://www.home-assistant.io/docs/energy/water/) * [Integrate individual devices](https://www.home-assistant.io/docs/energy/individual-devices/) If you have a sensor that returns instantaneous power readings (W or kW), then to add a sensor that returns energy usage or generation (kWh), refer to the [Riemann sum integral integration](https://www.home-assistant.io/integrations/integration/#energy) . You can also configure power sensors alongside energy sensors in the Energy dashboard. Power inputs accept sensors with `state_class: measurement` and appropriate units (for example `W` or `kW`). ![Visual representation of how all different energy forms relate.](https://www.home-assistant.io/images/docs/energy/energy-overview.png) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/energy/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/energy.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fenergy%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fenergy%2F%22&in=body "View given feedback for this page") --- # check_config - Home Assistant Test any changes to your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file before launching Home Assistant. This script allows you to test changes without the need to restart Home Assistant. hass --script check_config The script has further options like checking configuration files which are not located in the default directory or showing your secrets for debugging. $ hass --script check_config -h usage: hass [-h] [--script {check_config}] [-c CONFIG] [-i [INFO]] [-f] [-s] [--json] [--fail-on-warnings] Check Home Assistant configuration. optional arguments: -h, --help show this help message and exit --script {check_config} -c CONFIG, --config CONFIG Directory that contains the Home Assistant configuration -i [INFO], --info [INFO] Show a portion of the config -f, --files Show used configuration files -s, --secrets Show secret information --json Output JSON format --fail-on-warnings Exit non-zero if warnings are present Related topics[](https://www.home-assistant.io/docs/tools/check_config/#related-topics) ---------------------------------------------------------------------------------------- * [Validating the configuration](https://www.home-assistant.io/docs/configuration/#validating-the-configuration) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/tools/check_config/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/tools/check_config.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ftools%2Fcheck_config%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ftools%2Fcheck_config%2F%22&in=body "View given feedback for this page") --- # Creating an automation blueprint - Home Assistant Tip While the tutorial only shows how to create an automation blueprint, scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) also support blueprints in the same way. Creating an automation blueprint[](https://www.home-assistant.io/docs/blueprint/tutorial/#creating-an-automation-blueprint) ---------------------------------------------------------------------------------------------------------------------------- In this tutorial, we’re going to create an automation blueprint that controls a light based on a motion sensor. We will do this by taking an existing automation and converting it to a blueprint. ### Prerequisites[](https://www.home-assistant.io/docs/blueprint/tutorial/#prerequisites) * This tutorial assumes knowledge in the following topics: * [Editing the configuration file](https://www.home-assistant.io/docs/configuration/) * [YAML](https://www.home-assistant.io/docs/configuration/yaml/) , and specifically, [YAML used in automations](https://www.home-assistant.io/docs/automation/yaml/) * [Scripts](https://www.home-assistant.io/docs/scripts/) ### Creating an automation[](https://www.home-assistant.io/docs/blueprint/tutorial/#creating-an-automation) To create a blueprint, we first need to have a working automation. For this tutorial, we use a simple automation. The process for converting a complex automation is no different. The automation we’re going to use in this tutorial controls a light based on a motion sensor: triggers: - trigger: state entity_id: binary_sensor.motion_kitchen actions: - action: > {% if trigger.to_state.state == "on" %} light.turn_on {% else %} light.turn_off {% endif %} target: entity_id: light.kitchen The options that can be used with the `trigger` object are listed under [automation trigger variables](https://www.home-assistant.io/docs/automation/templating/#available-trigger-data) . In this example, a [state trigger](https://www.home-assistant.io/docs/automation/templating/#state) is used. `turn_on` and `turn_off` are [`homeassistant` actions](https://www.home-assistant.io/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[](https://www.home-assistant.io/docs/blueprint/tutorial/#creating-the-blueprint-file) Automation blueprints are YAML files (with the `.yaml` extension) and live in the `/blueprints/automation/` folder. You can create as many subdirectories in this folder as you want. To get started with our blueprint, we’re going to copy the above automation YAML and save it in that directory with the name `motion_light_tutorial.yaml`. #### Add basic blueprint metadata[](https://www.home-assistant.io/docs/blueprint/tutorial/#add-basic-blueprint-metadata) Home Assistant needs to know about the blueprint. This is achieved by adding a `blueprint:` section. It should contain the `domain` of the integration it is for (`automation`) and `name`, the name of your blueprint. Optionally, you can also include a `description` for your blueprint. Add this to the top of the file: blueprint: name: Motion Light Tutorial description: Turn a light on based on detected motion domain: automation #### Define the configurable parts as inputs[](https://www.home-assistant.io/docs/blueprint/tutorial/#define-the-configurable-parts-as-inputs) Now we have to decide what steps we want to make configurable. We want to make it as re-usable as possible, without losing its original intent of turning on a light-based on a motion sensor. Configurable parts in blueprints are called [inputs](https://www.home-assistant.io/docs/blueprint/schema/#blueprint-inputs) . To make the motion sensor entity configurable, we’re replacing the entity ID with a custom YAML tag `!input`. This YAML tag has to be combined with the name of the input: triggers: - trigger: state 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 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: actions: - action: > {% if trigger.to_state.state == "on" %} light.turn_on {% else %} light.turn_off {% endif %} target: !input target_light #### Add the inputs to the metadata[](https://www.home-assistant.io/docs/blueprint/tutorial/#add-the-inputs-to-the-metadata) All parts that are marked as inputs need to be added to the metadata. The minimum is that we add their names as used in the automation: blueprint: name: Motion Light Tutorial description: Turn a light on based on detected motion domain: automation input: motion_sensor: target_light: For more information on blueprint inputs, refer to the documentation of the [blueprint schema](https://www.home-assistant.io/docs/blueprint/schema/#input) Using your blueprint via configuration.yaml[](https://www.home-assistant.io/docs/blueprint/tutorial/#using-your-blueprint-via-configurationyaml) ------------------------------------------------------------------------------------------------------------------------------------------------- With the bare minimum metadata added, your blueprint is ready to use. Open your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) and add the following: automation tutorial: use_blueprint: path: motion_light_tutorial.yaml input: motion_sensor: binary_sensor.kitchen target_light: entity_id: light.kitchen Reload automations and your new automation should pop up. Because we configured the exact values as the original automation, they should work exactly the same. Improving the inputs[](https://www.home-assistant.io/docs/blueprint/tutorial/#improving-the-inputs) ---------------------------------------------------------------------------------------------------- Blueprints are easier to use if it’s easy to see what each field is used for. ### Add a user friendly names to the inputs[](https://www.home-assistant.io/docs/blueprint/tutorial/#add-a-user-friendly-names-to-the-inputs) We can improve this experience by adding names and descriptions to our inputs: blueprint: name: Motion Light Tutorial description: Turn a light on based on detected motion domain: automation input: motion_sensor: name: Motion Sensor description: This sensor will be synchronized with the light. target_light: name: Lights description: The lights to keep in sync. ### Describe the inputs[](https://www.home-assistant.io/docs/blueprint/tutorial/#describe-the-inputs) Our blueprint doesn’t currently describe what the inputs should contain. Without this information, Home Assistant will offer the user an empty text box. To instead allow Home Assistant to offer more assistance, we will use [selectors](https://www.home-assistant.io/docs/blueprint/selectors/) . Selectors describe a type and can be used to help the user pick a matching value. The selector for the motion sensor entity should describe that we want entities from the binary sensor domain that have the device class `motion`. The selector for the target light should describe that we want to target light entities. blueprint: name: Motion Light Tutorial domain: automation input: motion_sensor: name: Motion Sensor description: This sensor will be synchronized with the light. selector: entity: filter: - domain: binary_sensor device_class: motion target_light: name: Lights description: The lights to keep in sync. selector: target: entity: - domain: light By limiting our blueprint to working with lights and motion sensors, we unlock a couple of benefits: the UI will be able to limit suggested values to lights and motion sensors instead of all devices. It will also allow the user to pick an area to control the lights in. The final blueprint[](https://www.home-assistant.io/docs/blueprint/tutorial/#the-final-blueprint) -------------------------------------------------------------------------------------------------- After we have added all the steps, our blueprint will look like this: blueprint: name: Motion Light Tutorial description: Turn a light on based on detected motion domain: automation input: motion_sensor: name: Motion Sensor description: This sensor will be synchronized with the light. selector: entity: filter: - domain: binary_sensor device_class: motion target_light: name: Lights description: The lights to keep in sync. selector: target: entity: - domain: light triggers: - trigger: state entity_id: !input motion_sensor actions: - action: > {% if trigger.to_state.state == "on" %} light.turn_on {% else %} light.turn_off {% endif %} target: !input target_light Using the blueprint via the UI[](https://www.home-assistant.io/docs/blueprint/tutorial/#using-the-blueprint-via-the-ui) ------------------------------------------------------------------------------------------------------------------------ 1. To configure your blueprint via the UI, go to [**Settings** > **Automations & Scenes** > **Blueprints**](https://my.home-assistant.io/redirect/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. ![Screenshot of the blueprint UI](https://www.home-assistant.io/images/blueprints/tutorial-ui.png) Video tutorial[](https://www.home-assistant.io/docs/blueprint/tutorial/#video-tutorial) ---------------------------------------------------------------------------------------- This video tutorial explains how to create a blueprint that toggles a light on motion when the lux value is below a certain threshold. Share the love[](https://www.home-assistant.io/docs/blueprint/tutorial/#share-the-love) ---------------------------------------------------------------------------------------- The final step is to share this blueprint with others. For this tutorial we’re going to share it on GitHub Gists. ### Share informally[](https://www.home-assistant.io/docs/blueprint/tutorial/#share-informally) For this tutorial, we’re going to share it on GitHub Gists. This is a good option if you don’t want to publish your blueprint to a larger audience. 1. Go to [GitHub Gists](https://gist.github.com/) * **Gist description**: blueprint tutorial * **Filename including extension**: `motion_light_tutorial.yaml` * **Content** is the content of the blueprint file. 2. Select **Create Gist**. 3. To share your blueprint with other people, copy the URL of your new Gist. They can import it by going to [**Settings** > **Automations & Scenes** > **Blueprints**](https://my.home-assistant.io/redirect/blueprint_import) and select **Import blueprint**. 4. Celebrate! Cheers to you. You created your first blueprint and helped someone in the community. ### Share on the Blueprint Exchange[](https://www.home-assistant.io/docs/blueprint/tutorial/#share-on-the-blueprint-exchange) If you follow the [Rules and format for posting](https://www.home-assistant.io/get-blueprints) , you can share your blueprint on the Home Assistant Blueprint Exchange forum. This option is accessible to the general Home Assistant community but recommended only for your original blueprints. Please don’t post this tutorial to the Blueprint Exchange, but instead, remember this as an option for releasing your real blueprints. Related topics[](https://www.home-assistant.io/docs/blueprint/tutorial/#related-topics) ---------------------------------------------------------------------------------------- * [Editing the configuration file](https://www.home-assistant.io/docs/configuration/) * [YAML syntax](https://www.home-assistant.io/docs/configuration/yaml/) * [Yaml used in automations](https://www.home-assistant.io/docs/automation/yaml/) * [Scripts](https://www.home-assistant.io/docs/scripts/) * [Blueprint selectors](https://www.home-assistant.io/docs/blueprint/selectors/) * [Blueprint schema](https://www.home-assistant.io/docs/blueprint/schema/) * [About blueprints](https://www.home-assistant.io/docs/blueprint/) * [Using automation blueprints](https://www.home-assistant.io/docs/automation/using_blueprints/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/blueprint/tutorial/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/blueprint/tutorial.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fblueprint%2Ftutorial%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fblueprint%2Ftutorial%2F%22&in=body "View given feedback for this page") --- # Using automation blueprints - Home Assistant Automation blueprints are pre-made automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) that you can easily add to your Home Assistant instance. Each blueprint can be added as many times as you want. Quick links: * [Blueprints in the Home Assistant forums](https://www.home-assistant.io/get-blueprints) Blueprint automations[](https://www.home-assistant.io/docs/automation/using_blueprints/#blueprint-automations) --------------------------------------------------------------------------------------------------------------- Automations based on a blueprint need to be configured. What needs to be configured differs by blueprint. 1. To create your first automation based on a blueprint, go to **[Settings > Automations & Scenes > Blueprints](https://my.home-assistant.io/redirect/blueprints) **. 2. Find the blueprint that you want to use and select **Create Automation**. * This opens the automation editor with the blueprint selected. 3. Give it a name and configure the blueprint. 4. Select the blue **Save Automation** button in the bottom right corner. Done! If you want to revisit the configuration values, go to **[Settings > Automations & Scenes > Blueprints](https://my.home-assistant.io/redirect/blueprints) **. Importing blueprints[](https://www.home-assistant.io/docs/automation/using_blueprints/#importing-blueprints) ------------------------------------------------------------------------------------------------------------- Home Assistant can import blueprints from the Home Assistant forums, GitHub, and GitHub gists. 1. To import a blueprint, first [find a blueprint you want to import](https://www.home-assistant.io/get-blueprints) . * If you just want to practice importing, you can use this URL: https://github.com/home-assistant/core/blob/dev/homeassistant/components/automation/blueprints/motion_light.yaml 2. Go to **[Settings > Automations & Scenes > Blueprints](https://my.home-assistant.io/redirect/blueprints) **. 3. Select the blue **[Import Blueprint](https://my.home-assistant.io/redirect/blueprint_import) ** button in the bottom right. * A new dialog will pop-up asking you for the URL. 4. Enter the URL and select **Preview**. * This will load the blueprint and show a preview in the import dialog. * You can change the name and finish the import. The blueprint can now be used for creating automations. Editing an imported blueprint[](https://www.home-assistant.io/docs/automation/using_blueprints/#editing-an-imported-blueprint) ------------------------------------------------------------------------------------------------------------------------------- You can tweak an imported blueprint by “taking control” of this blueprint. Home Assistant then converts the blueprint automation into a regular automation, allowing you to make any tweak without having to fully re-invent the wheel. To edit an imported blueprint, follow these steps: 1. Go to **[Settings > Automations & Scenes > Blueprints](https://my.home-assistant.io/redirect/blueprints) **. 2. Select the blueprint from the list. 3. Select the and select **Take control**. 4. A preview of the automation is shown. * **Info**: By taking control, the blueprint is converted into an automation. You won’t be able to convert this back into a blueprint. * To convert it into an automation and take control, select **Yes**. * If you change your mind and want to keep the blueprint, select **No**. ![Screencast showing how to take control of a blueprint](https://www.home-assistant.io/images/blueprints/blueprint_take_control.webp) Re-importing a blueprint[](https://www.home-assistant.io/docs/automation/using_blueprints/#re-importing-a-blueprint) --------------------------------------------------------------------------------------------------------------------- Blueprints created by the community may go through multiple revisions. Sometimes a user creates a blueprint, the community provides feedback, new functionality is added. The quickest way to get these changes, is by re-importing the blueprint. This will overwrite the blueprint you currently have. Caution **Before you do this**: If the re-imported blueprint is not compatible, it can break your automations. * In this case, you will need to manually adjust your automations. ### To re-import a blueprint[](https://www.home-assistant.io/docs/automation/using_blueprints/#to-re-import-a-blueprint) 1. Go to **[Settings > Automations & Scenes > Blueprints](https://my.home-assistant.io/redirect/blueprints) **. 2. On the blueprint that you want to re-import, select the three dots menu, and select **Re-import blueprint**. Updating an imported blueprint in YAML[](https://www.home-assistant.io/docs/automation/using_blueprints/#updating-an-imported-blueprint-in-yaml) ------------------------------------------------------------------------------------------------------------------------------------------------- Blueprints created by the community may go through multiple revisions. Sometimes a user creates a blueprint, the community provides feedback, new functionality is added. If you do not want to [re-import the blueprint](https://www.home-assistant.io/docs/automation/using_blueprints/#re-importing-a-blueprint) for some reason, you can manually edit its YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) content to keep it up to date: 1. Navigate to the blueprints directory (`blueprints/automation/`). The location of this directory depends on the installation type. It’s similar to how you find [`configuration.yaml`](https://www.home-assistant.io/docs/configuration/#editing-configurationyaml) . 2. Next, you must find the blueprint to update. The path name of a blueprint consists of: * The username of the user that created it. The name depends on the source of the blueprint: the forum, or GitHub. * The name of the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file. For the forum it’s the title of the topic in the URL, for GitHub it’s the name of the YAML file. 3. Open the YAML file with your editor and update its contents. 4. Reload the automations for the changes to take effect. The new changes will appear to your existing automations as well. Finding new blueprints[](https://www.home-assistant.io/docs/automation/using_blueprints/#finding-new-blueprints) ----------------------------------------------------------------------------------------------------------------- The Home Assistant Community forums have a specific tag for blueprints. This tag is used to collect all blueprints. [Visit the Home Assistant forums](https://www.home-assistant.io/get-blueprints) Creating new blueprints[](https://www.home-assistant.io/docs/automation/using_blueprints/#creating-new-blueprints) ------------------------------------------------------------------------------------------------------------------- Using blueprints is nice and easy, but what if you could create that one missing blueprint that our community definitely needs? Learn more about blueprints by [reading our tutorial on creating a blueprint](https://www.home-assistant.io/docs/blueprint/tutorial/) . Troubleshooting missing automations[](https://www.home-assistant.io/docs/automation/using_blueprints/#troubleshooting-missing-automations) ------------------------------------------------------------------------------------------------------------------------------------------- When you’re creating automations using blueprints and they don’t appear in the UI, make sure that you add back `automation: !include automations.yaml` from the default configuration to your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) . #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/using_blueprints/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/using_blueprints.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Fusing_blueprints%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Fusing_blueprints%2F%22&in=body "View given feedback for this page") --- # Labels - Home Assistant 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[](https://www.home-assistant.io/docs/organizing/labels/#creating-a-label) ------------------------------------------------------------------------------------------- Follow these steps to create a new label from the **Labels** view. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/labels) and on top, select the **Labels** tab. 2. Select the **Create label** button. 3. In the dialog, enter the label details: * Give the label a **Name** (required). * Add an icon (We use [Material icons](https://pictogrammers.com/library/mdi/) ). * Add a **Color**. ![Create label dialog](https://www.home-assistant.io/images/organizing/create_label_01.png) 4. Select **Create**. **Result**: A new label is created. Applying labels[](https://www.home-assistant.io/docs/organizing/labels/#applying-labels) ----------------------------------------------------------------------------------------- Follow these steps to apply a label 1. To apply a label to an area: * Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) . * On the area card, select the 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 **[Settings > Devices & services](https://my.home-assistant.io/redirect/integrations) ** and open the respective tab. * Select the 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](https://www.home-assistant.io/images/organizing/labels_add_05.png) 3. To apply a label to an automation, scene, or script: * Go to [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) and open the respective tab. * Select the 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. Deleting a label[](https://www.home-assistant.io/docs/organizing/labels/#deleting-a-label) ------------------------------------------------------------------------------------------- Follow these steps to delete a label. It will be removed from all the list entries it was applied to. If you used this label in automations or script as targets, you need to adjust those. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/labels) 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. 3. Select **Delete**. 4. If you used this label in automations or script as targets, you need to adjust those. Removing labels[](https://www.home-assistant.io/docs/organizing/labels/#removing-labels) ----------------------------------------------------------------------------------------- 1. Go to the data table that contains the element from which you want to remove the label: * Go to **[Settings > Devices & services](https://my.home-assistant.io/redirect/integrations) ** and open the respective tab. * Or, go to [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) and open the respective tab. 2. Select the 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**. * Then, deselect the checkbox for the label you want to remove. Related topics[](https://www.home-assistant.io/docs/organizing/labels/#related-topics) --------------------------------------------------------------------------------------- * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Floors](https://www.home-assistant.io/docs/organizing/floors/) * [Categories](https://www.home-assistant.io/docs/organizing/categories/) * [Using labels in templates](https://www.home-assistant.io/docs/configuration/templating/#labels) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/organizing/labels/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/organizing/labels.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Forganizing%2Flabels%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Forganizing%2Flabels%2F%22&in=body "View given feedback for this page") --- # Frontend of Home Assistant - Home Assistant The Home Assistant [frontend integration](https://www.home-assistant.io/integrations/frontend/) provides the graphical user interface that allows you to browse and control the state of your house, manage automations, and configure integrations. ![](https://www.home-assistant.io/images/frontend/ui2022.png) Home Assistant comes with [built-in dashboards](https://www.home-assistant.io/dashboards/dashboards/#home-assistant-built-in-dashboards) . But you can also create and customize your own dashboards. Creating and styling your own dashboards[](https://www.home-assistant.io/docs/frontend/#creating-and-styling-your-own-dashboards) ---------------------------------------------------------------------------------------------------------------------------------- To learn how to create and style your own dashboards, refer to the following topics: * [Dashboard introduction](https://www.home-assistant.io/dashboards/) * [Types of dashboards](https://www.home-assistant.io/dashboards/dashboards/) * [Views](https://www.home-assistant.io/dashboards/views/) * [Dashboard cards](https://www.home-assistant.io/dashboards/cards/) * [Badges](https://www.home-assistant.io/dashboards/badges/) * [Themes](https://www.home-assistant.io/integrations/frontend/) * [Icons](https://www.home-assistant.io/docs/frontend/icons/) Organizing and filtering data[](https://www.home-assistant.io/docs/frontend/#organizing-and-filtering-data) ------------------------------------------------------------------------------------------------------------ To learn how to organize and filter your data on an existing dashboard, refer to the following topics: * [Grouping](https://www.home-assistant.io/docs/organizing/) into [areas](https://www.home-assistant.io/docs/organizing/areas/) , [floors](https://www.home-assistant.io/docs/organizing/floors/) , [labels](https://www.home-assistant.io/docs/organizing/labels/) , and [categories](https://www.home-assistant.io/docs/organizing/categories/) * [Filtering](https://www.home-assistant.io/docs/organizing/tables) User- or browser-dependent settings, general settings[](https://www.home-assistant.io/docs/frontend/#user--or-browser-dependent-settings-general-settings) ----------------------------------------------------------------------------------------------------------------------------------------------------------- ### User- or browser-dependent settings[](https://www.home-assistant.io/docs/frontend/#user--or-browser-dependent-settings) Some of the frontend settings depend on the user. Other settings can be set by client. This allows you for example to have different languages per user, and a different theme depending on the device that is used to display Home Assistant. To change these settings, in the bottom left, select your username to open your [**User profile**](https://my.home-assistant.io/redirect/profile) . * To change general settings such as language, number and time format, go to the **User settings**. * To change browser dependent settings such as the theme, default dashboard, or whether or not to show the sidebar, change the **Browser settings**. ### Themes[](https://www.home-assistant.io/docs/frontend/#themes) Themes can be set per browser. In the [**User profile**](https://my.home-assistant.io/redirect/profile) , you can define some theme settings, such as whether you want a light or dark theme. However, more detailed theme settings require YAML configuration. Refer to the documentation of the [frontend integration](https://www.home-assistant.io/integrations/frontend/) . ### General settings[](https://www.home-assistant.io/docs/frontend/#general-settings) Some of the settings, such as location and currency, were defined during the onboarding process. They can be changed under [**Settings** > **System** > **General**](https://my.home-assistant.io/redirect/general) . Refer to the documentation on [setup basic information](https://www.home-assistant.io/docs/configuration/basic/) . Apps for Android and iOS[](https://www.home-assistant.io/docs/frontend/#apps-for-android-and-ios) -------------------------------------------------------------------------------------------------- If you are looking for information on Home Assistant for Android or iOS, refer to the [documentation for the Companion Apps](https://companion.home-assistant.io/) . #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/frontend/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/frontend.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ffrontend%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ffrontend%2F%22&in=body "View given feedback for this page") --- # Grouping your assets - Home Assistant 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](https://www.home-assistant.io/docs/organizing/#area) , [floors](https://www.home-assistant.io/docs/organizing/#floor) , [labels](https://www.home-assistant.io/docs/organizing/#labels) , [categories](https://www.home-assistant.io/docs/organizing/#category) and [group integration](https://www.home-assistant.io/docs/organizing/#group-integration) . | Taxonomy | Automation target | Entity can have multiple | | --- | --- | --- | | Area | | | | Floor | | | | Label | | | | Category | | | | Group Integration | | | Area[](https://www.home-assistant.io/docs/organizing/#area) ------------------------------------------------------------ * Groups devicesA device is a model representing a physical or logical unit that contains entities. and entitiesAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) . * 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 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](https://www.home-assistant.io/dashboards/area/) . Floor[](https://www.home-assistant.io/docs/organizing/#floor) -------------------------------------------------------------- * Groups areas. * DevicesA device is a model representing a physical or logical unit that contains entities. and entitiesAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) cannot be assigned to floors, but to areas only. * Can have multiple areas. * 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. ![Screenshots showing areas settings page, which now also shows the areas grouped by floor.](https://www.home-assistant.io/images/organizing/floors.png) Labels[](https://www.home-assistant.io/docs/organizing/#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. * 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.](https://www.home-assistant.io/images/organizing/labels.png) Category[](https://www.home-assistant.io/docs/organizing/#category) -------------------------------------------------------------------- * Groups items in a table. * Categories are unique for each table. The automations page can have different categories than the scene, scripts, or helpers settings page. ![Screenshots the new categories. Automations are grouped into their categories, making it easier to get an overview or to filter them.](https://www.home-assistant.io/images/organizing/categories.png) Group Integration[](https://www.home-assistant.io/docs/organizing/#group-integration) -------------------------------------------------------------------------------------- * Designed to combine multiple entities into one entity representing the group. * The combined entity can also have an area and labels. * Can be used in automations and scripts as a target for actions. * Does not assist with organizing entities in the UI like the other methods above. For example, you cannot use group integration to sort or filter other entities. Related topics[](https://www.home-assistant.io/docs/organizing/#related-topics) -------------------------------------------------------------------------------- * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Floors](https://www.home-assistant.io/docs/organizing/floors/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) * [Categories](https://www.home-assistant.io/docs/organizing/categories/) * [Group integration](https://www.home-assistant.io/integrations/group/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/organizing/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/organizing.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Forganizing%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Forganizing%2F%22&in=body "View given feedback for this page") --- # Categories - Home Assistant 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[](https://www.home-assistant.io/docs/organizing/categories/#creating-a-category) ----------------------------------------------------------------------------------------------------- Follow these steps to create a new category. 1. Go to [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) and open the respective tab. 2. In the top left, select the **Filters** button. ![Select the filter button](https://www.home-assistant.io/images/organizing/filters_01.png) 3. Select **Category**, then **Add category**. 4. Enter a name, select an icon and select **Add**. **Result**: A new category is created. Assigning a category[](https://www.home-assistant.io/docs/organizing/categories/#assigning-a-category) ------------------------------------------------------------------------------------------------------- 1. Go to [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) 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. * 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 multi-select 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. 4. Once categories are applied, the table items are grouped by those categories. * The example shows 2 categories: Coffee and housekeeping. ![Group table items by category](https://www.home-assistant.io/images/organizing/category_02.png) Editing or deleting a category[](https://www.home-assistant.io/docs/organizing/categories/#editing-or-deleting-a-category) --------------------------------------------------------------------------------------------------------------------------- To rename or delete a category, follow these steps: 1. Go to [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) and open the respective tab. 2. In the top left, select the **Filters** button. ![Select the filter button](https://www.home-assistant.io/images/organizing/filters_01.png) 3. In the list, find the category you want to edit and select the three dots menu next to it. 4. Select **Edit category** or **Delete category**. ![Screenshot showing the edit and delete buttons for categories](https://www.home-assistant.io/images/organizing/edit-delete-category.png) Related topics[](https://www.home-assistant.io/docs/organizing/categories/#related-topics) ------------------------------------------------------------------------------------------- * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Floors](https://www.home-assistant.io/docs/organizing/floors/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/organizing/categories/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/organizing/categories.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Forganizing%2Fcategories%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Forganizing%2Fcategories%2F%22&in=body "View given feedback for this page") --- # General troubleshooting - Home Assistant This page provides some information about more generic troubleshooting topics. Home Assistant went into recovery mode[](https://www.home-assistant.io/docs/troubleshooting_general/#home-assistant-went-into-recovery-mode) --------------------------------------------------------------------------------------------------------------------------------------------- ### Symptom: Home Assistant is in recovery mode[](https://www.home-assistant.io/docs/troubleshooting_general/#symptom-home-assistant-is-in-recovery-mode) On top of the page you see a red banner. On the **Overview** page, you see a **Recovery mode** notification. ![image](https://www.home-assistant.io/images/docs/troubleshooting/recovery_mode_active.png) ### Description[](https://www.home-assistant.io/docs/troubleshooting_general/#description) When Home Assistant is in recovery mode, there was an issue with the configuration. Recovery mode loads a minimum set of integrations to allow troubleshooting the configuration. Recovery mode will use the parts of the configuration that was used the last time Home Assistant started successfully. You can still see the user interface, the settings, and add-ons. ### Resolution[](https://www.home-assistant.io/docs/troubleshooting_general/#resolution) You need to identify the issue in the configuration files and fix it there. The issue could be caused by something as simple as an invalid YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file. * If you are running Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users., you can install an add-on such as Studio Code Server to edit the configuration file if needed. * If you are still logged in, you can [edit your configuration](https://www.home-assistant.io/docs/configuration/#editing-configurationyaml) . * In the Home Assistant user interface, open the add-on you usually use and edit the configuration file. * Restart Home Assistant. * If you are locked out because you forgot your password, you cannot edit the configuration file from the user interface. Follow the steps to [reset your password](https://www.home-assistant.io/docs/locked_out/) . Restarting Home Assistant in safe mode[](https://www.home-assistant.io/docs/troubleshooting_general/#restarting-home-assistant-in-safe-mode) --------------------------------------------------------------------------------------------------------------------------------------------- If your Home Assistant is acting up and you cannot identify a root cause, you can use **Safe mode** to narrow down the number of possible causes. **Safe mode** loads Home Assistant Core, but no custom integrations, no custom cards, and no custom themes. If the issue does not persist in **Safe mode**, the issue is not with Home Assistant Core. Before reporting an issue, check if the issue persists in **Safe mode**. You can enable Safe mode in several ways: * From the UI: * Go to **Settings** > **System** > **Restart Home Assistant** (top right) > **Restart Home Assistant in safe mode**. * From the [command line](https://www.home-assistant.io/common-tasks/os/#home-assistant-via-the-command-line) : * Run: ha core restart --safe-mode * By creating a file in the configuration directory: * Create an empty file named `safe-mode` in your Home Assistant configuration directory. Home Assistant will detect this file on startup and automatically boot into Safe mode. I don’t see any updates[](https://www.home-assistant.io/docs/troubleshooting_general/#i-dont-see-any-updates) -------------------------------------------------------------------------------------------------------------- Typically, updates are shown at the top of the **Settings** page. If you don’t see them there, the **Visibility** option might be disabled. ### Resolution[](https://www.home-assistant.io/docs/troubleshooting_general/#resolution-1) 1. On the **System** page, in the top-right corner, select the three dots menu and select **Check for updates**. 2. Go to [**System** > **Updates**](https://my.home-assistant.io/redirect/updates) . * Select the update notification. * Select the cogwheel , then set **Visible** to active. Related topics[](https://www.home-assistant.io/docs/troubleshooting_general/#related-topics) --------------------------------------------------------------------------------------------- * [Editing your configuration](https://www.home-assistant.io/docs/configuration/#editing-configurationyaml) * [Recovery mode integration](https://www.home-assistant.io/integrations/recovery_mode/) * [Resetting your password](https://www.home-assistant.io/docs/locked_out/) * [Home assistant via command line](https://www.home-assistant.io/common-tasks/os/#home-assistant-via-the-command-line) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/troubleshooting_general/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/troubleshooting_general.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ftroubleshooting_general%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ftroubleshooting_general%2F%22&in=body "View given feedback for this page") --- # Scenes - Home Assistant You can create scenes that capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red. Scenes are available as an entity through the standalone [Scene integration](https://www.home-assistant.io/integrations/scene/) but can also be embedded in automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) and scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) . # Example configuration.yaml entry scene: - name: Romantic entities: light.tv_back_light: "on" light.ceiling: state: "on" xy_color: [0.33, 0.66] brightness: 200 - name: Movies entities: light.tv_back_light: state: "on" brightness: 125 light.ceiling: off media_player.sony_bravia_tv: state: "on" source: HDMI 1 How to configure your scene[](https://www.home-assistant.io/docs/scene/#how-to-configure-your-scene) ----------------------------------------------------------------------------------------------------- In the scene you define in your YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) files, please ensure you use all required parameters as listed below. #### Configuration Variables[](https://www.home-assistant.io/docs/scene/#scene-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) name string Required[](https://www.home-assistant.io/docs/scene/#name) Friendly name of the scene. entities list Required[](https://www.home-assistant.io/docs/scene/#entities) Entities to control and their desired state. 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 action `scene.turn_on` (there is no ‘scene.turn\_off’ action). # Example automation automation: triggers: - trigger: state entity_id: device_tracker.sweetheart from: "not_home" to: "home" actions: - action: scene.turn_on target: entity_id: scene.romantic Applying a scene without defining it[](https://www.home-assistant.io/docs/scene/#applying-a-scene-without-defining-it) ----------------------------------------------------------------------------------------------------------------------- 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. # Example automation automation: triggers: - trigger: state entity_id: device_tracker.sweetheart from: "not_home" to: "home" actions: - action: scene.apply data: entities: light.tv_back_light: state: "on" brightness: 100 light.ceiling: off media_player.sony_bravia_tv: state: "on" source: "HDMI 1" Using scene transitions[](https://www.home-assistant.io/docs/scene/#using-scene-transitions) --------------------------------------------------------------------------------------------- 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 light will transition to the scene in 2.5 seconds. # Example automation automation: triggers: - trigger: state entity_id: device_tracker.sweetheart from: "not_home" to: "home" actions: - action: scene.turn_on target: entity_id: scene.romantic data: transition: 2.5 Transitions are currently only support by lights, which in their turn, have to support it as well. However, the scene itself does not have to consist of only lights to have a transition set. Reloading scenes[](https://www.home-assistant.io/docs/scene/#reloading-scenes) ------------------------------------------------------------------------------- Whenever you make a change to your scene configuration, you can call the `scene.reload` action to reload the scenes. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/scene/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/scene.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fscene%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fscene%2F%22&in=body "View given feedback for this page") --- # Quick bar - Home Assistant The **Quick bar** allows you to quickly look up entities or run commands without needing to navigate away from your current view (Similar to the “quick open” feature in VS Code, Chrome Developer Tools, etc). It can be launched from anywhere in the frontend using [hotkeys](https://www.home-assistant.io/docs/tools/quick-bar/#hotkeys) . ![Quick Bar](https://www.home-assistant.io/images/docs/quick-bar/quick-bar-demo.gif) Quick Bar for accessing entities and running commands Hotkeys[](https://www.home-assistant.io/docs/tools/quick-bar/#hotkeys) ----------------------------------------------------------------------- Type these from anywhere in the application to launch the dialog. | Mode | Hotkey | Switch Modes | | --- | --- | --- | | Entity Filter | `e` | Type `>` at start of input to switch to command palette. Type `#` at start of input to switch to device filter. | | Command Palette | `c` | Remove `>` from start of input to switch to entity filter. | | Device Filter | `d` | Remove `#` from start of input to switch to entity filter. | | Create [`my`](https://www.home-assistant.io/integrations/my)
link | `m` | Open a new tab to create a my link to the page you are on. | | Assist | `a` | Open the Home Assistant Assist dialog. | 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. Entity filter[](https://www.home-assistant.io/docs/tools/quick-bar/#entity-filter) ----------------------------------------------------------------------------------- _Hotkey: `e`_ Similar to [**Settings** > **Devices & services** > **Entities**](https://my.home-assistant.io/redirect/entities) , but more lightweight and accessible from anywhere in the frontend. ![Quick Bar](https://www.home-assistant.io/images/docs/quick-bar/quick-bar-entity-filter.gif) Filter for entities in Quick Bar's entity filter mode Once launched, start typing your entity id (or [“bits and pieces” of your entity id](https://www.home-assistant.io/docs/tools/quick-bar/#search-by-bits-and-pieces-rather-than-an-exact-substring) ) to get back a filtered list of entities. Clicking on an entity (or hitting `enter` when the desired entity is highlighted) will open the “More Info” dialog for that entity. This is helpful when, say, you are in the middle of writing an automation and need some quick insight about an entity but don’t want to navigate away to Developer Tools. Device filter[](https://www.home-assistant.io/docs/tools/quick-bar/#device-filter) ----------------------------------------------------------------------------------- _Hotkey: `d`_ Similar to [**Settings** > **Devices & services** > **Devices**](https://my.home-assistant.io/redirect/entities) , but accessible from anywhere in the frontend. Once launched, start typing your device name to get back a filtered list of your devices. Clicking on a device (or hitting `enter` when the desired device is highlighted) will open the selected device detail page. This is helpful when you need to quickly access a device’s detail page without navigating your way through the menu. Command palette[](https://www.home-assistant.io/docs/tools/quick-bar/#command-palette) --------------------------------------------------------------------------------------- _Hotkey: `c`_ Run various commands from anywhere without having to navigate to another view. ![Quick Bar](https://www.home-assistant.io/images/docs/quick-bar/quick-bar-command-mode.gif) Run commands in Quick Bar's "command palette" ### Currently-supported commands[](https://www.home-assistant.io/docs/tools/quick-bar/#currently-supported-commands) | Type | Available | | --- | --- | | Navigate | All entries in the sidebar and settings | | Reload | All currently-supported “Reload {domain}” actions.
_(E.g., “Reload Scripts”)_ | | Server | Restart/Stop | My links[](https://www.home-assistant.io/docs/tools/quick-bar/#my-links) ------------------------------------------------------------------------- _Hotkey: `m`_ Create [`my`](https://www.home-assistant.io/integrations/my) links from any supported page in the user interface, when invoked on a supported page it will open a new tab that will allow you to share the link in different formats. Assist[](https://www.home-assistant.io/docs/tools/quick-bar/#assist) --------------------------------------------------------------------- _Hotkey: `a`_ Opens the Assist dialog to interact with Home Assistant using your voice or by text. This feature is only available if you have set up a voice assistant. Learn more about [voice assistants](https://www.home-assistant.io/voice_control) . Disabling shortcuts[](https://www.home-assistant.io/docs/tools/quick-bar/#disabling-shortcuts) ----------------------------------------------------------------------------------------------- You can enable or disable all of Home Assistant’s keyboard shortcuts by going to your User Profile and clicking the “Keyboard Shortcuts” toggle button. ![Toggle for enabling or disabling keyboard shortcuts](https://www.home-assistant.io/images/docs/quick-bar/disable-shortcuts-toggle.png) Toggle button for enabling/disabling keyboard shortcuts added by Home Assistant. Tips[](https://www.home-assistant.io/docs/tools/quick-bar/#tips) ----------------------------------------------------------------- ### Search by “bits and pieces” rather than an exact substring[](https://www.home-assistant.io/docs/tools/quick-bar/#search-by-bits-and-pieces-rather-than-an-exact-substring) We know something like “**light.ch**” should match “**light.ch**andelier”. Similarly, “**telev**” should match “media\_player.**telev**ision”. But with Quick Bar, “**lich**” would also match “**li**ght.**ch**andelier”, and “**plyrtv**” would also match “media\_**pl**a**y**e**r**.**t**ele**v**ision”. It checks letter _sequences_ rather than exact substrings. One nice use-case for this is that you can quickly filter out an entire domain of entities with just a couple letters and a period. For example, “**li.**” will match any “**light.**\*” entities. Continuing with “li.ch” would bring up the chandelier right away. ### Filters work against friendly name too[](https://www.home-assistant.io/docs/tools/quick-bar/#filters-work-against-friendly-name-too) If “light.hue\_ceiling\_light” has been named “Chandelier”, you can type either “hue\_ceil” or “chand” to find it. ### Use the enter key any time to open the top result in the list[](https://www.home-assistant.io/docs/tools/quick-bar/#use-the-enter-key-any-time-to-open-the-top-result-in-the-list) As soon as the item you wanted shows up at the top of your filtered results, just hit “enter” to activate it – no need to arrow down to the item, or click with your mouse. ### Use arrow keys to move around the list[](https://www.home-assistant.io/docs/tools/quick-bar/#use-arrow-keys-to-move-around-the-list) When in the text field, use the down arrow `↓` to navigate down the item list. Hit `enter` to activate the currently-highlighted row. When in the item list, use the up arrow `↑` to navigate up the item list, and to get back into the text field. ### Typing more letters will always add to your filter string[](https://www.home-assistant.io/docs/tools/quick-bar/#typing-more-letters-will-always-add-to-your-filter-string) Say you’ve just used arrow keys to navigate half-way down the list, and want to add more text to your filter. You don’t need to click back into the text field, just start typing new letters and they’ll append to your filter. Troubleshooting[](https://www.home-assistant.io/docs/tools/quick-bar/#troubleshooting) --------------------------------------------------------------------------------------- ### Dialog doesn’t launch using hotkeys[](https://www.home-assistant.io/docs/tools/quick-bar/#dialog-doesnt-launch-using-hotkeys) There are a few possible reasons why the quick bar dialog won’t launch: 1. Your user is not an admin. 2. The application lost focus. Try clicking into the main content area of the application and typing the shortcut again. 3. You have disabled Keyboard Shortcuts in your User Profile settings. 4. Shortcut is marked by browser as non-overridable. Firefox does this with some shortcuts, for example. But this shouldn’t be a problem with single-key shortcuts currently used by the Quick Bar. 5. Some other application or browser extension is using or overriding the shortcut. Try disabling the extension. ### A command is missing[](https://www.home-assistant.io/docs/tools/quick-bar/#a-command-is-missing) The command list only shows commands that are available to you based on your user settings, and loaded integrations. For example, if you don’t have `automations:` in your config, then you won’t see the “Reload Automations” command. If “Advanced Mode” is turned off in User Settings, then any command related to advanced mode will not appear in the list. If a command is missing that you feel is in error, please create an issue on GitHub. ### Shortcuts interfere with accessibility tools, browser extensions, or are otherwise annoying[](https://www.home-assistant.io/docs/tools/quick-bar/#shortcuts-interfere-with-accessibility-tools-browser-extensions-or-are-otherwise-annoying) You can [disable shortcuts](https://www.home-assistant.io/docs/tools/quick-bar/#disabling-shortcuts) in your User settings. Please consider submitting an issue explaining why the shortcut was disruptive to you. Keyboard shortcuts are new to Home Assistant, and getting them right is a challenge for any Web application. We rely on user feedback to ensure the experience is minimally-disruptive. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/tools/quick-bar/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/tools/quick-bar.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ftools%2Fquick-bar%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ftools%2Fquick-bar%2F%22&in=body "View given feedback for this page") --- # Areas - Home Assistant An area in Home Assistant is a logical grouping of devicesA device is a model representing a physical or logical unit that contains entities. and entitiesAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) 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 floorsA floor in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of areas that are meant to match the physical floors in your home. Devices & entities are not assigned to floors 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. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/floors/) . Areas can also be used to automatically generate cards, such as the [Area card](https://www.home-assistant.io/dashboards/area/) . Creating an area[](https://www.home-assistant.io/docs/organizing/areas/#creating-an-area) ------------------------------------------------------------------------------------------ Follow these steps to create a new area from the **Areas** view. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) and select **Create area**. 2. In the dialog, enter the area details: * Give the area a **Name** (required). * Add an icon (We use [Material icons](https://pictogrammers.com/library/mdi/) ). * Assign the area to a floor. * If you have not created floors yet, you can [create a new floor](https://www.home-assistant.io/docs/organizing/floors/#creating-a-floor) . * The number can be negative. For example for underground floors. * This number can later be used for sorting. * Add an image representing that area. * Add an **Alias**. * Aliases are alternative names used in [voice assistants](https://www.home-assistant.io/voice_control/aliases/) to refer to an area, entity, or floor. ![Create area dialog](https://www.home-assistant.io/images/organizing/create_area_01.png) 3. Select **Add**. **Result**: A new area is created. Assigning areas to floors and add labels[](https://www.home-assistant.io/docs/organizing/areas/#assigning-areas-to-floors-and-add-labels) ------------------------------------------------------------------------------------------------------------------------------------------ If an area has not yet been assigned to a floorA floor in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of areas that are meant to match the physical floors in your home. Devices & entities are not assigned to floors 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. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/floors/) , it is shown in the **Unassigned areas** section. Follow these steps to assign an area to a floor. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) and select **Create area**. 2. On the area card, select the edit button. 3. In the dialog, select the floorA floor in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of areas that are meant to match the physical floors in your home. Devices & entities are not assigned to floors 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. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/floors/) and add labelsLabels in Home Assistant allow [grouping](https://www.home-assistant.io/docs/organizing/) 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. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/labels/) if you like. Assigning an area to multiple items[](https://www.home-assistant.io/docs/organizing/areas/#assigning-an-area-to-multiple-items) -------------------------------------------------------------------------------------------------------------------------------- You can assign an area to multiple items at once in the automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) , sceneScenes capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red. [\[Learn more\]](https://www.home-assistant.io/integrations/scene/) , scriptScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) , and deviceA device is a model representing a physical or logical unit that contains entities. pages. 1. Depending on what you want to assign, go to one of the following pages: * For automations, scripts, or scenes [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) and open the respective tab. * For devices, go to [**Settings** > **Devices & services** > **Devices**](https://my.home-assistant.io/redirect/devices) . 2. In the list, [select all the items](https://www.home-assistant.io/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](https://www.home-assistant.io/images/organizing/area_assign_devices.png) 3. In the top right corner, select **Move to area** and select the target area from the list. Editing an area[](https://www.home-assistant.io/docs/organizing/areas/#editing-an-area) ---------------------------------------------------------------------------------------- Follow these steps to edit an area. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) and on the area card, select the 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/) ). * Assign the area to a floor. * If you have not created floors yet, you can [create a new one](https://www.home-assistant.io/docs/organizing/floors/#creating-a-floor) . * The number can be negative. For example for underground floors. * This number can later be used for sorting. * Add an image representing that area. * Add an **Alias**. * Aliases are alternative names used in [voice assistants](https://www.home-assistant.io/voice_control/aliases/) to refer to an area, entity, or floor. Reordering areas on built-in dashboards[](https://www.home-assistant.io/docs/organizing/areas/#reordering-areas-on-built-in-dashboards) ---------------------------------------------------------------------------------------------------------------------------------------- Follow these steps to rearrange floors and areas on the built-in dashboards (such as **Overview**, **Lights**, and **Security**). 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) . 2. There are 2 options to rearrange items: * **Option 1**: Use drag-and-drop. * **Option 2**: In the top-right corner, select the three dots menu and select **Reorder floors and areas**. * In the dialog, move the floors or areas you want to rearrange: ![Reorder floors and areas](https://www.home-assistant.io/images/organizing/reorder-areas-menu.png) Deleting an area[](https://www.home-assistant.io/docs/organizing/areas/#deleting-an-area) ------------------------------------------------------------------------------------------ Follow these steps to delete an area. It will be removed from all the floors it was assigned to. All the devices that were assigned to this area will become unassigned. If you used this area in automations or script as targets, or with voice assistant, these will no longer work. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) and select the area card. 2. In the top right corner, select the three dots menu. Then, select **Delete**. ![Delete area](https://www.home-assistant.io/images/organizing/area_delete.png) 3. If you used this area in automations or script as targets, or with voice assistant, they will no longer work. * You can adjust or delete the related scripts or automations. 4. If you still had devices in that area, they are no longer assigned to any room. * If you have moved the devices, you can now reassign them to a new area. Related topics[](https://www.home-assistant.io/docs/organizing/areas/#related-topics) -------------------------------------------------------------------------------------- * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Grouping your assets](https://www.home-assistant.io/docs/organizing/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) * [Categories](https://www.home-assistant.io/docs/organizing/categories/) * [Using areas in template](https://www.home-assistant.io/docs/configuration/templating/#areas) * [Home dashboard](https://www.home-assistant.io/dashboards/dashboards/#home-dashboard) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/organizing/areas/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/organizing/areas.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Forganizing%2Fareas%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Forganizing%2Fareas%2F%22&in=body "View given feedback for this page") --- # Developer tools - Home Assistant The dashboard contains a section called **Developer tools**. ![](https://www.home-assistant.io/images/screenshots/developer-tools.png) Screenshot of Home Assistant's developer tools. | Section | Description | | --- | --- | | YAML | Lets you validate the configuration and trigger a reload or restart | | States | Sets the representation of an entity | | Actions | Performs actions from integrations | | Template | Renders templates | | Events | Fires events | | Statistics | Shows a list of long-term statistic entities | | Assist | Lets you see how Home Assistant Assist processes a sentence | What can I do with Developer Tools?[](https://www.home-assistant.io/docs/tools/dev-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 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[](https://www.home-assistant.io/docs/tools/dev-tools/#yaml-tab) ------------------------------------------------------------------------- The YAML tab provides buttons to trigger a check of configuration files and to reload the configuration. Reloading is needed to apply changes that you’ve made to the configuration. It is almost the same as the option under **Settings** > three dots menu (top right) > **Restart Home Assistant** > **Quick reload**. The only difference is that **Quick reload** reloads all the configuration, whereas this YAML tab allows you to only reload one specific configuration at a time. ### Reloading the YAML configuration[](https://www.home-assistant.io/docs/tools/dev-tools/#reloading-the-yaml-configuration) For configuration changes to become effective, the configuration must be reloaded. Most integrations in Home Assistant (that do not interact with devicesA device is a model representing a physical or logical unit that contains entities. or servicesThe term “service” in Home Assistant is used in the sense of an **information service**. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called _service_ to avoid confusion, as it does not come with a piece of hardware.) can reload changes made to their configuration in `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) without needing to restart Home Assistant. 1. Go to [**Developer Tools** > **YAML**](https://my.home-assistant.io/redirect/server_controls) and scroll down to the YAML configuration reloading section (alternatively, hit [“c”](https://www.home-assistant.io/docs/tools/quick-bar/) anywhere in the UI and search for “reload”). * You are presented with a list of integrations, such as **Automations** or **Conversation**. ![Reload configuration changes](https://www.home-assistant.io/images/docs/configuration/reloading_config.png) 2. Depending on what you find in the list, you can proceed with either reloading or you need to restart Home Assistant: * If the integration is listed, select it to reload the settings. * For example, if you’ve changed the [General settings](https://www.home-assistant.io/docs/configuration/basic/) , you can select **Location & customizations** to apply those changes. * If the integration is not listed, you need to **Restart** Home Assistant for changes to take effect. States tab[](https://www.home-assistant.io/docs/tools/dev-tools/#states-tab) ----------------------------------------------------------------------------- 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 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 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”. Actions tab[](https://www.home-assistant.io/docs/tools/dev-tools/#actions-tab) ------------------------------------------------------------------------------- This section is used to perform actions that are available in Home Assistant. 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 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. 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 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 **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 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. entity_id: light.bedroom brightness: 255 rgb_color: [255, 0, 0] Template editor tab[](https://www.home-assistant.io/docs/tools/dev-tools/#template-editor-tab) ----------------------------------------------------------------------------------------------- The template editor provides a way to quickly test templates prior to placing them into automations and scripts. A code editor is on the left side and your real-time output is displayed in the preview on the right side. By default, this will contain sample code that illustrates how templates can be written and tested. This sample code can be removed and replaced with your own. You can restore the default example by pressing the “Reset to Demo Template” button beneath the code editor. For more information about Jinja2, visit [Jinja2 documentation](https://jinja.palletsprojects.com/en/latest/templates/) , and also read templating document [here](https://www.home-assistant.io/docs/configuration/templating) . Events tab[](https://www.home-assistant.io/docs/tools/dev-tools/#events-tab) ----------------------------------------------------------------------------- In the Events section, you can either fire an event on the event bus or subscribe to an event type in order to view the event data JSON. ### Fire an event[](https://www.home-assistant.io/docs/tools/dev-tools/#fire-an-event) To fire an event, simply type the name of the event, and pass the event data in JSON format. For example, to fire a custom event, enter the `event_type` as `event_light_state_changed` and the event data JSON as state: on If there is an automation that handles that event, it will be automatically triggered. See below: - alias: "Capture Event" triggers: - trigger: event event_type: event_light_state_changed actions: - action: notify.notify data: message: "Light is turned " ### Subscribe to an event[](https://www.home-assistant.io/docs/tools/dev-tools/#subscribe-to-an-event) To subscribe to an event, enter the event event type under “Listen to events” and click “Start listening”. Some events types are listed in the Events section under “Active listeners”. You can usually find information about event types for a particular integration in its documentation. You can then examine the event data JSON to find the correct parameters for your automations. For example, subscribing to the event type `shelly.click` of the Shelly integration, returns event data JSON similar to the following on a button press. Event 0 fired 9:53 AM: { "event_type": "shelly.click", "data": { "device_id": "e09c64a22553484d804353ef97f6fcd6", "device": "shellybutton1-A4C12A45174", "channel": 1, "click_type": "single" }, "origin": "LOCAL", "time_fired": "2021-04-28T08:53:12.755729+00:00", "context": { "id": "e0f379706563aaa0c2c1fda5174b5a0e", "parent_id": null, "user_id": null } } Statistics tab[](https://www.home-assistant.io/docs/tools/dev-tools/#statistics-tab) ------------------------------------------------------------------------------------- The **Statistics** tab shows a list of long-term statistic entities. If the long term statistics is not working for an entity, a **Fix Issue** link is shown. Select it to view a description of the issue. There might also be an option to fix the issue. ![Statistics issue message](https://www.home-assistant.io/images/docs/developer-tools/statistics_issue.png) Another use of the [statistics developer tool](https://my.home-assistant.io/redirect/developer_statistics) is to correct any measurements. Select the icon. Use date & time to search for the incorrect data point and adjust the value. ![Screenshot showing adjusting the long-term statistic history value](https://www.home-assistant.io/images/docs/developer-tools/adjust-statistics.png) Assist tab[](https://www.home-assistant.io/docs/tools/dev-tools/#assist-tab) ----------------------------------------------------------------------------- The **Assist** tab lets you see how Home Assistant’s Assist processes a sentence. If no matching intent is found, then Assist is unable to interpret the sentence. If a matching intent was found, information is provided on the action that will be performed on which entities. The example below shows how the following sentence was parsed: _what lights are on in the office_. * Assist found a matching intent: _HassGetState_. * It found entities matching the domain: _lights_. * The lights have the state _on_. * The lights are in the area _office_. * The targets are the narrowed-down entities in scope. ![Example use of assist developer tools](https://www.home-assistant.io/images/docs/developer-tools/Assist.png) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/tools/dev-tools/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/tools/dev-tools.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Ftools%2Fdev-tools%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Ftools%2Fdev-tools%2F%22&in=body "View given feedback for this page") --- # Scenes editor - Home Assistant From the UI choose **Settings** which is located in the sidebar, then click on **Automations & Scenes** to go to the scene editor. Press the **Add Scene** button in the lower right corner to get started. Choose a meaningful name for your scene. ![Scene editor](https://www.home-assistant.io/images/docs/scenes/editor.png) Select all the devicesA device is a model representing a physical or logical unit that contains entities. (or entitiesAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) when advanced mode is enabled on your user profile) you want to include in your scene. The state of your devices will be saved, so it can be restored when you are finished creating your scene. Set the state of the devices to how you want them to be in your scene, this can be done by clicking on it and edit the state from the popup, or any other method that changes the state. On the moment you save the scene, all the states of your devices are stored in the scene. 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 automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) action and scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) using a turn on scene actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) : action: scene.turn_on target: entity_id: scene.my_unique_id Updating your configuration to use the editor[](https://www.home-assistant.io/docs/scene/editor/#updating-your-configuration-to-use-the-editor) ------------------------------------------------------------------------------------------------------------------------------------------------ First, check that you have activated the configuration editor. # Activate the configuration editor config: The scene editor reads and writes to the file `scenes.yaml` in the root of your [configuration](https://www.home-assistant.io/docs/configuration/) folder. Currently, both the name of this file and its location are fixed. Make sure that you have set up the scene integration to read from it: # Configuration.yaml example scene: !include scenes.yaml If you still want to use your old scene section, add a label to the old entry: scene old: - name: ... You can use the `scene:` and `scene old:` sections at the same time: * `scene old:` to keep your manual designed scenes * `scene:` to save the scene created by the online editor scene: !include scenes.yaml scene old: !include_dir_merge_list scenes Migrating your scenes to scenes.yaml[](https://www.home-assistant.io/docs/scene/editor/#migrating-your-scenes-to-scenesyaml) ----------------------------------------------------------------------------------------------------------------------------- If you want to migrate your old scenes to use the editor, you’ll have to copy them to `scenes.yaml`. Make sure that `scenes.yaml` remains a list! For each scene that you copy over, you’ll have to add an `id`. This can be any string as long as it’s unique. For example: # Example scenes.yaml entry - id: my_unique_id # <-- Required for editor to work. name: Romantic entities: light.tv_back_light: on light.ceiling: state: on xy_color: [0.33, 0.66] brightness: 200 Note Any comments in the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file will be lost and templates will be reformatted when you update a scene via the editor. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/scene/editor/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/scene/editor.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fscene%2Feditor%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fscene%2Feditor%2F%22&in=body "View given feedback for this page") --- # Z-Wave adapters - Home Assistant To use Z-Wave with Home Assistant, you need a compatible Z-Wave adapter. Recommended Z-Wave adapter[](https://www.home-assistant.io/docs/z-wave/controllers/#recommended-z-wave-adapter) ---------------------------------------------------------------------------------------------------------------- The [Home Assistant Connect ZWA-2](https://www.home-assistant.io/connect/zwa-2/) is an 800 series Z-Wave adapter specifically developed to work with Home Assistant. Other supported Z-Wave adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#other-supported-z-wave-adapters) -------------------------------------------------------------------------------------------------------------------------- This section lists devices that have been confirmed to work with Z-Wave JS. A few recommendations if you are new to Z-Wave: * Use an [800 series adapter](https://www.home-assistant.io/docs/z-wave/controllers/#800-series-usb-adapters) (with firmware updated to ≥ 7.23.2). * The 800 series adapters are the most future-proof and offer the best RF performance. * Opt for a USB connection, not a module. * Passing a module through Docker is more complicated than passing a USB connector through. ### 800 series USB adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#800-series-usb-adapters) Before connecting the Z-Wave 800 series adapter to Home Assistant, make sure the adapter uses a compatible firmware and SDK version. Some 800 series Z-Wave adapters have bugs which impact the stability of the mesh and can cause the adapter to become unresponsive. Upgrade the firmware of the 800 series adapter to a recommended version. * Because there is no known firmware version that is completely fixed, it is recommended to choose a firmware based on the following criteria: * prefer SDK versions 7.23.x and newer * SDK versions 7.22.x are okay * 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. #### List of supported 800 series adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#list-of-supported-800-series-adapters) The following 800 series USB adapters have been reported to work with Home Assistant if using the SDK and firmware versions mentioned above. * [Home Assistant Connect ZWA-2](https://www.home-assistant.io/connect/zwa-2/) (officially recommended adapter) * HomeSeer SmartStick G8 * Zooz 800 Series Z-Wave Long Range S2 Stick (ZST39 LR) ### 700 series USB adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#700-series-usb-adapters) In general, using a 700 series USB adapter is not recommended. Before connecting the Z-Wave 700 series adapter to Home Assistant, make sure the adapter uses a compatible firmware and SDK version. Some 700 series Z-Wave adapters have bugs which impact the stability of the mesh and can cause the adapter to become unresponsive. Upgrade the firmware of the 700 series adapter to a recommended version: * Because there is no known firmware version that is completely fixed, it is recommended to choose a firmware based on the following criteria: * prefer SDK versions 7.17.2 to 7.18.x or 7.21.6 and newer * SDK versions 7.19.x are okay * avoid SDK versions before 7.17.2 * avoid SDK versions 7.20 to 7.21.5 * **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. * To upgrade the firmware, search for the instructions that match your system. * For Linux, the [Upgrade instructions from kpine](https://github.com/kpine/zwave-js-server-docker/wiki/700-series-Controller-Firmware-Updates-(Linux)) can be helpful. #### List of supported 700 series USB adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#list-of-supported-700-series-usb-adapters) The following 700 series USB adapters have been reported to work with Home Assistant if using the SDK and firmware versions mentioned above: * Aeotec Z-Stick 7 USB stick (ZWA010) (the EU version is not recommended due to RF performance issues) * 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 USB adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#500-series-usb-adapters) The following 500 series USB adapters have been reported to work with Home Assistant: * Aeotec Z-Stick Gen5 (see note below) * Everspring USB stick - Gen 5 * GoControl HUSBZB-1 stick * Sigma Designs UZB stick * Vision USB stick - Gen5 * Z-Wave.Me UZB1 stick (see Aeotec Z-Stick note below) * HomeSeer SmartStick+ G2 * HomeSeer Z-NET G2 ### Raspberry Pi HAT adapters[](https://www.home-assistant.io/docs/z-wave/controllers/#raspberry-pi-hat-adapters) * Aeotec Z-Pi 7 Raspberry Pi HAT/Shield (ZWA025, 700 series) * Z-Wave.Me RaZberry 7 (ZME\_RAZBERRY7, 700 series) * Z-Wave.Me RaZberry 7 Pro (ZMEERAZBERRY7\_PRO or ZMEURAZBERRY7\_PRO, 700 series) * Z-Wave.Me Razberry 2 (500 series) * Z-Wave.Me Razberry 1 (300 series) Third-party hubs[](https://www.home-assistant.io/docs/z-wave/controllers/#third-party-hubs) -------------------------------------------------------------------------------------------- For the best experience, it is recommended to use an adapter directly with Home Assistant. If this doesn’t work for you, you can use a hub that supports Z-Wave. Home Assistant supports the following third-party hubs with Z-Wave support: * [Vera](https://www.home-assistant.io/integrations/vera/) * [Fibaro](https://www.home-assistant.io/integrations/fibaro/) * [SmartThings](https://www.home-assistant.io/integrations/smartthings/) * [Z-Wave.Me Z-Way](https://www.home-assistant.io/integrations/zwave_me) Adapter notes[](https://www.home-assistant.io/docs/z-wave/controllers/#adapter-notes) -------------------------------------------------------------------------------------- ### Aeotec Z-Stick[](https://www.home-assistant.io/docs/z-wave/controllers/#aeotec-z-stick) Note The Aeotec Z-Stick and some of its variants (e.g. Z-Wave.Me UZB1) are known to have compatibility issues with the Linux kernel because of their [non-compliant behavior](https://forums.raspberrypi.com/viewtopic.php?f=28&t=245031#p1502030) . Plugging these adapters through a USB hub can serve as a workaround that sometimes mitigates the issue. It’s totally normal for your Z-Wave stick to cycle through its LEDs (Yellow, Blue and Red) while plugged into your system. Related topics[](https://www.home-assistant.io/docs/z-wave/controllers/#related-topics) ---------------------------------------------------------------------------------------- * [Z wave integration](https://www.home-assistant.io/integrations/zwave_js/) * [Home assistant connect zwa 2](https://www.home-assistant.io/connect/zwa-2/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/z-wave/controllers/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/z-wave/controllers.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fz-wave%2Fcontrollers%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fz-wave%2Fcontrollers%2F%22&in=body "View given feedback for this page") --- # Entities and domains - Home Assistant 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 sensorSensors return information about a thing, for instance the level of water in a tank. [\[Learn more\]](https://www.home-assistant.io/integrations/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 deviceA device is a model representing a physical or logical unit that contains entities. or a serviceThe term “service” in Home Assistant is used in the sense of an **information service**. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called _service_ to avoid confusion, as it does not come with a piece of hardware.. Entities have [states](https://www.home-assistant.io/docs/configuration/state_object/) and [state attributes](https://www.home-assistant.io/docs/configuration/state_object/#about-entity-state-attributes) . All your entities are listed in the entities table, under [**Settings** > **Devices & services** > **Entities**](https://my.home-assistant.io/redirect/entities) . ![Screenshot showing the Entities table](https://www.home-assistant.io/images/getting-started/entities.png)Screenshot of the Entities table. Each line represents an entity. Domains[](https://www.home-assistant.io/docs/configuration/entities_domains/#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_: * [AI Task](https://www.home-assistant.io/integrations/ai_task) * [Air quality](https://www.home-assistant.io/integrations/air_quality) * [Alarm control panel](https://www.home-assistant.io/integrations/alarm_control_panel) * [Assist Satellite](https://www.home-assistant.io/integrations/assist_satellite) * [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor) * [Button](https://www.home-assistant.io/integrations/button) * [Calendar](https://www.home-assistant.io/integrations/calendar) * [Camera](https://www.home-assistant.io/integrations/camera) * [Climate](https://www.home-assistant.io/integrations/climate) * [Conversation](https://www.home-assistant.io/integrations/conversation) * [Cover](https://www.home-assistant.io/integrations/cover) * [Date](https://www.home-assistant.io/integrations/date) * [Date/Time](https://www.home-assistant.io/integrations/datetime) * [Device tracker](https://www.home-assistant.io/integrations/device_tracker) * [Event](https://www.home-assistant.io/integrations/event) * [Fan](https://www.home-assistant.io/integrations/fan) * [Geolocation](https://www.home-assistant.io/integrations/geo_location) * [Humidifier](https://www.home-assistant.io/integrations/humidifier) * [Image](https://www.home-assistant.io/integrations/image) * [Image processing](https://www.home-assistant.io/integrations/image_processing) * [Lawn mower](https://www.home-assistant.io/integrations/lawn_mower) * [Light](https://www.home-assistant.io/integrations/light) * [Lock](https://www.home-assistant.io/integrations/lock) * [Media player](https://www.home-assistant.io/integrations/media_player) * [Notifications](https://www.home-assistant.io/integrations/notify) * [Number](https://www.home-assistant.io/integrations/number) * [Remote](https://www.home-assistant.io/integrations/remote) * [Scenes](https://www.home-assistant.io/integrations/scene) * [Select](https://www.home-assistant.io/integrations/select) * [Sensor](https://www.home-assistant.io/integrations/sensor) * [Siren](https://www.home-assistant.io/integrations/siren) * [Speech-to-text (STT)](https://www.home-assistant.io/integrations/stt) * [Switch](https://www.home-assistant.io/integrations/switch) * [Tags](https://www.home-assistant.io/integrations/tag) * [Text](https://www.home-assistant.io/integrations/text) * [Time](https://www.home-assistant.io/integrations/time) * [To-do list](https://www.home-assistant.io/integrations/todo) * [Text-to-speech (TTS)](https://www.home-assistant.io/integrations/tts) * [Update](https://www.home-assistant.io/integrations/update) * [Vacuum](https://www.home-assistant.io/integrations/vacuum) * [Valve](https://www.home-assistant.io/integrations/valve) * [Wake-word detection](https://www.home-assistant.io/integrations/wake_word) * [Water heater](https://www.home-assistant.io/integrations/water_heater) * [Weather](https://www.home-assistant.io/integrations/weather) Related topics[](https://www.home-assistant.io/docs/configuration/entities_domains/#related-topics) ---------------------------------------------------------------------------------------------------- * [State object, entity state and attributes](https://www.home-assistant.io/docs/configuration/state_object/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/entities_domains/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/entities_domains.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fentities_domains%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fentities_domains%2F%22&in=body "View given feedback for this page") --- # Configuration.yaml - Home Assistant 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 integrationsIntegrations connect and integrate Home Assistant with your devices, services, and more. [\[Learn more\]](https://www.home-assistant.io/getting-started/concepts-terminology/#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.](https://www.home-assistant.io/images/docs/configuration/config-yaml_via-file-editor.png) Example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation. Editing configuration.yaml[](https://www.home-assistant.io/docs/configuration/#editing-configurationyaml) ---------------------------------------------------------------------------------------------------------- How you edit your `configuration.yaml` file depends on your editor preferences and the [installation type](https://www.home-assistant.io/installation/#about-installation-types) you used to set up Home Assistant. Follow these steps: 1. [Set up file access](https://www.home-assistant.io/docs/configuration/#to-set-up-access-to-the-files-and-prepare-an-editor) . 2. [Locate the config directory](https://www.home-assistant.io/docs/configuration/#to-find-the-configuration-directory) . 3. [Edit your `configuration.yaml` file](https://www.home-assistant.io/docs/configuration/#to-edit-the-configuration-file) . 4. Save your changes and [reload the configuration](https://www.home-assistant.io/docs/configuration/#reloading-the-configuration-to-apply-changes) to apply the changes. ### To set up access to the files and prepare an editor[](https://www.home-assistant.io/docs/configuration/#to-set-up-access-to-the-files-and-prepare-an-editor) Before you can edit a file, you need to know how to access files in Home Assistant and setup an editor. File access depends on your [installation type](https://www.home-assistant.io/installation/#about-installation-types) . If you use Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users., you can use editor add-ons, for example. If you use Home Assistant ContainerHome Assistant Container is a standalone container-based installation of Home Assistant Core. Any [OCI](https://opencontainers.org/) compatible runtime can be used, but the documentation focus is on Docker. [\[Learn more\]](https://www.home-assistant.io/installation/#about-installation-types) , add-ons are not available. To set up file access on the Home Assistant Operating System, follow these steps: * If you are unsure which option to choose, install the [file editor add-on](https://www.home-assistant.io/common-tasks/os/#installing-and-using-the-file-editor-add-on) . * Alternatively, use the [Studio Code Server add-on](https://www.home-assistant.io/common-tasks/os/#installing-and-using-the-visual-studio-code-vsc-add-on) . This editor offers live syntax checking and auto-fill of various Home Assistant entities. But it looks more complex than the file editor. * If you prefer to use a file editor on your computer, use the [Samba add-on](https://www.home-assistant.io/common-tasks/os/#installing-and-using-the-samba-add-on) . ### To find the configuration directory[](https://www.home-assistant.io/docs/configuration/#to-find-the-configuration-directory) 1. To look up the path to your configuration directory, go to [**Settings** > **System** > **Repairs**](https://my.home-assistant.io/redirect/system_health) . * Select the three dots menu and select **System information**. ![Show system information option](https://www.home-assistant.io/images/screenshots/System_information_menu.png) 2. Find out the location of the **Configuration directory**. ![Screenshot showing the top of the system information panel](https://www.home-assistant.io/images/screenshots/system_information.png) * Unless you changed the file structure, the default is as follows: - * Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users.: the `configuration.yaml` is in the `/config` folder of the installation. * Home Assistant ContainerHome Assistant Container is a standalone container-based installation of Home Assistant Core. Any [OCI](https://opencontainers.org/) compatible runtime can be used, but the documentation focus is on Docker. [\[Learn more\]](https://www.home-assistant.io/installation/#about-installation-types) : the `configuration.yaml` is in the config folder that you mounted in your container. ### To edit the configuration file[](https://www.home-assistant.io/docs/configuration/#to-edit-the-configuration-file) Once you have located the config folder, you can edit your `configuration.yaml` file. How you edit the file depends on the editor you set up in step 1: * **If you are using the File editor add-on**: Open the add-on, navigate to the `/config` folder in the file browser on the left, and select the `configuration.yaml` file to open it in the editor. * **If you are using the Studio Code Server add-on**: Open the add-on, use the file explorer on the left to navigate to the `configuration.yaml` file, and select it to open in the editor. * **If you are using Samba to access files**: Navigate to the shared folder on your computer, locate the `configuration.yaml` file, and open it with your favorite text editor like [Notepad++](https://notepad-plus-plus.org/) or [Visual Studio Code](https://code.visualstudio.com/) . 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](https://www.home-assistant.io/integrations/default_config/) for more information on what’s included in that line. Validating the configuration[](https://www.home-assistant.io/docs/configuration/#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. The method for running a configuration check depends on your [installation type](https://www.home-assistant.io/installation/#about-installation-types) . Check the common tasks for your installation type: * [Configuration check on Operating System](https://www.home-assistant.io/common-tasks/os/#configuration-check) * [Configuration check on Container](https://www.home-assistant.io/common-tasks/container/#configuration-check) Reloading the configuration to apply changes[](https://www.home-assistant.io/docs/configuration/#reloading-the-configuration-to-apply-changes) ----------------------------------------------------------------------------------------------------------------------------------------------- For configuration changes to become effective, the configuration must be reloaded. Most integrations in Home Assistant (that do not interact with devicesA device is a model representing a physical or logical unit that contains entities. or servicesThe term “service” in Home Assistant is used in the sense of an **information service**. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called _service_ to avoid confusion, as it does not come with a piece of hardware.) 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**. ![Settings, three dot menu, restart Home Assistant](https://www.home-assistant.io/images/docs/configuration/settings_restart_ha.png) 2. If you find that your changes were not applied, you need to restart. * Select **Restart Home Assistant**. * Note: This interrupts automations and scripts. ![Reload and restart buttons](https://www.home-assistant.io/images/docs/configuration/reload_restart.png) Troubleshooting the configuration[](https://www.home-assistant.io/docs/configuration/#troubleshooting-the-configuration) ------------------------------------------------------------------------------------------------------------------------- If you run into trouble while configuring Home Assistant, refer to the [configuration troubleshooting page](https://www.home-assistant.io/docs/configuration/troubleshooting/) . Related topics[](https://www.home-assistant.io/docs/configuration/#related-topics) ----------------------------------------------------------------------------------- * [Yaml syntax](https://www.home-assistant.io/docs/configuration/yaml/) * [Creating and restoring backups](https://www.home-assistant.io/common-tasks/general/#backups) * [Reloading the yaml configuration from developer tools](https://www.home-assistant.io/docs/tools/dev-tools/#reloading-the-yaml-configuration) * [Configuring file access on the operating system](https://www.home-assistant.io/common-tasks/os/#configuring-access-to-files) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2F%22&in=body "View given feedback for this page") --- # Selectors - Home Assistant Selectors can be used to specify what values are accepted for a blueprint input. The selector also defines how the input is shown in the user interface. Some selectors can, for example, show a toggle button to turn something on or off, while another select can filter a list of devices to show only devices that have motion-sensing capabilities. Having good selectors set on your blueprint automation inputs makes a blueprint easier to use from the UI. The following selectors are currently available: * [Action selector](https://www.home-assistant.io/docs/blueprint/selectors/#action-selector) * [Add-on selector](https://www.home-assistant.io/docs/blueprint/selectors/#add-on-selector) * [Area selector](https://www.home-assistant.io/docs/blueprint/selectors/#area-selector) * [Attribute selector](https://www.home-assistant.io/docs/blueprint/selectors/#attribute-selector) * [Assist pipeline selector](https://www.home-assistant.io/docs/blueprint/selectors/#assist-pipeline-selector) * [Backup location selector](https://www.home-assistant.io/docs/blueprint/selectors/#backup-location-selector) * [Boolean selector](https://www.home-assistant.io/docs/blueprint/selectors/#boolean-selector) * [Color temperature selector](https://www.home-assistant.io/docs/blueprint/selectors/#color-temperature-selector) * [Condition selector](https://www.home-assistant.io/docs/blueprint/selectors/#condition-selector) * [Config entry selector](https://www.home-assistant.io/docs/blueprint/selectors/#config-entry-selector) * [Constant selector](https://www.home-assistant.io/docs/blueprint/selectors/#constant-selector) * [Conversation agent selector](https://www.home-assistant.io/docs/blueprint/selectors/#conversation-agent-selector) * [Country selector](https://www.home-assistant.io/docs/blueprint/selectors/#country-selector) * [Date selector](https://www.home-assistant.io/docs/blueprint/selectors/#date-selector) * [Date & time selector](https://www.home-assistant.io/docs/blueprint/selectors/#date--time-selector) * [Device selector](https://www.home-assistant.io/docs/blueprint/selectors/#device-selector) * [Duration selector](https://www.home-assistant.io/docs/blueprint/selectors/#duration-selector) * [Entity selector](https://www.home-assistant.io/docs/blueprint/selectors/#entity-selector) * [Floor selector](https://www.home-assistant.io/docs/blueprint/selectors/#floor-selector) * [Icon selector](https://www.home-assistant.io/docs/blueprint/selectors/#icon-selector) * [Label selector](https://www.home-assistant.io/docs/blueprint/selectors/#label-selector) * [Language selector](https://www.home-assistant.io/docs/blueprint/selectors/#language-selector) * [Location selector](https://www.home-assistant.io/docs/blueprint/selectors/#location-selector) * [Media selector](https://www.home-assistant.io/docs/blueprint/selectors/#media-selector) * [Number selector](https://www.home-assistant.io/docs/blueprint/selectors/#number-selector) * [Object selector](https://www.home-assistant.io/docs/blueprint/selectors/#object-selector) * [QR code selector](https://www.home-assistant.io/docs/blueprint/selectors/#qr-code-selector) * [RGB color selector](https://www.home-assistant.io/docs/blueprint/selectors/#rgb-color-selector) * [Select selector](https://www.home-assistant.io/docs/blueprint/selectors/#select-selector) * [State selector](https://www.home-assistant.io/docs/blueprint/selectors/#state-selector) * [Statistic selector](https://www.home-assistant.io/docs/blueprint/selectors/#statistic-selector) * [Target selector](https://www.home-assistant.io/docs/blueprint/selectors/#target-selector) * [Template selector](https://www.home-assistant.io/docs/blueprint/selectors/#template-selector) * [Text selector](https://www.home-assistant.io/docs/blueprint/selectors/#text-selector) * [Theme selector](https://www.home-assistant.io/docs/blueprint/selectors/#theme-selector) * [Time selector](https://www.home-assistant.io/docs/blueprint/selectors/#time-selector) * [Trigger selector](https://www.home-assistant.io/docs/blueprint/selectors/#trigger-selector) Interactive demos of each of these selectors can be found on the [Home Assistant Design portal](https://design.home-assistant.io/#components/ha-selector) . If no selector is defined, a text input for a single line will be shown. Action selector[](https://www.home-assistant.io/docs/blueprint/selectors/#action-selector) ------------------------------------------------------------------------------------------- The action selector allows the user to input one or more sequences of actions. On the user interface, the action part of the automation editor will be shown. The value of the input will contain a list of actions to perform. ![Screenshot of an action selector](https://www.home-assistant.io/images/blueprints/selector-action.png) This selector does not have any other options; therefore, it only has its key. action: The output of this selector is a list of actions. For example: # Example action selector output result - action: scene.turn_on target: entity_id: scene.watching_movies metadata: {} Add-on selector[](https://www.home-assistant.io/docs/blueprint/selectors/#add-on-selector) ------------------------------------------------------------------------------------------- This can only be used on a Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users. installation. For Home Assistant ContainerHome Assistant Container is a standalone container-based installation of Home Assistant Core. Any [OCI](https://opencontainers.org/) compatible runtime can be used, but the documentation focus is on Docker. [\[Learn more\]](https://www.home-assistant.io/installation/#about-installation-types) installations, an error will be displayed. The add-on selector allows the user to input an add-on slug. On the user interface, it will list all installed add-ons and use the slug of the selected add-on. ![Screenshot of an add-on selector](https://www.home-assistant.io/images/blueprints/selector-addon.png) This selector does not have any other options; therefore, it only has its key. # Example add-on selector addon: The output of this selector is the slug of the selected add-on. For example: `core_ssh`. Area selector[](https://www.home-assistant.io/docs/blueprint/selectors/#area-selector) --------------------------------------------------------------------------------------- The area selector shows an area finder that can pick a single or multiple areas based on the selector configuration. The value of the input will be the area ID, or a list of area IDs, based on if `multiple` is set to `true`. An area selector can filter the list of areas, based on properties of the devices and entities that are assigned to those areas. For example, the areas list could be limited to areas with entities provided by the [ZHA](https://www.home-assistant.io/integrations/zha) integration. In its most basic form, this selector doesn’t require any options, which will show all areas. ![Screenshot of an area selector](https://www.home-assistant.io/images/blueprints/selector-area.png) area: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#area-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) device list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device) When device options are provided, the list of areas is filtered by areas that at least provide one device that matches the given conditions. Can be either a object or a list of object. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of areas that provide devices by the set integration domain, for example, [`zha`](https://www.home-assistant.io/integrations/zha) . manufacturer string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#manufacturer) When set, it limits the list of areas that provide devices by the set manufacturer name. model string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#model) When set, it limits the list of areas that provide devices that have the set model. model\_id string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#model_id) When set, the list of areas is limited to areas with devices that have the set model ID. entity list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#entity) When entity options are provided, the list of areas is filtered by areas that at least provide one entity that matches the given conditions. Can be either a object or a list of object. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of areas that provide entities by the set integration domain, for example, [`zha`](https://www.home-assistant.io/integrations/zha) . domain string | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#domain) Limits the list of areas that provide entities of a certain [domain(s)](https://www.home-assistant.io/docs/configuration/entities_domains/#domains) , for example, [`light`](https://www.home-assistant.io/integrations/light) or [`binary_sensor`](https://www.home-assistant.io/integrations/binary_sensor) . Can be either a string with a single domain, or a list of string domains to limit the selection to. device\_class [device\_class](https://www.home-assistant.io/integrations/homeassistant/#device-class) | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device_class) Limits the list of areas to areas that have entities with a certain device class(es), for example, `motion` or `window`. Can be either a string with a single device\_class, or a list of string device\_class to limit the selection to. supported\_features list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#supported_features) Limits the list of areas to areas that have entities with a certain supported feature, for example, `light.LightEntityFeature.TRANSITION` or `climate.ClimateEntityFeature.TARGET_TEMPERATURE`. Should be a list of features. For a list of supported features for each entity type, refer to the [entity documentation](https://developers.home-assistant.io/docs/core/entity) . multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple areas. If set to `true`, the resulting value of this selector will be a list instead of a single string value. The output of this selector is the area ID, or (in case `multiple` is set to `true`) a list of area IDs. # Example area selector output result, when multiple is set to false living_room # Example area selector output result, when multiple is set to true - living_room - kitchen ### Example area selectors[](https://www.home-assistant.io/docs/blueprint/selectors/#example-area-selectors) An example area selector only shows areas that provide one or more lights or switches provided by the [ZHA](https://www.home-assistant.io/integrations/zha) integration. area: entity: integration: zha domain: - light - switch Another example uses the area selector, which only shows areas that provide one or more remote controls provided by the [deCONZ](https://www.home-assistant.io/integrations/deconz) integration. Multiple areas can be selected. area: multiple: true device: - integration: deconz manufacturer: IKEA of Sweden model: TRADFRI remote control Attribute selector[](https://www.home-assistant.io/docs/blueprint/selectors/#attribute-selector) ------------------------------------------------------------------------------------------------- The attributes selector shows a list of state attributes from a provided entity of which one can be selected. This allows for selecting, e.g., the “Effect” attribute from a light entity, or the “Next dawn” attribute from the `sun` entity. ![Screenshot of an attribute selector](https://www.home-assistant.io/images/blueprints/selector-attribute.png) #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#attribute-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) entity\_id string Required[](https://www.home-assistant.io/docs/blueprint/selectors/#entity_id) The entity ID of which an state attribute can be selected from. The output of this selector is the selected attribute key (not the translated or prettified name shown in the frontend). For example: `next_dawn`. Assist pipeline selector[](https://www.home-assistant.io/docs/blueprint/selectors/#assist-pipeline-selector) ------------------------------------------------------------------------------------------------------------- The assist pipeline selector shows all available assist pipelines (assistants) of which one can be selected. ![Screenshot of an assist pipeline selector](https://www.home-assistant.io/images/blueprints/selector-assist-pipeline.png) This selector does not have any other options; therefore, it only has its key. assist_pipeline: Backup location selector[](https://www.home-assistant.io/docs/blueprint/selectors/#backup-location-selector) ------------------------------------------------------------------------------------------------------------- This can only be used on an installation with a Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users.. For Home Assistant ContainerHome Assistant Container is a standalone container-based installation of Home Assistant Core. Any [OCI](https://opencontainers.org/) compatible runtime can be used, but the documentation focus is on Docker. [\[Learn more\]](https://www.home-assistant.io/installation/#about-installation-types) installations, an error will be displayed. The backup location selector shows a list of places a backup could go, depending on what you have configured in [storage](https://my.home-assistant.io/redirect/storage/) . ![Screenshot of an assist pipeline selector](https://www.home-assistant.io/images/blueprints/selector-backup-location.png) The output of this selector is the name of the selected network storage. It may also be the value `/backup`, if the user chooses to use the local data disk option instead of one of the configured network storage locations. backup_location: Boolean selector[](https://www.home-assistant.io/docs/blueprint/selectors/#boolean-selector) --------------------------------------------------------------------------------------------- The boolean selector shows a toggle that allows the user to turn on or off the selected option. ![Screenshot of a boolean selector](https://www.home-assistant.io/images/blueprints/selector-boolean.png) The boolean selector is suitable for adding feature switches to, for example, blueprints. This selector does not have any other options; therefore, it only has its key. boolean: The output of this selector is `true` when the toggle is on, `false` otherwise. Color temperature selector[](https://www.home-assistant.io/docs/blueprint/selectors/#color-temperature-selector) ----------------------------------------------------------------------------------------------------------------- The color temperature selector allows you to select a color temperature from a gradient using a slider. ![Screenshot of the Color temperature selector](https://www.home-assistant.io/images/blueprints/selector-color-temp.png) color_temp: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#color_temp-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) unit string (Optional, default: mired)[](https://www.home-assistant.io/docs/blueprint/selectors/#unit) The chosen unit for the color temperature. This can be either `kelvin` or `mired`. `mired` is the default for historical reasons. min integer (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#min) The minimum color temperature in the chosen unit. Default: 2700 for kelvin 153 for mired max integer (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#max) The maximum color temperature in the chosen unit. Default: 6500 for kelvin 500 for mired The output of this selector is the number representing the chosen color temperature for the unit used. Condition selector[](https://www.home-assistant.io/docs/blueprint/selectors/#condition-selector) ------------------------------------------------------------------------------------------------- The condition selector allows the user to input one or more conditions. On the user interface, the condition part of the automation editor will be shown. The value of the input will contain a list of conditions. ![Screenshot of an condition selector](https://www.home-assistant.io/images/blueprints/selector-condition.png) This selector does not have any other options; therefore, it only has its key. condition: The output of this selector is a list of conditions. For example: # Example condition selector output result - condition: numeric_state entity_id: "sensor.outside_temperature" below: 20 Config entry selector[](https://www.home-assistant.io/docs/blueprint/selectors/#config-entry-selector) ------------------------------------------------------------------------------------------------------- The config entry selector allows the user to select an integration configuration entry. The selector returns the entry ID of the selected integration configuration entry. ![Screenshot of the Configuration entry selector](https://www.home-assistant.io/images/blueprints/selector-config-entry.png) config_entry: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#config_entry-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Limits the list of selectable configuration entries to a single integration domain. The output of this selector is the entry ID of the config entry, for example, `6b68b250388cbe0d620c92dd3acc93ec`. Constant selector[](https://www.home-assistant.io/docs/blueprint/selectors/#constant-selector) ----------------------------------------------------------------------------------------------- The constant selector shows a toggle that allows the user to enable the selected option. This is similar to the [boolean selector](https://www.home-assistant.io/docs/blueprint/selectors/#boolean-selector) , the difference is that the constant selector has no value when it’s not enabled. ![Screenshot of a constant selector](https://www.home-assistant.io/images/blueprints/selector-constant.png) The selector’s value must be configured, and optionally, a label. constant: value: true label: Enabled The output of this selector is the configured value when the toggle is on, it has no output otherwise. Conversation agent selector[](https://www.home-assistant.io/docs/blueprint/selectors/#conversation-agent-selector) ------------------------------------------------------------------------------------------------------------------- The conversation agent selector allows picking a conversation agent. ![Screenshot of a conversation agent selector](https://www.home-assistant.io/images/blueprints/selector-conversation-agent.png) The selector has 1 option, `language`. This filters the conversation agents shown, depending on the language. conversation_agent: language: en #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#conversation_agent-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) language string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#language) Limits the list of conversation agents to those supporting the specified language. The output of this selector is the ID of the conversation agent. Country selector[](https://www.home-assistant.io/docs/blueprint/selectors/#country-selector) --------------------------------------------------------------------------------------------- The country selector allows a user to pick a country from a list of countries. ![Screenshot of a country selector](https://www.home-assistant.io/images/blueprints/country_selector.png) country: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#entity-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) countries list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#countries) A list of countries to pick from, this should be ISO 3166 country codes. Default: The available countries in the Home Assistant frontend no\_sort boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#no_sort) Should the options be sorted by name, if set to true, the order of the provided countries is kept. The output of this selector is an ISO 3166 country code. Date selector[](https://www.home-assistant.io/docs/blueprint/selectors/#date-selector) --------------------------------------------------------------------------------------- The date selector shows a date input that allows the user to specify a date. ![Screenshot of the Date selector](https://www.home-assistant.io/images/blueprints/selector-date.png) This selector does not have any other options; therefore, it only has its key. date: The output of this selector will contain the date in Year-Month-Day (`YYYY-MM-DD`) format, for example, `2022-02-22`. Date & time selector[](https://www.home-assistant.io/docs/blueprint/selectors/#date--time-selector) ---------------------------------------------------------------------------------------------------- The date selector shows a date and time input that allows the user to specify a date with a specific time. ![Screenshot of the Date & time selector](https://www.home-assistant.io/images/blueprints/selector-datetime.png) This selector does not have any other options; therefore, it only has its key. datetime: The output of this selector will contain the date in Year-Month-Day (`YYYY-MM-DD`) format and the time in 24-hour format, for example: `2022-02-22 13:30:00`. Device selector[](https://www.home-assistant.io/docs/blueprint/selectors/#device-selector) ------------------------------------------------------------------------------------------- The device selector shows a device finder that can pick a single or multiple devices based on the selector configuration. The value of the input will contain the device ID or a list of device IDs, based on if `multiple` is set to `true`. A device selector can filter the list of devices, based on things like the manufacturer, model, or model ID of the device, the entities the device provides or based on the domain that provided the device. ![Screenshot of a device selector](https://www.home-assistant.io/images/blueprints/selector-device.png) In its most basic form, this selector doesn’t require any options, which will show all devices. device: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#device-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) entity list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#entity) When entity options are provided, the list of devices is filtered by devices that at least provide one entity that matches the given conditions. Can be either a object or a list of object. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of devices that provide entities by the set integration domain, for example, [`zha`](https://www.home-assistant.io/integrations/zha) . domain string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#domain) Limits the list of devices that provide entities of a certain [domain(s)](https://www.home-assistant.io/docs/configuration/entities_domains/#domains) , for example, [`light`](https://www.home-assistant.io/integrations/light) or [`binary_sensor`](https://www.home-assistant.io/integrations/binary_sensor) . Can be either a string with a single domain, or a list of string domains to limit the selection to. device\_class [device\_class](https://www.home-assistant.io/integrations/homeassistant/#device-class) | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device_class) Limits the list of devices to devices that have entities with a certain device class(es), for example, `motion` or `window`. Can be either a string with a single device\_class, or a list of string device\_class to limit the selection to. supported\_features list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#supported_features) Limits the list of devices to devices that have entities with a certain supported feature, for example, `light.LightEntityFeature.TRANSITION` or `climate.ClimateEntityFeature.TARGET_TEMPERATURE`. Should be a list of features. For a list of supported features for each entity type, refer to the [entity documentation](https://developers.home-assistant.io/docs/core/entity) . filter list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#filter) When filter options are provided, the list of devices is filtered by devices that at least provide one entity that matches the given conditions. Can be either a object or a list of object. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of devices to devices provided by the set integration domain. manufacturer string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#manufacturer) When set, it limits the list of devices to devices provided by the set manufacturer name. model string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#model) When set, it limits the list of devices to devices that have the set model. model\_id string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#model_id) When set, the list of devices is limited to devices that have the set model ID. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple devices. If set to `true`, the resulting value of this selector will be a list instead of a single string value. The output of this selector is the device ID, or (in case `multiple` is set to `true`) a list of devices IDs. # Example device selector output result, when multiple is set to false faadde5365842003e8ca55267fe9d1f4 # Example device selector output result, when multiple is set to true - faadde5365842003e8ca55267fe9d1f4 - 3da77cb054352848b9544d40e19de562 ### Example device selector[](https://www.home-assistant.io/docs/blueprint/selectors/#example-device-selector) An example entity selector that, will only show devices that are: * Provided by the [deCONZ](https://www.home-assistant.io/integrations/deconz) integration. * Are a Philips Hue Remote of Model RWL021. * Provide a battery [sensor](https://www.home-assistant.io/integrations/sensor) . And this is what is looks like in YAML: device: filter: - integration: deconz manufacturer: Philips model: RWL021 entity: - domain: sensor device_class: battery Duration selector[](https://www.home-assistant.io/docs/blueprint/selectors/#duration-selector) ----------------------------------------------------------------------------------------------- The duration select allow the user to select a time duration. This can be helpful for, e.g., delays or offsets. ![Screenshot of the Duration selector](https://www.home-assistant.io/images/blueprints/selector-duration.png) duration: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#attribute-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) enable\_day boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#enable_day) When `true`, the duration selector will allow selecting days. enable\_millisecond boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#enable_millisecond) When `true`, the duration selector will allow selecting milliseconds. The output of this selector is a mapping of the time values the user selected. For example: days: 1 # Only when enable_day was set to true hours: 12 minutes: 30 seconds: 15 milliseconds: 500 # Only when enable_millisecond was set to true Entity selector[](https://www.home-assistant.io/docs/blueprint/selectors/#entity-selector) ------------------------------------------------------------------------------------------- The entity selector shows an entity finder that can pick a single entity or a list of entities based on the selector configuration. The value of the input will contain the entity ID, or list of entity IDs, based on if `multiple` is set to `true`. An entity selector can filter the list of entities, based on things like the class of the device, the domain of the entity or the domain that provided the entity. ![Screenshot of an entity selector](https://www.home-assistant.io/images/blueprints/selector-entity.png) In its most basic form, this selector doesn’t require any options, which will show all entities. entity: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#entity-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) exclude\_entities list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#exclude_entities) List of entity IDs to exclude from the selectable list. include\_entities list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#include_entities) List of entity IDs to limit the selectable list to. filter list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#filter) When filter options are provided, the entities are limited by entities that at least match the given conditions. Can be either an object or a list of objects. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of entities to entities provided by the set integration domain, for example, [`zha`](https://www.home-assistant.io/integrations/zha) . domain string | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#domain) Limits the list of entities to entities of a certain [domain(s)](https://www.home-assistant.io/docs/configuration/entities_domains/#domains) , for example, [`light`](https://www.home-assistant.io/integrations/light) or [`binary_sensor`](https://www.home-assistant.io/integrations/binary_sensor) . Can be either a string with a single domain, or a list of string domains to limit the selection to. device\_class [device\_class](https://www.home-assistant.io/integrations/homeassistant/#device-class) | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device_class) Limits the list of entities to entities that have a certain device class(es), for example, `motion` or `window`. Can be either a string with a single device\_class, or a list of string device\_class to limit the selection to. supported\_features list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#supported_features) Limits the list of entities to entities that have a certain supported feature, for example, `light.LightEntityFeature.TRANSITION` or `climate.ClimateEntityFeature.TARGET_TEMPERATURE`. Should be a list of features. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple entities. If set to `true`, the resulting value of this selector will be a list instead of a single string value. reorder boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#reorder) Allows reordering of entities (only applies if `multiple` is set to `true`). The output of this selector is the entity ID, or (in case `multiple` is set to `true`) a list of entity IDs. # Example entity selector output result, when multiple is set to false light.living_room # Example entity selector output result, when multiple is set to true - light.living_room - light.kitchen ### Example entity selector[](https://www.home-assistant.io/docs/blueprint/selectors/#example-entity-selector) An example entity selector that, will only show entities that are: * Provided by the [ZHA](https://www.home-assistant.io/integrations/zha) integration. * From the [Binary sensor](https://www.home-assistant.io/integrations/binary_sensor) domain. * Have presented themselves as devices of a motion device class. * Allows selecting one or more entities. And this is what it looks like in YAML: entity: multiple: true filter: - integration: zha domain: binary_sensor device_class: motion Floor selector[](https://www.home-assistant.io/docs/blueprint/selectors/#floor-selector) ----------------------------------------------------------------------------------------- The floor selector shows a floor finder that can pick floors based on the selector configuration. The value of the input will be the floor ID. If `multiple` is set to `true`, the value is a list of floor IDs. A floor selector can filter the list of floors based on the properties of the devices and entities assigned to the areas on those floors. For example, the floor list could be limited to floors with entities provided by the [ZHA](https://www.home-assistant.io/integrations/zha) integration, based on the areas they are in. In its most basic form, this selector doesn’t require any options. It will show all floors. ![Screenshot of a floor selector](https://www.home-assistant.io/images/blueprints/selector-floor.png) floor: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#floor-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) device list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device) When device options are provided, the list of floors is filtered by floors that have at least one device matching the given conditions. Can be either an object or a list of objects. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of floors that have devices by this integration domain. For example, [`zha`](https://www.home-assistant.io/integrations/zha) . manufacturer string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#manufacturer) When set, the list only includes floors that have devices by the set manufacturer name. model string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#model) When set, the list only includes floors that have devices which have the set model. model\_id string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#model_id) When set, the list only includes floors with devices that have the set model ID. entity list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#entity) When entity options are provided, the list only includes floors that at least have one entity that matches the given conditions. Can be either an object or a list of objects. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits the list of floors that have entities by the set integration domain. For example, [`zha`](https://www.home-assistant.io/integrations/zha) . domain string | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#domain) When set, the list only includes floors that have entities of certain [domains](https://www.home-assistant.io/docs/configuration/entities_domains/#domains) , for example, [`light`](https://www.home-assistant.io/integrations/light) or [`binary_sensor`](https://www.home-assistant.io/integrations/binary_sensor) . Can be either a string with a single domain, or a list of string domains to limit the selection to. device\_class [device\_class](https://www.home-assistant.io/integrations/homeassistant/#device-class) | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device_class) When set, the list only includes floors that have entities with a certain device class, for example, `motion` or `window`. Can be either a string with a single device\_class, or a list of string device\_class to limit the selection. supported\_features list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#supported_features) When set, the list only includes floors that have entities with a certain supported feature, for example, `light.LightEntityFeature.TRANSITION` or `climate.ClimateEntityFeature.TARGET_TEMPERATURE`. Should be a list of features. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple floors. If set to `true`, the resulting value of this selector will be a list instead of a single string value. The output of this selector is the floor ID, or (in case `multiple` is set to `true`) a list of floor IDs. # Example floor selector output result, when multiple is set to false first_floor # Example floor selector output result, when multiple is set to true - first_floor - second_floor ### Example floor selectors[](https://www.home-assistant.io/docs/blueprint/selectors/#example-floor-selectors) An example floor selector only shows floors that have one or more lights or switches provided by the [ZHA](https://www.home-assistant.io/integrations/zha) integration. floor: entity: integration: zha domain: - light - switch Another example using the floor selector, which only shows floors that have one or more remote controls provided by the [deCONZ](https://www.home-assistant.io/integrations/deconz) integration. Multiple floors can be selected. floor: multiple: true device: - integration: deconz manufacturer: IKEA of Sweden model: TRADFRI remote control Icon selector[](https://www.home-assistant.io/docs/blueprint/selectors/#icon-selector) --------------------------------------------------------------------------------------- The icon selector shows an icon picker that allows the user to select an icon. icon: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#entity-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) placeholder string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#placeholder) Placeholder icon to show, when no icon is selected. The output of this selector is a string containing the selected icon, for example: `mdi:bell`. Label selector[](https://www.home-assistant.io/docs/blueprint/selectors/#label-selector) ----------------------------------------------------------------------------------------- The label selector shows a label finder that can pick labels. The value of the input is the label ID. If `multiple` is set to `true`, the value is a list of label IDs. ![Screenshot of the label selector](https://www.home-assistant.io/images/blueprints/selector-label.png) In its most basic form, this selector doesn’t require any options. It will show all labels. label: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#text-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple labels. If set to `true`, the resulting value of this selector will be a list instead of a single string value. The output of this selector is the label ID, or (in case `multiple` is set to `true`) a list of label IDs. # Example label selector output result, when multiple is set to false energy_saving # Example label selector output result, when multiple is set to true - energy_saving - christmas_decorations Language selector[](https://www.home-assistant.io/docs/blueprint/selectors/#language-selector) ----------------------------------------------------------------------------------------------- The language selector allows a user to pick a language from a list of languages. ![Screenshot of an language selector](https://www.home-assistant.io/images/blueprints/selector-language.png) language: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#entity-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) languages list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#languages) A list of languages to pick from, this should be RFC 5646 languages codes. Default: The available languages in the Home Assistant frontend native\_name boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#native_name) Should the name of the languages be shown in the language of the user, or in the language itself. no\_sort boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#no_sort) Should the options be sorted by name, if set to true, the order of the provided languages is kept. The output of this selector is a RFC 5646 language code. Location selector[](https://www.home-assistant.io/docs/blueprint/selectors/#location-selector) ----------------------------------------------------------------------------------------------- The location selector allow a user to pick a location from a map and returns the matching longitude and latitude coordinators. Optionally it supports selecting the radius of the location. ![Screenshot of the Location selector](https://www.home-assistant.io/images/blueprints/selector-location.png) location: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#entity-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) icon string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#icon) An optional icon to show on the map. radius boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#radius) Allow selecting the radius of the location. If enabled, the radius will be returned in meters. The output of this selector is a mapping containing the latitude and longitude of the selected location, and, if enabled, the radius. For example: latitude: 50.935 longitude: 6.95 radius: 500 # Only provided when radius was set to true. Media selector[](https://www.home-assistant.io/docs/blueprint/selectors/#media-selector) ----------------------------------------------------------------------------------------- The media selector is a powerful selector that allows a user to easily select media to play on a media device. Media can be a lot of things, for example, cameras, local media, text-to-speech, Home Assistant Dashboards, and many more. You are prompted to select the device used to play media. Once the device is selected, the media selector only shows media that is suitable for this device. ![Screenshot of the Media selector](https://www.home-assistant.io/images/blueprints/selector-media.png) To ask the user to select a media device and suitable media, you can use the media selector without any options: media: You can also use the media selector with an optional `accept` filter to limit the media types that can be selected. The user will not be asked to pick a device. media: accept: - image/* #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#media-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) accept list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#accept) List of media types the user is allowed to select. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple media items. If set to `true`, the resulting value of this selector will be a list instead of a single object. The output of the media selector, is an mapping with information about the selected media device and the selected media to play. There is also metadata, which is used by the frontend and should not be used in the backend. Example output: entity_id: media_player.living_room media_content_id: media-source://tts/cloud?message=TTS+Message&language=en-US&gender=female media_content_type: provider metadata: title: TTS Message thumbnail: https://brands.home-assistant.io/_/cloud/logo.png media_class: app children_media_class: null navigateIds: - {} - media_content_type: app media_content_id: media-source://tts - media_content_type: provider media_content_id: >- media-source://tts/cloud?message=TTS+Message&language=en-US&gender=female Example output if accept filter is used. Note that the `entity_id` is not present: media_content_id: media-source://tts/cloud?message=TTS+Message&language=en-US&gender=female media_content_type: provider metadata: title: TTS Message thumbnail: https://brands.home-assistant.io/_/cloud/logo.png media_class: app children_media_class: null navigateIds: - {} - media_content_type: app media_content_id: media-source://tts - media_content_type: provider media_content_id: >- media-source://tts/cloud?message=TTS+Message&language=en-US&gender=female Example output when `multiple` is set to `true` (a list of media objects): - media_content_id: media-source://media_source/local/image1.jpg media_content_type: image/jpeg metadata: title: image1.jpg - media_content_id: media-source://media_source/local/image2.jpg media_content_type: image/jpeg metadata: title: image2.jpg Number selector[](https://www.home-assistant.io/docs/blueprint/selectors/#number-selector) ------------------------------------------------------------------------------------------- The number selector shows either a number input or a slider input, that allows the user to specify a numeric value. The value of the input will contain the select value. ![Screenshot of a number selector](https://www.home-assistant.io/images/blueprints/selector-number.png) On the user interface, the input can either be in a slider or number mode. Both modes limit the user input by a minimum and maximum value, and can have a unit of measurement to go with it. In its most basic form, this selector requires a minimum and maximum value: number: min: 0 max: 100 #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#number-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) min integer | float (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#min) The minimum user-settable number value. max integer | float (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#max) The maximum user-settable number value. step integer | float | any (Optional, default: 1)[](https://www.home-assistant.io/docs/blueprint/selectors/#step) The step size of the number value. Set to `"any"` to allow any number. unit\_of\_measurement string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#unit_of_measurement) Unit of measurement in which the number value is expressed in. mode string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#mode) This can be either `box` or `slider` mode. Default: slider if min and max are set, otherwise box translation\_key string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#translation_key) Allows translations provided by an integration where `translation_key` is the translation key that is providing the unit\_of\_measurement string translation. See the documentation on [Backend Localization](https://developers.home-assistant.io/docs/internationalization/core/#selectors) for more information. The output of this selector is a number, for example: `42` ### Example number selectors[](https://www.home-assistant.io/docs/blueprint/selectors/#example-number-selectors) An example number selector that allows a user a percentage, directly in a regular number input box. number: min: 0 max: 100 unit_of_measurement: "%" A more visual variant of this example could be achieved using a slider. This can be helpful for things like allowing the user to select a brightness level of lights. Additionally, this example changes the brightness in incremental steps of 10%. number: min: 0 max: 100 step: 10 unit_of_measurement: "%" mode: slider Object selector[](https://www.home-assistant.io/docs/blueprint/selectors/#object-selector) ------------------------------------------------------------------------------------------- The object selector can be used to input arbitrary data in YAML form. This is useful for e.g. lists and dictionaries containing data for actions. The value of the input will contain the provided data. When used without options, the selector will accept any valid YAML content, such as objects, arrays, strings, or other YAML types. The input box is displayed as an editor with syntax highlighting. ![Screenshot of an object selector](https://www.home-assistant.io/images/blueprints/selector-object.png) object: When used with `fields` specified, the selector will force the object to be in this format by displaying a form. ![Screenshot of an object selector](https://www.home-assistant.io/images/blueprints/selector-object-schema.png) object: label_field: name description_field: percentage multiple: true fields: name: label: Name selector: text: percentage: label: Percentage selector: number: unit_of_measurement: "%" The output of this selector is a YAML object. #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#object-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) fields map (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#fields) List of fields of the object. label string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#label) The label of the field required boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#required) If set to true, the field must be present. selector string Required[](https://www.home-assistant.io/docs/blueprint/selectors/#selector) The selector to use for this field. It can be any available selector. label\_field string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#label_field) The field to use as a label. By default, it will be the first field defined. This option is only used if `fields` option set. description\_field string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#description_field) The field to use as a description. This option is only used if `fields` option set. translation\_key string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#translation_key) Allows translations provided by an integration where `translation_key` is the translation key that is providing the selector option strings translation. See the documentation on [Backend Localization](https://developers.home-assistant.io/docs/internationalization/core/#selectors) for more information. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows adding multiple objects. If set to `true`, the resulting value of this selector will be a list instead of a single YAML object. This option is only used if `fields` option set. QR code selector[](https://www.home-assistant.io/docs/blueprint/selectors/#qr-code-selector) --------------------------------------------------------------------------------------------- The QR code selector shows a QR code. It has no return value. ![Screenshot of a QR code selector](https://www.home-assistant.io/images/blueprints/selector-qr-code.png) The QR code’s data must be configured, and optionally, the scale, and error correction level can be set. The scale makes the QR code bigger or smaller. #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#qr_code-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) data any Required[](https://www.home-assistant.io/docs/blueprint/selectors/#data) The data that should be represented in the QR code. scale integer (Optional, default: 4)[](https://www.home-assistant.io/docs/blueprint/selectors/#scale) The scale factor to use, this will make the QR code bigger or smaller. error\_correction\_level string (Optional, default: medium)[](https://www.home-assistant.io/docs/blueprint/selectors/#error_correction_level) The error correction level of the QR code, with a higher error correction level the QR code can be scanned even when some pieces are missing. Can be “low”, “medium”, “quartile” or “high”. qr_code: data: "https://home-assistant.io" scale: 5 error_correction_level: quartile RGB color selector[](https://www.home-assistant.io/docs/blueprint/selectors/#rgb-color-selector) ------------------------------------------------------------------------------------------------- The RGB color selector allows the user to select an color from a color picker from the user interface, and returns the RGB color value. ![Screenshot of the RGB Color selector](https://www.home-assistant.io/images/blueprints/selector-color-rgb.png) color_rgb: This selector does not have any other options; therefore, it only has its key. The output of this selector is a list with the three (RGB) color value, for example: `[255, 0, 0]`. Select selector[](https://www.home-assistant.io/docs/blueprint/selectors/#select-selector) ------------------------------------------------------------------------------------------- The select selector shows a list of available options from which the user can choose. The value of the input contains the value of the selected option. Only a single option can be selected at a time. ![Screenshot of a select selector](https://www.home-assistant.io/images/blueprints/selector-select.png) The selector requires a list of options that the user can choose from. select: options: - Red - Green - Blue #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#select-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) options list Required[](https://www.home-assistant.io/docs/blueprint/selectors/#options) List of options that the user can choose from. Small lists (5 items or less), are displayed as radio buttons. When more items are added, a dropdown list is used. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple options. If set to `true`, the resulting value of this selector will be a list instead of a single string value. custom\_value boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#custom_value) Allows the user to enter and select a custom value (or multiple custom values in addition to the listed options if `multiple` is set to `true`). mode string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#mode) This can be either `list` (radio buttons) or `dropdown` (combobox) mode. When not specified, small lists (5 items or less), are displayed as radio buttons. When more items are added, a dropdown list is used. If `custom_value` is `true`, this setting will be ignored and the frontend will use a `dropdown` input. translation\_key string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#translation_key) Allows translations provided by an integration where `translation_key` is the translation key that is providing the selector option strings translation. See the documentation on [Backend Localization](https://developers.home-assistant.io/docs/internationalization/core/#selectors) for more information. sort boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#sort) Display options in alphabetical order. Alternatively, a mapping can be used for the options. When you want to return a different value compared to how it is displayed to the user. select: options: - label: Red value: r - label: Green value: g - label: Blue value: b #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#select_map-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) options map Required[](https://www.home-assistant.io/docs/blueprint/selectors/#options) List of options that the user can choose from. Small lists (5 items or less), are displayed as radio buttons. When more items are added, a dropdown list is used. label string Required[](https://www.home-assistant.io/docs/blueprint/selectors/#label) The description to show in the UI for this item. value string Required[](https://www.home-assistant.io/docs/blueprint/selectors/#value) The value to return when this label is selected. When `multiple` is `false`, the output of this selector is the string of the selected option value. When selecting `Green` in the last example, it returns: `g`, in the first example it would return `Green`. When `multiple` is `true`, the output of this selector is the list of selected option values. In this case, if `Green` was selected, in the first example it would return \[“Green”\] and in the last example it returns \[“g”\]. State selector[](https://www.home-assistant.io/docs/blueprint/selectors/#state-selector) ----------------------------------------------------------------------------------------- The state selector shows a list of states for a provided entity of which one or more can be selected. ![Screenshot of an state selector](https://www.home-assistant.io/images/blueprints/selector-state.png) #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#state-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) entity\_id string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#entity_id) The entity ID of which an state can be selected from. hide\_states list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#hide_states) The states to exclude from the list of options multiple boolean[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows selecting multiple states. If set to `true`, the resulting value of this selector will be a list instead of a single string value. The output of this selector is the select state (not the translated or prettified name shown in the frontend), or a list of states if `multiple` is true. For example: `heat_cool`. Statistic selector[](https://www.home-assistant.io/docs/blueprint/selectors/#statistic-selector) ------------------------------------------------------------------------------------------------- The statistic selector selects the statistic ID of an entity that records Long-term statisticsHome Assistant saves long-term statistics for a sensor if the entity has a state\_class of measurement, total, or total\_increasing. For short-term statistics, a snapshot is taken every 5 minutes. For long-term statistics, an hourly aggregate is stored of the short-term statistics. Short-term statistics are automatically purged after a predefined period (default is 10 days). Long-term statistics are never purged. [\[Learn more\]](https://www.home-assistant.io/blog/2021/08/04/release-20218/#long-term-statistics) . It may resemble an entity ID (like `sensor.temperature`), or an external statistic ID (like `external:temperature`). ![Screenshot of a statistic selector](https://www.home-assistant.io/images/blueprints/selector-statistic.png) #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#statistic-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) If set to true, the selector returns a list of statistic IDs. The output of this selector is a string representing a statistic ID, or a list of statistic IDs if `multiple` is set to `true`. Target selector[](https://www.home-assistant.io/docs/blueprint/selectors/#target-selector) ------------------------------------------------------------------------------------------- The target selector is a rather special selector, allowing the user to select targeted entities, devices, or areas for actions. The value of the input will contain a special target format, that is accepted by actions. The selectable targets can be filtered, based on entity or device properties. Areas are only selectable as a target, if some entities or devices match those properties in those areas. ![Screenshot of a target selector](https://www.home-assistant.io/images/blueprints/selector-target.png) In its most basic form, this selector does not require any options, which will allow the user to target any entity, device or area available in the system. target: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#target-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) entity list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#entity) When entity options are provided, the targets are limited by entities that at least match the given conditions. Can be either a object or a list of object. integration string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#integration) Can be set to an integration domain. Limits targets to entities provided by the set integration domain, for example, [`zha`](https://www.home-assistant.io/integrations/zha) . domain string | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#domain) Limits the targets to entities of a certain [domain(s)](https://www.home-assistant.io/docs/configuration/entities_domains/#domains) , for example, [`light`](https://www.home-assistant.io/integrations/light) or [`binary_sensor`](https://www.home-assistant.io/integrations/binary_sensor) . Can be either a with a single domain, or a list of string domains to limit the selection to. device\_class [device\_class](https://www.home-assistant.io/integrations/homeassistant/#device-class) | list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#device_class) Limits the targets to entities with a certain device class(es), for example, `motion` or `window`. Can be either a string with a single device\_class, or a list of string device\_class to limit the selection to. supported\_features list (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#supported_features) Limits the targets to entities with a certain supported feature, for example, `light.LightEntityFeature.TRANSITION` or `climate.ClimateEntityFeature.TARGET_TEMPERATURE`. Should be a list of features. For a list of supported features for each entity type, refer to the [entity documentation](https://developers.home-assistant.io/docs/core/entity) . Important Targets are meant to be used with the `target` property of an action in a script sequence. For example: actions: - action: light.turn_on target: !input lights ### Example target selectors[](https://www.home-assistant.io/docs/blueprint/selectors/#example-target-selectors) An example target selector that only shows targets that at least provide one or more lights, provided by the [ZHA](https://www.home-assistant.io/integrations/zha) integration. target: entity: - integration: zha domain: light Template selector[](https://www.home-assistant.io/docs/blueprint/selectors/#template-selector) ----------------------------------------------------------------------------------------------- The template selector can be used to input a Jinja2 template. This is useful for allowing more advanced user-input that use Jinja2 templates. ![Screenshot of an template selector](https://www.home-assistant.io/images/blueprints/selector-template.png) This selector does not have any other options; therefore, it only has its key. template: The output of this selector is a template string. Text selector[](https://www.home-assistant.io/docs/blueprint/selectors/#text-selector) --------------------------------------------------------------------------------------- The text selector can be used to enter a text string. It can also be used to enter a list of text strings; if `multiple` is set to `true`. The value of the input will contain the selected text. This can be used in shopping lists, for example. ![Screenshot of text selectors](https://www.home-assistant.io/images/blueprints/selector-text.png) Unless `multiline` is set to `true`, this selector behaves exactly like if no selector at all was specified, and will display a single line text input box on the user interface. text: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#text-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) multiline boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiline) Set to true to display the input as a multi-line text box on the user interface. prefix string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#prefix) An optional prefix to show before the text input box. suffix string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#suffix) An optional suffix to show after the text input box. type string (Optional, default: text)[](https://www.home-assistant.io/docs/blueprint/selectors/#type) The type of input. This supplies the [HTML `type` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#input_types) , which controls how the browser displays and validates the field. A subset of types available to the attribute are supported, since some are handled by other selectors. Possible types are: `color`, `date`, `datetime-local`, `email`, `month`, `number`, `password`, `search`, `tel`, `text`, `time`, `url`, `week`. autocomplete string (Optional)[](https://www.home-assistant.io/docs/blueprint/selectors/#autocomplete) Guides the browser on the type of information which should automatically fill the field. This supplies the [HTML `autocomplete` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) . Any value supported by the HTML attribute is valid. multiple boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#multiple) Allows adding list of text strings. If set to `true`, the resulting value of this selector will be a list instead of a single string value. The output of this selector is a single string value. Theme selector[](https://www.home-assistant.io/docs/blueprint/selectors/#theme-selector) ----------------------------------------------------------------------------------------- The theme selector allows for selecting a theme from the available themes installed in Home Assistant. ![Screenshot of the Theme selector](https://www.home-assistant.io/images/blueprints/selector-theme.png) theme: #### Configuration Variables[](https://www.home-assistant.io/docs/blueprint/selectors/#theme-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) include\_default boolean (Optional, default: false)[](https://www.home-assistant.io/docs/blueprint/selectors/#include_default) Includes Home Assistant default theme in the list. The output of this selector will contain the selected theme, for example: `waves_dark`. Time selector[](https://www.home-assistant.io/docs/blueprint/selectors/#time-selector) --------------------------------------------------------------------------------------- The time selector shows a time input that allows the user to specify a time of the day. ![Screenshot of a time selector](https://www.home-assistant.io/images/blueprints/selector-time.png) This selector does not have any other options; therefore, it only has its key. time: The output of this selector will contain the time in 24-hour format, for example, `23:59:59`. Trigger selector[](https://www.home-assistant.io/docs/blueprint/selectors/#trigger-selector) --------------------------------------------------------------------------------------------- The triggers selector allows the user to input one or more triggers. On the user interface, the trigger part of the automation editor is shown. The value of the input contains a list of triggers. ![Screenshot of an trigger selector](https://www.home-assistant.io/images/blueprints/selector-trigger.png) This selector does not have any other options; therefore, it only has its key. trigger: The output of this selector is a list of triggers. For example: # Example trigger selector output result - trigger: numeric_state entity_id: "sensor.outside_temperature" below: 20 ### Example - Merging with existing triggers[](https://www.home-assistant.io/docs/blueprint/selectors/#example---merging-with-existing-triggers) If the trigger(s) should exist within a blueprint that already has some default triggers defined, and an additional customizable trigger should be merged, you need to use the `- triggers` syntax in the blueprint. # Example trigger selector input: my_trigger_input: selector: trigger: triggers: - triggers: !input my_trigger_input - platform: numeric_state [...] #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/blueprint/selectors/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/blueprint/selectors.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fblueprint%2Fselectors%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fblueprint%2Fselectors%2F%22&in=body "View given feedback for this page") --- # Entity integration platform options - Home Assistant Important These options are being phased out and are only available for single platform integrations. 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. Entity namespace[](https://www.home-assistant.io/docs/configuration/platform_options/#entity-namespace) -------------------------------------------------------------------------------------------------------- By setting an entity namespace, all entities will be prefixed with that namespace. That way, `light.bathroom` can become `light.holiday_house_bathroom`. # Example configuration.yaml entry light: - platform: your_lights entity_namespace: holiday_house Scan interval[](https://www.home-assistant.io/docs/configuration/platform_options/#scan-interval) -------------------------------------------------------------------------------------------------- Platforms that require polling will be polled in an interval specified by the main integration. For example, a light will check every 30 seconds for a changed state. It is possible to overwrite this scanning interval for any platform that is being polled by specifying a `scan_interval` configuration key. In the example below, we set up the `your_lights` platform but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds. # Example configuration.yaml entry to poll your_lights every 10 seconds. light: - platform: your_lights scan_interval: 10 #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/platform_options/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/platform_options.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fplatform_options%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fplatform_options%2F%22&in=body "View given feedback for this page") --- # Customizing entities - Home Assistant After adding a new device, you might find the automatically assigned entity ID too technical and the entity lacking a friendly name. You can personalize these elements to better fit your naming conventions or modify other attributes like the icon. To change entity attributes, follow these steps: 1. Go to [**Settings** > **Devices & services** > **Entities**](https://my.home-assistant.io/redirect/entities) and select the entity from the list. 2. In the top-right corner, select the cog icon. ![Entity dialog box with cog icon.](https://www.home-assistant.io/images/docs/configuration/customizing-entity-dialog.png) 3. Enter or edit the attributes: * For example, the entity ID here could be shortened to `binary_sensor.lumi_sensor_aq2_opening`. * You can use lowercase letters, numbers, and underscores. * The ID must not start or end with an underscore. * To undo the change and revert the ID to the default, select the icon. * **Note**: You can only reset the ID to the default ID for entities with a unique ID. * IDs of entities that are disabled or for which the integration is not set up cannot be reverted. * To revert all the entity IDs for a device, on the device page, select the three dots menu, then select **Recreate entity IDs**. * **Result**: This resets the entity ID and applies the current default naming convention. * The terms used to generate the entity ID depends on a few factors. Prioritization is as follows: 1. If you changed the friendly name of the entity, the friendly name will be used. 2. The entity ID suggested by the integration (just a few integrations do this). 3. The default name in the user language, if using Latin script. * If the something other than Latin script is used, the entity ID is based on the English default name. * This is because entity IDs must use lowercase alphanumeric characters in the range of \[a-z,1-9\]. ![revert all entity IDs for a device from the device page](https://www.home-assistant.io/images/docs/configuration/device-page-revert-entity-id.png) * Enter or edit the friendly name. * In this example, this would change “Opening”. * If needed, from the **Shown as** menu, you can select a different [device class](https://www.home-assistant.io/integrations/homeassistant/#device-class) . * If you like, add a [label](https://www.home-assistant.io/docs/organizing/labels/) . ![Settings for entity.](https://www.home-assistant.io/images/docs/configuration/customizing-entity.png) 4. To apply the changes, select **Update**. 5. If you have used this entity in automations and scripts, you need to rename the entity ID there, too. * Go to [**Settings** > **Automations & Scenes**](https://my.home-assistant.io/redirect/automations) open the respective tab and find your automation or script. ### Customizing an entity in YAML[](https://www.home-assistant.io/docs/configuration/customizing-devices/#customizing-an-entity-in-yaml) If your entity is not supported, or you could not customize what you need via the user interface, you need to edit the settings in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file. For a detailed description of the entity configuration variables and [device class](https://www.home-assistant.io/integrations/homeassistant/#device-class) information, refer to the [Home Assistant Core integration documentation](https://www.home-assistant.io/integrations/homeassistant/) . Related topics[](https://www.home-assistant.io/docs/configuration/customizing-devices/#related-topics) ------------------------------------------------------------------------------------------------------- * [Home Assistant Core Integration](https://www.home-assistant.io/integrations/homeassistant/) * [Configuration.yaml file](https://www.home-assistant.io/docs/configuration/) * [Troubleshooting your configuration](https://www.home-assistant.io/docs/configuration/troubleshooting/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/customizing-devices/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/customizing-devices.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fcustomizing-devices%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fcustomizing-devices%2F%22&in=body "View given feedback for this page") --- # Automation YAML - Home Assistant Automations are created in Home Assistant via the UI, but are stored in a YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) format. If you want to edit the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) of an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) , select the automation, click on the menu button in the top right then on **Edit in YAML**. The UI will write your automations to `automations.yaml`. This file is managed by the UI and should not be edited manually. It is also possible to write your automations directly inside `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) or other YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) files. You can do this by adding a labeled `automation` block to your `configuration.yaml`: # The configuration required for the UI to work automation: !include automations.yaml # Labeled automation block automation kitchen: - triggers: - trigger: ... You can add as many labeled `automation` blocks as you want. #### Configuration Variables[](https://www.home-assistant.io/docs/automation/yaml/#yaml-configuration-variables) [Looking for your configuration file?](https://www.home-assistant.io/docs/configuration/) alias string (Optional)[](https://www.home-assistant.io/docs/automation/yaml/#alias) Friendly name for the automation. id string (Optional)[](https://www.home-assistant.io/docs/automation/yaml/#id) A unique id for your automation, will allow you to make changes to the name and entity\_id in the UI, and will enable debug traces. description string (Optional)[](https://www.home-assistant.io/docs/automation/yaml/#description) A description of the automation. initial\_state boolean (Optional, default: Restored from last run)[](https://www.home-assistant.io/docs/automation/yaml/#initial_state) Used to define the state of your automation at startup. When not set, the state will be restored from the last run. See [Automation initial state](https://www.home-assistant.io/docs/automation/yaml/#automation-initial-state) . trace map (Optional, default: {})[](https://www.home-assistant.io/docs/automation/yaml/#trace) Configuration values for the traces stored, currently only `stored_traces` can be configured. stored\_traces integer (Optional, default: 5)[](https://www.home-assistant.io/docs/automation/yaml/#stored_traces) The number of traces which will be stored. See [Number of debug traces stored](https://www.home-assistant.io/docs/automation/yaml/#number-of-debug-traces-stored) . variables map (Optional, default: {})[](https://www.home-assistant.io/docs/automation/yaml/#variables) Variables that will be available inside your templates, both in `conditions` and `actions`. PARAMETER\_NAME any[](https://www.home-assistant.io/docs/automation/yaml/#parameter_name) The value of the variable. Any YAML is valid. Templates can also be used to pass a value to the variable. trigger\_variables map (Optional, default: {})[](https://www.home-assistant.io/docs/automation/yaml/#trigger_variables) Variables that will be available inside your [templates triggers](https://www.home-assistant.io/docs/automation/trigger/#template-trigger) . PARAMETER\_NAME any[](https://www.home-assistant.io/docs/automation/yaml/#parameter_name) The value of the variable. Any YAML is valid. Only [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) can be used. mode string (Optional, default: single)[](https://www.home-assistant.io/docs/automation/yaml/#mode) Controls what happens when the automation is invoked while it is still running from one or more previous invocations. See [Automation modes](https://www.home-assistant.io/docs/automation/yaml/#automation-modes) . max integer (Optional, default: 10)[](https://www.home-assistant.io/docs/automation/yaml/#max) Controls maximum number of runs executing and/or queued up to run at a time. Only valid with modes `queued` and `parallel`. max\_exceeded string (Optional, default: warning)[](https://www.home-assistant.io/docs/automation/yaml/#max_exceeded) When `max` is exceeded (which is effectively 1 for `single` mode) a log message will be emitted to indicate this has happened. This option controls the severity level of that log message. See [Log Levels](https://www.home-assistant.io/integrations/logger/#log-levels) for a list of valid options. Or `silent` may be specified to suppress the message from being emitted. triggers list Required[](https://www.home-assistant.io/docs/automation/yaml/#triggers) The trigger(s) which will start the automation. Multiple triggers can be added and the automation will start when any of these triggers trigger. id string (Optional)[](https://www.home-assistant.io/docs/automation/yaml/#id) An ID that can be used in the automation to determine which trigger caused the automation to start. variables map (Optional, default: {})[](https://www.home-assistant.io/docs/automation/yaml/#variables) Variables that will be available in the conditions and action sequence. PARAMETER\_NAME any[](https://www.home-assistant.io/docs/automation/yaml/#parameter_name) The value of the variable. Any YAML is valid. Templates can also be used to pass a value to the variable. conditions list (Optional)[](https://www.home-assistant.io/docs/automation/yaml/#conditions) Conditions that have to be `true` to start the automation. By default all conditions listed have to be `true`, you can use [logical conditions](https://www.home-assistant.io/docs/scripts/conditions/#logical-conditions) to change this default behavior. actions list Required[](https://www.home-assistant.io/docs/automation/yaml/#actions) The sequence of actions to be performed in the script. ### Automation modes[](https://www.home-assistant.io/docs/automation/yaml/#automation-modes) | Mode | Description | | --- | --- | | `single` | Do not start a new run. Issue a warning. | | `restart` | Start a new run after first stopping previous run. | | `queued` | Start a new run after all previous runs complete. Runs are guaranteed to execute in the order they were queued. | | `parallel` | Start a new, independent run in parallel with previous runs. | ![](https://www.home-assistant.io/images/integrations/script/script_modes.jpg) YAML example[](https://www.home-assistant.io/docs/automation/yaml/#yaml-example) --------------------------------------------------------------------------------- Example of a YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) based automation that you can add to `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) . # Example of entry in configuration.yaml automation my_lights: # Turns on lights 1 hour before sunset if people are home # and if people get home between 16:00-23:00 - alias: "Rule 1 Light on in the evening" triggers: # Prefix the first line of each trigger configuration # with a '-' to enter multiple - trigger: sun event: sunset offset: "-01:00:00" - trigger: state entity_id: all to: "home" conditions: # Prefix the first line of each condition configuration # with a '-'' to enter multiple - condition: state entity_id: all state: "home" - condition: time after: "16:00:00" before: "23:00:00" actions: # With a single action entry, we don't need a '-' before action - though you can if you want to - action: homeassistant.turn_on target: entity_id: group.living_room # Turn off lights when everybody leaves the house - alias: "Rule 2 - Away Mode" triggers: - trigger: state entity_id: all to: "not_home" actions: - action: light.turn_off target: entity_id: all # Notify when Paulus leaves the house in the evening - alias: "Leave Home notification" triggers: - trigger: zone event: leave zone: zone.home entity_id: device_tracker.paulus conditions: - condition: time after: "20:00" actions: - action: notify.notify data: message: "Paulus left the house" # Send a notification via Pushover with the event of a Xiaomi cube. Custom event from the Xiaomi integration. - alias: "Xiaomi Cube Action" initial_state: false triggers: - trigger: event event_type: cube_action event_data: entity_id: binary_sensor.cube_158d000103a3de actions: - action: notify.pushover data: title: "Cube event detected" message: "Cube has triggered this event: {{ trigger.event }}" Extra options[](https://www.home-assistant.io/docs/automation/yaml/#extra-options) ----------------------------------------------------------------------------------- When writing automations directly in YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) , you will have access to advanced options that are not available in the user interface. ### Automation initial state[](https://www.home-assistant.io/docs/automation/yaml/#automation-initial-state) At startup, automations by default restore their last state of when Home Assistant ran. This can be controlled with the `initial_state` option. Set it to `false` or `true` to force initial state to be off or on. automation: - alias: "Automation Name" initial_state: false triggers: - trigger: ... ### Number of debug traces stored[](https://www.home-assistant.io/docs/automation/yaml/#number-of-debug-traces-stored) When using YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) you can configure the number of debugging traces stored for an automation. This is controlled with the `stored_traces` option under `trace`. Set `stored_traces` to the number of traces you wish to store for the particular automation. If not specified the default value of 5 will be used. automation: - alias: "Automation Name" trace: stored_traces: 10 triggers: - trigger: ... Migrating your YAML automations to automations.yaml[](https://www.home-assistant.io/docs/automation/yaml/#migrating-your-yaml-automations-to-automationsyaml) -------------------------------------------------------------------------------------------------------------------------------------------------------------- If you want to migrate your manual automations to use the editor, you’ll have to copy them to `automations.yaml`. Make sure that `automations.yaml` remains a list! For each automation that you copy over, you’ll have to add an `id`. This can be any string as long as it’s unique. # Example automations.yaml entry. Note, automations.yaml is always a list! - id: my_unique_id # <-- Required for editor to work, for automations created with the editor the id will be automatically generated. alias: "Hello world" triggers: - trigger: state entity_id: sun.sun from: below_horizon to: above_horizon conditions: - condition: numeric_state entity_id: sensor.temperature above: 17 below: 25 value_template: "{{ float(state.state) + 2 }}" actions: - action: light.turn_on ### Deleting automations[](https://www.home-assistant.io/docs/automation/yaml/#deleting-automations) When automations remain visible in the Home Assistant dashboard, even after having deleted in the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file, you have to delete them in the UI. To delete them completely, go to UI [**Settings** > **Devices & services** > **Entities**](https://my.home-assistant.io/redirect/entities) and find the automation in the search field or by scrolling down. Check the square box aside of the automation you wish to delete and from the top-right of your screen, select ‘REMOVE SELECTED’. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/yaml/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/yaml.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Fyaml%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Fyaml%2F%22&in=body "View given feedback for this page") --- # Events - Home Assistant The core of Home Assistant is the event bus. The event bus allows any integration to fire or listen for events. Events and state changes[](https://www.home-assistant.io/docs/configuration/events/#events-and-state-changes) -------------------------------------------------------------------------------------------------------------- All entitiesAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) produce state change events. Every time a stateThe state holds the information of interest of an entity, for example, if a light is on or off. Each entity has exactly one state and the state only holds one value at a time. However, entities can store attributes related to that state such as brightness, color, or a unit of measurement. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/state_object/) 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](https://www.home-assistant.io/docs/configuration/events/#built-in-events-core) that are used to coordinate between various integrations. ### State change events versus event entity[](https://www.home-assistant.io/docs/configuration/events/#state-change-events-versus-event-entity) State change events are not to be confused with the [event entity](https://www.home-assistant.io/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[](https://www.home-assistant.io/docs/configuration/events/#common-fields) ---------------------------------------------------------------------------------------- All events share these basic fields. | Field | Description | | --- | --- | | `event_type` | Type of the event. Example: `call_service`. | | `origin` | Origin of the event. `REMOTE` (coming in from the API, e.g. a webhook) or `LOCAL` (everything else). | | `time_fired` | When the event was fired. Example: `2022-01-28T12:19:53.736380+00:00`. | | `context` | Dictionary with the [context](https://data.home-assistant.io/docs/context/)
. Example: `{ 'id': '123', "parent_id": null, 'user_id': 'abc'}`. | In addition, all events contain a `data` dictionary with event-specific information. These are described below. Built-in Events (core)[](https://www.home-assistant.io/docs/configuration/events/#built-in-events-core) -------------------------------------------------------------------------------------------------------- ### call\_service[](https://www.home-assistant.io/docs/configuration/events/#call_service) This event is fired when an service action is performed | 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[](https://www.home-assistant.io/docs/configuration/events/#component_loaded) This event is fired when a new integration has been loaded and initialized. Please note that while this event is fired for each loaded integration during Home Assistant startup, the automation engine of Home Assistant is started last. Thus this event can not be used to run automations during startup as it would have missed these events. | Field | Description | | --- | --- | | `component` | Domain of the integration that has just been initialized. Example: `light`. | ### core\_config\_updated[](https://www.home-assistant.io/docs/configuration/events/#core_config_updated) This event is fired when the core configuration is updated, for example when the location has been changed. It contains no additional data. ### data\_entry\_flow\_progressed[](https://www.home-assistant.io/docs/configuration/events/#data_entry_flow_progressed) This event is fired when a data entry flow has changed and is used by the frontend to reload the flow state. | Field | Description | | --- | --- | | `handler` | The flow handler. | | `flow_id` | Identification of the flow. | ### homeassistant\_start, homeassistant\_started[](https://www.home-assistant.io/docs/configuration/events/#homeassistant_start-homeassistant_started) These events are fired during the startup of Home Assistant, in the following order: 1. `homeassistant_start` 2. `homeassistant_started` These events contain no additional data. If you want to trigger automation on a Home Assistant start event, we recommend using the special [Home Assistant trigger](https://www.home-assistant.io/docs/automation/trigger/#home-assistant-trigger) instead of listening to these events. ### homeassistant\_stop, homeassistant\_final\_write, homeassistant\_close[](https://www.home-assistant.io/docs/configuration/events/#homeassistant_stop-homeassistant_final_write-homeassistant_close) These events are fired during the shutdown of Home Assistant, in the following order: 1. `homeassistant_stop` 2. `homeassistant_final_write` 3. `homeassistant_close` These events contain no additional data. Please note that `homeassistant_final_write` and `homeassistant_close`, cannot be used with automations, as the automation engine would already have been stopped when those are fired. If you want to trigger automation on a Home Assistant stop event, we recommend using the special [Home Assistant trigger](https://www.home-assistant.io/docs/automation/trigger/#home-assistant-trigger) instead of listening to these events. ### logbook\_entry[](https://www.home-assistant.io/docs/configuration/events/#logbook_entry) | Field | Description | | --- | --- | | `name` | Name of the entity. Example: `Kitchen light`. | | `message` | Message. Example: `was turned on` | | `domain` | Optional, domain of the entry. Example: `light` | | `entity_id` | Optional, identifier of the entity that was logged. | ### service\_registered[](https://www.home-assistant.io/docs/configuration/events/#service_registered) 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 action. Example: `light`. | | `service` | The name of the service action. Example: `turn_on` | ### service\_removed[](https://www.home-assistant.io/docs/configuration/events/#service_removed) 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 action. Example: `light`. | | `service` | The name of the service action. Example: `turn_on` | ### state\_changed[](https://www.home-assistant.io/docs/configuration/events/#state_changed) This event is fired when a state has changed. It contains the entity identifier and both the `new_state` and `old_state` of the entity as [state objects](https://www.home-assistant.io/topics/state_object/) . | Field | Description | | --- | --- | | `entity_id` | Identifier of the entity that has changed. Example: `light.kitchen` | | `old_state` | The previous state of the entity before it changed. Omitted if the state is set for the first time. | | `new_state` | The new state of the entity. Omitted if the state has been removed. | ### themes\_updated[](https://www.home-assistant.io/docs/configuration/events/#themes_updated) This event is fired after a theme has been set or reloaded. It contains no additional data. ### user\_added[](https://www.home-assistant.io/docs/configuration/events/#user_added) This event is fired when a user has been added. | Field | Description | | --- | --- | | `user_id` | Identification of the new user. | ### user\_removed[](https://www.home-assistant.io/docs/configuration/events/#user_removed) This event is fired when a user has been removed. | Field | Description | | --- | --- | | `user_id` | Identification of the removed user. | Built-in events (default integrations)[](https://www.home-assistant.io/docs/configuration/events/#built-in-events-default-integrations) ---------------------------------------------------------------------------------------------------------------------------------------- ### automation\_reloaded[](https://www.home-assistant.io/docs/configuration/events/#automation_reloaded) Integration: [`automation`](https://www.home-assistant.io/integrations/automation/) This event is fired when automations have been reloaded and thus might have changed. This event contains no additional data. ### automation\_triggered[](https://www.home-assistant.io/docs/configuration/events/#automation_triggered) Integration: [`automation`](https://www.home-assistant.io/integrations/automation/) This event is fired when an automation is triggered. | Field | Description | | --- | --- | | `name` | The name of the automation. | | `entity_id` | The identifier of the automation. | ### scene\_reloaded[](https://www.home-assistant.io/docs/configuration/events/#scene_reloaded) Integration: [`homeassistant`](https://www.home-assistant.io/integrations/homeassistant/) This event is fired when scenes have been reloaded and thus might have changed. This event contains no additional data. ### script\_started[](https://www.home-assistant.io/docs/configuration/events/#script_started) Integration: [`script`](https://www.home-assistant.io/integrations/script/) This event is fired when a script is run. A script can be invoked by a user or triggered by an automation. The resulting changes can be tracked because all related events will share the same context as this event. | Field | Description | | --- | --- | | `name` | Name of the script that was run. | | `entity_id` | Identifier of the script that was run. | Related topics[](https://www.home-assistant.io/docs/configuration/events/#related-topics) ------------------------------------------------------------------------------------------ * [Event triggers](https://www.home-assistant.io/docs/automation/trigger/#event-trigger) * [Event integration](https://www.home-assistant.io/integrations/event/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/events/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/events.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fevents%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fevents%2F%22&in=body "View given feedback for this page") --- # Remote access - Home Assistant 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](https://www.home-assistant.io/docs/configuration/securing/) before doing this. Home Assistant Cloud[](https://www.home-assistant.io/docs/configuration/remote/#home-assistant-cloud) ------------------------------------------------------------------------------------------------------ Users of [Home Assistant Cloud](https://www.nabucasa.com/) can use the [Home Assistant Cloud remote access](https://www.nabucasa.com/config/remote/) feature without requiring any configuration. A unique remote URL will be generated and given to you along with a certificate so all your traffic to Home Assistant is encrypted automatically. VPN[](https://www.home-assistant.io/docs/configuration/remote/#vpn) -------------------------------------------------------------------- A secure way to remotely access your Home Assistant is to use a Virtual Private Network (VPN) service such as [Tailscale](https://tailscale.com/) or [ZeroTier One](https://www.zerotier.com/) . A VPN connection needs to be established before you can connect to your Home Assistant from outside your local network. The VPN makes this connection secure. When using the Home Assistant Companion app (such as on a mobile device), without this connection, your sensors will not update in Home Assistant. Port forwarding[](https://www.home-assistant.io/docs/configuration/remote/#port-forwarding) -------------------------------------------------------------------------------------------- Set up port forwarding (for any port) from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching ` port forwarding instructions`. You can use any free port on your router and forward that to port 8123. A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/) . 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](https://www.home-assistant.io/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/) blog post or this [detailed guide](https://community.home-assistant.io/t/196970) to using Let’s Encrypt with Home Assistant. Adding a remote URL to Home Assistant[](https://www.home-assistant.io/docs/configuration/remote/#adding-a-remote-url-to-home-assistant) ---------------------------------------------------------------------------------------------------------------------------------------- To set the URL under which your Home Assistant can be accessed from outside your local network, follow these steps: 1. In the bottom left, select your username to go to your [**User profile**](https://my.home-assistant.io/redirect/profile) , and make sure **Advanced mode** is enabled. 2. Go to [**Settings** > **System** > **Network**](https://my.home-assistant.io/redirect/network) . 3. Under **Home Assistant URL**, enter the external URL that you previously set up for your instance. Related topics[](https://www.home-assistant.io/docs/configuration/remote/#related-topics) ------------------------------------------------------------------------------------------ * [Securing your instance](https://www.home-assistant.io/docs/configuration/securing/) Related links[](https://www.home-assistant.io/docs/configuration/remote/#related-links) ---------------------------------------------------------------------------------------- * [Home Assistant Cloud - remote access](https://www.nabucasa.com/config/remote/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/remote/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/remote.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fremote%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fremote%2F%22&in=body "View given feedback for this page") --- # Storing secrets - Home Assistant The `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) 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 `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file or even multiple YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) files if you [split up your configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/) . Using secrets.yaml[](https://www.home-assistant.io/docs/configuration/secrets/#using-secretsyaml) -------------------------------------------------------------------------------------------------- The workflow for moving private information to `secrets.yaml` is very similar to the [splitting of the configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/) . Create a `secrets.yaml` file in your Home Assistant [configuration directory](https://www.home-assistant.io/docs/configuration/) . The entries for password and API keys in the `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file usually looks like the example below. rest: - authentication: basic username: "admin" password: "YOUR_PASSWORD" ... Those entries need to be replaced with `!secret` and an identifier. rest: - authentication: basic username: "admin" password: !secret rest_password ... The `secrets.yaml` file contains the corresponding password assigned to the identifier. rest_password: "YOUR_PASSWORD" Debugging secrets[](https://www.home-assistant.io/docs/configuration/secrets/#debugging-secrets) ------------------------------------------------------------------------------------------------- When you start splitting your configuration into multiple files, you might end up with configuration in sub folders. Secrets will be resolved in this order: * A `secrets.yaml` located in the same folder as the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file referencing the secret, * next, parent folders will be searched for a `secrets.yaml` file with the secret, stopping at the folder with the main `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) . To see where secrets are being loaded from, you can add an option to your `secrets.yaml` file. Print where secrets are retrieved from to the Home Assistant log by adding the following to `secrets.yaml`: logger: debug This will not print the actual secret’s value to the log. Related topics[](https://www.home-assistant.io/docs/configuration/secrets/#related-topics) ------------------------------------------------------------------------------------------- * [Configuration.yaml file](https://www.home-assistant.io/docs/configuration/) * [Splitting the configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/) * [Securing your instance](https://www.home-assistant.io/docs/configuration/securing/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/secrets/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/secrets.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fsecrets%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fsecrets%2F%22&in=body "View given feedback for this page") --- # Floors - Home Assistant A floor in Home Assistant is a logical grouping of areasAn area in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of devices and entities that are meant to match areas (or rooms) in the physical world: your home. For example, the `living room` area groups devices and entities in your living room. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/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 automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) and scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) as a target for actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . For example, to turn off all the lights on the downstairs floor when you go to bed. Creating a floor[](https://www.home-assistant.io/docs/organizing/floors/#creating-a-floor) ------------------------------------------------------------------------------------------- Follow these steps to create a new floor. 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) and select **Create floor**. 2. In the dialog, enter the floor details: * Give the floor a **Name** (required). * Add a floor **Level**. * The number can be negative. For example for underground floors. * This number can later be used for sorting. * Add an icon (We use [Material icons](https://pictogrammers.com/library/mdi/) ). * Add an **Alias**. * Aliases are alternative names used in [voice assistants](https://www.home-assistant.io/voice_control/aliases/) to refer to an entity, area, or floor. ![Create floor dialog](https://www.home-assistant.io/images/organizing/create_floor_01.png) 3. Select **Add**. **Result**: A new floor is created. ![Create floor dialog](https://www.home-assistant.io/images/organizing/create_floor_02.png) 4. You can now [assign areas to that floor](https://www.home-assistant.io/docs/organizing/areas/#assigning-areas-to-floors-and-add-labels) . Reordering floors on built-in dashboards[](https://www.home-assistant.io/docs/organizing/floors/#reordering-floors-on-built-in-dashboards) ------------------------------------------------------------------------------------------------------------------------------------------- Follow these steps to rearrange floors and areas on the built-in dashboards (such as **Overview**, **Lights**, and **Security**). 1. Go to [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) . 2. There are 2 options to rearrange items: * **Option 1**: Use drag-and-drop. * **Option 2**: In the top-right corner, select the three dots menu and select **Reorder floors and areas**. * In the dialog, move the floors or areas you want to rearrange: ![Reorder floors and areas](https://www.home-assistant.io/images/organizing/reorder-areas-menu.png) Deleting a floor[](https://www.home-assistant.io/docs/organizing/floors/#deleting-a-floor) ------------------------------------------------------------------------------------------- Follow these steps to delete a floor. Areas that are assigned to a floor will become unassigned. AutomationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) and scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/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 [**Settings** > **Areas, labels & zones**](https://my.home-assistant.io/redirect/areas) . 2. Next to the floor, select the three dots menu and select **Delete floor**. ![Screenshot showing the dialog to delete a floor](https://www.home-assistant.io/images/organizing/floor_delete.png) 3. If you have automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) , scriptsScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) , or voice assistants that used floors as a target, you will need to update these. Related topics[](https://www.home-assistant.io/docs/organizing/floors/#related-topics) --------------------------------------------------------------------------------------- * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Grouping your assets](https://www.home-assistant.io/docs/organizing/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) * [Using floors in templates](https://www.home-assistant.io/docs/configuration/templating/#floors) * [Using floor alias for voice assistants](https://www.home-assistant.io/voice_control/aliases/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/organizing/floors/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/organizing/floors.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Forganizing%2Ffloors%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Forganizing%2Ffloors%2F%22&in=body "View given feedback for this page") --- # Automation Templates - Home Assistant Automations support the advanced features of [templating](https://www.home-assistant.io/docs/configuration/templating/) in the same way as scripts do. In addition to the [Home Assistant template extensions](https://www.home-assistant.io/docs/configuration/templating/#home-assistant-template-extensions) available to scripts, the `trigger` and `this` template variables are available for automations. Example of variables used in templates: * `{{ this.name }}` is the name of the automation executing from this trigger * `{{ trigger.platform }}` is the type of trigger object, like `calendar` Available state data[](https://www.home-assistant.io/docs/automation/templating/#available-state-data) ------------------------------------------------------------------------------------------------------- The template variable `this` is an object that contains the [state](https://www.home-assistant.io/docs/configuration/state_object) of the automation at the moment of triggering the actions and can be used to evaluate [`trigger_variables`](https://www.home-assistant.io/docs/automation/trigger/#trigger-variables) declared in the configuration of the active triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) . State objects also contain context data which can be used to identify the user that caused a scriptScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) or automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) to execute. Note that `this` will not change while executing the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . Available trigger data[](https://www.home-assistant.io/docs/automation/templating/#available-trigger-data) ----------------------------------------------------------------------------------------------------------- The template variable `trigger` is an object that contains details about which platformPlatforms are building blocks provided by some integrations to be used by other integrations. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/platform_options/) triggered the automation. The `platform` property contains the name of the platformPlatforms are building blocks provided by some integrations to be used by other integrations. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/platform_options/) whose event triggered the automation. Templates can use the data to modify the actions performed by the automation or displayed in a message. For example, you could create an automation that multiple sensors can trigger and then use the sensor’s location to specify a light to activate; or you could send a notification containing the friendly name of the sensor that triggered it. Each [trigger](https://www.home-assistant.io/docs/automation/trigger/#event-trigger) platform includes additional data specific to that platformPlatforms are building blocks provided by some integrations to be used by other integrations. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/platform_options/) . ### All[](https://www.home-assistant.io/docs/automation/templating/#all) Triggers from all platforms will include the following properties. | Template variable | Data | | --- | --- | | `trigger.platform` | Trigger object type. | | `trigger.alias` | Alias of the trigger. | | `trigger.id` | The [`id` of the trigger](https://www.home-assistant.io/docs/automation/trigger/#trigger-id)
. | | `trigger.idx` | Index of the trigger. (The first trigger idx is `0`.) | ### Calendar[](https://www.home-assistant.io/docs/automation/templating/#calendar) These are the properties available for a [Calendar trigger](https://www.home-assistant.io/docs/automation/trigger/#calendar-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `calendar` | | `trigger.event` | The trigger event type, either `start` or `end`. | | `trigger.calendar_event` | The calendar event object matched. | | `trigger.calendar_event.summary` | The title or summary of the calendar event. | | `trigger.calendar_event.start` | String representation of the start date or date time of the calendar event e.g. `2022-04-10`, or `2022-04-10 11:30:00-07:00` | | `trigger.calendar_event.end` | String representation of the end time of date time the calendar event in UTC e.g. `2022-04-11`, or `2022-04-10 11:45:00-07:00` | | `trigger.calendar_event.all_day` | Indicates the event spans the entire day. | | `trigger.calendar_event.description` | A detailed description of the calendar event, if available. | | `trigger.calendar_event.location` | Location information for the calendar event, if available. | | `trigger.offset` | Timedelta object with offset to the event, if any. | ### Device[](https://www.home-assistant.io/docs/automation/templating/#device) These are the properties available for a [Device trigger](https://www.home-assistant.io/docs/automation/trigger/#device-triggers) . Inherits template variables from [event](https://www.home-assistant.io/docs/automation/templating/#event) or [state](https://www.home-assistant.io/docs/automation/templating/#state) template based on the type of trigger selected for the device. | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `device` | ### Event[](https://www.home-assistant.io/docs/automation/templating/#event) An [Event](https://www.home-assistant.io/docs/configuration/events/) trigger is fired each time an entityAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) state changes or an event matching the configured event\_type occurs. These are the properties available for an [Event trigger](https://www.home-assistant.io/docs/automation/trigger/#event-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `event` | | `trigger.event` | Event object that matched. | | `trigger.event.event_type` | Event type. | | `trigger.event.data` | Optional event data. | ### Geolocation[](https://www.home-assistant.io/docs/automation/templating/#geolocation) These are the properties available for a [Geolocation trigger](https://www.home-assistant.io/docs/automation/trigger/#geolocation-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `geo_location` | | `trigger.event` | The trigger event type, either `enter` or `leave`. | | `trigger.source` | The Geolocation platform creating the trigger event. | | `trigger.zone` | State object of the zone. | ### Home Assistant[](https://www.home-assistant.io/docs/automation/templating/#home-assistant) The Home Assistant trigger is recommended for automations instead of [homeassistant\_start or homeassistant\_stop events](https://www.home-assistant.io/docs/configuration/events/#homeassistant_start-homeassistant_started) . These are the properties available for a [Home Assistant trigger](https://www.home-assistant.io/docs/automation/trigger/#home-assistant-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `homeassistant` | | `trigger.event` | The trigger event type, either `start` or `shutdown`. | ### MQTT[](https://www.home-assistant.io/docs/automation/templating/#mqtt) These are the properties available for a [MQTT trigger](https://www.home-assistant.io/docs/automation/trigger/#mqtt-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `mqtt` | | `trigger.topic` | Topic that received payload. | | `trigger.payload` | Payload. | | `trigger.payload_json` | Dictionary of the JSON parsed payload. | | `trigger.qos` | QOS of payload. | ### Numeric state[](https://www.home-assistant.io/docs/automation/templating/#numeric-state) These are the properties available for a [numeric state trigger](https://www.home-assistant.io/docs/automation/trigger/#numeric-state-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `numeric_state` | | `trigger.entity_id` | Entity ID that we observe. | | `trigger.below` | The below threshold, if any. | | `trigger.above` | The above threshold, if any. | | `trigger.from_state` | The previous [state object](https://www.home-assistant.io/docs/configuration/state_object/)
of the entity. | | `trigger.to_state` | The new [state object](https://www.home-assistant.io/docs/configuration/state_object/)
that triggered trigger. | | `trigger.for` | Timedelta object how long state has met above/below criteria, if any. | ### Sentence[](https://www.home-assistant.io/docs/automation/templating/#sentence) These are the properties available for a [Sentence trigger](https://www.home-assistant.io/docs/automation/trigger/#sentence-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `conversation` | | `trigger.sentence` | Text of the sentence that was matched. | | `trigger.slots` | Object with matched slot values. | | `trigger.details` | Object with matched slot details by name, such as [wildcards](https://www.home-assistant.io/docs/automation/trigger/#sentence-wildcards)
. Each detail contains:

* `name` - name of the slot
* `text` - matched text
* `value` - output value (see [lists](https://www.home-assistant.io/docs/voice/intent-recognition/template-sentence-syntax/#lists)
)

. | | `trigger.device_id` | The device ID that captured the command, if any. | | `trigger.satellite_id` | The entity ID of the satellite that captured the command, if any. | ### State[](https://www.home-assistant.io/docs/automation/templating/#state) These are the properties available for a [State trigger](https://www.home-assistant.io/docs/automation/trigger/#state-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `state` | | `trigger.entity_id` | Entity ID that we observe. | | `trigger.from_state` | The previous [state object](https://www.home-assistant.io/docs/configuration/state_object/)
of the entity. | | `trigger.to_state` | The new [state object](https://www.home-assistant.io/docs/configuration/state_object/)
that triggered trigger. | | `trigger.for` | Timedelta object how long state has been to state, if any. | ### Sun[](https://www.home-assistant.io/docs/automation/templating/#sun) These are the properties available for a [Sun trigger](https://www.home-assistant.io/docs/automation/trigger/#sun-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `sun` | | `trigger.event` | The event that just happened: `sunset` or `sunrise`. | | `trigger.offset` | Timedelta object with offset to the event, if any. | ### Tag[](https://www.home-assistant.io/docs/automation/templating/#tag) These are the properties available for a [Tag trigger](https://www.home-assistant.io/docs/automation/trigger/#tag-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `tag` | | `trigger.tag_id` | The tag ID captured. | | `trigger.device_id` | Optional device ID that captured the tag. | ### Template[](https://www.home-assistant.io/docs/automation/templating/#template) These are the properties available for a [Template trigger](https://www.home-assistant.io/docs/automation/trigger/#template-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `template` | | `trigger.entity_id` | Entity ID that caused change. | | `trigger.from_state` | Previous [state object](https://www.home-assistant.io/docs/configuration/state_object/)
of entity that caused change. | | `trigger.to_state` | New [state object](https://www.home-assistant.io/docs/configuration/state_object/)
of entity that caused template to change. | | `trigger.for` | Timedelta object how long state has been to state, if any. | ### Time[](https://www.home-assistant.io/docs/automation/templating/#time) These are the properties available for a [Time trigger](https://www.home-assistant.io/docs/automation/trigger/#time-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `time` | | `trigger.now` | DateTime object that triggered the time trigger. | ### Time pattern[](https://www.home-assistant.io/docs/automation/templating/#time-pattern) These are the properties available for a [time pattern trigger](https://www.home-assistant.io/docs/automation/trigger/#time-pattern-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `time_pattern` | | `trigger.now` | DateTime object that triggered the time\_pattern trigger. | ### Persistent notification[](https://www.home-assistant.io/docs/automation/templating/#persistent-notification) These properties are available for a [persistent notification trigger](https://www.home-assistant.io/docs/automation/trigger/#persistent-notification-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `persistent_notification` | | `trigger.update_type` | Type of persistent notification update `added`, `removed`, `current`, or `updated`. | | `trigger.notification` | Notification object that triggered the persistent notification trigger. | | `trigger.notification.notification_id` | The notification ID. | | `trigger.notification.title` | Title of the notification. | | `trigger.notification.message` | Message of the notification. | | `trigger.notification.created_at` | DateTime object indicating when the notification was created. | ### Webhook[](https://www.home-assistant.io/docs/automation/templating/#webhook) These are the properties available for a [Webhook trigger](https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `webhook` | | `trigger.webhook_id` | The webhook ID that was triggered. | | `trigger.json` | The JSON data of the request (if it had a JSON content type) as a mapping. | | `trigger.data` | The form data of the request (if it had a form data content type). | | `trigger.query` | The URL query parameters of the request (if provided). | ### Zone[](https://www.home-assistant.io/docs/automation/templating/#zone) These are the properties available for a [Zone trigger](https://www.home-assistant.io/docs/automation/trigger/#zone-trigger) . | Template variable | Data | | --- | --- | | `trigger.platform` | Hardcoded: `zone` | | `trigger.entity_id` | Entity ID that we are observing. | | `trigger.from_state` | Previous [state object](https://www.home-assistant.io/docs/configuration/state_object/)
of the entity. | | `trigger.to_state` | New [state object](https://www.home-assistant.io/docs/configuration/state_object/)
of the entity. | | `trigger.zone` | State object of the zone. | | `trigger.event` | Event that trigger observed: `enter` or `leave`. | Examples[](https://www.home-assistant.io/docs/automation/templating/#examples) ------------------------------------------------------------------------------- # Example configuration.yaml entries automation: triggers: - trigger: state entity_id: device_tracker.paulus id: paulus_device actions: - action: notify.notify data: message: > Paulus just changed from {{ trigger.from_state.state }} to {{ trigger.to_state.state }} This was triggered by {{ trigger.id }} automation 2: triggers: - trigger: mqtt topic: "/notify/+" actions: - action: > notify.{{ trigger.topic.split('/')[-1] }} data: message: "{{ trigger.payload }}" automation 3: triggers: # Multiple entities for which you want to perform the same action. - trigger: state entity_id: - light.bedroom_closet - light.kiddos_closet - light.linen_closet to: "on" # Trigger when someone leaves one of those lights on for 10 minutes. for: "00:10:00" actions: - action: light.turn_off target: # Turn off whichever entity triggered the automation. entity_id: "{{ trigger.entity_id }}" automation 4: triggers: # When an NFC tag is scanned by Home Assistant... - trigger: event event_type: tag_scanned # ...By certain people context: user_id: - 06cbf6deafc54cf0b2ffa49552a396ba - 2df8a2a6e0be4d5d962aad2d39ed4c9c conditions: # Check NFC tag (ID) is the one by the front door - condition: template value_template: "{{ trigger.event.data.tag_id == '8b6d6755-b4d5-4c23-818b-cf224d221ab7'}}" actions: # Turn off various lights - action: light.turn_off target: entity_id: - light.kitchen - light.bedroom - light.living_room #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/templating/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/templating.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Ftemplating%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Ftemplating%2F%22&in=body "View given feedback for this page") --- # Packages - Home Assistant Packages in Home Assistant provide a way to bundle configurations from multiple integrations. With packages, we have a way to include multiple integrations, or parts of integrations using any of the `!include` directives introduced in [splitting the configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration) . Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a package name (no spaces, all lower case) followed by a dictionary with the package configuration. For example, package `pack_1` would be created as: homeassistant: ... packages: pack_1: ...package configuration here... The package configuration can include: `switch`, `light`, `automation`, `groups`, or most other Home Assistant integrations including hardware platforms. It can be specified inline or in a separate YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file using `!include`. Inline example, main `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) : homeassistant: ... packages: pack_1: switch: - platform: rest ... light: - platform: rpi ... Include example, main `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) : homeassistant: ... packages: pack_1: !include my_package.yaml The file `my_package.yaml` contains the “top-level” configuration: switch: - platform: rest ... light: - platform: rpi ... There are some rules for packages that will be merged: 1. Platform based integrations (`light`, `switch`, etc) can always be merged. 2. Integrations where entities are identified by a key that will represent the entity\_id (`{key: config}`) need to have unique ‘keys’ between packages and the main configuration file. For example if we have the following in the main configuration. You are not allowed to re-use “my\_input” again for `input_boolean` in a package: input_boolean: my_input: 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. Create a packages folder[](https://www.home-assistant.io/docs/configuration/packages/#create-a-packages-folder) ---------------------------------------------------------------------------------------------------------------- One way to organize packages is to create a folder named “packages” in your Home Assistant configuration directory. In this packages folder, you can store any number of packages in YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) files, and organize those packages into YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) files and subfolders as you see fit. With `!include_dir_named`, the file name is used as the package name. This means that file names must be globally unique, even across subfolders. This entry in your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) will load all YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) \-files in this _packages_ folder and its sub folders: homeassistant: packages: !include_dir_named packages The benefit of this approach is to pull all configurations required to integrate a system into one file—rather than keeping them spread across several files. You can use other `!include` methods for packages. For example: `!include_dir_merge_named`. However, unlike `!include_dir_merge_named`, the `!include_dir_named` method uses the same indentation as the ‘configuration.yaml’. This means that you can copy and paste elements from the config file. With the `!include_dir_merge_named` method, the package name has to be included in the file. The configuration below then needs to be indented accordingly. This means you cannot directly copy and paste from the configuration file. homeassistant: packages: !include_dir_merge_named packages/ and in `packages/subsystem1/functionality1.yaml`: subsystem1_functionality1: input_boolean: ... binary_sensor: ... automation: Customizing entities with packages[](https://www.home-assistant.io/docs/configuration/packages/#customizing-entities-with-packages) ------------------------------------------------------------------------------------------------------------------------------------ It is possible to [customize entities](https://www.home-assistant.io/docs/configuration/customizing-devices/) within packages. Just create your customization entries under: homeassistant: customize: Important If you are moving configuration to packages, `auth_providers` must stay within ‘configuration.yaml’. See the general documentation for [Authentication Providers](https://www.home-assistant.io/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. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/packages/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/packages.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fpackages%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fpackages%2F%22&in=body "View given feedback for this page") --- # Automation Trigger - Home Assistant Triggers are what starts the processing of an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) rule. When _any_ of the automation’s triggers becomes true (trigger _fires_), Home Assistant will validate the [conditions](https://www.home-assistant.io/docs/automation/condition/) , if any, and call the [action](https://www.home-assistant.io/docs/automation/action/) . An automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) can be triggered by an eventEvery time something happens in Home Assistant, an event is fired. There are different types of events, such as state change events, when an action was triggered, or the time changed. All entities produce state change events. Every time a state changes, a state change event is produced. Events can be used to trigger automations or scripts. For example, you can trigger an automation when a light is turned on, then a speaker turns on in that room. Events can also be used to trigger actions in the frontend. For example, you can trigger an action when a button is pressed. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/events/) , a certain entityAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) stateThe state holds the information of interest of an entity, for example, if a light is on or off. Each entity has exactly one state and the state only holds one value at a time. However, entities can store attributes related to that state such as brightness, color, or a unit of measurement. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/state_object/) , at a given time, and more. These can be specified directly or more flexible via templates. It is also possible to specify multiple triggers for one automation. * [Trigger ID](https://www.home-assistant.io/docs/automation/trigger/#trigger-id) * [Trigger variables](https://www.home-assistant.io/docs/automation/trigger/#trigger-variables) * [Event trigger](https://www.home-assistant.io/docs/automation/trigger/#event-trigger) * [Home Assistant trigger](https://www.home-assistant.io/docs/automation/trigger/#home-assistant-trigger) * [MQTT trigger](https://www.home-assistant.io/docs/automation/trigger/#mqtt-trigger) * [Numeric state trigger](https://www.home-assistant.io/docs/automation/trigger/#numeric-state-trigger) * [State trigger](https://www.home-assistant.io/docs/automation/trigger/#state-trigger) * [Sun trigger](https://www.home-assistant.io/docs/automation/trigger/#sun-trigger) * [Tag trigger](https://www.home-assistant.io/docs/automation/trigger/#tag-trigger) * [Template trigger](https://www.home-assistant.io/docs/automation/trigger/#template-trigger) * [Time trigger](https://www.home-assistant.io/docs/automation/trigger/#time-trigger) * [Time pattern trigger](https://www.home-assistant.io/docs/automation/trigger/#time-pattern-trigger) * [Persistent notification trigger](https://www.home-assistant.io/docs/automation/trigger/#persistent-notification-trigger) * [Webhook trigger](https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger) * [Zone trigger](https://www.home-assistant.io/docs/automation/trigger/#zone-trigger) * [Geolocation trigger](https://www.home-assistant.io/docs/automation/trigger/#geolocation-trigger) * [Device triggers](https://www.home-assistant.io/docs/automation/trigger/#device-triggers) * [Calendar trigger](https://www.home-assistant.io/docs/automation/trigger/#calendar-trigger) * [Sentence trigger](https://www.home-assistant.io/docs/automation/trigger/#sentence-trigger) * [Multiple triggers](https://www.home-assistant.io/docs/automation/trigger/#multiple-triggers) * [Multiple Entity IDs for the same Trigger](https://www.home-assistant.io/docs/automation/trigger/#multiple-entity-ids-for-the-same-trigger) * [Disabling a trigger](https://www.home-assistant.io/docs/automation/trigger/#disabling-a-trigger) * [Merging lists of triggers](https://www.home-assistant.io/docs/automation/trigger/#merging-lists-of-triggers) Trigger ID[](https://www.home-assistant.io/docs/automation/trigger/#trigger-id) -------------------------------------------------------------------------------- All triggers can be assigned an optional `id`. If the ID is omitted, it will instead be set to the index of the trigger. The `id` can be referenced from [trigger conditions and actions](https://www.home-assistant.io/docs/scripts/conditions/#trigger-condition) . The `id` does not have to be unique for each trigger, and it can be used to group similar triggers for use later in the automation (i.e., several triggers of different types that should all turn some entity on). ### Video tutorial[](https://www.home-assistant.io/docs/automation/trigger/#video-tutorial) This video tutorial explains how trigger IDs work. automation: triggers: - trigger: event event_type: "MY_CUSTOM_EVENT" id: "custom_event" - trigger: mqtt topic: "living_room/switch/ac" id: "ac_on" - trigger: state # This trigger will be assigned id="2" entity_id: - device_tracker.paulus - device_tracker.anne_therese to: "home" Trigger variables[](https://www.home-assistant.io/docs/automation/trigger/#trigger-variables) ---------------------------------------------------------------------------------------------- There are two different types of variables available for triggers. Both work like [script level variables](https://www.home-assistant.io/integrations/script/#variables) . The first variant allows you to define variables that will be set when the trigger fires. The variables will be able to use templates and have access to [the `trigger` variable](https://www.home-assistant.io/docs/automation/templating#available-trigger-data) . The second variant is setting variables that are available when attaching a trigger when the trigger can contain templated values. These are defined using the `trigger_variables` key at an automation level. These variables can only contain [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . The triggers will not re-apply if the value of the template changes. Trigger variables are a feature meant to support using blueprint inputs in triggers. automation: trigger_variables: my_event: example_event triggers: - trigger: event # Able to use `trigger_variables` event_type: "{{ my_event }}" # These variables are evaluated and set when this trigger is triggered variables: name: "{{ trigger.event.data.name }}" Event trigger[](https://www.home-assistant.io/docs/automation/trigger/#event-trigger) -------------------------------------------------------------------------------------- An event trigger fires when an [event](https://www.home-assistant.io/docs/configuration/events/) is being received. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data or context to be present. Events can be fired by integrations or via the API. There is no limitation to the types. A list of built-in events can be found [here](https://www.home-assistant.io/docs/configuration/events/) . automation: triggers: - trigger: event event_type: "MY_CUSTOM_EVENT" # optional event_data: mood: happy context: user_id: # any of these will match - "MY_USER_ID" - "ANOTHER_USER_ID" It is also possible to listen for multiple events at once. This is useful for event that contain no, or similar, data and contexts. automation: triggers: - trigger: event event_type: - automation_reloaded - scene_reloaded It’s also possible to use [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) in the `event_type`, `event_data` and `context` options. Important The `event_type`, `event_data` and `context` templates are only evaluated when setting up the trigger, they will not be reevaluated for every event. automation: trigger_variables: sub_event: ABC node: ac value: on triggers: - trigger: event event_type: "{{ 'MY_CUSTOM_EVENT_' ~ sub_event }}" Home Assistant trigger[](https://www.home-assistant.io/docs/automation/trigger/#home-assistant-trigger) -------------------------------------------------------------------------------------------------------- Fires when Home Assistant starts up or shuts down. automation: triggers: - trigger: homeassistant # Event can also be 'shutdown' event: start Note Automations triggered by the `shutdown` event have 20 seconds to run, after which they are stopped to continue with the shutdown. MQTT trigger[](https://www.home-assistant.io/docs/automation/trigger/#mqtt-trigger) ------------------------------------------------------------------------------------ Fires when a specific message is received on given MQTT topic. Optionally can match on the payload being sent over the topic. The default payload encoding is ‘utf-8’. For images and other byte payloads use `encoding: ''` to disable payload decoding completely. automation: triggers: - trigger: mqtt topic: "living_room/switch/ac" # Optional payload: "on" encoding: "utf-8" The `payload` option can be combined with a `value_template` to process the message received on the given MQTT topic before matching it with the payload. The trigger in the example below will trigger only when the message received on `living_room/switch/ac` is valid JSON, with a key `state` which has the value `"on"`. automation: triggers: - trigger: mqtt topic: "living_room/switch/ac" payload: "on" value_template: "{{ value_json.state }}" It’s also possible to use [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) in the `topic` and `payload` options. Note The `topic` and `payload` templates are only evaluated when setting up the trigger, they will not be re-evaluated for every incoming MQTT message. automation: trigger_variables: room: "living_room" node: "ac" value: "on" triggers: - trigger: mqtt topic: "{{ room ~ '/switch/' ~ node}}" # Optional payload: "{{ 'state:' ~ value }}" encoding: "utf-8" Numeric state trigger[](https://www.home-assistant.io/docs/automation/trigger/#numeric-state-trigger) ------------------------------------------------------------------------------------------------------ Fires when the numeric value of an entity’s state (or attribute’s value if using the `attribute` property, or the calculated value if using the `value_template` property) **crosses** a given threshold (equal excluded). On state change of a specified entity, attempts to parse the state as a number and fires if the value is changing from above to below or from below to above the given threshold (equal excluded). Note Crossing the threshold means that the trigger only fires if the state wasn’t previously within the threshold. If the current state of your entity is `50` and you set the threshold to `below: 75`, the trigger would not fire if the state changed to e.g. `49` or `72` because the threshold was never crossed. The state would first have to change to e.g. `76` and then to e.g. `74` for the trigger to fire. automation: triggers: - trigger: numeric_state entity_id: sensor.temperature # If given, will trigger when the value of the given attribute for the given entity changes.. attribute: attribute_name # ..or alternatively, will trigger when the value given by this evaluated template changes. value_template: "{{ state.attributes.value - 5 }}" # At least one of the following required above: 17 below: 25 # If given, will trigger when the condition has been true for X time; you can also use days and milliseconds. for: hours: 1 minutes: 10 seconds: 5 Note Listing above and below together means the numeric\_state has to be between the two values. In the example above, the trigger would fire a single time if a numeric\_state goes into the 17.1-24.9 range (above 17 and below 25). It will only fire again, once it has left the defined range and enters it again. When the `attribute` option is specified the trigger is compared to the given `attribute` instead of the state of the entity. automation: triggers: - trigger: numeric_state entity_id: climate.kitchen attribute: current_temperature above: 23 More dynamic and complex calculations can be done with `value_template`. The variable ‘state’ is the [state object](https://www.home-assistant.io/docs/configuration/state_object) of the entity specified by `entity_id`. The state of the entity can be referenced like this: automation: triggers: - trigger: numeric_state entity_id: sensor.temperature value_template: "{{ state.state | float * 9 / 5 + 32 }}" above: 70 Attributes of the entity can be referenced like this: automation: triggers: - trigger: numeric_state entity_id: climate.kitchen value_template: "{{ state.attributes.current_temperature - state.attributes.temperature_set_point }}" above: 3 Number helpers (`input_number` entities), `number`, `sensor`, and `zone` entities that contain a numeric value, can be used in the `above` and `below` thresholds. However, the comparison will only be made when the entity specified in the trigger is updated. This would look like: automation: triggers: - trigger: numeric_state entity_id: sensor.outside_temperature # Other entity ids can be specified for above and/or below thresholds above: sensor.inside_temperature The `for:` can also be specified as `HH:MM:SS` like this: automation: triggers: - trigger: numeric_state entity_id: sensor.temperature # At least one of the following required above: 17 below: 25 # If given, will trigger when condition has been for X time. for: "01:10:05" You can also use templates in the `for` option. automation: triggers: - trigger: numeric_state entity_id: - sensor.temperature_1 - sensor.temperature_2 above: 80 for: minutes: "{{ states('input_number.high_temp_min')|int }}" seconds: "{{ states('input_number.high_temp_sec')|int }}" actions: - action: persistent_notification.create data: message: > {{ trigger.to_state.name }} too high for {{ trigger.for }}! The `for` template(s) will be evaluated when an entity changes as specified. Important Use of the `for` option will not survive Home Assistant restart or the reload of automations. During restart or reload, automations that were awaiting `for` the trigger to pass, are reset. If for your use case this is undesired, you could consider using the automation to set an [`input_datetime`](https://www.home-assistant.io/integrations/input_datetime) to the desired time and then use that [`input_datetime`](https://www.home-assistant.io/integrations/input_datetime) as an automation trigger to perform the desired actions at the set time. State trigger[](https://www.home-assistant.io/docs/automation/trigger/#state-trigger) -------------------------------------------------------------------------------------- In general, the state trigger fires when the state of any of given entities **changes**. The behavior is as follows: * If only the `entity_id` is given, the trigger fires for **all** state changes, even if only a state attribute changed. * If at least one of `from`, `to`, `not_from`, or `not_to` are given, the trigger fires on any matching state change, but not if only an attribute changed. * To trigger on all state changes, but not on changed attributes, set at least one of `from`, `to`, `not_from`, or `not_to` to `null`. * Use of the `for` option doesn’t survive a Home Assistant restart or the reload of automations. * During restart or reload, automations that were awaiting `for` the trigger to pass, are reset. * If for your use case this is undesired, you could consider using the automation to set an [`input_datetime`](https://www.home-assistant.io/integrations/input_datetime) to the desired time and then use that [`input_datetime`](https://www.home-assistant.io/integrations/input_datetime) as an automation trigger to perform the desired actions at the set time. Tip The values you see in your overview will often not be the same as the actual state of the entity. For instance, the overview may show `Connected` when the underlying entity is actually `on`. You should check the state of the entity by checking the states in the developer tool, under [**Developer Tools** > **States**](https://my.home-assistant.io/redirect/developer_states) . ### Examples[](https://www.home-assistant.io/docs/automation/trigger/#examples) This automation triggers if either Paulus or Anne-Therese are home for one minute. automation: triggers: - trigger: state entity_id: - device_tracker.paulus - device_tracker.anne_therese # Optional from: "not_home" # Optional to: "home" # If given, will trigger when the condition has been true for X time; you can also use days and milliseconds. for: hours: 0 minutes: 1 seconds: 0 It’s possible to give a list of `from` states or `to` states: automation: triggers: - trigger: state entity_id: vacuum.test from: - "cleaning" - "returning" to: "error" If you want to trigger on all state changes, but not on attribute changes, you can `to` to `null` (this would also work by setting `from`, `not_from`, or `not_to` to `null`): automation: triggers: - trigger: state entity_id: vacuum.test to: If you want to trigger on all state changes _except_ specific ones, use `not_from` or `not_to` The `not_from` and `not_to` options are the counter parts of `from` and `to`. They can be used to trigger on state changes that are **not** the specified state. automation: triggers: - trigger: state entity_id: vacuum.test not_from: - "unknown" - "unavailable" to: "on" You cannot use `from` and `not_from` at the same time. The same applies to `to` and `not_to`. ### Triggering on attribute changes[](https://www.home-assistant.io/docs/automation/trigger/#triggering-on-attribute-changes) When the `attribute` option is specified, the trigger only fires when the specified attribute **changes**. Changes to other attributes or state changes are ignored. For example, this trigger only fires when the boiler has been heating for 10 minutes: automation: triggers: - trigger: state entity_id: climate.living_room attribute: hvac_action to: "heating" for: "00:10:00" This trigger fires whenever the boiler’s `hvac_action` attribute changes: automation: triggers: - trigger: state entity_id: climate.living_room attribute: hvac_action ### Holding a state or attribute[](https://www.home-assistant.io/docs/automation/trigger/#holding-a-state-or-attribute) You can use `for` to have the state trigger only fire if the state holds for some time. This example fires, when the entity state changed to `"on"` and holds that state for 30 seconds: automation: triggers: - trigger: state entity_id: light.office # Must stay "on" for 30 seconds to: "on" for: "00:00:30" When holding a state, changes to attributes are ignored. Changes to attributes don’t cancel the hold time. You can also fire the trigger when the state value changed from a specific state, but hasn’t returned to that state value for the specified time. This can be useful, e.g., checking if a media player hasn’t turned “off” for the time specified, but doesn’t care about “playing” or “paused”. automation: triggers: - trigger: state entity_id: media_player.kitchen # Not "off" for 30 minutes from: "off" for: "00:30:00" Please note, that when using `from`, `to` and `for`, only the value of the `to` option is considered for the time specified. In this example, the trigger fires if the state value of the entity remains the same for `for` the time specified, regardless of the current state value. automation: triggers: - trigger: state entity_id: media_player.kitchen # The media player remained in its current state for 1 hour for: "01:00:00" You can also use templates in the `for` option. automation: triggers: - trigger: state entity_id: - device_tracker.paulus - device_tracker.anne_therese to: "home" for: minutes: "{{ states('input_number.lock_min')|int }}" seconds: "{{ states('input_number.lock_sec')|int }}" actions: - action: lock.lock target: entity_id: lock.my_place The `for` template(s) will be evaluated when an entity changes as specified. Tip Use quotes around your values for `from` and `to` to avoid the YAML parser from interpreting values as booleans. Sun trigger[](https://www.home-assistant.io/docs/automation/trigger/#sun-trigger) ---------------------------------------------------------------------------------- ### Sunset / Sunrise trigger[](https://www.home-assistant.io/docs/automation/trigger/#sunset--sunrise-trigger) Fires when the sun is setting or rising, i.e., when the sun elevation reaches 0°. An optional time offset can be given to have it fire a set time before or after the sun event (e.g., 45 minutes before sunset). A negative value makes it fire before sunrise or sunset, a positive value afterwards. The offset needs to be specified in number of seconds, or in a hh:mm:ss format. Tip Since the duration of twilight is different throughout the year, it is recommended to use [sun elevation triggers](https://www.home-assistant.io/docs/automation/trigger/#sun-elevation-trigger) instead of `sunset` or `sunrise` with a time offset to trigger automations during dusk or dawn. automation: triggers: - trigger: sun # Possible values: sunset, sunrise event: sunset # Optional time offset. This example will trigger 45 minutes before sunset. offset: "-00:45:00" ### Sun elevation trigger[](https://www.home-assistant.io/docs/automation/trigger/#sun-elevation-trigger) Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the “sunset” event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most automations intended to run during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example: automation: - alias: "Exterior Lighting on when dark outside" triggers: - trigger: numeric_state entity_id: sun.sun attribute: elevation # Can be a positive or negative number below: -4.0 actions: - action: switch.turn_on target: entity_id: switch.exterior_lighting If you want to get more precise, you can use this [solar calculator](https://gml.noaa.gov/grad/solcalc/) , which will help you estimate what the solar elevation will be at any specific time. Then from this, you can select from the defined twilight numbers. Although the actual amount of light depends on weather, topography and land cover, they are defined as: * Civil twilight: 0° > Solar angle > -6° This is what is meant by twilight for the average person: Under clear weather conditions, civil twilight approximates the limit at which solar illumination suffices for the human eye to clearly distinguish terrestrial objects. Enough illumination renders artificial sources unnecessary for most outdoor activities. * Nautical twilight: -6° > Solar angle > -12° * Astronomical twilight: -12° > Solar angle > -18° A very thorough explanation of this is available in the Wikipedia article about the [Twilight](https://en.wikipedia.org/wiki/Twilight) . Tag trigger[](https://www.home-assistant.io/docs/automation/trigger/#tag-trigger) ---------------------------------------------------------------------------------- Fires when a [tag](https://www.home-assistant.io/integrations/tag) is scanned. For example, a NFC tag is scanned using the Home Assistant Companion mobile application. automation: triggers: - trigger: tag tag_id: A7-6B-90-5F Additionally, you can also only trigger if a card is scanned by a specific device/scanner by setting the `device_id`: automation: triggers: - trigger: tag tag_id: A7-6B-90-5F device_id: 0e19cd3cf2b311ea88f469a7512c307d Or trigger on multiple possible devices for multiple tags: automation: triggers: - trigger: tag tag_id: - "A7-6B-90-5F" - "A7-6B-15-AC" device_id: - 0e19cd3cf2b311ea88f469a7512c307d - d0609cb25f4a13922bb27d8f86e4c821 Template trigger[](https://www.home-assistant.io/docs/automation/trigger/#template-trigger) -------------------------------------------------------------------------------------------- Template triggers work by evaluating a [template](https://www.home-assistant.io/docs/configuration/templating/) when any of the recognized entities change state. The trigger will fire if the state change caused the template to render ‘true’ (a non-zero number or any of the strings `true`, `yes`, `on`, `enable`) when it was previously ‘false’ (anything else). This is achieved by having the template result in a true boolean expression (for example `{{ is_state('device_tracker.paulus', 'home') }}`) or by having the template render `true` (example below). With template triggers you can also evaluate attribute changes by using is\_state\_attr (like `{{ is_state_attr('climate.living_room', 'away_mode', 'off') }}`) automation: triggers: - trigger: template value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}" # If given, will trigger when template remains true for X time. for: "00:01:00" You can also use templates in the `for` option. automation: triggers: - trigger: template value_template: "{{ is_state('device_tracker.paulus', 'home') }}" for: minutes: "{{ states('input_number.minutes')|int(0) }}" The `for` template(s) will be evaluated when the `value_template` becomes ‘true’. Templates that do not contain an entity will be rendered once per minute. Important Use of the `for` option will not survive Home Assistant restart or the reload of automations. During restart or reload, automations that were awaiting `for` the trigger to pass, are reset. If for your use case this is undesired, you could consider using the automation to set an [`input_datetime`](https://www.home-assistant.io/integrations/input_datetime) to the desired time and then use that [`input_datetime`](https://www.home-assistant.io/integrations/input_datetime) as an automation trigger to perform the desired actions at the set time. Time trigger[](https://www.home-assistant.io/docs/automation/trigger/#time-trigger) ------------------------------------------------------------------------------------ The time trigger is configured to fire once a day at a specific time, or at a specific time on a specific date. There are three allowed formats: ### Time string[](https://www.home-assistant.io/docs/automation/trigger/#time-string) A string that represents a time to fire on each day. Can be specified as `HH:MM` or `HH:MM:SS`. If the seconds are not specified, `:00` will be used. automation: - triggers: - trigger: time # 24-hour time format. This trigger will fire at 3:32 PM at: "15:32:00" ### Input datetime[](https://www.home-assistant.io/docs/automation/trigger/#input-datetime) The entity ID of an [input datetime](https://www.home-assistant.io/integrations/input_datetime/) . | has\_date | has\_time | Description | | --- | --- | --- | | `true` | `true` | Will fire at specified date & time. | | `true` | `false` | Will fire at midnight on specified date. | | `false` | `true` | Will fire once a day at specified time. | automation: - triggers: - trigger: state entity_id: binary_sensor.motion to: "on" actions: - action: climate.turn_on target: entity_id: climate.office - action: input_datetime.set_datetime target: entity_id: input_datetime.turn_off_ac data: datetime: > {{ (now().timestamp() + 2*60*60) | timestamp_custom('%Y-%m-%d %H:%M:%S') }} - triggers: - trigger: time at: input_datetime.turn_off_ac actions: - action: climate.turn_off target: entity_id: climate.office ### Sensors of datetime device class[](https://www.home-assistant.io/docs/automation/trigger/#sensors-of-datetime-device-class) The Entity ID of a [sensor](https://www.home-assistant.io/integrations/sensor/) with the “timestamp” device class. automation: - triggers: - trigger: time at: sensor.phone_next_alarm actions: - action: light.turn_on target: entity_id: light.bedroom ### Sensors of datetime device class with offsets[](https://www.home-assistant.io/docs/automation/trigger/#sensors-of-datetime-device-class-with-offsets) When the time is provided using a sensor of the timestamp device class, an offset can be provided. This offset will be added to (or subtracted from when negative) the sensor value. For example, this trigger fires 5 minutes before the phone alarm goes off. automation: - triggers: - trigger: time at: entity_id: sensor.phone_next_alarm offset: -00:05:00 actions: - action: light.turn_on target: entity_id: light.bedroom Important When using a positive offset the trigger might never fire. This is due to the sensor changing before the offset is reached. For example, when using a phone alarm as a trigger, the sensor value will change to the new alarm time when the alarm goes off, which means this trigger will change to the new time as well. ### Multiple times[](https://www.home-assistant.io/docs/automation/trigger/#multiple-times) Multiple times can be provided in a list. All formats can be intermixed. automation: triggers: - trigger: time at: - input_datetime.leave_for_work - "18:30:00" - entity_id: sensor.bus_arrival offset: "-00:10:00" ### Limited templates[](https://www.home-assistant.io/docs/automation/trigger/#limited-templates) It’s also possible to use [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) for times. blueprint: input: alarm: name: Alarm selector: text: hour: name: Hour selector: number: min: 0 max: 24 trigger_variables: my_alarm: !input alarm my_hour: !input hour trigger: - platform: time at: - "sensor.{{ my_alarm | slugify }}_time" - "{{ my_hour }}:30:00" ### Weekday filtering[](https://www.home-assistant.io/docs/automation/trigger/#weekday-filtering) Time triggers can be filtered to fire only on specific days of the week using the `weekday` option. This allows you to create automations that only run on certain days, such as weekdays or weekends. The `weekday` option accepts: * A single weekday as a string: `"mon"`, `"tue"`, `"wed"`, `"thu"`, `"fri"`, `"sat"`, `"sun"` * A list of weekdays using the expanded format #### Single weekday[](https://www.home-assistant.io/docs/automation/trigger/#single-weekday) This example will turn on the lights only on Mondays at 8:00 AM: automation: - triggers: - trigger: time at: "08:00:00" weekday: "mon" actions: - action: light.turn_on target: entity_id: light.bedroom #### Multiple weekdays[](https://www.home-assistant.io/docs/automation/trigger/#multiple-weekdays) This example will run a morning routine only on weekdays (Monday through Friday) at 6:30 AM: automation: - triggers: - trigger: time at: "06:30:00" weekday: - "mon" - "tue" - "wed" - "thu" - "fri" actions: - action: script.morning_routine #### Weekend example[](https://www.home-assistant.io/docs/automation/trigger/#weekend-example) This example demonstrates a different wake-up time for weekends: automation: - alias: "Weekday alarm" triggers: - trigger: time at: "06:30:00" weekday: - "mon" - "tue" - "wed" - "thu" - "fri" actions: - action: script.weekday_morning - alias: "Weekend alarm" triggers: - trigger: time at: "08:00:00" weekday: - "sat" - "sun" actions: - action: script.weekend_morning #### Combined with input datetime[](https://www.home-assistant.io/docs/automation/trigger/#combined-with-input-datetime) The `weekday` option works with all time formats, including input datetime entities: automation: - triggers: - trigger: time at: input_datetime.work_start_time weekday: - "mon" - "tue" - "wed" - "thu" - "fri" actions: - action: notify.mobile_app data: title: "Work Day!" message: "Time to start working" Time pattern trigger[](https://www.home-assistant.io/docs/automation/trigger/#time-pattern-trigger) ---------------------------------------------------------------------------------------------------- With the time pattern trigger, you can match if the hour, minute or second of the current time matches a specific value. You can prefix the value with a `/` to match whenever the value is divisible by that number. You can specify `*` to match any value. automation: triggers: - trigger: time_pattern # Matches every hour at 5 minutes past whole minutes: 5 automation 2: triggers: - trigger: time_pattern # Trigger once per minute during the hour of 3 hours: "3" minutes: "*" automation 3: triggers: - trigger: time_pattern # You can also match on interval. This will match every 5 minutes minutes: "/5" Note Do not prefix numbers with a zero - using `'01'` instead of `'1'` for example will result in errors. Persistent notification trigger[](https://www.home-assistant.io/docs/automation/trigger/#persistent-notification-trigger) -------------------------------------------------------------------------------------------------------------------------- Persistent notification triggers are fired when a `persistent_notification` is `added` or `removed` that matches the configuration options. automation: triggers: - trigger: persistent_notification update_type: - added - removed notification_id: invalid_config See the [Persistent Notification](https://www.home-assistant.io/integrations/persistent_notification/) integration for more details on event triggers and the additional event data available for use by an automation. Webhook trigger[](https://www.home-assistant.io/docs/automation/trigger/#webhook-trigger) ------------------------------------------------------------------------------------------ Webhook trigger fires when a web request is made to the webhook endpoint: `/api/webhook/`. The webhook endpoint is created automatically when you set it as the `webhook_id` in an automation trigger. The `webhook_id` can either be a static value or computed using [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . Note The `webhook_id` template is only evaluated when setting up the trigger, they will not be re-evaluated for incoming webhook triggers. automation: trigger_variables: webhook_id_variable: "template_webhook_id" triggers: - trigger: webhook webhook_id: "some_hook_id" allowed_methods: - POST - PUT local_only: true - trigger: webhook webhook_id: "" allowed_methods: - POST You can run this automation by sending an HTTP POST request to `http://your-home-assistant:8123/api/webhook/some_hook_id`. Here is an example using the **curl** command line program, with an example form data payload: curl -X POST -d 'key=value&key2=value2' https://your-home-assistant:8123/api/webhook/some_hook_id Webhooks support HTTP POST, PUT, HEAD, and GET requests; PUT requests are recommended. HTTP GET and HEAD requests are not enabled by default but can be enabled by adding them to the `allowed_methods` option. The request methods can also be configured in the UI by clicking the settings gear menu button beside the Webhook ID. By default, webhook triggers can only be accessed from devices on the same network as Home Assistant or via [Nabu Casa Cloud webhooks](https://www.nabucasa.com/config/webhooks/) . The `local_only` option should be set to `false` to allow webhooks to be triggered directly via the internet. This option can also be configured in the UI by clicking the settings gear menu button beside the Webhook ID. Remember to use an HTTPS URL if you’ve secured your Home Assistant installation with SSL/TLS. Note that a given webhook can only be used in one automation at a time. That is, only one automation trigger can use a specific webhook ID. ### Webhook data[](https://www.home-assistant.io/docs/automation/trigger/#webhook-data) Payloads may either be encoded as form data or JSON. Depending on that, its data will be available in an automation template as either `trigger.data` or `trigger.json`. URL query parameters are also available in the template as `trigger.query`. Note that to use JSON encoded payloads, the `Content-Type` header must be set to `application/json`, e.g.: curl -X POST -H "Content-Type: application/json" -d '{ "key": "value" }' https://your-home-assistant:8123/api/webhook/some_hook_id ### Webhook security[](https://www.home-assistant.io/docs/automation/trigger/#webhook-security) Webhook endpoints don’t require authentication, other than knowing a valid webhook ID. Security best practices for webhooks include: * Do not use webhooks to trigger automations that are destructive, or that can create safety issues. For example, do not use a webhook to unlock a lock, or open a garage door. * Treat a webhook ID like a password: use a unique, non-guessable value, and keep it secret. * Do not copy-and-paste webhook IDs from public sources, including blueprints. Always create your own. * Keep the `local_only` option enabled for webhooks if access from the internet is not required. Zone trigger[](https://www.home-assistant.io/docs/automation/trigger/#zone-trigger) ------------------------------------------------------------------------------------ Zone trigger fires when an entity is entering or leaving the zone. The entity can be either a person, or a device\_tracker. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. This includes [GPS Logger](https://www.home-assistant.io/integrations/gpslogger/) , the [OwnTracks platform](https://www.home-assistant.io/integrations/owntracks/) and the [iCloud platform](https://www.home-assistant.io/integrations/icloud/) . automation: triggers: - trigger: zone entity_id: person.paulus zone: zone.home # Event is either enter or leave event: enter # or "leave" Geolocation trigger[](https://www.home-assistant.io/docs/automation/trigger/#geolocation-trigger) -------------------------------------------------------------------------------------------------- Geolocation trigger fires when an entity is appearing in or disappearing from a zone. Entities that are created by a [Geolocation](https://www.home-assistant.io/integrations/geo_location/) platform support reporting GPS coordinates. Because entities are generated and removed by these platforms automatically, the entity ID normally cannot be predicted. Instead, this trigger requires the definition of a `source`, which is directly linked to one of the Geolocation platforms. Tip This isn’t for use with `device_tracker` entities. For those look above at the `zone` trigger. automation: triggers: - trigger: geo_location source: nsw_rural_fire_service_feed zone: zone.bushfire_alert_zone # Event is either enter or leave event: enter # or "leave" Device triggers[](https://www.home-assistant.io/docs/automation/trigger/#device-triggers) ------------------------------------------------------------------------------------------ Device triggers encompass a set of events that are defined by an integration. This includes, for example, state changes of sensors as well as button events from remotes. [MQTT device triggers](https://www.home-assistant.io/integrations/device_trigger.mqtt/) are set up through autodiscovery. In contrast to state triggers, device triggers are tied to a device and not necessarily an entity. To use a device trigger, set up an automation through the browser frontend. If you would like to use a device trigger for an automation that is not managed through the browser frontend, you can copy the YAML from the trigger widget in the frontend and paste it into your automation’s trigger list. Calendar trigger[](https://www.home-assistant.io/docs/automation/trigger/#calendar-trigger) -------------------------------------------------------------------------------------------- Calendar trigger fires when a [Calendar](https://www.home-assistant.io/integrations/calendar/) event starts or ends, allowing for much more flexible automations than using the Calendar entity state which only supports a single event start at a time. An optional time offset can be given to have it fire a set time before or after the calendar event (e.g., 5 minutes before event start). automation: triggers: - trigger: calendar # Possible values: start, end event: start # The calendar entity_id entity_id: calendar.light_schedule # Optional time offset offset: "-00:05:00" See the [Calendar](https://www.home-assistant.io/integrations/calendar/) integration for more details on event triggers and the additional event data available for use by an automation. Sentence trigger[](https://www.home-assistant.io/docs/automation/trigger/#sentence-trigger) -------------------------------------------------------------------------------------------- A sentence trigger fires when [Assist](https://www.home-assistant.io/voice_control/) matches a sentence from a voice assistant using the default [conversation agent](https://www.home-assistant.io/integrations/conversation/) . Sentence triggers work with Home Assistant Assist. They will not work with external conversation agents such as OpenAI or Google Generative AI unless “Prefer handling commands locally” is enabled in the conversation agent settings. Sentences are allowed to use some basic [template syntax](https://developers.home-assistant.io/docs/voice/intent-recognition/template-sentence-syntax/#sentence-templates-syntax) like optional and alternative words. For example, `[it's ]party time` will match both “party time” and “it’s party time”. automation: triggers: - trigger: conversation command: - "[it's ]party time" - "happy (new year|birthday)" The sentences matched by this trigger will be: * party time * it’s party time * happy new year * happy birthday Punctuation and casing are ignored, so “It’s PARTY TIME!!!” will also match. ### Related topic[](https://www.home-assistant.io/docs/automation/trigger/#related-topic) * [Adding a custom sentence to trigger an automation](https://www.home-assistant.io/voice_control/custom_sentences/#adding-a-custom-sentence-to-trigger-an-automation) ### Sentence wildcards[](https://www.home-assistant.io/docs/automation/trigger/#sentence-wildcards) Adding one or more `{lists}` to your trigger sentences will capture any text at that point in the sentence. A `slots` object will be [available in the trigger data](https://www.home-assistant.io/docs/automation/templating#sentence) . This allows you to match sentences with variable parts, such as album/artist names or a description of a picture. For example, the sentence `play {album} by {artist}` will match “play the white album by the beatles” and have the following variables available in the action templates: * `{{ trigger.slots.album }}` - “the white album” * `{{ trigger.slots.artist }}` - “the beatles” Wildcards will match as much text as possible, which may lead to surprises: “play day by day by taken by trees” will match `album` as “day” and `artist` as “day by taken by trees”. Including extra words in your template can help: `play {album} by artist {artist}` can now correctly match “play day by day by artist taken by trees”. Multiple triggers[](https://www.home-assistant.io/docs/automation/trigger/#multiple-triggers) ---------------------------------------------------------------------------------------------- It is possible to specify multiple triggers for the same rule. To do so just prefix the first line of each trigger with a dash (-) and indent the next lines accordingly. Whenever one of the triggers fires, processing of your automation rule begins. automation: triggers: # first trigger - trigger: time_pattern minutes: 5 # our second trigger is the sunset - trigger: sun event: sunset Multiple entity IDs for the same trigger[](https://www.home-assistant.io/docs/automation/trigger/#multiple-entity-ids-for-the-same-trigger) -------------------------------------------------------------------------------------------------------------------------------------------- It is possible to specify multiple entities for the same trigger. To do so add multiple entities using a nested list. The trigger will fire and start, processing your automation each time the trigger is true for any entity listed. automation: triggers: - trigger: state entity_id: - sensor.one - sensor.two - sensor.three Disabling a trigger[](https://www.home-assistant.io/docs/automation/trigger/#disabling-a-trigger) -------------------------------------------------------------------------------------------------- Every individual trigger in an automation can be disabled, without removing it. To do so, add `enabled: false` to the trigger. For example: # Example script with a disabled trigger automation: triggers: # This trigger will not trigger, as it is disabled. # This automation does not run when the sun is set. - enabled: false trigger: sun event: sunset # This trigger will fire, as it is not disabled. - trigger: time at: "15:32:00" Triggers can also be disabled based on limited templates or blueprint inputs. These are only evaluated once when the automation is loaded. blueprint: input: input_boolean: name: Boolean selector: boolean: input_number: name: Number selector: number: min: 0 max: 100 trigger_variables: _enable_number: !input input_number triggers: - trigger: sun event_type: sunrise enabled: !input input_boolean - trigger: sun event_type: sunset enabled: "{{ _enable_number < 50 }}" Merging lists of triggers[](https://www.home-assistant.io/docs/automation/trigger/#merging-lists-of-triggers) -------------------------------------------------------------------------------------------------------------- Caution This feature requires Home Assistant version 2024.10 or later. If using this in a blueprint, set the `min_version` for the blueprint to at least this version. See the [blueprint schema documentation](https://www.home-assistant.io/docs/blueprint/schema/#min_version) for more details. In some advanced cases (like for blueprints with trigger selectors), it may be necessary to insert a second list of triggers into the main trigger list. This can be done by adding a dictionary in the main trigger list with the sole key `triggers`, and the value for that key contains a second list of triggers. These will then be flattened into a single list of triggers. For example: blueprint: name: Nested Trigger Blueprint domain: automation input: usertrigger: selector: trigger: triggers: - trigger: event event_type: manual_event - triggers: !input usertrigger This blueprint automation can then be triggered either by the fixed manual\_event trigger, or additionally by any triggers selected in the trigger selector. This is also applicable for `wait_for_trigger` action. Related topics[](https://www.home-assistant.io/docs/automation/trigger/#related-topics) ---------------------------------------------------------------------------------------- * [Adding a custom sentence to trigger an automation](https://www.home-assistant.io/voice_control/custom_sentences/#adding-a-custom-sentence-to-trigger-an-automation) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/automation/trigger/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/automation/trigger.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fautomation%2Ftrigger%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fautomation%2Ftrigger%2F%22&in=body "View given feedback for this page") --- # Securing - Home Assistant One major advantage of Home Assistant is that it is not dependent on cloud services. Even if you are only using Home Assistant on a local network, you should take steps to secure your instance. Checklist[](https://www.home-assistant.io/docs/configuration/securing/#checklist) ---------------------------------------------------------------------------------- Here’s the summary of what you _must_ do to secure your Home Assistant system: * Centralize sensitive data in [secrets](https://www.home-assistant.io/docs/configuration/secrets/) (but do remember to back them up). * **Note**: Storing secrets in `secrets.yaml` does not encrypt them. * Regularly keep the system up to date. Remote access[](https://www.home-assistant.io/docs/configuration/securing/#remote-access) ------------------------------------------------------------------------------------------ If you want secure remote access, the easiest option is to use [Home Assistant Cloud](https://www.home-assistant.io/cloud/) by which you also support the [Open Home Foundation](https://www.openhomefoundation.org/) , which develops Home Assistant, ESPHome and much more. Another option is to use TLS/SSL via the add-on [Duck DNS](https://www.home-assistant.io/integrations/duckdns/) integrating Let’s Encrypt. To expose your instance to the internet, use a [VPN](https://pivpn.io/) , or an [SSH tunnel](https://www.home-assistant.io/blog/2017/11/02/secure-shell-tunnel/) . Make sure to expose the used port in your router. ### Extras for manual installations[](https://www.home-assistant.io/docs/configuration/securing/#extras-for-manual-installations) Besides the above, we advise that you consider the following to improve security: * For systems that use SSH, set `PermitRootLogin no` in your sshd configuration (usually `/etc/ssh/sshd_config`) and use SSH keys for authentication instead of passwords. This is particularly important if you enable remote access to your SSH services. * Lock down the host following good practice guidance, for example: * [Securing Debian Manual](https://www.debian.org/doc/manuals/securing-debian-manual/index.en.html) (this also applies to Raspberry Pi OS) * [Red Hat Enterprise Linux 7 Security Guide](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/index) , [CIS Red Hat Enterprise Linux 7 Benchmark](https://www.cisecurity.org/cis-benchmarks/) Related topics[](https://www.home-assistant.io/docs/configuration/securing/#related-topics) -------------------------------------------------------------------------------------------- * [Configuration.yaml](https://www.home-assistant.io/docs/configuration/) * [Secrets.yaml file](https://www.home-assistant.io/docs/configuration/secrets/) * [Home assistant cloud](https://www.home-assistant.io/cloud/) Related links[](https://www.home-assistant.io/docs/configuration/securing/#related-links) ------------------------------------------------------------------------------------------ * [Nabu Casa](https://nabucasa.com/config/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/securing/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/securing.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fsecuring%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fsecuring%2F%22&in=body "View given feedback for this page") --- # Setup basic information - Home Assistant As part of the default onboarding process, Home Assistant can detect your location from IP address geolocation. Home Assistant will automatically select a unit system and time zone based on this location. If you didn’t adjust this directly during onboarding, you can do it later. ![Screenshot showing General settings page](https://www.home-assistant.io/images/docs/configuration/general-settings.png) Screenshot showing the General settings page. The general settings described here are managed by the [Home Assistant Core integration](https://www.home-assistant.io/integrations/homeassistant/) . If you are interested in the actions offered by this integration, check out the integration documentation. Editing the general settings[](https://www.home-assistant.io/docs/configuration/basic/#editing-the-general-settings) --------------------------------------------------------------------------------------------------------------------- To change the general settings that were defined during onboarding, follow these steps: 1. Go to [**Settings** > **System** > **General**](https://my.home-assistant.io/redirect/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](https://www.home-assistant.io/images/docs/configuration/change_location_radius.webp) * 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 [**Settings** > **System** > **Network**](https://my.home-assistant.io/redirect/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 [**User profile**](https://my.home-assistant.io/redirect/profile) , and enable **Advanced mode**. 4. **Troubleshooting**: If any of the settings are grayed out and can’t be edited, this is because they are defined in the `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file. * If you prefer editing the settings in the UI, you have to delete these entries from the `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file. * For more information about the general settings in YAML, refer to the [Home Assistant Core integration documentation](https://www.home-assistant.io/integrations/homeassistant/) . ![Setting fields are grayed out because the configuration settings stored in configuration.yaml file](https://www.home-assistant.io/images/docs/configuration/general-settings-stored-in-config-yaml.png) 5. To apply the changes, follow the steps on [reloading the configuration](https://www.home-assistant.io/docs/configuration/#reloading-configuration-changes) . Changing a person’s display name[](https://www.home-assistant.io/docs/configuration/basic/#changing-a-persons-display-name) ---------------------------------------------------------------------------------------------------------------------------- The display name is the name that is shown in Home Assistant. It can differ from the username, which is the name used to log in. ### Prerequisites[](https://www.home-assistant.io/docs/configuration/basic/#prerequisites) * You need administrator rights to change a display name. To change a display name[](https://www.home-assistant.io/docs/configuration/basic/#to-change-a-display-name) ------------------------------------------------------------------------------------------------------------- 1. To edit the display name of a person using Home Assistant, go to [**Settings** > **People**](https://my.home-assistant.io/redirect/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 username[](https://www.home-assistant.io/docs/configuration/basic/#changing-a-username) --------------------------------------------------------------------------------------------------- The username is the name that is used to log in. It can differ from the display name. ### Prerequisites[](https://www.home-assistant.io/docs/configuration/basic/#prerequisites-1) * You need owner rights to change a username. ### To change a username[](https://www.home-assistant.io/docs/configuration/basic/#to-change-a-username) 1. To edit the username of a person using Home Assistant, go to [**Settings** > **People**](https://my.home-assistant.io/redirect/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. * It must be lowercase and contain no spaces. * The log in is case-sensitive. Changing authentication settings[](https://www.home-assistant.io/docs/configuration/basic/#changing-authentication-settings) ----------------------------------------------------------------------------------------------------------------------------- To learn how to edit authentication settings such as password or multi-factor authentication, refer to the following topics: * [Authentication](https://www.home-assistant.io/docs/authentication/) * [multi-factor authentication](https://www.home-assistant.io/docs/authentication/multi-factor-auth/) * [Help, I’m locked out](https://www.home-assistant.io/docs/locked_out/) Related topics[](https://www.home-assistant.io/docs/configuration/basic/#related-topics) ----------------------------------------------------------------------------------------- * [Home Assistant Core Integration](https://www.home-assistant.io/integrations/homeassistant/) * [Configuration.yaml](https://www.home-assistant.io/docs/configuration/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/basic/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/basic.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fbasic%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fbasic%2F%22&in=body "View given feedback for this page") --- # Performing actions - Home Assistant Various integrations allow performing actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) when a certain event occurs. The most common one is performing an action when an automation triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) happens. But an action can also be called from a scriptScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) , a dashboard, or via voice command devices such as Amazon Echo. The configuration options to perform action 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. Tip Use the “Actions” tab under **Developer tools** to discover available actions. ### The basics[](https://www.home-assistant.io/docs/scripts/perform-actions/#the-basics) Perform the action `homeassistant.turn_on` on the entityAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) `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. action: homeassistant.turn_on target: entity_id: group.living_room ### Targeting areas and devices[](https://www.home-assistant.io/docs/scripts/perform-actions/#targeting-areas-and-devices) Instead of targeting an entity, you can also target an areaAn area in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of devices and entities that are meant to match areas (or rooms) in the physical world: your home. For example, the `living room` area groups devices and entities in your living room. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/areas/) or deviceA device is a model representing a physical or logical unit that contains entities.. Or a combination of these. 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 action to turn on the lights in the living room area, 2 additional light devices and 2 additional light entities: action: light.turn_on target: area_id: living_room device_id: - ff22a1889a6149c5ab6327a8236ae704 - 52c050ca1a744e238ad94d170651f96b entity_id: - light.hallway - light.landing ### Passing data to the action[](https://www.home-assistant.io/docs/scripts/perform-actions/#passing-data-to-the-action) You can also specify other parameters beside the entity to target. For example, the `light.turn_on` action allows specifying the brightness. action: light.turn_on target: entity_id: group.living_room data: brightness: 120 rgb_color: [255, 0, 0] 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](https://www.home-assistant.io/integrations/light/#action-lightturn_on) . ### Use templates to decide which action to perform[](https://www.home-assistant.io/docs/scripts/perform-actions/#use-templates-to-decide-which-action-to-perform) You can use [templating](https://www.home-assistant.io/docs/configuration/templating/) support to dynamically choose which action to perform. For example, you can perform a certain action based on if a light is on. action: > {% if states('sensor.temperature') | float > 15 %} switch.turn_on {% else %} switch.turn_off {% endif %} entity_id: switch.ac ### Using the Actions developer tool[](https://www.home-assistant.io/docs/scripts/perform-actions/#using-the-actions-developer-tool) 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](https://www.home-assistant.io/integrations/group/) for more info) To turn a group on or off, pass the following info: * Domain: `homeassistant` * Action: `turn_on` * Action data: `{ "entity_id": "group.kitchen" }` ### Use templates to determine the attributes[](https://www.home-assistant.io/docs/scripts/perform-actions/#use-templates-to-determine-the-attributes) Templates can also be used for the data that you pass to the action. action: thermostat.set_temperature target: entity_id: > {% if is_state('device_tracker.paulus', 'home') %} thermostat.upstairs {% else %} thermostat.downstairs {% endif %} data: temperature: "{{ 22 - distance(states.device_tracker.paulus) }}" You can use a template returning a native dictionary as well, which is useful if the attributes to be set depend on the situation. action: climate.set_temperature data: > {% if states('sensor.temperature_living') < 19 %} {"hvac_mode": "heat", "temperature": 19 } {% else %} {"hvac_mode": "auto" } {% endif %} ### Use templates to handle response data[](https://www.home-assistant.io/docs/scripts/perform-actions/#use-templates-to-handle-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 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 action can specify a `response_variable`. This is the [variable](https://www.home-assistant.io/docs/scripts/#variables) 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`. action: calendar.get_events target: entity_id: calendar.school data: duration: hours: 24 response_variable: agenda 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. Important Which data fields can be used in an action depends on the type of notification that is used. action: notify.gmail_com data: target: "[email protected]" title: "Daily agenda for {{ now().date() }}" message: >- Your agenda for today:

{% for event in agenda['calendar.school'].events %} {{ event.start}}: {{ event.summary }}
{% endfor %}

### homeassistant actions[](https://www.home-assistant.io/docs/scripts/perform-actions/#homeassistant-actions) 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](https://www.home-assistant.io/integrations/google_travel_time/) sensor, a [template sensor](https://www.home-assistant.io/integrations/template/) , or a [light](https://www.home-assistant.io/integrations/light/) Complete action details and examples can be found on the [Home Assistant integration](https://www.home-assistant.io/integrations/homeassistant#actions) page. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/scripts/perform-actions/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/scripts/perform-actions.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fscripts%2Fperform-actions%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fscripts%2Fperform-actions%2F%22&in=body "View given feedback for this page") --- # Working with tables - Home Assistant When working with tables, you can select multiple items to apply an action. If you have [grouped](https://www.home-assistant.io/docs/organizing/) items by assigning them to floors, areas, labels, or directories, you can also filter your data accordingly. Selecting multiple items in a table[](https://www.home-assistant.io/docs/organizing/tables/#selecting-multiple-items-in-a-table) --------------------------------------------------------------------------------------------------------------------------------- 1. In your table, select the button. ![Screenshots point out the enable selection mode button in the toolbar of the tables in Home Assistant](https://www.home-assistant.io/images/blog/2024-04/enable-selection-mode.png) 2. In the list, select the items of interest. ![Selecting multiple elements in a list](https://www.home-assistant.io/images/organizing/multiselect_01.png) 3. You can now apply changes to all selected elements, such as [applying labels](https://www.home-assistant.io/docs/organzing/labels/) or [enabling or disabling entities and automations](https://www.home-assistant.io/common-tasks/general/) . Filtering items in a table[](https://www.home-assistant.io/docs/organizing/tables/#filtering-items-in-a-table) --------------------------------------------------------------------------------------------------------------- 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](https://www.home-assistant.io/images/organizing/filters_01.png) 2. In the filters panel, select your filter criteria. * You can filter for [floors](https://www.home-assistant.io/docs/organizing/floors/) , [areas](https://www.home-assistant.io/docs/organizing/areas/) , [labels](https://www.home-assistant.io/docs/organizing/labels/) , and [categories](https://www.home-assistant.io/docs/organizing/categories/) if you have previously defined them. * The list of available criteria depends on the type of table. ![Screenshots showing the filter panel that tables can have, allowing you to easily find what you are looking for](https://www.home-assistant.io/images/organizing/filter-panel.png) Grouping and sorting items in a table[](https://www.home-assistant.io/docs/organizing/tables/#grouping-and-sorting-items-in-a-table) ------------------------------------------------------------------------------------------------------------------------------------- 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. * The example shows a list of devices, grouped by manufacturer. * In contrast, the entities table does not allow grouping by manufacturer, but by entity domains. ![Select the Group by button](https://www.home-assistant.io/images/organizing/table_group_01.png) 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](https://www.home-assistant.io/images/organizing/table_group_collapse.png) Customizing columns[](https://www.home-assistant.io/docs/organizing/tables/#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](https://www.home-assistant.io/images/organizing/customize_columns.webp) Related topics[](https://www.home-assistant.io/docs/organizing/tables/#related-topics) --------------------------------------------------------------------------------------- * [Floors](https://www.home-assistant.io/docs/organizing/floors/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Categories](https://www.home-assistant.io/docs/organizing/categories/) * [Grouping your assets](https://www.home-assistant.io/docs/organizing/) * [Enabling or disabling entities and automations](https://www.home-assistant.io/common-tasks/general/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/organizing/tables/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/organizing/tables.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Forganizing%2Ftables%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Forganizing%2Ftables%2F%22&in=body "View given feedback for this page") --- # YAML syntax - Home Assistant Home Assistant uses the [YAML](https://yaml.org/) syntax for configuration. While most integrations can be configured through the UI, some integrations require you to edit your [`configuration.yaml`](https://www.home-assistant.io/docs/configuration/) file to specify its settings. YAML Style Guide[](https://www.home-assistant.io/docs/configuration/yaml/#yaml-style-guide) -------------------------------------------------------------------------------------------- This page gives a high-level introduction to the YAML syntax used in Home Assistant. For a more detailed description and more examples, refer to the [YAML Style Guide for Home Assistant developers](https://developers.home-assistant.io/docs/documenting/yaml-style-guide/) . A first example[](https://www.home-assistant.io/docs/configuration/yaml/#a-first-example) ------------------------------------------------------------------------------------------ The following YAML example entry assumes that you would like to set up the [notify integration](https://www.home-assistant.io/integrations/notify) with the [pushbullet platform](https://www.home-assistant.io/integrations/pushbullet) . notify: platform: pushbullet api_key: "o.1234abcd" name: pushbullet * An **integration** provides the core logic for some functionality (like `notify` provides sending notifications). * A **platform** makes the connection to a specific software or hardware platform (like `pushbullet` works with the service from pushbullet.com). The basics of YAML syntax are block collections and mappings containing key-value pairs. Each item in a collection starts with a `-` while mappings have the format `key: value`. This is somewhat similar to a Hash table or more specifically a dictionary in Python. These can be nested as well. **Beware that if you specify duplicate keys, the last value for a key is used**. Indentation in YAML[](https://www.home-assistant.io/docs/configuration/yaml/#indentation-in-yaml) -------------------------------------------------------------------------------------------------- In YAML, indentation is important for specifying relationships. Indented lines are nested inside lines that are one level higher. In the above example, `platform: pushbullet` is a property of (nested inside) the `notify` integration. Getting the right indentation can be tricky if you’re not using an editor with a fixed-width font. Tabs are not allowed to be used for indentation. The convention is to use 2 spaces for each level of indentation. Comments[](https://www.home-assistant.io/docs/configuration/yaml/#comments) ---------------------------------------------------------------------------- Strings of text following a `#` are comments. They are ignored by the system. Comments explain in plain language what a particular code block is supposed to do. For future-you or someone else looking at the file. ### Example with comment and nesting[](https://www.home-assistant.io/docs/configuration/yaml/#example-with-comment-and-nesting) The next example shows an [input\_select](https://www.home-assistant.io/integrations/input_select) integration that uses a block collection for the values of options. The other properties (like `name:`) are specified using mappings. Note that the second line just has `threat:` with no value on the same line. Here, `threat` is the name of the input\_select. The values for it are everything nested below it. input_select: threat: name: "Threat level" # A collection is used for options options: - 0 - 1 - 2 - 3 initial: 0 ### Example of nested mapping[](https://www.home-assistant.io/docs/configuration/yaml/#example-of-nested-mapping) The following example shows nesting a collection of mappings in a mapping. In Home Assistant, this would create two sensors that each use the MQTT platform but have different values for their `state_topic` (one of the properties used for MQTT sensors). sensor: - platform: mqtt state_topic: "sensor/topic" - platform: mqtt state_topic: "sensor2/topic" Including values[](https://www.home-assistant.io/docs/configuration/yaml/#including-values) -------------------------------------------------------------------------------------------- ### Environment variables[](https://www.home-assistant.io/docs/configuration/yaml/#environment-variables) On Home Assistant CoreHome Assistant Core is the Python program at the heart of Home Assistant. It is part of all installation types. It can be installed standalone (without Home Assistant Supervisor) as a container using Docker (this is typically referred to as the Home Assistant Container installation type). For development, Core can also be run using a Virtual Environment (previously referred as the Home Assistant Core installation type). For production setup, the Home Assistant Core installation type is deprecated. installations, you can include values from your system’s environment variables with `!env_var`. Note that this will only work for Home Assistant CoreHome Assistant Core is the Python program at the heart of Home Assistant. It is part of all installation types. It can be installed standalone (without Home Assistant Supervisor) as a container using Docker (this is typically referred to as the Home Assistant Container installation type). For development, Core can also be run using a Virtual Environment (previously referred as the Home Assistant Core installation type). For production setup, the Home Assistant Core installation type is deprecated. installations, in a scenario where it is possible to specify these. Regular Home Assistant users are recommended to use `!include` statements instead. example: password: !env_var PASSWORD #### Default value[](https://www.home-assistant.io/docs/configuration/yaml/#default-value) If an environment variable is not set, you can fall back to a default value. example: password: !env_var PASSWORD default_password ### Including entire files[](https://www.home-assistant.io/docs/configuration/yaml/#including-entire-files) To improve readability, you can source out certain domains from your main configuration file with the `!include`\-syntax. light: !include lights.yaml More information about this feature can also be found at [splitting configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/) . Common issues[](https://www.home-assistant.io/docs/configuration/yaml/#common-issues) -------------------------------------------------------------------------------------- ### found character ‘\\t’[](https://www.home-assistant.io/docs/configuration/yaml/#found-character-t) If you see the following message: found character '\t' that cannot start any token This means that you’ve mistakenly entered a tab character, instead of spaces. ### Upper and lower case[](https://www.home-assistant.io/docs/configuration/yaml/#upper-and-lower-case) Home Assistant is case sensitive, a state of `'on'` is not the same as `'On'` or `'ON'`. Similarly an entity of `group.Doors` is not the same as `group.doors`. If you’re having trouble, check the case that Home Assistant is reporting in the dev-state menu, under _Developer tools_. ### Booleans[](https://www.home-assistant.io/docs/configuration/yaml/#booleans) YAML treats `Y`, `true`, `Yes`, `ON` all as `true` and `n`, `FALSE`, `No`, `off` as `false`. This means that if you want to set the state of an entity to `on` you _must_ quote it as `'on'` otherwise it will be translated as setting the state to true. The same applies to `off`. Not quoting the value may generate an error such as: not a valid value for dictionary value @ data Validating YAML syntax[](https://www.home-assistant.io/docs/configuration/yaml/#validating-yaml-syntax) -------------------------------------------------------------------------------------------------------- With all these indents and rules, it is easy to make a mistake. The best way to check if your YAML syntax is correct (validate) depends on the editor you use. We can’t list them all here. * If you edit the files directly in Home Assistant, refer to the section: [Validating the configuration](https://www.home-assistant.io/docs/configuration/#validating-the-configuration) Related topics[](https://www.home-assistant.io/docs/configuration/yaml/#related-topics) ---------------------------------------------------------------------------------------- * [Configuration.yaml file](https://www.home-assistant.io/docs/configuration/) * [Storing private data in separate file](https://www.home-assistant.io/docs/configuration/secrets/) * [Automation.yaml](https://www.home-assistant.io/docs/automation/yaml/) * [Troubleshooting the configuration files](https://www.home-assistant.io/docs/configuration/troubleshooting/) * [Validating the configuration](https://www.home-assistant.io/docs/configuration/#validating-the-configuration) Related links[](https://www.home-assistant.io/docs/configuration/yaml/#related-links) -------------------------------------------------------------------------------------- * [YAML Style Guide for Home Assistant developers](https://developers.home-assistant.io/docs/documenting/yaml-style-guide/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/yaml/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/yaml.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fyaml%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fyaml%2F%22&in=body "View given feedback for this page") --- # Conditions - Home Assistant Conditions can be used within a scriptScripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [\[Learn more\]](https://www.home-assistant.io/docs/scripts/) or automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/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. Unlike a triggerA trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [\[Learn more\]](https://www.home-assistant.io/docs/automation/trigger/) , which is always `or`, conditions are `and` by default - all conditions have to be true. All conditions support an optional `alias`. * [Logical conditions](https://www.home-assistant.io/docs/scripts/conditions/#logical-conditions) * [AND condition](https://www.home-assistant.io/docs/scripts/conditions/#and-condition) * [OR condition](https://www.home-assistant.io/docs/scripts/conditions/#or-condition) * [Mixed AND and OR conditions](https://www.home-assistant.io/docs/scripts/conditions/#mixed-and-and-or-conditions) * [NOT condition](https://www.home-assistant.io/docs/scripts/conditions/#not-condition) * [Numeric state condition](https://www.home-assistant.io/docs/scripts/conditions/#numeric-state-condition) * [State condition](https://www.home-assistant.io/docs/scripts/conditions/#state-condition) * [Sun condition](https://www.home-assistant.io/docs/scripts/conditions/#sun-condition) * [Sun elevation condition](https://www.home-assistant.io/docs/scripts/conditions/#sun-elevation-condition) * [Sunset/sunrise condition](https://www.home-assistant.io/docs/scripts/conditions/#sunsetsunrise-condition) * [Template condition](https://www.home-assistant.io/docs/scripts/conditions/#template-condition) * [Template condition shorthand notation](https://www.home-assistant.io/docs/scripts/conditions/#template-condition-shorthand-notation) * [Time condition](https://www.home-assistant.io/docs/scripts/conditions/#time-condition) * [Trigger condition](https://www.home-assistant.io/docs/scripts/conditions/#trigger-condition) * [Zone condition](https://www.home-assistant.io/docs/scripts/conditions/#zone-condition) * [Examples](https://www.home-assistant.io/docs/scripts/conditions/#examples) * [Disabling a condition](https://www.home-assistant.io/docs/scripts/conditions/#disabling-a-condition) Logical conditions[](https://www.home-assistant.io/docs/scripts/conditions/#logical-conditions) ------------------------------------------------------------------------------------------------ ### AND condition[](https://www.home-assistant.io/docs/scripts/conditions/#and-condition) Test multiple conditions in one condition statement. Passes if all embedded conditions are true. conditions: - alias: "Paulus home AND temperature below 20" condition: and conditions: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 If you do not want to combine AND and OR conditions, you can list them sequentially. The following configuration works the same as the one listed above: conditions: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 Currently you need to format your conditions like this to be able to edit them using the [automations editor](https://www.home-assistant.io/docs/automation/editor/) . The AND condition also has a shorthand form. The following configuration works the same as the ones listed above: conditions: alias: "Paulus home AND temperature below 20" - and: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 ### OR condition[](https://www.home-assistant.io/docs/scripts/conditions/#or-condition) Test multiple conditions in one condition statement. Passes if any embedded condition is true. conditions: - alias: "Paulus home OR temperature below 20" condition: or conditions: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 The OR condition also has a shorthand form. The following configuration works the same as the one listed above: conditions: - alias: "Paulus home OR temperature below 20" or: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 ### Mixed AND and OR conditions[](https://www.home-assistant.io/docs/scripts/conditions/#mixed-and-and-or-conditions) Test multiple AND and OR conditions in one condition statement. Passes if any embedded condition is true. This allows you to mix several AND and OR conditions together. conditions: - condition: and conditions: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: or conditions: - condition: state entity_id: sensor.weather_precip state: "rain" - condition: numeric_state entity_id: "sensor.temperature" below: 20 Or in shorthand form: conditions: - and: - condition: state entity_id: "device_tracker.paulus" state: "home" - or: - condition: state entity_id: sensor.weather_precip state: "rain" - condition: numeric_state entity_id: "sensor.temperature" below: 20 ### NOT condition[](https://www.home-assistant.io/docs/scripts/conditions/#not-condition) Test multiple conditions in one condition statement. Passes if all embedded conditions are **not** true. conditions: - alias: "Paulus not home AND alarm not disarmed" condition: not conditions: - condition: state entity_id: device_tracker.paulus state: "home" - condition: state entity_id: alarm_control_panel.home_alarm state: "disarmed" The NOT condition also has a shorthand form. The following configuration works the same as the one listed above: conditions: alias: "Paulus not home AND alarm not disarmed" not: - condition: state entity_id: device_tracker.paulus state: "home" - condition: state entity_id: alarm_control_panel.home_alarm state: disarmed Numeric state condition[](https://www.home-assistant.io/docs/scripts/conditions/#numeric-state-condition) ---------------------------------------------------------------------------------------------------------- This type of condition attempts to parse the state of the specified entity or the attribute of an entity as a number, and triggers if the value matches the thresholds (strictly below/above, so equal excluded). If both `below` and `above` are specified, both tests have to pass. conditions: - alias: "Temperature between 17 and 25 degrees" condition: numeric_state entity_id: sensor.temperature above: 17 below: 25 You can optionally use a `value_template` to process the value of the state before testing it. conditions: - condition: numeric_state entity_id: sensor.temperature above: 17 below: 25 # If your sensor value needs to be adjusted value_template: "{{ float(state.state) + 2 }}" It is also possible to test the condition against multiple entities at once. The condition will pass if **all** entities match the thresholds. conditions: - condition: numeric_state entity_id: - sensor.kitchen_temperature - sensor.living_room_temperature below: 18 Alternatively, the condition can test against a state attribute. The condition will pass if the attribute value of the entity matches the thresholds. conditions: - condition: numeric_state entity_id: climate.living_room_thermostat attribute: temperature above: 17 below: 25 Number helpers (`input_number` entities), `number`, `sensor`, and `zone` entities that contain a numeric value, can be used in the `above` and `below` options to make the condition more dynamic. conditions: - condition: numeric_state entity_id: climate.living_room_thermostat attribute: temperature above: input_number.temperature_threshold_low below: input_number.temperature_threshold_high State condition[](https://www.home-assistant.io/docs/scripts/conditions/#state-condition) ------------------------------------------------------------------------------------------ Tests if an entity has a specified state. conditions: - alias: "Paulus not home for an hour and a bit" condition: state entity_id: device_tracker.paulus state: "not_home" # optional: Evaluates to true only if state was this for last X time. for: hours: 1 minutes: 10 seconds: 5 It is also possible to test the condition against multiple entities at once. The condition will pass if **all** entities match the state. conditions: - condition: state entity_id: - light.kitchen - light.living_room state: "on" Instead of matching all, it is also possible if one of the entities matches. In the following example the condition will pass if **any** entity matches the state. conditions: - condition: state entity_id: - binary_sensor.motion_sensor_left - binary_sensor.motion_sensor_right match: any state: "on" Testing if an entity is matching a set of possible conditions; The condition will pass if the entity matches one of the states given. conditions: - condition: state entity_id: alarm_control_panel.home state: - "armed_away" - "armed_home" Or, combine multiple entities with multiple states. In the following example, both media players need to be either paused or playing for the condition to pass. conditions: - condition: state entity_id: - media_player.living_room - media_player.kitchen state: - "playing" - "paused" Alternatively, the condition can test against a state attribute. The condition will pass if the attribute matches the given state. conditions: - condition: state entity_id: climate.living_room_thermostat attribute: fan_mode state: "auto" Finally, the `state` option accepts helper entities (also known as `input_*` entities). The condition will pass if the state of the entity matches the state of the given helper entity. conditions: - condition: state entity_id: alarm_control_panel.home state: input_select.guest_mode You can also use templates in the `for` option. conditions: - condition: state entity_id: device_tracker.paulus state: "home" for: minutes: "{{ states('input_number.lock_min')|int }}" seconds: "{{ states('input_number.lock_sec')|int }}" The `for` template(s) will be evaluated when the condition is tested. ### Sun condition[](https://www.home-assistant.io/docs/scripts/conditions/#sun-condition) #### Sun state condition[](https://www.home-assistant.io/docs/scripts/conditions/#sun-state-condition) The sun state can be used to test if the sun has set or risen. conditions: - alias: "Sun up" condition: state # 'day' condition: from sunrise until sunset entity_id: sun.sun state: "above_horizon" conditions: - alias: "Sun down" condition: state # from sunset until sunrise entity_id: sun.sun state: "below_horizon" ### Sun elevation condition[](https://www.home-assistant.io/docs/scripts/conditions/#sun-elevation-condition) The sun elevation can be used to test if the sun has set or risen, it is dusk, it is night, etc. when a trigger occurs. For an in-depth explanation of sun elevation, see [sun elevation trigger](https://www.home-assistant.io/docs/automation/trigger/#sun-elevation-trigger) . conditions: - condition: and # 'twilight' condition: dusk and dawn, in typical locations conditions: - condition: template value_template: "{{ state_attr('sun.sun', 'elevation') < 0 }}" - condition: template value_template: "{{ state_attr('sun.sun', 'elevation') > -6 }}" conditions: condition: template # 'night' condition: from dusk to dawn, in typical locations value_template: "{{ state_attr('sun.sun', 'elevation') < -6 }}" ### Sunset/sunrise condition[](https://www.home-assistant.io/docs/scripts/conditions/#sunsetsunrise-condition) The sun condition can also test if the sun has already set or risen when a trigger occurs. The `before` and `after` keys can only be set to `sunset` or `sunrise`. They have a corresponding optional offset value (`before_offset`, `after_offset`) that can be added, similar to the [sun trigger](https://www.home-assistant.io/docs/automation/trigger/#sun-trigger) . Note that if only `before` key is used, the condition will be true _from midnight_ until sunrise/sunset. If only `after` key is used, the condition will be true from sunset/sunrise _until midnight_. If both `before: sunrise` and `after: sunset` keys are used, the condition will be true _from midnight_ until sunrise **and** from sunset _until midnight_. If both `after: sunrise` and `before: sunset` keys are used, the condition will be true from sunrise until sunset. 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. This is an example of 1 hour offset before sunset: conditions: - condition: sun after: sunset after_offset: "-01:00:00" This is ‘when dark’ - equivalent to a state condition on `sun.sun` of `below_horizon`: conditions: - condition: sun after: sunset before: sunrise This is ‘when light’ - equivalent to a state condition on `sun.sun` of `above_horizon`: conditions: - condition: sun after: sunrise before: sunset A visual timeline is provided below, showing an example of when these conditions are true. In this chart, sunrise is at 6:00, and sunset is at 18:00 (6:00 PM). The green areas of the chart indicate when the specified conditions are true. ![Graphic showing an example of sun conditions](https://www.home-assistant.io/images/docs/scripts/sun-conditions.svg) Template condition[](https://www.home-assistant.io/docs/scripts/conditions/#template-condition) ------------------------------------------------------------------------------------------------ The template condition tests if the [given template](https://www.home-assistant.io/docs/configuration/templating/) renders a value equal to true. This is achieved by having the template result in a true boolean expression or by having the template render `True`. conditions: - alias: "Iphone battery above 50%" condition: template value_template: "{{ (state_attr('device_tracker.iphone', 'battery_level')|int) > 50 }}" Within an automation, template conditions also have access to the `trigger` variable as [described here](https://www.home-assistant.io/getting-started/automation-templating/) . ### Template condition shorthand notation[](https://www.home-assistant.io/docs/scripts/conditions/#template-condition-shorthand-notation) The template condition has a shorthand notation that can be used to make your scripts and automations shorter. For example: conditions: "{{ (state_attr('device_tracker.iphone', 'battery_level')|int) > 50 }}" Or in a list of conditions, allowing to use existing conditions as described in this chapter and one or more shorthand template conditions conditions: - "{{ (state_attr('device_tracker.iphone', 'battery_level')|int) > 50 }}" - condition: state entity_id: alarm_control_panel.home state: armed_away - "{{ is_state('device_tracker.iphone', 'away') }}" This shorthand notation can be used everywhere in Home Assistant where conditions are accepted. For example, in [`and`](https://www.home-assistant.io/docs/scripts/conditions/#and-condition) , [`or`](https://www.home-assistant.io/docs/scripts/conditions/#or-condition) and [`not`](https://www.home-assistant.io/docs/scripts/conditions/#not-condition) conditions: conditions: - condition: or conditions: - "{{ is_state('device_tracker.iphone', 'away') }}" - condition: numeric_state entity_id: "sensor.temperature" below: 20 It’s also supported in the `repeat` action’s `while` or `until` option, or in a `choose` action’s `conditions` option: - while: "{{ is_state('sensor.mode', 'Home') and repeat.index < 10 }}" sequence: - ... - choose: - conditions: "{{ is_state('sensor.mode', 'Home') and repeat.index < 10 }}" sequence: - ... It’s also supported in script or automation `condition` actions: - condition: "{{ is_state('device_tracker.iphone', 'away') }}" Time condition[](https://www.home-assistant.io/docs/scripts/conditions/#time-condition) ---------------------------------------------------------------------------------------- The time condition can test if it is after a specified time, before a specified time or if it is a certain day of the week. conditions: - alias: "Time 15~02" condition: time # At least one of the following is required. after: "15:00:00" before: "02:00:00" weekday: - mon - wed - fri Valid values for `weekday` are `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. Note that if only `before` key is used, the condition will be `true` _from midnight_ until the specified time. 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. The after times are inclusive while before are exclusive. In the example above, if the time was at 3pm (15:00:00) then it meets the after time condition. If the time was at 2am (2:00:00), it would fail the condition because it will only be valid up to 1:59:59. Tip A better weekday condition could be by using the [Workday Binary Sensor](https://www.home-assistant.io/integrations/workday/) . For the `after` and `before` options a time helper (`input_datetime` entity), a `time` entity, or another `sensor` entity containing a timestamp with the “timestamp” device class, can be used instead. conditions: - alias: "Example referencing a time helper" condition: time after: input_datetime.house_silent_hours_start before: input_datetime.house_silent_hours_end - alias: "Example referencing a time entity" before: time.dnd_start - alias: "Example referencing another sensor" after: sensor.groceries_delivery_time 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. Trigger condition[](https://www.home-assistant.io/docs/scripts/conditions/#trigger-condition) ---------------------------------------------------------------------------------------------- The trigger condition can test if an automation was triggered by a certain trigger, identified by the trigger’s `id`. conditions: - condition: trigger id: event_trigger For a trigger identified by its index, both a string and integer is allowed: conditions: - condition: trigger id: "0" conditions: - condition: trigger id: 0 It is possible to give a list of triggers: conditions: - condition: trigger id: - event_1_trigger - event_2_trigger Zone condition[](https://www.home-assistant.io/docs/scripts/conditions/#zone-condition) ---------------------------------------------------------------------------------------- Zone conditions test if an entity is in a certain zone. For zone automation to work, you need to have set up a device tracker platform that supports reporting GPS coordinates. conditions: - alias: "Paulus at home" condition: zone entity_id: device_tracker.paulus zone: zone.home It is also possible to test the condition against multiple entities at once. The condition will pass if all entities are in the specified zone. conditions: - condition: zone entity_id: - device_tracker.frenck - device_tracker.daphne zone: zone.home Testing if an entity is matching a set of possible zones; The condition will pass if the entity is in one of the zones. conditions: - condition: zone entity_id: device_tracker.paulus state: - zone.home - zone.work Or, combine multiple entities with multiple zones. In the following example, both entities need to be either in the home or the work zone for the condition to pass. conditions: condition: zone entity_id: - device_tracker.frenck - device_tracker.daphne state: - zone.home - zone.work Examples[](https://www.home-assistant.io/docs/scripts/conditions/#examples) ---------------------------------------------------------------------------- conditions: - condition: numeric_state entity_id: sun.sun value_template: "{{ state.attributes.elevation }}" below: 1 - condition: state entity_id: light.living_room state: "off" - condition: time before: "23:00:00" after: "14:00:00" - condition: state entity_id: script.light_turned_off_5min state: "off" Disabling a condition[](https://www.home-assistant.io/docs/scripts/conditions/#disabling-a-condition) ------------------------------------------------------------------------------------------------------ Every individual condition can be disabled, without removing it. To do so, add `enabled: false` to the condition configuration. This can be useful if you want to temporarily disable a condition, for example, for testing. A disabled condition will behave as if it were removed. For example: # This condition will always pass, as it is disabled. conditions: - enabled: false condition: state entity_id: sun.sun state: "above_horizon" Conditions can also be disabled based on limited templates or blueprint inputs. blueprint: input: input_boolean: name: Boolean selector: boolean: input_number: name: Number selector: number: min: 0 max: 100 trigger_variables: _enable_number: !input input_number conditions: - condition: state entity_id: sun.sun state: "above_horizon" enabled: !input input_boolean - condition: state entity_id: sun.sun state: "below_horizon" enabled: "{{ _enable_number < 50 }}" #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/scripts/conditions/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/scripts/conditions.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fscripts%2Fconditions%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fscripts%2Fconditions%2F%22&in=body "View given feedback for this page") --- # Troubleshooting your configuration - Home Assistant It can happen that you run into trouble while configuring Home Assistant. Perhaps an integration is not showing up or is acting strangely. This page will discuss a few of the most common problems. Before we dive into common issues, make sure you know where your configuration directory is. Home Assistant will print out the configuration directory it is using when starting up. Whenever an integration or configuration option results in a warning, it will be stored in [the logs](https://www.home-assistant.io/integrations/logger/#viewing-logs) . My integration does not show up[](https://www.home-assistant.io/docs/configuration/troubleshooting/#my-integration-does-not-show-up) ------------------------------------------------------------------------------------------------------------------------------------- When an integration does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the [the logs](https://www.home-assistant.io/integrations/logger/#viewing-logs) and see if there are any errors related to your integration you are trying to set up. If you have incorrect entries in your configuration files you can use the configuration check command (below) to assist in identifying them. ### Problems with the configuration[](https://www.home-assistant.io/docs/configuration/troubleshooting/#problems-with-the-configuration) One of the most common problems with Home Assistant is an invalid `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) or other configuration file. * Home Assistant provides a CLI that allows you to see how it interprets them, each installation type has its own section in the common-tasks about this: * [Operating System](https://www.home-assistant.io/common-tasks/os/#configuration-check) * [Container](https://www.home-assistant.io/common-tasks/container/#configuration-check) * The configuration files, including `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) must be UTF-8 encoded. If you see error like `'utf-8' codec can't decode byte`, edit the offending configuration and re-save it as UTF-8. * You can verify your configuration’s YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) structure using [this online YAML parser](https://yaml-online-parser.appspot.com/) or [YAML Validator](https://codebeautify.org/yaml-validator/) . * To learn more about the quirks of YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) , read [YAML IDIOSYNCRASIES](https://docs.saltproject.io/en/latest/topics/troubleshooting/yaml_idiosyncrasies.html) by SaltStack (the examples there are specific to SaltStack, but do explain YAML issues well). `configuration.yaml` does not allow multiple sections to have the same name. If you want to load multiple platforms for one integration, you can append a number or string to the name or nest them: sensor: - platform: forecast ... - platform: bitcoin ... Another common problem is that a required configuration setting is missing. If this is the case, the integration will report this in [the logs](https://www.home-assistant.io/integrations/logger/#viewing-logs) . You can have a look at [the various integration pages](https://www.home-assistant.io/integrations/) for instructions on how to setup the integrations. See the [logger](https://www.home-assistant.io/integrations/logger/) integration for instructions on how to define the level of logging you require for specific modules. If you find any errors or want to expand the documentation, please [let us know](https://github.com/home-assistant/home-assistant.io/issues) . #### Problems with dependencies[](https://www.home-assistant.io/docs/configuration/troubleshooting/#problems-with-dependencies) Almost all integrations have external dependencies to communicate with your devices and services. Sometimes Home Assistant is unable to install the necessary dependencies. If this is the case, it should show up in [the logs](https://www.home-assistant.io/integrations/logger/#viewing-logs) . The first step is trying to restart Home Assistant and see if the problem persists. If it does, look at the log to see what the error is. If you can’t figure it out, please [report it](https://github.com/home-assistant/core/issues) so we can investigate what is going on. #### Problems with integrations[](https://www.home-assistant.io/docs/configuration/troubleshooting/#problems-with-integrations) It can happen that some integrations either do not work right away or stop working after Home Assistant has been running for a while. If this happens to you, please [report it](https://github.com/home-assistant/core/issues) so that we can have a look. #### Multiple files[](https://www.home-assistant.io/docs/configuration/troubleshooting/#multiple-files) If you are using multiple files for your setup, make sure that the pointers are correct and the format of the files is valid. It’s important to understand the different types of `!include` and how the contents of each file should be structured - more information on the various methods of splitting your configuration into multiple files can be found [here](https://www.home-assistant.io/docs/configuration/splitting_configuration) . light: !include devices/lights.yaml sensor: !include devices/sensors.yaml Contents of `lights.yaml` (notice it does not contain `light:`): - platform: hyperion host: 192.168.1.98 ... Contents of `sensors.yaml`: - platform: mqtt name: "Room Humidity" state_topic: "room/humidity" - platform: mqtt name: "Door Motion" state_topic: "door/motion" ... 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. ### Entity names[](https://www.home-assistant.io/docs/configuration/troubleshooting/#entity-names) The only characters valid in entity names are: * Lowercase letters * Numbers * Underscores The entity name must not start or end with an underscore. If you create an entity with other characters from the UI, Home Assistant validates the name. If you change the name directly in the YAMLYAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/yaml/) file, then Home Assistant may not generate an error for that entity. However, attempts to use that entity will generate errors (or possibly fail silently). For instructions on how to change an entity name, refer to the section on [customizing entities](https://www.home-assistant.io/docs/configuration/customizing-devices/) . Debug logs and diagnostics[](https://www.home-assistant.io/docs/configuration/troubleshooting/#debug-logs-and-diagnostics) --------------------------------------------------------------------------------------------------------------------------- The first thing you will need before reporting an issue online is debug logs and diagnostics (if available) for the integration giving you trouble. Getting those ahead of time will ensure someone can help resolve your issue in the fastest possible manner. ### Enabling debug logging[](https://www.home-assistant.io/docs/configuration/troubleshooting/#enabling-debug-logging) To enable debug logging for a specific integration, follow these steps: 1. Go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the integration for which you want to enable debug logging. 3. In the top right of the page, open the three dots menu, and select **Enable debug logging**. ![Screenshot showing the Enable debug logging button on an integration detail page](https://www.home-assistant.io/images/docs/configuration/enable-debug-logging.png) Screenshot showing the **Enable debug logging** menu item. 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](https://www.home-assistant.io/docs/configuration/troubleshooting/#disable-debug-logging-and-download-logs) . ### Disable debug logging and download logs[](https://www.home-assistant.io/docs/configuration/troubleshooting/#disable-debug-logging-and-download-logs) Once you enable debug logging, you ideally need to make the error happen. Run your automation, change up your device or whatever was giving you an error and then come back and disable the debug logging. Disabling the debug logging is the same as enabling, but now the menu option says **Disable debug logging**. After you disable it, you will be automatically prompted you to download your log file. Save this to a safe location to upload later. ### Download diagnostics[](https://www.home-assistant.io/docs/configuration/troubleshooting/#download-diagnostics) After you download logs, you will also want to download the diagnostics for the integration giving you trouble. If the integration provides diagnostics, it will appear in the three dots menu next to the integration configuration. ![Example of Download Diagnostics](https://www.home-assistant.io/images/docs/configuration/download-diagnostics.png) Example of Download Diagnostics. ### Handling unexpected restarts or crashes[](https://www.home-assistant.io/docs/configuration/troubleshooting/#handling-unexpected-restarts-or-crashes) Suppose you find that Home Assistant unexpectedly restarts or crashes; it’s likely that you have a misbehaving integration impacting system stability. Home Assistant has a built-in debug option that can help find implementation errors. It can also block many unsafe thread operations from crashing the system. Enabling debug has a slight performance impact on the system and is not recommended for long-term use. To enable debug, add the following to your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) : homeassistant: debug: true Once debug is enabled, periodically check [Home Assistant System Logs](https://my.home-assistant.io/redirect/logs) for new messages. Related topics[](https://www.home-assistant.io/docs/configuration/troubleshooting/#related-topics) --------------------------------------------------------------------------------------------------- * [Configuration.yaml](https://www.home-assistant.io/docs/configuration/) * [Changing entity name and id](https://www.home-assistant.io/docs/configuration/customizing-devices/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/troubleshooting/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/troubleshooting.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Ftroubleshooting%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Ftroubleshooting%2F%22&in=body "View given feedback for this page") --- # State and state object - Home Assistant Devices are represented in Home Assistant as entitiesAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) . 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_. State versus state object[](https://www.home-assistant.io/docs/configuration/state_object/#state-versus-state-object) ---------------------------------------------------------------------------------------------------------------------- In Home Assistant, the state object is the current representation of the entityAn entity represents a 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 device or a service. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/entities_domains/) 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. ### About the state object[](https://www.home-assistant.io/docs/configuration/state_object/#about-the-state-object) 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. | 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[](https://www.home-assistant.io/docs/configuration/state_object/#about-the-state) The screenshot of the Developer Tools States page 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 the `supported_color_modes` attribute 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`](https://www.home-assistant.io/images/integrations/light/state_light.png) Three lights with different states: \`on\`, \`off\`, or \`unavailable\`. The `state.state` is the heart of the [state object](https://www.home-assistant.io/docs/configuration/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[](https://www.home-assistant.io/docs/configuration/state_object/#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](https://www.home-assistant.io/docs/configuration/events/#events-and-state-changes) can be used as triggers. The current state can be used in [conditions](https://www.home-assistant.io/docs/automation/condition/) . The example below shows three lights with different entity state attributes. ![Screenshot showing three lights with different states and attributes](https://www.home-assistant.io/images/integrations/light/state_light.png) 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`. 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](https://www.home-assistant.io/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[](https://www.home-assistant.io/docs/configuration/state_object/#context) ---------------------------------------------------------------------------------- Context is a property used in state objects and events. It ties eventsEvery time something happens in Home Assistant, an event is fired. There are different types of events, such as state change events, when an action was triggered, or the time changed. All entities produce state change events. Every time a state changes, a state change event is produced. Events can be used to trigger automations or scripts. For example, you can trigger an automation when a light is turned on, then a speaker turns on in that room. Events can also be used to trigger actions in the frontend. For example, you can trigger an action when a button is pressed. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/events/) and statesThe state holds the information of interest of an entity, for example, if a light is on or off. Each entity has exactly one state and the state only holds one value at a time. However, entities can store attributes related to that state such as brightness, color, or a unit of measurement. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/state_object/) together in Home Assistant. Whenever an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/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 | | --- | --- | | `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. | Examples[](https://www.home-assistant.io/docs/configuration/state_object/#examples) ------------------------------------------------------------------------------------ * Evaluate the `state.last_changed` of a switch entity: {{ states.switch.my_switch.last_changed }} result type: `string` representing a datetime object e.g. `2025-11-11 12:56:10.244125+00:00` * * * * Evaluate the `state.context.id` of this switch: {{ states.switch.my_switch.context.id }} result type: `string` representing an id code e.g. `01K9SF2R36KRV5N4PTC38S6KJ2F` * * * * Evaluate the `state.context.user_id` of this switch: {{ states.switch.my_switch.context.user_id }} result type: `string` representing an user id code e.g. `01K9SF2R36KRV5N4PTC38SKS4LW6` Related topics[](https://www.home-assistant.io/docs/configuration/state_object/#related-topics) ------------------------------------------------------------------------------------------------ * [Entities and domains](https://www.home-assistant.io/docs/configuration/entities_domains/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/state_object/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/state_object.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fstate_object%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fstate_object%2F%22&in=body "View given feedback for this page") --- # Splitting up the configuration - Home Assistant So you’ve been using Home Assistant for a while now and your `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) file brings people to tears because it has become so large. Or, you simply want to start off with the distributed approach. Here’s how to split the `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) into more manageable (read: human-readable) pieces. Example configuration files for inspiration[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#example-configuration-files-for-inspiration) --------------------------------------------------------------------------------------------------------------------------------------------------------------------- First off, several community members have sanitized (read: without API keys/passwords) versions of their configurations available for viewing. You can see a [list of example configuration on GitHub](https://github.com/search?q=topic%3Ahome-assistant-config&type=Repositories) . As commenting code doesn’t always happen, please read on to learn in detail how configuration files can be structured. Analyzing the configuration files[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#analyzing-the-configuration-files) ------------------------------------------------------------------------------------------------------------------------------------------------- In this section, we are going use some example configuration files and look at their structure and format in more detail. Now you might think that the `configuration.yaml`The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [\[Learn more\]](https://www.home-assistant.io/docs/configuration/) will be replaced during the splitting process. However, it will in fact remain, albeit in a much less cluttered form. ### The core configuration file[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#the-core-configuration-file) In this lighter version, we will still need what could be called the core snippet: homeassistant: # Name of the location where Home Assistant is running name: "My Home Assistant Instance" # Location required to calculate the time the sun rises and sets latitude: 37 longitude: -121 # 'metric' for Metric, 'us_customary' for US Customary unit_system: us_customary # Pick yours from here: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones time_zone: "America/Los_Angeles" customize: !include customize.yaml ### Indentation, includes, comments, and modularization[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#indentation-includes-comments-and-modularization) Note that each line after `homeassistant:` is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under `customize:`. `!include customize.yaml` is the statement that tells Home Assistant to insert the parsed contents of `customize.yaml` at that point. The contents of the included file must be yaml data that is valid at the location it is included. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks. Now before we start splitting out the different components, let’s look at the other integrations (in our example) that will stay in the base file: history: frontend: logbook: http: api_password: "ImNotTelling!" ifttt: key: ["nope"] mqtt: sensor: - name: "test sensor 1" state_topic: "test/some_topic1" - name: "test sensor 2" state_topic: "test/some_topic2" As with the core snippet, indentation makes a difference: * The integration headers (`mqtt:`) should be fully left aligned (aka no indent). * The key (`sensor:`) should be indented two (2) spaces. * The list `-` under the key `sensor` should be indented another two (2) spaces followed by a single space. * The `mqtt` sensor list contains two (2) configurations, with two (2) keys each. #### Comments[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#comments) The # symbol (hash/pound) represents a “comment” as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored by the software. It is for humans only. Comments allow breaking up files for readability, as well as turning off features while leaving the entry intact. #### Modularization and granularity[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#modularization-and-granularity) While some of these integrations could technically be moved to a separate file, they are so small or “one off’s” where splitting them off is superfluous. Now, lets assume that a blank file has been created in the Home Assistant configuration directory for each of the following: automation.yaml zone.yaml sensor.yaml switch.yaml device_tracker.yaml customize.yaml `automation.yaml` will hold all the automation integration details. `zone.yaml` will hold the zone integration details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of. Inside the base configuration file, add the following entries: automation: !include automation.yaml zone: !include zone.yaml sensor: !include sensor.yaml switch: !include switch.yaml device_tracker: !include device_tracker.yaml #### Include statements and packages to split files[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#include-statements-and-packages-to-split-files) Nesting `!include` statements (having an `!include` within a file that is itself `!include`d) will also work. Some integrations support multiple top-level `!include` statements. This includes integrations defining an IoT domain. For example, `light`, `switch`, or `sensor`; as well as the `automation`, `script`, and `template` integrations, if you give a different label to each one. Configuration for other integrations can instead be split up by using packages. To learn more about packages, see the [Packages](https://www.home-assistant.io/docs/configuration/packages) page. #### Top level keys[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#top-level-keys) Example of multiple top-level keys for the `light` platform. light: - platform: group name: "Bedside Lights" entities: - light.left_bedside_light - light.right_bedside_light # define more light groups in a separate file light groups: !include light-groups.yaml # define some light switch mappings in a different file light switches: !include light-switches.yaml where `light-groups.yaml` might look like: - platform: group name: "Outside Lights" entities: - light.porch_lights - light.patio_lights with `light-switches.yaml` containing: - platform: switch name: "Patio Lights" entity_id: switch.patio_lights - platform: switch name: "Floor Lamp" entity_id: switch.floor_lamp_plug Alright, so we’ve got the single integrations and the include statements in the base file, what goes in those extra files? Let’s look at the `device_tracker.yaml` file from our example: - platform: owntracks - platform: nmap_tracker home_interval: 3 hosts: 192.168.2.0/24 track_new_devices: true interval_seconds: 40 consider_home: 120 This small example illustrates how the “split” files work. In this case, we start with two (2) device tracker entries (`owntracks` and `nmap`). These files follow [“style 1”](https://www.home-assistant.io/getting-started/devices/#style-2-list-each-device-separately) that is to say a fully left aligned leading entry (`- platform: owntracks`) followed by the parameter entries indented two (2) spaces. This (large) sensor configuration gives us another example: ### sensor.yaml ### METEOBRIDGE ############################################# - platform: tcp name: "Outdoor Temp (Meteobridge)" host: 192.168.2.82 timeout: 6 payload: "Content-type: text/xml; charset=UTF-8\n\n" value_template: "{{value.split (' ')[2]}}" unit: C - platform: tcp name: "Outdoor Humidity (Meteobridge)" host: 192.168.2.82 port: 5556 timeout: 6 payload: "Content-type: text/xml; charset=UTF-8\n\n" value_template: "{{value.split (' ')[3]}}" unit: Percent #### STEAM FRIENDS ################################## - platform: steam_online api_key: ["not telling"] accounts: - 76561198012067051 #### TIME/DATE ################################## - platform: time_date display_options: - "time" - "date" - platform: worldclock time_zone: Etc/UTC name: "UTC" - platform: worldclock time_zone: America/New_York name: "Ann Arbor" You’ll notice that this example includes a secondary parameter section (under the steam section) as well as a better example of the way comments can be used to break down files into sections. All of the above can be applied when splitting up files using packages. To learn more about packages, see the [Packages](https://www.home-assistant.io/docs/configuration/packages) page. That about wraps it up. If you have issues, check the file indentations and check [the Home Assistant logs](https://www.home-assistant.io/integrations/logger/#viewing-logs) . If all else fails, head over to our [Discord chat server](https://discord.gg/c5DvZ4e) and ask away. Debugging configuration files[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#debugging-configuration-files) ----------------------------------------------------------------------------------------------------------------------------------------- If you have many configuration files, Home Assistant provides a CLI that allows you to see how it interprets them. Each installation type has its own section in the common-tasks about this: * [Operating System](https://www.home-assistant.io/common-tasks/os/#configuration-check) * [Container](https://www.home-assistant.io/common-tasks/container/#configuration-check) Advanced usage[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#advanced-usage) ----------------------------------------------------------------------------------------------------------- We offer four advanced options to include whole directories at once. Please note that your files must have the `.yaml` file extension; `.yml` is not supported. This will allow you to `!include` files with `.yml` extensions from within the `.yaml` files; without those `.yml` files being imported by the following commands themselves. * `!include_dir_list` will return the content of a directory as a list with each file content being an entry in the list. The list entries are ordered based on the alphanumeric ordering of the names of the files. * `!include_dir_named` will return the content of a directory as a dictionary which maps filename => content of file. * `!include_dir_merge_list` will return the content of a directory as a list by merging all files (which should contain a list) into 1 big list. * `!include_dir_merge_named` will return the content of a directory as a dictionary by loading each file and merging it into 1 big dictionary. These work recursively. As an example using `!include_dir_list automation`, will include all 6 files shown below: . └── .homeassistant ├── automation │   ├── lights │   │   ├── turn_light_off_bedroom.yaml │   │   ├── turn_light_off_lounge.yaml │   │   ├── turn_light_on_bedroom.yaml │   │   └── turn_light_on_lounge.yaml │   ├── say_hello.yaml │   └── sensors │   └── react.yaml └── configuration.yaml (not included) ### Example: !include\_dir\_list[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#example-include_dir_list) `configuration.yaml` automation: - alias: "Automation 1" triggers: - trigger: state entity_id: device_tracker.iphone to: "home" actions: - action: light.turn_on target: entity_id: light.entryway - alias: "Automation 2" triggers: - trigger: state entity_id: device_tracker.iphone from: "home" actions: - action: light.turn_off target: entity_id: light.entryway can be turned into: `configuration.yaml` automation: !include_dir_list automation/presence/ `automation/presence/automation1.yaml` alias: "Automation 1" triggers: - trigger: state entity_id: device_tracker.iphone to: "home" actions: - action: light.turn_on target: entity_id: light.entryway `automation/presence/automation2.yaml` alias: "Automation 2" triggers: - trigger: state entity_id: device_tracker.iphone from: "home" actions: - action: light.turn_off target: entity_id: light.entryway It is important to note that each file must contain only **one** entry when using `!include_dir_list`. ### Example: !include\_dir\_named[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#example-include_dir_named) `configuration.yaml` alexa: intents: LocateIntent: actions: action: notify.pushover data: message: "Your location has been queried via Alexa." speech: type: plaintext text: > {%- for state in states.device_tracker -%} {%- if state.name.lower() == User.lower() -%} {{ state.name }} is at {{ state.state }} {%- endif -%} {%- else -%} I am sorry. Pootie! I do not know where {{User}} is. {%- endfor -%} WhereAreWeIntent: speech: type: plaintext text: > {%- if is_state('device_tracker.iphone', 'home') -%} iPhone is home. {%- else -%} iPhone is not home. {% endif %} can be turned into: `configuration.yaml` alexa: intents: !include_dir_named alexa/ `alexa/LocateIntent.yaml` actions: action: notify.pushover data: message: "Your location has been queried via Alexa." speech: type: plaintext text: > {%- for state in states.device_tracker -%} {%- if state.name.lower() == User.lower() -%} {{ state.name }} is at {{ state.state }} {%- endif -%} {%- else -%} I am sorry. Pootie! I do not know where {{User}} is. {%- endfor -%} `alexa/WhereAreWeIntent.yaml` speech: type: plaintext text: > {%- if is_state('device_tracker.iphone', 'home') -%} iPhone is home. {%- else -%} iPhone is not home. {% endif %} ### Example: !include\_dir\_merge\_list[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#example-include_dir_merge_list) `configuration.yaml` automation: - alias: "Automation 1" triggers: - trigger: state entity_id: device_tracker.iphone to: "home" actions: - action: light.turn_on target: entity_id: light.entryway - alias: "Automation 2" triggers: - trigger: state entity_id: device_tracker.iphone from: "home" actions: - action: light.turn_off target: entity_id: light.entryway can be turned into: `configuration.yaml` automation: !include_dir_merge_list automation/ `automation/presence.yaml` - alias: "Automation 1" triggers: - trigger: state entity_id: device_tracker.iphone to: "home" actions: - action: light.turn_on target: entity_id: light.entryway - alias: "Automation 2" triggers: - trigger: state entity_id: device_tracker.iphone from: "home" actions: - action: light.turn_off target: entity_id: light.entryway It is important to note that when using `!include_dir_merge_list`, you must include a list in each file (each list item is denoted with a hyphen \[-\]). Each file may contain one or more entries. ### Example: !include\_dir\_merge\_named[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#example-include_dir_merge_named) `configuration.yaml` group: bedroom: name: "Bedroom" entities: - light.bedroom_lamp - light.bedroom_overhead hallway: name: "Hallway" entities: - light.hallway - thermostat.home front_yard: name: "Front Yard" entities: - light.front_porch - light.security - light.pathway - sensor.mailbox - camera.front_porch can be turned into: `configuration.yaml` group: !include_dir_merge_named group/ `group/interior.yaml` bedroom: name: "Bedroom" entities: - light.bedroom_lamp - light.bedroom_overhead hallway: name: Hallway entities: - light.hallway - thermostat.home `group/exterior.yaml` front_yard: name: "Front Yard" entities: - light.front_porch - light.security - light.pathway - sensor.mailbox - camera.front_porch ### Example: Combine !include\_dir\_merge\_list with automations.yaml[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#example-combine-include_dir_merge_list-with-automationsyaml) You want to go the advanced route and split your automations, but still want to be able to create [automations in the UI](https://my.home-assistant.io/redirect/automations) ? In a chapter above we write about nesting `!includes`. Here is how we can do that for automations. Using labels like `manual` or `ui` allows for using multiple keys in the config: `configuration.yaml` # My own handmade automations automation manual: !include_dir_merge_list automations/ # Automations I create in the UI automation ui: !include automations.yaml Related topics[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#related-topics) ----------------------------------------------------------------------------------------------------------- * [Configuration.yaml file](https://www.home-assistant.io/docs/configuration/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/splitting_configuration/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/splitting_configuration.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Fsplitting_configuration%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Fsplitting_configuration%2F%22&in=body "View given feedback for this page") --- # Script Syntax - Home Assistant Scripts are a sequence of actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) that Home Assistant will execute. Scripts are available as an entity through the standalone [Script integration](https://www.home-assistant.io/integrations/script/) but can also be embedded in automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) and [Alexa/Amazon Echo](https://www.home-assistant.io/integrations/alexa/) configurations. When the script is executed within an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) , the `trigger` variable is available. See [Available-Trigger-Data](https://www.home-assistant.io/docs/automation/templating/#available-trigger-data) . Script syntax[](https://www.home-assistant.io/docs/scripts/#script-syntax) --------------------------------------------------------------------------- The script syntax basic structure is a list of key/value maps that contain actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . If a script contains only 1 actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) , the wrapping list can be omitted. All actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) support an optional `alias`. # Example script integration containing script syntax script: example_script: sequence: # This is written using the Script Syntax - alias: "Turn on ceiling light" action: light.turn_on target: entity_id: light.ceiling - alias: "Notify that ceiling light is turned on" action: notify.notify data: message: "Turned on the ceiling light!" * [Script syntax](https://www.home-assistant.io/docs/scripts/#script-syntax) * [Perform an action](https://www.home-assistant.io/docs/scripts/#perform-an-action) * [Activate a scene](https://www.home-assistant.io/docs/scripts/#activate-a-scene) * [Variables](https://www.home-assistant.io/docs/scripts/#variables) * [Scope of variables](https://www.home-assistant.io/docs/scripts/#scope-of-variables) * [Test a condition](https://www.home-assistant.io/docs/scripts/#test-a-condition) * [Wait for time to pass (delay)](https://www.home-assistant.io/docs/scripts/#wait-for-time-to-pass-delay) * [Wait](https://www.home-assistant.io/docs/scripts/#wait) * [Wait for a template](https://www.home-assistant.io/docs/scripts/#wait-for-a-template) * [Wait for a trigger](https://www.home-assistant.io/docs/scripts/#wait-for-a-trigger) * [Wait timeout](https://www.home-assistant.io/docs/scripts/#wait-timeout) * [Wait variable](https://www.home-assistant.io/docs/scripts/#wait-variable) * [Fire an event](https://www.home-assistant.io/docs/scripts/#fire-an-event) * [Raise and Consume Custom Events](https://www.home-assistant.io/docs/scripts/#raise-and-consume-custom-events) * [Repeat a group of actions](https://www.home-assistant.io/docs/scripts/#repeat-a-group-of-actions) * [Counted repeat](https://www.home-assistant.io/docs/scripts/#counted-repeat) * [For each](https://www.home-assistant.io/docs/scripts/#for-each) * [While loop](https://www.home-assistant.io/docs/scripts/#while-loop) * [Repeat until](https://www.home-assistant.io/docs/scripts/#repeat-until) * [Repeat loop variable](https://www.home-assistant.io/docs/scripts/#repeat-loop-variable) * [If-then](https://www.home-assistant.io/docs/scripts/#if-then) * [Choose a group of actions](https://www.home-assistant.io/docs/scripts/#choose-a-group-of-actions) * [Grouping actions](https://www.home-assistant.io/docs/scripts/#grouping-actions) * [Parallelizing actions](https://www.home-assistant.io/docs/scripts/#parallelizing-actions) * [Stopping a script sequence](https://www.home-assistant.io/docs/scripts/#stopping-a-script-sequence) * [Continuing on error](https://www.home-assistant.io/docs/scripts/#continuing-on-error) * [Disabling an action](https://www.home-assistant.io/docs/scripts/#disabling-an-action) * [Respond to a conversation](https://www.home-assistant.io/docs/scripts/#respond-to-a-conversation) Perform an action[](https://www.home-assistant.io/docs/scripts/#perform-an-action) ----------------------------------------------------------------------------------- Performing an action can be done in various ways. For all the different possibilities, have a look at the [actions page](https://www.home-assistant.io/docs/scripts/perform-actions/) . - alias: "Bedroom lights on" action: light.turn_on target: entity_id: group.bedroom data: brightness: 100 ### Activate a scene[](https://www.home-assistant.io/docs/scripts/#activate-a-scene) Scripts may also use a shortcut syntax for activating scenesScenes capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red. [\[Learn more\]](https://www.home-assistant.io/integrations/scene/) instead of calling the `scene.turn_on` action. - scene: scene.morning_living_room Variables[](https://www.home-assistant.io/docs/scripts/#variables) ------------------------------------------------------------------- The variables actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows you to set/override variables that will be accessible by templates in actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) after it. See also [script variables](https://www.home-assistant.io/integrations/script/#configuration-variables) for how to define variables accessible in the entire script. - alias: "Set variables" variables: entities: - light.kitchen - light.living_room brightness: 100 - alias: "Control lights" action: light.turn_on target: entity_id: "{{ entities }}" data: brightness: "{{ brightness }}" Variables can be templated. - alias: "Set a templated variable" variables: blind_state_message: "The blind is {{ states('cover.blind') }}." - alias: "Notify about the state of the blind" action: notify.mobile_app_iphone data: message: "{{ blind_state_message }}" ### Scope of variables[](https://www.home-assistant.io/docs/scripts/#scope-of-variables) The `variables` actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) assigns the values to previously defined variables with the same name. If a variable was not previously defined, it is assigned in the top-level (script run) scope. sequence: # Set the people variable to a default value - variables: people: 0 # Try to increment people if Paulus is home - if: - condition: state entity_id: device_tracker.paulus state: "home" then: - variables: people: "{{ people + 1 }}" paulus_home: true - action: notify.notify data: message: "There are {{ people }} people home" # "There are 1 people home" # Variable value is now updated - action: notify.notify data: message: "There are {{ people }} people home {% if paulus_home is defined %}(including Paulus){% endif %}" # "There are 1 people home (including Paulus)" Test a condition[](https://www.home-assistant.io/docs/scripts/#test-a-condition) --------------------------------------------------------------------------------- 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](https://www.home-assistant.io/docs/scripts/conditions/) . Note The `condition` actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) only stops executing the current sequence block. When it is used inside a [repeat](https://www.home-assistant.io/docs/scripts/#repeat-a-group-of-actions) action, only the current iteration of the `repeat` loop will stop. When it is used inside a [choose](https://www.home-assistant.io/docs/scripts/#choose-a-group-of-actions) action, only the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) within that `choose` will stop. # If paulus is home, continue to execute the script below these lines - alias: "Check if Paulus is home" condition: state entity_id: device_tracker.paulus state: "home" `condition` can also be a list of conditions and execution will then only continue if ALL conditions return `true`. - alias: "Check if Paulus ishome AND temperature is below 20" conditions: - condition: state entity_id: "device_tracker.paulus" state: "home" - condition: numeric_state entity_id: "sensor.temperature" below: 20 Wait for time to pass (delay)[](https://www.home-assistant.io/docs/scripts/#wait-for-time-to-pass-delay) --------------------------------------------------------------------------------------------------------- Delays are useful for temporarily suspending your script and start it at a later moment. We support different syntaxes for a delay as shown below. # Seconds # Waits 5 seconds - alias: "Wait 5s" delay: 5 # HH:MM # Waits 1 hour - delay: "01:00" # HH:MM:SS # Waits 1.5 minutes - delay: "00:01:30" # Supports milliseconds, seconds, minutes, hours, days # Can be used in combination, at least one required # When using milliseconds, consider that delay as *at least* X milliseconds. It won´t be exact. # Waits 1 minute - delay: minutes: 1 All forms accept templates. # Waits however many minutes input_number.minute_delay is set to - delay: "{{ states('input_number.minute_delay') | multiply(60) | int }}" Wait[](https://www.home-assistant.io/docs/scripts/#wait) --------------------------------------------------------- These actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allow a script to wait for entities in the system to be in a certain state as specified by a template, or some event to happen as expressed by one or more triggers. ### Wait for a template[](https://www.home-assistant.io/docs/scripts/#wait-for-a-template) This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) evaluates the template, and if true, the script will continue. If not, then it will wait until it is true. The template is re-evaluated whenever an entity ID that it references changes state. If you use non-deterministic functions like `now()` in the template it will not be continuously re-evaluated, but only when an entity ID that is referenced is changed. If you need to periodically re-evaluate the template, reference a sensor from the [Time and Date](https://www.home-assistant.io/integrations/time_date/) integration that will update minutely or daily. # Wait until media player is stopped - alias: "Wait until media player is stopped" wait_template: "{{ is_state('media_player.floor', 'stop') }}" ### Wait for a trigger[](https://www.home-assistant.io/docs/scripts/#wait-for-a-trigger) This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) can use the same triggers that are available in an automation’s `trigger` section. See [Automation Trigger](https://www.home-assistant.io/docs/automation/trigger) . The script will continue whenever any of the triggers fires. All previously defined [trigger variables](https://www.home-assistant.io/docs/automation/trigger#trigger-variables) , [variables](https://www.home-assistant.io/docs/scripts/#variables) and [script variables](https://www.home-assistant.io/integrations/script/#configuration-variables) are passed to the trigger. # Wait for a custom event or light to turn on and stay on for 10 sec - alias: "Wait for MY_EVENT or light on" wait_for_trigger: - trigger: event event_type: MY_EVENT - trigger: state entity_id: light.LIGHT to: "on" for: 10 ### Wait timeout[](https://www.home-assistant.io/docs/scripts/#wait-timeout) With both types of waits it is possible to set a timeout after which the script will continue its execution if the condition/event is not satisfied. Timeout has the same syntax as `delay`, and like `delay`, also accepts templates. # Wait for sensor to change to 'on' up to 1 minute before continuing to execute. - wait_template: "{{ is_state('binary_sensor.entrance', 'on') }}" timeout: "00:01:00" You can also get the script to abort after the timeout by using optional `continue_on_timeout: false`. # Wait for IFTTT event or abort after specified timeout. - wait_for_trigger: - trigger: event event_type: ifttt_webhook_received event_data: action: connected_to_network timeout: minutes: "{{ timeout_minutes }}" continue_on_timeout: false Without `continue_on_timeout: false` the script will always continue since the default for `continue_on_timeout` is `true`. ### Wait variable[](https://www.home-assistant.io/docs/scripts/#wait-variable) 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` | `true` if the condition was met, `false` otherwise | | `wait.remaining` | Timeout remaining, or `none` if a timeout was not specified | | `wait.trigger` | Exists only after `wait_for_trigger`. Contains information about which trigger fired. (See [Available-Trigger-Data](https://www.home-assistant.io/docs/automation/templating/#available-trigger-data)
.) Will be `none` if no trigger happened before timeout expired | 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. # Take different actions depending on if condition was met. - wait_template: "{{ is_state('binary_sensor.door', 'on') }}" timeout: 10 - if: - "{{ not wait.completed }}" then: - action: script.door_did_not_open else: - action: script.turn_on target: entity_id: - script.door_did_open - script.play_fanfare # Wait a total of 10 seconds. - wait_template: "{{ is_state('binary_sensor.door_1', 'on') }}" timeout: 10 continue_on_timeout: false - action: switch.turn_on target: entity_id: switch.some_light - wait_for_trigger: - trigger: state entity_id: binary_sensor.door_2 to: "on" for: 2 timeout: "{{ wait.remaining }}" continue_on_timeout: false - action: switch.turn_off target: entity_id: switch.some_light Fire an event[](https://www.home-assistant.io/docs/scripts/#fire-an-event) --------------------------------------------------------------------------- This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows you to fire an event. Events can be used for many things. It could trigger an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) or indicate to another integration that something is happening. For instance, in the below example it is used to create an entry in the **Activity** panel. - alias: "Fire LOGBOOK_ENTRY event" event: LOGBOOK_ENTRY event_data: name: Paulus message: is waking up entity_id: device_tracker.paulus domain: light You can also use event\_data to fire an event with custom data. This could be used to pass data to another script awaiting an event trigger. The `event_data` accepts templates. - event: MY_EVENT event_data: name: myEvent customData: "{{ myCustomVariable }}" ### Raise and Consume Custom Events[](https://www.home-assistant.io/docs/scripts/#raise-and-consume-custom-events) The following automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) example shows how to raise a custom event called `event_light_state_changed` with `entity_id` as the event data. The actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) part could be inside a script or an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) . - alias: "Fire Event" triggers: - trigger: state entity_id: switch.kitchen to: "on" actions: - event: event_light_state_changed event_data: state: "on" The following automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) example shows how to capture the custom event `event_light_state_changed` with an [Event Automation Trigger](https://www.home-assistant.io/docs/automation/trigger#event-trigger) , and retrieve corresponding `entity_id` that was passed as the event trigger data, see [Available-Trigger-Data](https://www.home-assistant.io/docs/automation/templating/#available-trigger-data) for more details. - alias: "Capture Event" triggers: - trigger: event event_type: event_light_state_changed actions: - action: notify.notify data: message: "kitchen light is turned {{ trigger.event.data.state }}" Repeat a group of actions[](https://www.home-assistant.io/docs/scripts/#repeat-a-group-of-actions) --------------------------------------------------------------------------------------------------- This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows you to repeat a sequence of other actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . Nesting is fully supported. There are three ways to control how many times the sequence will be run. ### Counted repeat[](https://www.home-assistant.io/docs/scripts/#counted-repeat) This form accepts a count value. The value may be specified by a template, in which case the template is rendered when the repeat step is reached. script: flash_light: mode: restart sequence: - action: light.turn_on target: entity_id: "light.{{ light }}" - alias: "Cycle light 'count' times" repeat: count: "{{ count|int * 2 - 1 }}" sequence: - delay: 2 - action: light.toggle target: entity_id: "light.{{ light }}" flash_hallway_light: sequence: - alias: "Flash hallway light 3 times" action: script.flash_light data: light: hallway count: 3 ### For each[](https://www.home-assistant.io/docs/scripts/#for-each) This repeat form accepts a list of items to iterate over. The list of items can be a pre-defined list, or a list created by a template. The sequence is ran for each item in the list, and current item in the iteration is available as `repeat.item`. The following example will turn a list of lights: repeat: for_each: - "living_room" - "kitchen" - "office" sequence: - action: light.turn_off target: entity_id: "light.{{ repeat.item }}" Other types are accepted as list items, for example, each item can be a template, or even an mapping of key/value pairs. repeat: for_each: - language: English message: Hello World - language: Dutch message: Hallo Wereld sequence: - action: notify.phone data: title: "Message in {{ repeat.item.language }}" message: "{{ repeat.item.message }}!" ### While loop[](https://www.home-assistant.io/docs/scripts/#while-loop) This form accepts a list of conditions (see [conditions page](https://www.home-assistant.io/docs/scripts/conditions/) for available options) that are evaluated _before_ each time the sequence is run. The sequence will be run _as long as_ the condition(s) evaluate to true. script: do_something: sequence: - action: script.get_ready_for_something - alias: "Repeat the sequence AS LONG AS the conditions are true" repeat: while: - condition: state entity_id: input_boolean.do_something state: "on" # Don't do it too many times - condition: template value_template: "{{ repeat.index <= 20 }}" sequence: - action: script.something The `while` also accepts a [shorthand notation of a template condition](https://www.home-assistant.io/docs/scripts/conditions/#template-condition-shorthand-notation) . For example: - repeat: while: "{{ is_state('sensor.mode', 'Home') and repeat.index < 10 }}" sequence: - ... ### Repeat until[](https://www.home-assistant.io/docs/scripts/#repeat-until) This form accepts a list of conditions that are evaluated _after_ each time the sequence is run. Therefore the sequence will always run at least once. The sequence will be run _until_ the condition(s) evaluate to true. automation: - triggers: - trigger: state entity_id: binary_sensor.xyz to: "on" conditions: - condition: state entity_id: binary_sensor.something state: "off" actions: - alias: "Repeat the sequence UNTIL the conditions are true" repeat: sequence: # Run command that for some reason doesn't always work - action: shell_command.turn_something_on # Give it time to complete - delay: milliseconds: 200 until: # Did it work? - condition: state entity_id: binary_sensor.something state: "on" `until` also accepts a [shorthand notation of a template condition](https://www.home-assistant.io/docs/scripts/conditions/#template-condition-shorthand-notation) . For example: - repeat: until: "{{ is_state('device_tracker.iphone', 'home') }}" sequence: - ... ### Repeat loop variable[](https://www.home-assistant.io/docs/scripts/#repeat-loop-variable) A variable named `repeat` is defined within the repeat actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/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 | If-then[](https://www.home-assistant.io/docs/scripts/#if-then) --------------------------------------------------------------- This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows you to conditionally (`if`), based on or more [conditions](https://www.home-assistant.io/docs/scripts/conditions/) (which are `and` combined), run a sequence of actions (`then`) and optionally supports running other sequence when the condition didn’t pass (`else`). script: - if: - alias: "If no one is home" condition: state entity_id: zone.home state: 0 then: - alias: "Then start cleaning already!" action: vacuum.start target: area_id: living_room # The `else` is fully optional and can be omitted else: - action: notify.notify data: message: "Skipped cleaning, someone is home!" This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) supports nesting, however, if you find yourself using nested if-then actions in the `else` part, you may want to consider using [choose](https://www.home-assistant.io/docs/scripts/#choose-a-group-of-actions) instead. Choose a group of actions[](https://www.home-assistant.io/docs/scripts/#choose-a-group-of-actions) --------------------------------------------------------------------------------------------------- This actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows you to select a sequence of other actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) from a list of sequences. Nesting is fully supported. Each sequence is paired with a list of conditions. (See the [conditions page](https://www.home-assistant.io/docs/scripts/conditions/) for available options and how multiple conditions are handled.) The first sequence whose conditions are all true will be run. An _optional_ `default` sequence can be included which will be run only if none of the sequences from the list are run. An _optional_ `alias` can be added to each of the sequences, excluding the `default` sequence. The `choose` actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) can be used like an “if/then/elseif/then…/else” statement. The first `conditions`/`sequence` pair is like the “if/then”, and can be used just by itself. Or additional pairs can be added, each of which is like an “elif/then”. And lastly, a `default` can be added, which would be like the “else.” # Example with "if", "elif" and "else" automation: - triggers: - trigger: state entity_id: input_boolean.simulate to: "on" mode: restart actions: - choose: # IF morning - conditions: - condition: template value_template: "{{ now().hour < 9 }}" sequence: - action: script.sim_morning # ELIF day - conditions: - condition: template value_template: "{{ now().hour < 18 }}" sequence: - action: light.turn_off target: entity_id: light.living_room - action: script.sim_day # ELSE night default: - action: light.turn_off target: entity_id: light.kitchen - delay: minutes: "{{ range(1, 11)|random }}" - action: light.turn_off target: entity_id: all `conditions` also accepts a [shorthand notation of a template condition](https://www.home-assistant.io/docs/scripts/conditions/#template-condition-shorthand-notation) . For example: automation: - triggers: - trigger: state entity_id: input_select.home_mode actions: - choose: - conditions: > {{ trigger.to_state.state == 'Home' and is_state('binary_sensor.all_clear', 'on') }} sequence: - action: script.arrive_home data: ok: true - conditions: > {{ trigger.to_state.state == 'Home' and is_state('binary_sensor.all_clear', 'off') }} sequence: - action: script.turn_on target: entity_id: script.flash_lights - action: script.arrive_home data: ok: false - conditions: "{{ trigger.to_state.state == 'Away' }}" sequence: - action: script.left_home More `choose` can be used together. This is the case of an IF-IF. The following example shows how a single automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) can control entities that aren’t related to each other but have in common the same trigger. When the sun goes below the horizon, the `porch` and `garden` lights must turn on. If someone is watching the TV in the living room, there is a high chance that someone is in that room, therefore the living room lights have to turn on too. The same concept applies to the `studio` room. # Example with "if" and "if" automation: - alias: "Turn lights on when the sun gets dim and if some room is occupied" triggers: - trigger: numeric_state entity_id: sun.sun attribute: elevation below: 4 actions: # This must always apply - action: light.turn_on data: brightness: 255 color_temp: 366 target: entity_id: - light.porch - light.garden # IF a entity is ON - choose: - conditions: - condition: state entity_id: binary_sensor.livingroom_tv state: "on" sequence: - action: light.turn_on data: brightness: 255 color_temp: 366 target: entity_id: light.livingroom # IF another entity not related to the previous, is ON - choose: - conditions: - condition: state entity_id: binary_sensor.studio_pc state: "on" sequence: - action: light.turn_on data: brightness: 255 color_temp: 366 target: entity_id: light.studio Grouping actions[](https://www.home-assistant.io/docs/scripts/#grouping-actions) --------------------------------------------------------------------------------- The `sequence` actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows you to group multiple actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) together. Each action will be executed in order, meaning the next action will only be executed after the previous action has been completed. Grouping actions in a sequence can be useful when you want to be able to collapse related groups in the user interface for organizational purposes. Combined with the [`parallel`](https://www.home-assistant.io/docs/scripts/#parallelizing-actions) action, it can also be used to run multiple groups of actions in a sequence in parallel. In the example below, two separate groups of actions are executed in sequence, one for turning on devices, the other for sending notifications. Each group of actions is executed in order, this includes the actions in each group and the groups themselves. In total, four actions are executed, one after the other. automation: - triggers: - trigger: state entity_id: binary_sensor.motion to: "on" actions: - alias: "Turn on devices" sequence: - action: light.turn_on target: entity_id: light.ceiling - action: siren.turn_on target: entity_id: siren.noise_maker - alias: "Send notifications" sequence: - action: notify.person1 data: message: "The motion sensor was triggered!" - action: notify.person2 data: message: "Oh oh, someone triggered the motion sensor..." Parallelizing actions[](https://www.home-assistant.io/docs/scripts/#parallelizing-actions) ------------------------------------------------------------------------------------------- By default, all sequences of actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) in Home Assistant run sequentially. This means the next actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) is started after the current action has been completed. This is not always needed, for example, if the sequence of actions doesn’t rely on each other and order doesn’t matter. For those cases, the `parallel` action can be used to run the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) in the sequence in parallel, meaning all the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) are started at the same time. The following example shows sending messages out at the same time (in parallel): automation: - triggers: - trigger: state entity_id: binary_sensor.motion to: "on" actions: - parallel: - action: notify.person1 data: message: "These messages are sent at the same time!" - action: notify.person2 data: message: "These messages are sent at the same time!" It is also possible to run a group of actions sequentially inside the parallel actions. The example below demonstrates that: script: example_script: sequence: - parallel: - sequence: - wait_for_trigger: - trigger: state entity_id: binary_sensor.motion to: "on" - action: notify.person1 data: message: "This message awaited the motion trigger" - action: notify.person2 data: message: "I am sent immediately and do not await the above action!" Warning Running actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) in parallel can be helpful in many cases, but use it with caution and only if you need it. There are some caveats (see below) when using parallel actions. While it sounds attractive to parallelize, most of the time, just the regular sequential actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) will work just fine. Some of the caveats of running actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) in parallel: * There is no order guarantee. The actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) will be started in parallel, but there is no guarantee that they will be completed in the same order. * If one actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) fails or errors, the other actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) will keep running until they too have finished or errored. * Variables created/modified in one parallelized actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) can conflict with variables from another parallelized actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . Make sure to give them distinct names to prevent that. Stopping a script sequence[](https://www.home-assistant.io/docs/scripts/#stopping-a-script-sequence) ----------------------------------------------------------------------------------------------------- It is possible to halt a script sequence at any point and return script responses using the `stop` actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . The `stop` actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) takes a text as input explaining the reason for halting the sequence. This text will be logged and shows up in the automationsAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) and script traces. `stop` can be useful to halt a script halfway through a sequence when, for example, a condition is not met. - stop: "Stop running the rest of the sequence" To return a response from a script, use the `response_variable` option. This option expects the name of the variable that contains the data to return. The response data must contains a mapping of key/value pairs. - stop: "Stop running the rest of the sequence" response_variable: "my_response_variable" There is also an `error` option, to indicate we are stopping because of an unexpected error. It stops the sequence as well, but marks the automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) or script as failed to run. - stop: "Well, that was unexpected!" error: true Continuing on error[](https://www.home-assistant.io/docs/scripts/#continuing-on-error) --------------------------------------------------------------------------------------- By default, a sequence of actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) will be halted when one of the actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) in that sequence encounters an error. The automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) or script will be halted, an error is logged, and the automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) or script run is marked as errored. 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 actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . The `continue_on_error` is available on all actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) and is set to `false`. You can set it to `true` if you’d like to continue the actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) sequence, regardless of whether that actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) encounters an error. The example below shows the `continue_on_error` set on the first actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . If it encounters an error; it will continue to the next actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . - alias: "If this one fails..." continue_on_error: true action: notify.super_unreliable_service_provider data: message: "I'm going to error out..." - alias: "This one will still run!" action: persistent_notification.create data: title: "Hi there!" message: "I'm fine..." Please note that `continue_on_error` will not suppress/ignore misconfiguration or errors that Home Assistant does not handle. Disabling an action[](https://www.home-assistant.io/docs/scripts/#disabling-an-action) --------------------------------------------------------------------------------------- Every individual actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) in a sequence can be disabled, without removing it. To do so, add `enabled: false` to the actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) . For example: # Example script with a disabled action script: example_script: sequence: # This action will not run, as it is disabled. # The message will not be sent. - enabled: false alias: "Notify that the ceiling light is being turned on" 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" action: light.turn_on target: entity_id: light.ceiling Actions can also be disabled based on limited templates or blueprint inputs. blueprint: input: input_boolean: name: Boolean selector: boolean: actions: - delay: 0:35 enabled: !input input_boolean Respond to a conversation[](https://www.home-assistant.io/docs/scripts/#respond-to-a-conversation) --------------------------------------------------------------------------------------------------- The `set_conversation_response` script actionActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. [\[Learn more\]](https://www.home-assistant.io/docs/automation/action/) allows returning a custom response when an automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) is triggered by a conversation engine, for example a voice assistant. The conversation response can be templated. # Example of a templated conversation response resulting in "Testing 123" - variables: my_var: "123" - set_conversation_response: "{{ 'Testing ' ~ my_var }}" The response is handed to the conversation engine when the automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) finishes. If the `set_conversation_response` is executed multiple times, the most recent response will be handed to the conversation engine. To clear the response, set it to `None`: # Example of a clearing a conversation response set_conversation_response: ~ If the automationAutomations in Home Assistant allow you to automatically respond to things that happen in and around your home. [\[Learn more\]](https://www.home-assistant.io/docs/automation/) was not triggered by a conversation engine, the response will not be used by anything. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/scripts/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/scripts.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fscripts%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fscripts%2F%22&in=body "View given feedback for this page") --- # Glossary - Home Assistant The glossary covers terms which are used around Home Assistant. A[](https://www.home-assistant.io/docs/glossary/#a) ---------------------------------------------------- * * * ### Action[](https://www.home-assistant.io/docs/glossary/#action) Actions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called _sequence_. An action is a **software function that interacts with targets to make something happen**. Actions can use other actions and/or scenes to interact with entities and cause these entities to do something. Actions can also include conditions and a delay. An action can perform multiple actions at the same time. For example, if your presence is detected in a room, an action may perform one action to turn on a light and perform another action to start playing music after a delay. Actions are also used on the dashboard, for example as tap or hold action on a UI element. When triggered, the action performs another action. Home Assistant provides a series of predefined actions, such as `homeassistant.turn_on`, `homeassistant.toggle`, or `homeassistant.reload`. [Read more about _Action_](https://www.home-assistant.io/docs/automation/action/) ### Actor[](https://www.home-assistant.io/docs/glossary/#actor) An entity that receives a control signal and performs an action in a system. ### Add-on[](https://www.home-assistant.io/docs/glossary/#add-on) Add-ons are additional standalone third-party software packages that can be installed on Home Assistant OS. Most of these, add-on provided, applications can be integrated into Home Assistant using integrations. Examples of add-ons are: an MQTT broker, database service or a file server. [Read more about _Add-on_](https://www.home-assistant.io/getting-started/concepts-terminology/#add-ons) ### Area[](https://www.home-assistant.io/docs/glossary/#area) An area in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of devices and entities that are meant to match areas (or rooms) in the physical world: your home. For example, the `living room` area groups devices and entities in your living room. Areas allow you to target actions at an entire group of devices. For example, turning off all the lights in the living room. Locations within your home such as living room, dance floor, etc. Areas can be assigned to floors. Areas can also be used for automatically generated cards, such as the [Area card](https://www.home-assistant.io/dashboards/area/) . [Read more about _Area_](https://www.home-assistant.io/docs/organizing/areas/) ### Automation[](https://www.home-assistant.io/docs/glossary/#automation) Automations connect one or more triggers to one or more actions in a ‘when trigger then do action’ fashion with additional optional conditions. For example, an automation might connect the trigger ‘sunset’ to the action ‘turn the lights on’ but only if the condition ‘someone is home’ is met. Pre-made automations for common use-cases are available via [the blueprints feature](https://www.home-assistant.io/docs/automation/using_blueprints/) . [Read more about _Automation_](https://www.home-assistant.io/docs/automation/) B[](https://www.home-assistant.io/docs/glossary/#b) ---------------------------------------------------- * * * ### Backup[](https://www.home-assistant.io/docs/glossary/#backup) Home Assistant has built-in functionality to create files containing a copy of your configuration. This can be used to restore your Home Assistant as well as migrate to a new system. The backup feature is available for all [installation types](https://www.home-assistant.io/installation/#about-installation-types) . [Read more about _Backup_](https://www.home-assistant.io/common-tasks/general/#backups) ### Binary sensor[](https://www.home-assistant.io/docs/glossary/#binary-sensor) A binary sensor returns information about things that only have two states - such as on or off. [Read more about _Binary sensor_](https://www.home-assistant.io/integrations/binary_sensor) ### Blueprint[](https://www.home-assistant.io/docs/glossary/#blueprint) A blueprint is a [script](https://www.home-assistant.io/getting-started/concepts-terminology/#scripts) , [automation](https://www.home-assistant.io/getting-started/concepts-terminology/#automation) , or [template](https://www.home-assistant.io/integrations/template/) entity configuration with certain parts marked as configurable. This allows users to create multiple scripts, automations or template entities based on the same blueprint, with each having its own configuration-specific settings. Blueprints are shared by the community on the [blueprints exchange](https://community.home-assistant.io/c/53) in the forum. [Read more about _Blueprint_](https://www.home-assistant.io/docs/blueprint/) ### Button[](https://www.home-assistant.io/docs/glossary/#button) A button entity can fire an event, or trigger an action towards a device or service. It can be compared to a physical push button. The button entity does not have a state like `on` or `off`, but keeps the timestamp of when it was last pressed in the Home Assistant UI or via an action. [Read more about _Button_](https://www.home-assistant.io/integrations/button) C[](https://www.home-assistant.io/docs/glossary/#c) ---------------------------------------------------- * * * ### Category[](https://www.home-assistant.io/docs/glossary/#category) A category is an organization tool that allows [grouping](https://www.home-assistant.io/docs/organizing/) 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. Categories are unique for each table. The automations page can have different categories than the scene, scripts, or helpers settings page. [Read more about _Category_](https://www.home-assistant.io/docs/organizing/categories/) ### Climate[](https://www.home-assistant.io/docs/glossary/#climate) The Climate entity allows you to control and monitor HVAC (heating, ventilating, and air conditioning) devices and thermostats. [Read more about _Climate_](https://www.home-assistant.io/integrations/climate) ### Commissioning[](https://www.home-assistant.io/docs/glossary/#commissioning) In the context of Matter devices, _commissioning_ is the process of adding a device to a Matter controller. It is the equivalent of pairing a device in Zigbee or Z-Wave. Commissioning is done by scanning a QR code or entering a code manually. The code is printed on the device or its packaging. The code contains information about the device, such as its type, manufacturer, and serial number. The controller uses this information to identify the device and to download the required information to control the device. For example, the controller downloads the device’s capabilities, such as the supported commands and the available attributes. The controller also downloads the device’s configuration, such as the device’s name and location. [Read more about _Commissioning_](https://www.home-assistant.io/integrations/matter/) ### Component[](https://www.home-assistant.io/docs/glossary/#component) Better known as: Integrations. Integrations used to be known as components. ### Condition[](https://www.home-assistant.io/docs/glossary/#condition) Conditions are an optional part of an automation that will prevent an action from firing if they are not met. [Read more about _Condition_](https://www.home-assistant.io/docs/scripts/conditions/) ### Configuration file[](https://www.home-assistant.io/docs/glossary/#configuration-file) The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Read more about _Configuration file_](https://www.home-assistant.io/docs/configuration/) ### Cover[](https://www.home-assistant.io/docs/glossary/#cover) Covers are devices such as blinds, garage doors, etc that can be opened and closed and optionally set to a specific position. [Read more about _Cover_](https://www.home-assistant.io/integrations/cover) ### Custom integration[](https://www.home-assistant.io/docs/glossary/#custom-integration) A custom integration is an integration that has been created by someone from the Home Assistant community and has been published for others to use at their own risk. Custom integrations are not supported by the Home Assistant project. They are not reviewed or tested by the Home Assistant development team and thus may negatively impact the stability of your Home Assistant instance. An example of a custom integration is the [Spook](https://spook.boo/) integration. ### Customize[](https://www.home-assistant.io/docs/glossary/#customize) Customization allows you to overwrite the default parameters of your devices in the configuration. D[](https://www.home-assistant.io/docs/glossary/#d) ---------------------------------------------------- * * * ### Device[](https://www.home-assistant.io/docs/glossary/#device) A device is a model representing a physical or logical unit that contains entities. **Example for a device as a physical unit** A smart plug named ‘Coffee machine’ which provides 2 entities: a `switch` entity to turn power on or off (‘Coffee machine power switch’) and a `sensor` entity for power monitoring (‘Coffee machine power sensor’). **Example for a device as a logical unit** An ecobee thermostat with 4 room sensors. This thermostat is seen as 5 devices in Home Assistant: 1 device for the thermostat with 4 sensors, and 1 device for each room sensor. Each device can be in a different area and may have more than one input or output within that area. Devices have properties such as ID, manufacturer, name, model, hardware version, firmware version, connections, etc. ### Device tracker[](https://www.home-assistant.io/docs/glossary/#device-tracker) Device trackers are used to track the presence, or location, of a device. [Read more about _Device tracker_](https://www.home-assistant.io/integrations/device_tracker) ### Diagnostics[](https://www.home-assistant.io/docs/glossary/#diagnostics) The diagnostics integration provides a way to download diagnostic data from a device or integration for sharing in issue reports. Sharing diagnostics data when reporting an issue allows developers to diagnose and fix your reported problem quicker. [Read more about _Diagnostics_](https://www.home-assistant.io/integrations/diagnostics) ### Discovery[](https://www.home-assistant.io/docs/glossary/#discovery) Discovery is the automatic setup of zeroconf/mDNS and uPnP devices after they are discovered. ### Domain[](https://www.home-assistant.io/docs/glossary/#domain) Each integration in Home Assistant has a unique identifier: a domain. All of the 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.kitchen` is an entity in the `light` domain from the [light integration](https://www.home-assistant.io/integrations/light) , while `hue.activate_scene` is the `activate_scene` action for the `hue` domain which belongs to the [Hue integration](https://www.home-assistant.io/integrations/hue) . E[](https://www.home-assistant.io/docs/glossary/#e) ---------------------------------------------------- * * * ### Entity[](https://www.home-assistant.io/docs/glossary/#entity) An entity represents a 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 device or a service. Entities have states. **Example for entities as part of a device** A combined temperature and humidity sensor device provides two sensor entities. One for temperature (e.g. `sensor.temperature` with state `21.0` and unit `°C`) and one for humidity (e.g. `sensor.humidity` with state `65.4` and unit `%`). **Example for entities as part of a service** A weather service that provides 3 entities: wind speed, air pressure, and ozon level. **Example of an entity used for control** A fan that is turned on when the temperature exceeds 30 °C. There are standardized types of entities for common integrations such as light, switch, camera, sensor, fan, or vacuum. Some entities are not part of a device or service. Examples of standalone entities are automation, script, scene entities, and helper entities (e.g. input helpers). Most properties of entities are related to the state. Entities have optional attributes such as friendly name, unit of measurement, and an icon or picture that can be displayed in the frontend. [Read more about _Entity_](https://www.home-assistant.io/docs/configuration/entities_domains/) ### Event[](https://www.home-assistant.io/docs/glossary/#event) Every time something happens in Home Assistant, an event is fired. There are different types of events, such as state change events, when an action was triggered, or the time changed. All entities produce state change events. Every time a state changes, a state change event is produced. Events can be used to trigger automations or scripts. For example, you can trigger an automation when a light is turned on, then a speaker turns on in that room. Events can also be used to trigger actions in the frontend. For example, you can trigger an action when a button is pressed. [Read more about _Event_](https://www.home-assistant.io/docs/configuration/events/) ### Event entity[](https://www.home-assistant.io/docs/glossary/#event-entity) Events are signals that are emitted when something happens, for example, when a user presses a physical button like a doorbell or when a button on a remote control is pressed. [Read more about _Event entity_](https://www.home-assistant.io/integrations/event) F[](https://www.home-assistant.io/docs/glossary/#f) ---------------------------------------------------- * * * ### Floor[](https://www.home-assistant.io/docs/glossary/#floor) A floor in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of areas that are meant to match the physical floors in your home. Devices & entities are not assigned to floors but to areas. A floor has properties such as: Floor ID, name, aliases (for use in assistants), an icon, and a floor level. Some of these properties are optional. The level number can be negative to reflect floors below the basement. 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. [Read more about _Floor_](https://www.home-assistant.io/docs/organizing/floors/) ### Frontend[](https://www.home-assistant.io/docs/glossary/#frontend) The frontend is a necessary component for the UI, it is also where you can define your themes. [Read more about _Frontend_](https://www.home-assistant.io/integrations/frontend/) G[](https://www.home-assistant.io/docs/glossary/#g) ---------------------------------------------------- * * * ### Group[](https://www.home-assistant.io/docs/glossary/#group) Groups are a way to organize your entities into a single unit. [Read more about _Group_](https://www.home-assistant.io/integrations/group/) H[](https://www.home-assistant.io/docs/glossary/#h) ---------------------------------------------------- * * * ### HASS[](https://www.home-assistant.io/docs/glossary/#hass) HASS is an abbreviation for Home Assistant that was commonly used in the past. This abbreviation is no longer actively used. It is recommended to use the full name “Home Assistant” instead of abbreviations. ### HassOS[](https://www.home-assistant.io/docs/glossary/#hassos) Another name for Home Assistant Operating System [Read more about _HassOS_](https://www.home-assistant.io/hassio/installation/) ### Home Assistant Container[](https://www.home-assistant.io/docs/glossary/#home-assistant-container) Home Assistant Container is a standalone container-based installation of Home Assistant Core. Any [OCI](https://opencontainers.org/) compatible runtime can be used, but the documentation focus is on Docker. [Read more about _Home Assistant Container_](https://www.home-assistant.io/installation/#about-installation-types) ### Home Assistant Core[](https://www.home-assistant.io/docs/glossary/#home-assistant-core) Home Assistant Core is the Python program at the heart of Home Assistant. It is part of all installation types. It can be installed standalone (without Home Assistant Supervisor) as a container using Docker (this is typically referred to as the Home Assistant Container installation type). For development, Core can also be run using a Virtual Environment (previously referred as the Home Assistant Core installation type. For production setup, the [Home Assistant Core installation type is deprecated](https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems/) . ### Home Assistant Operating System[](https://www.home-assistant.io/docs/glossary/#home-assistant-operating-system) Home Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users. ### Home Assistant Supervised[](https://www.home-assistant.io/docs/glossary/#home-assistant-supervised) The Home Assistant Supervised installation type is a full UI managed home automation ecosystem that runs the Home Assistant Core program, the Home Assistant Supervisor and add-ons. It comes pre-installed on Home Assistant OS, but can be installed standalone on Debian Linux systems. It leverages Docker, which is managed by the Home Assistant Supervisor. The [Home Assistant Supervised installation type is deprecated](https://www.home-assistant.io/blog/2025/05/22/deprecating-core-and-supervised-installation-methods-and-32-bit-systems/) . ### Home Assistant Supervisor[](https://www.home-assistant.io/docs/glossary/#home-assistant-supervisor) The Home Assistant Supervisor is a program that manages a Home Assistant installation, taking care of installing and updating Home Assistant, add-ons, itself, and, if used, updating the Home Assistant Operating System. ### Host[](https://www.home-assistant.io/docs/glossary/#host) A device that can communicate with other devices on a network. During setup and configuration, an input requesting a **Host** typically refers to a device’s network address so that Home Assistant can attempt to connect to it. This may be in the form of a hostname, URL, IP address or some other type of network identifier. If you do not know the hostname or IP address of a device, you can find it in your router’s webinterface. For example, if your device is connected wirelessly, somewhere there is a page listing all the devices that are connected to your network. It depends on your router, where exactly this page is. It could be under **Network** > **Wireless**. [Read more about _Host_](https://en.wikipedia.org/wiki/Host_(network)) I[](https://www.home-assistant.io/docs/glossary/#i) ---------------------------------------------------- * * * ### Image[](https://www.home-assistant.io/docs/glossary/#image) The Image integration allows other integrations to display a static image. [Read more about _Image_](https://www.home-assistant.io/integrations/image) ### Integration[](https://www.home-assistant.io/docs/glossary/#integration) Integrations connect and integrate Home Assistant with devices, services, and more. They contain all the logic to handle vendor- and device-specific implementations, such as authentication or specific protocols. The integration brings such device-specific elements into Home Assistant in a standardized way. For example, the [Hue](https://www.home-assistant.io/integrations/hue) integration integrates the Philips Hue bridge and its connected bulbs into Home Assistant, making them available as Home Assistant light entities you can control. [Read more about _Integration_](https://www.home-assistant.io/getting-started/concepts-terminology/#integrations) ### Intent[](https://www.home-assistant.io/docs/glossary/#intent) Intent is a term used with voice assistants. The intent is what Home Assistant thinks you want it to do when it extracts a command from your voice or text utterance. Currently, the following intents are supported out of the box: HassTurnOn, HassTurnOff, HassGetState, and HassLightSet. These intents allow you to turn things on or off, inquire about a state, or change the brightness or color of a light. [Read more about _Intent_](https://developers.home-assistant.io/docs/intent_builtin) L[](https://www.home-assistant.io/docs/glossary/#l) ---------------------------------------------------- * * * ### Label[](https://www.home-assistant.io/docs/glossary/#label) Labels in Home Assistant allow [grouping](https://www.home-assistant.io/docs/organizing/) 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. [Read more about _Label_](https://www.home-assistant.io/docs/organizing/labels/) ### Light[](https://www.home-assistant.io/docs/glossary/#light) A light has a brightness you can control, and optionally color temperature or RGB color control. [Read more about _Light_](https://www.home-assistant.io/integrations/light) ### Long-term statistics[](https://www.home-assistant.io/docs/glossary/#long-term-statistics) Home Assistant saves long-term statistics for a sensor if the entity has a state\_class of measurement, total, or total\_increasing. For short-term statistics, a snapshot is taken every 5 minutes. For long-term statistics, an hourly aggregate is stored of the short-term statistics. Short-term statistics are automatically purged after a predefined period (default is 10 days). Long-term statistics are never purged. [Read more about _Long-term statistics_](https://www.home-assistant.io/blog/2021/08/04/release-20218/#long-term-statistics) ### Lovelace[](https://www.home-assistant.io/docs/glossary/#lovelace) Lovelace is the original code name of the UI that is now known as [Home Assistant dashboards](https://www.home-assistant.io/dashboards) . M[](https://www.home-assistant.io/docs/glossary/#m) ---------------------------------------------------- * * * ### Matter[](https://www.home-assistant.io/docs/glossary/#matter) Matter is an open-source standard that defines how to control smart home devices on a Wi-Fi or Thread network. The aim of the standard is to improve security and to make devices interoperable across vendors, replacing proprietary protocols for smart home ecosystems. Unlike other standards, Matter allows joining the same device to multiple controllers. For example, you can add a light to Google Home, Apple Home, and Home Assistant at the same time. A bridge device can be used to connect devices running on other smart home technologies such as Zigbee or Z-Wave. [Read more about _Matter_](https://www.home-assistant.io/integrations/matter) N[](https://www.home-assistant.io/docs/glossary/#n) ---------------------------------------------------- * * * ### Notification[](https://www.home-assistant.io/docs/glossary/#notification) You can use notifications to send messages, pictures, and more, to devices. [Read more about _Notification_](https://www.home-assistant.io/integrations/#notifications) P[](https://www.home-assistant.io/docs/glossary/#p) ---------------------------------------------------- * * * ### Package[](https://www.home-assistant.io/docs/glossary/#package) Packages allow you to bundle different component configurations together. [Read more about _Package_](https://www.home-assistant.io/docs/configuration/packages/) ### Platform[](https://www.home-assistant.io/docs/glossary/#platform) Platforms are building blocks provided by some integrations to be used by other integrations. For example, the [Light](https://www.home-assistant.io/integrations/light) integration provides the `light platform` that is utilized by all integrations providing `light` entities such as e.g. [Hue](https://www.home-assistant.io/integrations/hue) . [Read more about _Platform_](https://www.home-assistant.io/docs/configuration/platform_options/) ### Polling[](https://www.home-assistant.io/docs/glossary/#polling) Data polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Read more about _Polling_](https://www.home-assistant.io/common-tasks/general/#defining-a-custom-polling-interval) R[](https://www.home-assistant.io/docs/glossary/#r) ---------------------------------------------------- * * * ### Reload[](https://www.home-assistant.io/docs/glossary/#reload) Applies the changes made to the Home Assistant configuration files. Changes are normally automatically updated. However, changes made outside of the front end will not be reflected in Home Assistant and require a reload. To perform a manual reload, go to **Settings** > **System** > **Restart Home Assistant** (top right) > **Quick reload**. If you do not see the **Quick reload** option in the menu, you need to enable **Advanced mode** in your user settings. More granular reload options are available in _YAML configuration reloading_ section in **Developer tools** > **YAML**. S[](https://www.home-assistant.io/docs/glossary/#s) ---------------------------------------------------- * * * ### Scene[](https://www.home-assistant.io/docs/glossary/#scene) Scenes capture the states you want certain entities to be. For example, a scene can specify that light A should be turned on and light B should be bright red. [Read more about _Scene_](https://www.home-assistant.io/integrations/scene/) ### Script[](https://www.home-assistant.io/docs/glossary/#script) Scripts are components that allow users to specify a sequence of actions to be executed by Home Assistant when turned on. [Read more about _Script_](https://www.home-assistant.io/docs/scripts/) ### Selector[](https://www.home-assistant.io/docs/glossary/#selector) Selectors are components for the user interface. Some selectors can, for example, show a toggle button to turn something on or off, while another select can filter a list of devices to show only devices that have motion-sensing capabilities. [Read more about _Selector_](https://www.home-assistant.io/docs/blueprint/selectors/) ### Sensor[](https://www.home-assistant.io/docs/glossary/#sensor) Sensors return information about a thing, for instance the level of water in a tank. [Read more about _Sensor_](https://www.home-assistant.io/integrations/sensor/) ### Service[](https://www.home-assistant.io/docs/glossary/#service) The term “service” in Home Assistant is used in the sense of an **information service**. For example, the municipal waste management service that provides entities for organic, paper, and packaging waste. In terms of functionality, the information service is like a device. It is called _service_ to avoid confusion, as it does not come with a piece of hardware. ### State[](https://www.home-assistant.io/docs/glossary/#state) The 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. Entities store 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. However, entities can store attributes related to that state. For example, the state of a light is _on_, and the related state attributes could be its current brightness and color values. State change events can be used as triggers. The current state can be used in conditions. [Read more about _State_](https://www.home-assistant.io/docs/configuration/state_object/) ### Switch[](https://www.home-assistant.io/docs/glossary/#switch) Switches are things that have two states you can select between, such as turning on or off a socket. [Read more about _Switch_](https://www.home-assistant.io/integrations/switch/) T[](https://www.home-assistant.io/docs/glossary/#t) ---------------------------------------------------- * * * ### TTS[](https://www.home-assistant.io/docs/glossary/#tts) TTS (text-to-speech) allows Home Assistant to talk to you. [Read more about _TTS_](https://www.home-assistant.io/integrations/tts/) ### Template[](https://www.home-assistant.io/docs/glossary/#template) A template is an automation definition that can include variables for the action or data from the trigger values. This allows automations to generate dynamic actions. [Read more about _Template_](https://www.home-assistant.io/docs/automation/templating/) ### Thread[](https://www.home-assistant.io/docs/glossary/#thread) Thread is a low-power mesh networking standard that is specifically designed for smart home applications. It is a protocol that defines how devices communicate. _Mesh_ topology means that the devices can communicate with each other directly, without going through a central controller first. Thread uses the same radio frequency (RF) technology as Zigbee, but provides IP connectivity similar to Wi-Fi. Unlike Zigbee, Thread does not specify how to control devices. How Thread-enabled devices are controlled is specified in a higher level protocol such as HomeKit or Matter. [Read more about _Thread_](https://www.home-assistant.io/integrations/thread/) ### Thread border router[](https://www.home-assistant.io/docs/glossary/#thread-border-router) A Thread border router forwards data packets between your local network and the Thread network. This enables smart home devices within a Thread network to communicate with IPv6-capable devices in your local network. A Thread border router is connected to your network either via Wi-Fi or Ethernet and uses its radio frequency (RF) radio to communicate with the Thread mesh network. In case of Matter, the data that is forwarded is encrypted. Examples of Thread border routers are the Nest Hub (2nd gen), the HomePod mini, and the Home Assistant Connect ZBT-2 together with the OpenThread Border Router add-on. [Read more about _Thread border router_](https://www.home-assistant.io/integrations/thread/#about-thread-border-routers) ### Trigger[](https://www.home-assistant.io/docs/glossary/#trigger) A trigger is a set of values or conditions of a platform that are defined to cause an automation to run. [Read more about _Trigger_](https://www.home-assistant.io/docs/automation/trigger/) U[](https://www.home-assistant.io/docs/glossary/#u) ---------------------------------------------------- * * * ### Update[](https://www.home-assistant.io/docs/glossary/#update) An update entity is an entity that indicates if an update is available for a device or service. This can be any update, be it a firmware update for a device like a light bulb or router, or a software update for an add-on or a container. [Read more about _Update_](https://www.home-assistant.io/integrations/update) V[](https://www.home-assistant.io/docs/glossary/#v) ---------------------------------------------------- * * * ### Valve[](https://www.home-assistant.io/docs/glossary/#valve) Valves are devices to control the flow of liquids and gases. All valves in Home Assistant can be opened and closed. Some valves can also be set to a specific position. [Read more about _Valve_](https://www.home-assistant.io/integrations/valve) ### Variables[](https://www.home-assistant.io/docs/glossary/#variables) Variables are used to store values in memory that can be processed for example, in a script. [Read more about _Variables_](https://www.home-assistant.io/docs/scripts/#variables) Y[](https://www.home-assistant.io/docs/glossary/#y) ---------------------------------------------------- * * * ### YAML[](https://www.home-assistant.io/docs/glossary/#yaml) YAML is a human-readable data serialization language. It is used to store and transmit data in a structured format. In Home Assistant, YAML is used for configuration, for example in the `configuration.yaml` or `automations.yaml` files. [Read more about _YAML_](https://www.home-assistant.io/docs/configuration/yaml/) Z[](https://www.home-assistant.io/docs/glossary/#z) ---------------------------------------------------- * * * ### Zone[](https://www.home-assistant.io/docs/glossary/#zone) Zones allow you to specify certain regions on a map. They enable zone presence-detection and can be used in automations. For example, to start the vacuum after you left home or start the heating at home when you leave the office. [Read more about _Zone_](https://www.home-assistant.io/integrations/zone/) #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/glossary/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/glossary.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fglossary%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fglossary%2F%22&in=body "View given feedback for this page") --- # Templating - Home Assistant This is an advanced feature of Home Assistant. You’ll need a basic understanding of: * [Home Assistant architecture](https://www.home-assistant.io/developers/architecture/) , especially states. * The [State object](https://www.home-assistant.io/topics/state_object/) . Templating is a powerful feature that allows you to control information going into and out of the system. It is used for: * Formatting outgoing messages in, for example, the [notify](https://www.home-assistant.io/integrations/notify/) platforms and [Alexa](https://www.home-assistant.io/integrations/alexa/) integration. * Process incoming data from sources that provide raw data, like [MQTT](https://www.home-assistant.io/docs/configuration/templating/#using-templates-with-the-mqtt-integration) , [`rest` sensor](https://www.home-assistant.io/integrations/rest/) or the [`command_line` sensor](https://www.home-assistant.io/integrations/sensor.command_line/) . * [Automation Templating](https://www.home-assistant.io/docs/automation/templating/) . Building templates[](https://www.home-assistant.io/docs/configuration/templating/#building-templates) ------------------------------------------------------------------------------------------------------ Templating in Home Assistant is powered by the [Jinja2](https://palletsprojects.com/p/jinja) templating engine. This means that we are using their syntax and make some custom Home Assistant variables available to templates during rendering. Jinja2 supports a wide variety of operations: * [Mathematical operation](https://jinja.palletsprojects.com/en/latest/templates/#math) * [Comparisons](https://jinja.palletsprojects.com/en/latest/templates/#comparisons) * [Logic](https://jinja.palletsprojects.com/en/latest/templates/#logic) We will not go over the basics of the syntax, as Jinja2 does a great job of this in their [templates documentation](https://jinja.palletsprojects.com/en/latest/templates/) . The frontend has a [template editor tool](https://my.home-assistant.io/redirect/developer_template) to help develop and debug templates. Navigate to [Developer Tools > Template](https://my.home-assistant.io/redirect/developer_template) , create your template in the _Template editor_ and check the results on the right. Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates: script: msg_who_is_home: sequence: - action: notify.notify data: message: > {% if is_state('device_tracker.paulus', 'home') %} Ha, Paulus is home! {% else %} Paulus is at {{ states('device_tracker.paulus') }}. {% endif %} ### Important template rules[](https://www.home-assistant.io/docs/configuration/templating/#important-template-rules) There are a few very important rules to remember when adding templates to YAML: 1. You **must** surround single-line templates with double quotes (`"`) or single quotes (`'`). 2. It is advised that you prepare for undefined variables by using `if ... is not none` or the [`default` filter](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.default) , or both. 3. It is advised that when comparing numbers, you convert the number(s) to a [`float`](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.float) or an [`int`](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.int) by using the respective [filter](https://jinja.palletsprojects.com/en/latest/templates/#list-of-builtin-filters) . 4. While the [`float`](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.float) and [`int`](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.int) filters do allow a default fallback value if the conversion is unsuccessful, they do not provide the ability to catch undefined variables. Remembering these simple rules will help save you from many headaches and endless hours of frustration when using automation templates. ### Enabled Jinja extensions[](https://www.home-assistant.io/docs/configuration/templating/#enabled-jinja-extensions) Jinja supports a set of language extensions that add new functionality to the language. To improve the experience of writing Jinja templates, we have enabled the following extensions: * [Loop Controls](https://jinja.palletsprojects.com/en/stable/extensions/#loop-controls) (`break` and `continue`) * [Expression Statement](https://jinja.palletsprojects.com/en/stable/extensions/#expression-statement) (`do`) ### Reusing templates[](https://www.home-assistant.io/docs/configuration/templating/#reusing-templates) 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 [`homeassistant.reload_custom_templates`](https://my.home-assistant.io/redirect/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. For example, you might define a macro in a template in `config/custom_templates/formatter.jinja`: {% macro format_entity(entity_id) %} {{ state_attr(entity_id, 'friendly_name') }} - {{ states(entity_id) }} {% endmacro %} In your automations, you could then reuse this macro by importing it: {% from 'formatter.jinja' import format_entity %} {{ format_entity('sensor.temperature') }} Home Assistant also allows you to write macros with non-string return values by taking a named argument called `returns` and calling it with a return value. Once created, pass the macro into the `as_function` filter to use the returned value: {%- macro macro_is_switch(entity_name, returns) -%} {%- do returns(entity_name.startswith('switch.')) -%} {%- endmacro -%} {%- set is_switch = macro_is_switch | as_function -%} {{ "It's a switch!" if is_switch("switch.my_switch") else "Not a switch!" }} In this way, you can export utility functions that return scalar or complex values rather than just macros that render to strings. Home Assistant template extensions[](https://www.home-assistant.io/docs/configuration/templating/#home-assistant-template-extensions) -------------------------------------------------------------------------------------------------------------------------------------- Extensions allow templates to access all of the Home Assistant specific states and adds other convenience functions and filters. ### Limited templates[](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) Templates for some [triggers](https://www.home-assistant.io/docs/automation/trigger/) as well as `trigger_variables` only support a subset of the Home Assistant template extensions. This subset is referred to as “Limited Templates”. ### This[](https://www.home-assistant.io/docs/configuration/templating/#this) State-based and trigger-based template entities have the special template variable `this` available in their templates and actions. See more details and examples in the [Template integration documentation](https://www.home-assistant.io/integrations/template) . ### States[](https://www.home-assistant.io/docs/configuration/templating/#states) Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . * Iterating `states` will yield each state object. * Iterating `states.domain` will yield each state object of that domain. * `states.sensor.temperature` returns the state object for `sensor.temperature` (avoid when possible, see note below). * `states` can also be used as a function, `states(entity_id, rounded=False, with_unit=False)`, which returns the state string (not the state object) of the given entity, `unknown` if it doesn’t exist, and `unavailable` if the object exists but is not available. * The optional arguments `rounded` and `with_unit` control the formatting of sensor state strings, please see the [examples](https://www.home-assistant.io/docs/configuration/templating/#formatting-sensor-states) below. * `states.sensor.temperature.state_with_unit` formats the state string in the same way as if calling `states('sensor.temperature', rounded=True, with_unit=True)`. * `is_state` compares an entity’s state with a specified state or list of states and returns `True` or `False`. `is_state('device_tracker.paulus', 'home')` will test if the given entity is the specified state. `is_state('device_tracker.paulus', ['home', 'work'])` will test if the given entity is any of the states in the list. * `state_attr('device_tracker.paulus', 'battery')` will return the value of the attribute or None if it doesn’t exist. * `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). #### States examples[](https://www.home-assistant.io/docs/configuration/templating/#states-examples) The next two statements result in the same value if the state exists. The second one will result in an error if the state does not exist. {{ states('device_tracker.paulus') }} {{ states.device_tracker.paulus.state }} Print out a list of all the sensor states: {% for state in states.sensor %} {{ state.entity_id }}={{ state.state }}, {% endfor %} Print out a list of all the sensor states sorted by `entity_id`: {% for state in states.sensor | sort(attribute='entity_id') %} {{ state.entity_id }}={{ state.state }}, {% endfor %} Entities that are on: {{ ['light.kitchen', 'light.dining_room'] | select('is_state', 'on') | list }} Other state examples: {% if is_state('device_tracker.paulus', 'home') %} Ha, Paulus is home! {% else %} Paulus is at {{ states('device_tracker.paulus') }}. {% endif %} #check sensor.train_departure_time state {% if states('sensor.train_departure_time') in ("unavailable", "unknown") %} {{ ... }} {% if has_value('sensor.train_departure_time') %} {{ ... }} {% set state = states('sensor.temperature') %}{{ state | float + 1 if is_number(state) else "invalid temperature" }} {% set state = states('sensor.temperature') %}{{ (state | float * 10) | round(2) if is_number(state)}} {% set state = states('sensor.temperature') %} {% if is_number(state) and state | float > 20 %} It is warm! {% endif %} {{ as_timestamp(states.binary_sensor.garage_door.last_changed) }} {{ as_local(states.binary_sensor.garage_door.last_changed) }} {{ as_timestamp(now()) - as_timestamp(states.binary_sensor.garage_door.last_changed) }} {{ as_local(states.sensor.time.last_changed) }} {{ states('sensor.expires') | as_datetime }} # Make a list of states {{ ['light.kitchen', 'light.dining_room'] | map('states') | list }} #### Formatting sensor states[](https://www.home-assistant.io/docs/configuration/templating/#formatting-sensor-states) The examples below show the output of a temperature sensor with state `20.001`, unit `°C` and user configured presentation rounding set to 1 decimal. The following example results in the number `20.001`: {{ states('sensor.temperature') }} The following example results in the string `"20.0 °C"`: {{ states('sensor.temperature', with_unit=True) }} The following example result in the string `"20.001 °C"`: {{ states('sensor.temperature', with_unit=True, rounded=False) }} The following example results in the number `20.0`: {{ states('sensor.temperature', rounded=True) }} The following example results in the number `20.001`: {{ states.sensor.temperature.state }} The following example results in the string `"20.0 °C"`: {{ states.sensor.temperature.state_with_unit }} ### Attributes[](https://www.home-assistant.io/docs/configuration/templating/#attributes) Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . You can print an attribute with `state_attr` if state is defined. #### Attributes examples[](https://www.home-assistant.io/docs/configuration/templating/#attributes-examples) {% if states.device_tracker.paulus %} {{ state_attr('device_tracker.paulus', 'battery') }} {% else %} ?? {% endif %} With strings: {% set tracker_name = "paulus"%} {% if states("device_tracker." + tracker_name) != "unknown" %} {{ state_attr("device_tracker." + tracker_name, "battery")}} {% else %} ?? {% endif %} List of friendly names: {{ ['binary_sensor.garage_door', 'binary_sensor.front_door'] | map('state_attr', 'friendly_name') | list }} List of lights that are on with a brightness of 255: {{ ['light.kitchen', 'light.dining_room'] | select('is_state', 'on') | select('is_state_attr', 'brightness', 255) | list }} ### State translated[](https://www.home-assistant.io/docs/configuration/templating/#state-translated) Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . The `state_translated` function returns a translated state of an entity using a language that is currently configured in the [general settings](https://my.home-assistant.io/redirect/general/) . #### State translated examples[](https://www.home-assistant.io/docs/configuration/templating/#state-translated-examples) {{ states("sun.sun") }} # below_horizon {{ state_translated("sun.sun") }} # Below horizon {{ "sun.sun" | state_translated }} # Below horizon {{ states("binary_sensor.movement_backyard") }} # on {{ state_translated("binary_sensor.movement_backyard") }} # Detected {{ "binary_sensor.movement_backyard" | state_translated }} # Detected ### Working with groups[](https://www.home-assistant.io/docs/configuration/templating/#working-with-groups) Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . The `expand` function and filter can be used to sort entities and expand groups. It outputs a sorted array of entities with no duplicates. #### Expand examples[](https://www.home-assistant.io/docs/configuration/templating/#expand-examples) {% for tracker in expand('device_tracker.paulus', 'group.child_trackers') %} {{ state_attr(tracker.entity_id, 'battery') }} {%- if not loop.last %}, {% endif -%} {% endfor %} The same thing can also be expressed as a filter: {{ expand(['device_tracker.paulus', 'group.child_trackers']) | selectattr("attributes.battery", 'defined') | join(', ', attribute="attributes.battery") }} {% for energy in expand('group.energy_sensors') if is_number(energy.state) %} {{ energy.state }} {%- if not loop.last %}, {% endif -%} {% endfor %} The same thing can also be expressed as a test: {{ expand('group.energy_sensors') | selectattr("state", 'is_number') | join(', ') }} ### Entities[](https://www.home-assistant.io/docs/configuration/templating/#entities) * `is_hidden_entity(entity_id)` returns whether an entity has been hidden. Can also be used as a test. ### Entities examples[](https://www.home-assistant.io/docs/configuration/templating/#entities-examples) {{ area_entities('kitchen') | reject('is_hidden_entity') }} # Gets a list of visible entities in the kitchen area ### Devices[](https://www.home-assistant.io/docs/configuration/templating/#devices) * `device_entities(device_id)` returns a list of entities that are associated with a given device ID. Can also be used as a filter. * `device_attr(device_or_entity_id, attr_name)` returns the value of `attr_name` for the given device or entity ID. Can also be used as a filter. Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . * `is_device_attr(device_or_entity_id, attr_name, attr_value)` returns whether the value of `attr_name` for the given device or entity ID matches `attr_value`. Can also be used as a test. Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . * `device_id(entity_id)` returns the device ID for a given entity ID or device name. Can also be used as a filter. * `device_name(lookup_value)` returns the device name for a given device ID or entity ID. Can also be used as a filter. #### Devices examples[](https://www.home-assistant.io/docs/configuration/templating/#devices-examples) {{ device_attr('deadbeefdeadbeefdeadbeefdeadbeef', 'manufacturer') }} # Sony {{ is_device_attr('deadbeefdeadbeefdeadbeefdeadbeef', 'manufacturer', 'Sony') }} # true {{ device_id('sensor.sony') }} # deadbeefdeadbeefdeadbeefdeadbeef {{ device_name('deadbeefdeadbeefdeadbeefdeadbeef') }} # Sony speaker {{ device_name('sensor.sony') }} # Sony speaker ### Config entries[](https://www.home-assistant.io/docs/configuration/templating/#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](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . #### Config entries examples[](https://www.home-assistant.io/docs/configuration/templating/#config-entries-examples) {{ config_entry_id('sensor.sony') }} # deadbeefdeadbeefdeadbeefdeadbeef {{ config_entry_attr(config_entry_id('sensor.sony'), 'title') }} # Sony Bravia TV ### Floors[](https://www.home-assistant.io/docs/configuration/templating/#floors) * `floors()` returns the full list of floor IDs. * `floor_id(lookup_value)` returns the floor ID for a given floor name or alias, area name or alias, entity ID or device ID. Can also be used as a filter. * `floor_name(lookup_value)` returns the floor name for a given device ID, entity ID, area ID, or floor ID. Can also be used as a filter. * `floor_areas(floor_name_or_id)` returns the list of area IDs tied to a given floor ID or name. Can also be used as a filter. * `floor_entities(floor_name_or_id)` returns the list of entity IDs tied to a given floor ID or name. Can also be used as a filter. #### Floors examples[](https://www.home-assistant.io/docs/configuration/templating/#floors-examples) {{ floors() }} # ['floor_id'] {{ floor_id('First floor') }} # 'first_floor' {{ floor_id('First floor alias') }} # 'first_floor' {{ floor_id('my_device_id') }} # 'second_floor' {{ floor_id('sensor.sony') }} # 'first_floor' {{ floor_name('first_floor') }} # 'First floor' {{ floor_name('my_device_id') }} # 'Second floor' {{ floor_name('sensor.sony') }} # 'First floor' {{ floor_areas('first_floor') }} # ['living_room', 'kitchen'] ### Areas[](https://www.home-assistant.io/docs/configuration/templating/#areas) * `areas()` returns the full list of area IDs * `area_id(lookup_value)` returns the area ID for a given area name or alias, entity ID or device ID. Can also be used as a filter. * `area_name(lookup_value)` returns the area name for a given device ID, entity ID, or area ID. Can also be used as a filter. * `area_entities(area_name_or_id)` returns the list of entity IDs tied to a given area ID or name. Can also be used as a filter. * `area_devices(area_name_or_id)` returns the list of device IDs tied to a given area ID or name. Can also be used as a filter. #### Areas examples[](https://www.home-assistant.io/docs/configuration/templating/#areas-examples) {{ areas() }} # ['area_id'] {{ area_id('Living Room') }} # 'deadbeefdeadbeefdeadbeefdeadbeef' {{ area_id('Living Room Alias') }} # 'deadbeefdeadbeefdeadbeefdeadbeef' {{ area_id('my_device_id') }} # 'deadbeefdeadbeefdeadbeefdeadbeef' {{ area_id('sensor.sony') }} # 'deadbeefdeadbeefdeadbeefdeadbeef' {{ area_name('deadbeefdeadbeefdeadbeefdeadbeef') }} # 'Living Room' {{ area_name('my_device_id') }} # 'Living Room' {{ area_name('sensor.sony') }} # 'Living Room' {{ area_entities('deadbeefdeadbeefdeadbeefdeadbeef') }} # ['sensor.sony'] {{ area_devices('Living Room') }} # ['my_device_id'] ### Entities for an integration[](https://www.home-assistant.io/docs/configuration/templating/#entities-for-an-integration) * `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. #### Integrations examples[](https://www.home-assistant.io/docs/configuration/templating/#integrations-examples) {{ integration_entities('hue') }} # ['light.hue_light_upstairs', 'light.hue_light_downstairs'] {{ integration_entities('Hue bridge downstairs') }} # ['light.hue_light_downstairs'] ### Labels[](https://www.home-assistant.io/docs/configuration/templating/#labels) * `labels()` returns the full list of label IDs, or those for a given area ID, device ID, or entity ID. * `label_id(lookup_value)` returns the label ID for a given label name. * `label_name(lookup_value)` returns the label name for a given label ID. * `label_description(lookup_value)` returns the label description for a given label ID. * `label_areas(label_name_or_id)` returns the list of area IDs tied to a given label ID or name. * `label_devices(label_name_or_id)` returns the list of device IDs tied to a given label ID or name. * `label_entities(label_name_or_id)` returns the list of entity IDs tied to a given label ID or name. Each of the label template functions can also be used as a filter. #### Labels examples[](https://www.home-assistant.io/docs/configuration/templating/#labels-examples) {{ labels() }} # ['christmas_decorations', 'energy_saver', 'security'] {{ labels("living_room") }} # ['christmas_decorations', 'energy_saver'] {{ labels("my_device_id") }} # ['security'] {{ labels("light.christmas_tree") }} # ['christmas_decorations'] {{ label_id('Energy saver') }} # 'energy_saver' {{ label_name('energy_saver') }} # 'Energy saver' {{ label_areas('security') }} # ['driveway', 'garden', 'porch'] {{ label_devices('energy_saver') }} # ['deadbeefdeadbeefdeadbeefdeadbeef'] {{ label_entities('security') }} # ['camera.driveway', 'binary_sensor.motion_garden', 'camera.porch'] ### Issues[](https://www.home-assistant.io/docs/configuration/templating/#issues) * `issues()` returns all open issues as a mapping of (domain, issue\_id) tuples to the issue object. * `issue(domain, issue_id)` returns a specific issue for the provided domain and issue\_id. #### Issues examples[](https://www.home-assistant.io/docs/configuration/templating/#issues-examples) {{ issues() }} # { ("homeassistant", "deprecated_yaml_ping"): {...}, ("cloud", "legacy_subscription"): {...} } {{ issue('homeassistant', 'python_version') }} # {"breaks_in_ha_version": "2024.4", "domain": "homeassistant", "issue_id": "python_version", "is_persistent": False, ...} ### Immediate if (iif)[](https://www.home-assistant.io/docs/configuration/templating/#immediate-if-iif) A common case is to conditionally return a value based on another value. For example, return a “Yes” or “No” when the light is on or off. This can be written as: {% if is_state('light.kitchen', 'on') %} Yes {% else %} No {% endif %} Or using a shorter syntax: {{ 'Yes' if is_state('light.kitchen', 'on') else 'No' }} Additionally, to the above, you can use the `iif` function/filter, which is an immediate if. Syntax: `iif(condition, if_true, if_false, if_none)` `iif` returns the value of `if_true` if the condition is truthy, the value of `if_false` if it’s `falsy` and the value of `if_none` if it’s `None`. An empty string, an empty mapping or an an empty list, are all falsy, refer to [the Python documentation](https://docs.python.org/3/library/stdtypes.html#truth-value-testing) for an in depth explanation. `if_true` is optional, if it’s omitted `True` is returned if the condition is truthy. `if_false` is optional, if it’s omitted `False` is returned if the condition is falsy. `if_none` is optional, if it’s omitted the value of `if_false` is returned if the condition is `None`. Examples using `iif`: {{ iif(is_state('light.kitchen', 'on'), 'Yes', 'No') }} {{ is_state('light.kitchen', 'on') | iif('Yes', 'No') }} {{ (states('light.kitchen') == 'on') | iif('Yes', 'No') }} 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. ### Time[](https://www.home-assistant.io/docs/configuration/templating/#time) `now()`, `time_since()`, `time_until()`, `today_at()`, and `utcnow()` are not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . * `now()` returns a datetime object that represents the current time in your time zone. * You can also use: `now().second`, `now().minute`, `now().hour`, `now().day`, `now().month`, `now().year`, `now().weekday()` and `now().isoweekday()` and other [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) attributes and functions. * Using `now()` will cause templates to be refreshed at the start of every new minute. * `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 24-hour 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. # Is the current time past 10:15? {{ now() > today_at("10:15") }} * `as_datetime(value, default)` converts a string containing a timestamp or a valid UNIX timestamp to a datetime object. If conversion fails, the function returns the `default` value. If no `default` is provided and the input is a string that cannot be converted to a datetime, it returns `None`. For other invalid inputs (e.g., a list, dictionary, or a numeric value too large to convert), it raises an error when no `default` is supplied. In case the input is already a datetime object, it is returned unchanged. If the input is a `datetime.date` object, midnight is added as the 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/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. * `relative_time` converts a datetime object to its human-friendly “age” string. The age can be in seconds, minutes, hours, days, months, or years (but only the biggest unit is considered. For example, if it’s 2 days and 3 hours, “2 days” will be returned). Note that it only works for dates _in the past_. * Using `relative_time()` will cause templates to be refreshed at the start of every new minute. * `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. 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, 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. # 77 minutes before current time. {{ now() - timedelta( hours = 1, minutes = 17 ) }} * `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. # Renders to "00:10:00" {{ as_timedelta("PT10M") }} * Filter `timestamp_local(default)` converts a UNIX timestamp to the ISO format string representation as date/time in your local 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_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`). 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: `{{ states.sun.sun.last_changed }}` => `2023-07-30 20:03:49.253717+00:00` (missing “T” separator) To fix it, enforce the ISO conversion via `isoformat()`: `{{ states.sun.sun.last_changed.isoformat() }}` => `2023-07-30T20:03:49.253717+00:00` (contains “T” separator) {{ 120 | timestamp_local }} ### To/From JSON[](https://www.home-assistant.io/docs/configuration/templating/#tofrom-json) The `to_json` filter serializes an object to a JSON string. In some cases, it may be necessary to format a JSON string for use with a webhook, as a parameter for command-line utilities or any number of other applications. This can be complicated in a template, especially when dealing with escaping special characters. Using the `to_json` filter, this is handled automatically. `to_json` also accepts boolean arguments for `pretty_print`, which will pretty print the JSON with a 2-space indent to make it more human-readable, and `sort_keys`, which will sort the keys of the JSON object, ensuring that the resulting string is consistent for the same input. If you need to generate JSON that will be used by a parser that lacks support for Unicode characters, you can add `ensure_ascii=True` to have `to_json` generate Unicode escape sequences in strings. The `from_json` filter operates similarly, but in the other direction, de-serializing a JSON string back into an object. ### To/From JSON examples[](https://www.home-assistant.io/docs/configuration/templating/#tofrom-json-examples) #### Template[](https://www.home-assistant.io/docs/configuration/templating/#template) {% set temp = {'temperature': 25, 'unit': '°C'} %} stringified object: {{ temp }} object|to_json: {{ temp|to_json(sort_keys=True) }} #### Output[](https://www.home-assistant.io/docs/configuration/templating/#output) stringified object: {'temperature': 25, 'unit': '°C'} object|to_json: {"temperature": 25, "unit": "°C"} Conversely, `from_json` can be used to de-serialize a JSON string back into an object to make it possible to easily extract usable data. #### Template[](https://www.home-assistant.io/docs/configuration/templating/#template-1) {% set temp = '{"temperature": 25, "unit": "°C"}'|from_json %} The temperature is {{ temp.temperature }}{{ temp.unit }} #### Output[](https://www.home-assistant.io/docs/configuration/templating/#output-1) The temperature is 25°C `from_json(default)` function will attempt to convert the input to `json`. If that fails, returns the `default` value, or if omitted raises an error. #### Template[](https://www.home-assistant.io/docs/configuration/templating/#template-2) {% set result = 'not json'|from_json('not json') %} The value is {{ result }} #### Output[](https://www.home-assistant.io/docs/configuration/templating/#output-2) The value is not json ### Is defined[](https://www.home-assistant.io/docs/configuration/templating/#is-defined) Sometimes a template should only return if a value or object is defined, if not, the supplied default value should be returned. This can be useful to validate a JSON payload. The `is_defined` filter allows to throw an error if a value or object is not defined. Example using `is_defined` to parse a JSON payload: {{ value_json.val | is_defined }} This will throw an error `UndefinedError: 'value_json' is undefined` if the JSON payload has no `val` attribute. ### Version[](https://www.home-assistant.io/docs/configuration/templating/#version) * `version()` Returns a [AwesomeVersion object](https://github.com/ludeeus/awesomeversion) for the value given inside the brackets. * This is also available as a filter (`| version`). Examples: * `{{ version("2099.9.9") > "2000.0.0" }}` Will return `True` * `{{ version("2099.9.9") < "2099.10" }}` Will return `True` * `{{ "2099.9.9" | version < "2099.10" }}` Will return `True` * `{{ (version("2099.9.9") - "2100.9.10").major }}` Will return `True` * `{{ (version("2099.9.9") - "2099.10.9").minor }}` Will return `True` * `{{ (version("2099.9.9") - "2099.9.10").patch }}` Will return `True` ### Distance[](https://www.home-assistant.io/docs/configuration/templating/#distance) Not supported in [limited templates](https://www.home-assistant.io/docs/configuration/templating/#limited-templates) . * `distance()` measures the distance between home, an entity, or coordinates. The unit of measurement (kilometers or miles) depends on the system’s configuration settings. * `closest()` will find the closest entity. #### Distance examples[](https://www.home-assistant.io/docs/configuration/templating/#distance-examples) If only one location is passed in, Home Assistant will measure the distance from home. Using Lat Lng coordinates: {{ distance(123.45, 123.45) }} Using State: {{ distance(states.device_tracker.paulus) }} These can also be combined in any combination: {{ distance(123.45, 123.45, 'device_tracker.paulus') }} {{ distance('device_tracker.anne_therese', 'device_tracker.paulus') }} #### Closest examples[](https://www.home-assistant.io/docs/configuration/templating/#closest-examples) The closest function and filter will find the closest entity to the Home Assistant location: Query all entities: {{ closest(states) }} Query all entities of a specific domain: {{ closest(states.device_tracker) }} Query all entities in group.children: {{ closest('group.children') }} Query all entities in group.children: {{ closest(states.group.children) }} Find entities closest to a coordinate or another entity. All previous arguments still apply for second argument. Closest to a coordinate: {{ closest(23.456, 23.456, 'group.children') }} Closest to an entity: {{ closest('zone.school', 'group.children') }} Closest to an entity: {{ closest(states.zone.school, 'group.children') }} Since closest returns a state, we can combine it with distance too. {{ closest(states).name }} is {{ distance(closest(states)) }} kilometers away. The last argument of the closest function has an implicit `expand`, and can take any iterable sequence of states or entity IDs, and will expand groups: Closest out of given entities: {{ closest(['group.children', states.device_tracker]) }} Closest to a coordinate: {{ closest(23.456, 23.456, ['group.children', states.device_tracker]) }} Closest to some entity: {{ closest(states.zone.school, ['group.children', states.device_tracker]) }} It will also work as a filter over an iterable group of entities or groups: Closest out of given entities: {{ ['group.children', states.device_tracker] | closest }} Closest to a coordinate: {{ ['group.children', states.device_tracker] | closest(23.456, 23.456) }} Closest to some entity: {{ ['group.children', states.device_tracker] | closest(states.zone.school) }} ### Contains[](https://www.home-assistant.io/docs/configuration/templating/#contains) Jinja provides by default a [`in` operator](https://jinja.palletsprojects.com/en/latest/templates/#other-operators) how return `True` when one element is `in` a provided list. The `contains` test and filter allow you to do the exact opposite and test for a list containing an element. This is particularly useful in `select` or `selectattr` filter, as well as to check if a device has a specific attribute, a `supported_color_modes`, a specific light effect. Some examples: * `{{ state_attr('light.dining_room', 'effect_list') | contains('rainbow') }}` will return `true` if the light has a `rainbow` effect. * `{{ expand('light.office') | selectattr("attributes.supported_color_modes", 'contains', 'color_temp') | list }}` will return all light that support color\_temp in the office group. * {% set current_month = now().month %} {% set extra_ambiance = [\ {'name':'Halloween', 'month': [10,11]},\ {'name':'Noel', 'month': [1,11,12]}\ ]%} {% set to_add = extra_ambiance | selectattr('month', 'contains', current_month ) | map(attribute='name') | list %} {% 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` action. ### Numeric functions and filters[](https://www.home-assistant.io/docs/configuration/templating/#numeric-functions-and-filters) 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. * `{{ float("not_a_number") }}` - the template will fail to render * `{{ "not_a_number" | sin }}` - the template will fail to render * `{{ float("not_a_number", default="Invalid number!") }}` - renders as `"Invalid number!"` * `{{ "not_a_number" | sin(default="Invalid number!") }}` - renders as `"Invalid number!"` * `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. * `is_number` will return `True` if the input can be parsed by Python’s `float` function and the parsed input is not `inf` or `nan`, in all other cases returns `False`. Note that a Python `bool` will return `True` but the strings `"True"` and `"False"` will both return `False`. Can be used as a filter. * `int(value, default)` function is similar to `float`, but converts to an `int` instead. Like `float`, it has a filter form, and an error is raised if the `default` value is omitted. Fractional part is discarded: `int("1.5")` is `1`. * `bool(value, default)` function converts the value to either `true` or `false`. The following values are considered to be `true`: boolean `true`, non-zero `int`s and `float`s, and the strings `"true"`, `"yes"`, `"on"`, `"enable"`, and `"1"` (case-insensitive). `false` is returned for the opposite values: boolean `false`, integer or floating-point `0`, and the strings `"false"`, `"no"`, `"off"`, `"disable"`, and `"0"` (also case-insensitive). If the value is not listed here, the function returns the `default` value, or if omitted raises an error. This function is intended to be used on states of [binary sensors](https://www.home-assistant.io/integrations/binary_sensor/) , [switches](https://www.home-assistant.io/integrations/switch/) , or similar entities, so its behavior is different from Python’s built-in `bool` conversion, which would consider e.g. `"on"`, `"off"`, and `"unknown"` all to be `true`, but `""` to be `false`; if that is desired, use `not not value` or a similar construct instead. Like `float` and `int`, `bool` has a filter form. Using `none` as the default value is particularly useful in combination with the [immediate if filter](https://www.home-assistant.io/docs/configuration/templating/#immediate-if-iif) : it can handle all three possible cases in a single line. * `log(value, base, default)` will take the logarithm of the input. When the base is omitted, it defaults to `e` - the natural logarithm. If `value` or `base` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can also be used as a filter. * `sin(value, default)` will return the sine of the input. The input value is in radians. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `cos(value, default)` will return the cosine of the input. The input value is in radians. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `tan(value, default)` will return the tangent of the input. The input value is in radians. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `asin(value, default)` will return the arcus sine of the input. The return value is in radians. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `acos(value, default)` will return the arcus cosine of the input. The return value is in radians. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `atan(value, default)` will return the arcus tangent of the input. The return value is in radians. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `atan2(y, x, default)` will return the four quadrant arcus tangent of y / x. The return value is in radians. If `y` or `x` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `sqrt(value, default)` will return the square root of the input. If `value` can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `max([x, y, ...])` will obtain the largest item in a sequence. Uses the same parameters as the built-in [max](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.max) filter. * `min([x, y, ...])` will obtain the smallest item in a sequence. Uses the same parameters as the built-in [min](https://jinja.palletsprojects.com/en/latest/templates/#jinja-filters.min) filter. * `average([x, y, ...], default)` will return the average value of the sequence. If list is empty or contains non-numeric value, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `median([x, y, ...], default)` will return the median value of the sequence. If list is empty or contains non-numeric value, returns the `default` value, or if omitted raises an error. Can be used as a filter. * `statistical_mode([x, y, ...], default)` will return the statistical mode value (most frequent occurrence) of the sequence. If the list is empty, it returns the `default` value, or if omitted raises an error. It can be used as a filter. * `clamp(v, min, max)` limits the value `v` to be between `min` and `max`, [clamping at the edges](https://en.wikipedia.org/wiki/Clamp_(function)) . If any of the arguments cannot be converted to a float, an error is raised. Can be used as a filter. * `wrap(v, min, max)` limits the value to be between min and max, wrapping the value at the edges. In mathematical terms, this is [modular arithmetic](https://en.wikipedia.org/wiki/Modular_arithmetic) , sometimes called “clock face math”. If `v`, `min`, or `max` cannot be converted to numbers, an error is raised. Can be used as a filter. * `remap(v, in_min, in_max, out_min, out_max, *, [steps], [edges])` remaps a value `v` from the range `in_min`..`in_max` to the range `out_min`..`out_max`. If any of the values `v`, `in_min`, `in_max`, `out_min`, `out_max` cannot be converted to numbers, an error is raised. Can be used as a filter. * You can optionally set the `edges` parameter to control how out-of-bounds input values are handled: * `edges='clamp'` (the default) will clamp the output to the min/max output range. * `edges='wrap'` will wrap the input value around the input range before remapping. * `edges='mirror'` will bounce the input value back and forth within the input range before remapping. * You can optionally set the `steps` parameter to a positive integer to quantize the output to a number of discrete steps. * `e` mathematical constant, approximately 2.71828. * `pi` mathematical constant, approximately 3.14159. * `tau` mathematical constant, approximately 6.28318. * Filter `round(precision, method, default)` will convert the input to a number and round it to `precision` decimals. Round has four modes and the default mode (with no mode specified) will [round-to-even](https://en.wikipedia.org/wiki/Rounding#Roundhalfto_even) . If the input value can’t be converted to a `float`, returns the `default` value, or if omitted raises an error. * `round(precision, "floor", default)` will always round down to `precision` decimals * `round(precision, "ceil", default)` will always round up to `precision` decimals * `round(1, "half", default)` will always round to the nearest .5 value. `precision` should be 1 for this mode * Filter `value_one|bitwise_and(value_two)` perform a bitwise and(&) operation with two values. * Filter `value_one|bitwise_or(value_two)` perform a bitwise or(|) operation with two values. * Filter `value_one|bitwise_xor(value_two)` perform a bitwise xor(^) operation with two values. * Filter `ord` will return for a string of length one an integer representing the Unicode code point of the character when the argument is a Unicode object, or the value of the byte when the argument is an 8-bit string. * Filter `multiply(arg)` will convert the input to a number and multiply it by `arg`. Useful in list operations in conjunction with `map`. * Filter `add(arg)` will convert the input to a number and add it to `arg`. Useful in list operations in conjunction with `map`. ### Complex type checking[](https://www.home-assistant.io/docs/configuration/templating/#complex-type-checking) In addition to strings and numbers, Python (and Jinja) supports lists, sets, and dictionaries. To help you with testing these types, you can use the following tests: * `x is list` will return whether `x` is a `list` or not (e.g. `[1, 2] is list` will return `True`). * `x is set` will return whether `x` is a `set` or not (e.g. `{1, 2} is set` will return `True`). * `x is tuple` will return whether `x` is a `tuple` or not (e.g. `(1, 2) is tuple` will return `True`). * `x is datetime` will return whether `x` is a `datetime` or not (e.g. `datetime(2020, 1, 1, 0, 0, 0) is datetime` will return `True`). * `x is string_like` will return whether `x` is a string, bytes, or bytearray object. Note that, in Home Assistant, Jinja has built-in tests for `boolean` (`True`/`False`), `callable` (any function), `float` (a number with a decimal), `integer` (a number without a decimal), `iterable` (a value that can be iterated over such as a `list`, `set`, `string`, or generator), `mapping` (mainly `dict` but also supports other dictionary like types), `number` (`float` or `int`), `sequence` (a value that can be iterated over and indexed such as `list` and `string`), and `string`. ### Type conversions[](https://www.home-assistant.io/docs/configuration/templating/#type-conversions) While Jinja natively supports the conversion of an iterable to a `list`, it does not support conversion to a `tuple` or `set`. To help you with using these types, you can use the following functions: * `set(x)` will convert any iterable `x` to a `set` (e.g. `set([1, 2]) == {1, 2}`) * `tuple(x)` will convert any iterable `x` to a `tuple` (e.g. `tuple("abc") == ("a", "b", "c")`) 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[](https://www.home-assistant.io/docs/configuration/templating/#iterating-multiple-objects) The `zip()` function can be used to iterate over multiple collections in one operation. {% 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 %} `zip()` can also unzip lists. {% 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(', ') }} ### Functions and filters to process raw data[](https://www.home-assistant.io/docs/configuration/templating/#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. The `pack` and `unpack` functions can also be used as a filter. They make use of the Python 3 `struct` library. See: [Python struct library documentation](https://docs.python.org/3/library/struct.html) * Filter `value | pack(format_string)` will convert a native type to a `bytes` type object. This will call function `struct.pack(format_string, value)`. Returns `None` if an error occurs or when `format_string` is invalid. * Function `pack(value, format_string)` will convert a native type to a `bytes` type object. This will call function `struct.pack(format_string, value)`. Returns `None` if an error occurs or when `format_string` is invalid. * 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: * `{{ 0xDEADBEEF | pack(">I") }}` - renders as `b"\xde\xad\xbe\xef"` * `{{ pack(0xDEADBEEF, ">I") }}` - renders as `b"\xde\xad\xbe\xef"` * `{{ "0x%X" % 0xDEADBEEF | pack(">I") | unpack(">I") }}` - renders as `0xDEADBEEF` * `{{ "0x%X" % 0xDEADBEEF | pack(">I") | unpack(">H", offset=2) }}` - renders as `0xBEEF` ### String filters[](https://www.home-assistant.io/docs/configuration/templating/#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 | from_hex` Decodes a hex string to raw bytes. * Filter `value | base64_encode` Encodes a string or bytes to a base 64 string. * 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: * `{{ "homeassistant" | base64_encode }}` - renders as `aG9tZWFzc2lzdGFudA==` * `{{ "aG9tZWFzc2lzdGFudA==" | base64_decode }}` - renders as `homeassistant` * `{{ "aG9tZWFzc2lzdGFudA==" | base64_decode(None) }}` - renders as `b'homeassistant'` * `{{ "0F010003" | from_hex }}` - renders as `b'\x0f\x01\x00\x03'` * `{{ "0F010003" | from_hex | base64_encode }}` - renders as `DwEAAw==` ### Hashing[](https://www.home-assistant.io/docs/configuration/templating/#hashing) The template engine contains a few filters and functions to hash a string of data. A few very common hashing algorithms are supported: `md5`, `sha1`, `sha256`, and `sha512`. Some examples: * `{{ md5("Home Assistant") }}` - renders as `f3f2b8b3b40084aa87e92b7ffb02ed13885fea2d07` * `{{ "Home Assistant" | md5 }}` - renders as `f3f2b8b3b40084aa87e92b7ffb02ed13885fea2d07` * `{{ sha1("Home Assistant") }}` - renders as `14bffd017c73917bfda2372aaf287570597b8e82` * `{{ "Home Assistant" | sha1 }}` - renders as `14bffd017c73917bfda2372aaf287570597b8e82` * `{{ sha256("Home Assistant") }}` - renders as `a18f473c9d3ed968a598f996dcf0b9de84de4ee04c950d041b61297a25bcea49` * `{{ "Home Assistant" | sha256 }}` - renders as `a18f473c9d3ed968a598f996dcf0b9de84de4ee04c950d041b61297a25bcea49` * `{{ sha512("Home Assistant") }}` - renders as `f251e06eb7d3439e1a86d6497d6a4531c3e8c809f538be62f89babf147d7d63aca4e77ae475b94c654fd38d8f543f778ce80007d6afef379d8a0e5d3ddf7349d` * `{{ "Home Assistant" | sha512 }}` - renders as `f251e06eb7d3439e1a86d6497d6a4531c3e8c809f538be62f89babf147d7d63aca4e77ae475b94c654fd38d8f543f778ce80007d6afef379d8a0e5d3ddf7349d` ### Regular expressions[](https://www.home-assistant.io/docs/configuration/templating/#regular-expressions) For more information on regular expressions See: [Python regular expression operations](https://docs.python.org/3/library/re.html) * Test `string is match(find, ignorecase=False)` will match the find expression at the beginning of the string using regex. * Test `string is search(find, ignorecase=False)` will match the find expression anywhere in the string using regex. * Filter `string|regex_replace(find='', replace='', ignorecase=False)` will replace the find expression with the replace string using regex. Access to the matched groups in `replace` is possible with `'\\1'`, `'\\2'`, etc. * Filter `value | regex_findall(find='', ignorecase=False)` will find all regex matches of the find expression in `value` and return the array of matches. * Filter `value | regex_findall_index(find='', index=0, ignorecase=False)` will do the same as `regex_findall` and return the match at index. ### Shuffling[](https://www.home-assistant.io/docs/configuration/templating/#shuffling) The template engine contains a filter and function to shuffle a list. Shuffling can happen randomly or reproducibly using a seed. When using a seed it will always return the same shuffled list for the same seed. Some examples: * `{{ [1, 2, 3] | shuffle }}` - renders as `[3, 1, 2]` (_random_) * `{{ shuffle([1, 2, 3]) }}` - renders as `[3, 1, 2]` (_random_) * `{{ shuffle(1, 2, 3) }}` - renders as `[3, 1, 2]` (_random_) * `{{ [1, 2, 3] | shuffle("random seed") }}` - renders as \`\[2, 3, 1\] (_reproducible_) * `{{ shuffle([1, 2, 3], seed="random seed") }}` - renders as \`\[2, 3, 1\] (_reproducible_) * `{{ shuffle([1, 2, 3], "random seed") }}`\- renders as \`\[2, 3, 1\] (_reproducible_) * `{{ shuffle(1, 2, 3, seed="random seed") }}` - renders as \`\[2, 3, 1\] (_reproducible_) ### Flatten a list of lists[](https://www.home-assistant.io/docs/configuration/templating/#flatten-a-list-of-lists) The template engine provides a filter to flatten a list of lists: `flatten`. It will take a list of lists and return a single list with all the elements. The depth of the flattening can be controlled using the `levels` parameter. The flattening process is recursive, so it will flatten all nested lists, until the number of levels (if specified) is reached. Some examples: * `{{ flatten([1, [2, [3]], 4, [5 , 6]]) }}` - renders as `[1, 2, 3, 4, 5, 6]` * `{{ [1, [2, [3]], 4, [5 , 6]] | flatten }}` - renders as `[1, 2, 3, 4, 5, 6]` * `{{ flatten([1, [2, [3]]], levels=1) }}` - renders as `[1, 2, [3]]` * `{{ [1, [2, [3]]], flatten(levels=1) }}` - renders as `[1, 2, [3]]` * `{{ flatten([1, [2, [3]]], 1) }}` - renders as `[1, 2, [3]]` * `{{ [1, [2, [3]]], flatten(1) }}` - renders as `[1, 2, [3]]` ### Find common elements between lists[](https://www.home-assistant.io/docs/configuration/templating/#find-common-elements-between-lists) The template engine provides a filter to find common elements between two lists: `intersect`. This function returns a list containing all elements that are present in both input lists. Some examples: * `{{ intersect([1, 2, 5, 3, 4, 10], [1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[1, 2, 3, 4, 5]` * `{{ [1, 2, 5, 3, 4, 10] | intersect([1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[1, 2, 3, 4, 5]` * `{{ intersect(['a', 'b', 'c'], ['b', 'c', 'd']) }}` - renders as `['b', 'c']` * `{{ ['a', 'b', 'c'] | intersect(['b', 'c', 'd']) }}` - renders as `['b', 'c']` ### Find elements in first list not in second list[](https://www.home-assistant.io/docs/configuration/templating/#find-elements-in-first-list-not-in-second-list) The template engine provides a filter to find elements that are in the first list but not in the second list: `difference`. This function returns a list containing all elements that are present in the first list but absent from the second list. Some examples: * `{{ difference([1, 2, 5, 3, 4, 10], [1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[10]` * `{{ [1, 2, 5, 3, 4, 10] | difference([1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[10]` * `{{ difference(['a', 'b', 'c'], ['b', 'c', 'd']) }}` - renders as `['a']` * `{{ ['a', 'b', 'c'] | difference(['b', 'c', 'd']) }}` - renders as `['a']` ### Find elements that are in either list but not in both[](https://www.home-assistant.io/docs/configuration/templating/#find-elements-that-are-in-either-list-but-not-in-both) The template engine provides a filter to find elements that are in either of the input lists but not in both: `symmetric_difference`. This function returns a list containing all elements that are present in either the first list or the second list, but not in both. Some examples: * `{{ symmetric_difference([1, 2, 5, 3, 4, 10], [1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[10, 11, 99]` * `{{ [1, 2, 5, 3, 4, 10] | symmetric_difference([1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[10, 11, 99]` * `{{ symmetric_difference(['a', 'b', 'c'], ['b', 'c', 'd']) }}` - renders as `['a', 'd']` * `{{ ['a', 'b', 'c'] | symmetric_difference(['b', 'c', 'd']) }}` - renders as `['a', 'd']` ### Combine all unique elements from two lists[](https://www.home-assistant.io/docs/configuration/templating/#combine-all-unique-elements-from-two-lists) The template engine provides a filter to combine all unique elements from two lists: `union`. This function returns a list containing all unique elements that are present in either the first list or the second list. Some examples: * `{{ union([1, 2, 5, 3, 4, 10], [1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[1, 2, 3, 4, 5, 10, 11, 99]` * `{{ [1, 2, 5, 3, 4, 10] | union([1, 2, 3, 4, 5, 11, 99]) }}` - renders as `[1, 2, 3, 4, 5, 10, 11, 99]` * `{{ union(['a', 'b', 'c'], ['b', 'c', 'd']) }}` - renders as `['a', 'b', 'c', 'd']` * `{{ ['a', 'b', 'c'] | union(['b', 'c', 'd']) }}` - renders as `['a', 'b', 'c', 'd']` ### Combining dictionaries[](https://www.home-assistant.io/docs/configuration/templating/#combining-dictionaries) The template engine provides a function and filter to merge multiple dictionaries: `combine`. It will take multiple dictionaries and merge them into a single dictionary. When used as a filter, the filter value is used as the first dictionary. The optional `recursive` parameter determines whether nested dictionaries should be merged (defaults to `False`). Some examples: * `{{ {'a': 1, 'b': 2} | combine({'b': 3, 'c': 4}) }}` - renders as `{'a': 1, 'b': 3, 'c': 4}` * `{{ combine({'a': 1, 'b': 2}, {'b': 3, 'c': 4}) }}` - renders as `{'a': 1, 'b': 3, 'c': 4}` * `{{ combine({'a': 1, 'b': {'x': 1}}, {'b': {'y': 2}, 'c': 4}, recursive=True) }}` - renders as `{'a': 1, 'b': {'x': 1, 'y': 2}, 'c': 4}` * `{{ combine({'a': 1, 'b': {'x': 1}}, {'b': {'y': 2}, 'c': 4}) }}` - renders as `{'a': 1, 'b': {'y': 2}, 'c': 4}` ### Working with macros[](https://www.home-assistant.io/docs/configuration/templating/#working-with-macros) Home Assistant provides two additional functions that make macros much more powerful. * `apply` is both a filter and a test that allows you to use any callable (macros or functions) wherever you can use other filters and tests. `apply` also passes along any additional parameters to the function. For example, if you had a function called `double`, you could call `{{ [1, 2, 3, 4] | map('apply', double) | list }}`, which would render as `[2, 4, 6, 8]`. Alternatively, if you had a function called `is_multiple_of`, you could call `{{ [1, 2, 3, 4] | select('apply', is_multiple_of, 2) | list }}`, which would render as `[2, 4]`. * `as_function` is a filter that takes a macro that has a named parameter called `returns`. The macro can then call `{%- do returns(return_value) -%}`. After passing this macro into `as_function`, the resulting function returns your return value directly, preserving the underlying data type rather than rendering a string. You can return dictionaries, numbers, `True`/`False` (allowing you to write your own tests when used with `apply`), or any other value your code might produce. Merge action responses[](https://www.home-assistant.io/docs/configuration/templating/#merge-action-responses) -------------------------------------------------------------------------------------------------------------- Using action responses we can collect information from various entities at the same time. Using the `merge_response` template we can merge several responses into one list. | Variable | Description | | --- | --- | | `value` | The incoming value (must be an action response). | The `entity_id` key is appended to each dictionary within the template output list as a reference of origin. If the input dictionary already contains an `entity_id` key, the template will fail. The `value_key` key is appended to each dictionary within the template output list as a reference of origin if the original service call was providing a list of dictionaries, for example, `calendar.get_events` or `weather.get_forecasts`. Examples of these two keys can be seen in [example merge calendar action response](https://www.home-assistant.io/docs/configuration/templating/#example-merge-calendar-action-response) template output. ### Example[](https://www.home-assistant.io/docs/configuration/templating/#example) {% set combined_forecast = merge_response(response) %} {{ combined_forecast[0].precipitation | float(0) | round(1) }} ### Example how to sort[](https://www.home-assistant.io/docs/configuration/templating/#example-how-to-sort) Sorting the dictionaries within the list based on a specific key can be done directly by using Jinja’s `sort` filter. {{ merge_response(calendar_response) | sort(attribute='start') | ... }} ### Example merge calendar action response[](https://www.home-assistant.io/docs/configuration/templating/#example-merge-calendar-action-response) { "calendar.sports": { "events": [\ {\ "start": "2024-02-27T17:00:00-06:00",\ "end": "2024-02-27T18:00:00-06:00",\ "summary": "Basketball vs. Rockets",\ "description": "",\ }\ ] }, "calendar.local_furry_events": {"events": []}, "calendar.yap_house_schedules": { "events": [\ {\ "start": "2024-02-26T08:00:00-06:00",\ "end": "2024-02-26T09:00:00-06:00",\ "summary": "Dr. Appt",\ "description": "",\ },\ {\ "start": "2024-02-28T20:00:00-06:00",\ "end": "2024-02-28T21:00:00-06:00",\ "summary": "Bake a cake",\ "description": "something good",\ }\ ] }, } {{ merge_response(response_variable) }} [\ {\ "description": "",\ "end": "2024-02-27T18:00:00-06:00",\ "entity_id": "calendar.sports",\ "start": "2024-02-27T17:00:00-06:00",\ "summary": "Basketball vs. Rockets",\ "value_key": "events"\ },\ {\ "description": "",\ "end": "2024-02-26T09:00:00-06:00",\ "entity_id": "calendar.yap_house_schedules",\ "start": "2024-02-26T08:00:00-06:00",\ "summary": "Dr. Appt",\ "value_key": "events"\ },\ {\ "description": "something good",\ "end": "2024-02-28T21:00:00-06:00",\ "entity_id": "calendar.yap_house_schedules",\ "start": "2024-02-28T20:00:00-06:00",\ "summary": "Bake a cake",\ "value_key": "events"\ }\ ] ### Example non-list action responses[](https://www.home-assistant.io/docs/configuration/templating/#example-non-list-action-responses) { "vacuum.deebot_n8_plus_1": { "header": { "ver": "0.0.1", }, "payloadType": "j", "resp": { "body": { "msg": "ok", }, }, }, "vacuum.deebot_n8_plus_2": { "header": { "ver": "0.0.1", }, "payloadType": "j", "resp": { "body": { "msg": "ok", }, }, }, } {{ merge_response(response_variable) }} [\ {\ "entity_id": "vacuum.deebot_n8_plus_1",\ "header": {\ "ver": "0.0.1",\ },\ "payloadType": "j",\ "resp": {\ "body": {\ "msg": "ok",\ },\ },\ },\ {\ "entity_id": "vacuum.deebot_n8_plus_2",\ "header": {\ "ver": "0.0.1",\ },\ "payloadType": "j",\ "resp": {\ "body": {\ "msg": "ok",\ },\ },\ },\ ] Processing incoming data[](https://www.home-assistant.io/docs/configuration/templating/#processing-incoming-data) ------------------------------------------------------------------------------------------------------------------ The other part of templating is processing incoming data. It allows you to modify incoming data and extract only the data you care about. This will only work for platforms and integrations that mention support for this in their documentation. It depends per integration or platform, but it is common to be able to define a template using the `value_template` configuration key. When a new value arrives, your template will be rendered while having access to the following values on top of the usual Home Assistant extensions: | Variable | Description | | --- | --- | | `value` | The incoming value. | | `value_json` | The incoming value parsed as JSON. | This means that if the incoming values looks like the sample below: { "on": "true", "temp": 21 } The template for `on` would be: "{{value_json.on}}" Nested JSON in a response is supported as well: { "sensor": { "type": "air", "id": "12345" }, "values": { "temp": 26.09, "hum": 56.73 } } Just use the “Square bracket notation” to get the value. "{{ value_json['values']['temp'] }}" The following overview contains a couple of options to get the needed values: # Incoming value: {"primes": [2, 3, 5, 7, 11, 13]} # Extract first prime number {{ value_json.primes[0] }} # Format output {{ "%+.1f" | value_json }} # Math {{ value_json | float * 1024 if is_number(value_json) }} {{ float(value_json) * (2**10) if is_number(value_json) }} {{ value_json | log if is_number(value_json) }} {{ log(1000, 10) }} {{ sin(pi / 2) }} {{ cos(tau) }} {{ tan(pi) }} {{ sqrt(e) }} # Timestamps {{ value_json.tst | timestamp_local }} {{ value_json.tst | timestamp_utc }} {{ value_json.tst | timestamp_custom('%Y', True) }} To evaluate a response, go to **[Developer Tools > Template](https://my.home-assistant.io/redirect/developer_template) **, create your output in “Template editor”, and check the result. {% set value_json= {"name":"Outside", "device":"weather-ha", "data": {"temp":"24C", "hum":"35%" } }%} {{value_json.data.hum[:-1]}} ### Using templates with the MQTT integration[](https://www.home-assistant.io/docs/configuration/templating/#using-templates-with-the-mqtt-integration) The [MQTT integration](https://www.home-assistant.io/integrations/mqtt/) relies heavily on templates. Templates are used to transform incoming payloads (value templates) to state updates or incoming actions (command templates) to payloads that configure the MQTT device. #### Using value templates with MQTT[](https://www.home-assistant.io/docs/configuration/templating/#using-value-templates-with-mqtt) Value templates translate received MQTT payload to a valid state or attribute. The received MQTT is available in the `value` template variable, and in the `value_json` template variable if the received MQTT payload is valid JSON. In addition, the template variables `entity_id`, `name` and `this` are available for MQTT entity value templates. The `this` attribute refers to the [entity state](https://www.home-assistant.io/docs/configuration/state_object) of the MQTT item. Note Example value template: With given payload: { "state": "ON", "temperature": 21.902, "humidity": null } Template `{{ value_json.temperature | round(1) }}` renders to `21.9`. Template `{{ value_json.humidity }}` renders to `None`. #### Using command templates with MQTT[](https://www.home-assistant.io/docs/configuration/templating/#using-command-templates-with-mqtt) For actions, command templates are defined to format the outgoing MQTT payload to a format supported by the remote device. When an action is executed, the template variable `value` has the action data in most cases unless otherwise specified in the documentation. In addition, the template variables `entity_id`, `name` and `this` are available for MQTT entity command templates. The `this` attribute refers to the [entity state](https://www.home-assistant.io/docs/configuration/state_object) of the MQTT item. Note **Example command template with JSON data:** With given value `21.9` template `{"temperature": {{ value }} }` renders to: { "temperature": 21.9 } **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 `{{ "16" }}` renders to payload encoded string `"16"`. * Template `{{ 16 }}` renders to payload encoded string `"16"`. * Template `{{ pack(0x10, ">B") }}` renders to a raw 1 byte payload `0x10`. ### Determining types[](https://www.home-assistant.io/docs/configuration/templating/#determining-types) When working with templates, it can be useful to determine the type of the returned value from a method or the type of a variable at times. For this, Home Assistant provides the `typeof()` template function and filter, which is inspired by the [JavaScript](https://en.wikipedia.org/wiki/JavaScript) `typeof` operator. It reveals the type of the given value. This is mostly useful when you are debugging or playing with templates in the developer tools of Home Assistant. However, it might be useful in some other cases as well. Some examples: * `{{ typeof(42) }}` - renders as `int` * `{{ typeof(42.0) }}` - renders as `float` * `{{ typeof("42") }}` - renders as `str` * `{{ typeof([1, 2, 3]) }}` - renders as `list` * `{{ typeof({"key": "value"}) }}` - renders as `dict` * `{{ typeof(True) }}` - renders as `bool` * `{{ typeof(None) }}` - renders as `NoneType` * `{{ 42 | typeof }}` - renders as `int` * `{{ 42.0 | typeof }}` - renders as `float` * `{{ "42" | typeof }}` - renders as `str` * `{{ [1, 2, 3] | typeof }}` - renders as `list` * `{{ {"key": "value"} | typeof }}` - renders as `dict` * `{{ True | typeof }}` - renders as `bool` * `{{ None | typeof }}` - renders as `NoneType` * `{{ some_variable | typeof }}` - renders the type of `some_variable` * `{{ states("sensor.living_room") | typeof }}` - renders the type of the result of `states()` function Some more things to keep in mind[](https://www.home-assistant.io/docs/configuration/templating/#some-more-things-to-keep-in-mind) ---------------------------------------------------------------------------------------------------------------------------------- ### entity\_id that begins with a number[](https://www.home-assistant.io/docs/configuration/templating/#entity_id-that-begins-with-a-number) If your template uses an `entity_id` that begins with a number (example: `states.device_tracker.2008_gmc`) you must use a bracket syntax to avoid errors caused by rendering the `entity_id` improperly. In the example given, the correct syntax for the device tracker would be: `states.device_tracker['2008_gmc']` ### Priority of operators[](https://www.home-assistant.io/docs/configuration/templating/#priority-of-operators) The default priority of operators is that the filter (`|`) has priority over everything except brackets. This means that: {{ states('sensor.temperature') | float / 10 | round(2) }} Would round `10` to 2 decimal places, then divide `states('sensor.temperature')` by `10` (rounded to 2 decimal places so 10.00). This behavior is maybe not the one expected, but priority rules imply that. #### **Help us improve our documentation**[](https://www.home-assistant.io/docs/configuration/templating/#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_docs/configuration/templating.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fdocs%2Fconfiguration%2Ftemplating%2F&version=2026.1.1&labels=current "Provide feedback on this page") * [View given feedback](https://github.com/home-assistant/home-assistant.io/issues?utf8=%E2%9C%93&q=%22%2Fdocs%2Fconfiguration%2Ftemplating%2F%22&in=body "View given feedback for this page") --- # Documentation - Home Assistant The documentation covers beginner to advanced topics around the installation, setup, configuration, and usage of Home Assistant. To see what Home Assistant can do, take a look at the [demo page](https://demo.home-assistant.io/) . * [Automations](https://www.home-assistant.io/docs/automation/) * [Basic automations](https://www.home-assistant.io/docs/automation/basics/) * [Using automation blueprints](https://www.home-assistant.io/docs/automation/using_blueprints/) * [Editor](https://www.home-assistant.io/docs/automation/editor/) * [Triggers](https://www.home-assistant.io/docs/automation/trigger/) * [Conditions](https://www.home-assistant.io/docs/automation/condition/) * [Actions](https://www.home-assistant.io/docs/automation/action/) * [Run modes](https://www.home-assistant.io/docs/automation/modes/) * [Automation actions](https://www.home-assistant.io/docs/automation/services/) * [Templates](https://www.home-assistant.io/docs/automation/templating/) * [YAML](https://www.home-assistant.io/docs/automation/yaml/) * [Troubleshooting automation](https://www.home-assistant.io/docs/automation/troubleshooting/) * [Scenes](https://www.home-assistant.io/docs/scene/) * [Editor](https://www.home-assistant.io/docs/scene/editor/) * [Blueprints](https://www.home-assistant.io/docs/blueprint/) * [Tutorial](https://www.home-assistant.io/docs/blueprint/tutorial/) * [Blueprint schema](https://www.home-assistant.io/docs/blueprint/schema/) * [Selectors](https://www.home-assistant.io/docs/blueprint/selectors/) * [Scripts](https://www.home-assistant.io/docs/scripts/) * [Actions](https://www.home-assistant.io/docs/scripts/perform-actions/) * [Conditions](https://www.home-assistant.io/docs/scripts/conditions/) * [Dashboards](https://www.home-assistant.io/dashboards) * Dashboard basics * [Introduction](https://www.home-assistant.io/dashboards/) * [Dashboard types](https://www.home-assistant.io/dashboards/dashboards/) * [Views](https://www.home-assistant.io/dashboards/views/) * [Cards](https://www.home-assistant.io/dashboards/cards/) * [Badges](https://www.home-assistant.io/dashboards/badges/) * View types * [Masonry](https://www.home-assistant.io/dashboards/masonry/) * [Panel](https://www.home-assistant.io/dashboards/panel/) * [Sections (default)](https://www.home-assistant.io/dashboards/sections/) * [Sidebar](https://www.home-assistant.io/dashboards/sidebar/) * Card types * [Activity](https://www.home-assistant.io/dashboards/logbook/) * [Alarm panel](https://www.home-assistant.io/dashboards/alarm-panel/) * [Area](https://www.home-assistant.io/dashboards/area/) * [Button](https://www.home-assistant.io/dashboards/button/) * [Calendar](https://www.home-assistant.io/dashboards/calendar/) * [Clock](https://www.home-assistant.io/dashboards/clock/) * [Conditional](https://www.home-assistant.io/dashboards/conditional/) * [Energy cards](https://www.home-assistant.io/dashboards/energy/) * [Entities](https://www.home-assistant.io/dashboards/entities/) * [Entity](https://www.home-assistant.io/dashboards/entity/) * [Entity filter](https://www.home-assistant.io/dashboards/entity-filter/) * [Gauge](https://www.home-assistant.io/dashboards/gauge/) * [Glance](https://www.home-assistant.io/dashboards/glance/) * [Grid](https://www.home-assistant.io/dashboards/grid/) * [Heading](https://www.home-assistant.io/dashboards/heading/) * [History graph](https://www.home-assistant.io/dashboards/history-graph/) * [Horizontal stack](https://www.home-assistant.io/dashboards/horizontal-stack/) * [Humidifier](https://www.home-assistant.io/dashboards/humidifier/) * [Light](https://www.home-assistant.io/dashboards/light/) * [Map](https://www.home-assistant.io/dashboards/map/) * [Markdown](https://www.home-assistant.io/dashboards/markdown/) * [Media control](https://www.home-assistant.io/dashboards/media-control/) * [Picture](https://www.home-assistant.io/dashboards/picture/) * [Picture elements](https://www.home-assistant.io/dashboards/picture-elements/) * [Picture entity](https://www.home-assistant.io/dashboards/picture-entity/) * [Picture glance](https://www.home-assistant.io/dashboards/picture-glance/) * [Plant status](https://www.home-assistant.io/dashboards/plant-status/) * [Sensor](https://www.home-assistant.io/dashboards/sensor/) * [Statistic](https://www.home-assistant.io/dashboards/statistic/) * [Statistics graph](https://www.home-assistant.io/dashboards/statistics-graph/) * [Thermostat](https://www.home-assistant.io/dashboards/thermostat/) * [Tile](https://www.home-assistant.io/dashboards/tile/) * [To-do list](https://www.home-assistant.io/dashboards/todo-list/) * [Vertical stack](https://www.home-assistant.io/dashboards/vertical-stack/) * [Weather forecast](https://www.home-assistant.io/dashboards/weather-forecast/) * [Webpage](https://www.home-assistant.io/dashboards/iframe/) * Advanced * [Features](https://www.home-assistant.io/dashboards/features/) * [Headers & footers](https://www.home-assistant.io/dashboards/header-footer/) * [Actions](https://www.home-assistant.io/dashboards/actions/) * [Developing custom cards](https://developers.home-assistant.io/docs/frontend/custom-ui/custom-card/) * [Voice assistants](https://www.home-assistant.io/voice_control/) * [Assist up and running](https://www.home-assistant.io/voice_control/) * [Getting started - Local](https://www.home-assistant.io/voice_control/voice_remote_local_assistant/) * [Getting started - Home Assistant Cloud](https://www.home-assistant.io/voice_control/voice_remote_cloud_assistant/) * [Best practices](https://www.home-assistant.io/voice_control/best_practices) * [Exposing entities to Assist](https://www.home-assistant.io/voice_control/voice_remote_expose_devices/) * [Assigning devices to areas and areas to floors](https://www.home-assistant.io/voice_control/assign_areas_floors/) * [Aliases for entities, areas and floors](https://www.home-assistant.io/voice_control/aliases/) * [Talking to Assist - Sentences starter pack](https://www.home-assistant.io/voice_control/builtin_sentences/) * [Expanding Assist](https://www.home-assistant.io/voice_control/expanding_assist) * [Creating a personality with AI](https://www.home-assistant.io/voice_control/assist_create_open_ai_personality/) * [Custom sentences](https://www.home-assistant.io/voice_control/custom_sentences/) * [Assist for Android](https://www.home-assistant.io/voice_control/android/) * [Assist for Apple](https://www.home-assistant.io/voice_control/apple/) * Experiment with Assist setups * [The Home Assistant Approach to Wake Words](https://www.home-assistant.io/voice_control/about_wake_word/) * [Wake words for Assist](https://www.home-assistant.io/voice_control/create_wake_word/) * [Tutorial: ESP32-S3-BOX voice assistant](https://www.home-assistant.io/voice_control/s3_box_voice_assistant/) * [Tutorial: Customize the S3-BOX](https://www.home-assistant.io/voice_control/s3-box-customize/) * [Tutorial: $13 voice assistant](https://www.home-assistant.io/voice_control/thirteen-usd-voice-remote/) * [Tutorial: World's most private voice assistant](https://www.home-assistant.io/voice_control/worlds-most-private-voice-assistant/) * [Tutorial: Your daily summary by Assist](https://www.home-assistant.io/voice_control/assist_daily_summary/) * [Starting Assist from your dashboard](https://www.home-assistant.io/voice_control/start_assist_from_dashboard/) * [Contribute to the Voice initiative](https://www.home-assistant.io/voice_control/contribute-voice/) * Troubleshooting * [Troubleshooting Assist](https://www.home-assistant.io/voice_control/troubleshooting/) * [Troubleshooting the ESP32-S3-BOX](https://www.home-assistant.io/voice_control/troubleshooting_the_s3_box/) * [Using Piper TTS in automations](https://www.home-assistant.io/voice_control/using_tts_in_automation/) * [Organization](https://www.home-assistant.io/docs/organizing/) * [Grouping your assets](https://www.home-assistant.io/docs/organizing/) * [Working with tables](https://www.home-assistant.io/docs/organizing/tables) * [Areas](https://www.home-assistant.io/docs/organizing/areas/) * [Floors](https://www.home-assistant.io/docs/organizing/floors/) * [Labels](https://www.home-assistant.io/docs/organizing/labels/) * [Categories](https://www.home-assistant.io/docs/organizing/categories/) * [Icons](https://www.home-assistant.io/docs/frontend/icons/) * [Home energy management](https://www.home-assistant.io/docs/energy/) * [Electricity grid](https://www.home-assistant.io/docs/energy/electricity-grid/) * [Solar panels](https://www.home-assistant.io/docs/energy/solar-panels/) * [Individual devices](https://www.home-assistant.io/docs/energy/individual-devices/) * [FAQ](https://www.home-assistant.io/docs/energy/faq/) * [Common tasks](https://www.home-assistant.io/common-tasks/general/) * [Installation independent](https://www.home-assistant.io/common-tasks/general/) * [Home Assistant Operating System](https://www.home-assistant.io/common-tasks/os/) * [Home Assistant Container](https://www.home-assistant.io/common-tasks/container/) * [General troubleshooting](https://www.home-assistant.io/docs/troubleshooting_general/) * [Advanced configuration](https://www.home-assistant.io/docs/configuration/) * [YAML syntax](https://www.home-assistant.io/docs/configuration/yaml/) * [Basic information](https://www.home-assistant.io/docs/configuration/basic/) * [Customizing entities](https://www.home-assistant.io/docs/configuration/customizing-devices/) * [Troubleshooting configuration](https://www.home-assistant.io/docs/configuration/troubleshooting/) * [Security check points](https://www.home-assistant.io/docs/configuration/securing/) * [Remote access](https://www.home-assistant.io/docs/configuration/remote/) * [Splitting up the configuration](https://www.home-assistant.io/docs/configuration/splitting_configuration/) * [Packages](https://www.home-assistant.io/docs/configuration/packages/) * [Storing secrets](https://www.home-assistant.io/docs/configuration/secrets/) * [Events](https://www.home-assistant.io/docs/configuration/events/) * [State and state object](https://www.home-assistant.io/docs/configuration/state_object/) * [Entities and domains](https://www.home-assistant.io/docs/configuration/entities_domains/) * [Templating](https://www.home-assistant.io/docs/configuration/templating/) * [Entity component platform options](https://www.home-assistant.io/docs/configuration/platform_options/) * [Authentication](https://www.home-assistant.io/docs/authentication/) * [Auth providers](https://www.home-assistant.io/docs/authentication/providers/) * [Multi-factor authentication](https://www.home-assistant.io/docs/authentication/multi-factor-auth/) * [I'm locked out](https://www.home-assistant.io/docs/locked_out/) * [Backend](https://www.home-assistant.io/docs/backend/) * [User interface](https://www.home-assistant.io/docs/frontend/) * [Database](https://www.home-assistant.io/docs/backend/database/) * [Tools and helpers](https://www.home-assistant.io/docs/tools/) * [Developer tools](https://www.home-assistant.io/docs/tools/dev-tools/) * [Quick bar](https://www.home-assistant.io/docs/tools/quick-bar/) * [check\_config](https://www.home-assistant.io/docs/tools/check_config/) * [iOS and Android apps](https://companion.home-assistant.io/docs) * [MQTT](https://www.home-assistant.io/integrations/mqtt) * [Broker](https://www.home-assistant.io/integrations/mqtt/#broker-configuration) * [Certificate](https://www.home-assistant.io/integrations/mqtt/#advanced-broker-configuration) * [Discovery](https://www.home-assistant.io/integrations/mqtt/#mqtt-discovery) * [Publish action](https://www.home-assistant.io/integrations/mqtt/#publish--dump-actions) * [Birth and last will messages](https://www.home-assistant.io/integrations/mqtt/#birth-and-last-will-messages) * [Testing your setup](https://www.home-assistant.io/integrations/mqtt/#testing-your-setup) * [Logging](https://www.home-assistant.io/integrations/mqtt/#logging) * Official hardware * [Home Assistant Green](https://support.nabucasa.com/hc/categories/24638797677853) * [Home Assistant Connect ZBT-1](https://support.nabucasa.com/hc/categories/24734620813469) * [Home Assistant Connect ZBT-2](https://support.nabucasa.com/hc/categories/29400540866973) * [Home Assistant Connect ZWA-2](https://support.nabucasa.com/hc/categories/28669861145885) * [Home Assistant Yellow](https://support.nabucasa.com/hc/categories/24734575925149) * [Home Assistant Voice Preview Edition](https://support.nabucasa.com/hc/categories/24451727188125) --- # Z-Wave - Home Assistant The **Z-Wave** integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [\[Learn more\]](https://www.home-assistant.io/getting-started/concepts-terminology/#integrations) allows you to control a Z-Wave network from Home Assistant via the [Z-Wave JS](https://zwave-js.github.io/node-zwave-js/#/) driver. Getting started[](https://www.home-assistant.io/integrations/zwave_js#getting-started) --------------------------------------------------------------------------------------- This section shows how to set up a Z-Wave network and how to add a Z-Wave end device to that network. A Z-Wave network in Home Assistant includes the following elements: * a Z-Wave adapter (for example, [Home Assistant Connect ZWA-2](https://www.home-assistant.io/connect/zwa-2) ) * a Z-Wave server (for example, the **Z-Wave JS** add-on) * this Z-Wave integration * Z-Wave end devices ### Setting up a Z-Wave server in Home Assistant[](https://www.home-assistant.io/integrations/zwave_js#setting-up-a-z-wave-server-in-home-assistant) This section shows how to set up a Z-Wave server using the **Z-Wave JS** add-on in Home Assistant. For other ways to set up a Z-Wave server, refer to the [advanced installation instructions](https://www.home-assistant.io/integrations/zwave_js#advanced-installation-instructions) . Once you have set up the Z-Wave server, you can [add devices to the network](https://www.home-assistant.io/integrations/zwave_js#adding-a-new-device-to-the-z-wave-network) . #### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites) * A [supported Z-Wave adapter](https://www.home-assistant.io/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules) . * First-time user? For recommendations, refer to the [what-to-buy-section](https://www.home-assistant.io/integrations/zwave_js#which-z-wave-adapter-should-i-buy) . #### To set up a Z-Wave server[](https://www.home-assistant.io/integrations/zwave_js#to-set-up-a-z-wave-server) 1. Open the Home Assistant user interface. 2. Plug the Z-Wave adapter into the device running Home Assistant. * Most likely, your adapter will be recognized automatically. * In the dialog, select **Recommended installation**. * This will install the Z-Wave JS add-on on the Home Assistant server. * Add the device to an areaAn area in Home Assistant is a [logical grouping](https://www.home-assistant.io/docs/organizing/) of devices and entities that are meant to match areas (or rooms) in the physical world: your home. For example, the `living room` area groups devices and entities in your living room. [\[Learn more\]](https://www.home-assistant.io/docs/organizing/areas/) and select **Finish**. * **Troubleshooting**: If your adapter is not recognized, follow [these steps](https://www.home-assistant.io/integrations/zwave_js#my-z-wave-adapter-isnt-recognized-automatically-during-setup) . 3. Wait for the installation to complete. 4. Depending on your Home Assistant version, you may be prompted for network security keys. * If you are using Z-Wave for the first time, leave all the fields empty and select **Submit**. The system will generate network security keys for you. * If this Z-Wave adapter has already been paired with secure devices, you need to enter the previously used network key as the S0 network key. S2 security keys will be automatically generated for you. * Make sure that you keep a backup of these keys in a safe place in case you need to move your Z-Wave adapter to another device. Copy and paste them somewhere safe. 5. Wait for the Z-Wave JS add-on to start up. 6. Once the installation is complete, the **Device info** of the Z-Wave adapter is shown. * You successfully installed the Z-Wave integration and the Z-Wave JS add-on. * You can now [add devices](https://www.home-assistant.io/integrations/zwave_js/#adding-a-new-device-to-the-z-wave-network) to the Z-Wave network. Note While your Z-Wave mesh is permanently stored on your adapter, the additional metadata is not. When the Z-Wave integration starts up the first time, it will interview your entire Z-Wave network. Depending on the number of devices paired with the Z-Wave adapter, this can take a while. You can speed up this process by manually waking up your battery-powered devices. Most of the time, this is a button press on those devices (see their manual). It is not necessary to exclude and re-include devices from the mesh. ### Adding a new device to the Z-Wave network[](https://www.home-assistant.io/integrations/zwave_js#adding-a-new-device-to-the-z-wave-network) 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the Z-Wave integration. * Then, on the entry of the hub, select to open the device info page. 3. Select **Add device**. * The Z-Wave adapter is now in inclusion mode. 4. Check, if your device supports SmartStart: * On the packaging, check for the SmartStart label. * Find the QR code. It can be on the packaging or on the device itself. 5. Depending on whether your device supports SmartStart, follow the steps in either option 1 or 2: * **Option 1: your device supports SmartStart**: * Make sure the device is turned off. * Select **Scan QR code** and scan the QR code on your device. * **Troubleshooting**: If scanning does not work (for example due to missing HTTPS), paste the QR code content as text from a different QR reader and select **Submit**. * If the device supports Z-Wave Long Range, you’re prompted to choose the network type. * **Long Range**: If it is far away from other devices, or that spot has had connection issues in the past. It might also help preserve battery life. * **Mesh**: If you already have a mesh network. Adding it can enhance coverage and reliability of this network. * You can always remove and pair the device again to switch to the other network type. * Turn the device on and set it into inclusion mode. * If it was already on, you might need to power-cycle it. * **Option 2: your device does not support SmartStart**: * Set the device in inclusion mode. Refer to the device manual to see how this is done. * If your device is included using S2 security, you may be prompted to enter a PIN number provided with your device. Often, this PIN is provided with the documentation _and_ is also printed on the device itself. For more information on secure inclusion, refer to [this section](https://www.home-assistant.io/integrations/zwave_js/#should-i-use-secure-inclusion) . 6. The UI should confirm that the device was added. After a short while (seconds to minutes), the entities should also be created. 7. **Troubleshooting**: If the adapter fails to add/find your device, cancel the inclusion process. * In some cases, it might help to first [remove](https://www.home-assistant.io/integrations/zwave_js/#removing-a-device-from-the-z-wave-network) a device (exclusion) before you add it, even when the device has not been added to this Z-Wave network yet. * Another approach would be to factory reset the device. Refer to the device manual to see how this is done. **Important:** 1. **Do not move your Z-Wave adapter to include devices.** Moving the adapter is no longer necessary and leads to broken routes. 2. **Do not initiate device inclusion from the Z-Wave adapter itself.** This is no longer supported. ### Removing a device from the Z-Wave network[](https://www.home-assistant.io/integrations/zwave_js#removing-a-device-from-the-z-wave-network) Do this before using the device with another adapter, or when you don’t use the device anymore. It removes the device from the Z-Wave network stored on the adapter. It also removes the device and all its entities from Home Assistant. You can not join a device to a new network if it is still paired with an adapter. 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the **Z-Wave** integration. * Then, select the cogwheel . 3. Select **Remove a device**, then **Start exclusion**. * The Z-Wave adapter is now in exclusion mode. 4. Put the device you want to remove in exclusion mode. Refer to its manual how this is done. 5. The UI should confirm that the device was removed and the device and entities will be removed from Home Assistant. Migrating a Z-Wave network to a new adapter[](https://www.home-assistant.io/integrations/zwave_js#migrating-a-z-wave-network-to-a-new-adapter) ----------------------------------------------------------------------------------------------------------------------------------------------- Do this if you have an existing Z-Wave network and want to replace its adapter with a new adapter. The Z-Wave integration with all its entities will stay in Home Assistant. The new adapter is added to Home Assistant and paired with the existing network. Tip You cannot run two Z-Wave adapters simultaneously using the same add-on. If you only run one add-on, you need to migrate the network. If you want to run two adapters, you would need to install another add-on, such as Z-Wave JS UI. ### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites-1) * Administrator rights in Home Assistant #### Device-specific prerequisites[](https://www.home-assistant.io/integrations/zwave_js#device-specific-prerequisites) Migrating from a 500 series adapter Before starting migration, you need to update the adapter to SDK 6.61+ * Check the documentation of your device to see if and how they can be updated. * [Steps to update Aeotec Z-Stick 5](https://aeotec.freshdesk.com/support/solutions/articles/6000252294-z-stick-gen5-v1-02-firmware-update) . Migrating from a Nortek HUSBZB-1 adapter There is no easy way to update that device. * You need to set up a new network. * If you are comfortable with soldering: * Some users have reported that they were able to upgrade the firmware of the **Nortek HUSBZB-1** with [this update procedure (requires soldering)](https://community.hubitat.com/t/guide-nortek-husbzb-1-nvm-backup-restore-and-updating-z-wave-firmware/48012) . * The procedure is very involved. Most likely, starting from scratch is quicker. ### To migrate a Z-Wave network to a new adapter[](https://www.home-assistant.io/integrations/zwave_js#to-migrate-a-z-wave-network-to-a-new-adapter) 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Connect your new adapter. * Plug in your new adapter. * **Result**: The adapter should be discovered and show up in the **Discovered section**. * Select **Add** and follow the instructions on screen. * **Troubleshooting**: Not all devices can be discovered automatically. If your device does not show up, follow these steps: 1. Select the **Z-Wave** integration. 2. Then, select the cogwheel . 3. Under **Backup and restore**, select **Migrate adapter**. 4. Select **Migrate to a new adapter**. * To confirm, select **Submit**. 3. When the **Unplug your adapter** dialog shows up, unplug your old adapter. * It is important to remove the old device now, as it might interfere with the new one. Even though it might not throw an error immediately, it might cause issues. 4. Follow the steps on screen. 5. Once the migration has completed, check if you want to rename the adapter. If you have previously changed the name, the new adapter might keep the name of the old adapter. * In the top-left corner, select the back button to go back to the integration page. * In the list of devices, check the device name. * To change the device name, select the button. The video below shows how a Z-Wave network is migrated to a Home Assistant Connect ZWA-2: Overriding the radio frequency region of the adapter in the Z-Wave JS add-on[](https://www.home-assistant.io/integrations/zwave_js#overriding-the-radio-frequency-region-of-the-adapter-in-the-z-wave-js-add-on) ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The frequency used by Z-Wave devices depends on your region. For 700 and 800 series adapters, this frequency can be changed. The frequency of end devices cannot, so you need to make sure to buy devices specific to your region. If you are using the Z-Wave JS add-on, Home Assistant automatically changes the radio frequency region to match the region/country you’re in. If needed, you can override this setting. ### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites-2) * Administrator rights in Home Assistant * All your Z-Wave devices must be specified for that region * Note: this procedure only applies if your adapter is [set up using the Z-Wave JS add-on](https://www.home-assistant.io/integrations/zwave_js#to-set-a-up-a-z-wave-server) ### To override the radio frequency region of your Z-Wave adapter[](https://www.home-assistant.io/integrations/zwave_js#to-override-the-radio-frequency-region-of-your-z-wave-adapter) 1. Go to [**Settings** > **Add-ons** > **Z-Wave JS**](https://my.home-assistant.io/redirect/supervisor_addon?addon=core_zwave_js) . 2. Open the **Configuration** tab. 3. In the **Options** section, select the **Radio Frequency Region**. * **Automatic** sets the region based on the location defined under [**Settings** > **System** > **General**](https://my.home-assistant.io/redirect/general) . * For regions where Long Range is available, it uses Long Range if the adapter supports it. * If you set regions manually, choose one of the Long Range options where available: * **Europe (Long Range)** or **USA (Long Range)**. * Even with the Long Range option selected, you can still add devices that don’t support Long Range. 4. To apply your changes, select **Save**. * Your Z-Wave adapter is now ready to communicate with devices that were specified for your chosen region. 5. To return to the default setting and use the region defined by Home Assistant, under **Radio Frequency Region** choose **Automatic**. Backing up your Z-Wave network[](https://www.home-assistant.io/integrations/zwave_js#backing-up-your-z-wave-network) --------------------------------------------------------------------------------------------------------------------- It’s recommended to create a backup before making any major changes to your Z-Wave network. For example, before migrating from one adapter to another, or before resetting your adapter. The backup stores your Z-Wave adapter’s non-volatile memory (NVM), which contains your network information including paired devices. It is stored in a binary file that you can download. ### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites-3) * Administrator rights in Home Assistant ### To backup your Z-Wave network[](https://www.home-assistant.io/integrations/zwave_js#to-backup-your-z-wave-network) 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the **Z-Wave** integration. * Then, select the cogwheel . 3. Under **Backup and restore**, select **Download backup**. * **Result**: The backup file is downloaded to the device from which you initiated the download. 4. Done! Store the backup file somewhere safe in case you need it later to restore your Z-Wave network. Restoring your Z-Wave network from a backup[](https://www.home-assistant.io/integrations/zwave_js#restoring-your-z-wave-network-from-a-backup) ----------------------------------------------------------------------------------------------------------------------------------------------- You can restore your Z-Wave network from a backup. ### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites-4) * Administrator rights in Home Assistant * Have a [backup](https://www.home-assistant.io/integrations/zwave_js#backing-up-your-z-wave-network) downloaded ### Restoring a Z-Wave network from backup[](https://www.home-assistant.io/integrations/zwave_js#restoring-a-z-wave-network-from-backup) 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the **Z-Wave** integration. * Then, select the cogwheel . 3. Under **Backup and restore**, select **Restore from backup**. * Select the backup you want to restore from. * **Result**: The Z-Wave network is being restored and the devices that were part of the network should show up again. Updating the firmware of your Z-Wave device[](https://www.home-assistant.io/integrations/zwave_js#updating-the-firmware-of-your-z-wave-device) ----------------------------------------------------------------------------------------------------------------------------------------------- Adapters and devices with the Firmware Update Metadata Command Class allow you to update the firmware by uploading a firmware file. In those cases, you can start the firmware update from the device page in Home Assistant. Refer to the documentation of the device manufacturer to find the corresponding firmware file. An example is the [firmware page by Zooz](https://www.support.getzooz.com/kb/article/1158-zooz-ota-firmware-files/) . Note **Risk of damage to the device due to firmware update** A firmware update can damage your Z-Wave device. * Before updating your Z-Wave device, make sure an update is necessary, and that you have the correct firmware file matching your device. * Once you have started the update process, you must not interrupt the update process but let it complete. The Home Assistant and Z-Wave JS teams do not take any responsibility for any damages to your device as a result of the firmware update and will not be able to help you if you render your device useless due to firmware update. ### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites-5) * Administrator rights in Home Assistant * Downloaded the firmware file from the manufacturer website ### To update firmware of a Z-Wave device[](https://www.home-assistant.io/integrations/zwave_js#to-update-firmware-of-a-z-wave-device) 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the **Z-Wave** integration. * Then, on the entry of the hub, select to open the device info page. 3. Under **Device info**, select **Update**. 4. Select the firmware file that you previously downloaded to your computer. * **Notice: Risk of damage to the device** * Make sure you select the correct firmware file. * An incorrect firmware file can damage your device. * Once you start the update process, you must wait for the update to complete. * An interrupted update can damage your device. 5. Select **Begin firmware update** and wait for it to complete. Resetting a Z-Wave adapter[](https://www.home-assistant.io/integrations/zwave_js#resetting-a-z-wave-adapter) ------------------------------------------------------------------------------------------------------------- It is recommended to back up your Z-Wave network before resetting the device. * The adapter will forget all devices it is paired with. * All Z-Wave devices for this network will be removed from Home Assistant. * If there are any devices still paired with the adapter when it is reset, they will have to go through the exclusion process before they can be re-paired. * The device firmware will remain on the device. ### Prerequisites[](https://www.home-assistant.io/integrations/zwave_js#prerequisites-6) * Administrator rights on Home Assistant * [Backup your Z-Wave network](https://www.home-assistant.io/integrations/zwave_js#backing-up-your-z-wave-network) * [Remove all devices that are paired with your adapter from the network](https://www.home-assistant.io/integrations/zwave_js#removing-a-device-from-the-z-wave-network) . * Removing can be done by any adapter, not just the one that originally managed the network. In theory, this could also be done later. ### To reset a Z-Wave adapter[](https://www.home-assistant.io/integrations/zwave_js#to-reset-a-z-wave-adapter) 1. In Home Assistant, go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the **Z-Wave** integration. Then, select the controller. 3. Under **Device info**, select the three-dot menu, then select **Factory reset**. ![Screenshot showing the device panel of a Z-Wave adapter](https://www.home-assistant.io/images/integrations/z-wave/z-wave-controller-commands.png) 4. On the device info page, check the **Activity** panel. When you see that the status entity became unavailable, the reset process is finished. * You can now unplug the adapter and use it to start a new network, or pass it on to someone else. 5. If you no longer need the Z-Wave integration, you can [remove it](https://www.home-assistant.io/integrations/zwave_js#removing-z-wave-js-from-home-assistant) from Home Assistant. Special Z-Wave entities[](https://www.home-assistant.io/integrations/zwave_js#special-z-wave-entities) ------------------------------------------------------------------------------------------------------- The Z-Wave integration provides several special entities, some of which are available for every Z-Wave device, and some of which are conditional based on the device. ### Entities available for every Z-Wave device[](https://www.home-assistant.io/integrations/zwave_js#entities-available-for-every-z-wave-device) 1. **Node status** sensor: This sensor shows the node status for a given Z-Wave device. The sensor is disabled by default. The available node statuses are explained in the [Z-Wave JS documentation](https://zwave-js.github.io/node-zwave-js/#/api/node?id=status) . They can be used in state change automations. For example to ping a device when it is dead, or refresh values when it wakes up. 2. **Ping** button: This button can be pressed to ping a device. It is an alternative to the `zwave_js.ping` action. 3. **Adapter/node statistics** sensors: Z-Wave JS collects statistics about communications between [nodes](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotstatistics-updatedquot) and the [adapter](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=quotstatistics-updatedquot) . The statistics can be used to troubleshoot RF issues in your environment. These statistics are available in the network configuration and device info panels. But they are also available as sensors which are disabled by default. ### Conditional entities[](https://www.home-assistant.io/integrations/zwave_js#conditional-entities) 1. Button to **manually idle notifications**: Any Notification Command Class (CC) values on a device that have an idle state will get a corresponding button entity. This button entity can be used to manually idle a notification when it doesn’t automatically clear on its own. A device can have multiple Notification CC values. For example one for detecting smoke and one for detecting carbon monoxide. Using advanced features (UI only)[](https://www.home-assistant.io/integrations/zwave_js#using-advanced-features-ui-only) ------------------------------------------------------------------------------------------------------------------------- While the integration aims to provide as much functionality as possible through existing Home Assistant constructs (entities, states, automations, actions, etc.), there are some features that are only available through the UI. All of these features can be accessed either in the Z-Wave integration configuration panel or in a Z-Wave device’s device panel. ### Integration configuration panel[](https://www.home-assistant.io/integrations/zwave_js#integration-configuration-panel) The following features can be accessed from the integration configuration panel: ![Z-Wave integration configuration panel](https://www.home-assistant.io/images/integrations/z-wave/z-wave-integration-config-panel.png) * **Add device:** Allows you to pre-provision a SmartStart device or start the inclusion process for adding a new device to your network. * **Remove device:** Starts the exclusion process for removing a device from your network. * **Rebuild network routes:** Discovers new routes between the adapter and the device. This is useful when devices or the adapter have moved to a new location, or if you are having significant problems with your network, but it also generates a lot of network traffic and should be used sparingly. * **[Adapter statistics](https://zwave-js.github.io/node-zwave-js/#/api/controller?id=quotstatistics-updatedquot) :** Provides statistics about communication between the adapter and other devices, allowing you to troubleshoot your network’s RF quality. * **Third-party data opt-in/out:** Allows you to opt-in or out of telemetry that the Z-Wave JS project collects to help inform development decisions, influence manufacturers, etc. This telemetry is disabled by default and has to be opted in to be activated. ### Integration menu[](https://www.home-assistant.io/integrations/zwave_js#integration-menu) Some features can be accessed from the menu of integration itself. As they are not specific to Z-Wave, they are not described here in detail. ![Z-Wave integration configuration panel](https://www.home-assistant.io/images/integrations/z-wave/z-wave-integration-menu.png) * **[Download diagnostics](https://www.home-assistant.io/docs/configuration/troubleshooting/#download-diagnostics) :** Exports a JSON file describing the entities of all devices registered with this integration. #### Network devices[](https://www.home-assistant.io/integrations/zwave_js#network-devices) The following features can be accessed from the device panel of any Z-Wave device on your network aside from the adapter: ![Z-Wave device panel](https://www.home-assistant.io/images/integrations/z-wave/z-wave-device-info.png) * **Configure:** Provides an easy way to look up and update configuration parameters for the device. While there is an existing action for setting configuration parameter values, this UI may sometimes be quicker to use for one-off changes. * **Re-interview:** Forces the device to go through the interview process again so that Z-Wave-JS can discover all of its capabilities. Can be helpful if you don’t see all the expected entities for your device. * **Rebuild routes:** Discovers new routes between the adapter and the device. Use this if you think you are experiencing unexpected delays or RF issues with your device. Your device may be less responsive during this process. * **Delete:** Opens a dialog with the following options for removing the device: * Removing it from the network using exclusion * Removing a failed device from the adapter without excluding it from the network * **[Statistics](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotstatistics-updatedquot) :** Provides statistics about communication between this device and the adapter, allowing you to troubleshoot RF issues with the device. * **Update:** Updates a device’s firmware using a manually uploaded firmware file. Only some devices support this feature (adapters and devices with the Firmware Update Metadata Command Class). * **Download diagnostics:** Exports a JSON file describing the entities of this specific device. Actions[](https://www.home-assistant.io/integrations/zwave_js#actions) ----------------------------------------------------------------------- ### Action zwave\_js.set\_config\_parameter[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsset_config_parameter) This action will update a configuration parameter. To update multiple partial parameters in a single call, use the `zwave_js.bulk_set_partial_config_parameters` action. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Entity (or list of entities) to set the configuration parameter on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `device_id` | no | Device ID (or list of device IDs) to set the configuration parameter on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `area_id` | no | Area ID (or list of area IDs) for devices/entities to set the configuration parameter on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `parameter` | yes | The parameter number or the name of the property. The name of the property is case sensitive. | | `bitmask` | no | The bitmask for a partial parameter in hex (0xff) or decimal (255) format. If the name of the parameter is provided, this is not needed. Cannot be combined with value\_size or value\_format. | | `value` | yes | The target value for the parameter as the integer value or the state label. The state label is case sensitive. | | `value_size` | no | The size of the target parameter value, either 1, 2, or 4. Used in combination with value\_format when a config parameter is not defined in your device’s configuration file. Cannot be combined with bitmask. | | `value_format` | no | The format of the target parameter value, 0 for signed integer, 1 for unsigned integer, 2 for enumerated, 3 for bitfield. Used in combination with value\_size when a config parameter is not defined in your device’s configuration file. Cannot be combined with bitmask. | #### Examples of setting a single parameter value[](https://www.home-assistant.io/integrations/zwave_js#examples-of-setting-a-single-parameter-value) Let’s use parameter 31 for [this device](https://devices.zwave-js.io/?jumpTo=0x000c:0x0203:0x0001:0.0) as an example to show examples of different ways that the `LED 1 Blink Status (bottom)` partial parameter can be set. Note that in places where we are using different values for the same key, the different values are interchangeable across the examples. We can, for instance, use `1` or `Blink` interchangeably for the `value` in all of the examples. Example 1: action: zwave_js.set_config_parameter target: entity_id: switch.fan data: parameter: 31 bitmask: 0x01 value: 1 Example 2: action: zwave_js.set_config_parameter target: entity_id: switch.fan data: parameter: 31 bitmask: 1 value: "Blink" Example 3: action: zwave_js.set_config_parameter target: entity_id: switch.fan data: entity_id: switch.fan parameter: "LED 1 Blink Status (bottom)" value: "Blink" ### Action zwave\_js.bulk\_set\_partial\_config\_parameters[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsbulk_set_partial_config_parameters) This action will bulk set multiple partial configuration parameters. Be warned that correctly using this action requires advanced knowledge of Z-Wave. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Entity (or list of entities) to bulk set partial configuration parameters on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `device_id` | no | Device ID (or list of device IDs) to bulk set partial configuration parameters on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `area_id` | no | Area ID (or list of area IDs) for devices/entities to bulk set partial configuration parameters on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `parameter` | yes | The parameter number of the property. The name of the property is case sensitive. | | `value` | yes | Either the raw integer value that you want to set for the entire parameter, or a dictionary where the keys are either the bitmasks (in integer or hex form) or the partial parameter name and the values are the value you want to set on each partial (either the integer value or a named state when applicable). Note that when using a dictionary, and bitmasks that are not provided will be set to their currently cached values. | #### Examples of bulk setting partial parameter values[](https://www.home-assistant.io/integrations/zwave_js#examples-of-bulk-setting-partial-parameter-values) Let’s use parameter 21 for [this device](https://devices.zwave-js.io/?jumpTo=0x031e:0x000a:0x0001:0.0) as an example to show how partial parameters can be bulk set. In this case, we want to set `0xff` to `127`, `0x7f00` to `10`, and `0x8000` to `1` (or the raw value of `4735`). Note When using the dictionary format to map the partial parameter to values, the cached values for the missing partial parameters will be used. So in examples 2, 3, 4, and 5, the action would use the cached value for partial parameters `0xff0000`, `0x3f000000`, and `0x40000000` because new values haven’t been specified. If you send the raw integer value, it is assumed that you have calculated the full value, so in example 1, partial parameters `0xff0000`, `0x3f000000`, and `0x40000000` would all be set to `0`. Example 1: action: zwave_js.bulk_set_partial_config_parameters target: entity_id: switch.fan data: parameter: 21 value: 4735 Example 2: action: zwave_js.bulk_set_partial_config_parameters target: entity_id: switch.fan data: parameter: 21 value: 0xff: 127 0x7f00: 10 0x8000: 1 Example 3: action: zwave_js.bulk_set_partial_config_parameters target: entity_id: switch.fan data: parameter: 21 value: 255: 127 32512: 10 32768: 1 Example 4: action: zwave_js.bulk_set_partial_config_parameters target: entity_id: switch.fan data: parameter: 21 value: 255: 127 32512: 10 32768: "Fine" Example 5: action: zwave_js.bulk_set_partial_config_parameters target: entity_id: switch.fan data: parameter: 21 value: "Quick Strip Effect: Hue Color Wheel / Color Temp": 127 "Quick Strip Effect Intensity": 10 "Quick Strip Effect Intensity Scale": "Fine" ### Action zwave\_js.refresh\_value[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsrefresh_value) This action will refresh the value(s) for an entity. This action will generate extra traffic on your Z-Wave network and should be used sparingly. Updates from devices on battery may take some time to be received. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | yes | Entity or list of entities to refresh values for. | | `refresh_all_values` | no | Whether all values should be refreshed. If `false`, only the primary value will be refreshed. If `true`, all watched values will be refreshed. | ### Action zwave\_js.set\_value[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsset_value) This action will set a value on a Z-Wave device. It is for advanced use cases where you need to modify the state of a node and can’t do it using native Home Assistant entity functionality. Be warned that correctly using this action requires advanced knowledge of Z-Wave. The action provides minimal validation and blindly calls the Z-Wave JS API, so if you are having trouble using it, it is likely because you are providing an incorrect value somewhere. To set a config parameter, you should use the `zwave_js.set_config_parameter` or `zwave_js.bulk_set_partial_config_parameters` action instead of this one. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Entity (or list of entities) to set the value on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `device_id` | no | Device ID (or list of device IDs) to set the value on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `area_id` | no | Area ID (or list of area IDs) for devices/entities to set the value on. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `command_class` | yes | ID of Command Class that you want to set the value for. | | `property` | yes | ID of Property that you want to set the value for. | | `property_key` | no | ID of Property Key that you want to set the value for. | | `endpoint` | no | ID of Endpoint that you want to set the value for. | | `value` | yes | The new value that you want to set. | | `options` | no | Set value options map. Refer to the Z-Wave JS documentation for more information on what options can be set. | | `wait_for_result` | no | Boolean that indicates whether or not to wait for a response from the node. If not included in the payload, the integration will decide whether to wait or not. If set to `true`, note that the action can take a while if setting a value on an asleep battery device. | ### Action zwave\_js.multicast\_set\_value[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsmulticast_set_value) This action will set a value on multiple Z-Wave devices using multicast. It is for advanced use cases where you need to set the same value on multiple nodes simultaneously. Be warned that correctly using this action requires advanced knowledge of Z-Wave. The action provides minimal validation beyond what is necessary to properly call the Z-Wave JS API, so if you are having trouble using it, it is likely because you are providing an incorrect value somewhere. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Entity (or list of entities) to set the value on via multicast. At least two `entity_id` or `device_id` must be resolved if not broadcasting the command. | | `device_id` | no | Device ID (or list of device IDs) to set the value on via multicast. At least two `entity_id` or `device_id` must be resolved if not broadcasting the command. | | `area_id` | no | Area ID (or list of area IDs) for devices/entities to set the value on via multicast. At least two `entity_id` or `device_id` must be resolved if not broadcasting the command. | | `broadcast` | no | Boolean that indicates whether you want the message to be broadcast to all nodes on the network. If you have only one Z-Wave network configured, you do not need to provide a `device_id` or `entity_id` when this is set to true. When you have multiple Z-Wave networks configured, you MUST provide at least one `device_id` or `entity_id` so the action knows which network to target. | | `command_class` | yes | ID of Command Class that you want to set the value for. | | `property` | yes | ID of Property that you want to set the value for. | | `property_key` | no | ID of Property Key that you want to set the value for. | | `endpoint` | no | ID of Endpoint that you want to set the value for. | | `value` | yes | The new value that you want to set. | | `options` | no | Set value options map. Refer to the Z-Wave JS documentation for more information on what options can be set. | ### Action zwave\_js.invoke\_cc\_api[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsinvoke_cc_api) Leverage this action to use the Command Class API directly. In most cases, the `zwave_js.set_value` action will accomplish what you need to, but some Command Classes have API commands that can’t be accessed via that action. Refer to the [Z-Wave JS Command Class documentation](https://zwave-js.github.io/node-zwave-js/#/api/CCs/index) for the available APIs and arguments. Be sure to know what you are doing when calling this action. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Entity (or list of entities) to ping. At least one `entity_id`, `device_id`, or `area_id` must be provided. If `endpoint` is specified, that endpoint will be used to make the CC API call for all devices, otherwise the primary value endpoint will be used for each entity. | | `device_id` | no | Device ID (or list of device IDs) to ping. At least one `entity_id`, `device_id`, or `area_id` must be provided. If `endpoint` is specified, that endpoint will be used to make the CC API call for all devices, otherwise the root endpoint (0) will be used for each device. | | `area_id` | no | Area ID (or list of area IDs) for devices/entities to ping. At least one `entity_id`, `device_id`, or `area_id` must be provided. If `endpoint` is specified, that endpoint will be used to make the CC API call for all devices, otherwise the root endpoint (0) will be used for each `zwave_js` device in the area. | | `command_class` | yes | ID of Command Class that you want to set the value for. | | `endpoint` | no | The endpoint to call the CC API against. | | `method_name` | yes | The name of the method that is being called from the CC API. | | `parameters` | yes | A list of parameters to pass to the CC API method. | ### Action zwave\_js.refresh\_notifications[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsrefresh_notifications) This action will refresh the notifications of a given type on a device that supports the Notification Command Class. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Entity (or list of entities) to refresh notifications for. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `device_id` | no | Device ID (or list of device IDs) to refresh notifications for. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `area_id` | no | Area ID (or list of area IDs) for devices/entities to refresh notifications for. At least one `entity_id`, `device_id`, or `area_id` must be provided. | | `notification_type` | yes | The type of notification to refresh. | | `notification_event` | no | The notification event to refresh. | ### Action zwave\_js.reset\_meter[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsreset_meter) This action will reset the meters on a device that supports the Meter Command Class. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | yes | Entity (or list of entities) for the meters you want to reset. | | `meter_type` | no | If supported by the device, indicates the type of meter to reset. Not all devices support this option. | | `value` | no | If supported by the device, indicates the value to reset the meter to. Not all devices support this option. | ### Action zwave\_js.set\_lock\_configuration[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsset_lock_configuration) This action will set the configuration of a lock. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Lock entity or list of entities to set the usercode. | | `operation_type` | yes | Lock operation type, one of `timed` or `constant`. | | `lock_timeout` | no | Seconds until lock mode times out. Should only be used if operation type is `timed`. | | `auto_relock_time` | no | Duration in seconds until lock returns to secure state. Only enforced when operation type is `constant`. | | `hold_and_release_time` | no | Duration in seconds the latch stays retracted. | | `twist_assist` | no | Enable Twist Assist. | | `block_to_block` | no | Enable block-to-block functionality. | ### Action zwave\_js.set\_lock\_usercode[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsset_lock_usercode) This action will set the usercode of a lock to X at code slot Y. Valid usercodes are at least 4 digits. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Lock entity or list of entities to set the usercode. | | `code_slot` | yes | The code slot to set the usercode into. | | `usercode` | yes | The code to set in the slot. | ### Action zwave\_js.clear\_lock\_usercode[](https://www.home-assistant.io/integrations/zwave_js#action-zwave_jsclear_lock_usercode) This action will clear the usercode of a lock in code slot X. Valid code slots are between 1-254. | Data attribute | Required | Description | | --- | --- | --- | | `entity_id` | no | Lock entity or list of entities to clear the usercode. | | `code_slot` | yes | The code slot to clear the usercode from. | Events[](https://www.home-assistant.io/integrations/zwave_js#events) --------------------------------------------------------------------- There are two types of events that are fired, notification events and value notification events. You can test what events come in using the event [developer tools in Home Assistant](https://my.home-assistant.io/redirect/developer_events) and subscribing to the `zwave_js_notification` or `zwave_js_value_notification` events respectively. Once you know what the event data looks like, you can use this to create automations. ### Node events (Notification)[](https://www.home-assistant.io/integrations/zwave_js#node-events-notification) Check the [Z-Wave JS notification event documentation](https://zwave-js.github.io/node-zwave-js/#/api/node?id=quotnotificationquot) for an explanation of the notification event data. These events fire with the `zwave_js_notification` event type. Notification event data can be used to trigger automations, both in the automation UI and in YAML, using the event platform. Check the details of an event by subscribing to the zwave\_js\_notification event in the [Developers Tools](https://www.home-assistant.io/docs/tools/dev-tools/#subscribe-to-an-event) . # Fires whenever the lock is unlocked by the keypad. triggers: - trigger: event event_type: zwave_js_notification event_data: node_id: 14 event_label: "Keypad unlock operation" #### Notification Command Class[](https://www.home-assistant.io/integrations/zwave_js#notification-command-class) These are notification events fired by devices using the Notification Command Class. The `parameters` attribute in the example below is optional, and when it is included, the keys in the attribute will vary depending on the event. { "domain": "zwave_js", "node_id": 1, "endpoint": 0, "home_id": "974823419", "device_id": "ad8098fe80980974", "command_class": 113, "command_class_name": "Notification", "type": 6, "event": 5, "label": "Access Control", "event_label": "Keypad lock operation", "parameters": {"userId": 1} } #### Multilevel Switch Command Class[](https://www.home-assistant.io/integrations/zwave_js#multilevel-switch-command-class) These are notification events fired by devices using the Multilevel Switch Command Class. There are events for start level change and stop level change. These would typically be used in a device like the Aeotec Nano Dimmer with an external switch to respond to long button presses. ##### Start level change[](https://www.home-assistant.io/integrations/zwave_js#start-level-change) { "domain": "zwave_js", "node_id": 1, "endpoint": 0, "home_id": 974823419, "device_id": "2f44f0d4152be3123f7ad40cf3abd095", "command_class": 38, "command_class_name": "Multilevel Switch", "event_type": 4, "event_type_label": "label 1", "direction": "up" }, ##### Stop level change[](https://www.home-assistant.io/integrations/zwave_js#stop-level-change) { "domain": "zwave_js", "node_id": 8, "endpoint": 0, "home_id": 3803689189, "device_id": "2f44f0d4152be3123f7ad40cf3abd095", "command_class": 38, "command_class_name": "Multilevel Switch", "event_type": 5, "event_type_label": "label 2", "direction": null }, #### Entry Control Command Class[](https://www.home-assistant.io/integrations/zwave_js#entry-control-command-class) These are notification events fired by devices using the Entry Control Command Class. { "domain": "zwave_js", "node_id": 1, "endpoint": 0, "home_id": "974823419", "device_id": "ad8098fe80980974", "command_class": 111, "command_class_name": "Entry Control", "event_type": 6, "event_type_label": "label 1", "data_type": 5, "data_type_label": "label 2", "event_data": "555" } ### Scene events (Value Notification)[](https://www.home-assistant.io/integrations/zwave_js#scene-events-value-notification) Value Notifications are used for stateless values, like `Central Scenes` and `Scene Activation`. These events fire with the `zwave_js_value_notification` event type. Value Notification example: { "domain": "zwave_js", "node_id": 1, "home_id": "974823419", "endpoint": 0, "device_id": "ad8098fe80980974", "command_class": 91, "command_class_name": "Central Scene", "label": "Event value", "property": "scene", "property_name": "scene", "property_key": "001", "property_key_name": "001", "value": "KeyPressed", "value_raw": 0 } ### Value updated events[](https://www.home-assistant.io/integrations/zwave_js#value-updated-events) Due to some devices not following the Z-Wave Specification, there are scenarios where a device will send a value update but a state change won’t be detected in Home Assistant. To address the gap, the `zwave_js_value_updated` event can be listened to to capture any value updates that are received by an affected entity. This event is **enabled on a per device and per entity domain basis**, and the entities will have `assumed_state` set to `true`. This change will affect how the UI for these entities look; if you’d like the UI to match other entities of the same type where `assumed_state` is not set to `true`, you can override the setting via [entity customization](https://www.home-assistant.io/docs/configuration/customizing-devices/#assumed_state) . The following devices currently support this event: | Make | Model | Entity Domain | | --- | --- | --- | | Vision Security | ZL7432 In Wall Dual Relay Switch | `switch` | Value Updated example: { "node_id": 4, "home_id": "974823419", "device_id": "ad8098fe80980974", "entity_id": "switch.in_wall_dual_relay_switch", "command_class": 37, "command_class_name": "Switch Binary", "endpoint": 0, "property": "currentValue", "property_name": "currentValue", "property_key": null, "property_key_name": null, "value": 0, "value_raw": 0 } This event can be used to trigger a refresh of values when the new state needs to be retrieved. Here’s an example automation: triggers: - trigger: event event_type: zwave_js_value_updated event_data: entity_id: switch.in_wall_dual_relay_switch actions: - action: zwave_js.refresh_value data: entity_id: - switch.in_wall_dual_relay_switch_2 - switch.in_wall_dual_relay_switch_3 Automations[](https://www.home-assistant.io/integrations/zwave_js#automations) ------------------------------------------------------------------------------- The `Z-Wave` integration provides its own trigger platforms which can be used in automations. ### zwave\_js.value\_updated[](https://www.home-assistant.io/integrations/zwave_js#zwave_jsvalue_updated) This trigger platform can be used to trigger automations on any Z-Wave JS value update, including Z-Wave JS values that aren’t supported in Home Assistant via entities. While they can’t be authored from the automation UI, they can be authored in YAML directly in your `configuration.yaml`. #### Example automation trigger configuration[](https://www.home-assistant.io/integrations/zwave_js#example-automation-trigger-configuration) # Fires whenever the `latchStatus` value changes from `closed` to `opened` on the three devices (devices will be derived from an entity ID). triggers: - trigger: zwave_js.value_updated # At least one `device_id` or `entity_id` must be provided device_id: 45d7d3230dbb7441473ec883dab294d4 # Garage Door Lock device ID entity_id: - lock.front_lock - lock.back_door # `property` and `command_class` are required command_class: 98 # Door Lock CC property: "latchStatus" # `property_key` and `endpoint` are optional property_key: null endpoint: 0 # `from` and `to` will both accept lists of values and the trigger will fire if the value update matches any of the listed values from: - "closed" - "jammed" to: "opened" #### Available trigger data[](https://www.home-assistant.io/integrations/zwave_js#available-trigger-data) In addition to the [standard automation trigger data](https://www.home-assistant.io/docs/automation/templating/#all) , the `zwave_js.value_updated` trigger platform has additional trigger data available for use. | Template variable | Data | | --- | --- | | `trigger.device_id` | Device ID for the device in the device registry. | | `trigger.node_id` | Z-Wave node ID. | | `trigger.command_class` | Command Class ID. | | `trigger.command_class_name` | Command Class name. | | `trigger.property` | Z-Wave Value’s property. | | `trigger.property_name` | Z-Wave Value’s property name. | | `trigger.property_key` | Z-Wave Value’s property key. | | `trigger.property_key_name` | Z-Wave Value’s property key name. | | `trigger.endpoint` | Z-Wave Value’s endpoint. | | `trigger.previous_value` | The previous value for this Z-Wave value (translated to a state name when possible). | | `trigger.previous_value_raw` | The raw previous value for this Z-Wave value (the key of the state when a state is named). | | `trigger.current_value` | The current value for this Z-Wave value (translated to a state name when possible). | | `trigger.current_value_raw` | The raw current value for this Z-Wave value (the key of the state when a state is named). | ### zwave\_js.event[](https://www.home-assistant.io/integrations/zwave_js#zwave_jsevent) This trigger platform can be used to trigger automations on any Z-Wave JS controller, driver, or node event, including events that may not be handled by Home Assistant automatically. Refer to the linked [Z-Wave JS documentation](https://zwave-js.github.io/node-zwave-js/#/) to learn more about the available events and the data that is sent along with it. There is strict validation in place based on all known event types, so if you come across an event type that isn’t supported, please open a GitHub issue in the `home-assistant/core` repository. #### Example automation trigger configuration[](https://www.home-assistant.io/integrations/zwave_js#example-automation-trigger-configuration-1) # Fires whenever the `interview failed` event is fired on the three devices (devices will be derived from device and entity IDs). triggers: - trigger: zwave_js.event # At least one `device_id` or `entity_id` must be provided for `node` events. For any other events, a `config_entry_id` needs to be provided. device_id: 45d7d3230dbb7441473ec883dab294d4 # Garage Door Lock device ID entity_id: - lock.front_lock - lock.back_door config_entry_id: # `event_source` and `event` are required event_source: node # options are node, controller, and driver event: "interview failed" # event names can be retrieved from the Z-Wave JS docs (see links above) # `event_data` and `partial_dict_match` are optional. If `event_data` isn't included, all events of a given type for the given context will trigger the automation. When the `interview failed` event is fired, all argument live in a dictionary within the `event_data` dictionary under the `args` key. The default behavior is to require a full match of the event_data dictionary below and the dictionary that is passed to the event. By setting `partial_dict_match` to true, Home Assistant will check if the isFinal argument is true and ignore any other values in the dictionary. If this setting was false, this trigger would never fire because the dictionary always contains more keys than `isFinal` so the comparison check would never evaluate to true. event_data: args: isFinal: true partial_dict_match: true # defaults to false #### Available trigger data[](https://www.home-assistant.io/integrations/zwave_js#available-trigger-data-1) In addition to the [standard automation trigger data](https://www.home-assistant.io/docs/automation/templating/#all) , the `zwave_js.event` trigger platform has additional trigger data available for use. | Template variable | Data | | --- | --- | | `trigger.device_id` | Device ID for the device in the device registry (only included for node events). | | `trigger.node_id` | Z-Wave node ID (only included for node events). | | `trigger.event_source` | Source of event (node, controller, or driver). | | `trigger.event` | Name of event. | | `trigger.event_data` | Any data included in the event. | Advanced installation instructions[](https://www.home-assistant.io/integrations/zwave_js#advanced-installation-instructions) ----------------------------------------------------------------------------------------------------------------------------- If you are using Home Assistant Container or you don’t want to use the built-in Z-Wave JS Server add-on, you will need to run the Z-Wave JS server yourself, to which the Z-Wave integration will connect. ### Running [Z-Wave JS Server](https://github.com/zwave-js/zwave-js-server) This application provides the connection between your Z-Wave adapter and Home Assistant. The Home Assistant Z-Wave integration connects to this server via a WebSocket connection. You need to run this Z-Wave JS server before you can use the integration. There are multiple ways to run this server: The chart below illustrates Options 1 and 2, which are available for Home Assistant OS only. ![Overview of installation options 1 and 2](https://www.home-assistant.io/images/integrations/z-wave/z-wave-server-install-options-1-2.png) **Option 1: The official Z-Wave JS add-on, as described above** _This option is only available for Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users. (the recommended installation type) installations._ This add-on can only be configured via the built-in Z-Wave control panel in Home Assistant. If you followed the standard [installation procedure](https://www.home-assistant.io/integrations/zwave_js#setting-up-a-z-wave-js-server) , this is how you are running the Z-Wave JS server. **Option 2: The Z-Wave JS UI add-on installed from the community add-on store** _This option is only available for Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports add-ons. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users. (the recommended installation type) installations._ This add-on includes the Z-Wave JS Server as part of the Z-Wave JS UI application. The Z-Wave network can be configured via the built-in Z-Wave control panel in Home Assistant and alternatively via the Z-Wave control panel built into Z-Wave JS UI. It provides you with a full-fledged, attractive, and feature-complete UI to manage your Z-Wave nodes and settings, which may support more advanced use cases as development continues on the Z-Wave control panel. **Option 3: The Z-Wave JS UI Docker container** This is the recommended approach if you’re running Home Assistant Container. See the [Z-Wave JS UI documentation](https://zwave-js.github.io/zwave-js-ui//#/getting-started/quick-start) for instructions. This method provides the same server application and UI as the Z-Wave JS UI add-on. After installing the Docker image, make sure you enable the WS Server in the Home Assistant section of Settings page. **Option 4: Run the Z-Wave JS server yourself** This is considered a very advanced use case. In this case you run the Z-Wave JS Server or Z-Wave JS UI NodeJS application directly. Installation and maintaining this is out of scope for this document. See the [Z-Wave JS server](https://github.com/zwave-js/zwave-js-server) or [Z-Wave JS UI](https://github.com/zwave-js/zwave-js-ui/) GitHub repository for information. Note [Supported Z-Wave adapter](https://www.home-assistant.io/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules) . The Z-Wave adapter should be connected to the same host as where the Z-Wave JS server is running. In the configuration for the Z-Wave JS server, you need to provide the path to this adapter. It’s recommended to use the `/dev/serial-by-id/yourdevice` version of the path to your adapter, to make sure the path doesn’t change over reboots. The most common known path is `/dev/serial/by-id/usb-0658_0200-if00`. Note **Network keys** are used to connect securely to compatible devices. The network keys consist of 32 hexadecimal characters, for example, `2232666D100F795E5BB17F0A1BB7A146` (do not use this one, pick a random one). Without network keys security enabled devices cannot be added securely and will not function correctly. You must provide these network keys in the configuration part of the Z-Wave JS Server. For new installations, unique default keys will be auto-generated for you by the Z-Wave JS add-on. You can also generate those network keys in the Settings section of Z-Wave JS UI. Make sure that you keep a backup of these keys in a safe place. You will need to enter the same keys to be able to access securely paired devices. ### Installing and configuring the Z-Wave integration in Home Assistant[](https://www.home-assistant.io/integrations/zwave_js#installing-and-configuring-the-z-wave-integration-in-home-assistant) Once you have the Z-Wave JS server up and running, you need to install and configure the integration in Home Assistant (as described above). If you’re running full Home Assistant with supervisor, you will be presented with a dialog that asks if you want to use the Z-Wave JS Supervisor add-on. You **must** uncheck this box if you are running the Z-Wave JS server in any manner other than the official Z-Wave JS add-on, including using Z-Wave JS UI add-on. If you’re not running the supervisor or you’ve unchecked the above-mentioned box, you will be asked to enter a WebSocket URL (defaults to ws://localhost:3000). It is very important that you fill in the correct (Docker) IP/hostname here. For example for the Z-Wave JS UI add-on this is `ws://a0d7b954-zwavejs2mqtt:3000`. FAQ: Supported devices and Command Classes[](https://www.home-assistant.io/integrations/zwave_js#faq-supported-devices-and-command-classes) -------------------------------------------------------------------------------------------------------------------------------------------- For a list of supported devices, refer to the [Z-Wave JS device database](https://devices.zwave-js.io/) . While there is support for the most common devices, some Command Classes are not yet (fully) implemented in Z-Wave JS. You can track the status [here](https://github.com/zwave-js/node-zwave-js/issues/6) . You can also check the list of Z-Wave [Command Classes Home Assistant responds to when queried](https://www.home-assistant.io/integrations/zwave_js#z-wave-command-classes-home-assistant-responds-to-when-queried) towards the end of this page. You can also keep track of the road map for the Z-Wave integration [here](https://github.com/home-assistant-libs/zwave-js-server-python/issues/56) . FAQ: Installation and configuration[](https://www.home-assistant.io/integrations/zwave_js#faq-installation-and-configuration) ------------------------------------------------------------------------------------------------------------------------------ ### Which Z-Wave adapter should I buy?[](https://www.home-assistant.io/integrations/zwave_js#which-z-wave-adapter-should-i-buy) Z-Wave supports all known 500, 700, and 800 series Z-Wave adapters. If you are just starting out, we recommend that you purchase a 800-series adapter (with firmware updated to >=7.23.2). For more information, see [Supported Z-Wave adapters](https://www.home-assistant.io/docs/z-wave/controllers/#supported-z-wave-usb-sticks--hardware-modules) ### Why was I (not) automatically prompted to install Z-Wave?[](https://www.home-assistant.io/integrations/zwave_js#why-was-i-not-automatically-prompted-to-install-z-wave) Some Z-Wave adapters can be auto-discovered, which can simplify the Z-Wave setup process. The following devices have been tested with discovery, and offer a quick setup experience; however, these are **not** all of the devices supported by Z-Wave: | Device | Identifier | Vendor | | --- | --- | --- | | Aeotec Z-Stick Gen5+ | 0658:0200 | [https://aeotec.com/products/aeotec-z-stick-gen5/](https://aeotec.com/products/aeotec-z-stick-gen5/) | | Nortek HUSBZB-1 | 10C4:8A2A | [https://www.nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/](https://www.nortekcontrol.com/products/2gig/husbzb-1-gocontrol-quickstick-combo/) | | Zooz ZST10 | 10C4:EA60 | [https://www.getzooz.com/zooz-zst10-s2-stick/](https://www.getzooz.com/zooz-zst10-s2-stick/) | | Z-WaveMe UZB | 0658:0200 | [https://z-wave.me/products/uzb/](https://z-wave.me/products/uzb/) | Additional devices may be discoverable, however only devices that have been confirmed discoverable are listed above. ### What happened to Zwavejs2Mqtt or the Z-Wave JS to MQTT add-on?[](https://www.home-assistant.io/integrations/zwave_js#what-happened-to-zwavejs2mqtt-or-the-z-wave-js-to-mqtt-add-on) Zwavejs2Mqtt was renamed Z-Wave JS UI in September 2022. They are synonymous with no difference between their capabilities. ### Can I switch between Z-Wave JS and Z-Wave JS UI?[](https://www.home-assistant.io/integrations/zwave_js#can-i-switch-between-z-wave-js-and-z-wave-js-ui) You can switch between the official Z-Wave JS add-on and the Z-Wave JS UI add-on. However, you cannot run them both at the same time. Only one of them can be active at the same time. ### How to switch from Z-Wave JS to the Z-Wave JS UI add-on?[](https://www.home-assistant.io/integrations/zwave_js#how-to-switch-from-z-wave-js-to-the-z-wave-js-ui-add-on) You can switch from the official **Z-Wave JS** add-on to the community **Z-Wave JS UI** add-on. However, you cannot run them both at the same time. Only one of the add-ons can be active at the same time. Both add-ons communicate with Home Assistant via the same **Z-Wave** integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [\[Learn more\]](https://www.home-assistant.io/getting-started/concepts-terminology/#integrations) . 1. Note your network security keys from the official add-on. * In your browser, open [**Settings** > **Add-ons** > **Z-Wave JS**](https://my.home-assistant.io/redirect/supervisor_addon?addon=core_zwave_js) . * From the three dots menu, select **Edit in YAML**. * You should see about 12 lines of YAML, including items like `device: xxx` and `s2_access_control_key: xxx`. Select all and copy them somewhere safe. You will need them later. 2. Install and start the community **Z-Wave JS UI** add-on. * In your browser, open [**Settings** > **Add-ons** > **Add-on Store**](https://my.home-assistant.io/redirect/supervisor_store) . * Select **Install**, then **Start**. * It may take a while for the add-on to start up. 3. Note the WebSocket URL that the integration will use to communicate with Z-Wave JS. * Within the same **Z-Wave JS UI** add-on from step 2, open the **Documentation** tab. * Search (Ctrl-F) for a link that begins with “ws://”. For example, `ws://a0d7b954-zwavejs2mqtt:3000`. * Copy that URL somewhere safe. You will need it later. 4. Start reconfiguring the integration. * Open a new browser tab. * Go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) and select the **Z-Wave** integration. * Select the three-dot menu next to the **Z-Wave JS** top row. * From the menu, select **Reconfigure**, then **Reconfigure current adapter**. * Uncheck **Use the Z-Wave JS Supervisor add-on**. * Keep this tab open. 5. Configure the new add-on using the information saved in step 1. * Switch back to your initial browser tab. * Within the **Z-Wave JS UI** add-on, switch back to the **Info tab** and select **Open Web UI**. * Open the **Settings** page and expand the **Z-Wave** section. * Fill out the subsections for **Serial Port**, **Security Keys**, and **RF Region**. * Save your changes. 6. Finish reconfiguring the integration. * Switch back to the tab from step 4. * Under **WebSocket URL**, enter the URL you saved in step 3. 7. Uninstall the official add-on. * Go to [**Settings** > **Add-ons** > **Z-Wave JS**](https://my.home-assistant.io/redirect/supervisor_addon?addon=core_zwave_js) and select **Uninstall**. * You are asked if you want to delete the related data. * Keep it if you think you might switch back to the **Z-Wave JS** add-on later. ### How to migrate from one adapter to a new adapter using Z-Wave JS UI?[](https://www.home-assistant.io/integrations/zwave_js#how-to-migrate-from-one-adapter-to-a-new-adapter-using-z-wave-js-ui) If you are currently using [Z-Wave JS UI](https://zwave-js.github.io/zwave-js-ui/#/) instead of the official **Z-Wave JS** add-on and want to start using a new adapter, you can migrate your network inside **Z-Wave JS UI**. 1. Before starting migration, disable the **Z-Wave** integration. * Go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) and select the Z-Wave integration and select the three dots menu and select **Disable**. 2. Do the migration in Z-Wave JS UI. * If you are using the **Z-Wave JS UI** add-on, go to [**Settings** > **Add-ons** > **Z-Wave JS UI**](https://my.home-assistant.io/redirect/supervisor_addon?addon=core_zwave_jsa0d7b954_zwavejs2mqtt) * Open the Z-Wave JS UI control panel and in the bottom-right corner, select the purple **Advanced actions** button. * Under **NVM Management**, select **Backup**. * Unplug the current adapter and connect the new adapter. * Go to **Settings** > **UI** > **Z-Wave**. * Under **Serial port**, update the device path to show your new device (for example, `/dev/serial/by-id/usb-XXXX`). * Under **Default radio configuration** enter the region you’re in and save. * In the control panel, select the purple advanced actions button and under **NVM Management**, select **Restore**. 3. Rebuild all routes. * Select the purple advanced actions button and under **Rebuild routes**, select **Begin**. 4. Enable the Z-Wave integration again. ### What’s the benefit of using Z-Wave JS UI add-on?[](https://www.home-assistant.io/integrations/zwave_js#whats-the-benefit-of-using-z-wave-js-ui-add-on) You might wonder what the benefit is of using the [Z-Wave JS UI](https://zwave-js.github.io/zwave-js-ui/#/README) add-on instead of the official **Z-Wave JS** add-on. The official **Z-Wave JS** add-on provides the Z-Wave Server in its bare minimum variant, just enough to serve the Home Assistant integration. The **Z-Wave JS UI** project includes the Z-Wave JS Server for convenience but also provides a Z-Wave control panel and the ability to serve your Z-Wave network to MQTT. This allows you to use the control panel, and if you so choose, to also use MQTT at the same time. For example, some users may use MQTT to interact with Z-Wave from other devices, while the Home Assistant integration still works (as long as you keep the WS Server enabled in Z-Wave JS UI). ### Z-Wave JS UI provides discovery of HA devices on its own too, now I’m confused[](https://www.home-assistant.io/integrations/zwave_js#z-wave-js-ui-provides-discovery-of-ha-devices-on-its-own-too-now-im-confused) Correct, the Z-Wave JS UI project existed before Home Assistant had plans to move to the Z-Wave JS Driver. You should use the integration for device discovery and _not_ the MQTT discovery provided by Z-Wave JS UI. ### Can I run Z-Wave JS UI only for the control panel and nothing else?[](https://www.home-assistant.io/integrations/zwave_js#can-i-run-z-wave-js-ui-only-for-the-control-panel-and-nothing-else) Sure, in the settings of Z-Wave JS UI, make sure to enable “WS Server” and disable “Gateway”. ### Should I name my devices in Home Assistant, or in Z-Wave JS UI?[](https://www.home-assistant.io/integrations/zwave_js#should-i-name-my-devices-in-home-assistant-or-in-z-wave-js-ui) Ultimately, this is a personal decision. If you provide a name or location for a device in the Z-Wave JS UI, that name will be imported into Home Assistant when the integration is reloaded or Home Assistant is restarted. Any entity names, however, will not change if the device has already been set up by Home Assistant. Names set in Z-Wave JS UI _will not_ overwrite changes that have already been made in Home Assistant. Names set in Home Assistant will not import into Z-Wave JS UI. ### Should I use Secure Inclusion?[](https://www.home-assistant.io/integrations/zwave_js#should-i-use-secure-inclusion) That depends. There are two generations of Z-Wave encryption, Security S0, and Security S2. Both provide encryption and allow detecting packet corruption. Security S0 imposes significant additional traffic on your mesh and is recommended only for older devices that do not support Security S2 but require encryption to work, such as door locks. Security S2 does not impose additional network traffic and provides additional benefits. For example, end devices using S2 require the hub to report whether it has received and understood their reports. By default, Z-Wave prefers Security S2, if supported. Security S0 is used only when absolutely necessary. ### Where can I see the security keys in the Z-Wave JS add-on?[](https://www.home-assistant.io/integrations/zwave_js#where-can-i-see-the-security-keys-in-the-z-wave-js-add-on) After the initial setup of the Z-Wave adapter, you can view the security keys in the Z-Wave JS add-on. Go to [**Settings** > **Add-ons** > **Z-Wave JS**](https://my.home-assistant.io/redirect/supervisor_addon?addon=core_zwave_js) and open the **Configuration** tab. You can now see the three S2 keys and the S0 key. The network security key is a legacy configuration setting, identical to the S0 key. FAQ: Troubleshooting topics[](https://www.home-assistant.io/integrations/zwave_js#faq-troubleshooting-topics) -------------------------------------------------------------------------------------------------------------- ### I’m having a problem, what to do first?[](https://www.home-assistant.io/integrations/zwave_js#im-having-a-problem-what-to-do-first) _Many_ reported issues result from RF interference caused by the system’s USB ports. This can manifest in many ways, including devices that won’t include at all, devices that won’t include securely, sensors with erroneous values (packets corrupted), delayed control of devices, or no ability to control devices. **All users are encouraged to use a USB extension cable to prevent such interference.** Please try such a cable before opening an issue or requesting support on Discord. It will nearly always be the first troubleshooting step that we ask you to take anyway. After ensuring you are using an extension cable, rebuild network routes. The combination of these two steps corrects a large number of reported difficulties. ### My Z-Wave adapter isn’t recognized automatically during setup[](https://www.home-assistant.io/integrations/zwave_js#my-z-wave-adapter-isnt-recognized-automatically-during-setup) If your Z-Wave adapter doesn’t show up in the **Discovered** section automatically, try adding it manually: 1. Check the hardware: * Make sure the adapter is powered on. * Make sure the cable you are using supports data, not power only. 2. Go to **[Settings > Devices & services](https://my.home-assistant.io/redirect/integrations) **. 3. In the bottom right, select the **[Add Integration](https://my.home-assistant.io/redirect/config_flow_start?domain=zwave_js) ** button and select **Z-Wave**. 4. Follow the instructions on screen to complete the setup. 5. If it is still not discovered, [check for interference](https://www.home-assistant.io/integrations/zwave_js#im-having-a-problem-what-to-do-first) . ### I have an Aeotec Gen5 adapter, and it isn’t detected on my Raspberry Pi 4?[](https://www.home-assistant.io/integrations/zwave_js#i-have-an-aeotec-gen5-adapter-and-it-isnt-detected-on-my-raspberry-pi4) The first-generation Gen5 adapter has a known bug when plugged into a Pi 4 and possibly other systems. Aeotec released the Gen5+ stick to correct this bug. Gen5 users can plug their adapters into a USB 2.0 hub in order to overcome the issue. ### I do not see any entities created for my device in Home Assistant[](https://www.home-assistant.io/integrations/zwave_js#i-do-not-see-any-entities-created-for-my-device-in-home-assistant) Entities will be created only after the node is ready (the interview is completed). Also, note that some devices (like button remotes) do not create any entities but will only provide events when a button is pressed. See the events section on how to handle those events in your automations. If you are certain that your device should have entities and you do not see them (even after a restart of Home Assistant Core), create an issue about your problem on the GitHub issue tracker. ### My device doesn’t automatically update its status in HA if I control it manually[](https://www.home-assistant.io/integrations/zwave_js#my-device-doesnt-automatically-update-its-status-in-ha-if-i-control-it-manually) Your device might not send automatic status updates to the adapter. While the best advice would be to update to recent Z-Wave Plus devices, there is a workaround with active polling (request the status). Z-Wave does not automatically poll devices on a regular basis. Polling can quickly lead to network congestion and should be used very sparingly and only where necessary. * We provide a `zwave_js.refresh_value` action to allow you to manually poll a value, for example from an automation that only polls a device when there is motion in that same room. If you **really** need polling, you can enable this in Z-Wave JS UI but not in the official add-on. * Z-Wave JS UI allows you to configure scheduled polling on a per-value basis, which you can use to keep certain values updated. It also allows you to poll individual values on-demand from your automations, which should be preferred over blindly polling all the time if possible. Warning Polling should only be used as a last resort. You must use it with care and accept the negative impact on your network. Z-Wave is a very low speed network and poll requests can easily flood your network and slow down your commands. ### My device is recognized as Unknown Manufacturer and/or some functions don’t work with the Z-Wave integration[](https://www.home-assistant.io/integrations/zwave_js#my-device-is-recognized-as-unknown-manufacturer-andor-some-functions-dont-work-with-the-z-wave-integration) When your device is not yet fully interviewed, this info will not yet be present. So make sure your device is interviewed at least once. If the interview is complete, then the device does not yet have a device file for Z-Wave JS. Unlike other Z-Wave drivers, your device may very well work as intended even without such a file. If your device not fully supported, consider [contributing the device configuration file](https://zwave-js.github.io/node-zwave-js/#/config-files/contributing-files) . ### How do I get a dump of the current network state?[](https://www.home-assistant.io/integrations/zwave_js#how-do-i-get-a-dump-of-the-current-network-state) When trying to determine why something isn’t working as you expect, or when reporting an issue with the integration, it is helpful to know what Z-Wave JS sees as the current state of your Z-Wave network. To get a dump of your current network state, follow these steps: 1. Go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) . 2. Select the **Z-Wave** integration. Then, select the three-dot menu. 3. From the dropdown menu, select **Download diagnostics**. ### How do I address interference issues?[](https://www.home-assistant.io/integrations/zwave_js#how-do-i-address-interference-issues) Many users have reported issues with interference when the adapter was directly connected to the machine (proximity). If you are having issues, try to use a short USB 2.0 A (male to female) extension cord. ### How do I access the Z-Wave logs?[](https://www.home-assistant.io/integrations/zwave_js#how-do-i-access-the-z-wave-logs) #### The easy way[](https://www.home-assistant.io/integrations/zwave_js#the-easy-way) ##### Enable Z-Wave JS logging[](https://www.home-assistant.io/integrations/zwave_js#enable-z-wave-js-logging) 1. Go to the Z-Wave integration panel: [![](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration?domain=zwave_js) 2. In the top-right corner, select the three dots menu and select **Enable debug logging**. * **Result**: The log level will be set to `debug` for the integration, library, and optionally the driver (if the driver log level is not already set to `verbose`, `debug`, or `silly`), and all Z-Wave JS logs will be added to the Home Assistant logs. 3. If you want to change the log level, on the Z-Wave integration panel: [![](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration?domain=zwave_js) , select the cogwheel . * Select the **Logs** tab, then select the log level. ##### Disable Z-Wave JS logging[](https://www.home-assistant.io/integrations/zwave_js#disable-z-wave-js-logging) 1. Go to the Z-Wave integration panel: [![](https://my.home-assistant.io/badges/integration.svg)](https://my.home-assistant.io/redirect/integration?domain=zwave_js) 2. In the top-right corner, select the three dots menu and select **Disable debug logging**. * **Result**: The log level will be reset to its previous value for the integration, library, and driver, and the Home Assistant frontend will automatically send you the Z-Wave logs generated during that time period for download. #### The advanced way[](https://www.home-assistant.io/integrations/zwave_js#the-advanced-way) ##### Enable Z-Wave JS logging manually, or via an automation[](https://www.home-assistant.io/integrations/zwave_js#enable-z-wave-js-logging-manually-or-via-an-automation) Set the log level for `zwave_js_server` to `debug`. This can either be done in your `configuration.yaml` in the `logger` section, or using the `logger.set_level` action. When the integration detects that the log level has been set to `debug`, it will also set the Z-Wave JS logs to `debug` if the level isn’t already `verbose`, `debug`, or `silly` and will include those logs in the Home Assistant logs. The Z-Wave JS logs can be found under the logger name `zwave_js_server.server`. ##### Disable Z-Wave JS logging manually, or via an automation[](https://www.home-assistant.io/integrations/zwave_js#disable-z-wave-js-logging-manually-or-via-an-automation) Set the log level for `zwave_js_server` to a level higher than `debug`. This can either be done in your `configuration.yaml` in the `logger` section, or using the `logger.set_level` action. The Z-Wave JS logs will no longer be included in the Home Assistant logs, and if the log level of Z-Wave JS was changed by the integration, it will automatically change back to its original level. Unsupported functionality[](https://www.home-assistant.io/integrations/zwave_js#unsupported-functionality) ----------------------------------------------------------------------------------------------------------- This sections lists functionality that is available in Z-Wave but that is not currently supported in Home Assistant. ### Setting the adapter into learn mode to receive network information[](https://www.home-assistant.io/integrations/zwave_js#setting-the-adapter-into-learn-mode-to-receive-network-information) In Home Assistant, it is currently not possible to set the Z-Wave controller into learn mode to receive network information from another controller. ### Including / excluding a adapter in an existing network using [classic inclusion](https://www.home-assistant.io/integrations/zwave_js#classic-inclusion-versus-smartstart) A Z-Wave controller that manages an empty network can also join a different network and act as a secondary controller there. However, with Home Assistant, this is not possible. Home Assistant does not allow the Z-Wave controller to join another network, because Home Assistant acts as the central hub. Z-Wave association groups[](https://www.home-assistant.io/integrations/zwave_js#z-wave-association-groups) ----------------------------------------------------------------------------------------------------------- In Home Assistant, a single [association group](https://www.home-assistant.io/integrations/zwave_js#association-group) is implemented: * **Group 1**: This is an association group that includes only one device. It is used after a [factory reset](https://www.home-assistant.io/integrations/zwave_js#resetting-a-z-wave-adapter) , to send a **Device Reset Locally Notification**. This association group is used when Home Assistant [resets the Z-Wave adapter](https://www.home-assistant.io/integrations/zwave_js#resetting-a-z-wave-adapter) . Under normal circumstances, it is not necessary to add a device to this group. Identification via Z-Wave[](https://www.home-assistant.io/integrations/zwave_js#identification-via-z-wave) ----------------------------------------------------------------------------------------------------------- Other Z-Wave devices can instruct a Home Assistant instance to identify itself by sending the following `Indicator Set` Z-Wave command (all bytes are hexadecimal): 87010003500308500403500506 ~~ ~~ ~~ The bytes underlined with `~` can also have any other value. When receiving such a command, Home Assistant will show a notification in its sidebar, mentioning which node sent the command. Z-Wave Command Classes Home Assistant responds to when queried[](https://www.home-assistant.io/integrations/zwave_js#z-wave-command-classes-home-assistant-responds-to-when-queried) ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following table lists the Command Classes together with the implemented version and required security class. These are the Command Classes that Home Assistant will respond to when queried by other devices. | Command Class | Version | Security Class | | --- | --- | --- | | Association | 4 | Highest granted | | Association Group Information | 3 | Highest granted | | CRC-16 Encapsulation | 1 | None | | Device Reset Locally | 1 | Highest granted | | Firmware Update Meta Data | 8 | Highest granted | | Inclusion Controller | 1 | None | | Indicator | 4 | Highest granted | | Manufacturer Specific | 2 | Highest granted | | Multi Channel Association | 5 | Highest granted | | Multi Command | 1 | None | | Power Level | 1 | Highest granted | | Security | 1 | None | | Security 2 | 1 | None | | Supervision | 2 | None | | Transport Service | 2 | None | | Version | 3 | Highest granted | | Z-Wave Plus Info | 2 | None | Note Home Assistant and Z-Wave JS will never return a “Working” or “Fail” status for a valid and supported command of the Supervision Command Class. Z-Wave terminology[](https://www.home-assistant.io/integrations/zwave_js#z-wave-terminology) --------------------------------------------------------------------------------------------- This section explains some Z-Wave terms and concepts you might find in Z-Wave product documentation. ### Association group[](https://www.home-assistant.io/integrations/zwave_js#association-group) An _association_ in Z-Wave terminology is when two or more Z-Wave products communicate directly. This enables devices to communicate with each other without the need to communicate via a hub, or to send unsolicited reports to the central hub. An _association group_ in Z-Wave terminology is a group of devices that another one will send commands to in certain situations. Association groups and their functionality are specific to the device that sends the commands. Refer to the device manual for details. ### Classic inclusion versus SmartStart[](https://www.home-assistant.io/integrations/zwave_js#classic-inclusion-versus-smartstart) Home Assistant supports both _classic inclusion_ and _SmartStart_. _Classic inclusion_ means you set both the hub and the device to be included into the corresponding mode. The alternative is _SmartStart_, where the hub is constantly listening for inclusion requests from devices that want to join the network. ### SmartStart[](https://www.home-assistant.io/integrations/zwave_js#smartstart) SmartStart enabled products can be added into a Z-Wave network by scanning the Z-Wave QR Code present on the product with an adapter supporting SmartStart inclusion. No further action is required and the SmartStart product will be added automatically within 10 minutes of being switched on in the network vicinity. Not all devices support SmartStart. Some devices require _classic inclusion_. For documentation on adding a device to Home Assistant, refer to [adding a new device to the Z-Wave network](https://www.home-assistant.io/integrations/zwave_js#adding-a-new-device-to-the-z-wave-network) . ### Terminology mapping table[](https://www.home-assistant.io/integrations/zwave_js#terminology-mapping-table) Throughout this documentation, Home Assistant terminology is used. For some of the concepts, the terminology does not correspond to the terminology used in Z-Wave documentation. The table below provides equivalents for some of those terms. | Z-Wave functionality | Home Assistant | Definition | | --- | --- | --- | | barrier operator | cover | | | controller | adapter, when referring to the hardware device that provides the Z-Wave functionality. The term controller is still used when referring to the network role (such as primary, secondary controller) | | | exclusion | remove | The process of removing a node from the Z-Wave network | | [inclusion](https://www.home-assistant.io/integrations/zwave_js#classic-inclusion-versus-smartstart) | add | The process of adding a node to the Z-Wave network | | multilevel switch | represented by different entity types: light, fan etc. | | | replication | copy (not supported in Home Assistant) | The process of copying network information from one adapter to another. Not supported in Home Assistant. | | window covering | cover | | Removing Z-Wave JS from Home Assistant[](https://www.home-assistant.io/integrations/zwave_js#removing-z-wave-js-from-home-assistant) ------------------------------------------------------------------------------------------------------------------------------------- This removes all paired Z-Wave devices and their entities, the Z-Wave JS add-on, and the Z-Wave integration from Home Assistant. ### To remove Z-Wave JS from Home Assistant[](https://www.home-assistant.io/integrations/zwave_js#to-remove-z-wave-js-from-home-assistant) 1. [Remove the device from your Z-Wave network](https://www.home-assistant.io/integrations/zwave_js/#removing-a-device-from-the-z-wave-network) . * Do this for each device that is joined to your network so that it is no longer paired to the adapter. * You cannot add a device to a new adapter while it is still paired with an old one. * Alternatively, you can factory reset each device. Refer to the device manual to see how this is done. * This usually involves finding the device in your household and pressing a button. 2. Remove the Z-Wave integration. * Go to [**Settings** > **Devices & services**](https://my.home-assistant.io/redirect/integrations) and select the integration card. * Next to the integration entry, select the three dots menu. * Select **Delete**. 3. If it hasn’t been deleted automatically, remove the Z-Wave JS add-on. * Go to [**Settings** > **Add-ons** > **Z-Wave JS**](https://my.home-assistant.io/redirect/supervisor_addon?addon=core_zwave_js) . * Select **Uninstall**. * Decide whether to also delete the data related to the add-on or whether to keep it. 4. Done. Z-Wave JS is now completely removed from your Home Assistant server. * You can now use your Z-Wave devices and adapter on a new server. Related topics[](https://www.home-assistant.io/integrations/zwave_js#related-topics) ------------------------------------------------------------------------------------- * [Other z wave adapters](https://www.home-assistant.io/docs/z-wave/controllers/) #### **Help us improve our documentation**[](https://www.home-assistant.io/integrations/zwave_js#feedback_section) Suggest an edit to this page, or provide/view feedback for this page. * [Edit](https://github.com/home-assistant/home-assistant.io/tree/current/source/_integrations/zwave_js.markdown "Edit this page") * [Provide feedback](https://github.com/home-assistant/home-assistant.io/issues/new?template=feedback.yml&url=https%3A%2F%2Fwww.home-assistant.io%2Fintegrations%2Fzwave_js%2F&version=2026.1.0&labels=current,integration%3A%20zwave_js "Provide feedback on this page") * [View pending feedback](https://github.com/home-assistant/home-assistant.io/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22integration%3A+zwave_js%22 "View pending feedback for this page") ---