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

Merge branch 'current' into rc

Browse Source
This commit is contained in:
Franck Nijhof 2024-04-30 10:39:26 +02:00
commit 6fd455e924
No known key found for this signature in database
GPG Key ID: D62583BA8AB11CA3
74 changed files with 603 additions and 479 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.github/workflows/test.yml vendored
View File

@ -8,7 +8,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check out files from GitHub
uses: actions/checkout@v4.1.3
uses: actions/checkout@v4.1.4
- name: Setting up Node.js
uses: actions/setup-node@v4.0.2
with:
@ -25,7 +25,7 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Check out files from GitHub
uses: actions/checkout@v4.1.3
uses: actions/checkout@v4.1.4
- name: Setting up Node.js
uses: actions/setup-node@v4.0.2
with:

4
Gemfile
View File

@ -10,8 +10,8 @@ group :development do
gem 'stringex', '2.8.6'
# > 2.1.0 causes slowdowns https://github.com/sass/sassc-ruby/issues/189
gem 'sassc', '2.1.0'
gem 'rubocop', '1.63.3'
gem 'ruby-lsp', '0.16.4'
gem 'rubocop', '1.63.4'
gem 'ruby-lsp', '0.16.6'
gem 'rackup', '2.1.0'
end

20
Gemfile.lock
View File

@ -77,12 +77,12 @@ GEM
nokogiri (1.16.4-x86_64-linux)
racc (~> 1.4)
parallel (1.24.0)
parser (3.3.0.5)
parser (3.3.1.0)
ast (~> 2.4.1)
racc
pathutil (0.16.2)
forwardable-extended (~> 2.6)
prism (0.24.0)
prism (0.27.0)
public_suffix (5.0.5)
racc (1.7.3)
rack (3.0.10)
@ -102,7 +102,7 @@ GEM
regexp_parser (2.9.0)
rexml (3.2.6)
rouge (4.2.1)
rubocop (1.63.3)
rubocop (1.63.4)
json (~> 2.3)
language_server-protocol (>= 3.17.0)
parallel (~> 1.10)
@ -113,11 +113,11 @@ GEM
rubocop-ast (>= 1.31.1, < 2.0)
ruby-progressbar (~> 1.7)
unicode-display_width (>= 2.4.0, < 3.0)
rubocop-ast (1.31.2)
parser (>= 3.3.0.4)
ruby-lsp (0.16.4)
rubocop-ast (1.31.3)
parser (>= 3.3.1.0)
ruby-lsp (0.16.6)
language_server-protocol (~> 3.17.0)
prism (>= 0.22.0, < 0.25)
prism (>= 0.23.0, < 0.28)
sorbet-runtime (>= 0.5.10782)
ruby-progressbar (1.13.0)
ruby2_keywords (0.0.5)
@ -135,7 +135,7 @@ GEM
rack-protection (= 4.0.0)
rack-session (>= 2.0.0, < 3)
tilt (~> 2.0)
sorbet-runtime (0.5.11353)
sorbet-runtime (0.5.11361)
stringex (2.8.6)
terminal-table (3.0.2)
unicode-display_width (>= 1.1.1, < 3)
@ -160,8 +160,8 @@ DEPENDENCIES
nokogiri (= 1.16.4)
rackup (= 2.1.0)
rake (= 13.2.1)
rubocop (= 1.63.3)
ruby-lsp (= 0.16.4)
rubocop (= 1.63.4)
ruby-lsp (= 0.16.6)
sass-globbing (= 1.1.5)
sassc (= 2.1.0)
sinatra (= 4.0.0)

4
plugins/configuration.rb
View File

@ -2,9 +2,9 @@ module Jekyll
class ConfigurationBlock < Liquid::Block
TYPE_LINKS = {
'action' => '/docs/scripts/',
'device_class' => '/docs/configuration/customizing-devices/#device-class',
'device_class' => '/integrations/homeassistant/#device-class',
'template' => '/docs/configuration/templating/',
'icon' => '/docs/configuration/customizing-devices/#icon',
'icon' => '/integrations/homeassistant/#icon',
'selector' => '/docs/blueprint/selectors/',
}

2
source/_dashboards/picture-entity.markdown
View File

@ -144,5 +144,5 @@ tap_action:
{% endraw %}
The filename needs to be a path that is writable by Home Assistant in your system. You may need to configure `allowlist_external_dirs` ([documentation](/docs/configuration/basic/)).
The filename needs to be a path that is writable by Home Assistant in your system. You may need to configure `allowlist_external_dirs` ([documentation](/integrations/homeassistant/#allowlist_external_dirs)).

86
source/_docs/configuration.markdown
View File

@ -8,49 +8,61 @@ related:
title: Storing credentials in `secrets.yaml` file
- docs: /common-tasks/os/#backups
title: Creating and restoring backups
- docs: /integrations/backup
- docs: /integrations/backup/docs/tools/dev-tools/#reloading-the-yaml-configuration
title: Creating backups for Home Assistant Container and Core
- docs: /docs/tools/dev-tools/#reloading-the-yaml-configuration
title: Reloading the YAML configuration from developer tools
- docs: /common-tasks/os/#configuring-access-to-files
title: Configuring file access on the Operating System
- docs: /common-tasks/supervised/#configuring-access-to-files
title: Configuring file access on Supervised
- docs: docs/configuration/troubleshooting/
title: Troubleshooting the configuration
---
While you can configure most of Home Assistant directly from the user interface under {% my config %}, some parts need you to edit `configuration.yaml`. This file contains {% term integrations %} to be loaded along with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable specific functionality.
While you can configure most of Home Assistant from the user interface, for some integrations, you need to edit the `configuration.yaml` file. This file contains {% term integrations %} to be loaded along with their configurations. Throughout the documentation, you will find snippets that you can add to your configuration file to enable specific functionality.
If you run into trouble while configuring Home Assistant, refer to the [configuration troubleshooting page](/docs/configuration/troubleshooting/) and the [`configuration.yaml` examples](/examples/#example-configurationyaml).
<p class='img'>
<img src='/images/docs/configuration/config-yaml_via-file-editor.png' alt='Screenshot of an example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation.'>
Example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation.
</p>
## Editing `configuration.yaml`
The easiest option to edit `configuration.yaml` is to use the {% my supervisor_addon title="Studio Code Server add-on" addon="a0d7b954_vscode" %}. This add-on runs VS Code, which offers live syntax checking and auto-fill of various Home Assistant entities. See [here](/common-tasks/supervised/#installing-and-using-the-visual-studio-code-vsc-add-on) for details. If unavailable on your system, use {% my supervisor_addon title="File Editor add-on" addon="core_configurator" %} instead. Again, details can be found [here](/common-tasks/supervised/#installing-and-using-the-file-editor-add-on).
How you edit your `configuration.yaml` file depends on your editor preferences and the [installation method](/installation/#advanced-installation-methods) you used to set up Home Assistant.
If you prefer to use a file editor on your computer, use the {% my supervisor_addon title="Samba add-on" addon="core_samba" %} to access the files as a network share. More details can be found [here](/common-tasks/supervised/#installing-and-using-the-samba-add-on).
### To set up access to the files and prepare an editor
The path to your configuration directory can be found in the Home Assistant {% term frontend %} by going to {% my system_health title="Settings > System > Repairs > System information from the top right menu" %}
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 method](/installation/#advanced-installation-methods). If you use {% term "Home Assistant Operating System" %} or {% term "Home Assistant Supervised" %}, you can use editor add-ons, for example, but not if you use {% term "Home Assistant Core" %} or {% term "Home Assistant Container" %}.
![Show system menu option](/images/screenshots/System_information_menu.png)
1. To set up file access, follow the steps for your [installation method](/installation/#advanced-installation-methods):
- [Configuring file access on the Operating System](/common-tasks/os/#configuring-access-to-files)
- If you are unsure which option to choose, install the [file editor add-on](/common-tasks/os/#installing-and-using-the-file-editor-add-on).
- Alternatively, use the [VS Code add-on](/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](/common-tasks/os/#installing-and-using-the-samba-add-on).
- [Configuring file access on Supervised](/common-tasks/supervised/#configuring-access-to-files)
- [File editor add-on](/common-tasks/supervised/#installing-and-using-the-file-editor-add-on).
- [VS Code add-on](/common-tasks/supervised/#installing-and-using-the-visual-studio-code-vsc-add-on).
- [Samba add-on](/common-tasks/supervised/#installing-and-using-the-samba-add-on).
2. To look up the to your configuration directory, go to {% my system_health title="**Settings** > **System** > **Repairs**" %}.
- Select the three dots menu and select **System information**.
![Show system information option](/images/screenshots/System_information_menu.png)
3. Find out the location of the **Configuration directory**.
Right under the version you are running, you will find what path Home Assistant has loaded the configuration from.
![Screenshot showing the top of the system information panel](/images/screenshots/System_information.png)
_If you use {% term "Home Assistant Container" %}, you can find `configuration.yaml` in the config folder that you mounted in your container._
_If you use {% term "Home Assistant Operating System" %}, you can find `configuration.yaml` in the `/config` folder of the installation._
_If you use {% term "Home Assistant Core" %} , you can find `configuration.yaml` in the config folder passed to the `hass` command (default is `~/.homeassistant`)._
## Reloading configuration changes
Most integrations in Home Assistant that do not interact with {% term devices %} or {% term services %} can reload changes made to their configuration in `configuration.yaml`.
1. To reload configuration changes, go to {% my server_controls title="**Developer Tools** > **YAML**" %} and scroll down to the YAML configuration reloading section (alternatively, hit "c" anywhere in the UI and search for "reload").
- You are presented with a list of integrations, such as **Automations** or **Conversation**.
![Reload configuration changes](/images/docs/configuration/reloading_config.png)
2. If the integration is listed, select it to reload the settings.
3. If integration is not listed, you need to restart Home Assistant for changes to take effect:
- [Validate the configuration](#validating-the-configuration). Then, select the **Restart** button.
- Unless you changed the file structure, the default is as follows: -
- {% term "Home Assistant Operating System" %}: the `configuration.yaml` is in the `/config` folder of the installation.
- {% term "Home Assistant Container" %}: the `configuration.yaml` is in the config folder that you mounted in your container.
- {% term "Home Assistant Core" %}: the `configuration.yaml` is in the config folder passed to the `hass` command (default is `~/.homeassistant`).
## Validating the configuration
After changing configuration or automation files, check if the configuration is valid.
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](/installation/#advanced-installation-methods). Check the common tasks for your installation type:
@ -58,3 +70,21 @@ The method for running a configuration check depends on your [installation type]
- [Configuration check on Supervised](/common-tasks/supervised/#configuration-check)
- [Configuration check on Container](/common-tasks/container/#configuration-check)
- [Configuration check on Core](/common-tasks/core/#configuration-check)
## 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 {% term devices %} or {% term services %}) can reload changes made to their configuration in `configuration.yaml` without needing to restart Home Assistant.
1. Under **Settings**, select the three dots menu (top right), select **Restart Home Assistant** > **Quick reload**.
![Settings, three dot menu, restart Home Assistant](/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](/images/docs/configuration/reload_restart.png)
## Troubleshooting the configuration
If you run into trouble while configuring Home Assistant, refer to the [configuration troubleshooting page](/docs/configuration/troubleshooting/) and the [`configuration.yaml` examples](/examples/#example-configurationyaml).

7
source/_docs/configuration/basic.markdown
View File

@ -13,6 +13,8 @@ As part of the default onboarding process, Home Assistant can detect your locati
Screenshot showing the General settings page.
</p>
The general settings described here are managed by the [Home Assistant Core integration](/integrations/homeassistant/). If you are interested in the services offered by this integration, check out the integration documentation.
## Editing the general settings
To change the general settings that were defined during onboarding, follow these steps:
@ -27,7 +29,4 @@ To change the general settings that were defined during onboarding, follow these
![Setting fields are grayed out because the configuration settings stored in configuration.yaml file](/images/docs/configuration/general-settings-stored-in-config-yaml.png)
## Reload core service
Home Assistant offers a service to reload the core configuration while Home Assistant is running called {% my developer_call_service service="homeassistant.reload_core_config" %}. This allows you to change any of the above sections and see it being applied without having to restart Home Assistant. To call this service, go to the "{% my developer_services %}" tab under {% my developer_services title="Developer Tools" %}, select the {% my developer_call_service service="homeassistant.reload_core_config" %} service and click the "CALL SERVICE" button. Alternatively, you can press the "Location & Customizations" button under {% my server_controls title="Developer Tools > YAML" %}.
5. To apply the changes, follow the steps on [reloading the configuration](/docs/configuration/#reloading-configuration-changes).

140
source/_docs/configuration/customizing-devices.markdown
View File

@ -1,129 +1,33 @@
---
title: "Customizing entities"
description: "Simple customization for entities."
related:
- docs: /integrations/homeassistant/
- docs: /docs/configuration/
title: Home Assistant Core integration documentation
---
## Changing the entity ID
## Changing entity name and entity ID
You can use the UI to change the entity ID and friendly name of supported entities. To do this:
After adding a new device, the entity may not have a name and the automatically assigned entity ID might look very technical. If you like, you can use your own naming concept for devices.
To change the entity ID and friendly name of supported entities, follow these steps:
1. Go to {% my entities title="**Settings** > **Devices & services** > **Entities**" %} and select the entity from the list.
2. In the top right corner, select the cog icon.
![Entity dialog box with cog icon.](/images/docs/configuration/customizing-entity-dialog.png)
3. Enter the new name or the new entity ID.
- For example, the entity ID here could be `light.bedroom_ligthstrip`.
- Do not change the domain of the entity - the part before the `.`.
1. Select the {% term entity %}, either from the frontend or by selecting the info button next to the entity in the Developer Tools "States" tab.
2. Select the cog icon in the right corner of the entity's dialog
![Entity dialog box.](/images/docs/configuration/customizing-entity-dialog.png)
3. Enter the new name or the new entity ID (remember not to change the domain of the entity - the part before the `.`)
![Settings for entity.](/images/docs/configuration/customizing-entity.png)
4. Select *Update*
If your entity is not supported, or you cannot customize what you need via this method, please see below for more options.
4. Select **Update**.
5. If you have used this entity in automations and scripts, you need to rename the entity ID there, too.
- Go to {% my automations title="**Settings** > **Automations & Scenes**" %} open the respective tab and find your automation or script.
## Customizing entities
![Edit entity ID in automation.](/images/docs/configuration/edit_entity-id_in_automation.png)
By default, all of your devices will be visible and have a default icon determined by their domain. You can customize the look and feel of your front page by altering some of these parameters. This can be done by overriding attributes of specific entities.
### Possible values
{% configuration customize %}
friendly_name:
description: Name of the entity as displayed in the UI.
required: false
type: string
entity_picture:
description: URL to use as picture for entity.
required: false
type: string
icon:
description: "Any icon from [Material Design Icons](https://pictogrammers.com/library/mdi/). Prefix name with `mdi:`, ie `mdi:home`. Note: Newer icons may not yet be available in the current Home Assistant release."
required: false
type: string
assumed_state:
description: For switches with an assumed state two buttons are shown (turn off, turn on) instead of a switch. By setting `assumed_state` to `false` you will get the default switch icon.
required: false
type: boolean
default: true
device_class:
description: Sets the class of the device, changing the device state and icon that is displayed on the UI (see below). It does not set the `unit_of_measurement`.
required: false
type: device_class
default: None
unit_of_measurement:
description: Defines the units of measurement, if any. This will also influence the graphical presentation in the history visualization as continuous value. Sensors with missing `unit_of_measurement` are showing as discrete values.
required: false
type: string
default: None
initial_state:
description: Sets the initial state for automations, `on` or `off`.
required: false
type: boolean
default: None
{% endconfiguration %}
### Device class
Device class is currently supported by the following platforms:
- [Binary sensor](/integrations/binary_sensor/)
- [Button](/integrations/button/)
- [Cover](/integrations/cover/)
- [Humidifier](/integrations/humidifier/)
- [Media player](/integrations/media_player/)
- [Number](/integrations/number/)
- [Sensor](/integrations/sensor/)
- [Switch](/integrations/switch/)
### Manual customization
<div class='note'>
If you implement `customize`, `customize_domain`, or `customize_glob` you must make sure it is done inside of `homeassistant:` or it will fail.
</div>
```yaml
homeassistant:
name: Home
unit_system: metric
# etc
customize:
# Add an entry for each entity that you want to overwrite.
thermostat.family_room:
entity_picture: https://example.com/images/nest.jpg
friendly_name: Nest
switch.wemo_switch_1:
friendly_name: Toaster
entity_picture: /local/toaster.jpg
switch.wemo_switch_2:
friendly_name: Kitchen kettle
icon: mdi:kettle
switch.rfxtrx_switch:
assumed_state: false
media_player.my_media_player:
source_list:
- Channel/input from my available sources
# Customize all entities in a domain
customize_domain:
light:
icon: mdi:home
automation:
initial_state: "on"
# Customize entities matching a pattern
customize_glob:
"light.kitchen_*":
icon: mdi:description
"scene.month_*_colors":
icon: mdi:other
```
### Reloading customize
Home Assistant offers a service to reload the core configuration while Home Assistant is running. This allows you to change your customize section and see your changes being applied without having to restart Home Assistant.
To reload customizations, navigate to Developer Tools > YAML and then press the "Reload Location & Customizations" button. If you don't see this, enable Advanced Mode on your user profile page first.
You can also use the [Quick bar](/docs/tools/quick-bar/#command-palette), and choose "Reload Location & Customizations".
Alternatively, you can reload via service call. Navigate to Developer Tools > Services tab, select `homeassistant.reload_core_config` from the dropdown and press the "Call Service" button.
<div class='note warning'>
New customize information will be applied the next time the state of the entity gets updated.
</div>
If your entity is not supported, or you cannot customize what you need via this method, you need to edit the settings in your [`configuration.yaml` file](/docs/configuration/). For a detailed description of the entity configuration variables and device class information, refer to the [Home Assistant Core integration documentation](/integrations/homeassistant/).

13
source/_docs/organizing/categories.markdown
View File

@ -41,3 +41,16 @@ Follow these steps to create a new category.
- The example shows 2 categories: Coffee and housekeeping.
![Group table items by category](/images/organizing/category_02.png)
## Editing or deleting a category
To rename or delete a category, follow these steps:
1. Go to {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab.
2. In the top left, select the **Filters** button.
![Select the filter button](/images/organizing/filters_01.png)
3. In the list, find the category you want to edit and select the three dot menu next to it.
4. Select **Edit category** or **Delete category**.
![Screenshot showing the edit and delete buttons for categories](/images/organizing/edit-delete-category.png)

25
source/_docs/organizing/labels.markdown
View File

@ -41,12 +41,33 @@ Follow these steps to apply a label
2. To apply a label to a device, entity, or helper:
- Go to **{% my integrations title="Settings > Devices & Services" %}** and open the respective tab.
- Select the <img height="28px" src="/images/organizing/multiselect_icon.png" alt="Multiselect icon"/> button.
- From the list, select all the items to which you want to apply a label.
- From the list, select all the list entries to which you want to apply a label.
- In the top right corner, select **Add label**. Then, select the labels from the list.
![Apply label](/images/organizing/labels_add_05.png)
3. To apply a label to an automation, scene, or script:
- Go to {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab.
- Select the <img height="28px" src="/images/organizing/multiselect_icon.png" alt="Multiselect icon"/> button.
- From the list, select all the items to which you want to apply a label.
- 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
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 {% my labels title="**Settings** > **Areas, labels & zones**" %} and on top, select the **Labels** tab.
2. In the list of labels, find the label you want to delete and select the three dots menu.
3. Select **Delete**.
4. If you used this label in automations or script as targets, you need to adjust those.
## Removing labels
1. Go to the data table that contains the element from which you want to remove the label:
- Go to **{% my integrations title="Settings > Devices & Services" %}** and open the respective tab.
- Or, go to {% my automations title="**Settings** > **Automations & Scenes**" %} and open the respective tab.
2. Select the <img height="28px" src="/images/organizing/multiselect_icon.png" alt="Multiselect icon"/> 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.

36
source/_docs/tools/dev-tools.markdown
View File

@ -11,7 +11,7 @@ Screenshot of Home Assistant's developer tools.
</p>
| Section | Description |
| ---------- |---------------------------------------------------------------------|
| ---------- | ------------------------------------------------------------------- |
| YAML | Lets you validate the configuration and trigger a reload or restart |
| States | Sets the representation of an entity |
| Services | Calls services from integrations |
@ -24,7 +24,27 @@ Screenshot of Home Assistant's developer tools.
The Developer Tools is meant for **all** (not just for the developers) to quickly try out things - like calling services, updating states, raising events, and publishing messages in MQTT). It is also a necessary tool for those who write custom automations and scripts by hand. The following describes each of the sections in detail.
## States
## 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 dot 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
For configuration changes to become effective, the configuration must be reloaded. Most integrations in Home Assistant (that do not interact with {% term devices %} or {% term services %}) can reload changes made to their configuration in `configuration.yaml` without needing to restart Home Assistant.
1. Go to {% my server_controls title="**Developer Tools** > **YAML**" %} and scroll down to the YAML configuration reloading section (alternatively, hit ["c"](/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](/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](/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
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.
@ -35,7 +55,7 @@ For example, changing the `light.bedroom` state from `off` to `on` does not turn
The table containing all entities can be filtered for each column. The used search is a wildcard search meaning that if you input "office" in the entity column filter, every entity whose ID matches "\*office\*" will be shown. You can also add your own wildcards in the search input (e.g., "office\*light").
The attribute filter supports separate filters for attribute names and values, separated by a colon ":". So the filter "location:3" will result in the table showing all entities that have an attribute name that contains "location" and whose attribute value contains "3".
## Services
## Services tab
This section is used to call Services that are available in the ServiceRegistry.
@ -48,6 +68,7 @@ A Service may also require additional input to be passed. It is commonly referre
When an entity is selected from the Entity dropdown, it automatically populates service data with the corresponding `entity_id`. The service data YAML can then be modified to pass additional \[optional\] parameters. The following is an illustration on how to call a `light.turn_on` service.
To turn on a light bulb, use the following steps:
1. Select `light.turn_on` from the Service dropdown
2. Select the entity (typically the light bulb) from the Entity dropdown (if no entity_id is selected, it turns on ALL lights)
3. If an entity is selected, the service data is populated with basic YAML that will be passed to the service. Additional data can also be passed by updating the YAML as below.
@ -58,7 +79,7 @@ brightness: 255
rgb_color: [255, 0, 0]
```
## Template editor
## 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.
@ -66,7 +87,7 @@ By default, this will contain sample code that illustrates how templates can be
For more information about Jinja2, visit [Jinja2 documentation](https://jinja.palletsprojects.com/en/latest/templates/), and also read templating document [here](/docs/configuration/templating).
## Events
## 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.
@ -118,7 +139,7 @@ Event 0 fired 9:53 AM:
}
```
## Statistics
## 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.
@ -130,11 +151,12 @@ icon. Use date & time to search for the incorrect data point and adjust the valu
![Screenshot showing adjusting the long-term statistic history value](/images/blog/2022-04/adjust-statistics.png)
## Assist
## 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*.

2
source/_includes/common-tasks/backups.md
View File

@ -59,7 +59,7 @@ There are multiple ways to store the backup on another device:
- [Add a network storage location](/common-tasks/{{page.installation}}/#network-storage) for backups.
- [Change the default location](/common-tasks/{{page.installation}}/#change-default-backup-location) for backups.
- **Option 4**: Or even better, create an automation to handle that.
- **Option 4**: Or even better, create an automation to handle that, using one of the [backup services](/integrations/hassio/#service-hassiobackup_full).
- **Option 5**: Make use of a third-party add-on:
- [Google Drive Backup](https://github.com/sabeechen/hassio-google-drive-backup)
- [Dropbox Sync](https://github.com/danielwelch/hassio-dropbox-sync)

23
source/_includes/common-tasks/file_access.md
View File

@ -47,15 +47,32 @@ The Terminal & SSH add-on also provides a web terminal which allows you to acces
### Installing and using the Visual Studio Code (VSC) add-on
The Visual Studio Code add-on provides access through a feature packed web-based version of the Visual Studio Code editor and currently only supports AMD64 and aarch64/ARM64 machines. This add-on can be installed in the add-on store from the Community add-on repository. The add-on also provides access to the Home Assistant Command Line Interface (CLI) using VSC's built in terminal, which allows for checking logs, stopping and starting Home Assistant and add-ons, creating/restoring backups, and more. (See [Home Assistant via Command Line](https://www.home-assistant.io/hassio/commandline/) for further info).
The **Studio Code Server** add-on provides access through a feature-packed web-based version of the Visual Studio Code editor. It currently only supports AMD64 and aarch64/ARM64 machines. The add-on also provides access to the Home Assistant Command Line Interface (CLI) using VSC's built-in terminal, which allows for checking logs, stopping, and starting Home Assistant and add-ons, creating/restoring backups, and more. (See [Home Assistant via Command Line](/hassio/commandline/) for further info).
There is no configuration required for editing files within your `/config` directory. In order to enable access to other directories, it is necessary to edit the add-on's configuration from its configuration tab. See the add-on documentation for details.
<p class='img'>
<img src='/images/docs/configuration/config-yaml_via-vscode.png' alt='Screenshot of an example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation.'>
Example of a configuration.yaml file, accessed using the Studio Code Server add-on on a Home Assistant Operating System installation.
</p>
To install and use the **Studio Code Server** in Home Assistant, follow these steps:
1. To install the add-on, go to {% my supervisor_addon title="**Settings** > **Add-ons** > **Studio Code Server**" addon="a0d7b954_vscode" %} and install the add-on.
2. Once you have the add-on installed, if you want, select the **Show in sidebar** option. Then, select **Start**.
3. For information on configuration settings, open the **Documentation** tab.
4. To start browsing, on the **Info** tab, select **Open Web UI**.
---
### Installing and using the File Editor add-on
The File Editor add-on is a web-based file system browser and text editor. It is a more basic and light weight alternative to Visual Studio Code. YAML files are automatically checked for syntax errors while editing. To install and use the File Editor in Home Assistant, follow these steps:
The **File Editor** add-on is a web-based file system browser and text editor. It is a more basic and light weight alternative to Visual Studio Code. YAML files are automatically checked for syntax errors while editing.
<p class='img'>
<img src='/images/docs/configuration/config-yaml_via-file-editor.png' alt='Screenshot of an example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation.'>
Example of a configuration.yaml file, accessed using the File editor add-on on a Home Assistant Operating System installation.
</p>
To install and use the File Editor in Home Assistant, follow these steps:
1. To install the add-on, go to {% my supervisor_addon title="**Settings** > **Add-ons** > **File editor**" addon="core_configurator" %}.
- Once you have the add-on installed, you can edit files within your `/config` directory.

4
source/_integrations/air_quality.markdown
View File

@ -1,5 +1,5 @@
---
title: Air Quality
title: Air quality
description: Instructions on how to add air quality sensors with Home Assistant
ha_release: 0.85
ha_domain: air_quality
@ -10,7 +10,7 @@ ha_codeowners:
ha_integration_type: entity
---
The `air_quality` base platform allows other integrations to process information about air quality and pollution details. It is used by integrations that provide an `air_quality` sensor - you can find those under the `health` [integrations](/integrations/#health).
The **Air quality** {% term integration %} allows other integrations to process information about air quality and pollution details. It is used by integrations that provide an `air_quality` sensor - you can find those under the `health` [integrations](/integrations/#health).
The platforms cover the following levels (if they are available):

4
source/_integrations/application_credentials.markdown
View File

@ -1,5 +1,5 @@
---
title: Application Credentials
title: Application credentials
description: Allows users to link accounts with integrations that support OAuth2
ha_release: 2022.6
ha_domain: application_credentials
@ -10,7 +10,7 @@ ha_codeowners:
ha_integration_type: system
---
The Application Credentials integration is used by integrations that use OAuth2 to link your account to Home Assistant. The most common and preferred approach is using account linking with Home Assistant Cloud, however not all cloud providers support that and integrations can use Application Credentials instead. Additionally, users may use Application Credentials if preferred instead of Home Assistant Cloud Account Linking.
The **Application credentials** {% term integration %} is used by integrations that use OAuth2 to link your account to Home Assistant. The most common and preferred approach is using account linking with Home Assistant Cloud, however not all cloud providers support that and integrations can use Application Credentials instead. Additionally, users may use Application Credentials if preferred instead of Home Assistant Cloud Account Linking.
## Automatic setup

8
source/_integrations/backup.markdown
View File

@ -21,13 +21,9 @@ related:
title: Home Assistant Operating System- Restoring a backup
---
The **Backup** {% term integration %} allows you to create and download backups for your {% term "Home Assistant Core" %} and {% term "Home Assistant Container" %} installations. This backup file can be used if you migrate to {% term "Home Assistant Operating System" %}.
The **Backup** {% term integration %} is used for {% term "Home Assistant Core" %} and {% term "Home Assistant Container" %} installations to create and download backups. This backup file can be used if you migrate to {% term "Home Assistant Operating System" %}.
<div class="note">
If you use {% term "Home Assistant Operating System" %} or {% term "Home Assistant Supervised" %} , the [back up functionality is already built-in](/common-tasks/os/#backups). This integration is for {% term "Home Assistant Core" %} and {% term "Home Assistant Container" %} installations.
</div>
Note: If you use {% term "Home Assistant Operating System" %} or {% term "Home Assistant Supervised" %} installation, this page is not for you. Instead, refer to the documentation on using the [built-in back up](/common-tasks/os/#backups).
## Services

2
source/_integrations/button.mqtt.markdown
View File

@ -62,7 +62,7 @@ command_template:
type: template
command_topic:
description: The MQTT topic to publish commands to trigger the button.
required: false
required: true
type: string
device:
description: "Information about the device this button is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). Only works when [`unique_id`](#unique_id) is set. At least one of identifiers or connections must be present to identify the device."

18
source/_integrations/camera.markdown
View File

@ -40,7 +40,7 @@ Available services: `enable_motion_detection`, `disable_motion_detection`, `play
Enable the motion detection in a camera.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ---------------------------------------------------------------------------------- |
| `entity_id` | yes | Name(s) of entities to enable motion detection, e.g., `camera.living_room_camera`. |
#### Service `disable_motion_detection`
@ -48,7 +48,7 @@ Enable the motion detection in a camera.
Disable the motion detection in a camera.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ----------------------------------------------------------------------------------- |
| `entity_id` | yes | Name(s) of entities to disable motion detection, e.g., `camera.living_room_camera`. |
#### Service `play_stream`
@ -56,7 +56,7 @@ Disable the motion detection in a camera.
Play a live stream from a camera to selected media player(s). Requires [`stream`](/integrations/stream) integration to be set up.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `entity_id` | no | Name of entity to fetch stream from, e.g., `camera.living_room_camera`. |
| `media_player` | no | Name of media player to play stream on, e.g., `media_player.living_room_tv`. |
| `format` | yes | Stream format supported by `stream` integration and selected `media_player`. Default: `hls` |
@ -79,13 +79,13 @@ Make a `.mp4` recording from a camera stream. Requires `stream` integration to b
Both `duration` and `lookback` options are suggestions, but should be consistent per camera. The actual length of the recording may vary. It is suggested that you tweak these settings to fit your needs.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. |
| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/{{ entity_id.name }}.mp4`{% endraw %}. |
| `duration` | yes | Target recording length (in seconds). Default: 30 |
| `lookback` | yes | Target lookback period (in seconds) to include in addition to duration. Only available if there is currently an active HLS stream. Default: 0 |
The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/integrations/homeassistant/#allowlist_external_dirs) section of your `configuration.yaml` file.
For example, the following action in an automation would take a recording from "yourcamera" and save it to /tmp with a timestamped filename.
@ -107,11 +107,11 @@ action:
Take a snapshot from a camera.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. |
| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/snapshot_{{ entity_id.name }}`{% endraw %}. |
The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/integrations/homeassistant/) section of your `configuration.yaml` file.
For example, the following action in an automation would take a snapshot from "yourcamera" and save it to /tmp with a timestamped filename.
@ -133,7 +133,7 @@ action:
Turn off camera. Not all camera models support this service, please consult individual camera page.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ------------------------------------------------------------------- |
| `entity_id` | yes | Name(s) of entities to turn off, e.g., `camera.living_room_camera`. |
#### Service `turn_on`
@ -141,7 +141,7 @@ Turn off camera. Not all camera models support this service, please consult indi
Turn on camera. Not all camera models support this service, please consult individual camera page.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ------------------------------------------------------------------ |
| `entity_id` | yes | Name(s) of entities to turn on, e.g., `camera.living_room_camera`. |
### Test if it works

8
source/_integrations/cast.markdown
View File

@ -48,7 +48,7 @@ cast_downstairs_on_kitchen:
<div class='note'>
Home Assistant Cast requires your Home Assistant installation to be accessible via `https://`. If you're using Home Assistant Cloud, you don't need to do anything. Otherwise you must make sure that you have configured the `external_url` in your [configuration](/docs/configuration/basic).
Home Assistant Cast requires your Home Assistant installation to be accessible via `https://`. If you're using Home Assistant Cloud, you don't need to do anything. Otherwise you must make sure that you have configured the `external_url` in your [configuration](/integrations/homeassistant/#configuration-variables).
</div>
@ -58,7 +58,7 @@ Home Assistant Cast requires your Home Assistant installation to be accessible v
Chromecasts generally ignore DNS servers from DHCP and will instead use Google's DNS servers, 8.8.8.8 and 8.8.4.4. This means media URLs must either be specifying the IP-address of the server directly, e.g. `http://192.168.1.1:8123/movie.mp4`, or be publicly resolvable, e.g. `http://homeassistant.internal.mydomain.com:8123/movie.mp4` where `homeassistant.internal.mydomain.com` resolves to `192.168.1.1`. A hostname which can't be publicly resolved, e.g. `http://homeassistant.local:8123/movie.mp4` will fail to play.
This is important when casting TTS or local media sources; the cast integration will cast such media from the `external_url` if [configured](/docs/configuration/basic), otherwise from the Home Assistant Cloud if configured, otherwise from the [`internal_url`](/docs/configuration/basic). Note that the Home Assistant Cloud will not be used if an `external_url` is configured.
This is important when casting TTS or local media sources; the cast integration will cast such media from the `external_url` if [configured](/integrations/homeassistant/#editing-the-general-settings-in-yaml), otherwise from the Home Assistant Cloud if configured, otherwise from the [`internal_url`](/integrations/homeassistant/#editing-the-general-settings-in-yaml). Note that the Home Assistant Cloud will not be used if an `external_url` is configured.
</div>
@ -139,7 +139,7 @@ This app doesn't retrieve its own metadata, so if you want the cast interface or
Note: Media ID is NOT the 8 digit alphanumeric in the URL, it can be found by right-clicking the playing video. E.g., [this episode](https://www.bbc.co.uk/iplayer/episode/b09w7fd9/bitz-bob-series-1-1-castle-makeover) shows:
| | |
| --- | --- |
| -------- | ------------------------------- |
| 2908kbps | dash (mf_cloudfront_dash_https) |
| b09w70r2 | 960x540 |
@ -344,7 +344,7 @@ To cast media directly from a configured Plex server, set the fields [as documen
Note: Media ID is NOT the 8 digit alphanumeric in the URL, it can be found by right-clicking the playing audio clip. E.g., [this episode](https://www.bbc.co.uk/sounds/play/p009ycqy) shows:
| | |
| --- | --- |
| -------- | --------------------------------------- |
| 128bps | dash (mf_cloudfront_nonbidi_dash_https) |
| p009ycqz | |

4
source/_integrations/color_extractor.markdown
View File

@ -23,14 +23,14 @@ Because `color_extractor.turn_on` will then call `light.turn_on`, you can pass a
Passing the key `color_extract_url` to the {% term service %} call will download the linked image and extract the predominant color from it. Passing the key `color_extract_path` to the service call will process the image file from local storage instead. `color_extract_url` and `color_extract_path` are exclusive and cannot be used together.
| Key | Example | Description |
|---------------------|---------------------------------------|-------------------------------------------------------------------------------|
| -------------------- | ------------------------------------- | ------------------------------------------------------------------------------ |
| `color_extract_url` | `https://example.com/images/logo.png` | The full URL (including schema, `http://`, `https://`) of the image to process |
| `color_extract_path` | `/tmp/album.png` | The full path to the image file on local storage we'll process |
| `entity_id` | `light.shelf_leds` | The RGB capable light we'll set the color of |
<div class="note">
Please ensure any [external URLs](/docs/configuration/basic/#allowlist_external_urls) or [external files](/docs/configuration/basic/#allowlist_external_dirs) are authorized for use. You will receive error messages if this {% term integration %} is not allowed access to these external resources.
Please ensure any [external URLs](/integrations/homeassistant/#allowlist_external_urls) or [external files](/docs/integrations/homeassistant/#allowlist_external_dirs) are authorized for use. You will receive error messages if this {% term integration %} is not allowed access to these external resources.
</div>

6
source/_integrations/command_line.markdown
View File

@ -1,6 +1,6 @@
---
title: Command Line
description: Instructions on how to integrate the Command Line utility within Home Assistant.
title: Command line
description: Instructions on how to integrate the command line utility within Home Assistant.
ha_category:
- Binary sensor
- Cover
@ -21,7 +21,7 @@ ha_codeowners:
- '@gjohansson-ST'
---
The `command_line` offers functionality that issues specific commands to get data or to control a device.
The **Command line** {% term integration %} offers functionality that issues specific commands to get data or to control a device.
<div class='note'>

6
source/_integrations/device_automation.markdown
View File

@ -1,6 +1,6 @@
---
title: Device Automation
description: Information about the Device Automation plugin.
title: Device automation
description: Information about the device automation plugin.
ha_category:
- Automation
ha_release: 0.7
@ -11,7 +11,7 @@ ha_domain: device_automation
ha_integration_type: system
---
Device Automations is a plugin for the automation integration to allow other integrations to provide device specific triggers, conditions and actions.
**Device automation** is a plugin for the automation integration to allow other integrations to provide device specific triggers, conditions and actions.
There is no device automation specific configuration. Instead, it is configured as part of the normal automations.

2
source/_integrations/dialogflow.markdown
View File

@ -12,7 +12,7 @@ ha_integration_type: integration
The **Dialogflow** {% term integration %} is designed to be used with the [webhook](https://cloud.google.com/dialogflow/es/docs/fulfillment-webhook) integration of [Dialogflow](https://cloud.google.com/dialogflow/docs/). After each phrase a user says, Dialogflow sends an action and parameters to the webhook.
To be able to receive messages from Dialogflow, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic). Dialogflow will return fallback answers if your server does not answer or takes too long (more than 5 seconds).
To be able to receive messages from Dialogflow, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/integrations/homeassistant/#editing-the-general-settings-in-yaml). Dialogflow will return fallback answers if your server does not answer or takes too long (more than 5 seconds).
Dialogflow could be [integrated](https://cloud.google.com/dialogflow/es/docs/integrations) with many popular messaging, virtual assistant and IoT platforms.

32
source/_integrations/discord.markdown
View File

@ -70,25 +70,25 @@ When adding the Discord integration you will be asked for an API Key. Enter the
The following attributes can be placed inside the `data` key of the service call for extended functionality:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `images` | yes | The file(s) to attach to message.
| `urls` | yes | The file(s) to download from a remote URL and attach to message.
| `verify_ssl` | yes | A boolean to determine if SSL certs should be verified when calling the remote URLs in the `url` attribute. Defaults to `True`.
| `embed` | yes | Array of [Discord embeds](https://discordpy.readthedocs.io/en/latest/api.html#embed). *NOTE*: if using `embed`, `message` is still required.
| ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `images` | yes | The file(s) to attach to message. |
| `urls` | yes | The file(s) to download from a remote URL and attach to message. |
| `verify_ssl` | yes | A boolean to determine if SSL certs should be verified when calling the remote URLs in the `url` attribute. Defaults to `True`. |
| `embed` | yes | Array of [Discord embeds](https://discordpy.readthedocs.io/en/latest/api.html#embed). *NOTE*: if using `embed`, `message` is still required. |
To include messages with embedding, use these attributes underneath the `embed` key:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `title` | yes | Title of the embed.
| `description` | yes | Description of the embed.
| `color` | yes | Color code of the embed. This value is an *int*.
| `url` | yes | URL of the embed.
| `author` | yes | Sets the footer for the embed content.
| `footer` | yes | Sets the footer for the embed content.
| `thumbnail` | yes | Sets the thumbnail for the embed content.
| `image` | yes | Sets the image for the embed content.
| `fields` | yes | Adds a field to the embed object. `name` and `value` are *required*, `inline` is *true* by default.
| ------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `title` | yes | Title of the embed. |
| `description` | yes | Description of the embed. |
| `color` | yes | Color code of the embed. This value is an *int*. |
| `url` | yes | URL of the embed. |
| `author` | yes | Sets the footer for the embed content. |
| `footer` | yes | Sets the footer for the embed content. |
| `thumbnail` | yes | Sets the thumbnail for the embed content. |
| `image` | yes | Sets the image for the embed content. |
| `fields` | yes | Adds a field to the embed object. `name` and `value` are *required*, `inline` is *true* by default. |
### Example service call
@ -117,7 +117,7 @@ To include messages with embedding, use these attributes underneath the `embed`
- "https://example.com/video.mp4"
```
Note that `verify_ssl` defaults to `True`, and that any remote hosts will need to be in your [`allowlist_external_urls`](/docs/configuration/basic/#allowlist_external_urls) list. Discord limits attachment size to 8MB, so anything exceeding this will be skipped and noted in the error log.
Note that `verify_ssl` defaults to `True`, and that any remote hosts will need to be in your [`allowlist_external_urls`](/integrations/homeassistant/#allowlist_external_urls) list. Discord limits attachment size to 8MB, so anything exceeding this will be skipped and noted in the error log.
### Example embed service call

2
source/_integrations/file.markdown
View File

@ -56,7 +56,7 @@ To use notifications, please see the [getting started with automation page](/get
## Sensor
The `file` sensor platform reads the entries from a plain-text file and shows the found value. Only the last line of the file is used. This is similar to do `$ tail -n 1 sensor.txt` on the command-line. Note that file paths must be added to [allowlist_external_dirs](/docs/configuration/basic/).
The `file` sensor platform reads the entries from a plain-text file and shows the found value. Only the last line of the file is used. This is similar to do `$ tail -n 1 sensor.txt` on the command-line. Note that file paths must be added to [allowlist_external_dirs](/integrations/homeassistant/#allowlist_external_dirs).
To enable the `file` sensor, add the following lines to your `configuration.yaml`:

4
source/_integrations/file_upload.markdown
View File

@ -1,5 +1,5 @@
---
title: File Upload
title: File upload
description: File upload integration supports various frontend features within Home Assistant
ha_release: 2022.9
ha_quality_scale: internal
@ -10,6 +10,6 @@ ha_codeowners:
ha_category: []
---
The file upload integration allows various features in the frontend to upload files.
The **File upload** {% term integration %} allows various features in the frontend to upload files.
{% include integrations/building_block_integration.md %}

6
source/_integrations/filesize.markdown
View File

@ -1,5 +1,5 @@
---
title: File Size
title: File size
description: Integration for monitoring the size of a file.
ha_category:
- Sensor
@ -15,11 +15,11 @@ ha_config_flow: true
ha_integration_type: integration
---
The `filesize` sensor is for displaying the size in MB of a file.
The **File size** {% term integration %} is for displaying the size in MB of a file.
<div class='note'>
File paths must also be added to [allowlist_external_dirs](/docs/configuration/basic/) in your `configuration.yaml`.
File paths must also be added to [allowlist_external_dirs](/integrations/homeassistant/#allowlist_external_dirs) in your `configuration.yaml`.
File paths should be absolute paths. For example: `/config/home-assistant_v2.db` to monitor the size of the default database.

2
source/_integrations/folder.markdown
View File

@ -12,7 +12,7 @@ ha_platforms:
ha_integration_type: integration
---
Sensor for monitoring the contents of a folder. Note that folder paths must be added to [allowlist_external_dirs](/docs/configuration/basic/). Optionally a [wildcard filter](https://docs.python.org/3.6/library/fnmatch.html) can be applied to the files considered within the folder. The state of the sensor is the size in MB of files within the folder that meet the filter criteria.
Sensor for monitoring the contents of a folder. Note that folder paths must be added to [allowlist_external_dirs](/integrations/homeassistant/#allowlist_external_dirs). Optionally a [wildcard filter](https://docs.python.org/3.6/library/fnmatch.html) can be applied to the files considered within the folder. The state of the sensor is the size in MB of files within the folder that meet the filter criteria.
The sensor exposes the number of filtered files in the folder, total size in bytes of those files and a comma separated list of the file paths as attributes.
## Configuration

6
source/_integrations/folder_watcher.markdown
View File

@ -1,5 +1,5 @@
---
title: Folder Watcher
title: Folder watcher
description: Integration for monitoring changes within the filesystem.
ha_category:
- System monitor
@ -11,7 +11,7 @@ ha_domain: folder_watcher
ha_integration_type: integration
---
This integration adds [Watchdog](https://pythonhosted.org/watchdog/) file system monitoring, publishing events on the Home Assistant bus on the creation/deletion/modification of files within configured folders. The monitored `event_type` are:
The **Folder watcher** {% term integration %} adds [Watchdog](https://pythonhosted.org/watchdog/) file system monitoring, publishing events on the Home Assistant bus on the creation/deletion/modification of files within configured folders. The monitored `event_type` are:
- `closed`
- `created`
@ -19,7 +19,7 @@ This integration adds [Watchdog](https://pythonhosted.org/watchdog/) file system
- `modified`
- `moved`
Configured folders must be added to [allowlist_external_dirs](/docs/configuration/basic/). Note that by default folder monitoring is recursive, meaning that the contents of sub-folders are also monitored.
Configured folders must be added to [allowlist_external_dirs](/integrations/homeassistant/#allowlist_external_dirs). Note that by default folder monitoring is recursive, meaning that the contents of sub-folders are also monitored.
{% include integrations/config_flow.md %}

4
source/_integrations/history_stats.markdown
View File

@ -1,5 +1,5 @@
---
title: History Stats
title: History stats
description: Instructions about how to integrate historical statistics into Home Assistant.
ha_category:
- Sensor
@ -13,7 +13,7 @@ ha_platforms:
ha_integration_type: integration
---
The `history_stats` sensor platform provides quick statistics about another integration or platforms, using data from the [`history`](/integrations/history/) integration.
The **History stats** {% term integration %} provides quick statistics about another integration or platforms, using data from the [`history`](/integrations/history/) integration.
It can track how long the integration has been in a specific state, in a custom time period.

110
source/_integrations/homeassistant.markdown
View File

@ -15,6 +15,7 @@ related:
- docs: /docs/configuration/basic/
title: Basic information
- docs: /docs/configuration/
- docs: /docs/configuration/customizing-devices/
---
The **Home Assistant Core** {% term integration %} provides generic implementations like the generic `homeassistant.turn_on`.
@ -103,15 +104,15 @@ internal_url:
required: false
type: string
customize:
description: "[Customize](/docs/configuration/customizing-devices/) entities."
description: "[Customize](#editing-the-entity-settings-in-yaml) entities."
required: false
type: string
customize_domain:
description: "[Customize](/docs/configuration/customizing-devices/) all entities in a domain."
description: "[Customize](#editing-the-entity-settings-in-yaml) all entities in a domain."
required: false
type: string
customize_glob:
description: "[Customize](/docs/configuration/customizing-devices/) entities matching a pattern."
description: "[Customize](#editing-the-entity-settings-in-yaml) entities matching a pattern."
required: false
type: string
allowlist_external_dirs:
@ -142,6 +143,109 @@ debug:
default: false
{% endconfiguration %}
## Editing the entity settings in YAML
The Home Assistant Core integration is also responsible for the entity settings.
By default, all of your devices will be visible and have a default icon determined by their domain. You can customize the look and feel of your front page by altering some of these parameters. This can be done by overriding attributes of specific entities.
Most of these settings can be changed from the UI. For the detailed steps, refer to [Customizing entites](/docs/configuration/customizing-devices/).
If you prefer editing in YAML, you can define your general settings in the [`configuration.yaml` file](/docs/configuration/).
### Possible values
{% configuration customize %}
friendly_name:
description: Name of the entity as displayed in the UI.
required: false
type: string
entity_picture:
description: URL to use as picture for entity.
required: false
type: string
icon:
description: "Any icon from [Material Design Icons](https://pictogrammers.com/library/mdi/). Prefix name with `mdi:`, ie `mdi:home`. Note: Newer icons may not yet be available in the current Home Assistant release."
required: false
type: string
assumed_state:
description: For switches with an assumed state two buttons are shown (turn off, turn on) instead of a switch. By setting `assumed_state` to `false` you will get the default switch icon.
required: false
type: boolean
default: true
device_class:
description: Sets the class of the device, changing the device state and icon that is displayed on the UI (see below). It does not set the `unit_of_measurement`.
required: false
type: device_class
default: None
unit_of_measurement:
description: Defines the units of measurement, if any. This will also influence the graphical presentation in the history visualization as continuous value. Sensors with missing `unit_of_measurement` are showing as discrete values.
required: false
type: string
default: None
initial_state:
description: Sets the initial state for automations, `on` or `off`.
required: false
type: boolean
default: None
{% endconfiguration %}
### Device class
Device class is currently supported by the following platforms:
- [Binary sensor](/integrations/binary_sensor/)
- [Button](/integrations/button/)
- [Cover](/integrations/cover/)
- [Humidifier](/integrations/humidifier/)
- [Media player](/integrations/media_player/)
- [Number](/integrations/number/)
- [Sensor](/integrations/sensor/)
- [Switch](/integrations/switch/)
### Manual customization
<div class='note'>
If you implement `customize`, `customize_domain`, or `customize_glob` you must make sure it is done inside of `homeassistant:` or it will fail.
</div>
```yaml
homeassistant:
name: Home
unit_system: metric
# etc
customize:
# Add an entry for each entity that you want to overwrite.
thermostat.family_room:
entity_picture: https://example.com/images/nest.jpg
friendly_name: Nest
switch.wemo_switch_1:
friendly_name: Toaster
entity_picture: /local/toaster.jpg
switch.wemo_switch_2:
friendly_name: Kitchen kettle
icon: mdi:kettle
switch.rfxtrx_switch:
assumed_state: false
media_player.my_media_player:
source_list:
- Channel/input from my available sources
# Customize all entities in a domain
customize_domain:
light:
icon: mdi:home
automation:
initial_state: "on"
# Customize entities matching a pattern
customize_glob:
"light.kitchen_*":
icon: mdi:description
"scene.month_*_colors":
icon: mdi:other
```
## Services
The `homeassistant` integration provides services for controlling Home Assistant itself, as well as generic controls for any entity.

12
source/_integrations/ifttt.markdown
View File

@ -16,7 +16,7 @@ ha_integration_type: integration
## Prerequisites
To be able to receive events from IFTTT, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic), or use your Nabu Casa account's webhook URL from the IFTTT integration.
To be able to receive events from IFTTT, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/integrations/homeassistant/#allowlist_external_urls), or use your Nabu Casa account's webhook URL from the IFTTT integration.
{% include integrations/config_flow.md %}
@ -111,11 +111,11 @@ When your screen looks like this, click the 'call service' button.
By default, the trigger is sent to all the API keys from `configuration.yaml`. If you
want to send the trigger to a specific key use the `target` field:
Field | Value
----- | -----
domain | `ifttt`
service | `trigger`
Service Data | `{"event": "EventName", "value1": "Hello World", "target": "YOUR_KEY_NAME1"}`
| Field | Value |
| ------------ | ----------------------------------------------------------------------------- |
| domain | `ifttt` |
| service | `trigger` |
| Service Data | `{"event": "EventName", "value1": "Hello World", "target": "YOUR_KEY_NAME1"}` |
The `target` field can contain a single key name or a list of key names.

4
source/_integrations/image_upload.markdown
View File

@ -1,5 +1,5 @@
---
title: Image Upload
title: Image upload
description: The image upload integration handle image assets in Home Assistant.
ha_category:
- Other
@ -11,7 +11,7 @@ ha_quality_scale: internal
ha_integration_type: system
---
The Image Upload integration allows Home Assistant to handle image assets in
The **Image upload** {% term integration %} allows Home Assistant to handle image assets in
Home Assistant, for example, the profile photos of your systems account.
## Configuration

14
source/_integrations/input_boolean.markdown
View File

@ -1,6 +1,6 @@
---
title: Input Boolean
description: Instructions on how to use the Input Boolean helper with Home Assistant.
title: Input boolean
description: Instructions on how to use the input boolean helper with Home Assistant.
ha_category:
- Automation
- Helper
@ -12,7 +12,7 @@ ha_domain: input_boolean
ha_integration_type: helper
---
The Input Boolean helper integration allows you to define boolean values that
The **Input boolean** helper integration allows you to define boolean values that
can be controlled via the user interface and can be used within conditions of
an {% term automation %}. This can for example be used to disable or enable certain
automations by using them in their {% term conditions %}.
@ -68,10 +68,10 @@ This integration provides the following {% term services %} to modify the state
Home Assistant itself.
| Service | Data | Description |
| ------- | ---- | ----------- |
| `turn_on` | `entity_id(s)`<br>`area_id(s)` | Set the value of specific `input_boolean` entities to `on`
| `turn_off` | `entity_id(s)`<br>`area_id(s)` | Set the value of specific `input_boolean` entities to `off`
| `toggle` | `entity_id(s)`<br>`area_id(s)` | Toggle the value of specific `input_boolean` entities
| ---------- | ------------------------------ | ----------------------------------------------------------- |
| `turn_on` | `entity_id(s)`<br>`area_id(s)` | Set the value of specific `input_boolean` entities to `on` |
| `turn_off` | `entity_id(s)`<br>`area_id(s)` | Set the value of specific `input_boolean` entities to `off` |
| `toggle` | `entity_id(s)`<br>`area_id(s)` | Toggle the value of specific `input_boolean` entities |
| `reload` | | Reload `input_boolean` configuration |
### Restore state

6
source/_integrations/input_button.markdown
View File

@ -1,6 +1,6 @@
---
title: Input Button
description: Instructions on how to use the Input Button helper with Home Assistant.
title: Input button
description: Instructions on how to use the input button helper with Home Assistant.
ha_category:
- Automation
- Helper
@ -12,7 +12,7 @@ ha_domain: input_button
ha_integration_type: helper
---
The Input Button helper integration allows you to define buttons that
The **Input button** helper integration allows you to define buttons that
can be pressed via the user interface, and can be used to trigger things,
like an automation.

14
source/_integrations/input_number.markdown
View File

@ -1,6 +1,6 @@
---
title: Input Number
description: Instructions on how to integrate the Input Number integration into Home Assistant.
title: Input number
description: Instructions on how to integrate the input number integration into Home Assistant.
ha_category:
- Automation
- Helper
@ -12,7 +12,7 @@ ha_domain: input_number
ha_integration_type: helper
---
The `input_number` integration allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. The frontend can display a slider, or a numeric input box. Changes to the slider or numeric input box generate state events. These state events can be utilized as `automation` triggers as well.
The **Input number** {% term integration %} allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. The frontend can display a slider, or a numeric input box. Changes to the slider or numeric input box generate state events. These state events can be utilized as `automation` triggers as well.
The preferred way to configure an input number is via the user interface at **{% my helpers title="Settings > Devices & Services > Helpers" %}**. Click the add button and then choose the **{% my config_flow_start domain="input_number" title="Number" %}** option.
@ -88,11 +88,11 @@ This integration provides the following services to modify the state of the `inp
configuration without restarting Home Assistant itself.
| Service | Data | Description |
| ------- | ---- | ----------- |
| `decrement` | `entity_id(s)`<br>`area_id(s)` | Decrement the value of specific `input_number` entities by `step`
| `increment` | `entity_id(s)`<br>`area_id(s)` | Increment the value of specific `input_number` entities by `step`
| ----------- | ----------------------------------------- | ----------------------------------------------------------------- |
| `decrement` | `entity_id(s)`<br>`area_id(s)` | Decrement the value of specific `input_number` entities by `step` |
| `increment` | `entity_id(s)`<br>`area_id(s)` | Increment the value of specific `input_number` entities by `step` |
| `reload` | | Reload `input_number` configuration |
| `set_value` | `value`<br>`entity_id(s)`<br>`area_id(s)` | Set the value of specific `input_number` entities
| `set_value` | `value`<br>`entity_id(s)`<br>`area_id(s)` | Set the value of specific `input_number` entities |
### Restore state

24
source/_integrations/input_select.markdown
View File

@ -1,6 +1,6 @@
---
title: Input Select
description: Instructions on how to integrate the Input Select integration into Home Assistant.
title: Input select
description: Instructions on how to integrate the input select integration into Home Assistant.
ha_category:
- Automation
- Helper
@ -12,7 +12,7 @@ ha_domain: input_select
ha_integration_type: helper
---
The `input_select` integration allows the user to define a list of values that can be selected via the frontend and can be used within conditions of an automation. When a user selects a new item, a state transition event is generated. This state event can be used in an `automation` trigger.
The **Input select** {% term integration %} allows the user to define a list of values that can be selected via the frontend and can be used within conditions of an automation. When a user selects a new item, a state transition event is generated. This state event can be used in an `automation` trigger.
The preferred way to configure an input select is via the user interface at **{% my helpers title="Settings > Devices & Services > Helpers" %}**. Click the add button and then choose the **{% my config_flow_start domain="input_select" title="Dropdown" %}** option.
@ -78,11 +78,11 @@ If you set a valid value for `initial` this integration will start with the stat
This integration provides three services to modify the state of the `input_select`.
| Service | Data | Description |
| ------- | ---- | ----------- |
| `select_option` | `option` | This can be used to select a specific option.
| `set_options` | `options`<br>`entity_id(s)` | Set the options for specific `input_select` entities.
| `select_first` | | Select the first option.
| `select_last` | | Select the last option.
| --------------- | --------------------------- | ----------------------------------------------------- |
| `select_option` | `option` | This can be used to select a specific option. |
| `set_options` | `options`<br>`entity_id(s)` | Set the options for specific `input_select` entities. |
| `select_first` | | Select the first option. |
| `select_last` | | Select the last option. |
| `reload` | | Reload `input_select` configuration |
#### Service `input_select.select_next`
@ -90,16 +90,16 @@ This integration provides three services to modify the state of the `input_selec
Select the next option.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `cycle` | yes | Whether to cycle to the first value after the last. Default: `true`
| ---------------------- | -------- | ------------------------------------------------------------------- |
| `cycle` | yes | Whether to cycle to the first value after the last. Default: `true` |
#### Service `input_select.select_previous`
Select the previous option.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `cycle` | yes | Whether to cycle to the last value before the first. Default: `true`
| ---------------------- | -------- | -------------------------------------------------------------------- |
| `cycle` | yes | Whether to cycle to the last value before the first. Default: `true` |
### Scenes

10
source/_integrations/input_text.markdown
View File

@ -1,6 +1,6 @@
---
title: Input Text
description: Instructions on how to integrate the Input Text integration into Home Assistant.
title: Input text
description: Instructions on how to integrate the Input text integration into Home Assistant.
ha_category:
- Automation
- Helper
@ -12,7 +12,7 @@ ha_domain: input_text
ha_integration_type: helper
---
The `input_text` integration allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. It can also be configured in password mode (obscured text).
The **Input text** {% term integration %} allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. It can also be configured in password mode (obscured text).
The preferred way to configure an input text is via the user interface at **{% my helpers title="Settings > Devices & Services > Helpers" %}**. Click the add button and then choose the **{% my config_flow_start domain="input_text" title="Text" %}** option.
@ -84,8 +84,8 @@ input_text:
This integration provides a service to modify the state of the `input_text` and a service to reload the `input_text` configuration without restarting Home Assistant itself.
| Service | Data | Description |
| ------- | ---- | ----------- |
| `set_value` | `value`<br>`entity_id(s)` | Set the value for specific `input_text` entities.
| ----------- | ------------------------- | ------------------------------------------------- |
| `set_value` | `value`<br>`entity_id(s)` | Set the value for specific `input_text` entities. |
| `reload` | | Reload `input_text` configuration |
### Restore state

2
source/_integrations/konnected.markdown
View File

@ -111,7 +111,7 @@ Once all zones are configured you'll be presented with the configuration for add
**Blink panel LED on when sending state change:** The desired LED behavior for the panel.
**Override default Home Assistant API host panel URL:** The Konnected Alarm Panel post sensor states back to the Home Assistant API. If this value is unchecked the panel will default postbacks using the URL [configured](/docs/configuration/basic) in Home Assistant. By default, the integration will use the internal URL. However, if you check this field and set the **Override API host URL** to your _local_ IP address and port (e.g., `http://192.168.1.101:8123`), it will be used instead of the internal URL.
**Override default Home Assistant API host panel URL:** The Konnected Alarm Panel post sensor states back to the Home Assistant API. If this value is unchecked the panel will default postbacks using the URL [configured](/integrations/homeassistant/#allowlist_external_urls) in Home Assistant. By default, the integration will use the internal URL. However, if you check this field and set the **Override API host URL** to your _local_ IP address and port (e.g., `http://192.168.1.101:8123`), it will be used instead of the internal URL.
**Override API host URL (optional):** The host info to use if you checked **Override default Home Assistant API host panel URL** in the step above. This is ignored if **Override default Home Assistant API host panel URL** is unchecked.

6
source/_integrations/local_calendar.markdown
View File

@ -1,6 +1,6 @@
---
title: Local Calendar
description: Instructions on how to use Local Calendars in Home Assistant.
title: Local calendar
description: Instructions on how to use local calendars in Home Assistant.
ha_category:
- Calendar
ha_iot_class: Local Polling
@ -15,7 +15,7 @@ ha_codeowners:
ha_integration_type: integration
---
The local calendar integration allows you to create a calendar of events in Home Assistant for powering automations.
The **Local calendar** {% term integration %} allows you to create a calendar of events in Home Assistant for powering automations.
A calendar entity has a state and attributes that represent the next upcoming event (only). A calendar trigger is a much more flexible way to power automations with fewer limitations than using the entity state.

8
source/_integrations/local_file.markdown
View File

@ -1,6 +1,6 @@
---
title: Local File
description: Instructions how to use Local File as a Camera within Home Assistant.
title: Local file
description: Instructions how to use local file as a camera within Home Assistant.
ha_category:
- Camera
ha_iot_class: Local Polling
@ -11,7 +11,7 @@ ha_platforms:
ha_integration_type: integration
---
The `local_file` camera platform allows you to integrate an image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated. The service `local_file.update_file_path` can be used to update the image using an automation.
The **Local file** camera {% term integration %} allows you to integrate an image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated. The service `local_file.update_file_path` can be used to update the image using an automation.
The `local_file` camera can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodically and will then be displayed in Home Assistant.
@ -42,6 +42,6 @@ name:
Use this service to change the file displayed by the camera.
| Service data attribute | Description |
| -----------------------| ----------- |
| ---------------------- | ---------------------------------------------------- |
| `entity_id` | String of the `entity_id` of the camera to update. |
| `file_path` | The full path to the new image file to be displayed. |

4
source/_integrations/local_todo.markdown
View File

@ -1,5 +1,5 @@
---
title: Local To-do
title: Local to-do
description: Instructions on how to use local to-do lists in Home Assistant.
ha_category:
- To-do list
@ -19,7 +19,7 @@ related:
title: To-do list card
---
The **Local to-do list** integration allows you to create to-do lists in Home Assistant.
The **Local to-do list** {% term integration %} allows you to create to-do lists in Home Assistant.
To-do lists are shown on the **To-do list** dashboard for tracking items and whether
or not they have been completed.

2
source/_integrations/mailgun.markdown
View File

@ -12,7 +12,7 @@ ha_platforms:
ha_integration_type: integration
---
To be able to receive webhooks from Mailgun, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic)).
To be able to receive webhooks from Mailgun, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/integrations/homeassistant/#allowlist_external_urls).
To set it up, go to the integrations page in the configuration screen and find Mailgun. Click on configure. Follow the instructions on the screen to configure Mailgun.

2
source/_integrations/matrix.markdown
View File

@ -218,7 +218,7 @@ action:
<div class='note'>
If you need to include a file from an external folder in your notifications, you will have to [list the source folder as allowed](/docs/configuration/basic/).
If you need to include a file from an external folder in your notifications, you will have to [list the source folder as allowed](/integrations/homeassistant/#allowlist_external_dirs).
```yaml
configuration.yaml

2
source/_integrations/media_source.markdown
View File

@ -99,4 +99,4 @@ data:
media_content_id: "media-source://media_source/local/videos/favourites/Epic Sax Guy 10 Hours.mp4"
```
[basic-configuration]: /docs/configuration/basic/#media_dirs
[basic-configuration]: /integrations/homeassistant/#media_dirs

8
source/_integrations/minio.markdown
View File

@ -14,7 +14,7 @@ ha_integration_type: integration
This integration adds interaction with [Minio](https://min.io).
It also enables listening for bucket notifications: [see documentation](https://docs.min.io/docs/minio-client-complete-guide.html#watch)
To download or upload files, folders must be added to [allowlist_external_dirs](/docs/configuration/basic/).
To download or upload files, folders must be added to [allowlist_external_dirs](/integrations/homeassistant/#allowlist_external_dirs).
## Configuration
@ -134,7 +134,7 @@ These services are provided:
Download file.
| Service data attribute | Required | Description |
|---------------------------|----------|---------------------------------------------------|
| ---------------------- | -------- | ---------------------------------- |
| `bucket` | yes | Bucket to use |
| `key` | yes | Object key of the file |
| `file_path` | yes | File path on the local file system |
@ -144,7 +144,7 @@ Download file.
Upload file.
| Service data attribute | Required | Description |
|---------------------------|----------|---------------------------------------------------|
| ---------------------- | -------- | ---------------------------------- |
| `bucket` | yes | Bucket to use |
| `key` | yes | Object key of the file |
| `file_path` | yes | File path on the local file system |
@ -154,6 +154,6 @@ Upload file.
Delete file.
| Service data attribute | Required | Description |
|---------------------------|----------|---------------------------------------------------|
| ---------------------- | -------- | ---------------------- |
| `bucket` | yes | Bucket to use |
| `key` | yes | Object key of the file |

24
source/_integrations/mqtt.markdown
View File

@ -117,7 +117,6 @@ MQTT (aka MQ Telemetry Transport) is a machine-to-machine or "Internet of Things
{% enddetails %}
Your first step to get MQTT and Home Assistant working is to choose a broker.
## Setting up a broker
@ -144,7 +143,12 @@ Add the MQTT integration, then provide your broker's hostname (or IP address) an
3. Select **Configure**, then **Re-configure MQTT**.
<div class='note'>
<p>
If you experience an error message like `Failed to connect due to exception: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed`, then turn on `Advanced options` and set [Broker certificate validation](/integrations/mqtt/#broker-certificate-validation) to `Auto`.
</p>
</div>
### Advanced broker configuration
@ -327,7 +331,6 @@ support_url:
description: Support URL of the application that supplies the discovered MQTT item.
{% endconfiguration_basic %}
{% details "Supported abbreviations" %}
```txt
@ -599,7 +602,9 @@ support_url:
'sa': 'suggested_area',
'sn': 'serial_number',
```
{% enddetails %}
{% details "Supported abbreviations for origin info" %}
```txt
@ -607,6 +612,7 @@ support_url:
'sw': 'sw_version',
'url': 'support_url',
```
{% enddetails %}
### How to use discovery messages
@ -1054,16 +1060,15 @@ The MQTT notification support is different than for the other [notification](/in
```
<p class='img'>
<img src='/images/screenshots/mqtt-notify.png' />
<img src='/images/screenshots/mqtt-notify.png' alt='Screenshot showing how to publish a message to an MQTT topic'/>
</p>
The same will work for automations.
<p class='img'>
<img src='/images/screenshots/mqtt-notify-action.png' />
<img src='/images/screenshots/mqtt-notify-action.png' alt='Screenshot showing how to publish a message to an MQTT topic for automations' />
</p>
### Examples
#### REST API
@ -1124,9 +1129,16 @@ The MQTT integration will register the service `mqtt.publish` which allows publi
| `qos` | yes | Quality of Service to use. (default: 0) |
| `retain` | yes | If message should have the retain flag set. (default: false) |
<p class='note'>
<div class='note'>
<p>
You must include either `topic` or `topic_template`, but not both. If providing a payload, you need to include either `payload` or `payload_template`, but not both.
</p>
</div>
```yaml
topic: homeassistant/light/1/command

8
source/_integrations/netatmo.markdown
View File

@ -124,7 +124,7 @@ Set the heating schedule.
Set the preset mode for a Netatmo climate device. The preset mode must match a preset mode configured at Netatmo.
| Service data attribute | Required | Description |
| ---------------------- | -------- | ---------------------------------------------------------- |
| ---------------------- | -------- | ----------------------------------------------------------- |
| `preset_mode` | Yes | Climate preset mode such as Schedule, Away, or Frost Guard. |
| `end_datetime` | Yes | Date & time until which the preset will be active. |
@ -146,7 +146,7 @@ Sets the target temperature for a Netatmo climate device with an end date & time
Sets the target temperature for a Netatmo climate device as well as the time period during which this target temperature applies.
| Service data attribute | Required | Description |
| ---------------------- | -------- | ------------------------------------------------------ |
| ---------------------- | -------- | ----------------------------------------------------------- |
| `target_temperature` | Yes | The target temperature for the device. |
| `time_period` | Yes | Time period during which the target temperature is applied. |
@ -194,7 +194,7 @@ It is therefore recommended to use [an individual development account](#developm
</div>
To be able to receive events from [Netatmo](https://www.netatmo.com/), your Home Assistant instance needs to be accessible from the web over port `443`. To achieve this you can either use your Nabu Casa account or for example Duck DNS ([Home Assistant instructions](/addons/duckdns/)). You also need to have the external URL configured in the Home Assistant [configuration](/docs/configuration/basic).
To be able to receive events from [Netatmo](https://www.netatmo.com/), your Home Assistant instance needs to be accessible from the web over port `443`. To achieve this you can either use your Nabu Casa account or for example Duck DNS ([Home Assistant instructions](/addons/duckdns/)). You also need to have the external URL configured in the Home Assistant [configuration](/integrations/homeassistant/#allowlist_external_urls).
Events coming in from Netatmo will be available as an event in Home Assistant and are fired as `netatmo_event`, along with their data. You can use these events to trigger automations.
@ -304,7 +304,7 @@ Sign in using your username and password from your regular Netatmo account.
<div class='note warning'>
In your Netatmo Application configuration, do not enter a 'redirect URI' or a 'webhook URI'. The 'webhook URI' is automatically registered by this integration based on the external URL configured in the Home Assistant [configuration](/docs/configuration/basic).
In your Netatmo Application configuration, do not enter a 'redirect URI' or a 'webhook URI'. The 'webhook URI' is automatically registered by this integration based on the external URL configured in the Home Assistant [configuration](/integrations/homeassistant/#editing-the-general-settings-in-yaml).
</div>

6
source/_integrations/network.markdown
View File

@ -1,6 +1,6 @@
---
title: Network Configuration
description: Network Configuration for Home Assistant
title: Network configuration
description: Network configuration for Home Assistant
ha_category:
- Other
ha_release: 2021.6
@ -12,7 +12,7 @@ ha_codeowners:
ha_integration_type: system
---
This integration provides network configuration for integrations such as [Zeroconf](/integrations/zeroconf/). It is managed by going to **{% my network title="Settings > System > Network" %}** and is only available to users that have "Advanced Mode" enabled on their {% my profile title="user profile" %}.
The **Network configuration** {% term integration %} provides network configuration for integrations such as [Zeroconf](/integrations/zeroconf/). It is managed by going to **{% my network title="Settings > System > Network" %}** and is only available to users that have "Advanced Mode" enabled on their {% my profile title="user profile" %}.
**{% my general badge %}**

14
source/_integrations/pushbullet.markdown
View File

@ -60,12 +60,12 @@ The Pushbullet notification platform sends messages to [Pushbullet](https://www.
Pushbullet is a notify platform and thus can be controlled by calling the notify service [as described here](/integrations/notify/). It will send a notification to all devices registered in the Pushbullet account. An optional **target** parameter can be given to Pushbullet to specify specific account's devices, contacts or channels.
Type | Prefix | Suffix | Example
---- | ------ | ------ | -------
Device | `device/` | Device nickname | `device/iphone`
Channel | `channel/` | Channel tag | `channel/my_home`
Email | `email/` | Contact's email address | `email/email@example.com`
SMS | `sms/` | Contact's phone number | `sms/0612345678`
| Type | Prefix | Suffix | Example |
| ------- | ---------- | ----------------------- | ------------------------- |
| Device | `device/` | Device nickname | `device/iphone` |
| Channel | `channel/` | Channel tag | `channel/my_home` |
| Email | `email/` | Contact's email address | `email/email@example.com` |
| SMS | `sms/` | Contact's phone number | `sms/0612345678` |
If using targets, your own account's email address functions as 'send to all devices'. All targets are verified (if exists) before sending, except email.
@ -141,6 +141,6 @@ action:
<div class='note'>
Don't forget to [allowlist external directories](/docs/configuration/basic/), so Home Assistant has access to them.
Don't forget to [allowlist external directories](/integrations/homeassistant/#allowlist_external_dirs), so Home Assistant has access to them.
</div>

4
source/_integrations/recovery_mode.markdown
View File

@ -1,5 +1,5 @@
---
title: Recovery Mode
title: Recovery mode
description: Allows Home Assistant to start up in recovery mode.
ha_category: []
ha_release: 0.105
@ -13,7 +13,7 @@ related:
title: General troubleshooting
---
The **Recovery mode** integration is an internal integration used by the
The **Recovery mode** {% term integration %} is an internal integration used by the
Home Assistant Core.
You don't have to configure it since it is automatically always

2
source/_integrations/rpi_camera.markdown
View File

@ -87,4 +87,4 @@ file_path:
default: A temporary file is used.
{% endconfiguration %}
The given **file_path** must be an existing file because the camera platform setup performs a writeable check on it. Also, keep in mind that the path should be [whitelisted](/docs/configuration/basic/).
The given **file_path** must be an existing file because the camera platform setup performs a writeable check on it. Also, keep in mind that the path should be [whitelisted](/integrations/homeassistant/#allowlist_external_dirs).

14
source/_integrations/shopping_list.markdown
View File

@ -14,7 +14,7 @@ ha_platforms:
- todo
---
The `shopping_list` integration allows you to keep track of shopping list items.
The **Shopping list** {% term integration %} allows you to keep track of shopping list items.
Your shopping list will be accessible from the sidebar, and you can optionally add the [To-do list card](/dashboards/todo-list/) to your dashboard. With the [conversation integration](/integrations/conversation/), you can add items to your shopping list using voice commands like "Add eggs to my shopping list."
@ -29,7 +29,7 @@ You can add or remove items from your shopping list by using the following servi
Add an item to the shopping list.
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------------|
| ---------------------- | -------- | ---------------------------------------- |
| `name` | no | Name of the item to add. Example: "Milk" |
### Service `shopping_list.remove_item`
@ -37,7 +37,7 @@ Add an item to the shopping list.
Remove the first item with matching name from the shopping list.
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------------|
| ---------------------- | -------- | ------------------------------------------- |
| `name` | no | Name of the item to remove. Example: "Milk" |
### Service `shopping_list.complete_item`
@ -45,7 +45,7 @@ Remove the first item with matching name from the shopping list.
Mark the first item with matching name as completed in the shopping list. It does not remove the item.
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------------|
| ---------------------- | -------- | ------------------------------------------------------ |
| `name` | no | Name of the item to mark as completed. Example: "Milk" |
### Service `shopping_list.incomplete_item`
@ -53,7 +53,7 @@ Mark the first item with matching name as completed in the shopping list. It doe
Mark the first item with matching name as incomplete in the shopping list.
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------------|
| ---------------------- | -------- | ------------------------------------------------------- |
| `name` | no | Name of the item to mark as incomplete. Example: "Milk" |
### Service `shopping_list.complete_all`
@ -73,7 +73,7 @@ Clear completed items from the shopping list.
Sort all items by name in the shopping list.
| Service data attribute | Optional | Description |
|------------------------|----------|---------------------------------------------------------------------|
| ---------------------- | -------- | ------------------------------------------------------------------- |
| `reverse` | yes | Whether to sort in reverse (_descending_) order. (default: `False`) |
## Using in automations
@ -81,7 +81,7 @@ Sort all items by name in the shopping list.
A `shopping_list_updated` event is triggered when items in the list are modified, with the following data payload attached to it. This can be used to trigger automations such as sending a push notification when someone adds an item to the shopping list, which when clicked, will open the list.
| Data payload attribute | Description |
|------------------------|--------------------------------------------------------------------------------------------------------------------|
| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `action` | What action was taken on the item. Either `add` for a new item being added, or `update` for an item being updated. |
| `item` | A dictionary containing details of the item that was updated. |
| `item.id` | A unique ID for this item |

2
source/_integrations/signal_messenger.markdown
View File

@ -131,7 +131,7 @@ action:
### Text message with an attachment from a URL
To attach files from outside of Home Assistant, the URLs must be added to the [`allowlist_external_urls`](/docs/configuration/basic/#allowlist_external_urls) list.
To attach files from outside of Home Assistant, the URLs must be added to the [`allowlist_external_urls`](/integrations/homeassistant/#allowlist_external_urls) list.
Note there is a 50MB size limit for attachments retrieved via URLs. You can also set `verify_ssl` to `false` to ignore SSL errors (default `true`).

26
source/_integrations/slack.markdown
View File

@ -138,29 +138,29 @@ One sensor entity will be created:
The following attributes can be placed inside the `data` key of the service call for extended functionality:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `username` | yes | The username of the Slack bot.
| `icon` | yes | The icon of the Slack bot.
| `file` | yes | A file to include with the message; see below.
| `blocks` | yes | Array of [Slack blocks](https://api.slack.com/messaging/composing/layouts). *NOTE*: if using `blocks`, they are shown **in place of** the `message` within Slack apps. The message field will be used as notification text and anywhere else Slack is unable to display blocks. `message` is required regardless of whether this field is used.
| `blocks_template` | yes | The same as `blocks`, but able to support [templates](https://www.home-assistant.io/docs/configuration/templating).
| `thread_ts` | yes | Sends the message as a reply to a specified parent message.
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username` | yes | The username of the Slack bot. |
| `icon` | yes | The icon of the Slack bot. |
| `file` | yes | A file to include with the message; see below. |
| `blocks` | yes | Array of [Slack blocks](https://api.slack.com/messaging/composing/layouts). *NOTE*: if using `blocks`, they are shown **in place of** the `message` within Slack apps. The message field will be used as notification text and anywhere else Slack is unable to display blocks. `message` is required regardless of whether this field is used. |
| `blocks_template` | yes | The same as `blocks`, but able to support [templates](https://www.home-assistant.io/docs/configuration/templating). |
| `thread_ts` | yes | Sends the message as a reply to a specified parent message. |
Note that using `file` will ignore all usage of `blocks` and `blocks_template` (as Slack does not support those frameworks in messages that accompany uploaded files).
To include a local file with the Slack message, use these attributes underneath the `file` key:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `path` | no | A local filepath that has been [whitelisted](/docs/configuration/basic/#allowlist_external_dirs).
| --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `path` | no | A local filepath that has been [whitelisted](/integrations/homeassistant/#allowlist_external_dirs). |
To include a remote file with the Slack message, use these attributes underneath the `file` key:
| Attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `url` | no | A URL that has been [whitelisted](/docs/configuration/basic/#allowlist_external_urls).
| `username` | yes | An optional username if the URL is protected by HTTP Basic Auth.
| `password` | yes | An optional password if the URL is protected by HTTP Basic Auth.
| ---------- | -------- | ---------------------------------------------------------------------------------------- |
| `url` | no | A URL that has been [whitelisted](/integrations/homeassistant/#allowlist_external_urls). |
| `username` | yes | An optional username if the URL is protected by HTTP Basic Auth. |
| `password` | yes | An optional password if the URL is protected by HTTP Basic Auth. |
### Obtaining a member ID

18
source/_integrations/smartthings.markdown
View File

@ -64,7 +64,7 @@ The PAT is used to create a Home Assistant SmartApp in your SmartThings account
This integration requires an internet accessible incoming webhook to receive push updates from SmartThings. The preferred approach is to subscribe to [Home Assistant Cloud (Nabu Casa)](https://www.nabucasa.com/) and the integration will configure and use a cloudhook automatically. Alternatively, you will have to configure and setup an internet accessible webhook in Home Assistant as described below:
1. Setup [remote access](/docs/configuration/remote/) via a domain name secured with SSL. *Self-signed SSL certificates are not supported by the SmartThings Cloud API.*
2. Set the external URL in the Home Assistant [configuration](/docs/configuration/basic) to the URL that Home Assistant is available on the internet (this must start with `https://`). If you do not use Nabu Casa you must configure your network to allow TCP traffic from the internet to reach the IP address and port of the device running Home Assistant.
2. Set the external URL in the Home Assistant [configuration](/integrations/homeassistant/#external_url) to the URL that Home Assistant is available on the internet (this must start with `https://`). If you do not use Nabu Casa you must configure your network to allow TCP traffic from the internet to reach the IP address and port of the device running Home Assistant.
## Setup instructions
@ -141,7 +141,7 @@ Support for additional platforms will be added in the future.
The SmartThings binary sensor platform lets you view devices that have binary sensor-related capabilities. A binary sensor entity will be created for each attribute (below) supported by the device.
| Capability | Attribute | On-Value |
| ------------------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------- |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------- | ---------- |
| [`accelerationSensor`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#accelerationSensor) | `acceleration` | `active` |
| [`contactSensor`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#contactSensor) | `contact` | `open` |
| [`filterStatus`](https://developer.smartthings.com/docs/devices/capabilities/proposed#filterStatus) | `filterStatus` | `replace` |
@ -160,7 +160,7 @@ The SmartThings Climate platform lets you control devices that have air conditio
For a SmartThings Air Conditioner to be represented by the climate platform, it must have all of the following required capabilities:
| Capability | Climate Features |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`airConditionerMode`](https://developer.smartthings.com/docs/devices/capabilities/proposed#airConditionerMode) (required) | `hvac mode`, `hvac action` |
| [`airConditionerFanMode`](https://developer.smartthings.com/docs/devices/capabilities/proposed#airConditionerFanMode) (required) | `fan mode` |
| [`temperatureMeasurement`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#temperatureMeasurement) (required) | `temperature` |
@ -172,7 +172,7 @@ For a SmartThings Air Conditioner to be represented by the climate platform, it
For a SmartThings thermostat to be represented by the climate platform, it must have all the capabilities from either "set a" _or_ "set b":
| Capability | Climate Features |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| [`thermostat`](https://developer.smartthings.com/docs/devices/capabilities/deprecated#thermostat) (set a) | `hvac mode`, `hvac action`, `target temp high`, `target temp low` and `fan mode` |
| [`thermostatMode`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#thermostatMode) (set b) | `hvac mode` |
| [`thermostatCoolingSetpoint`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#thermostatCoolingSetpoint) (seb b) | `target temp low` |
@ -187,7 +187,7 @@ For a SmartThings thermostat to be represented by the climate platform, it must
The SmartThings Cover platform lets you control devices that have open/close related capabilities. For a device to be represented by the cover platform, it must have one of the capabilities from "set a" below.
| Capability | Cover Features |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| -------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| [`doorControl`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#doorControl) (set a) | `open` and `close` |
| [`garageDoorControl`](https://developer.smartthings.com/docs/devices/capabilities/deprecated#garageDoorControl) (seb a) | `open` and `close` |
| [`windowShade`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#windowShade) (set a) | `open` and `close` |
@ -200,7 +200,7 @@ The SmartThings Cover platform lets you control devices that have open/close rel
The SmartThings Fan platform lets you control devices that have fan-related capabilities. For a SmartThings device to be represented by the fan platform, it must have one or more of the capabilities below in addition to the [`switch`](https://smartthings.developer.samsung.com/develop/api-ref/capabilities.html#Switch) capability.
| Capability | Fan Features |
| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| --------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`fanSpeed`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#fanSpeed) | `speed` (`off`, `low`, `medium`, and `high`) |
### Light
@ -208,7 +208,7 @@ The SmartThings Fan platform lets you control devices that have fan-related capa
The SmartThings Light platform lets you control devices that have light-related capabilities. For a SmartThings device to be represented by the light platform, it must have one or more of the capabilities below in addition to the [`switch`](https://smartthings.developer.samsung.com/develop/api-ref/capabilities.html#Switch) capability.
| Capability | Light Features |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| ------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| [`switchLevel`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#switchLevel) | `brightness` and `transition` |
| [`colorControl`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#colorControl) | `color` |
| [`colorTemperature`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#colorTemperature) | `color_temp` |
@ -222,7 +222,7 @@ The SmartThings Lock platform lets you control devices that have the [`lock`](ht
The SmartThings Sensor platform lets your view devices that have sensor-related capabilities. A Sensor entity is created for each attribute (below) supported by the device.
| Capability | Attributes |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| [`activityLightingMode`](https://developer.smartthings.com/docs/devices/capabilities/proposed#activityLightingMode) | `lightingMode` |
| [`airConditionerMode`](https://developer.smartthings.com/docs/devices/capabilities/proposed#airConditionerMode) | `airConditionerMode` |
| [`airQualitySensor`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#airQualitySensor) | `airQuality` |
@ -287,7 +287,7 @@ The SmartThings Scene platform lets you activate scenes defined in SmartThings w
The SmartThings Switch platform lets you control devices that have the [`switch`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#switch) capability that are not already represented by a more specific platform. The following optional capabilities will provide energy and power utilization information:
| Capability | Switch Features |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| [`energyMeter`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#energyMeter) | energy consumption (`today_energy_kwh` state attribute) |
| [`powerMeter`](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference#powerMeter) | power consumption (`current_power_w` state attribute) |

2
source/_integrations/smtp.markdown
View File

@ -134,7 +134,7 @@ The optional `images` field adds image attachments to the email. If `html` is de
<div class='note info'>
When adding images, make sure the folders containing the attachments are added to `allowlist_external_dirs`.<br>See: [Setup basic documentation](/docs/configuration/basic/)
When adding images, make sure the folders containing the attachments are added to `allowlist_external_dirs`.<br>See: [Setup basic documentation](/integrations/homeassistant/#allowlist_external_dirs)
</div>

2
source/_integrations/telegram.markdown
View File

@ -265,7 +265,7 @@ inline_keyboard:
<div class='note'>
Since Home Assistant version 0.48 you have to [whitelist the source folder](/docs/configuration/basic/) of the file you want to include in the notification.
Since Home Assistant version 0.48 you have to [whitelist the source folder](/integrations/homeassistant/#allowlist_external_dirs) of the file you want to include in the notification.
```yaml
configuration.yaml

4
source/_integrations/telegram_webhooks.markdown
View File

@ -10,7 +10,7 @@ ha_domain: telegram_bot
Telegram chatbot webhooks implementation as described in the Telegram [documentation](https://core.telegram.org/bots/webhooks).
By default this integration sets your bot's webhook URL automatically to `https://<external_url>/api/telegram_webhooks` with the external_url of your Home Assistant [configuration](/docs/configuration/basic/) using Telegrams `setWebhook` method.
By default this integration sets your bot's webhook URL automatically to `https://<external_url>/api/telegram_webhooks` with the external_url of your Home Assistant [configuration](/integrations/homeassistant/#external_url) using Telegrams `setWebhook` method.
This is one of two bot implementations supported by Telegram. Described by Telegram as the preferred implementation but requires your Home Assistant instance to be exposed to the internet.
The other implementation method is [Telegram polling](/integrations/telegram_polling/), for which your Home Assistant instance does not have to be exposed to the internet.
@ -48,7 +48,7 @@ proxy_url:
required: false
type: string
url:
description: Allow to overwrite the external URL from the Home Assistant [configuration](/docs/configuration/basic/) for different setups (`https://<public_url>:<port>`).
description: Allow to overwrite the external URL from the Home Assistant [configuration](/integrations/homeassistant/#editing-the-general-settings-in-yaml) for different setups (`https://<public_url>:<port>`).
required: false
type: string
trusted_networks:

28
source/_integrations/transmission.markdown
View File

@ -84,40 +84,40 @@ All Transmission services require integration `entry_id`. To find it, go to Deve
### Service `add_torrent`
Adds a new torrent to download. It can either be a URL (HTTP, HTTPS or FTP), magnet link or a local file (make sure that the path is [white listed](/docs/configuration/basic/#allowlist_external_dirs)).
Adds a new torrent to download. It can either be a URL (HTTP, HTTPS or FTP), magnet link or a local file (make sure that the path is [white listed](/integrations/homeassistant/#allowlist_external_dirs)).
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entry_id` | no | The integration entry_id
| `torrent` | no | Torrent to download
| ---------------------- | -------- | ------------------------ |
| `entry_id` | no | The integration entry_id |
| `torrent` | no | Torrent to download |
### Service `remove_torrent`
Removes a torrent from the client.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entry_id` | no | The integration entry_id
| `id` | no | ID of the torrent, can be found in the `torrent_info` attribute of the `*_torrents` sensors
| `delete_data` | yes | Delete torrent data (Default: false)
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `entry_id` | no | The integration entry_id |
| `id` | no | ID of the torrent, can be found in the `torrent_info` attribute of the `*_torrents` sensors |
| `delete_data` | yes | Delete torrent data (Default: false) |
### Service `start_torrent`
Starts a torrent.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entry_id` | no | The integration entry_id
| `id` | no | ID of the torrent, can be found in the `torrent_info` attribute of the `*_torrents` sensors
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `entry_id` | no | The integration entry_id |
| `id` | no | ID of the torrent, can be found in the `torrent_info` attribute of the `*_torrents` sensors |
### Service `stop_torrent`
Stops a torrent.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entry_id` | no | The integration entry_id
| `id` | no | ID of the torrent, can be found in the `torrent_info` attribute of the `*_torrents` sensors
| ---------------------- | -------- | ------------------------------------------------------------------------------------------- |
| `entry_id` | no | The integration entry_id |
| `id` | no | ID of the torrent, can be found in the `torrent_info` attribute of the `*_torrents` sensors |
## Templating

2
source/_integrations/tts.markdown
View File

@ -133,7 +133,7 @@ $ curl -X POST -H "Authorization: Bearer <ACCESS TOKEN>" \
<div class='note'>
Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/docs/configuration/basic/).
Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/integrations/homeassistant/#external_url).
</div>

2
source/_integrations/twilio.markdown
View File

@ -41,7 +41,7 @@ auth_token:
After configuring the base Twilio integration, add and configure either or both of the [Twilio SMS](/integrations/twilio_sms) and [Twilio Phone](/integrations/twilio_call) integrations to utilize the notification functionality.
To be able to receive events from Twilio, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/docs/configuration/basic) in Home Assistant.
To be able to receive events from Twilio, your Home Assistant instance needs to be accessible from the web and you need to have the external URL [configured](/integrations/homeassistant/#external_url) in Home Assistant.
To set it up, go to the integrations page in the configuration screen and find Twilio. Click on configure. Follow the instructions on the screen to configure Twilio.

10
source/_integrations/vivotek.markdown
View File

@ -109,7 +109,7 @@ Available services: `enable_motion_detection`, `disable_motion_detection`, `snap
Play a live stream from a camera to selected media player(s). Requires [`stream`](/integrations/stream) {% term integration %} to be set up.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `entity_id` | no | Name of {% term entity %} to fetch stream from, e.g., `camera.front_door_camera`. |
| `media_player` | no | Name of media player to play stream on, e.g., `media_player.living_room_tv`. |
| `format` | yes | Stream format supported by `stream` {% term integration %} and selected `media_player`. Default: `hls` |
@ -130,7 +130,7 @@ action:
Enable motion detection in a camera. Currently, this will enable the first event configured on the camera.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | --------------------------------------------------------------------------------- |
| `entity_id` | yes | Name(s) of entities to enable motion detection, e.g., `camera.front_door_camera`. |
#### Service `disable_motion_detection`
@ -138,7 +138,7 @@ Enable motion detection in a camera. Currently, this will enable the first event
Disable the motion detection in a camera. Currently, this will disable the first event configured on the camera.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ---------------------------------------------------------------------------------- |
| `entity_id` | yes | Name(s) of entities to disable motion detection, e.g., `camera.front_door_camera`. |
#### Service `snapshot`
@ -146,11 +146,11 @@ Disable the motion detection in a camera. Currently, this will disable the first
Take a snapshot from a camera.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.front_door_camera`. |
| `filename` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/snapshot_{{ entity_id }}`{% endraw %}. |
The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file.
The path part of `filename` must be an entry in the `allowlist_external_dirs` in your [`homeassistant:`](/integrations/homeassistant/#allowlist_external_dirs) section of your `configuration.yaml` file.
For example, the following action is an automation that would take a snapshot from "front_door_camera" and save it to /tmp with a timestamped filename.

6
source/_redirects
View File

@ -256,6 +256,7 @@ layout: null
# Redirect for the QR Codes on the S3 Box
/s3-box-no-wifi /voice_control/troubleshooting_the_s3_box/#error-unable-to-connect-to-wi-fi
/s3-box-no-ha /voice_control/troubleshooting_the_s3_box/#error-no-home-assistant
/docs/assist/troubleshooting/ /voice_control/troubleshooting/
/docs/assist/worlds-most-private-voice-assistant/ /voice_control/worlds-most-private-voice-assistant/
/projects/worlds-most-private-voice-assistant/ /voice_control/worlds-most-private-voice-assistant/
@ -263,6 +264,11 @@ layout: null
/draw_assist /voice_control/s3-box-customize/#to-draw-your-own-images
/projects/thirteen-usd-voice-remote/ /voice_control/thirteen-usd-voice-remote/
/docs/backend/updater /integrations/analytics
/docs/configuration/basic/#allowlist_external_urls /integrations/homeassistant/#allowlist_external_urls
/docs/configuration/basic/#allowlist_external_dirs /integrations/homeassistant/#allowlist_external_dirs
/docs/configuration/basic/#external_urls /integrations/homeassistant/#external_urls
/docs/configuration/customizing-devices/#device-class /integrations/homeassistant/#device-class
/docs/configuration/customizing-devices/#customizing-entities /integrations/homeassistant/#editing-the-entity-settings-in-yaml
/docs/ecosystem/ios/ https://companion.home-assistant.io/
/docs/ecosystem/ios/devices_file https://companion.home-assistant.io/
/docs/ecosystem/ios/integration https://companion.home-assistant.io/docs/integrations/integrations

BIN
source/images/docs/configuration/config-yaml_via-file-editor.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 96 KiB

BIN
source/images/docs/configuration/config-yaml_via-vscode.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 264 KiB

BIN
source/images/docs/configuration/customizing-entity-dialog.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 26 KiB

BIN
source/images/docs/configuration/customizing-entity.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 26 KiB

After

Width:  |  Height:  |  Size: 82 KiB

BIN
source/images/docs/configuration/edit_entity-id_in_automation.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

BIN
source/images/docs/configuration/reload_restart.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 30 KiB

BIN
source/images/docs/configuration/settings_restart_ha.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 25 KiB

BIN
source/images/organizing/edit-delete-category.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
source/images/screenshots/System_information.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 12 KiB

BIN
source/images/screenshots/system_information.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 51 KiB