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-15 21:36:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'next' into rc

Browse Source
This commit is contained in:
Franck Nijhof 2023-04-26 18:56:44 +02:00
commit 7bf3e38bca
No known key found for this signature in database
GPG Key ID: D62583BA8AB11CA3
141 changed files with 2316 additions and 1273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Gemfile
View File

@ -7,7 +7,7 @@ group :development do
gem 'jekyll', '4.3.2'
gem 'compass', '1.0.3'
gem 'sass-globbing', '1.1.5'
gem 'stringex', '2.8.5'
gem 'stringex', '2.8.6'
# > 2.1.0 causes slowdowns https://github.com/sass/sassc-ruby/issues/189
gem 'sassc', '2.1.0'
end

12
Gemfile.lock
View File

@ -29,7 +29,7 @@ GEM
forwardable-extended (2.6.0)
google-protobuf (3.22.3)
http_parser.rb (0.8.0)
i18n (1.12.0)
i18n (1.13.0)
concurrent-ruby (~> 1.0)
jekyll (4.3.2)
addressable (~> 2.4)
@ -79,7 +79,7 @@ GEM
forwardable-extended (~> 2.6)
public_suffix (5.0.1)
racc (1.6.2)
rack (2.2.6.4)
rack (2.2.7)
rack-protection (3.0.6)
rack
rake (13.0.6)
@ -91,10 +91,10 @@ GEM
ruby2_keywords (0.0.5)
safe_yaml (1.0.5)
sass (3.4.25)
sass-embedded (1.62.0)
sass-embedded (1.62.1)
google-protobuf (~> 3.21)
rake (>= 10.0.0)
sass-embedded (1.62.0-x64-mingw32)
sass-embedded (1.62.1-x64-mingw32)
google-protobuf (~> 3.21)
sass-globbing (1.1.5)
sass (>= 3.1)
@ -107,7 +107,7 @@ GEM
rack (~> 2.2, >= 2.2.4)
rack-protection (= 3.0.6)
tilt (~> 2.0)
stringex (2.8.5)
stringex (2.8.6)
terminal-table (3.0.2)
unicode-display_width (>= 1.1.1, < 3)
tilt (2.1.0)
@ -134,7 +134,7 @@ DEPENDENCIES
sass-globbing (= 1.1.5)
sassc (= 2.1.0)
sinatra (= 3.0.6)
stringex (= 2.8.5)
stringex (= 2.8.6)
tzinfo (~> 2.0)
tzinfo-data

8
_config.yml
View File

@ -199,7 +199,7 @@ installation:
types:
odroid:
board: ODROID
installation_media: "eMMC module/SD card"
installation_media: "eMMC module or SD card"
variants:
- name: "ODROID-N2"
key: "odroid-n2"
@ -209,8 +209,8 @@ installation:
key: "odroid-c2"
- name: "ODROID-C4"
key: "odroid-c4"
- name: "ODROID-XU4"
key: "odroid-xu4"
- name: "ODROID-M1"
key: "odroid-m1"
raspberrypi:
board: Raspberry Pi
@ -223,7 +223,7 @@ installation:
tinkerboard:
board: ASUS Tinkerboard
installation_media: "eMMC module/SD card"
installation_media: "eMMC module or SD card"
variants:
- name: "ASUS Tinkerboard"
key: "tinker"

6
package-lock.json generated
View File

@ -4718,9 +4718,9 @@
"dev": true
},
"node_modules/yaml": {
"version": "2.2.1",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.2.1.tgz",
"integrity": "sha512-e0WHiYql7+9wr4cWMx3TVQrNwejKaEe7/rHNmQmqRjazfOP5W8PB6Jpebb5o6fIapbz9o9+2ipcaTM2ZwDI6lw==",
"version": "2.2.2",
"resolved": "https://registry.npmjs.org/yaml/-/yaml-2.2.2.tgz",
"integrity": "sha512-CBKFWExMn46Foo4cldiChEzn7S7SRV+wqiluAb6xmueD/fGyRHIhX8m14vVGgeFWjN540nKCNVj6P21eQjgTuA==",
"dev": true,
"engines": {
"node": ">= 14"

2
source/_dashboards/entities.markdown
View File

@ -227,7 +227,7 @@ entities:
required: false
description: If false, the button name is not shown.
type: boolean
default: "true"
default: "false"
show_icon:
required: false
description: If false, the icon is not shown.

2
source/_dashboards/history-graph.markdown
View File

@ -5,7 +5,7 @@ sidebar_label: History Graph
description: "The History Graph card allows you to display a graph for each of the entities listed."
---
The History Graph card allows you to display a graph for each of the entities listed.
The History Graph card allows you to display a graph for each of up to eight entities.
<p class='img'>
<img src='/images/dashboards/history_graph.png' alt='Screenshot of the history graph card for entities without a unit_of_measurement'>

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

@ -370,7 +370,7 @@ conditions:
type: string
elements:
required: true
description: One or more elements of any type to show when conditions are met. See below for an example.
description: One or more elements of any of the [listed types](#elements) to show when conditions are met. See below for an example.
type: list
{% endconfiguration %}

4
source/_dashboards/tile.markdown
View File

@ -8,8 +8,8 @@ description: "The tile card gives you a quick overview of your entity. The card
The tile card gives you a quick overview of your entity. The card allows you to toggle the entity and show the more info dialog. A badge is shown for some entities like the [climate](/integrations/climate) or [person](/integrations/person) entities.
<p class='img'>
<img src='/images/dashboards/tile_card.png' alt='Screenshot of the tile card'>
Screenshot of the Tile card.
<img src='/images/dashboards/tile_card.png' alt='Screenshot of tile cards'>
Screenshot of Tile cards.
</p>
To add the Tile card to your user interface, click the menu (three dots at the top right of the screen) and then **Edit Dashboard**. Click the "Add Card" button in the bottom right corner and select **Tile** from the card picker.

20
source/_data/glossary.yml
View File

@ -9,12 +9,18 @@
#
- term: Action
definition: >-
An action is an command that can be fired. For example, turning on a light.
Actions used in many places, most notably in automations and scripts.
definition: |-
Actions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called *sequence*.
Actions use service calls and/or scenes to interact with entities and cause these entities to do something. Actions can also include conditions and a delay. An action can call multiple services at the same time. For example, if your presence is detected in a room, an action may call one service to turn on a light and call another service to start playing music after a delay.
Actions are also used on the dashboard, for example as tap or hold action on a UI element. When triggered, the action calls a service.
aliases:
- actions
link: /docs/automation/action/
excerpt: >
Actions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called *sequence*.
- term: Add-on
definition: >-
@ -91,6 +97,8 @@
Devices have properties such as ID, manufacturer, name, model, hardware version, firmware version, connections, etc.
excerpt: >
A device is a model representing a physical or logical unit that contains entities.
aliases:
- devices
- term: Device tracker
definition: >-
@ -216,6 +224,8 @@
Integrations connect and integrates Home Assistant with your devices,
services, and more.
link: /integrations/
aliases:
- integrations
- term: Lovelace
definition: >-
@ -275,6 +285,8 @@
Sensors return information about a thing, for instance the level of water
in a tank.
link: /integrations/sensor/
aliases:
- sensors
- term: Selectors
definition: >-
@ -361,3 +373,5 @@
definition: >-
Zones are areas that can be used for presence detection.
link: /integrations/zone/
aliases:
- zones

28
source/_docs/automation/editor.markdown
View File

@ -5,29 +5,25 @@ description: "Instructions on how to use the automation editor."
The automation editor is an easy way of creating and editing automations from the UI. This page uses the [Random sensor](/integrations/random#sensor) as an example, though any other sensor with a numeric value can be used as well.
From the UI, choose **{% my config %}** which is located in the sidebar, then click on **{% my automations %}** to go to the automation editor. Press the **Create Automation** button in the lower right corner to get started. You can create an automation based on a [blueprint](/docs/automation/using_blueprints/) or start from scratch.
From the UI, choose **{% my config %}** which is located in the sidebar, then click on **{% my automations %}** to go to the automation editor. Press the **Create Automation** button in the lower right corner to get started. You can create an automation based on a [blueprint](/docs/automation/using_blueprints/) or start from scratch. Select **Create new automation**.
<p class='img'>
<img src='/images/docs/automation-editor/create-automation.png' />
</p>
![Create automation dialogue box](/images/docs/automation-editor/create-automation.png)
Select **Start with an empty automation** and choose a meaningful name for your new automation.
Click on the **Add Trigger** button and select **Nurmeric state**.
<p class='img'>
<img src='/images/docs/automation-editor/new-automation.png' />
</p>
![Add trigger](/images/docs/automation-editor/add-trigger-to-automation.png)
If the value of the sensor is greater than 10, then the automation should trigger.
<p class='img'>
<img src='/images/docs/automation-editor/new-trigger.png' />
</p>
![Automation trigger](/images/docs/automation-editor/new-trigger.png)
Click on the **Add Action** button and select **Call service**.
![Add trigger](/images/docs/automation-editor/new-action.png)
The action for this automation creates a [persistent notification](/integrations/persistent_notification/).
<p class='img'>
<img src='/images/docs/automation-editor/new-action.png' />
</p>
![Automation action](/images/docs/automation-editor/send-notification.png)
As the message we want a simple text that is shown as part of the notification.
@ -35,6 +31,10 @@ As the message we want a simple text that is shown as part of the notification.
message: Sensor value greater than 10
```
Press the **Save** button, and the save dialogue will appear. Give your automation a meaningful name and press the **Save** button again.
![New automation editor](/images/docs/automation-editor/new-automation.png)
Automations created or edited via the user interface are activated immediately after saving the automation. Read the documentation for [Automating Home Assistant](/getting-started/automation/) to learn more about automations.
## Troubleshooting missing automations

34
source/_docs/automation/templating.markdown
View File

@ -13,19 +13,25 @@ The variable `this` is the [state object](/docs/configuration/state_object) of t
## Available Trigger Data
The following tables show the available trigger data per platform.
The variable `trigger` is an object that contains details about which trigger triggered the automation.
Templates can use the data to modify the actions performed by the automation or displayed in a message. For example, you could create an automation that multiple sensors can trigger and then use the sensor's location to specify a light to activate; or you could send a notification containing the friendly name of the sensor that triggered it.
Each [trigger platform](/docs/automation/trigger/#event-trigger) can include additional data specific to that platform.
### All
The following describes trigger data associated with all platforms.
Triggers from all platforms will include the following data.
| Template variable | Data |
| ---- | ---- |
| `trigger.id` | Optional trigger `id`, or index of the trigger.
| `trigger.id` | The [`id` of the trigger](/docs/automation/trigger/#trigger-id).
| `trigger.idx` | Index of the trigger. (The first trigger idx is `0`.)
### Calendar
These are the properties available for a [Calendar trigger](/docs/automation/trigger/#calendar-trigger).
| Template variable | Data |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `trigger.platform` | Hardcoded: `calendar` |
@ -41,6 +47,8 @@ The following describes trigger data associated with all platforms.
### Device
These are the properties available for a [Device trigger](/docs/automation/trigger/#device-trigger).
Inherites template variables from [event](#event) or [state](#state) template based on the type of trigger selected for the device.
| Template variable | Data |
@ -49,6 +57,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Event
These are the properties available for a [Event trigger](/docs/automation/trigger/#event-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `event`.
@ -58,6 +68,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### MQTT
These are the properties available for a [MQTT trigger](/docs/automation/trigger/#mqtt-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `mqtt`.
@ -68,6 +80,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Numeric State
These are the properties available for a [Numeric State trigger](/docs/automation/trigger/#numeric-state-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `numeric_state`
@ -80,6 +94,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### State
These are the properties available for a [State trigger](/docs/automation/trigger/#state-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `state`
@ -90,6 +106,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Sun
These are the properties available for a [Sun trigger](/docs/automation/trigger/#sun-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `sun`
@ -98,6 +116,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Template
These are the properties available for a [Template trigger](/docs/automation/trigger/#template-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `template`
@ -108,6 +128,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Time
These are the properties available for a [Time trigger](/docs/automation/trigger/#time-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `time`
@ -115,6 +137,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Time Pattern
These are the properties available for a [Time Pattern trigger](/docs/automation/trigger/#time-pattern-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `time_pattern`
@ -122,6 +146,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Webhook
These are the properties available for a [Webhook trigger](/docs/automation/trigger/#webhook-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `webhook`
@ -132,6 +158,8 @@ Inherites template variables from [event](#event) or [state](#state) template ba
### Zone
These are the properties available for a [Zone trigger](/docs/automation/trigger/#zone-trigger).
| Template variable | Data |
| ---- | ---- |
| `trigger.platform` | Hardcoded: `zone`

9
source/_docs/automation/trigger.markdown
View File

@ -786,6 +786,10 @@ automation:
trigger:
- platform: webhook
webhook_id: "some_hook_id"
allowed_methods:
- POST
- PUT
local_only: true
```
You can run this automation by sending an HTTP POST request to `http://your-home-assistant:8123/api/webhook/some_hook_id`. Here is an example using the **curl** command line program, with an example form data payload:
@ -794,7 +798,9 @@ You can run this automation by sending an HTTP POST request to `http://your-home
curl -X POST -d 'key=value&key2=value2' https://your-home-assistant:8123/api/webhook/some_hook_id
```
Webhooks support HTTP POST, PUT, and HEAD requests; POST requests are recommended. HTTP GET requests are not supported.
Webhooks support HTTP POST, PUT, HEAD, and GET requests; PUT requests are recommended. HTTP GET and HEAD requests are not enabled by default but can be enabled by adding them to the `allowed_methods` option. The request methods can also be configured in the UI by clicking the settings gear menu button beside the Webhook ID.
By default, webhook triggers can only be accessed from devices on the same network as Home Assistant or via [Nabu Casa Cloud webhooks](https://www.nabucasa.com/config/webhooks/). The `local_only` option should be set to `false` to allow webhooks to be triggered directly via the internet. This option can also be configured in the UI by clicking the settings gear menu button beside the Webhook ID.
Remember to use an HTTPS URL if you've secured your Home Assistant installation with SSL/TLS.
@ -817,6 +823,7 @@ Webhook endpoints don't require authentication, other than knowing a valid webho
- Do not use webhooks to trigger automations that are destructive, or that can create safety issues. For example, do not use a webhook to unlock a lock, or open a garage door.
- Treat a webhook ID like a password: use a unique, non-guessable value, and keep it secret.
- Do not copy-and-paste webhook IDs from public sources, including blueprints. Always create your own.
- Keep the `local_only` option enabled for webhooks if access from the internet is not required.
## Zone trigger

2
source/_docs/configuration.markdown
View File

@ -40,6 +40,6 @@ If you can't see your integration listed there, you will need to restart Home As
## Migrating to a new system
The preferred way of migrating to a new system is by {% my supervisor_backups title="making a backup" %}.
The preferred way of migrating to a new system is by {% my supervisor_backups title="making a backup" %}. Once you have created the backup on the old system, you can download it to the system that is running the Home Assistant frontend. When setting up the new system, you may use the backup. Alternatively, you can upload it to your new system using the *Upload backup* menu option of the *Backups* menu. Then, a restore of the uploaded backup on the new system concludes the migration.
If you run the container or core installation methods, you will need to manually make a backup of your configuration folder. Be aware that some of the files you need start with `.`, which is hidden by default from both `ls` (in SSH), in Windows Explorer, and macOS Finder. You'll need to ensure that you're viewing all files before you copy them.

3
source/_docs/energy/gas.markdown
View File

@ -29,3 +29,6 @@ We have worked with creator [Marcel Zuidwijk](https://www.zuidwijk.com) to devel
![Photo of the AI-on-the-edge-device Workflow](/images/docs/energy/ai-on-the-edge-device.jpg)
#### Read the Gas Meter using a magnetometer
[Diaphragm gas meters](https://en.wikipedia.org/wiki/Gas_meter#Diaphragm/bellows_meters) are the most common type of gas meter, and their movement can frequently be observed with a magnetometer. The [QMC5883L](https://esphome.io/components/sensor/qmc5883l.html) is a common and inexpensive option that ESPHome supports. Many posts on the forums of users having luck with this method, such as [this one](https://community.home-assistant.io/t/water-gas-meter-monitoring-via-magnetometer-sine-wave-to-pulse-issue/245904).

2
source/_docs/scripts.markdown
View File

@ -779,7 +779,7 @@ automation:
message: "These messages are sent at the same time!"
```
It is also possible to run a group of actions sequantially inside the parallel
It is also possible to run a group of actions sequentially inside the parallel
actions. The example below demonstrates that:
```yaml

15
source/_docs/z-wave/controllers.markdown
View File

@ -120,3 +120,18 @@ You should also check the README for details on the overlays. You might find it
If you've installed the Z-Wave.Me Z-Way software. In order to use Z-Wave JS instead of Z-Way, you'll need to ensure you disable it before you install Home Assistant, or you won't be able to access the board. Do this with `sudo /etc/init.d/z-way-server stop; sudo update-rc.d z-way-server disable`. Alternatively, you could use the [Z-Wave.Me](/integrations/zwave_me) integration.
</div>
#### Setting up a Raspberry Pi Z-Wave module on Home Assistant Yellow
This procedure has been tested with the following modules:
* Aeotec Z-Pi 7 Raspberry Pi HAT/Shield
* Z-Wave.Me RaZberry 7
* Z-Wave.Me RaZberry 7 Pro
1. Make sure the module is properly seated on the Home Assistant Yellow.
![Aeotec Z-Pi 7 on Home Assistant Yellow](/images/docs/z-wave/zpi-7-yellow.jpg).
1. Carefully [close the case](https://yellow.home-assistant.io/guides/add-ssd-existing-installation/#reassembling-top-part) and power up Home Assistant Yellow.
1. Follow the procedure on [setting up a Z-Wave JS server](/integrations/zwave_js/#setting-up-a-z-wave-js-server).
1. In step 2, follow the manual setup steps to install the Z-Wave integration.
1. in Step 4, you will be prompted to choose a **Device path**. Choose **ttyAMA0**.

6
source/_examples/configuration_yaml_by_ntalekt.markdown Normal file
View File

@ -0,0 +1,6 @@
---
title: "Configuration.yaml by ntalekt"
description: "Unifi, ZHA, Pentair, Tuya, Tasmota"
ha_category: Example configuration.yaml
ha_external_link: https://github.com/ntalekt/homeassistant
---

10
source/_includes/asides/docs_navigation.html
View File

@ -177,6 +177,16 @@
<li>{% active_link /integrations/mqtt/#logging Logging %}</li>
</ul>
</li>
<li>
<b>Hardware</b>
<ul>
<li>
<a href="https://yellow.home-assistant.io/">Home Assistant Yellow</a>
</li>
<li>
<a href="https://skyconnect.home-assistant.io/">Home Assistant SkyConnect</a>
</ul>
</li>
</ul>
</div>
</section>

22
source/_includes/common-tasks/flashing_n2_otg.md
View File

@ -11,6 +11,7 @@ To flash your eMMC using Petitboot and OTG-USB, you will need the following item
- HDMI cable and monitor
- USB keyboard
- USB 2.0 to micro-USB cable
- If your board came in a Home Assistant Blue: No.2 hex key to open the case
#### Enabling SPI boot mode
@ -45,13 +46,13 @@ You can safely ignore this message and proceed with the installation
</div>
2. Use the following command at the console to confirm the storage device node:
1. Use the following command at the console to confirm the storage device node:
```bash
ls /dev/mmc*
```
3. Set the storage device on the ODROID-N2+ as a mass storage device using the `ums` command (USB Mass storage mode).
1. Set the storage device on the ODROID-N2+ as a mass storage device using the `ums` command (USB Mass storage mode).
This will configure the ODROID-N2+ and OTG to act as a memory card reader:
```bash
@ -60,10 +61,19 @@ This will configure the ODROID-N2+ and OTG to act as a memory card reader:
#### Flashing Home Assistant
Connect the ODROID-N2+ to your PC via the micro-USB port at the front of the ODROID-N2+. When the ODROID-N2 is recognized as a USB connected storage device, you can flash the eMMC with [Etcher](https://www.balena.io/etcher/) using the latest stable version of Home Assistant OS for the [ODROID-N2+](https://github.com/home-assistant/operating-system/releases/download/{{site.data.version_data.hassos['odroid-n2']}}/haos_odroid-n2-{{site.data.version_data.hassos['odroid-n2']}}.img.xz) (haos_odroid-n2-{{site.data.version_data.hassos['odroid-n2']}}.img.xz).
1. Connect the ODROID-N2+ to your PC via the micro-USB port at the front of the ODROID-N2+.
1. When the ODROID-N2 is recognized as a USB connected storage device, you can flash the eMMC with [Etcher](https://www.balena.io/etcher/).
* Use the latest stable version of Home Assistant OS for the [ODROID-N2+](https://github.com/home-assistant/operating-system/releases/download/{{site.data.version_data.hassos['odroid-n2']}}/haos_odroid-n2-{{site.data.version_data.hassos['odroid-n2']}}.img.xz) (haos_odroid-n2-{{site.data.version_data.hassos['odroid-n2']}}.img.xz).
When the flash process is complete, disconnect the ODROID-N2+ from your PC and remove the power cable. Remove the USB and HDMI cable, and make sure to toggle the boot mode switch back to MMC.
1. When the flash process is complete, disconnect the ODROID-N2+ from your PC.
* Remove the power cable.
* Remove the USB and HDMI cables.
* Make sure to toggle the boot mode switch back to MMC.
Once it is back in its case, connect your ODROID-N2+ to your network with an Ethernet cable and plug in power.
1. Put the ODROID back in its case.
1. Connect your ODROID-N2+ to your network with an Ethernet cable and plug in power.
If your router supports mDNS, you will be able to reach your installation on `http://homeassistant.local:8123`. If your network doesn’t support mDNS, you’ll have to use the IP address of your ODROID-N2+ instead of `homeassistant.local`. For example, `http://192.168.0.9:8123`. You should be able to find the IP address of your ODROID-N2+ from the admin interface of your router.
1. If your router supports mDNS, you can reach your installation at `http://homeassistant.local:8123`.
* If your network doesn’t support mDNS, you’ll have to use the IP address of your ODROID-N2+ instead of `homeassistant.local`. For example, `http://192.168.0.9:8123`.
* You should be able to find the IP address of your ODROID-N2+ from the admin interface of your router.
1. Continue with [onboarding](/getting-started/onboarding/).

14
source/_includes/installation/container.md
View File

@ -11,7 +11,7 @@ This guide assumes that you already have an operating system setup and a contain
If you are using Docker then you need to be on at least version 19.03.9, ideally an even higher version, and `libseccomp` 2.4.2 or newer.
</div>
### Platform Installation
### Platform installation
Installation with Docker is straightforward. Adjust the following command so that:
@ -32,10 +32,10 @@ Once the Home Assistant Container is running Home Assistant should be accessible
### Restart Home Assistant
If you change the configuration you have to restart the server. To do that you have 3 options.
If you change the configuration, you have to restart the server. To do that you have 3 options.
1. In your Home Assistant UI go to the **Settings** -> **System** and click the "Restart" button.
2. You can go to the **Developer Tools** -> **Services**, select the service `homeassistant.restart` and click "Call Service".
1. In your Home Assistant UI, go to the **Settings** > **System** and click the **Restart** button.
2. You can go to the **Developer Tools** > **Services**, select the service `homeassistant.restart` and select **Call Service**.
3. Restart it from a terminal.
{% tabbed_block %}
@ -56,7 +56,7 @@ If you change the configuration you have to restart the server. To do that you h
{% endtabbed_block %}
### Docker Compose
### Docker compose
<div class="note tip">
@ -74,11 +74,11 @@ Start it by running:
docker compose up -d
```
Once the Home Assistant Container is running Home Assistant should be accessible using `http://<host>:8123` (replace <host> with the hostname or IP of the system). You can continue with onboarding.
Once the Home Assistant Container is running, Home Assistant should be accessible using `http://<host>:8123` (replace <host> with the hostname or IP of the system). You can continue with onboarding.
{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %}
### Exposing Devices
### Exposing devices
In order to use Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the `/dev/tty*` file, then add the device mapping to your container instructions:

2
source/_includes/installation/core.md
View File

@ -99,6 +99,6 @@ If this address doesn't work you may also try `http://localhost:8123` or `http:/
<div class='note'>
When you run the `hass` command for the first time, it will download, install and cache the necessary libraries/dependencies. This procedure may take anywhere between 5 to 10 minutes. During that time, you may get "site cannot be reached" error when accessing the web interface. This will only happen for the first time, and subsequent restarts will be much faster.
When you run the `hass` command for the first time, it will download, install and cache the necessary libraries/dependencies. This procedure may take anywhere between 5 to 10 minutes. During that time, you may get a **site cannot be reached** error when accessing the web interface. This will only happen the first time. Subsequent restarts will be much faster.
</div>

114
source/_includes/installation/operating_system.md
View File

@ -6,25 +6,11 @@
Follow this guide if you want to get started with Home Assistant easily or if you have little to no Linux experience.
{% if page.installation_type == 'raspberrypi' %}
### Suggested Hardware
We will need a few things to get started with installing Home Assistant. Links below lead to Amazon US. If you’re not in the US, you should be able to find these items in web stores in your country.
- [Raspberry Pi 4](https://amzn.to/2S0Gcl1) (Raspberry Pi 3 is ok too, if you have one laying around). Raspberry Pi are currently hard to come by, use [RPilocator](https://rpilocator.com/?cat=PI4) to find official distributors with stock.
- [Power Supply for Raspberry Pi 4](https://amzn.to/2ReZ2Vq) or [Power Supply for Raspberry Pi 3](https://amzn.to/2R8yG7h)
- [Micro SD Card](https://amzn.to/2X0Z2di). Ideally get one that is [Application Class 2](https://www.sdcard.org/developers/overview/application/index.html) as they handle small I/O much more consistently than cards not optimized to host applications. A 32 GB or bigger card is recommended.
- SD Card reader. This is already part of most laptops, but you can purchase a [standalone USB adapter](https://amzn.to/2WWxntY) if you don't have one. The brand doesn't matter, just pick the cheapest.
- [Ethernet cable](https://amzn.com/dp/B00N2VISLW). Required for installation. After installation, Home Assistant can work with Wi-Fi, but an Ethernet connection is more reliable and highly recommended.
{% endif %}
{% if page.installation_type == 'odroid' %}
### Suggested Hardware
### Suggested hardware
We will need a few things to get started with installing Home Assistant. Links below lead to Ameridroid. If you’re not in the US, you should be able to find these items in web stores in your country.
We will need a few things to get started with installing Home Assistant. The links below lead to Ameridroid. If you’re not in the US, you should be able to find these items in web stores in your country.
To get started we suggest the ODROID N2+, it's the most powerful ODROID. It's fast and with built-in eMMC one of the best boards to run Home Assistant. It's also the board that powers our [Home Assistant Blue](/blue/).
@ -34,15 +20,15 @@ To get started we suggest the ODROID N2+, it's the most powerful ODROID. It's fa
- [eMMC Module](https://ameridroid.com/products/emmc-module-n2-linux-red-dot?ref=eeb6nfw07e)
- [Case](https://ameridroid.com/products/odroid-n2-case?ref=eeb6nfw07e)
If unavailable, we also recommend the [ODROID C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e) or [ODROID XU4](https://ameridroid.com/products/odroid-xu4?ref=eeb6nfw07e).
If unavailable, we also recommend the [ODROID C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e) or [ODROID M1](https://ameridroid.com/products/odroid-M1?ref=eeb6nfw07e).
{% endif %}
{% if page.installation_type == 'tinkerboard' %}
### Suggested Hardware
### Suggested hardware
We will need a few things to get started with installing Home Assistant. Links below lead to Amazon US. If you’re not in the US, you should be able to find it in web stores in your country.
We will need a few things to get started with installing Home Assistant. The links below lead to Amazon US. If you’re not in the US, you should be able to find it in web stores in your country.
- [Asus Tinkerboard S](https://amzn.to/3fFIcbI)
@ -111,13 +97,15 @@ sudo apt install libfuse2
1. Attach the Home Assistant boot medium ({{site.installation.types[page.installation_type].installation_media}}) to your computer.
{% if page.installation_type == 'odroid' %}
If you are using ODROID M1, note that booting from NVMe is not supported. If you want to boot from eMMC, [update the firmware](https://github.com/home-assistant/operating-system/blob/dev/Documentation/boards/hardkernel/odroid-m1.md) before installing the image.
If you are using a [Home Assistant Blue](/blue) or ODROID N2+, you can [attach your device directly](/common-tasks/os/#flashing-an-odroid-n2).
{% endif %}
2. Download and start <a href="https://www.balena.io/etcher" target="_blank">Balena Etcher</a>. You may need to run it with administrator privileges on Windows.
3. Select "Flash from URL".
1. Download and start <a href="https://www.balena.io/etcher" target="_blank">Balena Etcher</a>. You may need to run it with administrator privileges on Windows.
1. Select **Flash from URL**.
![Screenshot of the Etcher software showing flash from URL selected.](/images/installation/etcher1.png)
4. Copy the URL for the {{site.installation.types[page.installation_type].board}} image which is:
1. Copy the URL for the image. If there are multiple links below, make sure to select the correct link for your version of {{site.installation.types[page.installation_type].board}}:
{% if site.installation.types[page.installation_type].variants.size > 1 %}
{% tabbed_block %}
{% for variant in site.installation.types[page.installation_type].variants %}
@ -148,15 +136,15 @@ sudo apt install libfuse2
_Select and copy the URL or use the "copy" button that appear when you hover it._
1. Paste the URL for the {{site.installation.types[page.installation_type].board}} image into Balena Etcher and click "OK"
5. Paste the URL for the {{site.installation.types[page.installation_type].board}} image into Balena Etcher and select **OK**.
![Screenshot of the Etcher software showing the URL bar with a URL pasted in.](/images/installation/etcher2.png)
1. When Balena Etcher has downloaded the image, click "Select target"
1. When Balena Etcher has downloaded the image, click **Select target**.
![Screenshot of the Etcher software showing the select target button highlighted.](/images/installation/etcher3.png)
1. Select the boot medium ({{site.installation.types[page.installation_type].installation_media}}) you want to use for your installation
1. Select the boot medium ({{site.installation.types[page.installation_type].installation_media}}) you want to use for your installation.
![Screenshot of the Etcher software showing teh targets available.](/images/installation/etcher4.png)
1. Click on "Flash!" to start writing the image
1. Select **Flash!** to start writing the image.
![Screenshot of the Etcher software showing the Flash button highlighted.](/images/installation/etcher5.png)
1. When Balena Etcher has finished writing the image you will see a confirmation
1. When Balena Etcher has finished writing the image, you will see a confirmation.
![Screenshot of the Etcher software showing that the installation has completed.](/images/installation/etcher6.png)
### Start up your {{site.installation.types[page.installation_type].board}}
@ -168,7 +156,7 @@ _Select and copy the URL or use the "copy" button that appear when you hover it.
- If you used a live operating system (e.g. Ubuntu), shut it down and remove the live operating system USB device.
1. Plug in an Ethernet cable that is connected to the network.
2. Power the system on. If you have a screen connected to the {{site.installation.types[page.installation_type].board}} system, after a minute or so the Home Assistant welcome banner will appear in the console.
1. Power the system on. If you have a screen connected to the {{site.installation.types[page.installation_type].board}} system, after a minute or so the Home Assistant welcome banner will appear in the console.
<div class="note">
@ -223,9 +211,9 @@ If you are running an older Windows version or have a stricter network configura
- [Hyper-V][vhdx] (.vhdx)
{% endif %}
Follow this guide if you already are running a supported virtual machine hypervisor. If you are not familiar with virtual machines we recommend installation Home Assistant OS directly on a [Raspberry Pi](/installation/raspberrypi) or an [ODROID](/installation/odroid).
Follow this guide if you already are running a supported virtual machine hypervisor. If you are not familiar with virtual machines, we recommend installing Home Assistant OS directly on a [Home Assistant Yellow](/installation/yellow), a [Raspberry Pi](/installation/raspberrypi), or an [ODROID](/installation/odroid).
### Create the Virtual Machine
### Create the virtual machine
Load the appliance image into your virtual machine hypervisor. (Note: You are free to assign as much resources as you wish to the VM, please assign enough based on your add-on needs).
@ -243,19 +231,19 @@ _All these can be extended if your usage calls for more resources._
- title: VirtualBox
content: |
1. Create a new virtual machine
2. Select Type "Linux" and Version "Linux 2.6 / 3.x / 4.x (64-bit)"
3. Select "Use an existing virtual hard disk file", select the unzipped VDI file from above
4. Edit the "Settings" of the VM and go "System" then "Motherboard" and select "Enable EFI"
5. Then go to "Network" "Adapter 1" choose "Bridged Adapter" and choose your Network adapter
1. Create a new virtual machine.
1. Select type **Linux** and version **Linux 2.6 / 3.x / 4.x (64-bit)**.
1. Select **Use an existing virtual hard disk file**, select the unzipped VDI file from above.
1. Edit the **Settings** of the VM and go to **System** > **Motherboard**. Select **Enable EFI**.
1. Then go to **Network** > **Adapter 1**. Choose **Bridged Adapter** and choose your network adapter.
<div class="note warning">
Please keep in mind that the bridged adapter only functions over a hardwired Ethernet connection.
Using Wi-Fi on your VirtualBox host is unsupported.
</div>
6. Then go to "Audio" and choose "Intel HD Audio" as Audio Controller.
6. Then go to **Audio** and choose **Intel HD Audio** as audio controller.
<div class="note info">
By default VirtualBox does not free up unused disk space. To automatically shrink the vdi disk image
By default, VirtualBox does not free up unused disk space. To automatically shrink the vdi disk image
the `discard` option must be enabled:
```bash
VBoxManage storageattach <VM name> --storagectl "SATA" --port 0 --device 0 --nonrotational on --discard on
@ -265,16 +253,16 @@ _All these can be extended if your usage calls for more resources._
- title: KVM (virt-manager)
content: |
1. Create a new virtual machine in `virt-manager`
2. Select "Import existing disk image", provide the path to the QCOW2 image above
3. Choose "Generic Default" for the operating system
4. Check the box for "Customize configuration before install"
5. Select your bridge under "Network Selection"
6. Under customization select "Overview" -> "Firmware" -> "UEFI x86_64: ...". Make sure to select a non-secureboot version of OVMF (does not contain the word `secure`, `secboot`, etc.), e.g., `/usr/share/edk2/ovmf/OVMF_CODE.fd`.
7. Click "Add Hardware" (bottom left), and select "Channel"
8. Select device type: "unix"
9. Select name: "org.qemu.guest_agent.0"
10. Finally select "Begin Installation" (upper left corner)
1. Create a new virtual machine in `virt-manager`.
1 Select **Import existing disk image**, provide the path to the QCOW2 image above.
1. Choose **Generic Default** for the operating system.
1. Check the box for **Customize configuration before install**.
1. Under **Network Selection**, select your bridge.
6. Under customization select **Overview** > **Firmware** > **UEFI x86_64: ...**. Make sure to select a non-secureboot version of OVMF (does not contain the word `secure`, `secboot`, etc.), e.g., `/usr/share/edk2/ovmf/OVMF_CODE.fd`.
1. Click **Add Hardware** (bottom left), and select **Channel**.
1. Select device type: **unix**.
1. Select name: **org.qemu.guest_agent.0**.
1. Finally, select **Begin Installation** (upper left corner).
- title: KVM (virt-install)
content: |
@ -309,13 +297,13 @@ _All these can be extended if your usage calls for more resources._
- title: Vmware Workstation
content: |
1. Create a new virtual machine
2. Select “Custom”, make it compatible with the default of Workstation and ESX
3. Choose “I will install the operating system later”, select “Linux” -> “Other Linux 5.x or later kernel 64-bit”
4. Select “Use Bridged Networking”
5. Select “Use an existing virtual disk” and select the VMDK file above,
1. Create a new virtual machine.
1. Select **Custom**, make it compatible with the default of Workstation and ESX.
1. Choose **I will install the operating system later**, select **Linux** > **Other Linux 5.x or later kernel 64-bit**.
1. Select **Use Bridged Networking**.
1. Select **Use an existing virtual disk** and select the VMDK file above.
After creation of VM go to “Settings” and “Options” then “Advanced” and select “Firmware type” to “UEFI”.
After the VM has been created, go to **Settings** > **Options** > **Advanced**. Under **Firmware type** select **UEFI**.
{% elsif page.installation_type == 'alternative' %}
@ -330,25 +318,25 @@ _All these can be extended if your usage calls for more resources._
Hyper-V does not have USB support
</div>
1. Create a new virtual machine
2. Select “Generation 2”
3. Select “Connection -> “Your Virtual Switch that is bridged”
4. Select “Use an existing virtual hard disk” and select the VHDX file from above
1. Create a new virtual machine.
1. Select **Generation 2**.
1. Select **Connection** > **Your Virtual Switch that is bridged**.
1. Select **Use an existing virtual hard disk** and select the VHDX file from above.
After creation go to “Settings” -> “Security” and deselect “Enable Secure Boot”.
After creation, go to **Settings** > **Security** and deselect **Enable Secure Boot**.
{% endif %}
{% endtabbed_block %}
### Start up your Virtual Machine
### Start up your virtual machine
1. Start the Virtual Machine
2. Observe the boot process of Home Assistant Operating System
3. Once completed you will be able to reach Home Assistant on <a href="http://homeassistant.local:8123" target="_blank">homeassistant.local:8123</a>. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at <a href="http://homeassistant:8123" target="_blank">homeassistant:8123</a> or `http://X.X.X.X:8123` (replace X.X.X.X with your {{site.installation.types[page.installation_type].board}}’s IP address).
1. Start the virtual machine.
1. Observe the boot process of the Home Assistant Operating System.
1. Once completed, you will be able to reach Home Assistant on <a href="http://homeassistant.local:8123" target="_blank">homeassistant.local:8123</a>. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at <a href="http://homeassistant:8123" target="_blank">homeassistant:8123</a> or `http://X.X.X.X:8123` (replace X.X.X.X with your {{site.installation.types[page.installation_type].board}}’s IP address).
{% endif %}
With the Home Assistant Operating System installed and accessible you can continue with onboarding.
With the Home Assistant Operating System installed and accessible, you can continue with onboarding.
{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %}

2
source/_integrations/ads.markdown
View File

@ -20,7 +20,7 @@ ha_platforms:
ha_integration_type: integration
---
The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between [Beckhoff](https://www.beckhoff.com/) automation devices running [TwinCAT](https://www.beckhoff.hu/english.asp?twincat/default.htm) and other devices implementing this interface.
The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between [Beckhoff](https://www.beckhoff.com/) automation devices running [TwinCAT](https://www.beckhoff.com/en-en/products/automation/twincat/) and other devices implementing this interface.
There is currently support for the following device types within Home Assistant:

24
source/_integrations/advantage_air.markdown
View File

@ -36,11 +36,19 @@ The wall-mounted Android tablet running the [MyPlace](https://play.google.com/st
### Climate
The integration will create a climate entity for each air conditioning system found and for each zone that is temperature-controlled.
The integration will create a climate entity for each air conditioning system found and for each zone that is temperature-controlled. The main climate entity will change its supported features and modes based on the [MyComfort](https://www.advantageair.com.au/wp-content/uploads/2019/10/MyComfort.pdf) temperature mode currently set.
- MyZone (default) - Use the MyZone select platform to pick which zone will be used for temperature control. Setting this to "Inactive" will use the return air vent temperature. e-zone systems do not support any MyComfort temperature modes, so will always be in the MyZone preset with MyZone set as "Inactive".
- MyTemp - Use the main climate entity to change between cool, heat, and off. Use the zone climate entities to set the desired temperature in each zone.
- MyAuto - Uses the average temperature of all zones for temperature control. When set to the Heat/Cool mode, you can adjust the heating and cooling target temperatures separately, and the MyAir system will automatically switch between heating and cooling as required.
If you change MyComfort mode, you will need to restart Home Assistant or reload the integration.
### Cover
The integration will create a cover entity for each zone that is not temperature controlled, allowing you to adjust the opening level manually from 0% to 100% in 5% increments.
The integration will create a cover entity for each air conditioning zone that is not temperature controlled, allowing you to adjust the opening level manually from 0% to 100% in 5% increments.
With MyPlace, any blinds and/or garage doors will be created as cover entities.
### Sensor
@ -53,23 +61,25 @@ The integration will create sensor entities for a variety of aspects:
### Binary Sensor
The `advantage_air` binary sensor platform will create a binary sensor for each zone that has a motion sensor.
The integration will create a binary sensor for each zone that has a motion sensor.
### Switch
The `advantage_air` switch platform will create a switch entity to toggle fresh air mode, if it is supported.
The integration will create a switch entity to toggle air conditioning fresh air mode, if it is supported.
With MyPlace, any relays will be created as switch entities.
### Select
The `advantage_air` select platform allows you to change the zone used for the "MyZone" feature.
The MyZone select entity that allows you to change the zone used for the "MyZone" feature. Set this to "Inactive" to use the return air vent temperature.
### Update
The `advantage_air` update platform shows if the controller app requires an update.
The update platform shows if the controller app requires an update.
### Light
The `advantage_air` light platform will create a light entity for each light in MyLights tab of the MyPlace app.
With MyLights or MyPlace, light entities will be created for each light.
## Services

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

@ -98,7 +98,7 @@ code_trigger_required:
command_template:
description: "The [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) used for the command payload. Available variables: `action` and `code`."
required: false
type: string
type: template
default: action
command_topic:
description: The MQTT topic to publish commands to change the alarm state.

357
source/_integrations/androidtv_remote.markdown Normal file
View File

@ -0,0 +1,357 @@
---
title: Android TV Remote
description: Instructions on how to integrate Android TV remotes into Home Assistant.
ha_category:
- Remote
ha_release: 2023.5
ha_iot_class: Local Push
ha_config_flow: true
ha_codeowners:
- '@tronikos'
ha_quality_scale: platinum
ha_domain: androidtv_remote
ha_zeroconf: true
ha_platforms:
- diagnostics
- remote
ha_integration_type: device
---
The Android TV Remote integration allows you to control an Android TV device by sending [commands](https://github.com/tronikos/androidtvremote2/blob/main/TvKeys.txt) and launching apps. For this to work the Android TV device needs to have [Android TV Remote Service](https://play.google.com/store/apps/details?id=com.google.android.tv.remote.service) which is pre-installed on most devices.
{% include integrations/config_flow.md %}
## Entity
This integration adds a `remote` entity which turns on/off the Android TV device.
The entity has the `current_activity` attribute that shows the current foreground app on the Android TV.
## Services
You can use the `remote.turn_off`, `remote.turn_on`, `remote.toggle`, and `remote.send_command` services from the [remote](/integrations/remote/) platform.
For a list of the most common commands you can send to the Android TV via `remote.send_command` see: [TvKeys](https://github.com/tronikos/androidtvremote2/blob/main/TvKeys.txt).
For a full list see [here](https://github.com/tronikos/androidtvremote2/blob/main/src/androidtvremote2/remotemessage.proto#L90).
If `activity` is specified in `remote.turn_on` it will open the specified URL in the associated app.
Examples of URLs to pass as activity for some popular apps:
| App | URL |
| --- | --- |
| YouTube | https://www.youtube.com
| Netflix | https://www.netflix.com/title
| Prime Video | https://app.primevideo.com
| Disney+ | https://www.disneyplus.com
Examples of service calls:
```yaml
# Open the currently selected item on the Android TV
service: remote.send_command
data:
command: DPAD_CENTER
target:
entity_id: remote.living_room_tv
```
```yaml
# Long press on the currently selected item on the Android TV
service: remote.send_command
data:
command: DPAD_CENTER
hold_secs: 0.5
target:
entity_id: remote.living_room_tv
```
```yaml
# Launch YouTube
service: remote.turn_on
data:
activity: https://www.youtube.com
target:
entity_id: remote.living_room_tv
```
```yaml
# Open a specific YouTube video:
service: remote.turn_on
data:
activity: https://www.youtube.com/watch?v=dQw4w9WgXcQ
target:
entity_id: remote.living_room_tv
```
## Dashboard example
You have to manually create buttons in Lovelace to send commands to the Android TV device or launch apps on it.
Below is an example for you to start with. Many of the buttons support long press.
![Screenshot Android TV Remote example](/images/integrations/androidtv_remote/lovelace_example.png)
{% details "Lovelace example" %}
Replace all instances of `living_room_tv` with your entity ID.
```yaml
type: vertical-stack
cards:
- type: entities
entities:
- entity: remote.living_room_tv
- square: true
columns: 3
type: grid
cards:
- type: button
show_icon: false
tap_action:
action: none
hold_action:
action: none
- type: button
icon: mdi:arrow-up-bold
tap_action:
action: call-service
service: remote.send_command
data:
command: DPAD_UP
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
show_icon: false
tap_action:
action: none
hold_action:
action: none
- type: button
icon: mdi:arrow-left-bold
tap_action:
action: call-service
service: remote.send_command
data:
command: DPAD_LEFT
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
icon: mdi:circle
tap_action:
action: call-service
service: remote.send_command
data:
command: DPAD_CENTER
target:
entity_id: remote.living_room_tv
hold_action:
action: call-service
service: remote.send_command
data:
command: DPAD_CENTER
hold_secs: 0.5
target:
entity_id: remote.living_room_tv
- type: button
icon: mdi:arrow-right-bold
tap_action:
action: call-service
service: remote.send_command
data:
command: DPAD_RIGHT
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
icon: mdi:arrow-left
tap_action:
action: call-service
service: remote.send_command
data:
command: BACK
target:
entity_id: remote.living_room_tv
hold_action:
action: call-service
service: remote.send_command
data:
command: BACK
hold_secs: 0.5
target:
entity_id: remote.living_room_tv
- type: button
icon: mdi:arrow-down-bold
tap_action:
action: call-service
service: remote.send_command
data:
command: DPAD_DOWN
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
icon: mdi:home-outline
tap_action:
action: call-service
service: remote.send_command
data:
command: HOME
target:
entity_id: remote.living_room_tv
hold_action:
action: call-service
service: remote.send_command
data:
command: HOME
hold_secs: 0.5
target:
entity_id: remote.living_room_tv
- square: false
columns: 3
type: grid
cards:
- type: button
icon: mdi:skip-previous
tap_action:
action: call-service
service: remote.send_command
data:
command: MEDIA_PREVIOUS
target:
entity_id: remote.living_room_tv
hold_action:
action: call-service
service: remote.send_command
data:
command: MEDIA_REWIND
target:
entity_id: remote.living_room_tv
- type: button
icon: mdi:play-pause
tap_action:
action: call-service
service: remote.send_command
data:
command: MEDIA_PLAY_PAUSE
target:
entity_id: remote.living_room_tv
hold_action:
action: call-service
service: remote.send_command
data:
command: MEDIA_STOP
target:
entity_id: remote.living_room_tv
- type: button
icon: mdi:skip-next
tap_action:
action: call-service
service: remote.send_command
data:
command: MEDIA_NEXT
target:
entity_id: remote.living_room_tv
hold_action:
action: call-service
service: remote.send_command
data:
command: MEDIA_FAST_FORWARD
target:
entity_id: remote.living_room_tv
- type: button
icon: mdi:volume-off
tap_action:
action: call-service
service: remote.send_command
data:
command: MUTE
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
icon: mdi:volume-medium
tap_action:
action: call-service
service: remote.send_command
data:
command: VOLUME_DOWN
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
icon: mdi:volume-high
tap_action:
action: call-service
service: remote.send_command
data:
command: VOLUME_UP
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- square: false
columns: 4
type: grid
cards:
- type: button
icon: mdi:youtube
tap_action:
action: call-service
service: remote.turn_on
data:
activity: https://www.youtube.com
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: button
icon: mdi:netflix
tap_action:
action: call-service
service: remote.turn_on
data:
activity: https://www.netflix.com/title
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: picture
image: >-
https://upload.wikimedia.org/wikipedia/commons/thumb/1/11/Amazon_Prime_Video_logo.svg/450px-Amazon_Prime_Video_logo.svg.png
tap_action:
action: call-service
service: remote.turn_on
data:
activity: https://app.primevideo.com
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: picture
image: >-
https://upload.wikimedia.org/wikipedia/commons/thumb/3/3e/Disney%2B_logo.svg/440px-Disney%2B_logo.svg.png
tap_action:
action: call-service
service: remote.turn_on
data:
activity: https://www.disneyplus.com
target:
entity_id: remote.living_room_tv
hold_action:
action: none
- type: entity
entity: remote.living_room_tv
attribute: current_activity
- type: media-control
entity: media_player.living_room_tv
```
{% enddetails %}

38
source/_integrations/anova.markdown Normal file
View File

@ -0,0 +1,38 @@
---
title: Anova
description: Instructions on how to integrate Anova Wi-Fi Sous Vide into home assistant.
ha_category:
- Sensor
ha_iot_class: Cloud Polling
ha_config_flow: true
ha_release: 2023.5
ha_codeowners:
- '@Lash-L'
ha_domain: anova
ha_integration_type: integration
---
The Anova sensor platform allows you to control [Anova](https://anovaculinary.com/pages/find-your-anova-precision-cooker) sous vides with Wi-Fi capability.
Supported devices (tested):
- AN500-10 (Anova Precision Cooker)
- AN500-US00 (Anova Precision Cooker)
- AN600-10 (Anova Precision Cooker Pro)
The 'nano' versions of the sous vide are not supported, but as long as your app is connected to the sous vide, the data should update. They would be better served using BLE instead of API calls.
To add this platform to your installation, You will need your Anova username and password, and you need to have at least one sous vide connected to your account.
{% include integrations/config_flow.md %}
## Sensor
- Cook Time - How long the sous vide has been cooking in seconds
- Mode - The current mode of the sous vide ("Idle", "Cook", "Low water").
- State - The current state of the sous vide ("Preheating", "Cooking", "Maintaining").
- Target Temperature - The temperature the sous vide is set to heat to.
- Cook Time Remaining - How long is left in the cook in seconds.
- Heater Temperature - The current temperature of the heater.
- Triac Temperature - The current temperature of the triac.
- Water Temperature - The current temperature of the water.

18
source/_integrations/assist_pipeline.markdown Normal file
View File

@ -0,0 +1,18 @@
---
title: Assist pipeline
description: Assist pipeline integration.
ha_category:
- Voice
ha_iot_class: Local Push
ha_release: '2023.5'
ha_codeowners:
- '@balloob'
- '@synesthesiam'
ha_domain: assist_pipeline
ha_integration_type: integration
ha_quality_scale: internal
---
The Assist pipeline integration provides the foundation for the [Assist](/docs/assist/) voice assistant in Home Assistant.
There is no need to manually install this integration. The Assist pipeline integration is part of the default configuration and set up automatically if needed by other integrations.

5
source/_integrations/binary_sensor.mqtt.markdown
View File

@ -114,7 +114,8 @@ device:
required: false
type: string
device_class:
description: Sets the [class of the device](/integrations/binary_sensor/#device-class), changing the device state and icon that is displayed on the frontend.
description: Sets the [class of the device](/integrations/binary_sensor/#device-class), changing the device state and icon that is displayed on the frontend. The `device_class` can be `null`.
default: None
required: false
type: string
enabled_by_default:
@ -202,7 +203,7 @@ unique_id:
value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) that returns a string to be compared to `payload_on`/`payload_off` or an empty string, in which case the MQTT message will be removed. Remove this option when `payload_on` and `payload_off` are sufficient to match your payloads (i.e no pre-processing of original message is required)."
required: false
type: string
type: template
{% endconfiguration %}
## Examples

13
source/_integrations/bmw_connected_drive.markdown
View File

@ -8,6 +8,7 @@ ha_category:
- Lock
- Notifications
- Presence Detection
- Select
- Sensor
ha_release: 0.64
ha_iot_class: Cloud Polling
@ -23,6 +24,7 @@ ha_platforms:
- diagnostics
- lock
- notify
- select
- sensor
ha_integration_type: integration
---
@ -45,6 +47,7 @@ This integration provides the following platforms:
- Sensors: Mileage, remaining range, remaining fuel, charging time remaining (electric cars), charging status (electric cars), remaining range electric (electric cars).
- [Notifications](/integrations/bmw_connected_drive/#notifications): Send Points of Interest (POI) to your car.
- [Buttons](/integrations/bmw_connected_drive/#buttons): Turn on air condition, sound the horn, flash the lights, update the vehicle location and update the state.
- [Selects](/integrations/bmw_connected_drive/#selects): Display and control charging related settings for (PH)EVs.
## Configuration
@ -134,6 +137,16 @@ The `button.<your_vehicle>_find_vehicle` button requests the vehicle to update t
The `button.<vehicle_model>_refresh_from_cloud` button fetches the last state of the vehicles of all your accounts from the BMW server. This does *not* trigger an update from the vehicle; it gets the data from the BMW servers. So this service does *not* interact with your vehicles.
## Selects
If you have a (PH)EV, you can control the charging process through Home Assistant. The selects are created automatically depending on your vehicle's capabilities and can be pressed/executed from the UI or using the `select.select_option` service. For more information, please see the [select documentation](/integrations/select/).
Using these selects will impact the state of your vehicle. Use them with care!
- **Charging Mode**: Vehicle can be set to `IMMEDIATE_CHARGING` (charge as soon as plugged in) or `DELAYED_CHARGING` (charge only if within charging window). It can be used to start/stop charging if the charging window is set accordingly.
- **Target SoC**: The vehicle will charge until this battery level is reached. Not available on all EVs.
- **AC Charging Limit**: The maximum current a vehicle will charge with. Not available on all EVs.
## Disclaimer
This software is not affiliated with or endorsed by BMW Group.

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

@ -112,8 +112,9 @@ device:
required: false
type: string
device_class:
description: The [type/class](/integrations/button/#device-class) of the button to set the icon in the frontend.
description: The [type/class](/integrations/button/#device-class) of the button to set the icon in the frontend. The `device_class` can be `null`.
required: false
default: None
type: device_class
default: None
enabled_by_default:

4
source/_integrations/climate.mqtt.markdown
View File

@ -290,7 +290,7 @@ preset_mode_state_topic:
preset_mode_value_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the `preset_mode` value from the payload received on `preset_mode_state_topic`.
required: false
type: string
type: template
preset_modes:
description: List of preset modes this climate is supporting. Common examples include `eco`, `away`, `boost`, `comfort`, `home`, `sleep` and `activity`.
required: false
@ -342,7 +342,7 @@ target_humidity_state_topic:
target_humidity_state_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value for the climate `target_humidity` state.
required: false
type: string
type: template
temperature_command_template:
description: A template to render the value sent to the `temperature_command_topic` with.
required: false

579
source/_integrations/command_line.markdown
View File

@ -1,8 +1,11 @@
---
title: Command Line
description: Instructions on how to integrate Command binary sensors within Home Assistant.
description: Instructions on how to integrate the Command Line utility within Home Assistant.
ha_category:
- Binary Sensor
- Cover
- Sensor
- Notifications
- Utility
ha_release: 0.12
ha_iot_class: Local Polling
@ -16,9 +19,9 @@ ha_platforms:
ha_integration_type: integration
---
The `command_line` binary sensor platform issues specific commands to get data.
The `command_line` offers functionality that issues specific commands to get data or to control a device.
## Configuration
## Binary sensor
To use your Command binary sensor in your installation, add the following to your `configuration.yaml` file:
@ -40,45 +43,282 @@ command:
description: The action to take to get the value.
required: true
type: string
name:
description: Let you overwrite the name of the device.
required: false
type: string
default: "*name* from the device"
device_class:
description: Sets the [class of the device](/integrations/binary_sensor/), changing the device state and icon that is displayed on the frontend.
required: false
type: string
payload_on:
description: The payload that represents enabled state.
required: false
type: string
default: 'ON'
payload_off:
description: The payload that represents disabled state.
required: false
type: string
default: 'OFF'
value_template:
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
required: false
type: string
scan_interval:
description: Defines number of seconds for polling interval.
required: false
type: integer
default: 60
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
device_class:
description: Sets the [class of the device](/integrations/binary_sensor/), changing the device state and icon that is displayed on the frontend.
required: false
type: string
name:
description: Let you overwrite the name of the device.
required: false
type: string
default: "*name* from the device"
payload_on:
description: The payload that represents enabled state.
required: false
type: string
default: 'ON'
unique_id:
description: An ID that uniquely identifies this binary sensor. Set this to a unique value to allow customization through the UI.
required: false
type: string
payload_off:
description: The payload that represents disabled state.
required: false
type: string
default: 'OFF'
scan_interval:
description: Defines number of seconds for polling interval.
required: false
type: integer
default: 60
value_template:
description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload.
required: false
type: string
{% endconfiguration %}
## Cover
A `command_line`cover platform that issues specific commands when it is moved up, down and stopped. It allows anyone to integrate any type of cover into Home Assistant that can be controlled from the command line.
To enable a command line cover in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
cover:
- platform: command_line
covers:
garage_door:
command_open: move_command up garage
command_close: move_command down garage
command_stop: move_command stop garage
```
{% configuration %}
covers:
description: The array that contains all command line covers.
required: true
type: list
keys:
identifier:
description: Name of the command line cover as slug. Multiple entries are possible.
required: true
type: list
keys:
command_close:
description: The action to close the cover.
required: true
default: true
type: string
command_open:
description: The command to open the cover.
required: true
default: true
type: string
command_state:
description: If given, this will act as a sensor that runs in the background and updates the state of the cover. If the command returns a `0` the indicates the cover is fully closed, whereas a 100 indicates the cover is fully open.
required: false
type: string
command_stop:
description: The action to stop the cover.
required: true
default: true
type: string
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
friendly_name:
description: The name used to display the cover in the frontend.
required: false
type: string
scan_interval:
description: Defines number of seconds for polling interval.
required: false
type: integer
default: 60
unique_id:
description: An ID that uniquely identifies this cover. Set this to a unique value to allow customization through the UI.
required: false
type: string
value_template:
description: if specified, `command_state` will ignore the result code of the command but the template evaluating will indicate the position of the cover. For example, if your `command_state` returns a string "open", using `value_template` as in the example configuration above will allow you to translate that into the valid state `100`.
required: false
default: "'{% raw %}{{ value }}{% endraw%}'"
type: template
{% endconfiguration %}
## Notify
The `command_line` platform allows you to use external tools for notifications from Home Assistant. The message will be passed in as STDIN.
To enable those notifications in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
- name: NOTIFIER_NAME
platform: command_line
command: "espeak -vmb/mb-us1"
```
{% configuration %}
name:
description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`.
required: false
default: notify
type: string
command:
description: The action to take.
required: true
type: string
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
{% endconfiguration %}
To use notifications, please see the [getting started with automation page](/getting-started/automation/).
## Sensor
To enable it, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
command: SENSOR_COMMAND
```
{% configuration %}
command:
description: The action to take to get the value.
required: true
type: string
command_timeout:
description: Defines number of seconds for command timeout
required: false
type: integer
default: 15
json_attributes:
description: Defines a list of keys to extract values from a JSON dictionary result and then set as sensor attributes.
required: false
type: [string, list]
name:
description: Name of the command sensor.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this sensor. Set this to a unique value to allow customization through the UI.
required: false
type: string
scan_interval:
description: Defines number of seconds for polling interval.
required: false
type: integer
default: 60
unit_of_measurement:
description: Defines the unit of measurement of the sensor, if any.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload."
required: false
type: string
{% endconfiguration %}
## Switch
The `command_line` switch platform issues specific commands when it is turned on
and off. This might very well become our most powerful platform as it allows
anyone to integrate any type of switch into Home Assistant that can be
controlled from the command line, including calling other scripts!
To enable it, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
kitchen_light:
command_on: switch_command on kitchen
command_off: switch_command off kitchen
```
{% configuration %}
switches:
description: The array that contains all command switches.
required: true
type: map
keys:
identifier:
description: Name of the command switch as slug. Multiple entries are possible.
required: true
type: map
keys:
command_on:
description: The action to take for on.
required: true
type: string
command_off:
description: The action to take for off.
required: true
type: string
command_state:
description: "If given, this command will be run. Returning a result code `0` will indicate that the switch is on."
required: false
type: string
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
friendly_name:
description: The name used to display the switch in the frontend.
required: false
type: string
icon_template:
description: Defines a template for the icon of the entity.
required: false
type: template
scan_interval:
description: Defines number of seconds for polling interval.
required: false
type: integer
default: 60
unique_id:
description: An ID that uniquely identifies this switch. Set this to a unique value to allow customization through the UI.
required: false
type: string
value_template:
description: "If specified, `command_state` will ignore the result code of the command but the template evaluating to `true` will indicate the switch is on."
required: false
type: string
{% endconfiguration %}
A note on `friendly_name`:
When set, the `friendly_name` had been previously used for API calls and backend
configuration instead of the `object_id` ("identifier"), but
[this behavior is changing](https://github.com/home-assistant/home-assistant/pull/4343)
to make the `friendly_name` for display purposes only. This allows users to set
an `identifier` that emphasizes uniqueness and predictability for API and configuration
purposes but have a prettier `friendly_name` still show up in the UI. As an
additional benefit, if a user wanted to change the `friendly_name` / display
name (e.g., from "Kitchen Lightswitch" to "Kitchen Switch" or
"Living Room Light", or remove the `friendly_name` altogether), they could
do so without needing to change existing automations or API calls.
See aREST device below for an example.
## Execution
The `command` is executed within the [configuration directory](/docs/configuration/).
@ -91,9 +331,9 @@ If you are using [Home Assistant Operating System](https://github.com/home-assis
With a `0` exit code, the output (stdout) of the command is used as `value`. In case a command results in a non `0` exit code or is terminated by the `command_timeout`, the result is only logged to Home Assistant log and the sensors value is not updated.
## Examples
## Examples binary sensor platform
In this section you find some real-life examples of how to use this sensor.
In this section you find some real-life examples of how to use the command_line sensor.
### SickRage
@ -160,6 +400,279 @@ binary_sensor:
payload_off: "inactive"
```
## Example cover platform
{% raw %}
```yaml
# Example configuration.yaml entry
cover:
- platform: command_line
covers:
garage_door:
command_open: move_command up garage
command_close: move_command down garage
command_stop: move_command stop garage
command_state: state_command garage
value_template: >
{% if value == 'open' %}
100
{% elif value == 'closed' %}
0
{% endif %}
```
## Examples sensor platform
In this section you find some real-life examples of how to use this sensor.
### CPU temperature
Thanks to the [`proc`](https://en.wikipedia.org/wiki/Procfs) file system, various details about a system can be retrieved. Here the CPU temperature is of interest. Add something similar to your `configuration.yaml` file:
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: CPU Temperature
command: "cat /sys/class/thermal/thermal_zone0/temp"
# If errors occur, make sure configuration file is encoded as UTF-8
unit_of_measurement: "°C"
value_template: "{{ value | multiply(0.001) | round(1) }}"
```
{% endraw %}
### Monitoring failed login attempts on Home Assistant
If you'd like to know how many failed login attempts are made to Home Assistant, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: badlogin
command: "grep -c 'Login attempt' /home/hass/.homeassistant/home-assistant.log"
```
Make sure to configure the [Logger integration](/integrations/logger) to monitor the [HTTP integration](/integrations/http/) at least the `warning` level.
```yaml
# Example working logger settings that works
logger:
default: critical
logs:
homeassistant.components.http: warning
```
### Details about the upstream Home Assistant release
You can see directly in the frontend (**Developer tools** -> **About**) what release of Home Assistant you are running. The Home Assistant releases are available on the [Python Package Index](https://pypi.python.org/pypi). This makes it possible to get the current release.
```yaml
sensor:
- platform: command_line
command: python3 -c "import requests; print(requests.get('https://pypi.python.org/pypi/homeassistant/json').json()['info']['version'])"
name: HA release
```
### Read value out of a remote text file
If you own devices which are storing values in text files which are accessible over HTTP then you can use the same approach as shown in the previous section. Instead of looking at the JSON response we directly grab the sensor's value.
```yaml
sensor:
- platform: command_line
command: python3 -c "import requests; print(requests.get('http://remote-host/sensor_data.txt').text)"
name: File value
```
### Use an external script
The example is doing the same as the [aREST sensor](/integrations/arest#sensor) but with an external Python script. It should give you an idea about interfacing with devices which are exposing a RESTful API.
The one-line script to retrieve a value is shown below. Of course it would be possible to use this directly in the `configuration.yaml` file but need extra care about the quotation marks.
```bash
python3 -c "import requests; print(requests.get('http://10.0.0.48/analog/2').json()['return_value'])"
```
The script (saved as `arest-value.py`) that is used looks like the example below.
```python
#!/usr/bin/python3
from requests import get
response = get("http://10.0.0.48/analog/2")
print(response.json()["return_value"])
```
To use the script you need to add something like the following to your `configuration.yaml` file.
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: Brightness
command: "python3 /path/to/script/arest-value.py"
```
### Usage of templating in `command:`
[Templates](/docs/configuration/templating/) are supported in the `command` configuration variable. This could be used if you want to include the state of a specific sensor as an argument to your external script.
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: wind direction
command: "sh /home/pi/.homeassistant/scripts/wind_direction.sh {{ states('sensor.wind_direction') }}"
unit_of_measurement: "Direction"
```
{% endraw %}
### Usage of JSON attributes in command output
The example shows how you can retrieve multiple values with one sensor (where the additional values are attributes) by using `value_json` and `json_attributes`.
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: JSON time
json_attributes:
- date
- milliseconds_since_epoch
command: "python3 /home/pi/.homeassistant/scripts/datetime.py"
value_template: "{{ value_json.time }}"
```
{% endraw %}
## Example switch platform
### Change the icon when a state changes
This example demonstrates how to use template to change the icon as its state changes. This icon is referencing its own state.
{% raw %}
```yaml
switch:
- platform: command_line
switches:
driveway_sensor_motion:
friendly_name: Driveway outside sensor
command_on: >
curl -X PUT -d '{"on":true}' "http://ip_address/api/sensors/27/config/"
command_off: >
curl -X PUT -d '{"on":false}' "http://ip_address/api/sensors/27/config/"
command_state: curl http://ip_address/api/sensors/27/
value_template: >
{{value_json.config.on}}
icon_template: >
{% if value_json.config.on == true %} mdi:toggle-switch
{% else %} mdi:toggle-switch-off
{% endif %}
```
{% endraw %}
### aREST device
The example below is doing the same as the
[aREST switch](/integrations/arest#switch).
The command line tool [`curl`](https://curl.haxx.se/) is used to toggle a pin
which is controllable through REST.
{% raw %}
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
arest_pin_four:
command_on: "/usr/bin/curl -X GET http://192.168.1.10/digital/4/1"
command_off: "/usr/bin/curl -X GET http://192.168.1.10/digital/4/0"
command_state: "/usr/bin/curl -X GET http://192.168.1.10/digital/4"
value_template: '{{ value == "1" }}'
friendly_name: Kitchen Lightswitch
```
{% endraw %}
Given this example, in the UI one would see the `friendly_name` of
"Kitchen Light". However, the `identifier` is `arest_pin_four`, making the
`entity_id` `switch.arest_pin_four`, which is what one would use in
[`automation`](/integrations/automation/) or in [API calls](/developers/).
### Shutdown your local host
This switch will shutdown your system that is hosting Home Assistant.
<div class='note warning'>
This switch will shutdown your host immediately, there will be no confirmation.
</div>
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
home_assistant_system_shutdown:
command_off: "/usr/sbin/poweroff"
```
### Control your VLC player
This switch will control a local VLC media player
([Source](https://community.home-assistant.io/t/vlc-player/106)).
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
vlc:
command_on: "cvlc 1.mp3 vlc://quit &"
command_off: "pkill vlc"
```
### Control Foscam Motion Sensor
This switch will control the motion sensor of Foscam Webcams which Support CGI
Commands ([Source](https://www.iltucci.com/blog/wp-content/uploads/2018/12/Foscam-IPCamera-CGI-User-Guide-V1.0.4.pdf)).
This switch supports statecmd,
which checks the current state of motion detection.
{% raw %}
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
foscam_motion:
command_on: 'curl -k "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=1&usr=admin&pwd=password"'
command_off: 'curl -k "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=0&usr=admin&pwd=password"'
command_state: 'curl -k --silent "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=getMotionDetectConfig&usr=admin&pwd=password" | grep -oP "(?<=isEnable>).*?(?=</isEnable>)"'
value_template: '{{ value == "1" }}'
```
{% endraw %}
- Replace admin and password with an "Admin" privileged Foscam user
- Replace ipaddress with the local IP address of your Foscam
## Services
Available services: `reload`.

2
source/_integrations/compensation.markdown
View File

@ -14,7 +14,7 @@ ha_platforms:
ha_integration_type: integration
---
The Compensation integration consumes the state from other sensors. It exports the compensated value as state and the following values as attributes: `entity_id` and `coefficients`. A single polynomial, linear by default, is fit to all data points provided.
The Compensation {% term integration %} consumes the {% term state %} from other {% term sensors %}. It exports the compensated value as state in a separate {% term entity %} and the following values as attributes: `entity_id` and `coefficients`. A single polynomial, linear by default, is fit to all data points provided.
## Configuration

2
source/_integrations/counter.markdown
View File

@ -18,7 +18,7 @@ The `counter` integration allows one to count occurrences fired by automations.
The preferred way to configure counter helpers is via the user interface. To add one, go to
**{% my helpers title="Settings -> Devices & Services -> Helpers" %}** and click the add button;
next choose the "**Counter**" option.
next choose the **{% my config_flow_start domain=counter title="Counter" %}** option.
To be able to add **Helpers** via the user interface you should have
`default_config:` in your `configuration.yaml`, it should already be there by

102
source/_integrations/cover.command_line.markdown
View File

@ -1,102 +0,0 @@
---
title: "Command Line Cover"
description: "How to control a cover with the command line."
ha_category:
- Cover
ha_release: 0.14
ha_iot_class: Local Polling
ha_domain: command_line
---
A `command_line`cover platform that issues specific commands when it is moved up, down and stopped. It allows anyone to integrate any type of cover into Home Assistant that can be controlled from the command line.
To enable a command line cover in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
cover:
- platform: command_line
covers:
garage_door:
command_open: move_command up garage
command_close: move_command down garage
command_stop: move_command stop garage
```
{% configuration %}
covers:
description: The array that contains all command line covers.
required: true
type: list
keys:
identifier:
description: Name of the command line cover as slug. Multiple entries are possible.
required: true
type: list
keys:
command_open:
description: The command to open the cover.
required: true
default: true
type: string
command_close:
description: The action to close the cover.
required: true
default: true
type: string
command_stop:
description: The action to stop the cover.
required: true
default: true
type: string
command_state:
description: If given, this will act as a sensor that runs in the background and updates the state of the cover. If the command returns a `0` the indicates the cover is fully closed, whereas a 100 indicates the cover is fully open.
required: false
type: string
value_template:
description: if specified, `command_state` will ignore the result code of the command but the template evaluating will indicate the position of the cover. For example, if your `command_state` returns a string "open", using `value_template` as in the example configuration above will allow you to translate that into the valid state `100`.
required: false
default: "'{% raw %}{{ value }}{% endraw%}'"
type: template
friendly_name:
description: The name used to display the cover in the frontend.
required: false
type: string
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
unique_id:
description: An ID that uniquely identifies this cover. Set this to a unique value to allow customization through the UI.
required: false
type: string
{% endconfiguration %}
## Examples
In this section you find some real-life examples of how to use this sensor.
### Full configuration
{% raw %}
```yaml
# Example configuration.yaml entry
cover:
- platform: command_line
covers:
garage_door:
command_open: move_command up garage
command_close: move_command down garage
command_stop: move_command stop garage
command_state: state_command garage
value_template: >
{% if value == 'open' %}
100
{% elif value == 'closed' %}
0
{% endif %}
```
{% endraw %}

13
source/_integrations/cover.mqtt.markdown
View File

@ -125,7 +125,8 @@ device:
required: false
type: string
device_class:
description: Sets the [class of the device](/integrations/cover/), changing the device state and icon that is displayed on the frontend.
description: Sets the [class of the device](/integrations/cover/), changing the device state and icon that is displayed on the frontend. The `device_class` can be `null`.
default: None
required: false
type: string
enabled_by_default:
@ -207,7 +208,7 @@ position_open:
position_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) that can be used to extract the payload for the `position_topic` topic. Within the template the following variables are available: `entity_id`, `position_open`; `position_closed`; `tilt_min`; `tilt_max`. The `entity_id` can be used to reference the entity's attributes with help of the [states](/docs/configuration/templating/#states) template function;"
required: false
type: string
type: template
position_topic:
description: The MQTT topic subscribed to receive cover position messages.
required: false
@ -225,7 +226,7 @@ retain:
set_position_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to define the position to be sent to the `set_position_topic` topic. Incoming position value is available for use in the template `{% raw %}{{ position }}{% endraw %}`. Within the template the following variables are available: `entity_id`, `position`, the target position in percent; `position_open`; `position_closed`; `tilt_min`; `tilt_max`. The `entity_id` can be used to reference the entity's attributes with help of the [states](/docs/configuration/templating/#states) template function;"
required: false
type: string
type: template
set_position_topic:
description: "The MQTT topic to publish position commands to. You need to set position_topic as well if you want to use position topic. Use template if position topic wants different values than within range `position_closed` - `position_open`. If template is not defined and `position_closed != 100` and `position_open != 0` then proper position value is calculated from percentage position."
required: false
@ -267,7 +268,7 @@ tilt_closed_value:
tilt_command_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) that can be used to extract the payload for the `tilt_command_topic` topic. Within the template the following variables are available: `entity_id`, `tilt_position`, the target tilt position in percent; `position_open`; `position_closed`; `tilt_min`; `tilt_max`. The `entity_id` can be used to reference the entity's attributes with help of the [states](/docs/configuration/templating/#states) template function;"
required: false
type: string
type: template
tilt_command_topic:
description: The MQTT topic to publish commands to control the cover tilt.
required: false
@ -295,7 +296,7 @@ tilt_optimistic:
tilt_status_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) that can be used to extract the payload for the `tilt_status_topic` topic. Within the template the following variables are available: `entity_id`, `position_open`; `position_closed`; `tilt_min`; `tilt_max`. The `entity_id` can be used to reference the entity's attributes with help of the [states](/docs/configuration/templating/#states) template function;"
required: false
type: string
type: template
tilt_status_topic:
description: The MQTT topic subscribed to receive tilt status update values.
required: false
@ -307,7 +308,7 @@ unique_id:
value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) that can be used to extract the payload for the `state_topic` topic."
required: false
type: string
type: template
{% endconfiguration %}
<div class="note">

1
source/_integrations/default_config.markdown
View File

@ -14,6 +14,7 @@ ha_integration_type: system
This integration is a meta-component and configures a default set of integrations for Home Assistant to load. The integrations that will be loaded are:
- [Automation](/integrations/automation/) (`automation`)
- [Assist pipeline](/integrations/assist_pipeline/) (`assist_pipeline`)
- [Backup](/integrations/backup/) (`backup`)
- [Bluetooth](/integrations/bluetooth/) (`bluetooth`)
- [Configuration](/integrations/config/) (`config`)

2
source/_integrations/denonavr.markdown
View File

@ -73,6 +73,7 @@ Known supported devices:
- Marantz AV7703
- Marantz AV7704
- Marantz CINEMA 50
- Marantz CINEMA 70s
- Marantz M-CR510
- Marantz M-CR511
- Marantz M-CR603
@ -80,6 +81,7 @@ Known supported devices:
- Marantz M-CR611
- Marantz SR5006
- Marantz SR5008
- Marantz SR5010
- Marantz SR5011
- Marantz SR5015
- Marantz SR6007 - SR6012

12
source/_integrations/easyenergy.markdown
View File

@ -47,6 +47,18 @@ prices for electricity that you use (buy) or return (sell). Every day around
- Time of day when the price is highest
- Time of day when the price is at its lowest
- Percentage of the current price compared to the maximum price
- Number of hours with the current price higher or lower
Entities with the number of hours indicate how many hours there are with a price
**above** or **below** the current hourly price. If we take the graph below as an example
and it is 00:30, then there are 8 hours below the current price and 4 hours above the
current price. With this information, you could switch devices at the X cheapest number
of hours during the day.
<p class='img'>
<img src='/images/integrations/easyenergy/pricegraph.png' alt='Screenshot showing energy price graph.'>
Example showing the energy price graph.
</p>
### Gas market price

12
source/_integrations/fan.markdown
View File

@ -20,9 +20,6 @@ The Fan integration allows you to control and monitor Fan devices.
Available services:
`fan.set_percentage`, `fan.set_preset_mode`, `fan.set_direction`, `fan.oscillate`, `fan.turn_on`, `fan.turn_off`, `fan.toggle`, `fan.increase_speed`, `fan.decrease_speed`
Deprecated services:
`fan.set_speed`
<div class='note'>
Not all fan services may be available for your platform. You can check which services are available for your fan(s) under **Developer Tools** -> **Services**.
@ -144,15 +141,6 @@ Turn fan device off. This is only supported if the fan device supports being tur
| `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
### Deprecated Service `fan.set_speed`
Sets the speed for fan device.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
| `speed` | no | Speed setting
#### Automation example
```yaml

44
source/_integrations/fan.mqtt.markdown
View File

@ -160,6 +160,22 @@ optimistic:
required: false
type: boolean
default: "`true` if no state topic defined, else `false`."
direction_command_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `direction_command_topic`.
required: false
type: template
direction_command_topic:
description: The MQTT topic to publish commands to change the direction state.
required: false
type: string
direction_state_topic:
description: The MQTT topic subscribed to receive direction state updates.
required: false
type: string
direction_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the direction."
required: false
type: template
oscillation_command_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `oscillation_command_topic`.
required: false
@ -175,7 +191,7 @@ oscillation_state_topic:
oscillation_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the oscillation."
required: false
type: string
type: template
payload_available:
description: The payload that represents the available state.
required: false
@ -231,7 +247,7 @@ percentage_state_topic:
percentage_value_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the `percentage` value from the payload received on `percentage_state_topic`.
required: false
type: string
type: template
preset_mode_command_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `preset_mode_command_topic`.
required: false
@ -247,7 +263,7 @@ preset_mode_state_topic:
preset_mode_value_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the `preset_mode` value from the payload received on `preset_mode_state_topic`.
required: false
type: string
type: template
preset_modes:
description: List of preset modes this fan is capable of running at. Common examples include `auto`, `smart`, `whoosh`, `eco` and `breeze`.
required: false
@ -280,7 +296,7 @@ state_topic:
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the state."
required: false
type: string
type: template
unique_id:
description: An ID that uniquely identifies this fan. If two fans have the same unique ID, Home Assistant will raise an exception.
required: false
@ -309,6 +325,9 @@ mqtt:
- name: "Bedroom Fan"
state_topic: "bedroom_fan/on/state"
command_topic: "bedroom_fan/on/set"
direction_state_topic: "bedroom_fan/direction/state"
direction_command_topic: "bedroom_fan/direction/set"
oscillation_command_topic: "bedroom_fan/oscillation/set"
oscillation_state_topic: "bedroom_fan/oscillation/state"
oscillation_command_topic: "bedroom_fan/oscillation/set"
percentage_state_topic: "bedroom_fan/speed/percentage_state"
@ -343,6 +362,8 @@ mqtt:
- name: "Bedroom Fan"
command_topic: "bedroom_fan/on/set"
command_template: "{ state: '{{ value }}'}"
direction_command_template: "{{ iif(value == 'forward', 'fwd', 'rev') }}"
direction_value_template: "{{ iif(value == 'fwd', 'forward', 'reverse') }}"
oscillation_command_topic: "bedroom_fan/oscillation/set"
oscillation_command_template: "{ oscillation: '{{ value }}'}"
percentage_command_topic: "bedroom_fan/speed/percentage"
@ -358,3 +379,18 @@ mqtt:
```
{% endraw %}
This example shows how to configure a fan that doesn't use `forward` and `backward` as directions.
{% raw %}
```yaml
# Example configuration.yaml with direction templates
mqtt:
fan:
- name: "Bedroom Fan"
direction_command_template: "{{ iif(value == 'forward', 'fwd', 'rev') }}"
direction_value_template: "{{ iif(value == 'fwd', 'forward', 'reverse') }}"
```
{% endraw %}

2
source/_integrations/fixer.markdown
View File

@ -17,7 +17,7 @@ To get an overview about the available [currencies](https://fixer.io/symbols).
## Setup
You need to create an [API key](https://fixer.io/product). The free account is limited to only EUR as a base currency, allows 100 requests per month, and updates every hour.
You need to create an [API key](https://apilayer.com/marketplace/fixer-api#pricing). The free account is limited to only EUR as a base currency, allows 100 requests per month, and updates every hour.
## Configuration

1
source/_integrations/forecast_solar.markdown
View File

@ -71,6 +71,7 @@ The Forecast.Solar integration mainly provides sensors that you can use in your
automations.
- Estimated Energy Production - Today (in kWh)
- Estimated Energy Production - Remaining Today (in kWh)
- Estimated Energy Production - Tomorrow (in kWh)
- Estimated Energy Production - This Hour (in kWh)
- Estimated Energy Production - Next Hour (in kWh)

8
source/_integrations/freebox.markdown
View File

@ -6,6 +6,7 @@ ha_category:
- Presence Detection
- Sensor
- Switch
- Camera
ha_release: 0.85
ha_iot_class: Local Polling
ha_codeowners:
@ -18,6 +19,7 @@ ha_platforms:
- device_tracker
- sensor
- switch
- camera
ha_zeroconf: true
ha_integration_type: integration
---
@ -29,6 +31,7 @@ There is currently support for the following device types within Home Assistant:
* [Sensor](#sensor) with metrics for connection speed, internal temperature, free partition space and missed calls
* [Device tracker](#presence-detection) for connected devices
* [Switch](#switch) to control Wi-Fi
* [Camera](#camera)
{% include integrations/config_flow.md %}
@ -79,6 +82,8 @@ The first time Home Assistant will connect to your Freebox, you will need to aut
To make the Wi-Fi switch and the reboot service working you will have to add "Modification des réglages de la Freebox" permission to Home Assistant application in "Paramètres de la Freebox" > "Gestion des accès" > "Applications".
To use cameras from the Freebox Delta, you will have to add "Gestion de l'alarme et maison connectée" permission to Home Assistant application in "Paramètres de la Freebox" > "Gestion des accès" > "Applications".
### Supported routers
Only the routers with Freebox OS are supported:
@ -112,6 +117,9 @@ The monitored metrics are:
* Free partition space of used disks
* Number of missed calls
## Camera
Cameras are only available in Freebox V7 (also known as Freebox Delta).
## Service
### Service `freebox.reboot`

10
source/_integrations/google_assistant_sdk.markdown
View File

@ -78,13 +78,15 @@ The integration setup will next give you instructions to enter the [Application
1. Continue through the steps of selecting the account you want to authorize.
2. **NOTE**: You may get a message telling you that the app has not been verified and you will need to acknowledge that in order to proceed.
2. If your Google account settings are set to a language not supported by the SDK -- which can be noticed by the authentication screen of Google being localized in that language -- the authorization will fail without a clear error. Changing the language at the bottom of the error page to one that is [supported](https://developers.google.com/assistant/sdk/reference/rpc/languages) by the SDK will allow you to continue to the link page of Home Assistant.
3. You can now see the details of what you are authorizing Home Assistant to access with two options at the bottom. Click **Continue**.
3. **NOTE**: You may get a message telling you that the app has not been verified and you will need to acknowledge that in order to proceed.
4. The page will now display _Link account to Home Assistant?_, note _Your instance URL_. If this is not correct, please refer to [My Home Assistant](/integrations/my). If everything looks good, click **Link Account**.
4. You can now see the details of what you are authorizing Home Assistant to access with two options at the bottom. Click **Continue**.
5. You may close the window, and return back to Home Assistant where you should see a _Success!_ message from Home Assistant.
5. The page will now display _Link account to Home Assistant?_, note _Your instance URL_. If this is not correct, please refer to [My Home Assistant](/integrations/my). If everything looks good, click **Link Account**.
6. You may close the window, and return back to Home Assistant where you should see a _Success!_ message from Home Assistant.
{% enddetails %}

16
source/_integrations/habitica.markdown
View File

@ -145,3 +145,19 @@ Also an event `habitica_api_call_success` will be fired with the following data:
"id": "NEW_TASK_UUID"}
}
```
## Templating
`sensor.habitica_USER_dailys`, `sensor.habitica_USER_habits`, `sensor.habitica_USER_rewards`, and `sensor.habitica_USER_todos` have state attributes listing the user's respective tasks. For example, you can see this information in **Developer Tools** -> **States** -> `sensor.habitica_USER_dailys` -> **Attributes**, or by adding a [Markdown card](/dashboards/markdown/) to a dashboard with the following code:
{% raw %}
```jinja
{% for key, value in states.sensor.habitica_USER_dailys.attributes.items() %}
{% if 'text' in value | string %}
{{ loop.index }}. {{ value.text }}
{% endif %}
{% endfor %}
```
{% endraw %}

2
source/_integrations/hassio.markdown
View File

@ -68,6 +68,8 @@ For Home Assistant Host, the following sensors are available:
For each installed add-on Supervisor provides following binary sensors:
(These entities are disabled by default and must be reenabled to appear)
| Sensor | Enabled by default | Description |
| ------- | ------------------ | ----------- |
| Update Available | no | Whether there is an update available for this add-on (This is deprecated, use the Update entities instead.)

6
source/_integrations/honeywell.markdown
View File

@ -33,11 +33,11 @@ Home Assistant is integrated with the following devices through [https://mytotal
- Thermostats
- Every thermostat is exposed as a climate entity
- Known working devices: TH6320R1004, RTH9585WF1004
- Known working devices: [TH6320R1004](https://customer.resideo.com/en-US/Pages/Product.aspx?cat=HonECC%2520Catalog&pid=TH6320R1004/U), [RTH9585WF1004](https://www.honeywellhome.com/us/en/products/air/thermostats/wifi-thermostats/wifi-color-touchscreen-thermostat-rth9585wf1004-u/)
- Sensors
- A Temperature sensor entity.
- A Humidity sensor entity.
- Known working devices: C7089R1013
- Known working devices: [C7089R1013](https://customer.resideo.com/en-US/Pages/Product.aspx?cat=HonECC%20Catalog&pid=C7089R1013/U)
Others devices like Security systems are not currently supported by this integration
@ -45,7 +45,7 @@ Others devices like Security systems are not currently supported by this integra
The climate platform integrates Honeywell US-based thermostats into Home Assistant, allowing control of the thermostat through the user interface. The current inside temperature, operating mode, and fan state are also displayed on the thermostat card.
All [climate services](/integrations/climate) are supported except set_swing_mode
All [climate services](/integrations/climate) are supported except set_swing_mode.
## Sensor

12
source/_integrations/http.markdown
View File

@ -42,7 +42,7 @@ server_port:
type: integer
default: 8123
ssl_certificate:
description: Path to your TLS/SSL certificate to serve Home Assistant over a secure connection. If using the [Let's Encrypt add-on](https://github.com/home-assistant/hassio-addons/tree/master/letsencrypt) this will be at `/ssl/fullchain.pem`. We recommend to use the [NGINX add-on](https://github.com/home-assistant/addons/tree/master/nginx_proxy) instead of using this option.
description: Path to your TLS/SSL certificate to serve Home Assistant over a secure connection. If using the [Let's Encrypt add-on](https://github.com/home-assistant/addons/tree/master/letsencrypt) this will be at `/ssl/fullchain.pem`. We recommend to use the [NGINX add-on](https://github.com/home-assistant/addons/tree/master/nginx_proxy) instead of using this option.
required: false
type: string
ssl_peer_certificate:
@ -50,7 +50,7 @@ ssl_peer_certificate:
required: false
type: string
ssl_key:
description: Path to your TLS/SSL key to serve Home Assistant over a secure connection. If using the [Let's Encrypt add-on](https://github.com/home-assistant/hassio-addons/tree/master/letsencrypt) this will be at `/ssl/privkey.pem`.
description: Path to your TLS/SSL key to serve Home Assistant over a secure connection. If using the [Let's Encrypt add-on](https://github.com/home-assistant/addons/tree/master/letsencrypt) this will be at `/ssl/privkey.pem`.
required: false
type: string
cors_allowed_origins:
@ -118,7 +118,7 @@ http:
## APIs
On top of the `http` integration is a [REST API](https://developers.home-assistant.io/docs/api/rest), [Python API](https://developers.home-assistant.io/docs/api_lib_index) and [WebSocket API](https://developers.home-assistant.io/docs/api/websocket) available.
On top of the `http` integration is a [REST API](https://developers.home-assistant.io/docs/api/rest/), [Python API](https://developers.home-assistant.io/docs/api_lib_index/) and [WebSocket API](https://developers.home-assistant.io/docs/api/websocket/) available.
The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP.
@ -188,7 +188,7 @@ $ curl -X POST -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
http://localhost:8123/api/states/binary_sensor.radio
```
To check if the sensor is working, use again `curl` to retrieve the [current state](/developers/rest_api/#get-apistatesltentity_id).
To check if the sensor is working, use again `curl` to retrieve the [current state](https://developers.home-assistant.io/docs/api/rest/).
```bash
$ curl -X GET -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
@ -227,7 +227,7 @@ print(response.text)
#### Using `httpie`
[`httpie`](https://github.com/jkbrzt/httpie) is a user-friendly CLI HTTP client.
[`httpie`](https://github.com/httpie/httpie) is a user-friendly CLI HTTP client.
```bash
$ http -v POST http://localhost:8123/api/states/binary_sensor.radio \
@ -266,7 +266,7 @@ $ curl -X POST -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \
http://localhost:8123/api/states/sensor.bathroom_temperature
```
You can then use `curl` again to retrieve the [current sensor state](/developers/rest_api/#get-apistatesltentity_id) and verify the sensor is working.
You can then use `curl` again to retrieve the [current sensor state](https://developers.home-assistant.io/docs/api/rest/) and verify the sensor is working.
```bash
$ curl -X GET -H "Authorization: Bearer LONG_LIVED_ACCESS_TOKEN" \

8
source/_integrations/humidifier.mqtt.markdown
View File

@ -121,7 +121,7 @@ device:
required: false
type: string
device_class:
description: The device class of the MQTT device. Must be either `humidifier` or `dehumidifier`.
description: The device class of the MQTT device. Must be either `humidifier`, `dehumidifier` or `null`.
required: false
type: string
default: humidifier
@ -221,7 +221,7 @@ target_humidity_state_topic:
target_humidity_state_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value for the humidifier `target_humidity` state.
required: false
type: string
type: template
mode_command_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to generate the payload to send to `mode_command_topic`.
required: false
@ -237,7 +237,7 @@ mode_state_topic:
mode_state_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value for the humidifier `mode` state.
required: false
type: string
type: template
modes:
description: List of available modes this humidifier is capable of running at. Common examples include `normal`, `eco`, `away`, `boost`, `comfort`, `home`, `sleep`, `auto` and `baby`. These examples offer built-in translations but other custom modes are allowed as well. This attribute ust be configured together with the `mode_command_topic` attribute.
required: false
@ -260,7 +260,7 @@ state_topic:
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a value from the state."
required: false
type: string
type: template
unique_id:
description: An ID that uniquely identifies this humidifier. If two humidifiers have the same unique ID, Home Assistant will raise an exception.
required: false

2
source/_integrations/hunterdouglas_powerview.markdown
View File

@ -178,7 +178,7 @@ Set the type for connected power source. Available options are Hardwired Power S
### Calling a Powerview Scene
``` yaml
alias: "blinds closed at night"
alias: "Blinds closed at night"
trigger:
platform: time
at: "18:00:00"

11
source/_integrations/imap.markdown
View File

@ -49,6 +49,17 @@ Below is an example for setting up the integration to connect to your Microsoft
- Password: Your password
- Charset: `US-ASCII`
### Selecting an alternate SSL cipher list (advanced mode)
If the default IMAP server settings do not work, you might try to set an alternate SLL cipher list.
The SSL cipher list option allows to select the list of SSL ciphers to be accepted from this endpoint. `default` (_system default_), `modern` or `intermediate` (_inspired by [Mozilla Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS)_)
<div class='note info'>
The SSL cipher list is an advanced setting. The option is available only when advanced mode is enabled (see user settings).
</div>
### Using events
When a new message arrives that meets the search criteria the `imap` integration will send a custom [event](/docs/automation/trigger/#event-trigger) that can be used to trigger an automation.

2
source/_integrations/input_boolean.markdown
View File

@ -22,7 +22,7 @@ automations by using them in their conditions.
The preferred way to configure input boolean helpers is via the user interface,
in which they are known as Toggle Helpers. To add one, go to
**{% my helpers title="Settings -> Devices & Services -> Helpers" %}** and click the add button;
next choose the "**Toggle**" option.
next choose the **{% my config_flow_start domain=input_boolean title="Toggle" %}** option.
To be able to add **Helpers** via the user interface you should have
`default_config:` in your `configuration.yaml`, it should already be there by

2
source/_integrations/input_button.markdown
View File

@ -20,7 +20,7 @@ like an automation.
The preferred way to configure button helpers is via the user interface.
To add one, go to **{% my helpers title="Settings -> Devices & Services -> Helpers" %}**
and click the add button; next choose the "**Button**" option.
and click the add button; next choose the **{% my config_flow_start domain=input_button title="Button" %}** option.
To be able to add **Helpers** via the user interface you should have
`default_config:` in your `configuration.yaml`, it should already be there by

4
source/_integrations/input_datetime.markdown
View File

@ -16,9 +16,9 @@ The `input_datetime` integration allows the user to define date and time values
that can be controlled via the frontend and can be used within automations and
templates.
The preferred way to configure input datetime is via the user interface at **Settings** -> **Devices & Services** -> **Helpers**. Click the add button and then choose the **Date and/or time** option.
The preferred way to configure input datetime 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_datetime title="Date and/or time" %}** option.
To be able to add **Helpers** via the user interface you should have `default_config:` in your `configuration.yaml`, it should already be there by default unless you removed it.
To be able to add **{% my helpers title="Helpers" %}** via the user interface you should have `default_config:` in your `configuration.yaml`, it should already be there by default unless you removed it.
If you removed `default_config:` from your configuration, you must add `input_datetime:` to your `configuration.yaml` first, then you can use the UI.
`input_datetime` can also be configured via YAML. To add three datetime inputs to your installation,

2
source/_integrations/input_number.markdown
View File

@ -14,7 +14,7 @@ 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 preferred way to configure an input number is via the user interface at **Settings** -> **Devices & Services** -> **Helpers**. Click the add button and then choose the **Number** option.
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.
To be able to add **Helpers** via the user interface you should have `default_config:` in your `configuration.yaml`, it should already be there by default unless you removed it.
If you removed `default_config:` from you configuration, you must add `input_number:` to your `configuration.yaml` first, then you can use the UI.

2
source/_integrations/input_select.markdown
View File

@ -14,7 +14,7 @@ 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 preferred way to configure an input select is via the user interface at **Settings** -> **Devices & Services** -> **Helpers**. Click the add button and then choose the **Dropdown** option.
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.
To be able to add **Helpers** via the user interface you should have `default_config:` in your `configuration.yaml`, it should already be there by default unless you removed it.
If you removed `default_config:` from you configuration, you must add `input_select:` to your `configuration.yaml` first, then you can use the UI.

4
source/_integrations/input_text.markdown
View File

@ -14,10 +14,10 @@ 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 preferred way to configure an input text is via the user interface at **Settings** -> **Devices & Services** -> **Helpers**. Click the add button and then choose the **Text** option.
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.
To be able to add **Helpers** via the user interface you should have `default_config:` in your `configuration.yaml`, it should already be there by default unless you removed it.
If you removed `default_config:` from you configuration, you must add `input_text:` to your `configuration.yaml` first, then you can use the UI.
If you removed `default_config:` from your configuration, you must add `input_text:` to your `configuration.yaml` first, then you can use the UI.
It can also be configured via `configuration.yaml`:

54
source/_integrations/light.mqtt.markdown
View File

@ -95,7 +95,7 @@ brightness_command_topic:
brightness_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `brightness_command_topic`. Available variables: `value`."
required: false
type: string
type: template
brightness_scale:
description: "Defines the maximum brightness value (i.e., 100%) of the MQTT device."
required: false
@ -108,7 +108,7 @@ brightness_state_topic:
brightness_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the brightness value."
required: false
type: string
type: template
color_mode_state_topic:
description: "The MQTT topic subscribed to receive color mode updates. If this is not configured, `color_mode` will be automatically set according to the last received valid color or color temperature"
required: false
@ -116,11 +116,11 @@ color_mode_state_topic:
color_mode_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the color mode."
required: false
type: string
type: template
color_temp_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `color_temp_command_topic`. Available variables: `value`."
required: false
type: string
type: template
color_temp_command_topic:
description: The MQTT topic to publish commands to change the light’s color temperature state. The color temperature command slider has a range of 153 to 500 mireds (micro reciprocal degrees).
required: false
@ -132,7 +132,7 @@ color_temp_state_topic:
color_temp_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the color temperature value."
required: false
type: string
type: template
command_topic:
description: The MQTT topic to publish commands to change the switch state.
required: true
@ -204,7 +204,7 @@ effect_command_topic:
effect_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `effect_command_topic`. Available variables: `value`."
required: false
type: string
type: template
effect_list:
description: The list of effects the light supports.
required: false
@ -216,11 +216,11 @@ effect_state_topic:
effect_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the effect value."
required: false
type: string
type: template
hs_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `hs_command_topic`. Available variables: `hue` and `sat`."
required: false
type: string
type: template
hs_command_topic:
description: "The MQTT topic to publish commands to change the light's color state in HS format (Hue Saturation).
Range for Hue: 0° .. 360°, Range of Saturation: 0..100.
@ -235,7 +235,7 @@ hs_state_topic:
hs_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the HS value."
required: false
type: string
type: template
icon:
description: "[Icon](/docs/configuration/customizing-devices/#icon) for the entity."
required: false
@ -307,7 +307,7 @@ retain:
rgb_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `rgb_command_topic`. Available variables: `red`, `green` and `blue`."
required: false
type: string
type: template
rgb_command_topic:
description: "The MQTT topic to publish commands to change the light's RGB state."
required: false
@ -319,11 +319,11 @@ rgb_state_topic:
rgb_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the RGB value."
required: false
type: string
type: template
rgbw_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `rgbw_command_topic`. Available variables: `red`, `green`, `blue` and `white`."
required: false
type: string
type: template
rgbw_command_topic:
description: "The MQTT topic to publish commands to change the light's RGBW state."
required: false
@ -335,11 +335,11 @@ rgbw_state_topic:
rgbw_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the RGBW value."
required: false
type: string
type: template
rgbww_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `rgbww_command_topic`. Available variables: `red`, `green`, `blue`, `cold_white` and `warm_white`."
required: false
type: string
type: template
rgbww_command_topic:
description: "The MQTT topic to publish commands to change the light's RGBWW state."
required: false
@ -351,7 +351,7 @@ rgbww_state_topic:
rgbww_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the RGBWW value."
required: false
type: string
type: template
schema:
description: The schema to use. Must be `default` or omitted to select the default schema.
required: false
@ -364,7 +364,7 @@ state_topic:
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the state value. The template should match the payload `on` and `off` values, so if your light uses `power on` to turn on, your `state_value_template` string should return `power on` when the switch is on. For example if the message is just `on`, your `state_value_template` should be `power {{ value }}`."
required: false
type: string
type: template
unique_id:
description: An ID that uniquely identifies this light. If two lights have the same unique ID, Home Assistant will raise an exception.
required: false
@ -381,7 +381,7 @@ white_scale:
xy_command_template:
description: "Defines a [template](/docs/configuration/templating/) to compose message which will be sent to `xy_command_topic`. Available variables: `x` and `y`."
required: false
type: string
type: template
xy_command_topic:
description: "The MQTT topic to publish commands to change the light's XY state."
required: false
@ -393,7 +393,7 @@ xy_state_topic:
xy_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the XY value."
required: false
type: string
type: template
{% endconfiguration %}
<div class='note warning'>
@ -928,23 +928,23 @@ availability_topic:
blue_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract blue color from the state payload value. Expected result of the template is an integer from 0-255 range."
required: false
type: string
type: template
brightness_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract brightness from the state payload value. Expected result of the template is an integer from 0-255 range."
required: false
type: string
type: template
color_temp_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract color temperature from the state payload value. Expected result of the template is an integer representing mired units."
required: false
type: string
type: template
command_off_template:
description: "The [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) for *off* state changes. Available variables: `state` and `transition`."
required: true
type: string
type: template
command_on_template:
description: "The [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) for *on* state changes. Available variables: `state`, `brightness`, `color_temp`, `red`, `green`, `blue`, `flash`, `transition` and `effect`. Values `red`, `green`, `blue`, `brightness` are provided as integers from range 0-255. Value of `color_temp` is provided as integer representing mired units."
required: true
type: string
type: template
command_topic:
description: The MQTT topic to publish commands to change the light’s state.
required: true
@ -1004,11 +1004,11 @@ effect_list:
effect_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract effect from the state payload value."
required: false
type: string
type: template
green_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract green color from the state payload value. Expected result of the template is an integer from 0-255 range."
required: false
type: string
type: template
icon:
description: "[Icon](/docs/configuration/customizing-devices/#icon) for the entity."
required: false
@ -1061,7 +1061,7 @@ qos:
red_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract red color from the state payload value. Expected result of the template is an integer from 0-255 range."
required: false
type: string
type: template
schema:
description: The schema to use. Must be `template` to select the template schema.
required: false
@ -1070,7 +1070,7 @@ schema:
state_template:
description: "[Template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract state from the state payload value."
required: false
type: string
type: template
state_topic:
description: The MQTT topic subscribed to receive state updates.
required: false

8
source/_integrations/lirc.markdown
View File

@ -9,9 +9,9 @@ ha_domain: lirc
ha_integration_type: integration
---
[LIRC](http://www.lirc.org/) integration for Home Assistant allows you to receive signals from an infrared remote control and control actions based on the buttons you press. You can use them to set scenes or trigger any other [automation](/integrations/automation/).
[LIRC](https://www.lirc.org/) integration for Home Assistant allows you to receive signals from an infrared remote control and control actions based on the buttons you press. You can use them to set scenes or trigger any other [automation](/docs/automation/).
Sending IR commands is not supported in this integration (yet), but can be accomplished using the [shell_command component](/integrations/shell_command/) in conjunction with the `irsend` command.
Sending IR commands is not supported in this integration (yet), but can be accomplished using the [shell_command integration](/integrations/shell_command/) in conjunction with the `irsend` command.
## Installation
@ -36,9 +36,9 @@ For more information have a look at `/usr/share/doc/lirc/README.Debian.gz` where
## Configuring LIRC
Now teach LIRC about your particular remote control by preparing a lircd configuration file (`/etc/lirc/lircd.conf`). Search the [LIRC remote database](http://lirc.sourceforge.net/remotes/) for your model. If you can't find it, then you can always use the `irrecord` program to learn your remote. This will create a valid configuration file. Add as many remotes as you want by pasting them into the file. If `irrecord` doesn't work (e.g., for some air conditioner remotes), then the `mode2` program is capable of reading the codes in raw mode, followed by `irrecord -a` to extract hex codes.
Now teach LIRC about your particular remote control by preparing a lircd configuration file (`/etc/lirc/lircd.conf`). Search the [LIRC remote database](https://lirc.sourceforge.net/remotes/) for your model. If you can't find it, then you can always use the `irrecord` program to learn your remote. This will create a valid configuration file. Add as many remotes as you want by pasting them into the file. If `irrecord` doesn't work (e.g., for some air conditioner remotes), then the `mode2` program is capable of reading the codes in raw mode, followed by `irrecord -a` to extract hex codes.
Next, you have to make a `~/.lircrc` file that maps keypresses to system actions. The file has to be in the home dir of the user running Home Assistant, e.g., in `/home/homeassistant/.lircrc` if you're running in a virtual env. [The configuration](http://www.lirc.org/html/configure.html) is a bit tedious but it must be done. Use the `prog = home-assistant` for all keys you want to be recognized by Home Assistant. The values you set for `button` must be the same as in the `lircd.conf` file and the values you put for `config` entry will be the sensor value in Home Assistant when you press the button. An example may look like this:
Next, you have to make a `~/.lircrc` file that maps keypresses to system actions. The file has to be in the home dir of the user running Home Assistant, e.g., in `/home/homeassistant/.lircrc` if you're running in a virtual env. [The configuration](https://www.lirc.org/html/configure.html) is a bit tedious but it must be done. Use the `prog = home-assistant` for all keys you want to be recognized by Home Assistant. The values you set for `button` must be the same as in the `lircd.conf` file and the values you put for `config` entry will be the sensor value in Home Assistant when you press the button. An example may look like this:
```bash
begin

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

@ -238,7 +238,7 @@ unique_id:
value_template:
description: Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract a state value from the payload.
required: false
type: string
type: template
{% endconfiguration %}
<div class='note warning'>

2
source/_integrations/london_air.markdown
View File

@ -13,7 +13,7 @@ ha_integration_type: integration
The `london_air` integration [queries](https://api.erg.kcl.ac.uk/AirQuality/Hourly/MonitoringIndex/GroupName=London/Json) the London air quality [data feed](https://www.londonair.org.uk/LondonAir/API/) provided by Kings College London. A single sensor will be added for each `location` ([local authority district or borough](https://en.wikipedia.org/wiki/List_of_London_boroughs)) specified in the configuration file. The state of each sensor is the overall air quality in that borough. Note that only 28 of the 32 boroughs have data available.
Boroughs can have multiple monitoring sites at different geographical positions within the borough, and each of those sites can monitor up to six different kinds of pollutant. The pollutants are described [here](https://api.erg.kcl.ac.uk/AirQuality/Information/Species/Json) and are Carbon Monoxide ([CO2](https://www.londonair.org.uk/LondonAir/guide/WhatIsCO.aspx)), Nitrogen Dioxide ([NO2](https://www.londonair.org.uk/LondonAir/guide/WhatIsNO2.aspx)), Ozone ([O3](https://www.londonair.org.uk/LondonAir/guide/WhatIsO3.aspx)), Sulfur Dioxide ([SO2](https://www.londonair.org.uk/LondonAir/guide/WhatIsSO2.aspx)), PM2.5 & PM10 [particulates](https://www.londonair.org.uk/LondonAir/guide/WhatIsPM.aspx). The `latitude` and `longitude` of each site is accessible through a `data` attribute of the sensor, as are details about the pollutants monitored at that site. The `sites` attribute of a sensor displays how many monitoring sites that sensor covers. The `updated` attribute of a sensor states when the data was last published. Nominally data is published hourly, but in my experience this can vary. To limit the number of requests made by the sensor, a single API request is made every 30 minutes.
Boroughs can have multiple monitoring sites at different geographical positions within the borough, and each of those sites can monitor up to six different kinds of pollutant. The pollutants are described [here](https://api.erg.kcl.ac.uk/AirQuality/Information/Species/Json) and are Carbon Monoxide ([CO](https://www.londonair.org.uk/LondonAir/guide/WhatIsCO.aspx)), Nitrogen Dioxide ([NO2](https://www.londonair.org.uk/LondonAir/guide/WhatIsNO2.aspx)), Ozone ([O3](https://www.londonair.org.uk/LondonAir/guide/WhatIsO3.aspx)), Sulfur Dioxide ([SO2](https://www.londonair.org.uk/LondonAir/guide/WhatIsSO2.aspx)), PM2.5 & PM10 [particulates](https://www.londonair.org.uk/LondonAir/guide/WhatIsPM.aspx). The `latitude` and `longitude` of each site is accessible through a `data` attribute of the sensor, as are details about the pollutants monitored at that site. The `sites` attribute of a sensor displays how many monitoring sites that sensor covers. The `updated` attribute of a sensor states when the data was last published. Nominally data is published hourly, but in my experience this can vary. To limit the number of requests made by the sensor, a single API request is made every 30 minutes.
To add sensors to Home Assistant for all possible areas/boroughs add the following to your `configuration.yaml` file:

273
source/_integrations/matter.markdown
View File

@ -8,11 +8,11 @@ ha_category:
- Lock
- Sensor
- Switch
ha_release: '2022.12'
ha_release: "2022.12"
ha_iot_class: Local Push
ha_config_flow: true
ha_codeowners:
- '@home-assistant/matter'
- "@home-assistant/matter"
ha_domain: matter
ha_platforms:
- binary_sensor
@ -25,62 +25,101 @@ ha_platforms:
ha_integration_type: integration
---
The Matter integration allows you to control Matter devices on your local WiFi or Thread network.
The Matter integration allows you to control Matter devices on your local Wi-Fi or {% term Thread %} network.
Matter is [the new standard for home automation](https://en.wikipedia.org/wiki/Matter_(standard)) which has just been released. It is in the process of being adopted by the tech industry. Matter is a local protocol, device control is done without the need of any cloud. You can use a Matter compatible device with Home Assistant without having to connect to a vendor specific cloud.
<div class='note warning'>
The integration is marked BETA: Both the Matter standard itself and its implementation within Home Assistant are in a early stage. You may run into compatibility issues and/or other bugs.
</div>
Matter devices are available using either WiFi based communication or [Thread](/integrations/thread/), both are supported by Home Assistant. Bluetooth is used for adding new devices to your Matter network.
# What is Matter?
Home Assistant only supports control of Matter devices. Home Assistant is not a bridge itself and it cannot turn devices within Home Assistant into Matter compatible devices.
Matter is [the new standard for home automation](<https://en.wikipedia.org/wiki/Matter_(standard)>), which has been released recently. It is in the process of being adopted by the tech industry. Matter is a local protocol. Device control is done without the need of any cloud. From a technical perspective, you can use a Matter-compatible device with Home Assistant without connecting to a vendor-specific cloud. However, some vendors may require you to set up an account before you can enable Matter.
At this time there are only a few devices available that are compatible with the standard and some of them require you to join a beta/developer program. It is to be expected that more devices will hit the market during the 2nd quarter of 2023 and beyond.
Unlike the radio based protocols we're already familiar with in the IoT landscape, like Zigbee and Z-Wave, Matter uses standard IP-based communication. Matter is not a radio protocol, but a control protocol that runs on top of the existing network infrastructure, using your existing Wi-Fi/Ethernet routers and Thread.
<p class='note'>
Both the Matter standard itself and its implementation within Home Assistant are in a very early stage where only the basics are working and/or breaking changes can still happen. Using it in production is not recommended yet until it matures a bit more.
</p>
Home Assistant is a so-called _controller_, it can control Matter based devices. Other examples of Matter controllers are the Google Nest speakers, Apple HomePods, and a SmartThings Station.
One of the great features of Matter is the so called _Multi Fabric_ feature: you can join the same device to multiple controllers. For example: add it to Google Home, Apple Home, and Home Assistant at the same time.
## Bridge devices
For devices where Home Assistant provides a native integration (with local API), Matter may not be the best option. Matter, being a universal standard, might not have the nitty-gritty features that come with a product specific protocol. A good example is Philips Hue: the communication over Matter only provides the basic controls over lights, the official integration brings all Hue unique features like (dynamic) scenes, entertainment mode, etc.
One of the great things about Matter is that you can have both Wi-Fi and Thread based devices on the same controller.
Next to actual devices (like actors or sensors), you will also see bridges. The bridge connects the network over Ethernet or Wi-Fi and bridges multiple devices into a Matter network. A great example is the Philips Hue V2 bridge, which is a Zigbee hub and a Matter bridge. This bridge exposes all Zigbee devices already connected to the bridge as Matter devices on the network. Also, Aqara, SwitchBot, and IKEA have launched such Hub devices.
<p class='note'>
The Matter protocol relies on (local) IPv6 and mDNS (multicast traffic) which should be able to travel freely in your network. Matter devices (and any Thread Border routers) must be on the same LAN/VLAN as Home Assistant. Implementations like mDNS reflectors usually do more harm than good.
</p>
<div class='note'>
Home Assistant, as a Matter controller, only supports **control** of Matter devices. Home Assistant is not a bridge itself and it cannot turn existing devices within Home Assistant into Matter compatible devices.
</div>
## Thread
Matter goes hand-in-hand with (but is not the same as) [Thread](<https://en.wikipedia.org/wiki/Thread_(network_protocol)>), which is a low power Radio mesh networking techology. Much like Zigbee, but with the key difference that it is _IP-addressable_, making it the perfect companion transport for Matter.
Thread devices become directly addressable by Matter controllers (such as Home Assistant) thanks to the use of so-called Thread Border Routers, which are in fact just devices that are both within your network and have a Thread chip builtin and thus act as a "router" between the Thread radio signal and your local network. These border routers (you will probably end up having multiple of them in your house) make sure that your Thread-based devices are reachable on your regular network and thus can be controlled with Matter. Examples of Thread Borders routers are the Apple TV 4K, HomePod (gen 2 or Mini), and the Google Nest Hub V2, so devices that you may already own. Besides that, all kind of other border routers are available, built-in to hardware appliances or software solutions based on OpenThread Border Router, such as the add-on we provide to use with the built-in Zigbee/Thread chip of the [Home Assistant Yellow](/yellow/) or the [Home Assistant SkyConnect](/skyconnect/) dongle.
To use any Thread-based devices on a Matter controller, you need to have at least one Thread Border router device within range of the device.
More info about Thread and diagnosing Thread networks and Border routers, see the [Thread](/integrations/thread/) integration.
<div class='note'>
Many devices that (will) hit the market will use Thread for radio communication and Matter as a control protocol, but this is not guaranteed. For example, Thread-based devices are available that only support Apple HomeKit or some vendor-specific communication protocol. There are also a few cases where you need to apply for a (beta) firmware update on the device to enable Matter as a communication protocol. Therefore, do not assume Matter support when you see a Thread logo when looking for devices. Please be sure to look for the *Matter* logo itself (on either Wi-Fi/Ethernet-based devices or Thread) or any other confirmation by the manufacturer that the device supports Matter.
</div>
## Bluetooth
Most (if not all) Matter-compliant devices will also have a Bluetooth chip onboard, this is to ease commissioning (a somewhat technical term for adding a device to your controller). Bluetooth will not be used to control a device but only to pair it after unboxing or factory resetting. The Home Assistant controller uses the Home Assistant Companion app to do commissioning, so you can bring your phone close to the device you want to commission. The controller will then send your network credentials to your device over Bluetooth in the commissioning process. If that succeeds, the device will communicate over its native interface, meaning Wi-Fi, Ethernet, or Thread.
<div class='note'>
Although your Home Assistant server might have a Bluetooth adapter on board that the controller can use to commission devices, we choose not to utilize that adapter. Mainly to prevent issues with the built-in Bluetooth integration but also because it makes more sense to bring your mobile devices close to the Matter device you'd like to commission.
</div>
## Multi fabric: join to multiple controllers
One of the great features of Matter is the so-called _Multi Fabric_ feature: you can join the same device to multiple controllers. For example, simultaneously add it to Google Home, Apple Home, and Home Assistant. The standard describes that each device should be able to at least support 5 different fabrics simultaneously.
For devices where Home Assistant provides a native integration (with local API), Matter may not be the best option. Matter, being a universal standard, might not have the nitty-gritty features that come with a product-specific protocol. A good example is Philips Hue: the communication over Matter only provides the basic controls over lights, while the official [Hue integration](/integrations/hue) brings all Hue unique features like (dynamic) scenes, entertainment mode, etc.
![image](/images/integrations/matter/matter_thread_infographic.webp)
Image taken from [this excellent article by The Verge](https://www.theverge.com/23165855/thread-smart-home-protocol-matter-apple-google-interview) about Matter that shows the landcape of Matter, Thread, Border routers and bridges in a nice visualized way.
{% include integrations/config_flow.md %}
_If you run Home Assistant Container, Home Assistant Core, or you don’t want to use the built-in Matter Server add-on, please see the [advanced installation instructions](#advanced-installation-instructions)._
For communicating with Matter devices, the Home Assistant integration runs its own "Matter controller" in a separate process which will be launched as an add-on. This add-on runs the controller software and connects your Matter network (called Fabric in technical terms) and Home Assistant. The Home Assistant Matter integration connects to this server via a WebSocket connection.
The only supported configuration (for now) for the Matter integration is by running the officially provided Home Assistant Matter add-on. Running the [Matter server](https://github.com/home-assistant-libs/python-matter-server) by any other means is at your own risk and is currently not officially supported.
## Current state of the integration
While the support for Matter is evolving, we will regularly update the Matter integration with new features or device support. Because it might be hard to track what's supported and what not, we list the current state here and try to update this information as often as possible.
While the support for Matter is evolving, we will regularly update the Matter integration with new features or device support. Because it might be hard to track what's supported and what's not, we list the current state here and try to update this information regularly.
Platform support in Home Assistant is currently limited to switches, lights, locks, covers and (binary) sensors.
Supported platforms (device types):
### Known issues
- Binary sensor: We have so far tested door/window sensors and motion sensors, but others will probably work too.
- Climate: Support for thermostat devices is in development now.
- Cover: Has been implemented, but support for a tilt feature is still missing.
- Lights: All features (in the Matter specification) should be supported, including color control, etc.
- Locks: Basic lock control has been implemented, but not all devices and features are supported yet.
- Sensor: We have tested Illuminance and temperature sensors, but others will probably work too.
- Switch: Powerplugs should work (note: no support for energy metering yet in Matter).
- Support for bridges (e.g. Hue bridge) is NOT working yet. Please do not try to add a bridge as it will break the integration.
- Door/window sensors show up reversed (closed instead of open)
Note that a single Matter device can exist on multiple platforms. For example, a Motion sensor also has a temperature sensor and an illuminance sensor on board.
_Both issues will be fixed in Home Assistant 2023.3._
If you own a (bridged) Matter device and you are missing controls for this device, create an issue on [GitHub](https://github.com/home-assistant/home-assistant.io) and make sure to post your Integration diagnostics there. In some cases, we can easily extend the existing platform support based on your diagnostics dump.
## Adding Matter devices to Home Assistant
Each Matter network is called a fabric. Each home automation controller that controls Matter devices has its own fabric. You can add devices directly to the fabric of your Home Assistant instance, or share them from another fabric (ie Google, Apple) to Home Assistant's fabric. We're going to explore all these options below.
Each Matter network is called a fabric. Each home automation controller that controls Matter devices has its own "fabric". You can add devices directly to the fabric of your Home Assistant instance, or share them from another fabric (ie Google, Apple) to Home Assistant's fabric. We're going to explore all these options below.
### Add a device using the iOS Companion app
This will use the Bluetooth connection of your phone to add the device.
1) Open The Home Assistant app on your phone.
2) Go to Settings, Devices & Services.
3) On the Devices tab, press the `Add device` button.
4) Choose `Add Matter device` as the top of the list.
5) Scan the QR-code of the Matter device with your phone camera or press `More options...` to manually enter the Commission code.
6) Press the `Add to Home Assistant` button which will start the commissioning process which may take up to a few minutes.
7) If you're adding a test board or beta device you might get a prompt about an Uncertified Accessory". In this dialog press `Add Anyway`.
8) Once prompted you can enter a custom Accessory Name, this is just an internal reference and not visible in Home Assistant so you can type whatever you like here.
9) Once the process is complete and you pressed the `Done` button, you are redirected to the Device within Home Assistant and its ready for use.
1. Open The Home Assistant app on your phone.
2. Go to {% my integrations title="**Settings** > **Devices & Services**" %}.
3. On the **Devices** tab, press the **Add device** button.
4. Choose **Add Matter device** at the top of the list.
5. Scan the QR-code of the Matter device with your phone camera or press **More options...** to manually enter the Commission code.
6. Select the **Add to Home Assistant** button which will start the commissioning process which may take up to a few minutes.
7. If you're adding a test board or beta device, you might get a prompt about an "Uncertified Accessory". In this dialog, select **Add Anyway**.
8. Once prompted, you can enter a custom **Accessory Name**, this is just an internal reference and not visible in Home Assistant. You can type whatever you like here.
9. Once the process is complete and you pressed the **Done** button, you are redirected to the device within Home Assistant. It is ready for use.
<lite-youtube videoid="8y79Kq3QfCQ" videotitle="Add Matter device via iOS app in Home Assistant"></lite-youtube>
@ -88,14 +127,14 @@ This will use the Bluetooth connection of your phone to add the device.
This will use the Bluetooth connection of your phone to add the device.
1) Open The Home Assistant app on your phone.
2) Go to Settings, Devices & Services.
3) On the Devices tab, press the `Add device` button.
4) Choose `Add Matter device` as the top of the list.
5) Scan the QR-code of the Matter device with your phones camera or press the `Setup without QR-code` button to manually enter the Commission code.
6) The process will start adding the device which takes up to a few minutes.
7) If you're adding a test board (e.g. ESP32 running the example apps) and commissioning fails, you might need to take some actions in the Google Developer console, have a look at any instructions for your test device.
8) Once the process is complete and you pressed the `Done` button, you are redirected to the Device within Home Assistant and its ready for use.
1. Open The Home Assistant app on your phone.
2. Go to {% my integrations title="**Settings** > **Devices & Services**" %}.
3. On the **Devices** tab, press the **Add device** button.
4. Choose **Add Matter device** as the top of the list.
5. Scan the QR-code of the Matter device with your phones camera or select the **Setup without QR-code** button to manually enter the commission code.
6. The process will start adding the device which takes up to a few minutes.
7. If you're adding a test board (e.g. ESP32 running the example apps) and commissioning fails, you might need to take some actions in the Google Developer console, have a look at any instructions for your test device.
8. Once the process is complete and you pressed the **Done** button, you are redirected to the device within Home Assistant. It is ready for use.
<lite-youtube videoid="Fk0n0r0eKcE" videotitle="Add Matter device via Android app in Home Assistant"></lite-youtube>
@ -103,9 +142,9 @@ This will use the Bluetooth connection of your phone to add the device.
This method will allow you to select a Matter device from Apple Home and share it to Home Assistant. The result is that the device can be controlled from both Apple Home and Home Assistant at the same time.
1) Find your device in Apple Home and press the jogwheel to edit it. In the page with detailed descriptions and settings for the device, scroll all the way down and press the button `Turn On Pairing Mode`.
2) You are now given a Setup code, copy this to the clipboard.
3) Follow the [Add a device using the iOS Companion app](#add-a-device-using-the-ios-companion-app) directions above to add the device to Home Assistant where you paste the code you just received from Apple Home.
1. Find your device in Apple Home and press the jogwheel to edit it. In the page with detailed descriptions and settings for the device, scroll all the way down and press the button **Turn On Pairing Mode**.
2. You are now given a Setup code, copy this to the clipboard.
3. Follow the [Add a device using the iOS Companion app](#add-a-device-using-the-ios-companion-app) directions above to add the device to Home Assistant where you paste the code you just received from Apple Home.
<lite-youtube videoid="nyGyZv90jnQ" videotitle="Share Matter device from Apple Home to Home Assistant"></lite-youtube>
@ -113,94 +152,114 @@ This method will allow you to select a Matter device from Apple Home and share i
This method will allow you to share a device that was added to Google Home to Home Assistant. The result is that the device can be controlled from both Google Home and Home Assistant at the same time.
1) Open the device in Google Home and press the settings button (jog wheel) in the top right.
2) Click `Linked Matter apps and services`.
3) Press the button `Link apps and services` to link the device to Home Assistant.
4) Choose Home Assistant from the list, you are redirected to the Home Assistant Companion app now. Press `Add device`.
5) Your device will now be added to Home Assistant. When the process finishes, you're redirected to the device page in Home Assistant.
1. Open the device in Google Home and press the settings button (jog wheel) in the top right.
2. Click **Linked Matter apps and services**.
3. Press the button **Link apps and services** to link the device to Home Assistant.
4. Choose Home Assistant from the list, you are redirected to the Home Assistant Companion app now. Press **Add device**.
5. Your device will now be added to Home Assistant. When the process finishes, you're redirected to the device page in Home Assistant.
<lite-youtube videoid="-B4WWevd2JI" videotitle="Share Matter device from Google Home to Home Assistant"></lite-youtube>
## Device specific instructions
<p class='note'>
At this time it is not yet possible to share a device from Home Assistant to another platform. This feature should be added after the Matter SDK 1.1 is released.
</p>
Because availability of actual Matter devices is sparse and proper HOWTO documentation even more, we provide a few step by step instructions for devices we have currently tested.
## Experiment with Matter using a ESP32 dev board
### TP-Link Tapo P125M (power plug)
This device runs Matter out of the box, so you can add it directly to the controller(s) of your choice!
Look for the M addition in the model name, a device without the M (regular P125) is not Matter compliant. This device is available in the US only.
[TP-Link Tapo P125M on Amazon](https://amzn.to/3RILJah)
### ESP32 dev board running Matter example app
This is the most convenient and easy way to start playing with Matter. We have [prepared a page for you](https://nabucasa.github.io/matter-example-apps/) where you can easily flash Matter firmware to a supported ESP32 development board. We actually recommend the M5 Stamp C3 device running the Lightning app.
You do not yet have any Matter-compatible hardware but you do like to try it out or maybe create your own DIY Matter device? We have [prepared a page for you](https://nabucasa.github.io/matter-example-apps/) where you can easily flash Matter firmware to a supported ESP32 development board. We recommend the M5 Stamp C3 device running the Lightning app.
NOTE for Android users: You need to follow the instructions at the bottom of the page to add the test device to the Google developer console, otherwise commissioning will fail. iOS users will not have this issue but they will get a prompt during commissioning asking if you trust the development device.
1) Make sure you are using the Google Chrome or Microsoft Edge browser.
2) Open https://nabucasa.github.io/matter-example-apps/
3) Attach the ESP32 device using an USB cable.
4) Click the radiobutton next to the example you like to setup, in case of an M5 Stamp, click `Lightning app for M5STAMP C3`.
5) Press `Connect`.
6) In the popup dialog that appears choose the correct serial device, in most cases this will be something like "cu-usbserial" or alike.
7) Click `Install Matter Lightning app example` and let it install the firmware on the device, this will take a few minutes.
8) Once the device is flashed with the Matter firmware, connect to the device again but this time choose `Logs & console`.
9) You are presented with a console interface where you see live logging of events. This is actually an interactive shell where you can type commands. For a list of all commands, type `matter help` and press enter.
10) To add the device, we need the QR code. In the console type in `matter onboardingcodes ble` and copy/paste the URL in your browser.
11) Use the QR code to add the device using one of the above instructions on your phone, e.g. using the Home Assistant Companion app.
1. Make sure you use Google Chrome or Microsoft Edge browser.
2. Open https://nabucasa.github.io/matter-example-apps/
3. Attach the ESP32 device using a USB cable.
4. Select the radio button next to the example you like to set up, in case of an M5 Stamp, click **Lightning app for M5STAMP C3**.
5. Select **Connect**.
6. In the popup dialog that appears, choose the correct serial device. This will usually be something like "cu-usbserial" or alike.
7. Click **Install Matter Lightning app example** and let it install the firmware on the device. This will take a few minutes.
8. Once the device is flashed with the Matter firmware, connect to the device again but this time choose **Logs & console**.
9. You are presented with a console interface where you see live logging of events. This is an interactive shell where you can type commands. For a list of all commands, type **matter help** and press enter.
10. To add the device, we need the QR code. In the console, type in `matter onboardingcodes ble` and copy/paste the URL into your browser.
11. Use the QR code to add the device using one of the above instructions on your phone, e.g. using the Home Assistant Companion app.
## Known working devices
Because the availability of actual Matter devices (and their documentation) is sparse, we provide a list of all known working devices that are tested by the Home Assistant Matter developers and/or the community to help you find the device you need. Note: The list below is ordered alphabetically, and some links contain affiliate links.
Did you test a device that is not listed below? It would be greatly appreciated if you share your experience either on the Matter discord channel or contribute a PR (or suggestion) to this documentation page so you can help others, thanks in advance!
### Aqara M2 Hub
- Bridges Aqara (Zigbee) devices connected to the hub to Matter.
- You need to enable Matter support/firmware in the Aqara app.
- You will need an Aqara (cloud) account and the app before you can use Matter.
- See [this Aqara landingpage](https://www.aqara.com/en/article-1583275073188196352.html) for more information, including what devices are bridged.
- Thermostat devices (climate platform) are not supported yet (but are currently in development).
- Device events, for example for the wall rockers and Cube, are not supported.
### Eve Energy (power plug), Eve Door & Window (contact sensor), Eve Motion (motion sensor)
1) Look for the Thread logo on the box to ensure you have the new device which is compatible with Matter.
2) The Eve device runs on HomeKit by default, you will need an iOS device to set it up out of the box.
3) The Eve device uses Thread for communication, therefore you will need to have a Thread Border Router configured in your network setup, such as the Apple TV 4K (2021/2022), Homepod Mini, or Homepod V2.
4) You need to join the [Eve Beta program here](https://www.evehome.com/en/meet-matter) and wait for instructions per email.
5) Update the firmware of your Eve device using the Eve beta app to Matter.
6) During the update process the Eve app will create a new QR code for you to save somewhere safe. This QR code is required when you want to add the device to a Matter controller. The normal QR code attached to the device will no longer work!
7) During the upgrade process, the Eve app will join the device to Apple Home using Matter.
8) Confirm that the device is working properly within Apple Home.
9) Follow our instructions above to share the device from Apple Home to Home Assistant.
- If you see a Matter logo on the box, the device runs Matter already and you can add it to HA immediately.
- If there is a Thread logo, you need to install the Matter firmware using the Eve app.
- No Matter logo and no Thread logo on the box? The device is not Matter compatible.
- The energy metering feature of the Eve plug will not work in Home Assistant (Apple only feature).
- Eve has just released official Matter support so ignore any documentation about the beta program.
Once the initial firmware upgrade to Matter is complete, the device can also be paired to non-Apple based Thread networks, like Google Home or later Home Assistant's own Thread implementation based on OTBR but you do need an Apple ecosystem running (iOS phone + Border router) for the first time setup.
[Eve Energy on Amazon](https://amzn.to/3YuO62P)
[Eve Door & Window on Amazon](https://amzn.to/3RIU6ml)
[Eve Motion on Amazon](https://amzn.to/3jDujiP)
- [Eve Energy on Amazon](https://amzn.to/3YuO62P)
- [Eve Door & Window on Amazon](https://amzn.to/3RIU6ml)
- [Eve Motion on Amazon](https://amzn.to/3jDujiP)
### Nanoleaf Matter bulbs and Lightstrips
- Although the products work great once commissioned, multiple users have reported that commissioning them can be a bit difficult and requires some patience and multiple resets or optimizations to your home network.
- Check the [Nanoleaf Matter infopage](https://nanoleaf.me/en-EU/integration/matter/) for all supported products and instructions.
### Philips Hue (V2) Bridge
The Philips Hue V2 bridge supports Matter since a recent update (the beta program closed, it is now officially available). You can enable Matter support from the Hue app after which you can commission it to Home Assistant and other fabrics.
- Binding the Hue bridge to Home Assistant does not make sense because you will lose functionality over the default Hue integration in Home Assistant, such as button press events and (dynamic) scenes.
- You will need a Hue/Signify (cloud) account and the app before you can use Matter.
- Device events for example for dimmer remotes are not supported.
- Only basic control of lights is supported, no scenes, events, effects etc.
### TP-Link Tapo P125M (power plug)
- Look for the M addition in the model name, a device without the M (regular P125) is not Matter compliant.
- This device is available in the US only.
[TP-Link Tapo P125M on Amazon](https://amzn.to/3RILJah)
## Troubleshooting
### I do not see the option to add a Matter device in the settings
We've added the option to **Add a Matter device** from the **Settings**>**Devices** in a recent version of the Home Assistant frontend, available from version 2023.3 and upwards or if you're running the Home Assistant nightly channel. If you are on a previous version of Home Assistant, you should see a button **Configure** on the Matter integration card within **Settings**>**Devices & Services**>**Integrations**. Click that **Configure** button and you should be able to see the **Commission** button on the Companion app.
### General recommendations
- Using Thread-based Matter devices in Home Assistant requires Home Assistant OS (version 10 and above) because of kernel patches to solve routing issues. Not using HAOS (and thus the official Matter add-on) is at your own risk.
- To use Thread devices you will need a Thread Network with at least one Thread Border Router in your network nearby the Thread device(s). Apple users need for example the Apple TV 4K or the HomePod Mini, while Google users need a Nest Hub V2. Use the Thread integration in Home Assistant to diagnose your Thread network(s).
- Start simple and work from there, keep your network easy and add for example an ESP32 test device. Once that works, move on to the next step or more devices.
- Realize that you are an early adopter, both on the hardware side and on the software (controller) side so you may run into compatibility issues or features that are still missing. Report any issues you may find and help out others if you find a workaround or tested a device.
- Make sure IPv6 (multicast) traffic travels freely from your network to the Home Assistant host. There is no requirement to have an IPv6-enabled internet connection or DHCPv6 server. However, IPv6 support has to be enabled (it's enabled by default on Home Assistant OS).
### I do not see the button "Commission using the Companion app"
This button will only be visible within the Home Assistant Companion App (so not in the browser) and your device meets all requirements for Matter support.
- For iOS, minimum version is iOS 16 (minimal 16.3 is preferred) and the most recent version of the HA companion app.
- For Android, minimum version is 8.1 and the most recent version of both the Google Home app and the (full) HA Companion app, downloaded from the app store.
### When I'm trying to commission using the Android app, I get an error stating "Matter is currently unavailable"
See above, make sure your device meets all requirements to support Matter. Update Android to the latest version and the Google Home and Home Assistant Companion app. To quickly verify if your device meets all requirements to support Matter, on your Android device go to **Settings**>**Google**>**Devices & Sharing**. There should be an entry there for **Matter devices**.
See above, make sure your device meets all requirements to support Matter. Update Android to the latest version and the Google Home and Home Assistant Companion app. To quickly verify if your device meets all requirements to support Matter, on your Android device, go to **Settings** > **Google** > **Devices & Sharing**. There should be an entry there for **Matter devices**.
Some users have reported that uninstalling and reinstalling the Google Home app fixed this issue for them.
Also see this [extended troubleshooting guide](https://developers.home.google.com/matter/verify-services) from Google.
### Unable to commission devices, it keeps giving errors or stops working randomly
We've seen cases (e.g. on UniFi hardware) where IPv6 derived from the Internet Provider causes issues with the discovery of Matter devices. Keep this in mind when you experience issues trying to add or control Matter devices. Protocols like Matter are designed for regular residential network setups and do not play nice with enterprise solutions like VLAN's, Multicast filtering, and IGMP snooping. To avoid issues, try to keep your network as simple and flat as possible.
## Advanced installation instructions
The Matter protocol relies on (local) IPv6 and mDNS (multicast traffic) which should be able to travel freely in your network. Matter devices that use Wi-Fi (including Thread Border routers) must be on the same LAN/VLAN as Home Assistant. Matter devices that only use Thread must be joined to Thread networks for which there is at least one border router connected to the Home Assistant LAN.
If you are using Home Assistant Container, Home Assistant Core, or you don't want to use the built-in Matter Server add-on, you will need to run the Matter Server yourself, to which the Matter integration will connect.
### Running Matter Server
This application provides the connection between your Matter network (called Fabric in technical terms) and Home Assistant. The Home Assistant Matter integration connects to this server via a websocket connection. You need to run the Matter Server before you can use the integration.
There are multiple ways to run the server:
**Option 1: The official Matter Server add-on, as described above**
_This option is only available for Home Assistant OS (the recommended installation type) and Home Assistant Supervised installations._
**Option 2: Run the Matter server yourself**
This option is considered a very advanced setup and only for experienced users. You can find instructions on how to run the Matter Server in the [project repository](https://github.com/home-assistant-libs/python-matter-server).
_Disclaimer: Some links on this page are affiliate links._
Investigate your network topology if you experience any issues with discovering devices (like the initial commission keeps failing) or if devices become unavailable randomly. For instance, a setting on your router or Wi-Fi access point to "optimize" multicast traffic can harm the (discovery) traffic from Matter devices. Keep this in mind when you experience issues trying to add or control Matter devices. Protocols like Matter are designed for regular residential network setups and do not play nicely with enterprise networking solutions like VLANs, Multicast filtering, and IGMP snooping. Try to keep your network as simple and flat as possible to avoid issues.

30
source/_integrations/monessen.markdown Normal file
View File

@ -0,0 +1,30 @@
---
title: "Monessen"
description: Connect and control your Monessen fireplace using the IntelliFire integration
ha_category:
- Binary Sensor
- Climate
- Fan
- Light
- Number
- Sensor
- Switch
ha_domain: monessen
ha_integration_type: virtual
ha_supporting_domain: intellifire
ha_supporting_integration: IntelliFire
ha_release: 2022.3
ha_codeowners:
- '@jeeftor'
ha_platforms:
- binary_sensor
- climate
- fan
- light
- number
- sensor
- switch
ha_iot_class: Local Polling
---
{% include integrations/supported_brand.md %}

14
source/_integrations/mqtt.markdown
View File

@ -80,6 +80,12 @@ If you experience an error message like `Failed to connect due to exception: [SS
Advanced broker configuration options include setting a custom client ID, setting a client certificate and key for authentication and enabling TLS validation of the brokers certificate for. To access the advanced settings, open the MQTT broker settings, switch on `Advanced options` and click `Next`. The advanced options will be shown by default if there are advanced settings active already.
<div class='note info'>
Advanced broker options are accessible only when advanced mode is enabled (see user settings), or when advanced broker settings are configured already.
</div>
#### Alternative client ID
You can set a custom MQTT client ID, this can help when debugging. Mind that the client ID must be unique. Leave this settings default if you want Home Assistant to generate a unique ID.
@ -280,6 +286,10 @@ Configuration variable names in the discovery payload may be abbreviated to cons
'curr_temp_tpl': 'current_temperature_template',
'dev': 'device',
'dev_cla': 'device_class',
'dir_cmd_t': 'direction_command_topic',
'dir_cmd_tpl': 'direction_command_template',
'dir_stat_t': 'direction_state_topic',
'dir_val_tpl': 'direction_value_template',
'dock_t': 'docked_topic',
'dock_tpl': 'docked_template',
'e': 'encoding',
@ -369,6 +379,8 @@ Configuration variable names in the discovery payload may be abbreviated to cons
'pl_cln_sp': 'payload_clean_spot',
'pl_cls': 'payload_close',
'pl_disarm': 'payload_disarm',
'pl_dir_fwd': 'payload_direction_forward',
'pl_dir_rev': 'payload_direction_reverse',
'pl_home': 'payload_home',
'pl_inst': 'payload_install',
'pl_lock': 'payload_lock',
@ -523,6 +535,8 @@ The following software has built-in support for MQTT discovery:
- [HASS.Agent](https://github.com/LAB02-Research/HASS.Agent)
- [IOTLink](https://iotlink.gitlab.io) (starting with 2.0.0)
- [MiFlora MQTT Daemon](https://github.com/ThomDietrich/miflora-mqtt-daemon)
- [Nuki Hub](https://github.com/technyon/nuki_hub)
- [Nuki Smart Lock 3.0 Pro](https://support.nuki.io/hc/en-us/articles/12947926779409-MQTT-support)
- [OpenMQTTGateway](https://github.com/1technophile/OpenMQTTGateway)
- [room-assistant](https://github.com/mKeRix/room-assistant) (starting with 1.1.0)
- [SmartHome](https://github.com/roncoa/SmartHome)

39
source/_integrations/notify.command_line.markdown
View File

@ -1,39 +0,0 @@
---
title: "Command line Notify"
description: "Instructions on how to add command line notifications to Home Assistant."
ha_category:
- Notifications
ha_release: 0.14
ha_domain: command_line
---
The `command_line` platform allows you to use external tools for notifications from Home Assistant. The message will be passed in as STDIN.
To enable those notifications in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
- name: NOTIFIER_NAME
platform: command_line
command: "espeak -vmb/mb-us1"
```
{% configuration %}
name:
description: Setting the optional parameter `name` allows multiple notifiers to be created. The notifier will bind to the service `notify.NOTIFIER_NAME`.
required: false
default: notify
type: string
command:
description: The action to take.
required: true
type: string
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
{% endconfiguration %}
To use notifications, please see the [getting started with automation page](/getting-started/automation/).

6
source/_integrations/number.mqtt.markdown
View File

@ -106,7 +106,8 @@ device:
required: false
type: string
device_class:
description: The [type/class](/integrations/number/#device-class) of the number.
description: The [type/class](/integrations/number/#device-class) of the number. The `device_class` can be `null`.
default: None
required: false
type: device_class
default: None
@ -194,7 +195,8 @@ unique_id:
required: false
type: string
unit_of_measurement:
description: Defines the unit of measurement of the sensor, if any.
description: Defines the unit of measurement of the sensor, if any. The `unit_of_measurement` can be `null`.
Default: None
required: false
type: string
value_template:

39
source/_integrations/nut.markdown
View File

@ -17,9 +17,7 @@ ha_platforms:
ha_integration_type: device
---
The Network UPS Tools (NUT) integration allows you to monitor a UPS
(battery backup) by using data from a [NUT](https://networkupstools.org/)
server.
The Network UPS Tools (NUT) integration allows you to monitor and manage a UPS (battery backup) using a [NUT] https://networkupstools.org/) server. It lets you view their status, receives notifications about important events, and execute commands as device actions.
{% include integrations/config_flow.md %}
@ -72,3 +70,38 @@ values with `ups`, `battery`, `input` and `output` prefixes.
An additional virtual sensor type `ups.status.display` is available
translating the UPS status value retrieved from `ups.status` into a
human-readable version.
## Device Actions
A device action is available for each parameterless NUT [command](https://networkupstools.org/docs/user-manual.chunked/apcs03.html) supported by the device. To find the list of supported commands for
your specific UPS device, you can use the `upscmd -l` command followed by the UPS name:
```bash
$ upscmd -l my_ups
Instant commands supported on UPS [my_ups]:
beeper.disable - Disable the UPS beeper
beeper.enable - Enable the UPS beeper
test.battery.start.quick - Start a quick battery test
test.battery.stop - Stop the battery test
```
These commands will be available as device actions in Home Assistant, allowing you to interact with your UPS.
### User Credentials and Permissions
To execute device actions through the NUT integration, you must specify user credentials in the configuration. These credentials are stored in the `upsd.users` file, part of the NUT server configuration. This file defines the usernames, passwords, and permissions for users accessing the UPS devices.
No actions will be available if no user credentials are specified for a given device.
Ensure the user you specify has the required permissions to execute the desired commands. Here's an example of a user with command permissions in the `upsd.users` file:
```text
[my_user]
password = my_password
actions = SET
instcmds = ALL
```
In this example, the user `my_user` has permission to execute all commands (`instcmds = ALL`).
Please note that Home Assistant cannot determine whether a user can access a specific action without executing it. If you attempt to perform an action for which the user does not have permission, an exception will be thrown at runtime.

1
source/_integrations/obihai.markdown
View File

@ -14,6 +14,7 @@ ha_platforms:
- button
- sensor
ha_integration_type: integration
ha_dhcp: true
---
The `obihai` integration allows you to view the call status for your [Obihai devices](https://www.obitalk.com/info/products#home_section).

15
source/_integrations/pi_hole.markdown
View File

@ -22,10 +22,23 @@ ha_integration_type: integration
---
The Pi-hole integration allows you to retrieve statistics and interact with a
[Pi-hole](https://pi-hole.net/) system. If your Pi-hole web interface is password protected, an API key is needed for the setup (_from Settings -> API / Web interface_).
[Pi-hole](https://pi-hole.net/) system.
{% include integrations/config_flow.md %}
During the setup, it will ask for the following:
| Item | Description | Example |
| ---- | ----------- | ------- |
| `Host` | The IP or domain name to Pi-Hole | 192.168.1.1 |
| `Port` | Port used to get to the admin page | 80 |
| `Name` | Name to for this Pi-Hole. | Pi-Hole |
| `Location` | the path to the admin page. | /admin |
The combined host, port and location should take you to the login page of Pi-Hole. Using the example above, it would be `http://192.168.1.1:80/admin`.
If your Pi-hole web interface is password protected, an API key will be requested by Home Assistant after submitting the initial details above. You can get the API key by logging into your Pi-Hole and going to _from Settings > API_ and then the **Show API token** button.
## Services
The platform provides the following services to interact with your Pi-hole. Use switch entities when calling the services.

2
source/_integrations/python_script.markdown
View File

@ -23,7 +23,7 @@ This integration allows you to write Python scripts that are exposed as services
Other imports like `min`, `max` are available as builtins. See the [python_script](https://github.com/home-assistant/core/blob/dev/homeassistant/components/python_script/__init__.py) source code for up-to-date information on the available objects inside the script.
[hass-api]: /developers/development_hass_object/
[hass-api]: https://developers.home-assistant.io/docs/dev_101_hass/
[logger-api]: https://docs.python.org/3.7/library/logging.html#logger-objects
<div class='note'>

26
source/_integrations/rapt_ble.markdown Normal file
View File

@ -0,0 +1,26 @@
---
title: RAPT Bluetooth
description: Instructions on how to integrate RAPT Pill Hydrometers configured in Bluetooth mode into Home Assistant.
ha_category:
- Sensor
ha_bluetooth: true
ha_release: 2023.5
ha_iot_class: Local Push
ha_codeowners:
- '@sairon'
ha_domain: rapt_ble
ha_config_flow: true
ha_platforms:
- sensor
ha_integration_type: integration
---
Integrates [RAPT Pill](https://www.kegland.com.au/rapt-pill-hydrometer-thermometer-wifi-bluetooth.html) hydrometers into Home Assistant.
{% include integrations/config_flow.md %}
The RAPT Pill BLE integration will automatically discover devices once the [Bluetooth](/integrations/bluetooth) integration is enabled and functional. RAPT Pill must be switched to the Bluetooth mode in Settings - Telemetry method. See the [user manual](https://cdn.shopify.com/s/files/1/0667/3019/7248/files/KL20596_-_RAPT_Pill_Hydrometer_and_Thermometer_Quick_Start_Guide.pdf) for detailed instructions.
## Supported devices
- [RAPT Pill Hydrometer & Thermometer](https://www.kegland.com.au/rapt-pill-hydrometer-thermometer-wifi-bluetooth.html)

5
source/_integrations/reolink.markdown
View File

@ -111,6 +111,7 @@ Depending on the supported features of the camera, select entities are added for
- PTZ preset
- Auto quick reply message
- Auto track method (Digital, Digital first, Pan/Tilt first)
- Status LED (Doorbell only: Stay off, Auto, Auto & always on at night)
PTZ preset positions can be set in the Reolink app/windows/web client, the names of the presets will be loaded into Home Assistant at the start of the integration. When adding new preset positions, please restart the Reolink integration.
@ -132,6 +133,7 @@ Depending on the supported features of the camera, switch entities are added for
- Auto tracking
- Auto focus
- Guard return
- Doorbell button sound
Depending on the supported features of the NVR/host, global switch entities are added for:
@ -193,7 +195,8 @@ The following models have been tested and confirmed to work:
Battery-powered cameras are not yet supported.
The following models are lacking the HTTP webserver API and can therfore not work with this integration:
The following models are lacking the HTTP web server API and can, therefore, not work directly with this integration.
However, these cameras can work with this integration through an NVR in which the NVR is connected to Home Assistant.
- E1 Pro
- E1

5
source/_integrations/rest.markdown
View File

@ -132,6 +132,11 @@ verify_ssl:
required: false
type: boolean
default: True
ssl_cipher_list:
description: Define the list of SSL ciphers to be accepted from this endpoint. `python_default` (_default_), `modern` or `intermediate` (_inspired by [Mozilla Security/Server Side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS)_).
required: false
type: string
default: default
timeout:
description: Defines max time to wait data from the endpoint.
required: false

54
source/_integrations/roborock.markdown
View File

@ -1,43 +1,25 @@
---
title: Roborock
description: Connect and control your Roborock devices using the Xiaomi Miio integration
description: Instructions on how to integrate Roborock vacuums into Home Assistant
ha_category:
- Alarm
- Fan
- Health
- Hub
- Light
- Presence Detection
- Remote
- Vacuum
ha_domain: roborock
ha_integration_type: virtual
ha_supporting_domain: xiaomi_miio
ha_supporting_integration: Xiaomi Miio
ha_release: 0.51
ha_codeowners:
- '@rytilahti'
- '@syssi'
- '@starkillerOG'
ha_config_flow: true
ha_platforms:
- air_quality
- alarm_control_panel
- binary_sensor
- button
- device_tracker
- diagnostics
- fan
- humidifier
- light
- number
- remote
- select
- sensor
- switch
- vacuum
- Select
ha_iot_class: Local Polling
ha_zeroconf: true
ha_release: 2023.5
ha_config_flow: true
ha_codeowners:
- '@humbertogontijo'
- '@Lash-L'
ha_domain: roborock
ha_platforms:
- vacuum
ha_integration_type: integration
---
{% include integrations/supported_brand.md %}
The Roborock integration allows you to control your [Roborock](https://us.roborock.com/pages/robot-vacuum-cleaner) vacuum while continuing to use the Roborock app.
In contrast to [Xiaomi Miio](/integrations/xiaomi_miio/) integration, this integration provides more complete support but requires cloud access to set up and device configuration using the Roborock app.
Once you log in with your Roborock account, the integration will automatically discover your Roborock devices and get the needed information to communicate locally with them. Please ensure your Home Assistant instance can communicate with the local IP of your device. We recommend setting a static IP for your Roborock Vacuum to help prevent future issues.
{% include integrations/config_flow.md %}

6
source/_integrations/schedule.markdown
View File

@ -17,12 +17,12 @@ Home Assistant that can be used to trigger or make decisions in your
automations and scripts.
The preferred way to configure a schedule is via the user interface at
**Settings** -> **Devices & Services** -> **Helpers**. Click the add button
and then choose the **Schedule** option, or click the My button below.
**{% my helpers title="Settings > Devices & Services > Helpers." %}** Click the add button
and then choose the **{% my config_flow_start domain=schedule title="Schedule" %}** option, or click the My button below.
{% include integrations/config_flow.md %}
To be able to add **Helpers** via the user interface you should
To be able to add **{% my helpers title="Helpers" %}** via the user interface you should
have `default_config:` in your `configuration.yaml`, it should already
be there by default unless you removed it.

208
source/_integrations/sensor.command_line.markdown
View File

@ -1,208 +0,0 @@
---
title: "Command line Sensor"
description: "Instructions on how to integrate command line sensors into Home Assistant."
ha_category:
- Utility
- Sensor
ha_release: pre 0.7
ha_iot_class: Local Polling
ha_domain: command_line
---
The `command_line` sensor platform simply issues specific commands to get its data. This makes it a very powerful platform as it allows anyone to integrate any type of sensor into Home Assistant that can get data from the command line.
## Configuration
To enable it, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
command: SENSOR_COMMAND
```
{% configuration %}
command:
description: The action to take to get the value.
required: true
type: string
name:
description: Name of the command sensor.
required: false
type: string
unit_of_measurement:
description: Defines the unit of measurement of the sensor, if any.
required: false
type: string
value_template:
description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload."
required: false
type: string
scan_interval:
description: Defines number of seconds for polling interval.
required: false
type: integer
default: 60
command_timeout:
description: Defines number of seconds for command timeout
required: false
type: integer
default: 15
json_attributes:
description: Defines a list of keys to extract values from a JSON dictionary result and then set as sensor attributes.
required: false
type: [string, list]
unique_id:
description: An ID that uniquely identifies this sensor. Set this to a unique value to allow customization through the UI.
required: false
type: string
{% endconfiguration %}
## Execution
The `command` is executed within the [configuration directory](/docs/configuration/).
<div class='note'>
If you are using [Home Assistant Operating System](https://github.com/home-assistant/operating-system), the commands are executed in the `homeassistant` container context. So if you test or debug your script, it might make sense to do this in the context of this container to get the same runtime environment.
</div>
With a `0` exit code, the output (stdout) of the command is used as `value`. In case a command results in a non `0` exit code or is terminated by the `command_timeout`, the result is only logged to Home Assistant log and the value of the sensor is not updated.
## Examples
In this section you find some real-life examples of how to use this sensor.
### CPU temperature
Thanks to the [`proc`](https://en.wikipedia.org/wiki/Procfs) file system, various details about a system can be retrieved. Here the CPU temperature is of interest. Add something similar to your `configuration.yaml` file:
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: CPU Temperature
command: "cat /sys/class/thermal/thermal_zone0/temp"
# If errors occur, make sure configuration file is encoded as UTF-8
unit_of_measurement: "°C"
value_template: "{{ value | multiply(0.001) | round(1) }}"
```
{% endraw %}
### Monitoring failed login attempts on Home Assistant
If you'd like to know how many failed login attempts are made to Home Assistant, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: badlogin
command: "grep -c 'Login attempt' /home/hass/.homeassistant/home-assistant.log"
```
Make sure to configure the [Logger integration](/integrations/logger) to monitor the [HTTP integration](/integrations/http/) at least the `warning` level.
```yaml
# Example working logger settings that works
logger:
default: critical
logs:
homeassistant.components.http: warning
```
### Details about the upstream Home Assistant release
You can see directly in the frontend (**Developer tools** -> **About**) what release of Home Assistant you are running. The Home Assistant releases are available on the [Python Package Index](https://pypi.python.org/pypi). This makes it possible to get the current release.
```yaml
sensor:
- platform: command_line
command: python3 -c "import requests; print(requests.get('https://pypi.python.org/pypi/homeassistant/json').json()['info']['version'])"
name: HA release
```
### Read value out of a remote text file
If you own devices which are storing values in text files which are accessible over HTTP then you can use the same approach as shown in the previous section. Instead of looking at the JSON response we directly grab the sensor's value.
```yaml
sensor:
- platform: command_line
command: python3 -c "import requests; print(requests.get('http://remote-host/sensor_data.txt').text)"
name: File value
```
### Use an external script
The example is doing the same as the [aREST sensor](/integrations/arest#sensor) but with an external Python script. It should give you an idea about interfacing with devices which are exposing a RESTful API.
The one-line script to retrieve a value is shown below. Of course it would be possible to use this directly in the `configuration.yaml` file but need extra care about the quotation marks.
```bash
python3 -c "import requests; print(requests.get('http://10.0.0.48/analog/2').json()['return_value'])"
```
The script (saved as `arest-value.py`) that is used looks like the example below.
```python
#!/usr/bin/python3
from requests import get
response = get("http://10.0.0.48/analog/2")
print(response.json()["return_value"])
```
To use the script you need to add something like the following to your `configuration.yaml` file.
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: Brightness
command: "python3 /path/to/script/arest-value.py"
```
### Usage of templating in `command:`
[Templates](/docs/configuration/templating/) are supported in the `command` configuration variable. This could be used if you want to include the state of a specific sensor as an argument to your external script.
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: wind direction
command: "sh /home/pi/.homeassistant/scripts/wind_direction.sh {{ states('sensor.wind_direction') }}"
unit_of_measurement: "Direction"
```
{% endraw %}
### Usage of JSON attributes in command output
The example shows how you can retrieve multiple values with one sensor (where the additional values are attributes) by using `value_json` and `json_attributes`.
{% raw %}
```yaml
# Example configuration.yaml entry
sensor:
- platform: command_line
name: JSON time
json_attributes:
- date
- milliseconds_since_epoch
command: "python3 /home/pi/.homeassistant/scripts/datetime.py"
value_template: "{{ value_json.time }}"
```
{% endraw %}

11
source/_integrations/sensor.mqtt.markdown
View File

@ -106,7 +106,8 @@ device:
required: false
type: string
device_class:
description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend.
description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend. The `device_class` can be `null`.
default: None
required: false
type: device_class
default: None
@ -150,7 +151,7 @@ json_attributes_topic:
last_reset_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract the last_reset. Available variables: `entity_id`. The `entity_id` can be used to reference the entity's attributes."
required: false
type: string
type: template
name:
description: The name of the MQTT sensor.
required: false
@ -185,7 +186,8 @@ state_class:
type: string
default: None
state_topic:
description: The MQTT topic subscribed to receive sensor values. If `device_class`, `state_class`, `unit_of_measurement` or `suggested_display_precision` is set, and a numeric value is expected, an empty value `''` will be ignored and will not update the state, a `'None'` value will set the sensor to an `unknown` state.
description: The MQTT topic subscribed to receive sensor values. If `device_class`, `state_class`, `unit_of_measurement` or `suggested_display_precision` is set, and a numeric value is expected, an empty value `''` will be ignored and will not update the state, a `'null'` value will set the sensor to an `unknown` state. The `device_class` can be `null`.
default: None
required: true
type: string
unique_id:
@ -193,7 +195,8 @@ unique_id:
required: false
type: string
unit_of_measurement:
description: Defines the units of measurement of the sensor, if any.
description: Defines the units of measurement of the sensor, if any. The `unit_of_measurement` can be `null`.
default: None
required: false
type: string
value_template:

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

@ -216,7 +216,7 @@ state_topic:
state_value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract device's state from the `state_topic`. To determine the siren's state result of this template will be compared to `state_on` and `state_off`. Alternatively `value_template` can be used to render to a valid JSON payload."
required: false
type: string
type: template
support_duration:
description: Set to `true` if the MQTT siren supports the `duration` service turn on parameter and enables the `duration` state attribute.
required: false

4
source/_integrations/smtp.markdown
View File

@ -205,6 +205,6 @@ notify:
sender_name: "SENDER_NAME"
```
Keep in mind that Google has some extra layers of protection that need special attention. By default, the usage by external applications is limited so you will need to visit the [less secure apps](https://www.google.com/settings/security/lesssecureapps) page and enable it to be able to send e-mails. Be aware that Google will periodically turn it off if it is not used (no e-mail is sent).
Keep in mind that Google has some extra layers of protection that need special attention. By default, the usage by external applications is limited so you will need to visit the [less secure apps](https://myaccount.google.com/lesssecureapps) page and enable it to be able to send e-mails. Be aware that Google will periodically turn it off if it is not used (no e-mail is sent).
To avoid having your e-mail notifications broken due to the less secure app's behavior, it is recommended that you enable 2-step verification on your Google account, and use [an application-specific password](https://support.google.com/mail/answer/185833?hl=en) in your notification configuration.
To avoid having your e-mail notifications broken due to the less secure app's behavior, it is recommended that you enable 2-step verification on your Google account, and use [an application-specific password](https://support.google.com/mail/answer/185833) in your notification configuration.

7
source/_integrations/sonos.markdown
View File

@ -117,19 +117,24 @@ Sonos accepts a variety of `media_content_id` formats in the `media_player.play_
Music services which require an account (e.g., Spotify) must first be configured using the Sonos app.
Playing TTS (text to speech) or audio files as alerts (e.g., a doorbell or alarm) is possible by setting the `announce` argument to `true`. Using `announce` will play the provided media URL as an overlay, gently lowering the current music volume and automatically restoring to the original level when finished. An optional `volume` argument can also be provided in the `extra` dictionary to play the alert at a specific volume level. Note that older Sonos hardware or legacy firmware versions ("S1") may not fully support these features.
An optional `enqueue` argument can be added to the service call. If `true`, the media will be appended to the end of the playback queue. If not provided or `false` then the queue will be replaced.
### Examples:
This is an example service call that plays an audio file from a web server on the local network (like the Home Assistant built-in webserver):
Below is an example service call that plays an audio file from a web server on the local network (like the Home Assistant built-in webserver) using the `announce` feature and its associated (optional) `volume` parameter:
```yaml
service: media_player.play_media
target:
entity_id: media_player.sonos
data:
announce: true
media_content_type: "music"
media_content_id: "http://192.168.1.50:8123/local/sound_files/doorbell-front.mp3"
extra:
volume: 20
```
Sonos can also play music or playlists from Spotify. Both Spotify URIs and URLs can be used directly. An example service call using a playlist URI:

11
source/_integrations/starlink.markdown
View File

@ -32,20 +32,23 @@ The Starlink integration allows you to integrate your [Starlink](https://www.sta
### Sensor
- Ping - The ping that Starlink has measured, in ms
- Ping drop rate - The percentage of failed ping requests (aka "dropped"). This is the inverse of "Uptime" in the Starlink app.
- Azimuth - The direction Dishy is facing in degrees
- Elevation - Dishy's current elevation in degrees
- Uplink throughput - The amount of data being uploaded through Starlink in Bit/s
- Downlink throughput - The amount of data being downloaded through Starlink in Bit/s
- Uplink throughput - The amount of data being uploaded through Starlink
- Downlink throughput - The amount of data being downloaded through Starlink
- Last boot time - The time Starlink was last turned on
### Binary Sensor
- Update available - Whether there is an update pending install
- Obstructed - Whether Dishy is currently obstructed
- Roaming - Whether Starlink is "roaming". Roaming is an optional upgrade that allows you to use your Starlink outside of your home address. It is also known as "portability"
- Roaming mode - Whether Starlink is "roaming". Roaming is an optional upgrade that allows you to use your Starlink outside of your home address. It is also known as "portability mode"
- Heating - Whether Dishy is currently heating. This may be due to cold temperatures, or an attempt to thaw snow and ice
- Idle - Whether Starlink is in an "idle" state to save power
- Idle - Whether Starlink is "sleeping", as per the schedule defined in the Starlink app
- Mast near vertical - Whether Dishy is mounted straight
- Motors stuck - Whether Dishy is unable to move
- Slow ethernet - Whether the Ethernet link is at max (gigabit) speed
- Thermal throttle - Whether Starlink has reduced performance to avoid overheating
- Unexpected location - Whether Starlink has detected operation outside of its designated area

6
source/_integrations/statistics.markdown
View File

@ -119,7 +119,7 @@ sensor:
{% configuration %}
entity_id:
description: The source sensor to observe and compute statistical characteristics for. Only [sensors](/integrations/sensor/) and [binary sensor](/integrations/binary_sensor/) are supported.
description: The source sensor to observe and compute statistical characteristics for. Only [sensors](/integrations/sensor/) and [binary sensors](/integrations/binary_sensor/) are supported.
required: true
type: string
name:
@ -157,4 +157,6 @@ unique_id:
### An important note on `max_age` and `sampling_size`
The `max_age` option is only valid within the measured samples specified by `sampling_size` (default 20). Specify a wide-enough `sampling_size` if using an extended max-age (e.g., when looking for `max_age` 1 hour, a sensor that produces one measurement a minute should have at least a `sampling_size` of 60.
If both `max_age` and `sampling_size` are given, the considered samples are those within the `max_age` time window but limited to the number of `sample_size` newest samples. Specify a wide-enough `sampling_size` if using an extended `max_age` (e.g., when looking for `max_age` 1 hour, a sensor that produces one measurement per minute should have at least a `sampling_size` of 60 to use all samples within the `max_age` timeframe.)
If only `sample_size` is given there is no time limit. If only `max_age` is given the considered number of samples is unlimited.

10
source/_integrations/stt.markdown
View File

@ -3,6 +3,7 @@ title: Speech-to-Text (STT)
description: Instructions on how to set up Speech-to-Text (STT) with Home Assistant.
ha_release: '0.102'
ha_codeowners:
- '@home-assistant/core'
- '@pvizeli'
ha_domain: stt
ha_quality_scale: internal
@ -10,6 +11,11 @@ ha_category: []
ha_integration_type: entity
---
Speech-to-Text (STT) allows you to stream speech data to the STT API and get text back.
A speech to text (STT) entity allows other integrations or applications to stream speech data to the STT API and get text back.
This is an integration that is a building block for other integrations or apps building on top of Home Assistant, like [Ada](https://github.com/home-assistant/ada).
The speech to text entities cannot be implemented manually, but can be provided by integrations.
## The state of a speech to text entity
Every speech to text entity keeps track of the timestamp of when the last time
the speech to text entity was used to process speech.

22
source/_integrations/sun.markdown
View File

@ -51,23 +51,25 @@ sun:
<img src='/images/screenshots/more-info-dialog-sun.png' />
</p>
## Implementation Details
## Automation trigger
The sun's event listener will call the service when the sun rises or sets with
an offset.
The sun event need to have the type 'sun', which service to call,
which event (sunset or sunrise) and the offset.
The sun trigger need to have the type 'sun', which event (sunset or sunrise) and an optional offset.
```json
{
"type": "sun",
"service": "switch.turn_on",
"event": "sunset",
"offset": "-01:00:00"
}
```yaml
trigger:
- platform: sun
event: sunrise
offset: "-01:00:01"
```
| Key name | Description |
| --------- | ----------- |
| `event` | Possible values: `sunset` or `sunrise`
| `offset` | An optional offset for the sun event trigger, in a positive or negative number of seconds, or specified in `HH:MM:SS` (after sun event trigger) or `-HH:MM:SS` (before sun event trigger).
### Maintains entity `sun.sun`
| Possible state | Description |

205
source/_integrations/switch.command_line.markdown
View File

@ -1,205 +0,0 @@
---
title: "Command line Switch"
description: "Instructions on how to have switches call command line commands."
ha_category:
- Switch
ha_release: pre 0.7
ha_iot_class: Local Polling
ha_domain: command_line
---
The `command_line` switch platform issues specific commands when it is turned on
and off. This might very well become our most powerful platform as it allows
anyone to integrate any type of switch into Home Assistant that can be
controlled from the command line, including calling other scripts!
To enable it, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
kitchen_light:
command_on: switch_command on kitchen
command_off: switch_command off kitchen
```
{% configuration %}
switches:
description: The array that contains all command switches.
required: true
type: map
keys:
identifier:
description: Name of the command switch as slug. Multiple entries are possible.
required: true
type: map
keys:
command_on:
description: The action to take for on.
required: true
type: string
command_off:
description: The action to take for off.
required: true
type: string
command_state:
description: "If given, this command will be run. Returning a result code `0` will indicate that the switch is on."
required: false
type: string
value_template:
description: "If specified, `command_state` will ignore the result code of the command but the template evaluating to `true` will indicate the switch is on."
required: false
type: string
friendly_name:
description: The name used to display the switch in the frontend.
required: false
type: string
icon_template:
description: Defines a template for the icon of the entity.
required: false
type: template
command_timeout:
description: Defines number of seconds for command timeout.
required: false
type: integer
default: 15
unique_id:
description: An ID that uniquely identifies this switch. Set this to a unique value to allow customization through the UI.
required: false
type: string
{% endconfiguration %}
A note on `friendly_name`:
When set, the `friendly_name` had been previously used for API calls and backend
configuration instead of the `object_id` ("identifier"), but
[this behavior is changing](https://github.com/home-assistant/home-assistant/pull/4343)
to make the `friendly_name` for display purposes only. This allows users to set
an `identifier` that emphasizes uniqueness and predictability for API and configuration
purposes but have a prettier `friendly_name` still show up in the UI. As an
additional benefit, if a user wanted to change the `friendly_name` / display
name (e.g., from "Kitchen Lightswitch" to "Kitchen Switch" or
"Living Room Light", or remove the `friendly_name` altogether), they could
do so without needing to change existing automations or API calls.
See aREST device below for an example.
## Examples
In this section you find some real-life examples of how to use this switch.
### Change the icon when a state changes
This example demonstrates how to use template to change the icon as its state changes. This icon is referencing its own state.
{% raw %}
```yaml
switch:
- platform: command_line
switches:
driveway_sensor_motion:
friendly_name: Driveway buiten sensor
command_on: >
curl -X PUT -d '{"on":true}' "http://ip_address/api/sensors/27/config/"
command_off: >
curl -X PUT -d '{"on":false}' "http://ip_address/api/sensors/27/config/"
command_state: curl http://ip_address/api/sensors/27/
value_template: >
{{value_json.config.on}}
icon_template: >
{% if value_json.config.on == true %} mdi:toggle-switch
{% else %} mdi:toggle-switch-off
{% endif %}
```
{% endraw %}
### aREST device
The example below is doing the same as the
[aREST switch](/integrations/arest#switch).
The command line tool [`curl`](https://curl.haxx.se/) is used to toggle a pin
which is controllable through REST.
{% raw %}
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
arest_pin_four:
command_on: "/usr/bin/curl -X GET http://192.168.1.10/digital/4/1"
command_off: "/usr/bin/curl -X GET http://192.168.1.10/digital/4/0"
command_state: "/usr/bin/curl -X GET http://192.168.1.10/digital/4"
value_template: '{{ value == "1" }}'
friendly_name: Kitchen Lightswitch
```
{% endraw %}
Given this example, in the UI one would see the `friendly_name` of
"Kitchen Light". However, the `identifier` is `arest_pin_four`, making the
`entity_id` `switch.arest_pin_four`, which is what one would use in
[`automation`](/integrations/automation/) or in [API calls](/developers/).
### Shutdown your local host
This switch will shutdown your system that is hosting Home Assistant.
<div class='note warning'>
This switch will shutdown your host immediately, there will be no confirmation.
</div>
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
home_assistant_system_shutdown:
command_off: "/usr/sbin/poweroff"
```
### Control your VLC player
This switch will control a local VLC media player
([Source](https://community.home-assistant.io/t/vlc-player/106)).
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
vlc:
command_on: "cvlc 1.mp3 vlc://quit &"
command_off: "pkill vlc"
```
### Control Foscam Motion Sensor
This switch will control the motion sensor of Foscam Webcams which Support CGI
Commands ([Source](https://www.iltucci.com/blog/wp-content/uploads/2018/12/Foscam-IPCamera-CGI-User-Guide-V1.0.4.pdf)).
This switch supports statecmd,
which checks the current state of motion detection.
{% raw %}
```yaml
# Example configuration.yaml entry
switch:
- platform: command_line
switches:
foscam_motion:
command_on: 'curl -k "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=1&usr=admin&pwd=password"'
command_off: 'curl -k "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=setMotionDetectConfig&isEnable=0&usr=admin&pwd=password"'
command_state: 'curl -k --silent "https://ipaddress:443/cgi-bin/CGIProxy.fcgi?cmd=getMotionDetectConfig&usr=admin&pwd=password" | grep -oP "(?<=isEnable>).*?(?=</isEnable>)"'
value_template: '{{ value == "1" }}'
```
{% endraw %}
- Replace admin and password with an "Admin" privileged Foscam user
- Replace ipaddress with the local IP address of your Foscam

4
source/_integrations/switch.mqtt.markdown
View File

@ -116,7 +116,7 @@ device:
required: false
type: string
device_class:
description: The [type/class](/integrations/switch/#device-class) of the switch to set the icon in the frontend.
description: The [type/class](/integrations/switch/#device-class) of the switch to set the icon in the frontend. The `device_class` can be `null`.
required: false
type: device_class
default: None
@ -212,7 +212,7 @@ unique_id:
value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) to extract device's state from the `state_topic`. To determine the switches's state result of this template will be compared to `state_on` and `state_off`."
required: false
type: string
type: template
{% endconfiguration %}
<div class='note warning'>

14
source/_integrations/synology_dsm.markdown
View File

@ -5,6 +5,7 @@ ha_category:
- Camera
- System Monitor
- Update
- Media Source
ha_release: 0.32
ha_iot_class: Local Polling
ha_domain: synology_dsm
@ -22,6 +23,7 @@ ha_platforms:
- sensor
- switch
- update
- media_source
ha_integration_type: integration
ha_zeroconf: true
---
@ -126,3 +128,15 @@ Reboot the NAS.
### Button `shutdown`
Shutdown the NAS.
## Media Source
A media source is provided for your [Synology Photos](https://www.synology.com/en-global/dsm/feature/photos).
The media source URIs will look like `media-source://synology_dsm/<unique_id>/<album_id>/<image>`.
This media browser supports multiple Synology Photos instances. `<unique_id>` is the Home Assistant ID for the NAS (_usually the serial number of the NAS_). You can find this id when using the media browser, when you hover over the NAS name, you get shown the simple name followed by the unique id ex: `192.168.0.100:5001 - 18C0PEN253705`.
To find the `<album_id>` you need to go to the album in your photos instance, and the id will be in the URL ex: `https://192.168.0.100:5001/#/album/19`, where 19 is the album id. An `<album_id>` of 0 will contain all images.
For performance reasons, a maximum of 1000 images will be shown in the Media Browser.

2
source/_integrations/system_log.markdown
View File

@ -72,7 +72,7 @@ Traceback (most recent call last):
[...]
```
The message ("Unable to find integration system_healt"), name (`homeassistant.loader`) and level (`ERROR`) can easily be extracted from the log. The exact timestamp and if there is a stack trace that's shown as well. Here is another error caused by the `google_map` integration with additional output present.
The message ("Unable to find integration system_healt"), name (`homeassistant.loader`) and level (`ERROR`) can easily be extracted from the log. The exact timestamp and if there is a stack trace that's shown as well.
## Examples

2
source/_integrations/tado.markdown
View File

@ -134,7 +134,7 @@ You can use the service `tado.set_water_heater_timer` to set your water heater t
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------------------------- |
| `entity_id` | yes | String, Name of entity e.g., `climate.heating` |
| `entity_id` | yes | String, Name of entity e.g., `water_heater.hot_water` |
| `time_period` | no | Time Period, Period of time the boost should last for e.g., `01:30:00` |
| `temperature` | yes | String, The required target temperature e.g., `20.5` |

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

@ -23,7 +23,7 @@ topic:
value_template:
description: "Defines a [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) that returns a tag ID."
required: false
type: string
type: template
device:
description: "Information about the device this device trigger is a part of to tie it into the [device registry](https://developers.home-assistant.io/docs/en/device_registry_index.html). At least one of identifiers or connections must be present to identify the device."
required: true

8
source/_integrations/tellduslive.markdown
View File

@ -24,7 +24,13 @@ ha_platforms:
ha_integration_type: integration
---
The `tellduslive` integration let you connect to [Telldus Live](https://live.telldus.com). It's cloud platform that connects to your Tellstick Net or Tellstick ZNet connected gear at home.
The `tellduslive` integration let you connect to the [Telldus Live](https://live.telldus.com) API. It's cloud platform that connects to your Tellstick Net or Tellstick ZNet connected gear at home.
<div class='note'>
Note that you need a [Telldus Premium](https://telldus.com/en/telldus-premium/) subscription to access the Cloud API (https://telldus.com/en/important-announcement-english/).
</div>
Local API supports only one device at this stage. Local API is only supported with the Znet Lite products, the older hardware (such as Tellstick Net) does not support local API.

2
source/_integrations/thethingsnetwork.markdown
View File

@ -15,7 +15,7 @@ ha_integration_type: integration
---
<div class='note warning'>
This integration only supports TTNv2.
This integration only supports TTNv2 that has been definitively switched off in 2022 (deprecated).
</div>
The `thethingsnetwork` integration allows one to interact with the [The Things Network](https://www.thethingsnetwork.org). This community-driven and open network supports [LoRaWAN](https://www.lora-alliance.org/) for long range (~5 to 15 km) communication with a low bandwidth (51 bytes/message). [Gateways](https://www.thethingsnetwork.org/docs/gateways/) transfers the received data from the sensors to the The Things Network.

2
source/_integrations/timer.markdown
View File

@ -23,7 +23,7 @@ However, automations using the `timer.finished` event **will not** trigger if th
</div>
## Configuration
The preferred way to configure timer helpers is via the user interface at **Settings** -> **Devices & Services** -> **Helpers** and click the add button; next choose the **Timer** option.
The preferred way to configure timer helpers is via the user interface at **{% my helpers title="Settings > Devices & Services > Helpers" %}** and click the add button; next choose the {% my config_flow_start domain=timer title="Timer" %} option.
You can also click the following button to be redirected to the Helpers page of your Home Assistant instance.

2
source/_integrations/torque.markdown
View File

@ -29,7 +29,7 @@ Under the **Logging Preferences** header:
Under the **Realtime Web Upload** header:
- Check **Upload to web-server**.
- Enter `https://HOST/api/torque` or `https://@/HOST:PORT/api/torque` as the **Web-server URL**, where `HOST` and `PORT` are your externally accessible Home Assistant HTTP host. To use a Bearer Token, this has to be [SSL/TSL](/docs/ecosystem/certificates/).
- Enter `https://HOST/api/torque` or `https://@/HOST:PORT/api/torque` as the **Web-server URL**, where `HOST` and `PORT` are your externally accessible Home Assistant HTTP host. To use a Bearer Token, this has to be [SSL/TLS](/docs/ecosystem/certificates/).
- Enable **Send https: Bearer Token** (available since Torque Pro 1.12.46)
- Paste a Long-Lived Access Token from any Home Assistant user in **Set Bearer Token** field.
- Enter an email address in **User Email Address** (this can be any non empty string you like).

2
source/_integrations/tplink_omada.markdown
View File

@ -38,7 +38,7 @@ TP-Link Omada Controller:
- OC300
- Software Controller.
Controller versions 5.0.0 and later are supported.
Controller versions 5.1.0 and later are supported.
## Supported Omada devices

4
source/_integrations/traccar.markdown
View File

@ -80,7 +80,7 @@ monitored_conditions:
required: false
type: list
event:
description: "Traccar events to include in the scan and fire within Home Assistant. *NOTE* For more info regarding Traccar events please refer to Traccar's documentation: https://www.traccar.org/documentation/events/."
description: "Traccar events to include in the scan and fire within Home Assistant. *NOTE* For more info regarding Traccar events please refer to [Traccar's documentation](https://www.traccar.org/events/)."
required: false
type: list
keys:
@ -163,7 +163,7 @@ device_tracker:
monitored_conditions: ['alarm', 'mycomputedattribute']
```
The parameter `event` allows you to import events from the traccar platform (https://www.traccar.org/documentation/events/) and fire them in your Home Assistant. It accepts a list of events to be monitored and imported and each event must be listed in lowercase snakecase. The events will be fired with the same event name defined in the aforementioned list preceded by the prefix `traccar_`. For example if you need to import the Traccar events `deviceOverspeed` and `deviceFuelDrop` in Home Assistant, you need to fill the `event` parameter with:
The parameter `event` allows you to import [events](https://www.traccar.org/events/) from the traccar platform and fire them in your Home Assistant. It accepts a list of events to be monitored and imported and each event must be listed in lowercase snakecase. The events will be fired with the same event name defined in the aforementioned list preceded by the prefix `traccar_`. For example if you need to import the Traccar events `deviceOverspeed` and `deviceFuelDrop` in Home Assistant, you need to fill the `event` parameter with:
```yaml
device_tracker:

127
source/_integrations/tts.markdown
View File

@ -6,6 +6,7 @@ ha_category:
- Text-to-speech
ha_release: 0.35
ha_codeowners:
- '@home-assistant/core'
- '@pvizeli'
ha_domain: tts
ha_quality_scale: internal
@ -16,83 +17,27 @@ ha_integration_type: entity
Text-to-Speech (TTS) enables Home Assistant to speak to you.
## Configuring a `tts` platform
## Services
To get started, add the following lines to your `configuration.yaml` (example for Google):
### Service speak
Modern platforms will create entities under the `tts` domain, where each entity represents one text-to-speech service provider. These entities may be used as targets for the `tts.speak` service.
The `tts.speak` service supports `language` and on some platforms also `options` for settings, e.g., *voice, motion, speed, etc*. The text that should be spoken is set with `message`, and the media player that should output the sound is selected with `media_player_entity_id`.
```yaml
# Example configuration.yaml entry for Google TTS service
tts:
- platform: google_translate
service: tts.speak
target: tts.example
data:
media_player_entity_id: media_player.kitchen
message: "May the force be with you."
```
<div class='note'>
### Service say (legacy)
Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/docs/configuration/basic/) or in the parameters of this component.
The `say` service supports `language` and on some platforms also `options` for settings, e.g., *voice, motion, speed, etc*. The text that should be spoken is set with `message`. Since release 0.92, service name can be defined in configuration `service_name` option.
</div>
The following optional parameters can be used with any platform. However, the TTS integration will only look for global settings under the configuration of the first configured platform:
{% configuration %}
cache:
description: Allow TTS to cache voice file to local storage.
required: false
type: boolean
default: true
cache_dir:
description: Folder name or path to a folder for caching files.
required: false
type: string
default: tts
time_memory:
description: Time to hold the voice data inside memory for fast play on a media player. Minimum is 60 s and the maximum 57600 s (16 hours).
required: false
type: integer
default: 300
service_name:
description: Define the service name.
required: false
type: string
default: The service name default set to <platform>_say. For example, for google_translate TTS, its service name default is `google_translate_say`.
{% endconfiguration %}
The extended example from above would look like the following sample:
```yaml
# Example configuration.yaml entry for Google Translate TTS service
tts:
- platform: google_translate
cache: true
cache_dir: /tmp/tts
time_memory: 300
service_name: google_say
```
The following sections describe some of the problems encountered with media devices.
### Self-signed certificates
This problem occurs when your Home Assistant instance is configured to be accessed through SSL, and you are using a self-signed certificate on your internal URL.
The `tts` service will send an `https://` URL to the media device, which will check the certificate, and reject it. So it won't play your file. If you could make the device accept your certificate, it would play the file. However, many media devices do not allow changing settings to accept self-signed certificates. Ultimately, your option may be to serve files to local devices as `http://` rather than `https://`.
### Google cast devices
The Google cast devices (Google Home, Chromecast, etc.) present the following problems:
* They [reject self-signed certificates](#self-signed-certificates).
* They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). If you are _not_ using SSL then setting an internal URL that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
* If you are using an SSL (e.g., `https://yourhost.example.org/...`) then you _must_ use the hostname in the certificate (e.g., `external_url: https://yourhost.example.org`). You cannot use an IP address since the certificate won't be valid for the IP address, and the cast device will refuse the connection.
## Service say
The `say` service support `language` and on some platforms also `options` for set, i.e., *voice, motion, speed, etc*. The text for speech is set with `message`. Since release 0.92, service name can be defined in configuration `service_name` option.
Say to all `media_player` device entities:
Say to all `media_player` entities:
```yaml
# Replace google_translate_say with <platform>_say when you use a different platform.
@ -102,7 +47,7 @@ data:
message: "May the force be with you."
```
Say to the `media_player.floor` device entity:
Say to the `media_player.floor` entity:
```yaml
service: tts.google_translate_say
@ -111,7 +56,7 @@ data:
message: "May the force be with you."
```
Say to the `media_player.floor` device entity in French:
Say to the `media_player.floor` entity in French:
```yaml
service: tts.google_translate_say
@ -136,17 +81,17 @@ data:
## Cache
The integration has two caches. Both caches can be controlled with the `cache` option in the platform configuration or the service call `say`. A long time cache will be located on the file system. The in-memory cache for fast responses to media players will be auto-cleaned after a short period.
The integration cache can be controlled with the `cache` option in the service call to `speak` or `say`. A long time cache will be located on the file system. The in-memory cache for fast responses to media players will be auto-cleaned after a short period.
## REST API
### POST `/api/tts_get_url`
Returns a URL to the generated TTS file. Platform and message are required.
Returns a URL to the generated TTS file. The `engine_id` or `platform` parameter together with `message` are required.
```json
{
"platform": "amazon_polly",
"engine_id": "tts.amazon_polly",
"message": "I am speaking now"
}
```
@ -155,8 +100,8 @@ The return code is 200 if the file is generated. The message body will contain a
```json
{
"path": "/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_demo.mp3",
"url": "http://127.0.0.1:8123/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_demo.mp3"
"path": "/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_tts.demo.mp3",
"url": "http://127.0.0.1:8123/api/tts_proxy/265944c108cbb00b2a621be5930513e03a0bb2cd_en_-_tts.demo.mp3"
}
```
@ -165,6 +110,32 @@ Sample `curl` command:
```bash
$ curl -X POST -H "Authorization: Bearer <ACCESS TOKEN>" \
-H "Content-Type: application/json" \
-d '{"message": "I am speaking now", "platform": "amazon_polly"}' \
-d '{"message": "I am speaking now", "engine_id": "amazon_polly"}' \
http://localhost:8123/api/tts_get_url
```
## Troubleshooting
<div class='note'>
Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/docs/configuration/basic/).
</div>
The following sections describe some of the problems encountered with media devices.
### Self-signed certificates
This problem occurs when your Home Assistant instance is configured to be accessed through SSL, and you are using a self-signed certificate on your internal URL.
The `tts` service will send an `https://` URL to the media device, which will check the certificate, and reject it. So it won't play your file. If you could make the device accept your certificate, it would play the file. However, many media devices do not allow changing settings to accept self-signed certificates. Ultimately, your option may be to serve files to local devices as `http://` rather than `https://`.
### Google cast devices
The Google cast devices (Google Home, Chromecast, etc.) present the following problems:
* They [reject self-signed certificates](#self-signed-certificates).
* They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). If you are _not_ using SSL then setting an internal URL that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
* If you are using SSL (e.g., `https://yourhost.example.org/...`) then you _must_ use the hostname in the certificate (e.g., `external_url: https://yourhost.example.org`). You cannot use an IP address since the certificate won't be valid for the IP address, and the cast device will refuse the connection.

30
source/_integrations/unifiprotect.markdown
View File

@ -50,15 +50,15 @@ The UniFi Protect integration adds support for retrieving Camera feeds and Senso
This Integration supports all UniFi OS Consoles that can run UniFi Protect. Currently, this includes:
* Any UniFi Protect Network Video Recorder (**UNVR** or **UNVRPRO**)
* Any UniFi "Dream" device (**UDMPRO**, **UDR**, or **UDMSE**), _except the base UniFi Dream Machine/UDM_
* UniFi Cloud Key Gen2 Plus (**UCKP**) firmware version v2.0.24+
* Any UniFi Protect Network Video Recorder (**[UNVR](https://store.ui.com/collections/unifi-protect-nvr/products/unvr)** or **[UNVRPRO](https://store.ui.com/collections/unifi-protect-nvr/products/unvr-pro)**)
* Any UniFi "Dream" device (**[UDMPRO](https://store.ui.com/collections/unifi-network-unifi-os-consoles/products/udm-pro)**, **[UDR](https://store.ui.com/collections/unifi-network-unifi-os-consoles/products/dream-router)**, or **[UDMSE](https://store.ui.com/collections/unifi-network-unifi-os-consoles/products/dream-machine-se)**), _except the base UniFi Dream Machine/UDM_
* UniFi Cloud Key Gen2 Plus (**[UCKP](https://store.ui.com/collections/unifi-protect-nvr/products/unifi-cloudkey-plus)**) firmware version v2.0.24+
UCKP with Firmware v1.x **do NOT run UniFi OS**, you must upgrade to firmware `v2.0.24` or newer.
UCKP with Firmware v1.x **do NOT run UniFi OS**, you must upgrade to firmware `[v2.0.24](https://community.ui.com/releases/UniFi-Cloud-Key-Firmware-2-0-24/b6684f1e-8542-4660-bc0b-74e0634448e8)` or newer.
### Software Support
The absolute **minimal** software version is `v1.20.0` for UniFi Protect. If you have an older version, you will get errors trying to set up the integration. However, the general advice is the latest 2 minor versions of UniFi Protect and hardware supported by those are supported.
The absolute **minimal** software version is `[v1.20.0](https://community.ui.com/releases/UniFi-Protect-Application-1-20-0/d43c0905-3fb4-456b-a7ca-73aa830cb011)` for UniFi Protect. If you have an older version, you will get errors trying to set up the integration. However, the general advice is the latest 2 minor versions of UniFi Protect and hardware supported by those are supported.
#### About UniFi Early Access
@ -71,18 +71,18 @@ Using Early Access versions will likely cause your UniFi Protect integration to
#### Downgrading UniFi Protect
In the event you accidentally upgrade to an Early Access version of UniFi Protect you can downgrade to a stable version by either [restoring a backup](https://help.ui.com/hc/en-us/articles/360008976393-UniFi-Backups-and-Migration) or by manually downgrading your UniFi Protect.
In the event you accidentally upgrade to an Early Access version of UniFi Protect you can downgrade to a stable version by either [restoring a backup](https://help.ui.com/hc/articles/360008976393) or by manually downgrading your UniFi Protect.
##### Manually Downgrade
Manually downgrading comes with its own risks and it is not recommended unless you do not have a backup available. Some Protect versions cannot be downgraded from (like `v2.0` to `v1.21`). To downgrade, you can access your [UniFi OS Console via SSH](https://help.ui.com/hc/en-us/articles/204909374#h_01F8G1NSFWE9GWXMT977VQEP8V) and then do the following:
Manually downgrading comes with its own risks and it is not recommended unless you do not have a backup available. Some Protect versions cannot be downgraded from (like `v2.0` to `v1.21`). To downgrade, you can access your [UniFi OS Console via SSH](https://help.ui.com/hc/articles/204909374) and then do the following:
```bash
# run this command first _only_ if you are on a 1.x firmware of the UDM Pro
# it is not needed for the UDM SE, UNVR, etc.
# Run this command first _only_ if you are on a 1.x firmware of the UDM Pro.
# It is not needed for the UDM SE, UNVR, etc.
unifi-os shell
# downgrade UniFi Protect
# Downgrade UniFi Protect.
apt-get update
apt-get install --reinstall --allow-downgrades unifi-protect=2.0.0~beta.5 -y
```
@ -91,7 +91,7 @@ You can replace `2.0.0~beta.5` with whatever version of UniFi Protect you want t
<div class='note'>
If you want to downgrade to another Early Access version, you must have [Remote Access enabled](https://help.ui.com/hc/en-us/articles/115012240067-UniFi-How-to-enable-remote-access) and have the Early Access release channel enabled.
If you want to downgrade to another Early Access version, you must have [Remote Access enabled](https://help.ui.com/hc/articles/115012240067) and have the Early Access release channel enabled.
</div>
@ -108,13 +108,13 @@ use has.
2. In the upper right corner, click on _Add User_.
3. Fill out the fields for your user. Be sure the role you assign to the user grants them access to at least one or
more UniFi Protect devices.
4. Click _Add_ in the bottom Right.
4. Click _Add_ in the bottom right.
![UniFi OS User Creation](/images/integrations/unifiprotect/user.png)
### Camera Streams
The Integration uses the RTSP(S) Streams as the Live Feed source, so this needs to be enabled on each camera to ensure
The integration uses the RTSP(S) Streams as the Live Feed source, so this needs to be enabled on each camera to ensure
you can stream your camera in Home Assistant. This may already be enabled by default, but it is recommended to just
check that this is done. To check and enable the feature:
@ -145,8 +145,8 @@ and in many cases, get a read-only sensor instead of an editable switch/select/n
**Smart Detections**: The following cameras have Smart Detections:
* All "AI" series cameras. This includes the AI 360 and the AI Bullet.
* All "G4" series cameras. This includes the G4 Doorbell, G4 Bullet, G4 Pro and G4 Instant.
* All "AI" series cameras. This includes the [AI 360](https://store.ui.com/collections/unifi-protect/products/unifi-protect-ai-360) and the [AI Bullet](https://store.ui.com/collections/unifi-protect/products/uvc-ai-bullet).
* All "G4" series cameras. This includes the [G4 Doorbell](https://store.ui.com/collections/unifi-protect/products/uvc-g4-doorbell), [G4 Bullet](https://store.ui.com/collections/unifi-protect/products/uvc-g4-bullet), [G4 Pro](https://store.ui.com/collections/unifi-protect/products/uvc-g4-pro) and [G4 Instant](https://store.ui.com/collections/unifi-protect/products/camera-g4-instant).
G3 Series cameras do _not_ have Smart detections.

Some files were not shown because too many files have changed in this diff Show More