diff --git a/CODEOWNERS b/CODEOWNERS index 944fc57ca1e0..1f48d53b984e 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -778,7 +778,6 @@ source/_integrations/workday.markdown @fabaff @gjohansson-ST source/_integrations/worldclock.markdown @fabaff source/_integrations/ws66i.markdown @ssaenger source/_integrations/xbox.markdown @hunterjm -source/_integrations/xbox_live.markdown @MartinHjelmare source/_integrations/xiaomi_aqara.markdown @danielhiversen @syssi source/_integrations/xiaomi_ble.markdown @Jc2k @Ernst79 source/_integrations/xiaomi_miio.markdown @rytilahti @syssi @starkillerOG diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index 86fe15d59dbe..802852f9b27b 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -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 diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 07949b713219..c3bbe7874c11 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -657,13 +657,14 @@ To fix it, enforce the ISO conversion via `isoformat()`: The `to_json` filter serializes an object to a JSON string. In some cases, it may be necessary to format a JSON string for use with a webhook, as a parameter for command-line utilities or any number of other applications. This can be complicated in a template, especially when dealing with escaping special characters. Using the `to_json` filter, this is handled automatically. -Similarly to the Python equivalent, the filter accepts an `ensure_ascii` parameter, defaulting to `True`. If `ensure_ascii` is `True`, the output is guaranteed to have all incoming non-ASCII characters escaped. If `ensure_ascii` is false, these characters will be output as-is. +`to_json` also accepts boolean arguments for `pretty_print`, which will pretty print the JSON with a 2-space indent to make it more human-readable, and `sort_keys`, which will sort the keys of the JSON object, ensuring that the resulting string is consistent for the same input. + +If you need to generate JSON that will be used by a parser that lacks support for Unicode characters, you can add `ensure_ascii=True` to have `to_json` generate Unicode escape sequences in strings. The `from_json` filter operates similarly, but in the other direction, de-serializing a JSON string back into an object. -### To/From JSON examples -In this example, the special character '°' will be automatically escaped in order to produce valid JSON. The difference between the stringified object and the actual JSON is evident. +### To/From JSON examples #### Template @@ -672,7 +673,7 @@ In this example, the special character '°' will be automatically escaped in ord ```text {% set temp = {'temperature': 25, 'unit': '°C'} %} stringified object: {{ temp }} -object|to_json: {{ temp|to_json(ensure_ascii=False) }} +object|to_json: {{ temp|to_json(sort_keys=True) }} ``` {% endraw %} @@ -683,7 +684,7 @@ object|to_json: {{ temp|to_json(ensure_ascii=False) }} ```text stringified object: {'temperature': 25, 'unit': '°C'} -object|to_json: {"temperature": 25, "unit": "\u00b0C"} +object|to_json: {"temperature": 25, "unit": "°C"} ``` {% endraw %} @@ -695,7 +696,7 @@ Conversely, `from_json` can be used to de-serialize a JSON string back into an o {% raw %} ```text -{% set temp = '{"temperature": 25, "unit": "\u00b0C"}'|from_json %} +{% set temp = '{"temperature": 25, "unit": "°C"}'|from_json %} The temperature is {{ temp.temperature }}{{ temp.unit }} ``` diff --git a/source/_integrations/advantage_air.markdown b/source/_integrations/advantage_air.markdown index 28750ee90c03..7aeaf90eaa40 100644 --- a/source/_integrations/advantage_air.markdown +++ b/source/_integrations/advantage_air.markdown @@ -40,7 +40,9 @@ The integration will create a climate entity for each air conditioning system fo ### 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 +55,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 diff --git a/source/_integrations/androidtv.markdown b/source/_integrations/androidtv.markdown index 2e79570a0767..a24c394984de 100644 --- a/source/_integrations/androidtv.markdown +++ b/source/_integrations/androidtv.markdown @@ -1,6 +1,6 @@ --- -title: Android TV -description: Instructions on how to integrate Android TV and Fire TV devices into Home Assistant. +title: Android Debug Bridge +description: Instructions on how to integrate Android and Fire TV devices into Home Assistant. ha_category: - Media Player ha_release: 0.7.6 @@ -16,7 +16,7 @@ ha_platforms: ha_integration_type: device --- -The `androidtv` platform allows you to control an Android TV device or [Amazon Fire TV](https://www.amazon.com/b/?node=8521791011) device. +The Android Debug Bridge integration allows you to control an Android device or [Amazon Fire TV](https://www.amazon.com/b/?node=8521791011) device.
@@ -26,7 +26,7 @@ When setting up this integration, it is recommended that you do NOT use an ADB s ## Device preparation -To set up your device, you will need to find its IP address and enable ADB debugging. For Android TV devices, please consult the documentation for your device. +To set up your device, you will need to find its IP address and enable ADB debugging. For Android devices, please consult the documentation for your device. For Fire TV devices, the instructions are as follows: @@ -62,11 +62,11 @@ Configure State Detection Rules: ## ADB Setup -This integration works by sending ADB commands to your Android TV / Fire TV device. There are two ways to accomplish this. +This integration works by sending ADB commands to your Android / Fire TV device. There are two ways to accomplish this.
-When connecting to your device for the first time, a dialog will appear on your Android TV / Fire TV asking you to approve the connection. Check the box that says "always allow connections from this device" and hit OK. +When connecting to your device for the first time, a dialog will appear on your Android / Fire TV asking you to approve the connection. Check the box that says "always allow connections from this device" and hit OK.
@@ -84,7 +84,7 @@ Prior to Home Assistant 0.101, this approach did not work well for newer devices ### 2. ADB Server -The second option is to use an ADB server to connect to your Android TV and Fire TV devices. +The second option is to use an ADB server to connect to your Android and Fire TV devices.
@@ -92,21 +92,21 @@ To configure ADB server on integration setup, you need to enable [advanced mode]
-Using this approach, Home Assistant will send the ADB commands to the server, which will then send them to the Android TV / Fire TV device and report back to Home Assistant. To use this option, add the `adb_server_ip` option to your configuration. If you are running the server on the same machine as Home Assistant, you can use `127.0.0.1` for this value. +Using this approach, Home Assistant will send the ADB commands to the server, which will then send them to the Android / Fire TV device and report back to Home Assistant. To use this option, add the `adb_server_ip` option to your configuration. If you are running the server on the same machine as Home Assistant, you can use `127.0.0.1` for this value. ## ADB Troubleshooting -If the setup for your Android TV or Fire TV device fails, then there is probably an issue with your ADB connection. Here are some possible causes. +If the setup for your Android or Fire TV device fails, then there is probably an issue with your ADB connection. Here are some possible causes. 1. You have the wrong IP address for the device. 2. ADB is not enabled on your device. -3. You are already connected to the Android TV / Fire TV via ADB from another device. Only one device can be connected, so disconnect the other device, restart the Android TV / Fire TV (for good measure), and then restart Home Assistant. +3. You are already connected to the Android / Fire TV via ADB from another device. Only one device can be connected, so disconnect the other device, restart the Android / Fire TV (for good measure), and then restart Home Assistant. 4. You need to approve the ADB connection; see the note in the [ADB Setup](#adb-setup) section above. -5. Some Android TV devices (e.g., Philips TVs running Android TV) only accept the initial ADB connection request over their Wi-Fi interface. If you have the TV wired, you need to connect it to Wi-Fi and try the initial connection again. Once the authentication has been granted via Wi-Fi, you can connect to the TV over the wired interface as well. +5. Some Android devices (e.g., Philips TVs running Android TV) only accept the initial ADB connection request over their Wi-Fi interface. If you have the TV wired, you need to connect it to Wi-Fi and try the initial connection again. Once the authentication has been granted via Wi-Fi, you can connect to the TV over the wired interface as well. 6. If your device drops off WiFi, breaking the ADB connection and causing the entity to become unavailable in Home Assistant, you could install a wake lock utility (such as [Wakelock](https://github.com/d4rken/wakelock-revamp)) to prevent this from happening. Some users have reported this problem with Xiaomi Mi Box devices. @@ -138,11 +138,11 @@ stop_netflix: ### `androidtv.adb_command` -The service `androidtv.adb_command` allows you to send either keys or ADB shell commands to your Android TV / Fire TV device. If there is any output, it will be stored in the `'adb_response'` attribute (i.e., `state_attr('media_player.android_tv_living_room', 'adb_response')` in a template) and logged at the INFO level. +The service `androidtv.adb_command` allows you to send either keys or ADB shell commands to your Android / Fire TV device. If there is any output, it will be stored in the `'adb_response'` attribute (i.e., `state_attr('media_player.android_tv_living_room', 'adb_response')` in a template) and logged at the INFO level. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of Android TV / Fire TV entities. +| `entity_id` | no | Name(s) of Android / Fire TV entities. | `command` | no | Either a key command or an ADB shell command. In an [action](/getting-started/automation-action/) of your [automation setup](/getting-started/automation/) it could look like this: @@ -177,14 +177,14 @@ A list of various intents can be found [here](https://gist.github.com/mcfrojd/9e ### `androidtv.learn_sendevent` (for faster ADB commands) -When sending commands like UP, DOWN, HOME, etc. via ADB, the device can be slow to respond. The problem isn't ADB, but rather the Android command `input` that is used to perform those actions. A faster way to send these commands is using the Android `sendevent` command. The challenge is that these commands are device-specific. To assist users in learning commands for their device, the Android TV integration provides the `androidtv.learn_sendevent` service. Its usage is as follows: +When sending commands like UP, DOWN, HOME, etc. via ADB, the device can be slow to respond. The problem isn't ADB, but rather the Android command `input` that is used to perform those actions. A faster way to send these commands is using the Android `sendevent` command. The challenge is that these commands are device-specific. To assist users in learning commands for their device, the Android debug bridge integration provides the `androidtv.learn_sendevent` service. Its usage is as follows: | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of Android TV / Fire TV entities. +| `entity_id` | no | Name(s) of Android / Fire TV entities. 1. Call the `androidtv.learn_sendevent` service. -2. Within 8 seconds, hit a single button on your Android TV / Fire TV remote. +2. Within 8 seconds, hit a single button on your Android / Fire TV remote. 3. After 8 seconds, a persistent notification will appear that contains the equivalent command that can be sent via the `androidtv.adb_command` service. This command can also be found in the `adb_response` attribute of the media player in Home Assistant, and it will be logged at the INFO level. As an example, a service call in a [script](/docs/scripts) could be changed from this: @@ -211,25 +211,25 @@ to this: ### `androidtv.download` and `androidtv.upload` -You can use the `androidtv.download` service to download a file from your Android TV / Fire TV device to your Home Assistant instance. +You can use the `androidtv.download` service to download a file from your Android / Fire TV device to your Home Assistant instance. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name of Android TV / Fire TV entity. -| `device_path` | no | The filepath on the Android TV / Fire TV device. +| `entity_id` | no | Name of Android / Fire TV entity. +| `device_path` | no | The filepath on the Android / Fire TV device. | `local_path` | no | The filepath on your Home Assistant instance. -Similarly, you can use the `androidtv.upload` service to upload a file from Home Assistant instance to Android TV / Fire TV devices. +Similarly, you can use the `androidtv.upload` service to upload a file from Home Assistant instance to Android / Fire TV devices. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of Android TV / Fire TV entities. -| `device_path` | no | The filepath on the Android TV / Fire TV device. +| `entity_id` | no | Name(s) of Android / Fire TV entities. +| `device_path` | no | The filepath on the Android / Fire TV device. | `local_path` | no | The filepath on your Home Assistant instance. ## Custom State Detection -The Android TV integration works by polling the Android TV / Fire TV device at a regular interval and collecting a handful of properties. Unfortunately, there is no standard API for determining the state of the device to which all apps adhere. Instead, the backend `androidtv` package uses three of the properties that it collects to determine the state: `audio_state`, `media_session_state`, and `wake_lock_size`. The correct logic for determining the state differs depending on the current app, and the backend `androidtv` package implements app-specific state detection logic for a handful of apps. Of course, it is not feasible to implement custom logic for each and every app in the `androidtv` package. Moreover, the correct state detection logic may differ across devices and device configurations. +The Android Debug Bridge integration works by polling the Android / Fire TV device at a regular interval and collecting a handful of properties. Unfortunately, there is no standard API for determining the state of the device to which all apps adhere. Instead, the backend `androidtv` package uses three of the properties that it collects to determine the state: `audio_state`, `media_session_state`, and `wake_lock_size`. The correct logic for determining the state differs depending on the current app, and the backend `androidtv` package implements app-specific state detection logic for a handful of apps. Of course, it is not feasible to implement custom logic for each and every app in the `androidtv` package. Moreover, the correct state detection logic may differ across devices and device configurations. The solution to this problem is the `state_detection_rules` configuration parameter, which allows you to provide your own rules for state detection. The keys are app IDs, and the values are lists of rules that are evaluated in order. Valid rules are: diff --git a/source/_integrations/androidtv_remote.markdown b/source/_integrations/androidtv_remote.markdown new file mode 100644 index 000000000000..ff4874af3ddd --- /dev/null +++ b/source/_integrations/androidtv_remote.markdown @@ -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 %} diff --git a/source/_integrations/anova.markdown b/source/_integrations/anova.markdown new file mode 100644 index 000000000000..70a377cc4789 --- /dev/null +++ b/source/_integrations/anova.markdown @@ -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. diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown index e4a13a4cea58..55b1ef5e603d 100644 --- a/source/_integrations/binary_sensor.mqtt.markdown +++ b/source/_integrations/binary_sensor.mqtt.markdown @@ -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: diff --git a/source/_integrations/brottsplatskartan.markdown b/source/_integrations/brottsplatskartan.markdown index 23bc564cd7fb..9dff345cbf10 100644 --- a/source/_integrations/brottsplatskartan.markdown +++ b/source/_integrations/brottsplatskartan.markdown @@ -2,9 +2,13 @@ title: Brottsplatskartan description: Instructions on how to integrate brottsplatskartan.se into Home Assistant. ha_category: + - Sensor - Social ha_release: 0.85 ha_iot_class: Cloud Polling +ha_config_flow: true +ha_codeowners: + - '@gjohansson-ST' ha_domain: brottsplatskartan ha_platforms: - sensor @@ -13,36 +17,7 @@ ha_integration_type: integration The `brottsplatskartan` sensor allows one to track reported incidents occurring in a given area. Incidents include anything reported to [Brottsplatskartan](https://brottsplatskartan.se). The sensor only counts incidents from the current day. -## Configuration - -To enable this sensor, add the following lines to your `configuration.yaml`. - -```yaml -sensor: - - platform: brottsplatskartan -``` - -{% configuration %} -name: - description: Custom name for the sensor. - required: false - type: string - default: Brottsplatskartan -area: - description: Area for sensor to monitor - required: false - type: string -latitude: - description: Latitude for sensor. - required: false - type: float - default: Your home zone latitude defined in your configuration. -longitude: - description: Longitude for sensor. - required: false - type: float - default: Your home zone longitude defined in your configuration. -{% endconfiguration %} +{% include integrations/config_flow.md %} ## Notes diff --git a/source/_integrations/button.mqtt.markdown b/source/_integrations/button.mqtt.markdown index f4dbf214ff31..ef9d737cc682 100644 --- a/source/_integrations/button.mqtt.markdown +++ b/source/_integrations/button.mqtt.markdown @@ -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: diff --git a/source/_integrations/coronavirus.markdown b/source/_integrations/coronavirus.markdown deleted file mode 100644 index 890cb1fc4245..000000000000 --- a/source/_integrations/coronavirus.markdown +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Coronavirus (COVID-19) -description: Instructions on how to integrate the Coronavirus sensors within Home Assistant. -ha_category: - - Health -ha_release: 0.106 -ha_iot_class: Cloud Polling -ha_config_flow: true -ha_codeowners: - - '@home-assistant/core' -ha_domain: coronavirus -ha_platforms: - - sensor -ha_integration_type: integration ---- - -In December 2019, an outbreak of a novel Coronavirus, also called severe acute -respiratory syndrome coronavirus-2 (SARS-CoV-2), began in the Wuhan region of -China. This virus can cause the COVID-19 disease. - -This novel Coronavirus is spreading globally at a disturbing rate, which keeps -everybody on top of the news. The media worldwide is covering the spread of -the virus constantly, and a lot of people are tracking the number of cases -in their country. - -The Coronavirus integration tracks the number of people that are confirmed with, -recovered from, and deceased caused by the virus in your country, or worldwide. - -The data is sourced from the [Johns Hopkins University](https://www.arcgis.com/apps/opsdashboard/index.html#/bda7594740fd40299423467b48e9ecf6). - -{% include integrations/config_flow.md %} diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown index c5a2d5d40394..7300f5fa5e7e 100644 --- a/source/_integrations/cover.mqtt.markdown +++ b/source/_integrations/cover.mqtt.markdown @@ -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: diff --git a/source/_integrations/cover.template.markdown b/source/_integrations/cover.template.markdown index ae69a4a980db..5291ecccaad3 100644 --- a/source/_integrations/cover.template.markdown +++ b/source/_integrations/cover.template.markdown @@ -54,11 +54,11 @@ cover: required: false type: string value_template: - description: Defines a template to get the state of the cover. Valid output values from the template are `open`, `opening`, `closing` and `closed` which are directly mapped to the corresponding states. In addition, `true` is valid as a synonym to `open` and `false` as a synonym to `closed`. If [both a `value_template` and a `position_template`](#combining_value_template_and_position_template) are specified, only `opening` and `closing` are set from the `value_template`. + description: Defines a template to get the state of the cover. Valid output values from the template are `open`, `opening`, `closing` and `closed` which are directly mapped to the corresponding states. In addition, `true` is valid as a synonym to `open` and `false` as a synonym to `closed`. If [both a `value_template` and a `position_template`](#combining_value_template_and_position_template) are specified, only `opening` and `closing` are set from the `value_template`. If the template produces a `None` value the state will be set to `unknown`. required: false type: template position_template: - description: Defines a template to get the position of the cover. Legal values are numbers between `0` (closed) and `100` (open). + description: Defines a template to get the position of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value the current position will be set to `unknown`. required: false type: template icon_template: @@ -109,7 +109,7 @@ cover: type: boolean default: false tilt_template: - description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). + description: Defines a template to get the tilt state of the cover. Legal values are numbers between `0` (closed) and `100` (open). If the template produces a `None` value the current tilt state will be set to `unknown`. required: false type: template {% endconfiguration %} diff --git a/source/_integrations/easyenergy.markdown b/source/_integrations/easyenergy.markdown index f01451832b3d..c3e9b464afc6 100644 --- a/source/_integrations/easyenergy.markdown +++ b/source/_integrations/easyenergy.markdown @@ -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. + +

+ Screenshot showing energy price graph. + Example showing the energy price graph. +

### Gas market price diff --git a/source/_integrations/history.markdown b/source/_integrations/history.markdown index efffd6a9c5ff..d13ccfa8fe3f 100644 --- a/source/_integrations/history.markdown +++ b/source/_integrations/history.markdown @@ -30,141 +30,6 @@ history:

-
-Events are saved in a local database. Google Graphs is used to draw the graph. -Drawing is happening 100% in your browser. No data is transferred to anyone at any time. -
- -{% configuration %} -exclude: - description: Configure which integrations should **not** be displayed. - required: false - type: map - keys: - entities: - description: The list of entity ids to be excluded from the history. - required: false - type: list - entity_globs: - description: Include all entities matching a listed pattern when creating logbook entries (e.g., `sensor.weather_*`). - required: false - type: list - domains: - description: The list of domains to be excluded from the history. - required: false - type: list -include: - description: Configure which integrations should be displayed. - required: false - type: map - keys: - entities: - description: The list of entity ids to be included in the history. - required: false - type: list - entity_globs: - description: Include all entities matching a listed pattern when creating logbook entries (e.g., `sensor.weather_*`). - required: false - type: list - domains: - description: The list of domains to be included in the history. - required: false - type: list -{% endconfiguration %} - -Without any `include` or `exclude` configuration the history displays graphs for - every entity (well that's not exactly true - - `scenes` are never shown) on a given date. If you are only interested in some - of the entities you have several options: - -Define domains and entities to `exclude` (aka. blocklist). This is convenient -when you are basically happy with the information displayed, but just want to -remove some entities or domains. Usually these are entities/domains which do not -change or rarely change (like `updater` or `automation`). - -```yaml -# Example configuration.yaml entry with exclude -history: - exclude: - domains: - - automation - - updater - entities: - - sensor.last_boot - - sensor.date - entity_globs: - - binary_sensor.*_occupancy -``` - -Define domains and entities to display by using the `include` configuration -(aka. allowlist). If you have a lot of entities in your system and your -`exclude` list is getting too large, it might be better just to define the -entities or domains to `include`. - -```yaml -# Example configuration.yaml entry with include -history: - include: - domains: - - sensor - - switch - - media_player -``` - -Use the `include` list to define the domains/entities to display, and exclude -some of them within the `exclude` list. This makes sense if you, for instance, -include the `sensor` domain, but want to exclude some specific sensors. Instead -of adding every sensor entity to the `include` `entities` list just include the -`sensor` domain and exclude the sensor entities you are not interested in. -Note that the order of any `include` `entities` will be displayed as listed in -the configuration, otherwise, the display order is arbitrary. - -```yaml -# Example configuration.yaml entry with include and exclude -history: - include: - domains: - - sensor - - switch - - media_player - exclude: - entities: - - sensor.last_boot - - sensor.date -``` - -{% include common-tasks/filters.md %} - -#### Implementation details - -The history is stored in a SQLite database `home-assistant_v2.db` within your -configuration directory unless the `recorder` integration is set up differently. - -- events table is all that happened while recorder integration was running. -- states table contains all the `new_state` values of `state_changed` events. -- Inside the states table you have: - - `entity_id`: the entity_id of the entity - - `state`: the state of the entity - - `attributes`: JSON of the state attributes - - `last_changed`: timestamp last time the state has changed. - - `last_updated`: timestamp anything has changed (state, attributes) - - `created`: timestamp this entry was inserted into the database - -When the `history` integration queries the states table it only selects states -where the state has changed: `WHERE last_changed=last_updated` - -#### On dates - -SQLite databases do not support native dates. That's why all the dates are saved -in seconds since the UNIX epoch. Convert them manually using -[this site](https://www.epochconverter.com/) or in Python: - -```python -from datetime import datetime - -datetime.fromtimestamp(1422830502) -``` - #### API The history information is also available through the diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index e1c631b5af19..f72512415f9a 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -253,13 +253,18 @@ homekit: type: integer default: 1316 video_codec: - description: Only for `camera` entities. FFmpeg video codec for transcoding. `copy` option reduces CPU load when video source already encoded with `H264` (MPEG4). `h264_omx` option is only available with custom FFmpeg builds and enables GPU Hardware acceleration on Raspberry Pi. + description: Only for `camera` entities. FFmpeg video codec for transcoding. `copy` option reduces CPU load when video source is already encoded with `H264` (MPEG4). `h264_v4l2m2m` can be used with supported hardware, e.g., the Raspberry Pi, to offload encoding to hardware. The `h264_omx` option is only available with custom FFmpeg builds and enables GPU Hardware acceleration on Raspberry Pi. required: false type: string default: libx264 - available options: copy, libx264, h264_omx + available options: copy, libx264, h264_v4l2m2m, h264_omx + video_profile_names: + description: Only for `camera` entities. FFmpeg video profile names for transcoding, only relevant if `video_codec` isn't `copy`. Some encoders, e.g., the Raspberry Pi's `h264_v4l2m2m`, don't use the standard `["baseline", "main", "high"]` profile names but expects `["0", "2", "4"]` instead. Use this option to override the default names, if needed. + required: false + type: list + default: ["baseline", "main", "high"] audio_codec: - description: Only for `camera` entities. FFmpeg audio codec for transcoding. `copy` option reduces CPU load when audio source already encoded with `libopus`. + description: Only for `camera` entities. FFmpeg audio codec for transcoding. `copy` option reduces CPU load when audio source is already encoded with `libopus`. required: false type: string default: libopus diff --git a/source/_integrations/humidifier.mqtt.markdown b/source/_integrations/humidifier.mqtt.markdown index 8921ff1f731f..1a512dd2f89e 100644 --- a/source/_integrations/humidifier.mqtt.markdown +++ b/source/_integrations/humidifier.mqtt.markdown @@ -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 diff --git a/source/_integrations/imap_email_content.markdown b/source/_integrations/imap_email_content.markdown deleted file mode 100644 index f045047edeb9..000000000000 --- a/source/_integrations/imap_email_content.markdown +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: IMAP Email Content -description: Instructions on how to integrate IMAP email content sensor into Home Assistant. -ha_category: - - Mailbox -ha_iot_class: Cloud Push -ha_release: 0.25 -ha_domain: imap_email_content -ha_platforms: - - sensor -ha_integration_type: integration ---- - -The `imap_email_content` integration will read emails from an IMAP email server and report them as a state change within Home Assistant. This is useful if you have a device that only reports its state via email. - -## Configuration - -To enable this sensor, add the following lines to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: imap_email_content - server: imap.gmail.com - port: 993 - username: YOUR_USERNAME - password: YOUR_PASSWORD - folder: YOUR_FOLDER - senders: - - example@gmail.com -``` - -{% configuration %} -server: - description: The IP address or hostname of the IMAP server. - required: true - type: string -port: - description: The port where the server is accessible. - required: false - default: 993 - type: integer -name: - description: Name of the IMAP sensor. - required: false - type: string -username: - description: Username for the IMAP server. - required: true - type: string -password: - description: Password for the IMAP server. - required: true - type: string -folder: - description: Folder to get mails from. - required: false - default: INBOX - type: string -senders: - description: A list of sender email addresses that are allowed to report state via email. Only emails received from these addresses will be processed. - required: true - type: string -value_template: - description: If specified this template will be used to render the state of the sensor. If a template is not supplied the message subject will be used for the sensor value. The following attributes will be supplied to the template. - required: false - type: template - keys: - from: - description: The from address of the email. - body: - description: The body of the email. - subject: - description: The subject of the email. - date: - description: The date and time the email was sent. -verify_ssl: - description: If the SSL certificate of the server needs to be verified. - required: false - type: boolean - default: true -{% endconfiguration %} - -## Example - keyword spotting - -The following example shows the usage of the IMAP email content sensor to scan the subject of an email for text, in this case, an email from the APC SmartConnect service which tells whether the UPS is running on battery or not. - -{% raw %} - -```yaml -sensor: - - platform: imap_email_content - server: imap.gmail.com - name: house_electricity - port: 993 - username: MY_EMAIL_USERNAME - password: MY_EMAIL_PASSWORD - senders: - - no-reply@smartconnect.apc.com - value_template: >- - {% if 'UPS On Battery' in subject %} - power_out - {% elif 'Power Restored' in subject %} - power_on - {% endif %} -``` - -{% endraw %} - -The same template structure can scan the date, body or sender for matching text before setting the state of the sensor. - -## Example - extracting formatted text from an email using template sensors - -This example shows how to extract numbers or other formatted data from an email to change the value of a template sensor to a value extracted from the email. In this example, we will be extracting energy use, cost, and billed amount from an email (from Georgia Power) and putting it into sensor values using a template sensor that runs against our IMAP email sensor already set up. A sample of the body of the email used is below: - -```text -Yesterday's Energy Use: 76 kWh -Yesterday's estimated energy cost: $8 -Monthly Energy use-to-date for 23 days: 1860 kWh -Monthly estimated energy cost-to-date for 23 days: $198 - -To view your account for details about your energy use, please click here. -``` - -Below is the template sensor which extracts the information from the body of the email in our IMAP email sensor (named sensor.energy_email) into 3 sensors for the energy use, daily cost, and billing cycle total. - -{% raw %} - -```yaml -template: - - sensor: - - name: "Previous Day Energy Use" - unit_of_measurement: "kWh" - state: > - {{ state_attr('sensor.energy_email','body') - | regex_findall_index("\*Yesterday's Energy Use:\* ([0-9]+) kWh") }} - - name: "Previous Day Cost" - unit_of_measurement: "$" - state: > - {{ state_attr('sensor.energy_email', 'body') - | regex_findall_index("\*Yesterday's estimated energy cost:\* \$([0-9.]+)") }} - - name: "Billing Cycle Total" - unit_of_measurement: "$" - state: > - {{ state_attr('sensor.energy_email', 'body') - | regex_findall_index("\ days:\* \$([0-9.]+)") }} -``` - -{% endraw %} - -By making small changes to the regular expressions defined above, a similar structure can parse other types of data out of the body of other emails. diff --git a/source/_integrations/matter.markdown b/source/_integrations/matter.markdown index df427facef19..1703d0c165a4 100644 --- a/source/_integrations/matter.markdown +++ b/source/_integrations/matter.markdown @@ -3,6 +3,7 @@ title: Matter (BETA) description: Instructions on how to integrate Matter with Home Assistant. ha_category: - Binary Sensor + - Cover - Light - Lock - Sensor @@ -15,6 +16,7 @@ ha_codeowners: ha_domain: matter ha_platforms: - binary_sensor + - cover - diagnostics - light - lock @@ -53,7 +55,7 @@ _If you run Home Assistant Container, Home Assistant Core, or you don’t want t 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. -Platform support in Home Assistant is currently limited to switches, lights, and (binary) sensors. The light platform is limited to _on/off_ and _brightness_ control only, support for _color_ and _color temperature_ control will be added soon. +Platform support in Home Assistant is currently limited to switches, lights, locks, covers and (binary) sensors. ### Known issues diff --git a/source/_integrations/monessen.markdown b/source/_integrations/monessen.markdown new file mode 100644 index 000000000000..567537084533 --- /dev/null +++ b/source/_integrations/monessen.markdown @@ -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 %} diff --git a/source/_integrations/number.mqtt.markdown b/source/_integrations/number.mqtt.markdown index 5dbcb101c929..81f2a883c962 100644 --- a/source/_integrations/number.mqtt.markdown +++ b/source/_integrations/number.mqtt.markdown @@ -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: diff --git a/source/_integrations/nut.markdown b/source/_integrations/nut.markdown index 0adcee441df5..847d057df013 100644 --- a/source/_integrations/nut.markdown +++ b/source/_integrations/nut.markdown @@ -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. diff --git a/source/_integrations/qbittorrent.markdown b/source/_integrations/qbittorrent.markdown index ee99df8adc50..60010a3df09c 100644 --- a/source/_integrations/qbittorrent.markdown +++ b/source/_integrations/qbittorrent.markdown @@ -4,6 +4,7 @@ description: Instructions on how to integrate qBittorrent sensors within Home As ha_category: - Downloading ha_release: 0.84 +ha_config_flow: true ha_iot_class: Local Polling ha_domain: qbittorrent ha_codeowners: @@ -19,37 +20,7 @@ The `qbittorrent` platform allows you to monitor your downloads with [qBittorren This sensor requires the qBittorrent Web UI enabled. The [official reference](https://github.com/qbittorrent/qBittorrent/wiki#webui-related) describes how to set up the Web UI. -## Configuration - -To enable this sensor, add the following lines to your `configuration.yaml`: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: qbittorrent - url: "http://:" - username: YOUR_USERNAME - password: YOUR_PASSWORD -``` - -{% configuration %} -url: - description: The URL of the Web UI of qBittorrent. - required: true - type: string -name: - description: The name to use when displaying this qBittorrent instance. - required: false - type: string -username: - description: The username of the Web UI of qBittorrent. - required: true - type: string -password: - description: The password of the Web UI of qBittorrent. - required: true - type: string -{% endconfiguration %} +{% include integrations/config_flow.md %} ## Sensors diff --git a/source/_integrations/rapt_ble.markdown b/source/_integrations/rapt_ble.markdown new file mode 100644 index 000000000000..0b9121ee5797 --- /dev/null +++ b/source/_integrations/rapt_ble.markdown @@ -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) diff --git a/source/_integrations/reolink.markdown b/source/_integrations/reolink.markdown index e403324f7a6a..b1a9a7d68de0 100644 --- a/source/_integrations/reolink.markdown +++ b/source/_integrations/reolink.markdown @@ -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: diff --git a/source/_integrations/rest.markdown b/source/_integrations/rest.markdown index c776fc8fc7fb..9b2711d8747d 100644 --- a/source/_integrations/rest.markdown +++ b/source/_integrations/rest.markdown @@ -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 diff --git a/source/_integrations/roborock.markdown b/source/_integrations/roborock.markdown index 9de58cdc5c6f..15173dc6b3c2 100644 --- a/source/_integrations/roborock.markdown +++ b/source/_integrations/roborock.markdown @@ -1,43 +1,24 @@ --- 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_iot_class: Local Polling +ha_release: 2023.5 ha_config_flow: true +ha_codeowners: + - '@humbertogontijo' + - '@Lash-L' +ha_domain: roborock ha_platforms: - - air_quality - - alarm_control_panel - - binary_sensor - - button - - device_tracker - - diagnostics - - fan - - humidifier - - light - - number - - remote - - select - - sensor - - switch - vacuum -ha_iot_class: Local Polling -ha_zeroconf: true +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 %} diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown index 0d7d55ddefc6..6566221189df 100644 --- a/source/_integrations/sensor.mqtt.markdown +++ b/source/_integrations/sensor.mqtt.markdown @@ -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 @@ -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: diff --git a/source/_integrations/shopping_list.markdown b/source/_integrations/shopping_list.markdown index 0873762b8721..f5e2926cc89e 100644 --- a/source/_integrations/shopping_list.markdown +++ b/source/_integrations/shopping_list.markdown @@ -65,6 +65,14 @@ Mark all items as incomplete in the shopping list. Clear completed items from the shopping list. +### Service `shopping_list.sort` + +Sort all items by name in the shopping list. + +| Service data attribute | Optional | Description | +|------------------------|----------|---------------------------------------------------------------------| +| `reverse` | yes | Whether to sort in reverse (_descending_) order. (default: `False`) | + ## Using in Automations A `shopping_list_updated` event is triggered when items in the list are modified, with the following data payload attached to it. This can be used to trigger automations such as sending a push notification when someone adds an item to the shopping list, which when clicked, will open the list. diff --git a/source/_integrations/simplepush.markdown b/source/_integrations/simplepush.markdown index da61e4275d2a..8b31502e8545 100644 --- a/source/_integrations/simplepush.markdown +++ b/source/_integrations/simplepush.markdown @@ -14,17 +14,55 @@ ha_codeowners: - '@engrbm87' --- -The `simplepush` platform uses [Simplepush](https://simplepush.io/) to deliver notifications from Home Assistant to your Android device. Unlike similar apps the Simplepush app requires no registration. +The `simplepush` platform uses [Simplepush](https://simplepush.io/) to deliver notifications from Home Assistant to your Android and iOS device. Unlike similar apps the Simplepush app requires no registration and supports end-to-end encryption. {% include integrations/config_flow.md %} To test if the service works, just send a message with `curl` from the command-line. ```bash -curl 'https://api.simplepush.io/send/device_key/title/message' +curl 'https://simplepu.sh/YOUR_SIMPLEPUSH_KEY/message' ``` + +If you enter your password and salt (as defined in the Simplepush app settings) during the configuration of this integration, all notifications sent from this integration will be end-to-end encrypted. + ## Notifications -Simplepush can send a notification by calling the [`notify` service](/integrations/notify/). You can specify the `event` under the `data` key. This will override the event configured in YAML when imported. +Simplepush can send a notification by calling the [`notify` service](/integrations/notify/). + +You can specify the `event` under the `data` key. +Events can be used to customize the notification behavior. + +It is also possible to specify `attachments` under the `data` key. +Attachments can be images, GIFs or video files that are accessible by a URL. To use notifications, please see the [getting started with automation page](/getting-started/automation/). + +## Examples + +Send a notification with a title and event. + +```yml +- service: notify.simplepush + data: + title: "This is the title" + message: "This is the message" + data: + event: "event" +``` + +Send a notification with four attachments defined by their URL. +Attachments can be images, GIFs or video files. + +```yml +- service: notify.simplepush + data: + message: "This is the message" + data: + attachments: + - image: "https://upload.wikimedia.org/wikipedia/commons/e/ee/Sample_abc.jpg" + - image: "https://upload.wikimedia.org/wikipedia/commons/d/d3/Newtons_cradle_animation_book_2.gif" + - video: "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4" + - video: "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4" + thumbnail: "http://commondatastorage.googleapis.com/gtv-videos-bucket/sample/images/ForBiggerEscapes.jpg" +``` diff --git a/source/_integrations/snapcast.markdown b/source/_integrations/snapcast.markdown index fe1f9a49d1f6..5fac754680c1 100644 --- a/source/_integrations/snapcast.markdown +++ b/source/_integrations/snapcast.markdown @@ -6,6 +6,7 @@ ha_category: ha_release: 0.13 ha_iot_class: Local Polling ha_domain: snapcast +ha_config_flow: true ha_platforms: - media_player ha_integration_type: integration @@ -13,28 +14,9 @@ ha_codeowners: - '@luar123' --- -The `snapcast` platform allows you to control [Snapcast](https://github.com/badaix/snapcast) from Home Assistant. - -To add Snapcast to your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -media_player: - - platform: snapcast - host: YOUR_IP_ADDRESS -``` - -{% configuration %} -host: - description: The IP address of the device, e.g., `192.168.0.10`. - required: true - type: string -port: - description: The port number. - required: false - default: 1705 - type: integer -{% endconfiguration %} +The Snapcast integration allows you to control [Snapcast](https://github.com/badaix/snapcast) from Home Assistant. + +{% include integrations/config_flow.md %} ## Services diff --git a/source/_integrations/sonos.markdown b/source/_integrations/sonos.markdown index f7d3ff2988e7..817b68f39ebc 100644 --- a/source/_integrations/sonos.markdown +++ b/source/_integrations/sonos.markdown @@ -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: diff --git a/source/_integrations/starlink.markdown b/source/_integrations/starlink.markdown index cc27a0d9570c..d107e0521b51 100644 --- a/source/_integrations/starlink.markdown +++ b/source/_integrations/starlink.markdown @@ -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 diff --git a/source/_integrations/stt.markdown b/source/_integrations/stt.markdown index 46ec6c89241d..0fb1f959f820 100644 --- a/source/_integrations/stt.markdown +++ b/source/_integrations/stt.markdown @@ -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. diff --git a/source/_integrations/supla.markdown b/source/_integrations/supla.markdown index a354cdcca23d..97a478b98dec 100644 --- a/source/_integrations/supla.markdown +++ b/source/_integrations/supla.markdown @@ -17,7 +17,7 @@ ha_integration_type: integration The [Supla](https://supla.org/) is an Open Source home automation system for ESP8266 based devices. It has its own set of protocols, its own firmware and commercially available devices (produced for example by [Zamel](https://zamel.pl/pl-PL/produkty/supla-sterowanie-wi-fi)) -Currently only covers (shutters in Supla's lingo), gates and switches are supported, but, thanks to comprehensive and universal REST API, it's pretty easy to add more. +Currently only covers (shutters in Supla's lingo), gates, garage doors and switches are supported, but, thanks to comprehensive and universal REST API, it's pretty easy to add more. Right now it's impossible to add a device -- all of them are discovered from Supla Cloud's servers or yours. Devices disabled on Supla Cloud will not be loaded into Home Assistant. diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index 9df9c1422838..1bddf16005d5 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -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 diff --git a/source/_integrations/switcher_kis.markdown b/source/_integrations/switcher_kis.markdown index e070d568a6a4..8f6040710f7f 100644 --- a/source/_integrations/switcher_kis.markdown +++ b/source/_integrations/switcher_kis.markdown @@ -88,5 +88,5 @@ Note: This does not affect the auto off timer. ## Notes -Make sure that Home Assistant host's firewall allows incoming traffic on UDP ports 20002 & 20003 and outgoing connections to Switcher device(s) on TCP ports 9957 & 10000. +Make sure that Home Assistant host's firewall allows incoming traffic on UDP ports 10002, 20002 & 20003 and outgoing connections to Switcher device(s) on TCP ports 9957 & 10000. If Home Assistant and the Switcher device(s) are not on the same network, you will also need to have their traffic properly forwarded between the two networks. diff --git a/source/_integrations/synology_dsm.markdown b/source/_integrations/synology_dsm.markdown index 0f1625639ddc..178fa2c0dc0e 100644 --- a/source/_integrations/synology_dsm.markdown +++ b/source/_integrations/synology_dsm.markdown @@ -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///`. + +This media browser supports multiple Synology Photos instances. `` 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 `` 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 `` of 0 will contain all images. + +For performance reasons, a maximum of 1000 images will be shown in the Media Browser. diff --git a/source/_integrations/tplink_omada.markdown b/source/_integrations/tplink_omada.markdown index e4970b47859a..a860c42b5954 100644 --- a/source/_integrations/tplink_omada.markdown +++ b/source/_integrations/tplink_omada.markdown @@ -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 diff --git a/source/_integrations/tts.markdown b/source/_integrations/tts.markdown index ac1f099411af..5285769032f4 100644 --- a/source/_integrations/tts.markdown +++ b/source/_integrations/tts.markdown @@ -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 -```yaml -# Example configuration.yaml entry for Google TTS service -tts: - - platform: google_translate -``` - -
- -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. - -
+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 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 _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: +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 Translate TTS service -tts: - - platform: google_translate - cache: true - cache_dir: /tmp/tts - time_memory: 300 - service_name: google_say +service: tts.speak +target: tts.example +data: + media_player_entity_id: media_player.kitchen + message: "May the force be with you." ``` +### Service say (legacy) -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. +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. -Say to all `media_player` device entities: +Say to all `media_player` entities: ```yaml # Replace google_translate_say with _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 " \ -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 + +
+ +Depending on your setup, you might need to set an external URL (`external_url`) inside the [configuration](/docs/configuration/basic/). + +
+ +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. diff --git a/source/_integrations/update.mqtt.markdown b/source/_integrations/update.mqtt.markdown index b444cc210f43..62ce2a0fc909 100644 --- a/source/_integrations/update.mqtt.markdown +++ b/source/_integrations/update.mqtt.markdown @@ -109,7 +109,8 @@ device: required: false type: string device_class: - description: The [type/class](/integrations/update/#device-classes) of the update to set the icon in the frontend. + description: The [type/class](/integrations/update/#device-classes) of the update to set the icon in the frontend. The `device_class` can be `null`. + default: None required: false type: device_class default: None diff --git a/source/_integrations/workday.markdown b/source/_integrations/workday.markdown index f8f1a12b3ed1..db41fed3a516 100644 --- a/source/_integrations/workday.markdown +++ b/source/_integrations/workday.markdown @@ -7,6 +7,7 @@ ha_category: ha_iot_class: Local Polling ha_release: 0.41 ha_quality_scale: internal +ha_config_flow: true ha_codeowners: - '@fabaff' - '@gjohansson-ST' @@ -25,127 +26,26 @@ This can be used to make automations that act differently on weekdays vs weekend Check the [country list](https://github.com/dr-prodigy/python-holidays#available-countries) for available provinces (and other subdivisions, like states and territories) for each country. -## Configuration -To enable the `workday` sensor in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -binary_sensor: - - platform: workday - country: DE -``` - -{% configuration %} -name: - description: A name for this sensor. - required: false - type: string - default: Workday Sensor -country: - description: > - Country code according to [holidays](https://pypi.org/project/holidays/) notation. - required: true - type: string -province: - description: Subdivision code according to [holidays](https://pypi.org/project/holidays/) notation. - required: false - type: string -workdays: - description: List of workdays. - required: false - type: list - default: "[mon, tue, wed, thu, fri]" -excludes: - description: List of workday excludes. - required: false - type: list - default: "[sat, sun, holiday]" -days_offset: - description: Set days offset (e.g., -1 for yesterday, 1 for tomorrow). - required: false - type: integer - default: 0 -add_holidays: - description: "Add custom holidays (such as company, personal holidays or vacations). Needs to formatted as `YYYY-MM-DD`." - required: false - type: list -remove_holidays: - description: "Remove holidays (treat holiday as workday). Can be formatted as `YYYY-MM-DD` or by name for a partial string match (e.g. Thanksgiving)." - required: false - type: list -{% endconfiguration %} +{% include integrations/config_flow.md %} Days are specified as follows: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. The keyword `holiday` is used for public holidays identified by the holidays module.
-If you use the sensor for Norway (`NO`) you need to wrap `NO` in quotes or write the name in full. -Otherwise, the value is evaluated as `false`. -If you use the sensor for Canada (`CA`) with Ontario (`ON`) as `province:` then you need to wrap `ON` in quotes. -Otherwise, the value is evaluated as `true` (check the YAML documentation for further details) and the sensor will not work. - -One other thing to watch is how the `holiday` keyword is used. Your first instinct might be to add it to the `exclude` configuration, thinking that it means to skip the holidays. Actually it means to exclude the days in the holidays list from the workdays. So, when you exclude `holiday` and a workday falls on that day, then that workday is excluded, and the sensor will be **off**. If you want every workday flagged with no regard to holidays, make sure that there is something in your `Excludes` configuration _other_ than `holiday`. +Watch how the `holiday` keyword is used. Your first instinct might be adding it to the `exclude` configuration, thinking it means skipping the holidays. It means to exclude the days in the holiday list from the workdays. So, when you exclude `holiday` and a workday falls on that day, that workday is excluded, and the sensor will be **off**. If you want every workday flagged with no regard to holidays, ensure that there is something in your `Excludes` configuration _other_ than `holiday`.
-## Full examples +## Specific field information -This example excludes Saturdays and Sundays but not pre-configured holidays. Two custom holidays are added. +Country code must be given according to [holidays](https://pypi.org/project/holidays/) notation. -```yaml -# Example 1 configuration.yaml entry -binary_sensor: - - platform: workday - country: US - workdays: [mon, tue, wed, thu, fri] - excludes: [sat, sun] - add_holidays: - - "2020-02-24" - - "2020-04-25" -``` +Subdivision code must be given according to [holidays](https://pypi.org/project/holidays/) notation. -This example excludes Saturdays, Sundays and holidays. One custom holiday is added. -The date February 24th, 2020 is a Monday, but will be excluded (the sensor will be **off**) because it was added to the `add_holidays` configuration. +Add holidays will only take dates formatted with `YYYY-MM-DD`. -```yaml -# Example 2 configuration.yaml entry -binary_sensor: - - platform: workday - country: DE - workdays: [mon, tue, wed, thu, fri] - excludes: [sat, sun, holiday] - add_holidays: - - '2020-02-24' -``` - -This example excludes Saturdays, Sundays and holidays. Two holidays are removed: November 26, 2020 and December 25, 2020. - -```yaml -# Example 3 configuration.yaml entry -binary_sensor: - - platform: workday - country: US - workdays: [mon, tue, wed, thu, fri] - excludes: [sat, sun, holiday] - remove_holidays: - - '2020-11-26' - - '2020-12-25' -``` - -This example excludes Saturdays, Sundays and holidays. Two holidays are removed by name: Thanksgiving and Christmas Day. - -```yaml -# Example 4 configuration.yaml entry -binary_sensor: - - platform: workday - country: US - workdays: [mon, tue, wed, thu, fri] - excludes: [sat, sun, holiday] - remove_holidays: - - 'Thanksgiving' - - 'Christmas Day' -``` +Remove holidays will take dates formatted with `YYYY-MM-DD` or partial of name, for example, `christmas` will exclude `Christmas Day`. ## Automation example diff --git a/source/_integrations/xbox_live.markdown b/source/_integrations/xbox_live.markdown deleted file mode 100644 index 2125fdbbe9d4..000000000000 --- a/source/_integrations/xbox_live.markdown +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Xbox Live -description: Instructions on how to set up Xbox Live sensors in Home Assistant. -ha_category: - - Social -ha_iot_class: Cloud Polling -ha_release: 0.28 -ha_codeowners: - - '@MartinHjelmare' -ha_domain: xbox_live -ha_platforms: - - sensor -ha_integration_type: integration ---- - -
- This integration is pending removal from Home Assistant and will be no longer available as of Home Assistant 2023.2. -
- -The Xbox Live integration is able to track [Xbox](https://xbox.com/) profiles. - -To use this sensor you need a free API key from -[xapi.us](https://xapi.us/). -Please also make sure to connect your Xbox account on that site. - -The configuration requires you to specify XUIDs which are the unique identifiers -for profiles. These can be determined on [xapi.us](https://xapi.us/) by -either looking at your own profile page or using their interactive documentation -to search for gamertags. Sensor names default to the gamertag associated with an XUID. - -To use the Xbox Live sensor in your installation, -add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: xbox_live - api_key: YOUR_API_KEY - xuid: - - account1 - - account2 -``` - -{% configuration %} -api_key: - description: Your API key from [xapi.us](https://xapi.us/). - required: true - type: string -xuid: - description: Array of profile XUIDs to be tracked. - required: true - type: list -{% endconfiguration %} diff --git a/source/_integrations/yolink.markdown b/source/_integrations/yolink.markdown index 754a86a1445e..1f8308f705bd 100644 --- a/source/_integrations/yolink.markdown +++ b/source/_integrations/yolink.markdown @@ -56,3 +56,4 @@ The integration is tested and verified for the following devices from YoLink: * YS5707 (Dimmer) * YS6801/2 (MultiOutlet) * YS3604 (FlexFob) +* YS7106 (PowerFailureAlarm) diff --git a/source/_redirects b/source/_redirects index 470319116fbe..34b28af854c8 100644 --- a/source/_redirects +++ b/source/_redirects @@ -263,6 +263,7 @@ /integrations/trace /docs/automation/troubleshooting /integrations/hassio /hassio /integrations/cloud.alexa /cloud/alexa +/integrations/imap_email_content /integrations/imap/#using-events /getting-started/automation-create-first /getting-started/automation /getting-started/automation-2 /getting-started/automation /getting-started/automation-action /docs/automation/action @@ -433,6 +434,7 @@ /integrations/bom /more-info/removed-integration 301 /integrations/ciscospark /more-info/removed-integration 301 /integrations/coinmarketcap /more-info/removed-integration 301 +/integrations/coronavirus /more-info/removed-integration 301 /integrations/crimereports /more-info/removed-integration 301 /integrations/darksky /more-info/removed-integration 301 /integrations/deutsche_bahn /more-info/removed-integration 301 @@ -525,6 +527,7 @@ /integrations/wink /more-info/removed-integration 301 /integrations/wunderground /more-info/removed-integration 301 /integrations/xbee /more-info/removed-integration 301 +/integrations/xbox_live /more-info/removed-integration 301 /integrations/xfinity /more-info/removed-integration 301 /integrations/yessssms /more-info/removed-integration 301 /integrations/yweather /more-info/removed-integration 301 diff --git a/source/images/integrations/androidtv_remote/lovelace_example.png b/source/images/integrations/androidtv_remote/lovelace_example.png new file mode 100644 index 000000000000..ac68b166ad1a Binary files /dev/null and b/source/images/integrations/androidtv_remote/lovelace_example.png differ diff --git a/source/images/integrations/easyenergy/pricegraph.png b/source/images/integrations/easyenergy/pricegraph.png new file mode 100644 index 000000000000..489328cc6c43 Binary files /dev/null and b/source/images/integrations/easyenergy/pricegraph.png differ