From e9ca9821bb963dcb9391a6340cd07ab9dc458e9b Mon Sep 17 00:00:00 2001 From: Aidan Timson Date: Wed, 24 Feb 2021 22:29:50 +0000 Subject: [PATCH 01/65] Update Lyric docs to use config flow include (#16735) --- source/_integrations/lyric.markdown | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/source/_integrations/lyric.markdown b/source/_integrations/lyric.markdown index 583fe46e5539..c274d0328c04 100644 --- a/source/_integrations/lyric.markdown +++ b/source/_integrations/lyric.markdown @@ -34,12 +34,7 @@ lyric: You can then add the integration in the frontend. -## Configuration - -Menu: **Configuration** -> **Integrations**. - -Click on the `+` sign to add an integration and click on **Honeywell Lyric**. -Log in with your Honeywell Lyric account and agree to the terms. The Honeywell Lyric integration will then be available. +{% include integrations/config_flow.md %} ## Sensors From 9694859482ff88fe81e41f48fdb7cda800940e34 Mon Sep 17 00:00:00 2001 From: Nathan Spencer Date: Wed, 24 Feb 2021 18:03:49 -0700 Subject: [PATCH 02/65] Adjust wording and add ha_platforms in Litter-Robot documentation (#16737) --- source/_integrations/litterrobot.markdown | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/source/_integrations/litterrobot.markdown b/source/_integrations/litterrobot.markdown index b5def7d9fff3..96e769609aed 100644 --- a/source/_integrations/litterrobot.markdown +++ b/source/_integrations/litterrobot.markdown @@ -10,21 +10,23 @@ ha_quality_scale: gold ha_codeowners: - '@natekspencer' ha_domain: litterrobot +ha_platforms: + - sensor + - switch + - vacuum --- The Litter-Robot integration allows you to control and monitor your Wi-Fi-enabled, automatic, self-cleaning litter box for cats. You will need a Litter-Robot account as well as a Wi-Fi-enabled Litter-Robot unit that has already been associated with your account. -There is currently support for the following device types within Home Assistant: - -- Vacuum (this is the representation of your Litter-Robot litter box) +The Feeder-Robot is not currently supported by this integration. {% include integrations/config_flow.md %} ## Entities -The following entities are created for this component: +The following entities are created for this component and identified by a single device per Litter-Robot unit: | Entity | Domain | Description | | ---------------- | -------- | -------------------------------------------------------------------------------- | @@ -33,15 +35,13 @@ The following entities are created for this component: | Panel Lockout | `switch` | When turned on, disables the buttons on the unit to prevent changes to settings. | | Waste Drawer | `sensor` | Displays the current waste level gauge. | -All of the entities above are grouped together and identified by a single device. - -## Attributes +## Additional Attributes Some entities have attributes in addition to the default ones that are available for that platform. They are listed below. ### Litter Box `vacuum` entity -| Attribute | Type | Definition | +| Attribute | Type | Description | | ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | clean_cycle_wait_time_minutes | integer | Current wait time, in minutes, between when your cat uses the Litter-Robot and when the unit cycles automatically. | | is_sleeping | boolean | Whether or not the unit is currently in sleep mode. | @@ -53,7 +53,7 @@ Some entities have attributes in addition to the default ones that are available ### Waste Drawer `sensor` entity -| Attribute | Type | Definition | +| Attribute | Type | Description | | ------------------------ | ------- | ------------------------------------------------------------------------ | | cycle_count | integer | Number of clean cycles performed since last reset. | | cycle_capacity | integer | Number of clean cycles before unit is full. | @@ -61,7 +61,7 @@ Some entities have attributes in addition to the default ones that are available ## Commands -In addition to the entities that are created above, some commands are utilized for additional functionality that is available in the Litter-Robot companion app. +Commands are utilized for additional functionality that is available in the Litter-Robot companion app. The following are currently available: ### reset_waste_drawer From c0b7a9b0a41b21078a0d7f20579844f16c5bf376 Mon Sep 17 00:00:00 2001 From: starkillerOG Date: Thu, 25 Feb 2021 13:18:31 +0100 Subject: [PATCH 03/65] Add Xiaomi Miio fan config flow (#16683) --- source/_integrations/xiaomi_miio.markdown | 38 +++++------------------ 1 file changed, 7 insertions(+), 31 deletions(-) diff --git a/source/_integrations/xiaomi_miio.markdown b/source/_integrations/xiaomi_miio.markdown index c08b76da8994..c2e4adad542e 100644 --- a/source/_integrations/xiaomi_miio.markdown +++ b/source/_integrations/xiaomi_miio.markdown @@ -350,6 +350,13 @@ Supported devices: | Air Humidifier CB1 | zhimi.humidifier.cb1 | | | Air Fresh VA2 | zhimi.airfresh.va2 | | + +### Configuration + +Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token to use during configuration flow setup. + +To add a Xiaomi Air Purifier to your installation, click Configuration in the sidebar, then click Integrations and then click the + icon in the lower right and find xiaomi_miio. You will then be presented with a form in which you will need to fill in the “IP address” and 32 characters “token”. After you click submit, you will have the opportunity to select the area that your devices are located. + ### Features ### Air Purifier 2 et al. @@ -677,37 +684,6 @@ This model uses newer MiOT communication protocol. - `motor_speed` - `extra_features` -Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file. - -To add a Xiaomi Air Purifier to your installation, add the following to your `configuration.yaml` file: - -```yaml -fan: -# Example configuration.yaml entry - - platform: xiaomi_miio - host: 192.168.130.66 - token: YOUR_TOKEN -``` - -{% configuration %} -host: - description: The IP address of your miio fan. - required: true - type: string -token: - description: The API token of your miio fan. - required: true - type: string -name: - description: The name of your miio fan. - required: false - type: string - default: Xiaomi Air Purifier -model: - description: The model of your miio fan. See the table above for valid values (f.e. `zhimi.airpurifier.v2`). This setting can be used to bypass the device model detection and is recommended if your device isn't always available. - required: false - type: string -{% endconfiguration %} ### Platform Services From d1294d1b840f6eec21ab62560820176d193a178f Mon Sep 17 00:00:00 2001 From: Hmmbob <33529490+hmmbob@users.noreply.github.com> Date: Thu, 25 Feb 2021 13:44:20 +0100 Subject: [PATCH 04/65] Remove docs for removed keyring/credstash options (#16745) --- source/_docs/configuration/secrets.markdown | 8 +--- source/_docs/tools/credstash.markdown | 35 ------------------ source/_docs/tools/keyring.markdown | 39 -------------------- source/_includes/asides/docs_navigation.html | 2 - source/_redirects | 2 + 5 files changed, 3 insertions(+), 83 deletions(-) delete mode 100644 source/_docs/tools/credstash.markdown delete mode 100644 source/_docs/tools/keyring.markdown diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown index 23a68d3c8377..8dec4f4c6c53 100644 --- a/source/_docs/configuration/secrets.markdown +++ b/source/_docs/configuration/secrets.markdown @@ -38,8 +38,7 @@ http_password: YOUR_PASSWORD When you start splitting your configuration into multiple files, you might end up with configuration in sub folders. Secrets will be resolved in this order: - A `secrets.yaml` located in the same folder as the YAML file referencing the secret, -- next, parent folders will be searched for a `secrets.yaml` file with the secret, stopping at the folder with the main `configuration.yaml`, -- lastly, `keyring` will be queried for the secret (more info below). +- next, parent folders will be searched for a `secrets.yaml` file with the secret, stopping at the folder with the main `configuration.yaml`. To see where secrets are being loaded from, you can either add an option to your `secrets.yaml` file or use the `check_config` script. @@ -58,8 +57,3 @@ hass --script check_config --secrets ``` This will print all your secrets. - -## Alternatives to `secrets.yaml` - -- [Using a keyring that is managed by your OS to store secrets](/docs/tools/keyring/) -- [Storing passwords securely in AWS](/docs/tools/credstash/) diff --git a/source/_docs/tools/credstash.markdown b/source/_docs/tools/credstash.markdown deleted file mode 100644 index 5560cd7d39e6..000000000000 --- a/source/_docs/tools/credstash.markdown +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: "credstash" -description: "Script to store credentials securely in AWS" ---- - -

-This feature has been deprecated and will be removed in March 2021. -

- -Using [Credstash](https://github.com/fugue/credstash) is an alternative way to `secrets.yaml`. They can be managed from the command line via the credstash script. - -Before using credstash, you need to set up AWS credentials either via the `aws` command line tool or using environment variables as explained in the [AWS CLI documentation](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) as well as creating a KMS key named `credstash` as explained in the [credstash Readme](https://github.com/fugue/credstash#setting-up-kms). After that is complete, you can use the provided script to add secrets to your Home Assistant secret store in credstash. - -```bash -hass --script credstash --help -``` - -To store a password in credstash, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file. - -```yaml -example: - password: !secret example_password -``` - -Create an entry in your credstash store. - -```bash -hass --script credstash put http_password 123 -``` - -List your secrets. - -```bash -hass --script credstash list -``` diff --git a/source/_docs/tools/keyring.markdown b/source/_docs/tools/keyring.markdown deleted file mode 100644 index c146440ae20e..000000000000 --- a/source/_docs/tools/keyring.markdown +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: "keyring" -description: "Script to store secrets in a keyring" ---- - -

-This feature has been deprecated and will be removed in March 2021. -

- -Using [Keyring](https://github.com/jaraco/keyring) is an alternative way to `secrets.yaml`. The secrets can be managed from the command line via the `keyring` script. - -```bash -hass --script keyring --help -``` - -To store a password in keyring, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file. - -```yaml -integration1: - api_key: !secret integration1_key -``` - -Create an entry in your keyring. - -```bash -hass --script keyring set integration1_key -``` - -If you launch Home Assistant now, you will be prompted for the keyring password to unlock your keyring. - -```bash -$ hass -Config directory: /home/homeassistant/.homeassistant -Please enter password for encrypted keyring: -``` - -
-If you are using the Python Keyring, automatic starting of Home Assistant Core will no longer work. -
diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index 632e1dd44616..a7546728ac30 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -146,8 +146,6 @@

Topics

  • {% active_link /docs/tools/quick-bar/ Quick Bar %}
  • {% active_link /docs/tools/hass/ hass %}
  • {% active_link /docs/tools/check_config/ check_config %}
    • -
  • {% active_link /docs/tools/credstash/ credstash %}
    • -
  • {% active_link /docs/tools/keyring/ keyring %}
  • diff --git a/source/_redirects b/source/_redirects index 89a69feb2195..f4bc0b59b4a5 100644 --- a/source/_redirects +++ b/source/_redirects @@ -2190,6 +2190,8 @@ /docs/installation/raspberry-pi-all-in-one /getting-started /getting-started/hassbian /getting-started /getting-started/installation-raspberry-pi-all-in-one /getting-started +/docs/tools/keyring/ /docs/configuration/secrets +/docs/tools/credstash/ /docs/configuration/secrets # Blog /blog/2019/05/29/release-94 /blog/2019/06/05/release-94 From 0e86e8e9e5a17dddbb1868ccd344f1971288f96b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joakim=20S=C3=B8rensen?= Date: Thu, 25 Feb 2021 16:28:03 +0100 Subject: [PATCH 05/65] Fix style for my integration button (#16746) --- sass/custom/_paulus.scss | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index 8c37c81f9fe5..e313c289ff99 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -460,6 +460,8 @@ div.note { .brand-logo-container { text-align: center; margin-top: 50px; + display: grid; + justify-items: center; img { max-height: 67px; From 5e595693508f0e6eeea783c845bfaad7b8d5eb4b Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 26 Feb 2021 10:41:26 +0100 Subject: [PATCH 06/65] Document value_template in MQTT triggers (#16754) --- source/_docs/automation/trigger.markdown | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index 04e7bc513636..75d5c6471b8c 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -97,6 +97,18 @@ automation: encoding: "utf-8" ``` +The `payload` option can be combined with a `value_template` to process the message received on the given MQTT topic before matching it with the payload. +The trigger in the example below will trigger only when the message received on `living_room/switch/ac` is valid JSON, with a key `state` which has the value `"on"`. + +```yaml +automation: + trigger: + platform: mqtt + topic: "living_room/switch/ac" + payload: "on" + value_template: "{{ value_json.state }}" +``` + It's also possible to use [limited templates](/docs/configuration/templating/#limited-templates) in the `topic` and `payload` options.
    From 39d3a758aee2719af8948016ccca7b0cfb5c3f21 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 26 Feb 2021 10:49:35 +0100 Subject: [PATCH 07/65] Fix MQTT trigger value_template example (#16755) --- source/_docs/automation/trigger.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index 75d5c6471b8c..d4642e31cd1b 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -100,6 +100,8 @@ automation: The `payload` option can be combined with a `value_template` to process the message received on the given MQTT topic before matching it with the payload. The trigger in the example below will trigger only when the message received on `living_room/switch/ac` is valid JSON, with a key `state` which has the value `"on"`. +{% raw %} + ```yaml automation: trigger: @@ -109,6 +111,8 @@ automation: value_template: "{{ value_json.state }}" ``` +{% endraw %} + It's also possible to use [limited templates](/docs/configuration/templating/#limited-templates) in the `topic` and `payload` options.
    From 268f1fb25e6300e49489ea183c893f1cb99be801 Mon Sep 17 00:00:00 2001 From: Joakim Plate Date: Fri, 26 Feb 2021 18:35:06 +0100 Subject: [PATCH 08/65] Add support for v6 features to philips js integration (#16628) Co-authored-by: Klaas Schoute --- source/_integrations/philips_js.markdown | 27 +++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/source/_integrations/philips_js.markdown b/source/_integrations/philips_js.markdown index b4aa566e9963..aa3316e9a177 100644 --- a/source/_integrations/philips_js.markdown +++ b/source/_integrations/philips_js.markdown @@ -11,10 +11,31 @@ ha_domain: philips_js ha_config_flow: true --- -The `philips_js` platform allows you to control Philips TVs which expose the [jointSPACE](http://jointspace.sourceforge.net/) JSON-API. Instructions on how to activate the API and if your model is supported can be found [here](http://jointspace.sourceforge.net/download.html). Note that not all listed, jointSPACE-enabled devices will have JSON-interface running on port 1925. This is true at least for some models before year 2011. +The `philips_js` platform allows you to control Philips TVs which expose the [jointSPACE](http://jointspace.sourceforge.net/) JSON-API. -To enable the integration go to **Configuration** -> **Integrations** +Instructions on how to activate the API and if your model is supported can be found [here](http://jointspace.sourceforge.net/download.html). Note that not all listed, jointSPACE-enabled devices will have JSON-interface running on port 1925. This is true at least for some models before year 2011. + +{% include integrations/config_flow.md %} + +### Features + +| Feature | 1 | 5 | 6 (Android) | 6 (Saphi) | +| ------------------ | ---------------- | --- | ------------------ | ---------------- | +| Power On | WOL / IR Blaster | ? | Yes (if always on) | WOL / IR Blaster | +| Volume Detect | Yes | ? | Yes (not over CEC) | ? | +| Volume Up/Down | Yes | ? | Yes | No | +| Volume Set | Yes | ? | Yes | ? | +| Source Select | Yes | ? | Yes | No | +| Source Detect | Yes | ? | No | No | +| Channel Select | Yes | ? | Yes | ? | +| Channel Detect | Yes | ? | Yes | ? | +| Channel Favorites | No | ? | Yes | ? | +| Application Select | No | ? | Yes | No | +| Application Detect | No | ? | Yes | No | +| Browse URL | No | No | No | No | +| Send Key | No | No | No | No | +| Ambilight Control | No | No | No | No | ### Turn on device -The Philips TV does not support turning on via the API. You can either turn it on via IR blaster to or on som models WOL. To trigger this command from the entities, the integration exposes a `device trigger` that can be setup to execute when the `media_player` is asked to turn on. +The Philips TV does not always support turning on via the API. You can either turn it on via IR blaster or on som models WOL. To trigger this command from the entities, the integration exposes a `device trigger` that can be setup to execute when the `media_player` is asked to turn on. From ca9524323013df340408167f2bbe014f8fc2e5dc Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Mon, 1 Mar 2021 08:27:15 -0600 Subject: [PATCH 09/65] Remove griddy integration (#16790) --- source/_integrations/griddy.markdown | 53 ---------------------------- source/_redirects | 1 + 2 files changed, 1 insertion(+), 53 deletions(-) delete mode 100644 source/_integrations/griddy.markdown diff --git a/source/_integrations/griddy.markdown b/source/_integrations/griddy.markdown deleted file mode 100644 index 2823de39722a..000000000000 --- a/source/_integrations/griddy.markdown +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Griddy Power -description: Instructions on how to integrate griddy real-time electricity prices into Home Assistant. -ha_category: - - Energy - - Sensor -ha_release: 0.107 -ha_iot_class: Cloud Polling -ha_config_flow: true -ha_codeowners: - - '@bdraco' -ha_domain: griddy -ha_platforms: - - sensor ---- - -The `griddy` integration allows you to integrate your [Griddy](https://griddy.com/) price data into Home Assistant. - -There is currently support for the following device types within Home Assistant: - -- Sensor - -## Prerequisites - -You will need your Griddy Load Zone to use this module. - -{% include integrations/config_flow.md %} - -### Sensor - -The current price for the Load Zone will appear as a sensor: - -- LZ_XXXXX Price Now - -### Example Automation - -```yaml -- id: '1572630019168' - alias: "Stop Tesla Charging if Power Price Spikes" - description: "" - trigger: - - above: '30' - entity_id: sensor.lz_houston_price_now - platform: numeric_state - condition: - - condition: zone - entity_id: device_tracker.my_tesla - zone: zone.home - action: - - service: switch.turn_off - target: - entity_id: switch.my_tesla_charger_switch -``` diff --git a/source/_redirects b/source/_redirects index f4bc0b59b4a5..22d4f185a06c 100644 --- a/source/_redirects +++ b/source/_redirects @@ -2285,3 +2285,4 @@ /components/sensor.coinmarketcap /more-info/removed-integration 301 /components/coinmarketcap /more-info/removed-integration 301 /integrations/coinmarketcap /more-info/removed-integration 301 +/integrations/griddy /more-info/removed-integration 301 From 0ad4b123275cc477010cb7288755059987d8b5cc Mon Sep 17 00:00:00 2001 From: Anders Melchiorsen Date: Mon, 1 Mar 2021 20:08:14 +0100 Subject: [PATCH 10/65] Clarify template trigger behaviour (#16733) --- source/_docs/automation/trigger.markdown | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index d4642e31cd1b..55ee1a5d69d9 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -465,8 +465,11 @@ automation: ### Template trigger -Template triggers work by evaluating a [template](/docs/configuration/templating/) on every state change for all of the recognized entities. The trigger will fire if the state change caused the template to render 'true'. This is achieved by having the template result in a true boolean expression (`{% raw %}{{ is_state('device_tracker.paulus', 'home') }}{% endraw %}`) or by having the template render 'true' (example below). Being a boolean expression the template must evaluate to false (or anything other than true) before the trigger will fire again. -With template triggers you can also evaluate attribute changes by using is_state_attr (`{% raw %}{{ is_state_attr('climate.living_room', 'away_mode', 'off') }}{% endraw %}`) +Template triggers work by evaluating a [template](/docs/configuration/templating/) when any of the recognized entities change state. The trigger will fire if the state change caused the template to render 'true' (a non-zero number or any of the strings `true`, `yes`, `on`, `enable`) when it was previously 'false' (anything else). + +This is achieved by having the template result in a true boolean expression (for example `{% raw %}{{ is_state('device_tracker.paulus', 'home') }}{% endraw %}`) or by having the template render `true` (example below). + +With template triggers you can also evaluate attribute changes by using is_state_attr (like `{% raw %}{{ is_state_attr('climate.living_room', 'away_mode', 'off') }}{% endraw %}`) {% raw %} @@ -497,9 +500,9 @@ automation: {% endraw %} -The `for` template(s) will be evaluated when the `value_template` becomes `true`. +The `for` template(s) will be evaluated when the `value_template` becomes 'true'. -Templates that don't contain an entity will be rendered once per minute. +Templates that do not contain an entity will be rendered once per minute. ### Time trigger From 0148f5a3c12cb91aa5ac6d60eed12b642750980f Mon Sep 17 00:00:00 2001 From: Raman Gupta <7243222+raman325@users.noreply.github.com> Date: Tue, 2 Mar 2021 05:17:36 -0500 Subject: [PATCH 11/65] Update Z-Wave JS limitations for next release (#16796) --- source/_integrations/zwave_js.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/zwave_js.markdown b/source/_integrations/zwave_js.markdown index f5ecc35cdd63..70d4d8e72ed8 100644 --- a/source/_integrations/zwave_js.markdown +++ b/source/_integrations/zwave_js.markdown @@ -103,6 +103,7 @@ data: parameter: "LED 1 Blink Status (bottom)" value: "Blink" ``` + ### Service `zwave_js.refresh_value` This service will refresh the value(s) for an entity. This service will generate extra traffic on your Z-Wave network and should be used sparingly. Updates from devices on battery may take some time to be received. @@ -181,8 +182,7 @@ Value Notification example: As this integration is still in the early stages there are some important limitations to be aware of. - While support for the most common devices is working, some command classes are not yet (fully) implemented in Z-Wave JS. You can track the status [here](https://github.com/zwave-js/node-zwave-js/issues/6). -- Configuration of Z-Wave nodes and/or configuration with the Home Assistant UI is currently not yet implemented. You will need to use another tool, such as [zwavejs2mqtt](https://github.com/zwave-js/zwavejs2mqtt), to manage device configuration. -- Polling is currently not supported in the integration but will be added soon as a service. +- Configuration of Z-Wave nodes within the Home Assistant UI is not yet implemented, but a [service](#service-zwave_js.set_config_parameter) is available with limited configuration capabilities. If the service doesn't meet your needs, you will need to use another tool, such as [zwavejs2mqtt](https://github.com/zwave-js/zwavejs2mqtt), to manage device configuration. - There currently is no migration path available from any of the other Z-Wave implementations in Home Assistant. Your Z-Wave network is however stored on your stick so migrating will only require you to redo your device and entity naming. You can keep track of the Roadmap for the Z-Wave JS integration [here](https://github.com/home-assistant-libs/zwave-js-server-python/issues/56). From 9efbce26f77af179eb12956ab84c226205b93c04 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 2 Mar 2021 14:13:56 +0100 Subject: [PATCH 12/65] My plugin updates (#16806) Co-authored-by: Bram Kragten --- .textlintrc.json | 3 +- plugins/my.rb | 46 +++++++++++++++++-- sass/custom/_paulus.scss | 1 - source/_docs/automation/services.markdown | 10 ++-- source/_docs/automation/templating.markdown | 2 +- .../automation/using_blueprints.markdown | 6 +-- .../asides/component_navigation.html | 2 +- source/_includes/common-tasks/snapshots.md | 18 +++----- source/_includes/integrations/config_flow.md | 4 +- 9 files changed, 61 insertions(+), 31 deletions(-) diff --git a/.textlintrc.json b/.textlintrc.json index 67f435bca753..aaf0c0dcc698 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -173,6 +173,7 @@ "MJPEG", "MQTT", "Mullvad", + "My Home Assistant", "MySensors", "NAS", "NETGEAR", @@ -278,7 +279,6 @@ "XML", "Yamaha MusicCast", "Yamaha", - "YAML", "Yandex", "Yeelight", "YouTube", @@ -302,7 +302,6 @@ ["cancelled", "canceled"], ["client ?side", "client-side"], ["colour", "color"], - ["config\\b", "configuration"], ["DarkSky", "Dark Sky"], ["docs\\b", "documentation"], ["e\\.g\\.", "e.g.,"], diff --git a/plugins/my.rb b/plugins/my.rb index 948e7efaf067..b785fb737f14 100644 --- a/plugins/my.rb +++ b/plugins/my.rb @@ -12,11 +12,11 @@ def initialize(tag_name, args, tokens) else raise SyntaxError, <<~MSG Syntax error in tag 'my' while parsing the following options: - ` + #{args} Valid syntax: - {% my [title="Link name"] [badge] [icon[="icon-puzzle-piece"]] [addon="core_ssh"] [blueprint_url=""] [domain="hue"] %} + {% my [title="Link name"] [badge] [icon[="icon-puzzle-piece"]] [addon="core_ssh"] [blueprint_url="http://example.com/blueprint.yaml"] [domain="hue"] [service="light.turn_on"] %} MSG end end @@ -33,24 +33,39 @@ def render(context) query += [["addon", options[:addon]]] if options.include? :addon query += [["blueprint_url", options[:blueprint_url]]] if options.include? :blueprint_url query += [["domain", options[:domain]]] if options.include? :domain + query += [["service", options[:service]]] if options.include? :service unless query.empty? uri.query = URI.encode_www_form(query) end if options[:badge] - title = options[:title] ? options[:title].gsub(/\ /, '_') : @redirect + raise ArgumentError, "Badges cannot have custom titles" if options[:title] ""\ - ""\ + ""\ "" else - title = options[:title] ? options[:title] : @redirect.gsub(/_/, ' ').titlecase + title = @redirect.gsub(/_/, ' ').titlecase icon = "" + + if options[:title] + # Custom title + title = options[:title] + elsif @redirect == "developer_call_service" + # Developer service call + title = "Call Service" + title = "`#{options[:service]}`" if options.include? :service + elsif DEFAULT_TITLES.include?(@redirect) + # Lookup defaults + title = DEFAULT_TITLES[@redirect] + end + if options[:icon] raise ArgumentError, "No default icon for redirect #{@redirect}" \ if !!options[:icon] == options[:icon] and ! DEFAULT_ICONS.include?(@redirect) icon = !!options[:icon] == options[:icon] ? DEFAULT_ICONS[@redirect] : @options[:icon] icon = " " end + "#{icon}#{title}" end end @@ -60,11 +75,32 @@ def render(context) SYNTAX = %r!^([a-z_]+)((\s+\w+(=([\w\.]+?|".+?"))?)*)$!.freeze OPTIONS_REGEX = %r!(?:\w="[^"]*"|\w=[\w\.]+|\w)+!.freeze + # Default icons when used in in-line text DEFAULT_ICONS = { "config_flow_start" => "icon-plus-sign", + "config" => "icon-cog", "integrations" => "icon-puzzle-piece", } + # Default title used for in-line text + DEFAULT_TITLES = { + "blueprint_import" => "Import Blueprint", + "cloud" => "Home Assistant Cloud", + "config_flow_start" => "Add Integration", + "config_mqtt" => "MQTT Configuration", + "config_zha" => "ZHA Configuration", + "config_zwave_js" => "Z-Wave JS Configuration", + "config" => "Configuration", + "developer_events" => "Events", + "developer_services" => "Services", + "developer_states" => "States", + "developer_template" => "Templates", + "general" => "General Settings", + "info" => "Information", + "supervisor_info" => "Supervisor Information", + "supervisor_snapshots" => "Snapshots", + } + def parse_options(input, context) options = {} return options if input.empty? diff --git a/sass/custom/_paulus.scss b/sass/custom/_paulus.scss index e313c289ff99..2dba14063b29 100644 --- a/sass/custom/_paulus.scss +++ b/sass/custom/_paulus.scss @@ -676,6 +676,5 @@ code { a.my { img { border: 0px; - border-radius: 3px; } } diff --git a/source/_docs/automation/services.markdown b/source/_docs/automation/services.markdown index 57525889bde4..40e9ceaf90db 100644 --- a/source/_docs/automation/services.markdown +++ b/source/_docs/automation/services.markdown @@ -5,7 +5,7 @@ description: "How to use the various automation services." The automation integration has services to control automations, like turning automations on and off. This can be useful if you want to disable an automation from another automation. -## Service `automation.turn_on` +## Service {% my developer_call_service service="automation.turn_on" %} This service enables the automation's triggers. @@ -13,7 +13,7 @@ Service data attribute | Optional | Description -|-|- `entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted. -## Service `automation.turn_off` +## Service {% my developer_call_service service="automation.turn_off" %} This service disables the automation's triggers, and optionally stops any currently active actions. @@ -22,7 +22,7 @@ Service data attribute | Optional | Description `entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted. `stop_actions` | yes | Stop any currently active actions (defaults to true). -## Service `automation.toggle` +## Service {% my developer_call_service service="automation.toggle" %} This service enables the automation's triggers if they were disabled, or disables the automation's triggers, and stops any currently active actions, if the triggers were enabled. @@ -30,7 +30,7 @@ Service data attribute | Optional | Description -|-|- `entity_id` | no | Entity ID of automation to turn on. Can be a list. `none` or `all` are also accepted. -## Service `automation.trigger` +## Service {% my developer_call_service service="automation.trigger" %} This service will trigger the action of an automation. By default it bypasses any conditions, though that can be changed via the `skip_condition` attribute. @@ -39,7 +39,7 @@ Service data attribute | Optional | Description `entity_id` | no | Entity ID of automation to trigger. Can be a list. `none` or `all` are also accepted. `skip_condition` | yes | Whether or not the condition will be skipped (defaults to true). -## Service `automation.reload` +## Service {% my developer_call_service service="automation.reload" %} _This service is only required if you create/edit automations in YAML. Automations via the UI do this automatically._ diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown index 15baca1e9311..0b72cd1e4593 100644 --- a/source/_docs/automation/templating.markdown +++ b/source/_docs/automation/templating.markdown @@ -7,7 +7,7 @@ Automations support [templating](/docs/configuration/templating/) in the same wa
    - Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in Developer Tools > Template together with your trigger's definition like: + Be aware that if you reference a `trigger` state object in templates of an automation' `action` or `condition` sections, attempting to test that automation by calling the `automation.trigger` service or by clicking EXECUTE in the More Info box for the automation will not work. This is because the trigger state object doesn't exist in those contexts. One way to test automations like these is to manually check that the templates work as expected by pasting them in {% my developer_template title="Developer Tools > Template" %} together with your trigger's definition like: {%raw%} diff --git a/source/_docs/automation/using_blueprints.markdown b/source/_docs/automation/using_blueprints.markdown index 5f10a2d25a1a..a17617bacd12 100644 --- a/source/_docs/automation/using_blueprints.markdown +++ b/source/_docs/automation/using_blueprints.markdown @@ -13,11 +13,11 @@ Quick links: Automations based on a blueprint only need to be configured to be used. What needs to be configured differs on each blueprint. -To create your first automation based on a blueprint, go to **Configuration** and then **Blueprints**. Find the blueprint that you want to use and click on "Create Automation". +To create your first automation based on a blueprint, go to **{% my config %}** and then **{% my blueprints %}**. Find the blueprint that you want to use and click on "Create Automation". This will open the automation editor with the blueprint selected. Give it a name and configure the blueprint and click on the blue button "Save Automation" in the bottom right. -Done! If you want to revisit the configuration values, you can find it by going to **Configuration** and then **Automations**. +Done! If you want to revisit the configuration values, you can find it by going to **{% my config %}** and then **{% my automations %}**. ## Importing blueprints @@ -29,7 +29,7 @@ To do this, first [find a blueprint you want to import][blueprint-forums]. If yo https://github.com/home-assistant/core/blob/dev/homeassistant/components/automation/blueprints/motion_light.yaml ``` -Go to **Configuration** and then **Blueprints**. Click on the blue "Import Blueprint" button in the bottom right. +Go to **{% my config %}** and then **{% my blueprints %}**. Click on the blue "{% my blueprint_import blueprint="https://github.com/home-assistant/core/blob/master/homeassistant/components/automation/blueprints/motion_light.yaml" %} button in the bottom right. A new dialog will pop-up asking you for the URL. Enter the URL and click on "preview blueprint". diff --git a/source/_includes/asides/component_navigation.html b/source/_includes/asides/component_navigation.html index e93dfc2c5a90..75a809b53997 100644 --- a/source/_includes/asides/component_navigation.html +++ b/source/_includes/asides/component_navigation.html @@ -8,7 +8,7 @@ {%- endif -%} {%- if page.ha_config_flow and page.ha_domain -%} - {% my config_flow_start badge title="Add Integration" domain=page.ha_domain %} + {% my config_flow_start badge domain=page.ha_domain %} {%- endif -%}
    diff --git a/source/_includes/common-tasks/snapshots.md b/source/_includes/common-tasks/snapshots.md index b806173f345e..49f33abd9505 100644 --- a/source/_includes/common-tasks/snapshots.md +++ b/source/_includes/common-tasks/snapshots.md @@ -14,7 +14,7 @@ A partial snapshot consists of any number of the above default directories and i ### Making a Snapshot from the UI -1. Go to Supervisor > Snapshots in the UI +1. Go to {% my supervisor_snapshots title="Supervisor > Snapshots" %} in the UI 2. Provide a name for the snapshot. 3. Choose full or partial. 4. Choose to password protect or not. Password protected snapshots cannot easily be browsed outside of Home Assistant OS @@ -33,7 +33,7 @@ When the upload is completed, you will be presented with the snapshot restore di If the snapshot you are uploading is more than 1GB in size, it can be faster and more efficient to make use of the Samba add-on in order to transfer files to the `/backup` directory. -The length of time it takes to create or restore snapshots will depend on how much you have to compress or decompress. +The length of time it takes to create or restore snapshots will depend on how much you have to compress or decompress. If you're looking to slim down your snapshots, check if your configuration directory contains a large database file (`home-assistant_v2.db`). See the [`recorder`](https://www.home-assistant.io/components/recorder/) integration page for options to keep your database data down to a size that won't cause issues. Note the keep days, purge interval, and include/exclude options. @@ -52,12 +52,8 @@ Use `ha help` to see more info. You often need a snapshot in case your system has crashed. If you only store them on the crashed device, you won't be able to access it easily. We recommend that you manually copy them from `/backup` to another machine on occasion. Or even better, create an automation to handle that, or make use of one of the following add-ons: - - [Google Drive Backup](https://github.com/sabeechen/hassio-google-drive-backup) - - - [Dropbox Sync](https://github.com/danielwelch/hassio-dropbox-sync) - - - [Nextcloud Backup](https://github.com/Sebclem/hassio-nextcloud-backup) - - - [Samba backup](https://github.com/thomasmauerer/hassio-addons/tree/master/samba-backup) - - - [Remote Backup (uses scp)](https://github.com/overkill32/hassio-remote-backup) \ No newline at end of file +- [Google Drive Backup](https://github.com/sabeechen/hassio-google-drive-backup) +- [Dropbox Sync](https://github.com/danielwelch/hassio-dropbox-sync) +- [Nextcloud Backup](https://github.com/Sebclem/hassio-nextcloud-backup) +- [Samba backup](https://github.com/thomasmauerer/hassio-addons/tree/master/samba-backup) +- [Remote Backup (uses scp)](https://github.com/overkill32/hassio-remote-backup) diff --git a/source/_includes/integrations/config_flow.md b/source/_includes/integrations/config_flow.md index ff49aa3acb32..20c04db3e1a6 100644 --- a/source/_includes/integrations/config_flow.md +++ b/source/_includes/integrations/config_flow.md @@ -6,7 +6,7 @@ Adding {{ name }} to your Home Assistant instance can be done via the user interface, by taking the following steps: - Browse to your Home Assistant instance. -- In the sidebar click on _**Configuration**_. +- In the sidebar click on _**{% my config icon %}**_. - From the configuration menu select: _**{% my integrations icon %}**_. {% if include.discovery or page.ha_dhcp or page.ha_homekit or page.ha_ssdp or page.ha_zeroconf %} @@ -20,7 +20,7 @@ manual integration entry: {% endif %} - In the bottom right, click on the - _**{% my config_flow_start icon title="Add Integration" domain=page.ha_domain %}**_ button. + _**{% my config_flow_start icon domain=page.ha_domain %}**_ button. - From the list, search and select _**"{{ name }}"**_. - Follow the instruction on screen to complete the set up. From f467f4929b6d1ed2617000206c236051fdbf2798 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 2 Mar 2021 21:14:00 +0100 Subject: [PATCH 13/65] Add more My links (#16816) --- source/_docs/authentication/multi-factor-auth.markdown | 6 +++--- source/_docs/authentication/providers.markdown | 2 +- source/_docs/automation/basics.markdown | 4 ++-- source/_docs/automation/editor.markdown | 5 +++-- source/_docs/automation/troubleshooting.markdown | 4 ++-- source/_docs/automation/yaml.markdown | 2 +- source/_docs/blueprint/tutorial.markdown | 2 +- source/_docs/configuration/basic.markdown | 2 +- source/_docs/configuration/devices.markdown | 2 +- source/_docs/configuration/splitting_configuration.markdown | 2 +- source/_docs/configuration/templating.markdown | 2 +- source/_integrations/xbox.markdown | 2 +- source/_integrations/zwave_js.markdown | 2 +- 13 files changed, 19 insertions(+), 18 deletions(-) diff --git a/source/_docs/authentication/multi-factor-auth.markdown b/source/_docs/authentication/multi-factor-auth.markdown index 47969af1deea..d295b48b4bec 100644 --- a/source/_docs/authentication/multi-factor-auth.markdown +++ b/source/_docs/authentication/multi-factor-auth.markdown @@ -36,9 +36,9 @@ If no `auth_mfa_modules` configuration section is defined in `configuration.yaml You will need an authenticator app on your phone. We recommend either [Google Authenticator](https://support.google.com/accounts/answer/1066447) or [Authy](https://authy.com/). Both are available for iOS or Android. -After restarting Home Assistant, go to your [profile page](/docs/authentication/#your-account-profile) and there should be a "Multi-factor Authentication Modules" section. +After restarting Home Assistant, go to your {% my profile %} and there should be a "Multi-factor Authentication Modules" section. -Click _Enable_ and a new secret key will be generated. Go to your phone app and enter the key, either by scanning the QR code or typing in the key below the QR code manually. +Click _Enable_ and a new secret key will be generated. Go to your phone app and enter the key, either by scanning the QR code or typing in the key below the QR code manually. Screenshot of setting up multi-factor authentication @@ -99,7 +99,7 @@ homeassistant: message: "I almost forget, to get into my clubhouse, you need to say {}" ``` -After restarting Home Assistant, go to your [profile page](/docs/authentication/#your-account-profile) and there should be a "Multi-factor Authentication Modules" section. Click _Enable_ on the _Notify One-Time Password_ option. +After restarting Home Assistant, go to your {% my profile %} and there should be a "Multi-factor Authentication Modules" section. Click _Enable_ on the _Notify One-Time Password_ option. Try logging out, then logging in again. You will be asked for the six-digit one-time password that was sent to your notify service. Enter the password to log in. diff --git a/source/_docs/authentication/providers.markdown b/source/_docs/authentication/providers.markdown index a8003727e372..c414de45e3f4 100644 --- a/source/_docs/authentication/providers.markdown +++ b/source/_docs/authentication/providers.markdown @@ -37,7 +37,7 @@ This is the default auth provider. The first user created is designated as the _ User details are stored in the `[your config]/.storage` directory. All passwords are stored hashed and with a salt, making it almost impossible for an attacker to figure out the password even if they have access to the file. -Users can be managed in Home Assistant by the owner. Go to the configuration panel and click on _Users_. +Users can be managed in Home Assistant by the owner. Go to the configuration panel and click on _{% my users %}_. This is the entry in `configuration.yaml` for Home Assistant auth: diff --git a/source/_docs/automation/basics.markdown b/source/_docs/automation/basics.markdown index fb46acb9a406..87a1d384f250 100644 --- a/source/_docs/automation/basics.markdown +++ b/source/_docs/automation/basics.markdown @@ -27,7 +27,7 @@ The difference between a condition and a trigger can be confusing as they are ve ## Exploring the internal state -Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. **Developer Tools** -> **States** will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts: +Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. **{% my developer_states title="Developer Tools -> States" %}** will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts: | Name | Description | Example | | ---- | ----- | ---- | @@ -37,7 +37,7 @@ Automation rules interact directly with the internal state of Home Assistant, so State changes can be used as the source of triggers and the current state can be used in conditions. -Actions are all about calling services. To explore the available services open the **Developer Tools** -> **Services**. Services allow changing anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use. +Actions are all about calling services. To explore the available services open the **{% my developer_states title="Developer Tools -> Services" %}**. Services allow changing anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service {% my developer_call_service service="light.turn_on" %} is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use. ## Creating automations diff --git a/source/_docs/automation/editor.markdown b/source/_docs/automation/editor.markdown index 4e51eee8d1cb..a4f8cab57a04 100644 --- a/source/_docs/automation/editor.markdown +++ b/source/_docs/automation/editor.markdown @@ -3,7 +3,7 @@ title: "Automation Editor" description: "Instructions on how to use the automation editor." --- -From the UI choose **Configuration** which is located in the sidebar, then click on **Automation** to go to the automation editor. Press the **+** sign in the lower right corner to get started. This example is based on the manual steps described in the [Getting started section](/getting-started/automation/) for a [`random` sensor](/integrations/random#sensor). +From the UI choose **{% my config %}** which is located in the sidebar, then click on **{% my automations %}** to go to the automation editor. Press the **+** sign in the lower right corner to get started. This example is based on the manual steps described in the [Getting started section](/getting-started/automation/) for a [`random` sensor](/integrations/random#sensor). Choose a meaningful name for your automation rules. @@ -29,4 +29,5 @@ As "Service Data" we want a simple text that is shown as part of the notificatio message: Sensor value greater than 10 ``` -Don't forget to save your new automation rule. For your saved automation rule to come into effect, you will need to go to the **Configuration** page and click on **Reload Automation**. +Automation created or edited via the user interface, are activated immediately +after save the automation. diff --git a/source/_docs/automation/troubleshooting.markdown b/source/_docs/automation/troubleshooting.markdown index 1181dbb4b608..f63899cf9284 100644 --- a/source/_docs/automation/troubleshooting.markdown +++ b/source/_docs/automation/troubleshooting.markdown @@ -27,11 +27,11 @@ Please note that if you click on **Trigger** of an automation in the frontend, * All this makes that Trigger feature pretty limited and nearly useless for debugging purposes so you need to find another way. Make sure you check and adapt to your circumstances appropriate examples from Automation Trigger, Conditions and Actions. -It is also useful to go to **Configuration** -> **Server Control** and click on **Check Configuration** button in Configuration validation section to make sure there are no syntax errors before restarting Home Assistant. In order for **Check configuration** to be visible, you must enable **Advanced Mode** on your user profile. +It is also useful to go to **{% my server_controls title="Configuration -> Server Control" %}** and click on **Check Configuration** button in Configuration validation section to make sure there are no syntax errors before restarting Home Assistant. In order for **Check configuration** to be visible, you must enable **Advanced Mode** on {% my profile title="your user profile" %}. If your automation uses templates in any part, you can do the following to make sure it works as expected: -1. Go to **Developer tools** -> **Template** tab. +1. Go to **{% my developer_templates title="Developer tools -> Template" %}** tab. 2. Create all variables (sources) required for your template as described at the end of [this](https://www.home-assistant.io/docs/configuration/templating/#processing-incoming-data) paragraph. 3. Copy your template code and paste it in Template editor straight after your variables. 4. If necessary, change your sources' value and check if the template works as you want and does not generate any errors. diff --git a/source/_docs/automation/yaml.markdown b/source/_docs/automation/yaml.markdown index 2efe894ad7ee..77a869289f09 100644 --- a/source/_docs/automation/yaml.markdown +++ b/source/_docs/automation/yaml.markdown @@ -148,6 +148,6 @@ If you want to migrate your manual automations to use the editor, you'll have to When automations remain visible in the Home Assistant Dashboard, even after having deleted in the YAML file, you have to delete them in the UI. -To delete them completely, go to UI **Configuration** -> **Entities** and find the automation in the search field or by scrolling down. +To delete them completely, go to UI **{% my entities title="Configuration -> Entities" %}** and find the automation in the search field or by scrolling down. Check the square box aside of the automation you wish to delete and from the top-right of your screen, select 'REMOVE SELECTED'. diff --git a/source/_docs/blueprint/tutorial.markdown b/source/_docs/blueprint/tutorial.markdown index ec95e596db28..d26eaa99bedb 100644 --- a/source/_docs/blueprint/tutorial.markdown +++ b/source/_docs/blueprint/tutorial.markdown @@ -208,7 +208,7 @@ action: ## Use it via the UI -To configure it via the UI, go to **Configuration** and then **Blueprints**. Find the "Motion Light Tutorial" blueprint and click on "Create Automation". +To configure it via the UI, go to **{% my config %}** and then **{% my blueprints %}**. Find the "Motion Light Tutorial" blueprint and click on "Create Automation".
    Don't forget to reload automations after you make changes to your blueprint to have the UI and the automation integration pick up the latest blueprint changes. diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown index 0742a6bd824c..d1d5396947d3 100644 --- a/source/_docs/configuration/basic.markdown +++ b/source/_docs/configuration/basic.markdown @@ -100,4 +100,4 @@ legacy_templates: ## Reload Core Service -Home Assistant offers a service to reload the core configuration while Home Assistant is running called `homeassistant.reload_core_config`. This allows you to change any of the above sections and see it being applied without having to restart Home Assistant. To call this service, go to the "Service" tab under Developer Tools, select the `homeassistant.reload_core_config` service and click the "CALL SERVICE" button. Alternatively, you can press the "Reload Location & Customizations" button under Configuration > Server Control. +Home Assistant offers a service to reload the core configuration while Home Assistant is running called {% my developer_call_service service="homeassistant.reload_core_config" %}. This allows you to change any of the above sections and see it being applied without having to restart Home Assistant. To call this service, go to the "{% my developer_services %}" tab under {% my developer_services title="Developer Tools" %}, select the {% my developer_call_service service="homeassistant.reload_core_config" %} service and click the "CALL SERVICE" button. Alternatively, you can press the "Reload Location & Customizations" button under {% my server_controls title="Configuration > Server Control" %}. diff --git a/source/_docs/configuration/devices.markdown b/source/_docs/configuration/devices.markdown index a170014870ac..0f93b43382a7 100644 --- a/source/_docs/configuration/devices.markdown +++ b/source/_docs/configuration/devices.markdown @@ -62,7 +62,7 @@ switch 2: ## Grouping devices Once you have several devices set up, it is time to organize them into groups. -Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the “States” page in the Developer Tools. +Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the {% my developer_states title="States page in the Developer Tools" %}. ```yaml # Example configuration.yaml entry showing two styles diff --git a/source/_docs/configuration/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown index 642048da29f4..5bfbc9d3233a 100644 --- a/source/_docs/configuration/splitting_configuration.markdown +++ b/source/_docs/configuration/splitting_configuration.markdown @@ -491,7 +491,7 @@ front_yard: ### Example: Combine `!include_dir_merge_list` with `automations.yaml` -You want to go the advanced route and split your automations, but still want to be able to create automations in the UI? +You want to go the advanced route and split your automations, but still want to be able to create {% my automations title="automations in the UI" %}? In a chapter above we write about nesting `!includes`. Here is how we can do that for automations. Using labels like `manual` or `ui` allows for using multiple keys in the config: diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 15f2e1387a04..3f3852ffa3c6 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -24,7 +24,7 @@ Templating in Home Assistant is powered by the [Jinja2](https://palletsprojects. We will not go over the basics of the syntax, as Jinja2 does a great job of this in their [templates documentation](https://jinja.palletsprojects.com/en/master/templates/). -The frontend has a template editor tool to help develop and debug templates. Navigate to Developer Tools > Template, create your template in the _Template editor_ and check the results on the right. +The frontend has a {% my developer_templates title="template editor tool" %} to help develop and debug templates. Navigate to {% my developer_templates title="Developer Tools > Template" %}, create your template in the _Template editor_ and check the results on the right. Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates: diff --git a/source/_integrations/xbox.markdown b/source/_integrations/xbox.markdown index 60176702b23e..d5a1e614f4dd 100644 --- a/source/_integrations/xbox.markdown +++ b/source/_integrations/xbox.markdown @@ -40,7 +40,7 @@ The Xbox media player platform will create Media Player entities for each consol Launches an application on the Xbox console using the application's product ID. Also supports "Home" and "TV" to navigate to the dashboard or Live TV respectively. -You can find Product IDs using the **Developer Tools -> Events** tab and listening to the `call_service` event. In a new browser tab, navigate to the media browser for your console and click on an App/Game to see the product ID in the event. +You can find Product IDs using the **{% my developer_events title="Developer Tools -> Events" %}** tab and listening to the `call_service` event. In a new browser tab, navigate to the media browser for your console and click on an App/Game to see the product ID in the event. | Service data attribute | Description | | ---------------------- | --------------------------------------| diff --git a/source/_integrations/zwave_js.markdown b/source/_integrations/zwave_js.markdown index 70d4d8e72ed8..edd74a0d612b 100644 --- a/source/_integrations/zwave_js.markdown +++ b/source/_integrations/zwave_js.markdown @@ -136,7 +136,7 @@ Valid code slots are between 1-254. ## Events -Events are fired when you press a button on a remote (aka Central Scene support) or when a stateless value is being signalled by a device. You can test what events come in using the event developer tools in Home Assistant and subscribe to `zwave_js_event`. Once you know what the event data looks like, you can use this to create automations. +Events are fired when you press a button on a remote (aka Central Scene support) or when a stateless value is being signalled by a device. You can test what events come in using the event {% my developer_events title="developer tools in Home Assistant" %} and subscribe to `zwave_js_event`. Once you know what the event data looks like, you can use this to create automations. ### Node events (Notification) From 1a49a1b18160e7a8d950b0fc3c8034f16e6d5858 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 2 Mar 2021 21:14:30 +0100 Subject: [PATCH 14/65] Collection of Markdown/YAML cleanups (#16817) --- .../authentication/multi-factor-auth.markdown | 2 +- source/_docs/automation/action.markdown | 31 +- source/_docs/automation/basics.markdown | 2 +- source/_docs/automation/condition.markdown | 30 +- source/_docs/automation/templating.markdown | 18 +- source/_docs/automation/trigger.markdown | 442 +++++++++--------- source/_docs/automation/yaml.markdown | 59 ++- source/_docs/blueprint/schema.markdown | 8 +- source/_docs/blueprint/tutorial.markdown | 18 +- source/_docs/configuration/basic.markdown | 10 +- source/_docs/configuration/devices.markdown | 10 +- source/_docs/configuration/packages.markdown | 9 +- .../configuration/platform_options.markdown | 4 +- source/_docs/configuration/remote.markdown | 4 - source/_docs/configuration/secrets.markdown | 2 +- .../splitting_configuration.markdown | 94 ++-- .../_docs/configuration/templating.markdown | 85 +++- .../configuration/troubleshooting.markdown | 2 +- source/_docs/configuration/yaml.markdown | 12 +- 19 files changed, 446 insertions(+), 396 deletions(-) diff --git a/source/_docs/authentication/multi-factor-auth.markdown b/source/_docs/authentication/multi-factor-auth.markdown index d295b48b4bec..240224f0a833 100644 --- a/source/_docs/authentication/multi-factor-auth.markdown +++ b/source/_docs/authentication/multi-factor-auth.markdown @@ -94,7 +94,7 @@ message: homeassistant: auth_mfa_modules: - type: totp - name: Authenticator app + name: "Authenticator app" - type: notify message: "I almost forget, to get into my clubhouse, you need to say {}" ``` diff --git a/source/_docs/automation/action.markdown b/source/_docs/automation/action.markdown index 3297a6749efe..74ccbe6f9e7b 100644 --- a/source/_docs/automation/action.markdown +++ b/source/_docs/automation/action.markdown @@ -11,23 +11,24 @@ You can also call the service to activate [a scene](/integrations/scene/) which automation: # Change the light in the kitchen and living room to 150 brightness and color red. trigger: - platform: sun - event: sunset + - platform: sun + event: sunset action: - service: light.turn_on - data: - brightness: 150 - rgb_color: [255, 0, 0] - entity_id: - - light.kitchen - - light.living_room + - service: light.turn_on + target: + entity_id: + - light.kitchen + - light.living_room + data: + brightness: 150 + rgb_color: [255, 0, 0] automation 2: # Notify me on my mobile phone of an event trigger: - platform: sun - event: sunset - offset: -00:30 + - platform: sun + event: sunset + offset: -00:30 variables: notification_service: notify.paulus_iphone action: @@ -47,9 +48,9 @@ Conditions can also be part of an action. You can combine multiple service calls automation: - alias: "Office at evening" trigger: - platform: state - entity_id: sensor.office_occupancy - to: "on" + - platform: state + entity_id: sensor.office_occupancy + to: "on" action: - service: notify.notify data: diff --git a/source/_docs/automation/basics.markdown b/source/_docs/automation/basics.markdown index 87a1d384f250..0ad584c5e5ed 100644 --- a/source/_docs/automation/basics.markdown +++ b/source/_docs/automation/basics.markdown @@ -15,7 +15,7 @@ We can break up this automation into the following three parts: (action) Turn the lights on in the living room ``` -The first part is the [trigger](/docs/automation/trigger/) of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'. +The first part is the [trigger](/docs/automation/trigger/) of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from `not_home` to `home`. The second part is the [condition](/docs/automation/condition/). Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set. diff --git a/source/_docs/automation/condition.markdown b/source/_docs/automation/condition.markdown index b530f18e5ded..d9f7076920db 100644 --- a/source/_docs/automation/condition.markdown +++ b/source/_docs/automation/condition.markdown @@ -15,19 +15,19 @@ Example of using condition: automation: - alias: "Enciende Despacho" trigger: - platform: state - entity_id: sensor.mini_despacho - to: "on" + - platform: state + entity_id: sensor.mini_despacho + to: "on" condition: - condition: or - conditions: - - condition: numeric_state - entity_id: sun.sun - attribute: elevation - below: 4 - - condition: numeric_state - entity_id: sensor.sensorluz_7_0 - below: 10 + - condition: or + conditions: + - condition: numeric_state + entity_id: sun.sun + attribute: elevation + below: 4 + - condition: numeric_state + entity_id: sensor.sensorluz_7_0 + below: 10 action: - service: scene.turn_on target: @@ -44,9 +44,9 @@ The `condition` option of an automation, also accepts a single condition templat automation: - alias: "Enciende Despacho" trigger: - platform: state - entity_id: sensor.mini_despacho - to: "on" + - platform: state + entity_id: sensor.mini_despacho + to: "on" condition: "{{ state_attr('sun.sun', 'elevation') < 4 }}" action: - service: scene.turn_on diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown index 0b72cd1e4593..38da81fa0bfd 100644 --- a/source/_docs/automation/templating.markdown +++ b/source/_docs/automation/templating.markdown @@ -127,19 +127,19 @@ The following tables show the available trigger data per platform. # Example configuration.yaml entries automation: trigger: - platform: state - entity_id: device_tracker.paulus + - platform: state + entity_id: device_tracker.paulus action: - service: notify.notify - data: - message: > - Paulus just changed from {{ trigger.from_state.state }} - to {{ trigger.to_state.state }} + - service: notify.notify + data: + message: > + Paulus just changed from {{ trigger.from_state.state }} + to {{ trigger.to_state.state }} automation 2: trigger: - platform: mqtt - topic: /notify/+ + - platform: mqtt + topic: "/notify/+" action: service: > notify.{{ trigger.topic.split('/')[-1] }} diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown index 55ee1a5d69d9..8f8a730b9588 100644 --- a/source/_docs/automation/trigger.markdown +++ b/source/_docs/automation/trigger.markdown @@ -3,7 +3,7 @@ title: "Automation Trigger" description: "All the different ways how automations can be triggered." --- -### What are triggers +## What are triggers Triggers are what starts the processing of an automation rule. When _any_ of the automation's triggers becomes true (trigger _fires_), Home Assistant will validate the [conditions](/docs/automation/condition/), if any, and call the [action](/docs/automation/action/). @@ -11,11 +11,11 @@ An automation can be triggered by an event, with a certain entity state, at a gi The following sections introduce all trigger types and further details to get started. -### Trigger variables +## Trigger variables Similar to [script level variables](/integrations/script/#variables), `trigger_variables` will be available in trigger templates with the difference that only [limited templates](/docs/configuration/templating/#limited-templates) can be used to pass a value to the trigger variable. -### Event trigger +## Event trigger Fires when an event is being received. Events are the raw building blocks of Home Assistant. You can match events on just the event name or also require specific event data or context to be present. @@ -24,16 +24,16 @@ Events can be fired by integrations or via the API. There is no limitation to th ```yaml automation: trigger: - platform: event - event_type: MY_CUSTOM_EVENT - # optional - event_data: - mood: happy - context: - user_id: - # any of these will match - - MY_USER_ID - - ANOTHER_USER_ID + - platform: event + event_type: "MY_CUSTOM_EVENT" + # optional + event_data: + mood: happy + context: + user_id: + # any of these will match + - "MY_USER_ID" + - "ANOTHER_USER_ID" ``` It is also possible to listen for multiple events at once. This is useful for @@ -42,10 +42,10 @@ event that contain no, or similar, data and contexts. ```yaml automation: trigger: - platform: event - event_type: - - automation_reloaded - - scene_reloaded + - platform: event + event_type: + - automation_reloaded + - scene_reloaded ``` It's also possible to use [limited templates](/docs/configuration/templating/#limited-templates) in the `event_type`, `event_data` and `context` options. @@ -65,36 +65,36 @@ automation: node: ac value: on trigger: - platform: event - event_type: "{{ 'MY_CUSTOM_EVENT_' ~ sub_event }}" + - platform: event + event_type: "{{ 'MY_CUSTOM_EVENT_' ~ sub_event }}" ``` {% endraw %} -### Home Assistant trigger +## Home Assistant trigger Fires when Home Assistant starts up or shuts down. ```yaml automation: trigger: - platform: homeassistant - # Event can also be 'shutdown' - event: start + - platform: homeassistant + # Event can also be 'shutdown' + event: start ``` -### MQTT trigger +## MQTT trigger Fires when a specific message is received on given MQTT topic. Optionally can match on the payload being sent over the topic. The default payload encoding is 'utf-8'. For images and other byte payloads use `encoding: ''` to disable payload decoding completely. ```yaml automation: trigger: - platform: mqtt - topic: living_room/switch/ac - # Optional - payload: "on" - encoding: "utf-8" + - platform: mqtt + topic: "living_room/switch/ac" + # Optional + payload: "on" + encoding: "utf-8" ``` The `payload` option can be combined with a `value_template` to process the message received on the given MQTT topic before matching it with the payload. @@ -105,10 +105,10 @@ The trigger in the example below will trigger only when the message received on ```yaml automation: trigger: - platform: mqtt - topic: "living_room/switch/ac" - payload: "on" - value_template: "{{ value_json.state }}" + - platform: mqtt + topic: "living_room/switch/ac" + payload: "on" + value_template: "{{ value_json.state }}" ``` {% endraw %} @@ -130,16 +130,16 @@ automation: node: "ac" value: "on" trigger: - platform: mqtt - topic: "{{ room ~ '/switch/' ~ node}}" - # Optional - payload: "{{ 'state:' ~ value }}" - encoding: "utf-8" + - platform: mqtt + topic: "{{ room ~ '/switch/' ~ node}}" + # Optional + payload: "{{ 'state:' ~ value }}" + encoding: "utf-8" ``` {% endraw %} -### Numeric state trigger +## Numeric state trigger Fires when the numeric value of an entity's state (or attribute's value if using the `attribute` property) crosses a given threshold. On state change of a specified entity, attempts to parse the state as a number and fires if the value is changing from above to below or from below to above the given threshold. @@ -148,20 +148,20 @@ Fires when the numeric value of an entity's state (or attribute's value if using ```yaml automation: trigger: - platform: numeric_state - entity_id: sensor.temperature - # Optional - value_template: "{{ state.attributes.battery }}" - # At least one of the following required - above: 17 - below: 25 - # If given, will trigger when the value of the given attribute for the given entity changes - attribute: attribute_name - # If given, will trigger when the condition has been true for X time; you can also use days and milliseconds. - for: - hours: 1 - minutes: 10 - seconds: 5 + - platform: numeric_state + entity_id: sensor.temperature + # Optional + value_template: "{{ state.attributes.battery }}" + # At least one of the following required + above: 17 + below: 25 + # If given, will trigger when the value of the given attribute for the given entity changes + attribute: attribute_name + # If given, will trigger when the condition has been true for X time; you can also use days and milliseconds. + for: + hours: 1 + minutes: 10 + seconds: 5 ``` {% endraw %} @@ -177,11 +177,11 @@ the trigger more dynamic, like: ```yaml automation: trigger: - platform: numeric_state - entity_id: sensor.temperature - # input_number entity id can be specified for above and/or below thresholds - above: input_number.temperature_threshold_high - below: input_number.temperature_threshold_low + - platform: numeric_state + entity_id: sensor.temperature + # input_number entity id can be specified for above and/or below thresholds + above: input_number.temperature_threshold_high + below: input_number.temperature_threshold_low ``` The `for:` can also be specified as `HH:MM:SS` like this: @@ -191,16 +191,16 @@ The `for:` can also be specified as `HH:MM:SS` like this: ```yaml automation: trigger: - platform: numeric_state - entity_id: sensor.temperature - # Optional - value_template: "{{ state.attributes.battery }}" - # At least one of the following required - above: 17 - below: 25 + - platform: numeric_state + entity_id: sensor.temperature + # Optional + value_template: "{{ state.attributes.battery }}" + # At least one of the following required + above: 17 + below: 25 - # If given, will trigger when condition has been for X time. - for: "01:10:05" + # If given, will trigger when condition has been for X time. + for: "01:10:05" ``` {% endraw %} @@ -212,26 +212,26 @@ You can also use templates in the `for` option. ```yaml automation: trigger: - platform: numeric_state - entity_id: - - sensor.temperature_1 - - sensor.temperature_2 - above: 80 - for: - minutes: "{{ states('input_number.high_temp_min')|int }}" - seconds: "{{ states('input_number.high_temp_sec')|int }}" + - platform: numeric_state + entity_id: + - sensor.temperature_1 + - sensor.temperature_2 + above: 80 + for: + minutes: "{{ states('input_number.high_temp_min')|int }}" + seconds: "{{ states('input_number.high_temp_sec')|int }}" action: - service: persistent_notification.create - data: - message: > - {{ trigger.to_state.name }} too high for {{ trigger.for }}! + - service: persistent_notification.create + data: + message: > + {{ trigger.to_state.name }} too high for {{ trigger.for }}! ``` {% endraw %} The `for` template(s) will be evaluated when an entity changes as specified. -### State trigger +## State trigger Fires when the state of any of given entities changes. If only `entity_id` is given, the trigger will fire for all state changes, even if only state attributes change. If only one of `from_state` or `to_state` are given, the trigger will fire on any matching state change, but not if only attributes change. @@ -245,14 +245,14 @@ The values you see in your overview will often not be the same as the actual sta ```yaml automation: trigger: - platform: state - entity_id: - - device_tracker.paulus - - device_tracker.anne_therese - # Optional - from: "not_home" - # Optional - to: "home" + - platform: state + entity_id: + - device_tracker.paulus + - device_tracker.anne_therese + # Optional + from: "not_home" + # Optional + to: "home" ``` It's possible to give a list of from_states or to_states: @@ -260,15 +260,15 @@ It's possible to give a list of from_states or to_states: ```yaml automation: trigger: - platform: state - entity_id: vacuum.test - from: - - "cleaning" - - "returning" - to: "error" + - platform: state + entity_id: vacuum.test + from: + - "cleaning" + - "returning" + to: "error" ``` -#### Holding a state +### Holding a state You can use `for` to have the state trigger only fire if the state holds for some time. @@ -278,11 +278,11 @@ state for 30 seconds: ```yaml automation: trigger: - platform: state - entity_id: light.office - # Must stay "on" for 30 seconds - to: "on" - for: "00:00:30" + - platform: state + entity_id: light.office + # Must stay "on" for 30 seconds + to: "on" + for: "00:00:30" ``` Please note, that when holding a state, changes to attributes are ignored and @@ -297,11 +297,11 @@ the time specified, but doesn't care about "playing" or "paused". ```yaml automation: trigger: - platform: state - entity_id: media_player.kitchen - # Not "off" for 30 minutes - from: "off" - for: "00:30:00" + - platform: state + entity_id: media_player.kitchen + # Not "off" for 30 minutes + from: "off" + for: "00:30:00" ``` Please note, that when using `from`, `to` and `for`, only the value of the @@ -313,10 +313,10 @@ same for `for` the time specified, regardless of the current state value. ```yaml automation: trigger: - platform: state - entity_id: media_player.kitchen - # The media player remained in its current state for 1 hour - for: "01:00:00" + - platform: state + entity_id: media_player.kitchen + # The media player remained in its current state for 1 hour + for: "01:00:00" ``` When the `attribute` option is specified, all of the above works, but only @@ -328,11 +328,11 @@ For example, this trigger only fires if the boiler was heating for 10 minutes: ```yaml automation: trigger: - platform: state - entity_id: climate.living_room - attribute: hvac_action - to: "heating" - for: "00:10:00" + - platform: state + entity_id: climate.living_room + attribute: hvac_action + to: "heating" + for: "00:10:00" ``` You can also use templates in the `for` option. @@ -342,16 +342,18 @@ You can also use templates in the `for` option. ```yaml automation: trigger: - platform: state - entity_id: device_tracker.paulus, device_tracker.anne_therese - to: "home" - for: - minutes: "{{ states('input_number.lock_min')|int }}" - seconds: "{{ states('input_number.lock_sec')|int }}" + - platform: state + entity_id: + - device_tracker.paulus + - device_tracker.anne_therese + to: "home" + for: + minutes: "{{ states('input_number.lock_min')|int }}" + seconds: "{{ states('input_number.lock_sec')|int }}" action: - service: lock.lock - target: - entity_id: lock.my_place + - service: lock.lock + target: + entity_id: lock.my_place ``` {% endraw %} @@ -364,9 +366,9 @@ Use quotes around your values for `from` and `to` to avoid the YAML parser from
    -### Sun trigger +## Sun trigger -#### Sunset / Sunrise trigger +### Sunset / Sunrise trigger Fires when the sun is setting or rising, i.e., when the sun elevation reaches 0°. @@ -383,14 +385,14 @@ Since the duration of twilight is different throughout the year, it is recommend ```yaml automation: trigger: - platform: sun - # Possible values: sunset, sunrise - event: sunset - # Optional time offset. This example will trigger 45 minutes before sunset. - offset: "-00:45:00" + - platform: sun + # Possible values: sunset, sunrise + event: sunset + # Optional time offset. This example will trigger 45 minutes before sunset. + offset: "-00:45:00" ``` -#### Sun elevation trigger +### Sun elevation trigger Sometimes you may want more granular control over an automation than simply sunset or sunrise and specify an exact elevation of the sun. This can be used to layer automations to occur as the sun lowers on the horizon or even after it is below the horizon. This is also useful when the "sunset" event is not dark enough outside and you would like the automation to run later at a precise solar angle instead of the time offset such as turning on exterior lighting. For most automations intended to run during dusk or dawn, a number between 0° and -6° is suitable; -4° is used in this example: @@ -398,17 +400,17 @@ Sometimes you may want more granular control over an automation than simply suns ```yaml automation: - alias: "Exterior Lighting on when dark outside" - trigger: - platform: numeric_state - entity_id: sun.sun - attribute: elevation - # Can be a positive or negative number - below: -4.0 - action: - service: switch.turn_on - target: - entity_id: switch.exterior_lighting + - alias: "Exterior Lighting on when dark outside" + trigger: + - platform: numeric_state + entity_id: sun.sun + attribute: elevation + # Can be a positive or negative number + below: -4.0 + action: + - service: switch.turn_on + target: + entity_id: switch.exterior_lighting ``` {% endraw %} @@ -426,7 +428,7 @@ Although the actual amount of light depends on weather, topography and land cove A very thorough explanation of this is available in the Wikipedia article about the [Twilight](https://en.wikipedia.org/wiki/Twilight). -### Tag trigger +## Tag trigger Fires when a [tag](/integrations/tag) is scanned. For example, a NFC tag is scanned using the Home Assistant Companion mobile application. @@ -434,8 +436,8 @@ scanned using the Home Assistant Companion mobile application. ```yaml automation: trigger: - platform: tag - tag_id: A7-6B-90-5F + - platform: tag + tag_id: A7-6B-90-5F ``` Additionally, you can also only trigger if a card is scanned by a specific @@ -444,9 +446,9 @@ device/scanner by setting the `device_id`: ```yaml automation: trigger: - platform: tag - tag_id: A7-6B-90-5F - device_id: 0e19cd3cf2b311ea88f469a7512c307d + - platform: tag + tag_id: A7-6B-90-5F + device_id: 0e19cd3cf2b311ea88f469a7512c307d ``` Or trigger on multiple possible devices for multiple tags: @@ -454,16 +456,16 @@ Or trigger on multiple possible devices for multiple tags: ```yaml automation: trigger: - platform: tag - tag_id: - - A7-6B-90-5F - - A7-6B-15-AC - device_id: - - 0e19cd3cf2b311ea88f469a7512c307d - - d0609cb25f4a13922bb27d8f86e4c821 + - platform: tag + tag_id: + - "A7-6B-90-5F" + - "A7-6B-15-AC" + device_id: + - 0e19cd3cf2b311ea88f469a7512c307d + - d0609cb25f4a13922bb27d8f86e4c821 ``` -### Template trigger +## Template trigger Template triggers work by evaluating a [template](/docs/configuration/templating/) when any of the recognized entities change state. The trigger will fire if the state change caused the template to render 'true' (a non-zero number or any of the strings `true`, `yes`, `on`, `enable`) when it was previously 'false' (anything else). @@ -476,11 +478,11 @@ With template triggers you can also evaluate attribute changes by using is_state ```yaml automation: trigger: - platform: template - value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}" + - platform: template + value_template: "{% if is_state('device_tracker.paulus', 'home') %}true{% endif %}" - # If given, will trigger when template remains true for X time. - for: "00:01:00" + # If given, will trigger when template remains true for X time. + for: "00:01:00" ``` {% endraw %} @@ -492,10 +494,10 @@ You can also use templates in the `for` option. ```yaml automation: trigger: - platform: template - value_template: "{{ is_state('device_tracker.paulus', 'home') }}" - for: - minutes: "{{ states('input_number.minutes')|int(0) }}" + - platform: template + value_template: "{{ is_state('device_tracker.paulus', 'home') }}" + for: + minutes: "{{ states('input_number.minutes')|int(0) }}" ``` {% endraw %} @@ -504,23 +506,23 @@ The `for` template(s) will be evaluated when the `value_template` becomes 'true' Templates that do not contain an entity will be rendered once per minute. -### Time trigger +## Time trigger The time trigger is configured to fire once a day at a specific time, or at a specific time on a specific date. There are three allowed formats: -#### Time String +### Time String A string that represents a time to fire on each day. Can be specified as `HH:MM` or `HH:MM:SS`. If the seconds are not specified, `:00` will be used. ```yaml automation: - trigger: - platform: time - # Military time format. This trigger will fire at 3:32 PM - at: "15:32:00" + - trigger: + - platform: time + # Military time format. This trigger will fire at 3:32 PM + at: "15:32:00" ``` -#### Input Datetime +### Input Datetime The Entity ID of an [Input Datetime](/integrations/input_datetime/). @@ -535,9 +537,9 @@ has_date | has_time | Description ```yaml automation: - trigger: - platform: state - entity_id: binary_sensor.motion - to: "on" + - platform: state + entity_id: binary_sensor.motion + to: "on" action: - service: climate.turn_on target: @@ -549,69 +551,68 @@ automation: datetime: > {{ (now().timestamp() + 2*60*60) | timestamp_custom('%Y-%m-%d %H:%M:%S') }} - - trigger: - platform: time - at: input_datetime.turn_off_ac + - platform: time + at: input_datetime.turn_off_ac action: - service: climate.turn_off - target: - entity_id: climate.office + - service: climate.turn_off + target: + entity_id: climate.office ``` {% endraw %} -#### Sensors of datetime device class +### Sensors of datetime device class The Entity ID of a [sensor](/integrations/sensor/) with the "timestamp" device class. ```yaml automation: - trigger: - platform: time - at: sensor.phone_next_alarm + - platform: time + at: sensor.phone_next_alarm action: - service: light.turn_on - target: - entity_id: light.bedroom + - service: light.turn_on + target: + entity_id: light.bedroom ``` -#### Multiple Times +### Multiple Times Multiple times can be provided in a list. Both formats can be intermixed. ```yaml automation: trigger: - platform: time - at: - - input_datetime.leave_for_work - - "18:30:00" + - platform: time + at: + - input_datetime.leave_for_work + - "18:30:00" ``` -### Time pattern trigger +## Time pattern trigger With the time pattern trigger, you can match if the hour, minute or second of the current time matches a specific value. You can prefix the value with a `/` to match whenever the value is divisible by that number. You can specify `*` to match any value (when using the web interface this is required, the fields cannot be left empty). ```yaml automation: trigger: - platform: time_pattern - # Matches every hour at 5 minutes past whole - minutes: 5 + - platform: time_pattern + # Matches every hour at 5 minutes past whole + minutes: 5 automation 2: trigger: - platform: time_pattern - # Trigger once per minute during the hour of 3 - hours: "3" - minutes: "*" + - platform: time_pattern + # Trigger once per minute during the hour of 3 + hours: "3" + minutes: "*" automation 3: trigger: - platform: time_pattern - # You can also match on interval. This will match every 5 minutes - minutes: "/5" + - platform: time_pattern + # You can also match on interval. This will match every 5 minutes + minutes: "/5" ```
    @@ -620,15 +621,15 @@ Do not prefix numbers with a zero - using `'00'` instead of '0' for example will
    -### Webhook trigger +## Webhook trigger Webhook trigger fires when a web request is made to the webhook endpoint: `/api/webhook/`. The webhook endpoint is created automatically when you set it as the `webhook_id` in an automation trigger. ```yaml automation: trigger: - platform: webhook - webhook_id: some_hook_id + - platform: webhook + webhook_id: "some_hook_id" ``` 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 empty data payload: @@ -641,21 +642,21 @@ Webhook endpoints don't require authentication, other than knowing a valid webho Note that a given webhook can only be used in one automation at a time. That is, only one automation trigger can use a specific webhook ID. -### Zone trigger +## Zone trigger Zone trigger fires when an entity is entering or leaving the zone. The entity can be either a person, or a device_tracker. For zone automation to work, you need to have setup a device tracker platform that supports reporting GPS coordinates. This includes [GPS Logger](/integrations/gpslogger/), the [OwnTracks platform](/integrations/owntracks/) and the [iCloud platform](/integrations/icloud/). ```yaml automation: trigger: - platform: zone - entity_id: person.paulus - zone: zone.home - # Event is either enter or leave - event: enter # or "leave" + - platform: zone + entity_id: person.paulus + zone: zone.home + # Event is either enter or leave + event: enter # or "leave" ``` -### Geolocation trigger +## Geolocation trigger Geolocation trigger fires when an entity is appearing in or disappearing from a zone. Entities that are created by a [Geolocation](/integrations/geo_location/) platform support reporting GPS coordinates. Because entities are generated and removed by these platforms automatically, the entity id normally cannot be predicted. Instead, this trigger requires the definition of a `source`, which is directly linked to one of the Geolocation platforms. @@ -666,18 +667,17 @@ This isn't for use with `device_tracker` entities. For those look above at the `
    - ```yaml automation: trigger: - platform: geo_location - source: nsw_rural_fire_service_feed - zone: zone.bushfire_alert_zone - # Event is either enter or leave - event: enter # or "leave" + - platform: geo_location + source: nsw_rural_fire_service_feed + zone: zone.bushfire_alert_zone + # Event is either enter or leave + event: enter # or "leave" ``` -### Device triggers +## Device triggers Device triggers encompass a set of events that are defined by an integration. This includes, for example, state changes of sensors as well as button events from remotes. [MQTT device triggers](/integrations/device_trigger.mqtt/) are set up through autodiscovery. @@ -686,7 +686,7 @@ In contrast to state triggers, device triggers are tied to a device and not nece To use a device trigger, set up an automation through the browser frontend. If you would like to use a device trigger for an automation that is not managed through the browser frontend, you can copy the YAML from the trigger widget in the frontend and paste it into your automation's trigger list. -### Multiple triggers +## Multiple triggers It is possible to specify multiple triggers for the same rule. To do so just prefix the first line of each trigger with a dash (-) and indent the next lines accordingly. Whenever one of the triggers fires, [processing](#what-are-triggers) of your automation rule begins. @@ -701,7 +701,7 @@ automation: event: sunset ``` -### Multiple Entity IDs for the same Trigger +## Multiple Entity IDs for the same Trigger It is possible to specify multiple entities for the same trigger. To do so add multiple entities using a nested list. The trigger will fire and start, [processing](#what-are-triggers) your automation each time the trigger is true for each entity listed. diff --git a/source/_docs/automation/yaml.markdown b/source/_docs/automation/yaml.markdown index 77a869289f09..b8bc80f455ad 100644 --- a/source/_docs/automation/yaml.markdown +++ b/source/_docs/automation/yaml.markdown @@ -15,8 +15,8 @@ automation: !include automations.yaml # Labeled automation block automation kitchen: -- trigger: - platform: ... + - trigger: + - platform: ... ``` You can add as many labeled `automation` blocks as you want. @@ -53,54 +53,53 @@ automation my_lights: before: "23:00:00" action: # With a single service call, we don't need a '-' before service - though you can if you want to - service: homeassistant.turn_on - target: - entity_id: group.living_room + - service: homeassistant.turn_on + target: + entity_id: group.living_room # Turn off lights when everybody leaves the house - alias: "Rule 2 - Away Mode" trigger: - platform: state - entity_id: all - to: "not_home" - action: - service: light.turn_off - target: + - platform: state entity_id: all + to: "not_home" + action: + - service: light.turn_off + target: + entity_id: all # Notify when Paulus leaves the house in the evening - alias: "Leave Home notification" trigger: - platform: zone - event: leave - zone: zone.home - entity_id: device_tracker.paulus + - platform: zone + event: leave + zone: zone.home + entity_id: device_tracker.paulus condition: - condition: time - after: "20:00" + - condition: time + after: "20:00" action: - service: notify.notify - data: - message: "Paulus left the house" + - service: notify.notify + data: + message: "Paulus left the house" # Send a notification via Pushover with the event of a Xiaomi cube. Custom event from the Xiaomi component. - alias: "Xiaomi Cube Action" initial_state: false trigger: - platform: event - event_type: cube_action - event_data: - entity_id: binary_sensor.cube_158d000103a3de + - platform: event + event_type: cube_action + event_data: + entity_id: binary_sensor.cube_158d000103a3de action: - service: notify.pushover - data: - title: "Cube event detected" - message: "Cube has triggered this event: {{ trigger.event }}" + - service: notify.pushover + data: + title: "Cube event detected" + message: "Cube has triggered this event: {{ trigger.event }}" ``` {% endraw %} - ## Extra options When writing automations directly in YAML, you will have access to advanced options that are not available in the user interface. @@ -114,7 +113,7 @@ automation: - alias: "Automation Name" initial_state: false trigger: - - platform: ... + - platform: ... ``` ## Migrating your YAML automations to `automations.yaml` diff --git a/source/_docs/blueprint/schema.markdown b/source/_docs/blueprint/schema.markdown index c514467a4957..2f88a109dc47 100644 --- a/source/_docs/blueprint/schema.markdown +++ b/source/_docs/blueprint/schema.markdown @@ -171,10 +171,10 @@ mode: restart max_exceeded: silent trigger: - platform: state - entity_id: !input motion_entity - from: "off" - to: "on" + - platform: state + entity_id: !input motion_entity + from: "off" + to: "on" action: - service: light.turn_on diff --git a/source/_docs/blueprint/tutorial.markdown b/source/_docs/blueprint/tutorial.markdown index d26eaa99bedb..97bef2a2254e 100644 --- a/source/_docs/blueprint/tutorial.markdown +++ b/source/_docs/blueprint/tutorial.markdown @@ -191,17 +191,17 @@ blueprint: domain: light trigger: - platform: state - entity_id: !input motion_sensor + - platform: state + entity_id: !input motion_sensor action: - service: > - {% if trigger.to_state.state == "on" %} - light.turn_on - {% else %} - light.turn_off - {% endif %} - target: !input target_light + - service: > + {% if trigger.to_state.state == "on" %} + light.turn_on + {% else %} + light.turn_off + {% endif %} + target: !input target_light ``` {% endraw %} diff --git a/source/_docs/configuration/basic.markdown b/source/_docs/configuration/basic.markdown index d1d5396947d3..8a42d18bcd58 100644 --- a/source/_docs/configuration/basic.markdown +++ b/source/_docs/configuration/basic.markdown @@ -14,17 +14,17 @@ homeassistant: longitude: 117.22743 elevation: 430 unit_system: metric - time_zone: America/Los_Angeles + time_zone: "America/Los_Angeles" external_url: "https://www.example.com" internal_url: "http://homeassistant.local:8123" allowlist_external_dirs: - - /usr/var/dumping-ground - - /tmp + - "/usr/var/dumping-ground" + - "/tmp" allowlist_external_urls: - "http://images.com/image1.png" media_dirs: - media: /media - recordings: /mnt/recordings + media: "/media" + recordings: "/mnt/recordings" legacy_templates: false ``` diff --git a/source/_docs/configuration/devices.markdown b/source/_docs/configuration/devices.markdown index 0f93b43382a7..61e10fce2262 100644 --- a/source/_docs/configuration/devices.markdown +++ b/source/_docs/configuration/devices.markdown @@ -25,7 +25,7 @@ sensor: state_topic: "home/kitchen/temperature" name: "MQTT Sensor 2" - platform: rest - resource: http://IP_ADDRESS/ENDPOINT + resource: "http://IP_ADDRESS/ENDPOINT" name: "Weather" switch: @@ -49,7 +49,7 @@ sensor kitchen: sensor weather: platform: rest - resource: http://IP_ADDRESS/ENDPOINT + resource: "http://IP_ADDRESS/ENDPOINT" name: "Weather" switch 1: @@ -65,10 +65,12 @@ Once you have several devices set up, it is time to organize them into groups. Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the {% my developer_states title="States page in the Developer Tools" %}. ```yaml -# Example configuration.yaml entry showing two styles +# Example configuration.yaml entry group: living_room: - entities: light.table_lamp, switch.ac + entities: + - light.table_lamp + - switch.ac bedroom: entities: - light.bedroom diff --git a/source/_docs/configuration/packages.markdown b/source/_docs/configuration/packages.markdown index 21b49a04cfd6..9680a6b30e18 100644 --- a/source/_docs/configuration/packages.markdown +++ b/source/_docs/configuration/packages.markdown @@ -57,21 +57,22 @@ light: There are some rules for packages that will be merged: 1. Platform based integrations (`light`, `switch`, etc) can always be merged. -2. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file. +2. Components where entities are identified by a key that will represent the entity_id (`{key: config}`) need to have unique 'keys' between packages and the main configuration file. For example if we have the following in the main configuration. You are not allowed to re-use "my_input" again for `input_boolean` in a package: - + ```yaml input_boolean: my_input: ``` + 3. Any integration that is not a platform [1], or dictionaries with Entity ID keys [2] can only be merged if its keys, except those for lists, are solely defined once.
    Components inside packages can only specify platform entries using configuration style 1, where all the platforms are grouped under the integration name.
    -### Create a packages folder +## Create a packages folder One way to organize packages is to create a folder named "packages" in your Home Assistant configuration directory. In the packages directory you can store any number of packages in a YAML file. This entry in your `configuration.yaml` will load all packages: @@ -101,7 +102,7 @@ subsystem1_functionality1: automation: ``` -### Customizing entities with packages +## Customizing entities with packages It is possible to [customize entities](/docs/configuration/customizing-devices/) within packages. Just create your customization entries under: diff --git a/source/_docs/configuration/platform_options.markdown b/source/_docs/configuration/platform_options.markdown index af528461dc97..f632baa4128a 100644 --- a/source/_docs/configuration/platform_options.markdown +++ b/source/_docs/configuration/platform_options.markdown @@ -9,7 +9,7 @@ These options are being phased out and are only available for single platform in Some integrations or platforms (those that are based on the [entity](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/helpers/entity.py) class) allows various extra options to be set. -### Entity namespace +## Entity namespace By setting an entity namespace, all entities will be prefixed with that namespace. That way `light.bathroom` can become `light.holiday_house_bathroom`. @@ -20,7 +20,7 @@ light: entity_namespace: holiday_house ``` -### Scan Interval +## Scan Interval Platforms that require polling will be polled in an interval specified by the main component. For example a light will check every 30 seconds for a changed state. It is possible to overwrite this scan interval for any platform that is being polled by specifying a `scan_interval` configuration key. In the example below we set up the `your_lights` platform but tell Home Assistant to poll the devices every 10 seconds instead of the default 30 seconds. diff --git a/source/_docs/configuration/remote.markdown b/source/_docs/configuration/remote.markdown index a829d9e2b7ef..975afd8884ae 100644 --- a/source/_docs/configuration/remote.markdown +++ b/source/_docs/configuration/remote.markdown @@ -15,10 +15,6 @@ Remember to follow the [securing checklist](/docs/configuration/securing/) befor
    -
    -Home Assistant no longer support remote access via IP address since release 0.77, you have to use a domain name. -
    - The most common approach is to set up port forwarding (for any port) from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching ` port forwarding instructions`. You can use any free port on your router and forward that to port 8123. A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/). diff --git a/source/_docs/configuration/secrets.markdown b/source/_docs/configuration/secrets.markdown index 8dec4f4c6c53..9fac0e3d9cea 100644 --- a/source/_docs/configuration/secrets.markdown +++ b/source/_docs/configuration/secrets.markdown @@ -30,7 +30,7 @@ homeassistant: The `secrets.yaml` file contains the corresponding password assigned to the identifier. ```yaml -http_password: YOUR_PASSWORD +http_password: "YOUR_PASSWORD" ``` ## Debugging secrets diff --git a/source/_docs/configuration/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown index 5bfbc9d3233a..bb7edc22e6ab 100644 --- a/source/_docs/configuration/splitting_configuration.markdown +++ b/source/_docs/configuration/splitting_configuration.markdown @@ -16,14 +16,14 @@ In this lighter version we will still need what could be called the core snippet ```yaml homeassistant: # Name of the location where Home Assistant is running - name: My Home Assistant Instance + name: "My Home Assistant Instance" # Location required to calculate the time the sun rises and sets latitude: 37 longitude: -121 # 'metric' for Metric, 'imperial' for Imperial unit_system: imperial # Pick yours from here: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones - time_zone: America/Los_Angeles + time_zone: "America/Los_Angeles" customize: !include customize.yaml ``` @@ -38,18 +38,18 @@ history: frontend: logbook: http: - api_password: ImNotTelling! + api_password: "ImNotTelling!" ifttt: - key: [nope] + key: ["nope"] wink: - access_token: [wouldn't you] - refresh_token: [like to know] + access_token: ["wouldn't you"] + refresh_token: ["like to know"] zwave: - usb_path: /dev/ttyUSB0 - config_path: /usr/local/share/python-openzwave/config + usb_path: "/dev/ttyUSB0" + config_path: "/usr/local/share/python-openzwave/config" polling_interval: 10000 mqtt: @@ -88,7 +88,7 @@ Nesting `!include`s (having an `!include` within a file that is itself `!include ```yaml light: - platform: group - name: Bedside Lights + name: "Bedside Lights" entities: - light.left_bedside_light - light.right_bedside_light @@ -104,7 +104,7 @@ where `light-groups.yaml` might look like: ```yaml - platform: group - name: Outside Lights + name: "Outside Lights" entities: - light.porch_lights - light.patio_lights @@ -114,11 +114,11 @@ with `light-switches.yaml` containing: ```yaml - platform: switch - name: Patio Lights + name: "Patio Lights" entity_id: switch.patio_lights - platform: switch - name: Floor Lamp + name: "Floor Lamp" entity_id: switch.floor_lamp_plug ``` @@ -129,8 +129,8 @@ Let's look at the `device_tracker.yaml` file from our example: ```yaml - platform: owntracks - platform: nmap_tracker - hosts: 192.168.2.0/24 home_interval: 3 + hosts: 192.168.2.0/24 track_new_devices: true interval_seconds: 40 @@ -164,15 +164,15 @@ This (large) sensor configuration gives us another example: #### STEAM FRIENDS ################################## - platform: steam_online - api_key: [not telling] + api_key: ["not telling"] accounts: - 76561198012067051 #### TIME/DATE ################################## - platform: time_date display_options: - - 'time' - - 'date' + - "time" + - "date" - platform: worldclock time_zone: Etc/UTC name: "UTC" @@ -303,7 +303,7 @@ alexa: action: service: notify.pushover data: - message: Your location has been queried via Alexa. + message: "Your location has been queried via Alexa." speech: type: plaintext text: > @@ -341,7 +341,7 @@ alexa: action: service: notify.pushover data: - message: Your location has been queried via Alexa. + message: "Your location has been queried via Alexa." speech: type: plaintext text: > @@ -376,22 +376,22 @@ speech: automation: - alias: "Automation 1" trigger: - platform: state - entity_id: device_tracker.iphone - to: "home" + - platform: state + entity_id: device_tracker.iphone + to: "home" action: - service: light.turn_on - target: - entity_id: light.entryway + - service: light.turn_on + target: + entity_id: light.entryway - alias: "Automation 2" trigger: - platform: state - entity_id: device_tracker.iphone - from: "home" + - platform: state + entity_id: device_tracker.iphone + from: "home" action: - service: light.turn_off - target: - entity_id: light.entryway + - service: light.turn_off + target: + entity_id: light.entryway ``` can be turned into: @@ -407,22 +407,22 @@ automation: !include_dir_merge_list automation/ ```yaml - alias: "Automation 1" trigger: - platform: state - entity_id: device_tracker.iphone - to: "home" + - platform: state + entity_id: device_tracker.iphone + to: "home" action: - service: light.turn_on - target: - entity_id: light.entryway + - service: light.turn_on + target: + entity_id: light.entryway - alias: "Automation 2" trigger: - platform: state - entity_id: device_tracker.iphone - from: "home" + - platform: state + entity_id: device_tracker.iphone + from: "home" action: - service: light.turn_off - target: - entity_id: light.entryway + - service: light.turn_off + target: + entity_id: light.entryway ``` It is important to note that when using `!include_dir_merge_list`, you must include a list in each file (each list item is denoted with a hyphen [-]). Each file may contain one or more entries. @@ -434,17 +434,17 @@ It is important to note that when using `!include_dir_merge_list`, you must incl ```yaml group: bedroom: - name: Bedroom + name: "Bedroom" entities: - light.bedroom_lamp - light.bedroom_overhead hallway: - name: Hallway + name: "Hallway" entities: - light.hallway - thermostat.home front_yard: - name: Front Yard + name: "Front Yard" entities: - light.front_porch - light.security @@ -465,7 +465,7 @@ group: !include_dir_merge_named group/ ```yaml bedroom: - name: Bedroom + name: "Bedroom" entities: - light.bedroom_lamp - light.bedroom_overhead @@ -480,7 +480,7 @@ hallway: ```yaml front_yard: - name: Front Yard + name: "Front Yard" entities: - light.front_porch - light.security diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index 3f3852ffa3c6..73b694f2075f 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -29,6 +29,7 @@ The frontend has a {% my developer_templates title="template editor tool" %} to Templates can get big pretty fast. To keep a clear overview, consider using YAML multiline strings to define your templates: {% raw %} + ```yaml script: msg_who_is_home: @@ -42,6 +43,7 @@ script: Paulus is at {{ states('device_tracker.paulus') }}. {% endif %} ``` + {% endraw %} ### Important Template Rules @@ -87,20 +89,24 @@ Besides the normal [state object methods and properties](/topics/state_object/), The next two statements result in the same value if the state exists. The second one will result in an error if the state does not exist. {% raw %} + ```text {{ states('device_tracker.paulus') }} {{ states.device_tracker.paulus.state }} ``` + {% endraw %} Print out a list of all the sensor states: {% raw %} + ```text {% for state in states.sensor %} {{ state.entity_id }}={{ state.state }}, {% endfor %} ``` + {% endraw %} Other state examples: @@ -128,8 +134,8 @@ Other state examples: {{ as_timestamp(now()) - as_timestamp(states.binary_sensor.garage_door.last_changed) }} {{ as_local(states.sensor.time.last_changed) }} - ``` + {% endraw %} ### Attributes @@ -141,6 +147,7 @@ You can print an attribute with `state_attr` if state is defined. #### Attributes examples {% raw %} + ```text {% if states.device_tracker.paulus %} {{ state_attr('device_tracker.paulus', 'battery') }} @@ -148,11 +155,13 @@ You can print an attribute with `state_attr` if state is defined. ?? {% endif %} ``` + {% endraw %} With strings: {% raw %} + ```text {% set tracker_name = "paulus"%} @@ -162,6 +171,7 @@ With strings: ?? {% endif %} ``` + {% endraw %} ### Working with Groups @@ -173,22 +183,26 @@ The `expand` function and filter can be used to sort entities and expand groups. #### Expand examples {% raw %} + ```text {% for tracker in expand('device_tracker.paulus', 'group.child_trackers') %} {{ state_attr(tracker, 'battery') }} {%- if not loop.last %}, {% endif -%} {% endfor %} ``` + {% endraw %} The same thing can also be expressed as a filter: {% raw %} + ```text {{ expand(['device_tracker.paulus', 'group.child_trackers']) | selectattr("attributes.battery", 'defined') | join(', ', attribute="attributes.battery") }} ``` + {% endraw %} ### Time @@ -208,10 +222,12 @@ The same thing can also be expressed as a filter: - `timedelta` returns a timedelta object and accepts the same arguments as the Python `datetime.timedelta` function -- days, seconds, microseconds, milliseconds, minutes, hours, weeks. {% raw %} + ```yaml # 77 minutes before curret time. {{ now() - timedelta( hours = 1, minutes = 17 ) }} ``` + {% endraw %} - Filter `timestamp_local` converts an UNIX timestamp to its string representation as date/time in your local timezone. @@ -219,13 +235,13 @@ The same thing can also be expressed as a filter: - Filter `timestamp_custom(format_string, local_time=True)` converts an UNIX timestamp to its string representation based on a custom format, the use of a local timezone is default. Supports the standard [Python time formatting options](https://docs.python.org/3/library/time.html#time.strftime).
    - + [UNIX timestamp](https://en.wikipedia.org/wiki/Unix_time) is the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970. Therefore, if used as a function's argument, it can be substituted with a numeric value (`int` or `float`).
    - + If your template is returning a timestamp that should be displayed in the frontend (e.g., as a sensor entity with `device_class: timestamp`), you have to ensure that it is the ISO 8601 format (meaning it has the "T" separator between the date and time portion). Otherwise, frontend rendering on macOS and iOS devices will show an error. The following value template would result in such an error: {% raw %} @@ -245,9 +261,11 @@ To fix it, enforce the ISO conversion via `isoformat()`:
    {% raw %} + ```yaml {{ 120 | timestamp_local }} ``` + {% endraw %} ### To/From JSON @@ -263,20 +281,24 @@ In this example, the special character '°' will be automatically escaped in ord *Template* {% raw %} + ```text {% set temp = {'temperature': 25, 'unit': '°C'} %} stringified object: {{ temp }} object|to_json: {{ temp|to_json }} ``` + {% endraw %} *Output* {% raw %} + ```text stringified object: {'temperature': 25, 'unit': '°C'} object|to_json: {"temperature": 25, "unit": "\u00b0C"} ``` + {% endraw %} Conversely, `from_json` can be used to de-serialize a JSON string back into an object to make it possible to easily extract usable data. @@ -284,18 +306,22 @@ Conversely, `from_json` can be used to de-serialize a JSON string back into an o *Template* {% raw %} + ```text {% set temp = '{"temperature": 25, "unit": "\u00b0C"}'|from_json %} The temperature is {{ temp.temperature }}{{ temp.unit }} ``` + {% endraw %} *Output* {% raw %} + ```text The temperature is 25°C ``` + {% endraw %} ### Distance @@ -311,6 +337,7 @@ If only one location is passed in, Home Assistant will measure the distance from {% raw %} ```text + Using Lat Lng coordinates: {{ distance(123.45, 123.45) }} Using State: {{ distance(states.device_tracker.paulus) }} @@ -319,6 +346,7 @@ These can also be combined in any combination: {{ distance(123.45, 123.45, 'device_tracker.paulus') }} {{ distance('device_tracker.anne_therese', 'device_tracker.paulus') }} ``` + {% endraw %} #### Closest examples @@ -326,35 +354,42 @@ These can also be combined in any combination: The closest function and filter will find the closest entity to the Home Assisant location: {% raw %} + ```text Query all entities: {{ closest(states) }} Query all entities of a specific domain: {{ closest(states.device_tracker) }} Query all entities in group.children: {{ closest('group.children') }} Query all entities in group.children: {{ closest(states.group.children) }} ``` + {% endraw %} Find entities closest to a coordinate or another entity. All previous arguments still apply for second argument. {% raw %} + ```text Closest to a coordinate: {{ closest(23.456, 23.456, 'group.children') }} Closest to an entity: {{ closest('zone.school', 'group.children') }} Closest to an entity: {{ closest(states.zone.school, 'group.children') }} ``` + {% endraw %} Since closest returns a state, we can combine it with distance too. {% raw %} + ```text {{ closest(states).name }} is {{ distance(closest(states)) }} kilometers away. ``` + {% endraw %} The last argument of the closest function has an implicit `expand`, and can take any iterable sequence of states or entity IDs, and will expand groups: {% raw %} + ```text Closest out of given entities: {{ closest(['group.children', states.device_tracker]) }} @@ -364,8 +399,12 @@ Closest to some entity: {{ closest(states.zone.school, ['group.children', states.device_tracker]) }} ``` +{% endraw %} + It will also work as a filter over an iterable group of entities or groups: +{% raw %} + ```text Closest out of given entities: {{ ['group.children', states.device_tracker] | closest }} @@ -441,9 +480,11 @@ This means that if the incoming values looks like the sample below: The template for `on` would be: {% raw %} + ```yaml '{{value_json.on}}' ``` + {% endraw %} Nested JSON in a response is supported as well: @@ -464,42 +505,49 @@ Nested JSON in a response is supported as well: Just use the "Square bracket notation" to get the value. {% raw %} + ```yaml "{{ value_json['values']['temp'] }}" ``` + {% endraw %} The following overview contains a couple of options to get the needed values: +{% raw %} + ```text # Incoming value: {"primes": [2, 3, 5, 7, 11, 13]} # Extract third prime number -{% raw %}{{ value_json.primes[2] }}{% endraw %} +{{ value_json.primes[2] }} # Format output -{% raw %}{{ "%+.1f" | value_json }}{% endraw %} +{{ "%+.1f" | value_json }} # Math -{% raw %}{{ value_json | float * 1024 }}{% endraw %} -{% raw %}{{ float(value_json) * (2**10) }}{% endraw %} -{% raw %}{{ value_json | log }}{% endraw %} -{% raw %}{{ log(1000, 10) }}{% endraw %} -{% raw %}{{ sin(pi / 2) }}{% endraw %} -{% raw %}{{ cos(tau) }}{% endraw %} -{% raw %}{{ tan(pi) }}{% endraw %} -{% raw %}{{ sqrt(e) }}{% endraw %} +{{ value_json | float * 1024 }} +{{ float(value_json) * (2**10) }} +{{ value_json | log }} +{{ log(1000, 10) }} +{{ sin(pi / 2) }} +{{ cos(tau) }} +{{ tan(pi) }} +{{ sqrt(e) }} # Timestamps -{% raw %}{{ value_json.tst | timestamp_local }}{% endraw %} -{% raw %}{{ value_json.tst | timestamp_utc }}{% endraw %} -{% raw %}{{ value_json.tst | timestamp_custom('%Y' True) }}{% endraw %} +{{ value_json.tst | timestamp_local }} +{{ value_json.tst | timestamp_utc }} +{{ value_json.tst | timestamp_custom('%Y' True) }} ``` -To evaluate a response, go to **Developer Tools** -> **Template**, create your output in "Template editor", and check the result. +{% endraw %} + +To evaluate a response, go to **{% my developer_templates title="Developer Tools -> Template" %}**, create your output in "Template editor", and check the result. {% raw %} + ```yaml {% set value_json= {"name":"Outside", @@ -511,6 +559,7 @@ To evaluate a response, go to **Developer Tools** -> **Template**, create your o {{value_json.data.hum[:-1]}} ``` + {% endraw %} ## Some more things to keep in mind @@ -524,9 +573,11 @@ If your template uses an `entity_id` that begins with a number (example: `states The default priority of operators is that the filter (`|`) has priority over everything except brackets. This means that: {% raw %} + ```yaml {{ states('sensor.temperature') | float / 10 | round(2) }} ``` + {% endraw %} Would round `10` to 2 decimal places, then divide `states('sensor.temperature')` by `10` (rounded to 2 decimal places so 10.00). This behavior is maybe not the one expected, but priority rules imply that. diff --git a/source/_docs/configuration/troubleshooting.markdown b/source/_docs/configuration/troubleshooting.markdown index 34d3677582ae..399853c9148f 100644 --- a/source/_docs/configuration/troubleshooting.markdown +++ b/source/_docs/configuration/troubleshooting.markdown @@ -13,7 +13,7 @@ Whenever an integration or configuration option results in a warning, it will be When an integration does not show up, many different things can be the case. Before you try any of these steps, make sure to look at the `home-assistant.log` file and see if there are any errors related to your integration you are trying to set up. -If you have incorrect entries in your configuration files you can use the configuration check command (below) to assist in identifying them. +If you have incorrect entries in your configuration files you can use the configuration check command (below) to assist in identifying them. ### Problems with the configuration diff --git a/source/_docs/configuration/yaml.markdown b/source/_docs/configuration/yaml.markdown index 1bf3d3d238c3..e0e4ff9d4de4 100644 --- a/source/_docs/configuration/yaml.markdown +++ b/source/_docs/configuration/yaml.markdown @@ -5,7 +5,7 @@ description: "Details about YAML to configure Home Assistant." Home Assistant uses the [YAML](https://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations. -While more and more integrations are configured through the UI, for some, you will add code in your `configuration.yaml` file to specify its settings. +While more and more integrations are configured through the UI, for some, you will add code in your `configuration.yaml` file to specify its settings. The following example entry assumes that you would like to set up the [notify integration](/integrations/notify) with the [pushbullet platform](/integrations/pushbullet). @@ -41,8 +41,8 @@ The other properties (like `name:`) are specified using mappings. Note that the ```yaml input_select: threat: - name: Threat level -# A collection is used for options + name: "Threat level" + # A collection is used for options options: - 0 - 1 @@ -56,9 +56,9 @@ The following example shows nesting a collection of mappings in a mapping. In Ho ```yaml sensor: - platform: mqtt - state_topic: sensor/topic + state_topic: "sensor/topic" - platform: mqtt - state_topic: sensor2/topic + state_topic: "sensor2/topic" ``` ## Including values @@ -111,7 +111,7 @@ Home Assistant is case sensitive, a state of `'on'` is not the same as `'On'` or If you're having trouble, check the case that Home Assistant is reporting in the dev-state menu, under *Developer tools*. -### Booleans +### Booleans YAML treats `Y`, `true`, `Yes`, `ON` all as `true` and `n`, `FALSE`, `No`, `off` as `false`. This means that if you want to set the state of an entity to `on` you *must* quote it as `'on'` otherwise it will be translated as setting the state to true. The same applies to `off`. From 9a3fa3dcd73913f6c202bfaa9db2fff0d9bda66c Mon Sep 17 00:00:00 2001 From: Raman Gupta <7243222+raman325@users.noreply.github.com> Date: Tue, 2 Mar 2021 16:12:07 -0500 Subject: [PATCH 15/65] Update example zwave_js_event value notification event to include new keys (#16815) --- source/_integrations/zwave_js.markdown | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/source/_integrations/zwave_js.markdown b/source/_integrations/zwave_js.markdown index edd74a0d612b..84fa202c215a 100644 --- a/source/_integrations/zwave_js.markdown +++ b/source/_integrations/zwave_js.markdown @@ -168,12 +168,15 @@ Value Notification example: "home_id": "974823419", "endpoint": 0, "device_id": "ad8098fe80980974", - "command_class": 32, - "command_class_name": "Basic", + "command_class": 91, + "command_class_name": "Central Scene", "label": "Event value", - "property_name": "event", - "property_key_name": "some value", - "value": 255, + "property": "scene", + "property_name": "scene", + "property_key": "001", + "property_key_name": "001", + "value": "KeyPressed", + "value_raw": 0 } ``` From 53293b63d0cf5583eba70dbc15dfc5f2a1e54698 Mon Sep 17 00:00:00 2001 From: Joakim Plate Date: Wed, 3 Mar 2021 09:37:15 +0100 Subject: [PATCH 16/65] Add list of commands (#16807) Co-authored-by: Franck Nijhof --- source/_integrations/philips_js.markdown | 72 ++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/source/_integrations/philips_js.markdown b/source/_integrations/philips_js.markdown index aa3316e9a177..2fdccf4cedc5 100644 --- a/source/_integrations/philips_js.markdown +++ b/source/_integrations/philips_js.markdown @@ -3,6 +3,7 @@ title: Philips TV description: Instructions on how to add Philips TVs to Home Assistant. ha_category: - Media Player + - Remote ha_iot_class: Local Polling ha_release: 0.34 ha_codeowners: @@ -39,3 +40,74 @@ Instructions on how to activate the API and if your model is supported can be fo ### Turn on device The Philips TV does not always support turning on via the API. You can either turn it on via IR blaster or on som models WOL. To trigger this command from the entities, the integration exposes a `device trigger` that can be setup to execute when the `media_player` is asked to turn on. + +### Remote + +The integration provides a remote entity for sending remote key presses directly to the TV. The following list of commands are available for use with the `remote.send_command` service. + +| Command | Comment | +| ---------------- | ----------------------------------------- | +| Standby | | +| CursorUp | | +| CursorDown | | +| CursorLeft | | +| CursorRight | | +| Confirm | | +| Back | | +| Exit | | +| WatchTV | | +| Home | | +| Source | | +| List | | +| Find | | +| Options | | +| Adjust | | +| RedColour | | +| GreenColour | | +| YellowColour | | +| BlueColour | | +| Play | | +| PlayPause | Mapped to same as Play on Android devices | +| Pause | | +| FastForward | | +| Stop | | +| Rewind | | +| Record | | +| ChannelStepUp | | +| ChannelStepDown | | +| Digit0 | | +| Digit1 | | +| Digit2 | | +| Digit3 | | +| Digit4 | | +| Digit5 | | +| Digit6 | | +| Digit7 | | +| Digit8 | | +| Digit9 | | +| Dot | | +| VolumeUp | | +| VolumeDown | | +| Mute | | +| Teletext | | +| Subtitle | | +| ClosedCaption | | +| TvGuide | | +| Info | | +| AmbilightOnOff | | +| Viewmode | | +| 3dFormat | | +| Multiview | | +| PictureStyle | | +| 3dDepth | | +| SoundStyle | | +| SurroundMode | | +| HeadphonesVolume | | +| 2PlayerGaming | | +| Setup | | +| WhiteColour | | +| PowerOn | | +| PowerOff | Mapped to same as Standby on Android | +| Online | | +| SmartTV | | +| PhilipsMenu | | From 3aee41e2c3221e0f24205ed63a0263c0252cfb90 Mon Sep 17 00:00:00 2001 From: Nick Adams <4012017+Nick-Adams-AU@users.noreply.github.com> Date: Wed, 3 Mar 2021 19:10:03 +1000 Subject: [PATCH 17/65] Add airflow min-max service description (#16823) Co-authored-by: Franck Nijhof --- source/_integrations/izone.markdown | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/source/_integrations/izone.markdown b/source/_integrations/izone.markdown index 887535b5904b..819c9ddb3464 100644 --- a/source/_integrations/izone.markdown +++ b/source/_integrations/izone.markdown @@ -122,3 +122,23 @@ logger: ``` This will help you to find network connection issues etc. + +## Services + +### Service `izone.airflow_min` + +Set the minimum airflow for a particular zone. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | izone Zone entity. For example `climate.bed_2` +| `airflow` | no | Airflow percent in 5% increments + +### Service `izone.airflow_max` + +Set the maximum airflow for a particular zone. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | izone Zone entity. For example `climate.bed_2` +| `airflow` | no | Airflow percent in 5% increments From 66f7d0c63067b992f0d5984c613e1a25d3a74a8d Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sat, 6 Mar 2021 21:42:16 -1000 Subject: [PATCH 18/65] Change default homekit ports to 21063 and 21064 (#16882) --- source/_integrations/homekit.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index 21dbb1827067..f7ce387e180c 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -57,7 +57,7 @@ homekit: camera.back_porch: support_audio: True - name: HASS Bridge 2 - port: 56332 + port: 21065 filter: include_domains: - light @@ -78,7 +78,7 @@ homekit: description: Port for the HomeKit extension. If you are adding more than one instance they need to have different values for port. required: false type: integer - default: 51827 + default: 21063 name: description: Need to be individual for each instance of Home Assistant using the integration on the same local network. Between `3` and `25` characters. Alphanumeric and spaces allowed. required: false From 2d66a00aa08c399d8983231f0ec6385f9fd93498 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 15 Mar 2021 13:58:22 +0100 Subject: [PATCH 19/65] Deprecate HomeKit auto start (#16874) --- source/_integrations/homekit.markdown | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index 4424b3dabef5..cba7290dd815 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -83,11 +83,6 @@ homekit: required: true type: map keys: - auto_start: - description: Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. ([Disable Auto Start](#disable-auto-start)) - required: false - type: boolean - default: true port: description: Port for the HomeKit extension. If you are adding more than one instance they need to have different values for port. required: false @@ -304,12 +299,6 @@ Currently, this integration uses the `entity_id` to generate a unique `accessory The HomeKit Accessory Protocol Specification only allows a maximum of 150 unique accessories (`aid`) per bridge. Be mindful of this when configuring the filter(s). If you plan on exceeding the 150 devices limit, it is possible to create multiple bridges. If you need specific configuration for some entities via `entity_config` be sure to add them to a bridge configured via `YAML`. -### Persistence Storage - -Unfortunately, `HomeKit` doesn't support any persistent storage - only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems, it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If, for some reason, some entities are not set up, their configuration will be deleted. (State unknown or similar will not cause any issues.) - -A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable `auto start` and `turn off` the `Start HomeKit` automation (if you have one). - ### Multiple HomeKit instances If you create a HomeKit integration via the UI (i.e., **Configuration** >> **Integrations**), it must be configured via the UI **only**. While the UI only offers limited configuration options at the moment, any attempt to configure a HomeKit instance created in the UI via the `configuration.yaml` file will result in another instance of HomeKit running on a different port. @@ -338,10 +327,6 @@ To add a single entity in accessory mode: 5. Complete the options flow 6. [Pair the accessory](#setup). -## Disable Auto Start - -It is not needed (anymore) to disable `Auto Start` for all accessories to be available for `HomeKit` as Home Assistant restores all entities on start instantly. - ## Configure Filter By default, no entity will be excluded. To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. Keep in mind only [supported components](#supported-components) can be added. @@ -537,10 +522,6 @@ Pairing works fine when the filter is set to only include `demo.demo`, but fails ### Issues during normal use -#### Some of my devices don't show up - Z-Wave / Discovery - -See [disable auto start](#disable-auto-start) - #### My entity doesn't show up Check if the domain of your entity is [supported](#supported-components). If it is, check your [filter](#configure-filter) settings. Make sure the spelling is correct, especially if you use `include_entities`. From fa0c50fa807c4cac98fb0076be7e85e75abd00ae Mon Sep 17 00:00:00 2001 From: Matthias Alphart Date: Mon, 15 Mar 2021 15:06:18 +0100 Subject: [PATCH 20/65] remove KNX config_file (#16684) --- source/_integrations/knx.markdown | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 8b0a700733a7..11166bcb3c03 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -80,18 +80,7 @@ knx: Please see the dedicated platform sections below about how to configure them correctly. -Alternatively, if you want to use the [XKNX](https://xknx.io/) library abstraction (e.g., to re-use the configuration also for other scripted tools outside of Home Assistant): - -```yaml -knx: - config_file: "/path/to/xknx.yaml" -``` - {% configuration %} -config_file: - description: The path for XKNX configuration file. See [xknx.io](https://xknx.io/configuration) for details. - required: false - type: string individual_address: description: The KNX individual address (IA) that shall be used for routing or if a tunneling server doesn't assign an IA at connection. required: false From 079549f822e219d508f835c52d02b112e7475b80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=81lvaro=20Fern=C3=A1ndez=20Rojas?= Date: Mon, 15 Mar 2021 15:09:28 +0100 Subject: [PATCH 21/65] Add weather support to Tado integration (#16096) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Álvaro Fernández Rojas --- source/_integrations/tado.markdown | 2 ++ 1 file changed, 2 insertions(+) diff --git a/source/_integrations/tado.markdown b/source/_integrations/tado.markdown index 6018b729ee4f..9755b4e7157d 100644 --- a/source/_integrations/tado.markdown +++ b/source/_integrations/tado.markdown @@ -8,6 +8,7 @@ ha_category: - Water Heater - Presence Detection - Sensor + - Weather ha_release: 0.41 ha_iot_class: Cloud Polling ha_codeowners: @@ -34,6 +35,7 @@ There is currently support for the following device types within Home Assistant: - Water Heater - for water heater zones. - [Presence Detection](#presence-detection) - Sensor - for some additional information of the zones. +- Weather - for information about the current weather at the location of your Tado home. {% include integrations/config_flow.md %} From ee5fa813a9c9b168a15e1d254c3e818cad66db94 Mon Sep 17 00:00:00 2001 From: starkillerOG Date: Mon, 15 Mar 2021 15:16:12 +0100 Subject: [PATCH 22/65] Add Xiaomi Miio sensor config flow (#16717) --- source/_integrations/xiaomi_miio.markdown | 75 ++--------------------- 1 file changed, 6 insertions(+), 69 deletions(-) diff --git a/source/_integrations/xiaomi_miio.markdown b/source/_integrations/xiaomi_miio.markdown index d7f857e3e01f..bbd450fb2275 100644 --- a/source/_integrations/xiaomi_miio.markdown +++ b/source/_integrations/xiaomi_miio.markdown @@ -36,8 +36,7 @@ The `xiaomi_miio` integration supports the following devices: - [Xiaomi Gateway](#xiaomi-gateway) - [Xiaomi device tracker (Xiaomi Mi WiFi Repeater 2)](#xiaomi-device-tracker-xiaomi-mi-wifi-repeater-2)) - [Xiaomi Air Purifier and Humidifier](#xiaomi-air-purifier-and-humidifier) -- [Xiaomi Air Quality Index Monitor](#xiaomi-air-quality-index-monitor) -- [Xiaomi Mi Air Quality Monitor](#xiaomi-mi-air-quality-monitor) +- [Xiaomi Air Quality Monitor](#xiaomi-air-quality-monitor) - [Xiaomi IR Remote](#xiaomi-ir-remote) - [Xiaomi Mi Robot Vacuum](#xiaomi-mi-robot-vacuum) - [Xiaomi Philips Light](#xiaomi-philips-light) @@ -869,91 +868,29 @@ Check if the device is in the same subnet as the Home Assistant instance. Otherw If it's not possible to use VLANs for some reason, your last resort may be using NAT translation, between the IPs. -## Xiaomi Air Quality Index Monitor +## Xiaomi Air Quality Monitor -The `xiaomi_miio` sensor platform is observing your Xiaomi Mi Air Quality Monitor (PM2.5) and reporting the air quality index. +The `xiaomi_miio` Air Quality Monitor is observing your Xiaomi Mi Air Quality Monitor (PM2.5) and reporting the air quality index and other values. Currently, the supported features are: - Air Quality Index (AQI) +- Particulate matter 2.5 - Attributes - power - charging - battery - time_stat - -Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token. - -### Configuration - -To add a Xiaomi Mi Air Quality Monitor to your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - - platform: xiaomi_miio - host: IP_ADDRESS - token: YOUR_TOKEN -``` - -{% configuration %} -host: - description: The IP address of your miio device. - required: true - type: string -token: - description: The API token of your miio device. - required: true - type: string -name: - description: The name of your miio device. - required: false - type: string - default: Xiaomi Miio Sensor -{% endconfiguration %} - -## Xiaomi Mi Air Quality Monitor - -The `xiaomi_miio` sensor platform is observing your Xiaomi Mi Air Quality Monitor and reporting the air quality values. - -Currently, the supported features are: - -- Particulate matter 2.5 -- Attributes - carbon_dioxide_equivalent - total_volatile_organic_compounds - temperature - humidity -Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token. - ### Configuration -To add a Xiaomi Mi Air Quality Monitor to your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -air_quality: - - platform: xiaomi_miio - host: IP_ADDRESS - token: YOUR_TOKEN -``` +Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token to use during configuration flow setup. -{% configuration %} -host: - description: The IP address of your miio device. - required: true - type: string -token: - description: The API token of your miio device. - required: true - type: string -name: - description: The name of your miio device. - required: false - type: string - default: Xiaomi Miio Air Quality Monitor -{% endconfiguration %} +To add a Xiaomi Mi Air Quality Monitor to your installation, click Configuration in the sidebar, then click Integrations and then click the + icon in the lower right and find xiaomi_miio. You will then be presented with a form in which you will need to fill in the “IP address” and 32 characters “token”. After you click submit, you will have the opportunity to select the area that your devices are located. ## Xiaomi IR Remote From 44c4dd69e3f72108a16c5eada62d1b39141088e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Gabriel?= Date: Mon, 15 Mar 2021 11:16:33 -0300 Subject: [PATCH 23/65] Adding Panasonic Viera remote documentation (#15377) Co-authored-by: Franck Nijhof --- source/_integrations/panasonic_viera.markdown | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/source/_integrations/panasonic_viera.markdown b/source/_integrations/panasonic_viera.markdown index b0336fcd781d..32cbb39d4e5e 100644 --- a/source/_integrations/panasonic_viera.markdown +++ b/source/_integrations/panasonic_viera.markdown @@ -3,6 +3,7 @@ title: Panasonic Viera description: Instructions on how to integrate a Panasonic Viera TV with Home Assistant. ha_category: - Media Player + - Remote ha_release: 0.17 ha_iot_class: Local Polling ha_domain: panasonic_viera @@ -13,9 +14,16 @@ The `panasonic_viera` platform allows you to control a Panasonic Viera TV. {% include integrations/config_flow.md %} +There is currently support for the following device types within Home Assistant: + +- Media Player +- [Remote](#remote) + +{% include integrations/config_flow.md %} + If your TV needs to be paired, you will be prompted to type the PIN code that will be displayed on it. -To allow your TV to be turned on or controlled while off, enable `Powered On By Apps` in the TV Settings: **Network > TV Remote App Settings** +To allow your TV to be turned on or controlled while off, enable `Powered On By Apps` in your settings (if available): **Network > TV Remote App Settings** ## Manual configuration @@ -89,6 +97,23 @@ script: entity_id: media_player.living_room_tv ``` +### Remote + +When the integration is configured, two entities will be created: a `media_player` and a `remote`. The remote allows you to send key commands to your TV with the `remote.send_command` service. + +Some of the known valid key values are: + +- `up` +- `down` +- `left` +- `right` +- `select` +- `home` +- `back` +- `power` + +The list with all known valid keys can be found [here](https://github.com/florianholzapfel/panasonic-viera/blob/521cefadc8e1543514ce41d3d49e9218d1c2302d/panasonic_viera/__init__.py#L35). Additionally, you can also send custom commands, such as `"NRC_HOME-ONOFF"` (which is the same as `home`). + ### Currently known supported models - TC-P50ST50 From 40dda044b51b17fa2d046ac681ec73fa705bc448 Mon Sep 17 00:00:00 2001 From: starkillerOG Date: Mon, 15 Mar 2021 15:32:08 +0100 Subject: [PATCH 24/65] Add Xiaomi Miio Light config flow (#16782) --- source/_integrations/xiaomi_miio.markdown | 40 ++++------------------- 1 file changed, 6 insertions(+), 34 deletions(-) diff --git a/source/_integrations/xiaomi_miio.markdown b/source/_integrations/xiaomi_miio.markdown index bbd450fb2275..1d803b563647 100644 --- a/source/_integrations/xiaomi_miio.markdown +++ b/source/_integrations/xiaomi_miio.markdown @@ -1410,6 +1410,12 @@ It seems to be the case that Numbers 1..15 are used to number the intitial segme The `xiaomi_miio` platform allows you to control the state of your Xiaomi Philips LED Ball Lamp, Xiaomi Philips Zhirui LED Bulb E14 Candle Lamp, Xiaomi Philips Zhirui Downlight, Xiaomi Philips LED Ceiling Lamp, Xiaomi Philips Eyecare Lamp 2, Xiaomi Philips Moonlight Bedside Lamp and Philips Zhirui Desk Lamp. +Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token to use during configuration flow setup. + +### Configuration + +To add a Xiaomi Philips Light to your installation, click Configuration in the sidebar, then click Integrations and then click the + icon in the lower right and find xiaomi_miio. You will then be presented with a form in which you will need to fill in the “IP address” and 32 characters “token”. After you click submit, you will have the opportunity to select the area that your devices are located. + ### Features ### Philips LED Ball Lamp, Philips Zhirui LED Candle Lamp and Philips Zhirui Downlight @@ -1494,40 +1500,6 @@ Supported models: `philips.light.moonlight` - brand_sleep - brand -Please follow the instructions on [Retrieving the Access Token](/integrations/xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file. - -To add a Xiaomi Philips Light to your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entries -light: - - platform: xiaomi_miio - name: Xiaomi Philips Smart LED Ball - host: 192.168.130.67 - token: YOUR_TOKEN - model: philips.light.bulb -``` - -{% configuration %} -host: - description: The IP address of your miio light. - required: true - type: string -token: - description: The API token of your miio light. - required: true - type: string -name: - description: The name of your miio light. - required: false - type: string - default: Xiaomi Philips Light -model: - description: The model of your light. Valid values are `philips.light.sread1`, `philips.light.ceiling`, `philips.light.zyceiling`, `philips.light.moonlight`, `philips.light.bulb`, `philips.light.candle`, `philips.light.candle2`, `philips.light.mono1` and `philips.light.downlight`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available. - required: false - type: string -{% endconfiguration %} - ### Platform Services ### Service `xiaomi_miio.light_set_scene` From 9781bca09d8a11d06ed0f8208b9320b1e5de1dfe Mon Sep 17 00:00:00 2001 From: starkillerOG Date: Mon, 15 Mar 2021 15:32:28 +0100 Subject: [PATCH 25/65] Add subdevice lightbulb support (#16619) --- source/_integrations/xiaomi_miio.markdown | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/_integrations/xiaomi_miio.markdown b/source/_integrations/xiaomi_miio.markdown index 1d803b563647..b3daac0be6f4 100644 --- a/source/_integrations/xiaomi_miio.markdown +++ b/source/_integrations/xiaomi_miio.markdown @@ -238,6 +238,14 @@ These subdevices are fully implemented in HomeAssistant: | -------------------------------- | ----------------------- | --------------- | ------------------------------------------------ | | Weather sensor | lumi.sensor_ht | WSDCGQ01LM | readout `temperature` and `humidity` | | Weather sensor | lumi.weather.v1 | WSDCGQ11LM | readout `temperature`, `humidity` and `pressure` | +| Smart bulb E27 | lumi.light.aqcn02 | ZNLDP12LM | on/off, brightness, color temperature | +| IKEA smart bulb E27 white | ikea.light.led1545g12 | LED1545G12 | on/off, brightness, color temperature | +| IKEA smart bulb E27 white | ikea.light.led1546g12 | LED1546G12 | on/off, brightness, color temperature | +| IKEA smart bulb E12 white | ikea.light.led1536g5 | LED1536G5 | on/off, brightness, color temperature | +| IKEA smart bulb GU10 white | ikea.light.led1537r6 | LED1537R6 | on/off, brightness, color temperature | +| IKEA smart bulb E27 white | ikea.light.led1623g12 | LED1623G12 | on/off, brightness, color temperature | +| IKEA smart bulb GU10 white | ikea.light.led1650r5 | LED1650R5 | on/off, brightness, color temperature | +| IKEA smart bulb E12 white | ikea.light.led1649c5 | LED1649C5 | on/off, brightness, color temperature | ### Recognized subdevices (not yet implemented) @@ -284,14 +292,6 @@ These subdevices are recognized by the python-miio code but are still being work | Door lock S2 | lumi.lock.acn02 | ZNMS12LM | | Door lock S2 pro | lumi.lock.acn03 | ZNMS13LM | | Vima cylinder lock | lumi.lock.v1 | A6121 | -| Smart bulb E27 | lumi.light.aqcn02 | ZNLDP12LM | -| IKEA smart bulb E27 white | ikea.light.led1545g12 | LED1545G12 | -| IKEA smart bulb E27 white | ikea.light.led1546g12 | LED1546G12 | -| IKEA smart bulb E12 white | ikea.light.led1536g5 | LED1536G5 | -| IKEA smart bulb GU10 white | ikea.light.led1537r6 | LED1537R6 | -| IKEA smart bulb E27 white | ikea.light.led1623g12 | LED1623G12 | -| IKEA smart bulb GU10 white | ikea.light.led1650r5 | LED1650R5 | -| IKEA smart bulb E12 white | ikea.light.led1649c5 | LED1649C5 | | Thermostat S2 | lumi.airrtc.tcpecn02 | KTWKQ03ES | ## Xiaomi device tracker (Xiaomi Mi WiFi Repeater 2) From 2f3481e6c2cde7e5bbdc47db80c70dae519182be Mon Sep 17 00:00:00 2001 From: Marc Mueller <30130371+cdce8p@users.noreply.github.com> Date: Mon, 15 Mar 2021 15:33:58 +0100 Subject: [PATCH 26/65] Add apply_filter to recorder.purge service (#16377) --- source/_integrations/recorder.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_integrations/recorder.markdown b/source/_integrations/recorder.markdown index 00b7d16ef671..a50954ad7be8 100644 --- a/source/_integrations/recorder.markdown +++ b/source/_integrations/recorder.markdown @@ -210,6 +210,7 @@ Note that purging will not immediately decrease disk space usage but it will sig | ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `keep_days` | yes | The number of history days to keep in recorder database (defaults to the integration `purge_keep_days` configuration) | | `repack` | yes | When using SQLite or PostgreSQL this will rewrite the entire database. When using MySQL or MariaDB it will optimize or recreate the events and states tables. This is a heavy operation that can cause slowdowns and increased disk space usage while it runs. Only supported by SQLite, PostgreSQL, MySQL and MariaDB. | +| `apply_filter` | yes | Apply entity_id and event_type filter in addition to time based purge. Useful in combination with `include` / `exclude` filter to remove falsely added states and events. Combine with `repack: true` to reduce database size. | ### Service `disable` From 2fa97ec08c0fb8a2b99e4c258af4752422805f21 Mon Sep 17 00:00:00 2001 From: Khole Date: Mon, 15 Mar 2021 14:35:06 +0000 Subject: [PATCH 27/65] Hive UI Docs update (#16568) Co-authored-by: Franck Nijhof --- source/_integrations/hive.markdown | 33 ++++++++---------------------- 1 file changed, 9 insertions(+), 24 deletions(-) diff --git a/source/_integrations/hive.markdown b/source/_integrations/hive.markdown index b66db5a84708..47e9b5b6c75b 100644 --- a/source/_integrations/hive.markdown +++ b/source/_integrations/hive.markdown @@ -24,35 +24,20 @@ ha_platforms: - water_heater --- -The `hive` integration is the main integration to set up and integrate all supported Hive devices. Once configured with the minimum required details it will detect and add all Hive devices into Home Assistant, including support for multi-zone heating. +The Hive integration for Home Assistant allows you to interact with supported devices and services offered by +[hivehome.com](https://www.hivehome.com) -This integration uses the Hive website [https://my.hivehome.com](https://my.hivehome.com) credentials, you will need to use the same username and password you use on the Hive website to configure this Hive integration in Home Assistant. +This Hive integration uses the same username and password you use on the [Hive website](https://sso.hivehome.com) to configure it within Home Assistant, 2FA authentication is also supported. Once configured Home Assistant will detect and add all Hive devices, including support for multi-zone heating. -To add your Hive devices into your Home Assistant installation, add the following to your `configuration.yaml` file: +{% include integrations/config_flow.md %} -```yaml -# Example configuration.yaml entry -hive: - username: YOUR_USERNAME - password: YOUR_PASSWORD -``` -{% configuration %} -username: - description: Your username from [https://my.hivehome.com](https://my.hivehome.com). - required: true - type: string -password: - description: Your password from [https://my.hivehome.com](https://my.hivehome.com). - required: true - type: string -scan_interval: - description: The time in minutes between Hive API calls - required: false - type: integer - default: 2 -{% endconfiguration %} +## Options +Menu: *Configuration* > *Integrations* > *Select your new integration* > *Press the options button* + +- **Scan Interval**: Update the scan interval allowing the integration to poll for data more frequently (Cannot be set lower than 30 seconds). + ## Services ### Service `hive.boost_heating` From ce5b32d348050afdf51efd68ce15640529c4b92b Mon Sep 17 00:00:00 2001 From: starkillerOG Date: Mon, 15 Mar 2021 15:41:27 +0100 Subject: [PATCH 28/65] Add gateway switch support (#16617) --- source/_integrations/xiaomi_miio.markdown | 24 +++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/source/_integrations/xiaomi_miio.markdown b/source/_integrations/xiaomi_miio.markdown index b3daac0be6f4..97e5f66555a4 100644 --- a/source/_integrations/xiaomi_miio.markdown +++ b/source/_integrations/xiaomi_miio.markdown @@ -238,6 +238,18 @@ These subdevices are fully implemented in HomeAssistant: | -------------------------------- | ----------------------- | --------------- | ------------------------------------------------ | | Weather sensor | lumi.sensor_ht | WSDCGQ01LM | readout `temperature` and `humidity` | | Weather sensor | lumi.weather.v1 | WSDCGQ11LM | readout `temperature`, `humidity` and `pressure` | +| Wall switch single | lumi.ctrl_ln1 | QBKG11LM | load_power, status, turn_on, turn_off, toggle | +| Wall switch single | lumi.ctrl_ln1.aq1 | QBKG11LM | load_power, status, turn_on, turn_off, toggle | +| Wall switch no neutral | lumi.ctrl_neutral1.v1 | QBKG04LM | status, turn_on, turn_off, toggle | +| Wall switch double | lumi.ctrl_ln2 | QBKG12LM | load_power, status, turn_on, turn_off, toggle | +| Wall switch double | lumi.ctrl_ln2.aq1 | QBKG12LM | load_power, status, turn_on, turn_off, toggle | +| Wall switch double no neutral | lumi.ctrl_neutral2 | QBKG03LM | status, turn_on, turn_off, toggle | +| D1 wall switch triple | lumi.switch.n3acn3 | QBKG26LM | load_power, status, turn_on, turn_off, toggle | +| D1 wall switch triple no neutral | lumi.switch.l3acn3 | QBKG25LM | load_power, status, turn_on, turn_off, toggle | +| Wall outlet | lumi.ctrl_86plug.v1 | QBCZ11LM | status, turn_on, turn_off, toggle | +| Wall outlet | lumi.ctrl_86plug.aq1 | QBCZ11LM | load_power, status, turn_on, turn_off, toggle | +| Plug | lumi.plug | ZNCZ02LM | load_power, status, turn_on, turn_off, toggle | +| Relay | lumi.relay.c2acn01 | LLKZMK11LM | load_power, status, turn_on, turn_off, toggle | | Smart bulb E27 | lumi.light.aqcn02 | ZNLDP12LM | on/off, brightness, color temperature | | IKEA smart bulb E27 white | ikea.light.led1545g12 | LED1545G12 | on/off, brightness, color temperature | | IKEA smart bulb E27 white | ikea.light.led1546g12 | LED1546G12 | on/off, brightness, color temperature | @@ -273,18 +285,6 @@ These subdevices are recognized by the python-miio code but are still being work | Remote switch double | lumi.sensor_86sw2.v1 | WXKG02LM 2016 | | Remote switch double | lumi.remote.b286acn01 | WXKG02LM 2018 | | D1 remote switch double | lumi.remote.b286acn02 | WXKG07LM | -| Wall switch single | lumi.ctrl_ln1 | QBKG11LM | -| Wall switch single | lumi.ctrl_ln1.aq1 | QBKG11LM | -| Wall switch no neutral | lumi.ctrl_neutral1.v1 | QBKG04LM | -| Wall switch double | lumi.ctrl_ln2 | QBKG12LM | -| Wall switch double | lumi.ctrl_ln2.aq1 | QBKG12LM | -| Wall switch double no neutral | lumi.ctrl_neutral2 | QBKG03LM | -| D1 wall switch triple | lumi.switch.n3acn3 | QBKG26LM | -| D1 wall switch triple no neutral | lumi.switch.l3acn3 | QBKG25LM | -| Wall outlet | lumi.ctrl_86plug.v1 | QBCZ11LM | -| Wall outlet | lumi.ctrl_86plug.aq1 | QBCZ11LM | -| Plug | lumi.plug | ZNCZ02LM | -| Relay | lumi.relay.c2acn01 | LLKZMK11LM | | Curtain | lumi.curtain | ZNCLDJ11LM | | Curtain | lumi.curtain.aq2 | ZNGZDJ11LM | | Curtain B1 | lumi.curtain.hagl04 | ZNCLDJ12LM | From 8033cf271288a5a283f4bdbbc055fb91fe2e8f76 Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Mon, 15 Mar 2021 16:26:08 +0100 Subject: [PATCH 29/65] Remove duplicate configuration instruction from Panasonic Viera (#17014) --- source/_integrations/panasonic_viera.markdown | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/_integrations/panasonic_viera.markdown b/source/_integrations/panasonic_viera.markdown index 32cbb39d4e5e..6614b86464ca 100644 --- a/source/_integrations/panasonic_viera.markdown +++ b/source/_integrations/panasonic_viera.markdown @@ -12,8 +12,6 @@ ha_config_flow: true The `panasonic_viera` platform allows you to control a Panasonic Viera TV. -{% include integrations/config_flow.md %} - There is currently support for the following device types within Home Assistant: - Media Player From 0311c161d54c282e7e13de8396c40cf3ec664aa1 Mon Sep 17 00:00:00 2001 From: Nathan Tilley Date: Mon, 15 Mar 2021 11:20:55 -0500 Subject: [PATCH 30/65] Update WOL Documentation For Bugfix (#16946) --- source/_integrations/wake_on_lan.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/wake_on_lan.markdown b/source/_integrations/wake_on_lan.markdown index f77761accaa6..31e1c48fe880 100644 --- a/source/_integrations/wake_on_lan.markdown +++ b/source/_integrations/wake_on_lan.markdown @@ -83,7 +83,7 @@ name: default: Wake on LAN type: string host: - description: The IP address or hostname to check the state of the device (on/off). + description: The IP address or hostname to check the state of the device (on/off). If this is not provided, the state of the switch will be assumed based on the last action that was taken. required: false type: string turn_off: From 968bb0eb17a4e7d53e97ef2d20b9995f0d96f4d3 Mon Sep 17 00:00:00 2001 From: RadekHvizdos <10856567+RadekHvizdos@users.noreply.github.com> Date: Mon, 15 Mar 2021 20:13:56 +0100 Subject: [PATCH 31/65] Update documentation MQTT suggested_area (#17003) Add MQTT suggested_area to the documentation (next branch) --- source/_docs/mqtt/discovery.markdown | 1 + source/_integrations/alarm_control_panel.mqtt.markdown | 4 ++++ source/_integrations/binary_sensor.mqtt.markdown | 4 ++++ source/_integrations/camera.mqtt.markdown | 4 ++++ source/_integrations/climate.mqtt.markdown | 4 ++++ source/_integrations/cover.mqtt.markdown | 4 ++++ source/_integrations/device_tracker.mqtt.markdown | 4 ++++ source/_integrations/device_trigger.mqtt.markdown | 4 ++++ source/_integrations/fan.mqtt.markdown | 4 ++++ source/_integrations/light.mqtt.markdown | 4 ++++ source/_integrations/lock.mqtt.markdown | 4 ++++ source/_integrations/sensor.mqtt.markdown | 4 ++++ source/_integrations/switch.mqtt.markdown | 4 ++++ source/_integrations/tag.mqtt.markdown | 4 ++++ source/_integrations/vacuum.mqtt.markdown | 4 ++++ 15 files changed, 57 insertions(+) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index bd40db3fe5bc..3a057e6f9306 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -273,6 +273,7 @@ Supported abbreviations for device registry configuration: 'mf': 'manufacturer', 'mdl': 'model', 'sw': 'sw_version', + 'sa': 'suggested_area', ``` ## Support by third-party tools diff --git a/source/_integrations/alarm_control_panel.mqtt.markdown b/source/_integrations/alarm_control_panel.mqtt.markdown index 4d7647c9e38d..895ba5364fe1 100644 --- a/source/_integrations/alarm_control_panel.mqtt.markdown +++ b/source/_integrations/alarm_control_panel.mqtt.markdown @@ -113,6 +113,10 @@ device: description: "The name of the device." required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: "The firmware version of the device." required: false diff --git a/source/_integrations/binary_sensor.mqtt.markdown b/source/_integrations/binary_sensor.mqtt.markdown index 428f376dfafb..be94a14381c5 100644 --- a/source/_integrations/binary_sensor.mqtt.markdown +++ b/source/_integrations/binary_sensor.mqtt.markdown @@ -84,6 +84,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/camera.mqtt.markdown b/source/_integrations/camera.mqtt.markdown index 811382e65a4d..80fd9f0796ae 100644 --- a/source/_integrations/camera.mqtt.markdown +++ b/source/_integrations/camera.mqtt.markdown @@ -77,6 +77,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/climate.mqtt.markdown b/source/_integrations/climate.mqtt.markdown index 448ac310a3cb..373ae3b2a8b8 100644 --- a/source/_integrations/climate.mqtt.markdown +++ b/source/_integrations/climate.mqtt.markdown @@ -116,6 +116,10 @@ device: description: 'The name of the device.' required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: 'The firmware version of the device.' required: false diff --git a/source/_integrations/cover.mqtt.markdown b/source/_integrations/cover.mqtt.markdown index 8bf363c67107..0d72e73249b4 100644 --- a/source/_integrations/cover.mqtt.markdown +++ b/source/_integrations/cover.mqtt.markdown @@ -94,6 +94,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/device_tracker.mqtt.markdown b/source/_integrations/device_tracker.mqtt.markdown index 1c777d8f7a6a..33eda93ed908 100644 --- a/source/_integrations/device_tracker.mqtt.markdown +++ b/source/_integrations/device_tracker.mqtt.markdown @@ -133,6 +133,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/device_trigger.mqtt.markdown b/source/_integrations/device_trigger.mqtt.markdown index 1f47e3f0fe60..f088a7cbe687 100644 --- a/source/_integrations/device_trigger.mqtt.markdown +++ b/source/_integrations/device_trigger.mqtt.markdown @@ -68,6 +68,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index cd43ae5c1ad1..bd53656f198c 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -85,6 +85,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/light.mqtt.markdown b/source/_integrations/light.mqtt.markdown index 8f833fbe3b28..549cd01e1d10 100644 --- a/source/_integrations/light.mqtt.markdown +++ b/source/_integrations/light.mqtt.markdown @@ -138,6 +138,10 @@ device: description: 'The name of the device.' required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: 'The firmware version of the device.' required: false diff --git a/source/_integrations/lock.mqtt.markdown b/source/_integrations/lock.mqtt.markdown index 08beb2e43aeb..1cb52e8d3961 100644 --- a/source/_integrations/lock.mqtt.markdown +++ b/source/_integrations/lock.mqtt.markdown @@ -85,6 +85,10 @@ device: description: 'The name of the device.' required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: 'The firmware version of the device.' required: false diff --git a/source/_integrations/sensor.mqtt.markdown b/source/_integrations/sensor.mqtt.markdown index f0d2dc8391b4..e082f81f8c0a 100644 --- a/source/_integrations/sensor.mqtt.markdown +++ b/source/_integrations/sensor.mqtt.markdown @@ -75,6 +75,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/switch.mqtt.markdown b/source/_integrations/switch.mqtt.markdown index 4ad3ee8f93e8..59f51b21c29b 100644 --- a/source/_integrations/switch.mqtt.markdown +++ b/source/_integrations/switch.mqtt.markdown @@ -85,6 +85,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/tag.mqtt.markdown b/source/_integrations/tag.mqtt.markdown index 1fba648a745a..1b509fd1efd6 100644 --- a/source/_integrations/tag.mqtt.markdown +++ b/source/_integrations/tag.mqtt.markdown @@ -49,6 +49,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false diff --git a/source/_integrations/vacuum.mqtt.markdown b/source/_integrations/vacuum.mqtt.markdown index 60323b25f3b6..2bc77dff3be5 100644 --- a/source/_integrations/vacuum.mqtt.markdown +++ b/source/_integrations/vacuum.mqtt.markdown @@ -348,6 +348,10 @@ device: description: The name of the device. required: false type: string + suggested_area: + description: 'Suggest an area if the device isn’t in one yet.' + required: false + type: string sw_version: description: The firmware version of the device. required: false From ff80b77bbd955890c1ffd04a6067b553019aa5ad Mon Sep 17 00:00:00 2001 From: Franck Nijhof Date: Tue, 16 Mar 2021 00:47:15 +0100 Subject: [PATCH 32/65] Add config flow to Verisure (#17000) --- source/_integrations/verisure.markdown | 72 ++------------------------ 1 file changed, 3 insertions(+), 69 deletions(-) diff --git a/source/_integrations/verisure.markdown b/source/_integrations/verisure.markdown index 97a90b73d591..c2e002ab1a48 100644 --- a/source/_integrations/verisure.markdown +++ b/source/_integrations/verisure.markdown @@ -21,6 +21,8 @@ ha_platforms: - lock - sensor - switch +ha_config_flow: true +ha_dhcp: true --- Home Assistant has support to integrate your [Verisure](https://www.verisure.com/) devices. @@ -34,75 +36,7 @@ There is currently support for the following device types within Home Assistant: - Lock - Binary Sensor (Door & Window) -## Configuration - -To integrate Verisure with Home Assistant, add the following section to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -verisure: - username: USERNAME - password: PASSWORD -``` - -{% configuration %} -username: - description: The username to Verisure mypages. - required: true - type: string -password: - description: The password to Verisure mypages. - required: true - type: string -alarm: - description: Set to `true` to show alarm, `false` to disable. - required: false - type: boolean - default: true -hygrometers: - description: Set to `true` to show hygrometers, `false` to disable. - required: false - type: boolean - default: true -smartplugs: - description: Set to `true` to show smartplugs, `false` to disable. - required: false - type: boolean - default: true -locks: - description: Set to `true` to show locks, `false` to disable. - required: false - type: boolean - default: true -default_lock_code: - description: Code that will be used to lock or unlock, if none is supplied. - required: false - type: string -thermometers: - description: Set to `true` to show thermometers, `false` to disable. - required: false - type: boolean - default: true -mouse: - description: Set to `true` to show mouse detectors, `false` to disable. - required: false - type: boolean - default: true -door_window: - description: Set to `true` to show doors and windows, `false` to disable. - required: false - type: boolean - default: true -code_digits: - description: Number of digits in PIN code. - required: false - type: integer - default: 4 -giid: - description: The GIID of your installation (If you have more then one alarm system). To find the GIID for your systems run `python verisure.py` EMAIL PASSWORD installations'. - required: false - type: string -{% endconfiguration %} +{% include integrations/config_flow.md %} ## Alarm Control Panel From 173875f77ce21a66e65dfa83aab2a287242bf70f Mon Sep 17 00:00:00 2001 From: Kevin Worrel <37058192+dieselrabbit@users.noreply.github.com> Date: Tue, 16 Mar 2021 16:32:17 -0700 Subject: [PATCH 33/65] Add screenlogic integration documentation (#17010) Add documentation for Pentair ScreenLogic integration. --- source/_integrations/screenlogic.markdown | 33 +++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 source/_integrations/screenlogic.markdown diff --git a/source/_integrations/screenlogic.markdown b/source/_integrations/screenlogic.markdown new file mode 100644 index 000000000000..be182dacf94d --- /dev/null +++ b/source/_integrations/screenlogic.markdown @@ -0,0 +1,33 @@ +--- +title: "Pentair ScreenLogic" +description: "Instructions on how to integrate a ScreenLogic gateway within Home Assistant." +ha_release: "2021.4" +ha_category: + - Hub + - Sensor + - Binary Sensor + - Switch + - Water Heater +ha_iot_class: "Local Polling" +ha_quality_scale: gold +ha_config_flow: true +ha_dhcp: true +ha_codeowners: + - '@dieselrabbit' +ha_domain: screenlogic +ha_platforms: + - switch + - binary_sensor + - sensor + - water_heater +--- + +The Pentair ScreenLogic integration allows you to integrate your Pentair Intellitouch or EasyTouch pool controller with Home Assistant via the [Pentair ScreenLogic](https://www.pentair.com/en-us/products/residential/pool-spa-equipment/pool-automation/screenlogic2_interfaceforintellitouchandeasytouchautomationsystems.html) gateway. + +{% include integrations/config_flow.md %} + +## Options + +ScreenLogic options are set via **Configuration** -> **Integrations** -> **Pentair ScreenLogic** -> **Options**. + +* Seconds between scans - How many seconds between each polling of the ScreenLogic gateway. From ffe95a0214d090573fd355f53583da1f48f63757 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Thu, 18 Mar 2021 10:56:21 +0100 Subject: [PATCH 34/65] Update to new entity model introducing percentage and preset modes --- source/_docs/mqtt/discovery.markdown | 9 +++ source/_integrations/fan.mqtt.markdown | 79 +++++++++++++++++++------- 2 files changed, 69 insertions(+), 19 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index bd40db3fe5bc..85f38a6dc1d0 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -156,6 +156,9 @@ Supported abbreviations: 'osc_cmd_t': 'oscillation_command_topic', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', + 'pct_cmd_t': 'percentage_command_topic', + 'pct_stat_t': 'percentage_state_topic', + 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_home': 'payload_arm_home', @@ -192,6 +195,10 @@ Supported abbreviations: 'pow_cmd_t': 'power_command_topic', 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', + 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_stat_t': 'preset_mode_state_topic', + 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', 'rgb_cmd_tpl': 'rgb_command_template', @@ -207,6 +214,8 @@ Supported abbreviations: 'pos_tpl': 'position_template', 'spd_cmd_t': 'speed_command_topic', 'spd_stat_t': 'speed_state_topic', + 'spd_rng_min': 'speed_range_min', + 'spd_rng_max': 'speed_range_max', 'spd_val_tpl': 'speed_value_template', 'spds': 'speeds', 'src_type': 'source_type', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index cd43ae5c1ad1..581966855f2a 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -129,17 +129,17 @@ payload_available: type: string default: online payload_high_speed: - description: The payload that represents the fan's high speed. + description: DEPRECATED - The payload that represents the fan's high speed. required: false type: string default: high payload_low_speed: - description: The payload that represents the fan's low speed. + description: DEPRECATED - The payload that represents the fan's low speed. required: false type: string default: low payload_medium_speed: - description: The payload that represents the fan's medium speed. + description: DEPRECATED - The payload that represents the fan's medium speed. required: false type: string default: medium @@ -168,6 +168,35 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_topic: + description: The MQTT topic to publish commands to change the fan speed state based on a percentage. + required: false + type: string +percentage_state_topic: + description: The MQTT topic subscribed to receive fan speed based on percentage. + required: false + type: string +percentage_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. + required: false + type: string +preset_mode_command_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_state_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the preset_mode payload. + required: false + type: string +preset_modes: + description: List of preset modes this fan is capable of running at. Common examples include `auto`, `smart`, `whoosh`, `eco` and `breeze`. + required: false + type: [list] + default: [] qos: description: The maximum QoS level of the state topic. required: false @@ -179,19 +208,29 @@ retain: type: boolean default: true speed_command_topic: - description: The MQTT topic to publish commands to change speed state. + description: DEPRECATED - The MQTT topic to publish commands to change speed state. required: false type: string +speed_range_min: + description: The minimum of numeric output range (`off` not included). + required: false + type: integer + default: 1 +speed_range_max: + description: The maximum of numeric output range (representing 100%). + required: false + type: integer + default: 100 speed_state_topic: - description: The MQTT topic subscribed to receive speed state updates. + description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. required: false type: string speed_value_template: - description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." + description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." required: false type: string speeds: - description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." + description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." required: false type: [string, list] state_topic: @@ -220,10 +259,10 @@ In this section you find some real-life examples of how to use this fan. ### Full configuration -The example below shows a full configuration for a MQTT fan. +The example below shows a full configuration for a MQTT fan using percentage and preset modes. ```yaml -# Example configuration.yaml entry +# Example using percentage based speeds with preset modes configuration.yaml fan: - platform: mqtt name: "Bedroom Fan" @@ -231,19 +270,21 @@ fan: command_topic: "bedroom_fan/on/set" oscillation_state_topic: "bedroom_fan/oscillation/state" oscillation_command_topic: "bedroom_fan/oscillation/set" - speed_state_topic: "bedroom_fan/speed/state" - speed_command_topic: "bedroom_fan/speed/set" + percentage_state_topic: "bedroom_fan/speed/percentage_state" + percentage_command_topic: "bedroom_fan/speed/percentage" + preset_mode_state_topic: "bedroom_fan/speed/preset_mode_state" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" qos: 0 payload_on: "true" payload_off: "false" payload_oscillation_on: "true" payload_oscillation_off: "false" - payload_low_speed: "low" - payload_medium_speed: "medium" - payload_high_speed: "high" - speeds: - - "off" - - low - - medium - - high + speed_range_min: 1 + speed_range_max: 100 ``` From 3ca3a44751ece4a17cb2319eb119d48c36aaafb9 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Thu, 18 Mar 2021 11:26:32 +0100 Subject: [PATCH 35/65] Support preset modes and percentage for mqtt fan --- source/_docs/mqtt/discovery.markdown | 9 +++ source/_integrations/fan.mqtt.markdown | 79 +++++++++++++++++++------- 2 files changed, 69 insertions(+), 19 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index bd40db3fe5bc..85f38a6dc1d0 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -156,6 +156,9 @@ Supported abbreviations: 'osc_cmd_t': 'oscillation_command_topic', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', + 'pct_cmd_t': 'percentage_command_topic', + 'pct_stat_t': 'percentage_state_topic', + 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_home': 'payload_arm_home', @@ -192,6 +195,10 @@ Supported abbreviations: 'pow_cmd_t': 'power_command_topic', 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', + 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_stat_t': 'preset_mode_state_topic', + 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', 'rgb_cmd_tpl': 'rgb_command_template', @@ -207,6 +214,8 @@ Supported abbreviations: 'pos_tpl': 'position_template', 'spd_cmd_t': 'speed_command_topic', 'spd_stat_t': 'speed_state_topic', + 'spd_rng_min': 'speed_range_min', + 'spd_rng_max': 'speed_range_max', 'spd_val_tpl': 'speed_value_template', 'spds': 'speeds', 'src_type': 'source_type', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index cd43ae5c1ad1..581966855f2a 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -129,17 +129,17 @@ payload_available: type: string default: online payload_high_speed: - description: The payload that represents the fan's high speed. + description: DEPRECATED - The payload that represents the fan's high speed. required: false type: string default: high payload_low_speed: - description: The payload that represents the fan's low speed. + description: DEPRECATED - The payload that represents the fan's low speed. required: false type: string default: low payload_medium_speed: - description: The payload that represents the fan's medium speed. + description: DEPRECATED - The payload that represents the fan's medium speed. required: false type: string default: medium @@ -168,6 +168,35 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_topic: + description: The MQTT topic to publish commands to change the fan speed state based on a percentage. + required: false + type: string +percentage_state_topic: + description: The MQTT topic subscribed to receive fan speed based on percentage. + required: false + type: string +percentage_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. + required: false + type: string +preset_mode_command_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_state_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the preset_mode payload. + required: false + type: string +preset_modes: + description: List of preset modes this fan is capable of running at. Common examples include `auto`, `smart`, `whoosh`, `eco` and `breeze`. + required: false + type: [list] + default: [] qos: description: The maximum QoS level of the state topic. required: false @@ -179,19 +208,29 @@ retain: type: boolean default: true speed_command_topic: - description: The MQTT topic to publish commands to change speed state. + description: DEPRECATED - The MQTT topic to publish commands to change speed state. required: false type: string +speed_range_min: + description: The minimum of numeric output range (`off` not included). + required: false + type: integer + default: 1 +speed_range_max: + description: The maximum of numeric output range (representing 100%). + required: false + type: integer + default: 100 speed_state_topic: - description: The MQTT topic subscribed to receive speed state updates. + description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. required: false type: string speed_value_template: - description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." + description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." required: false type: string speeds: - description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." + description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." required: false type: [string, list] state_topic: @@ -220,10 +259,10 @@ In this section you find some real-life examples of how to use this fan. ### Full configuration -The example below shows a full configuration for a MQTT fan. +The example below shows a full configuration for a MQTT fan using percentage and preset modes. ```yaml -# Example configuration.yaml entry +# Example using percentage based speeds with preset modes configuration.yaml fan: - platform: mqtt name: "Bedroom Fan" @@ -231,19 +270,21 @@ fan: command_topic: "bedroom_fan/on/set" oscillation_state_topic: "bedroom_fan/oscillation/state" oscillation_command_topic: "bedroom_fan/oscillation/set" - speed_state_topic: "bedroom_fan/speed/state" - speed_command_topic: "bedroom_fan/speed/set" + percentage_state_topic: "bedroom_fan/speed/percentage_state" + percentage_command_topic: "bedroom_fan/speed/percentage" + preset_mode_state_topic: "bedroom_fan/speed/preset_mode_state" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" qos: 0 payload_on: "true" payload_off: "false" payload_oscillation_on: "true" payload_oscillation_off: "false" - payload_low_speed: "low" - payload_medium_speed: "medium" - payload_high_speed: "high" - speeds: - - "off" - - low - - medium - - high + speed_range_min: 1 + speed_range_max: 100 ``` From 85f265312783881988427de18113984d5847a495 Mon Sep 17 00:00:00 2001 From: Andreas <28764847+andreas-amlabs@users.noreply.github.com> Date: Thu, 18 Mar 2021 12:42:59 +0100 Subject: [PATCH 36/65] Amcrest add documentation for CrossLineDetected (#16033) Co-authored-by: andreas-amlabs --- source/_integrations/amcrest.markdown | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/_integrations/amcrest.markdown b/source/_integrations/amcrest.markdown index 1c266a8d6ff5..fd642957a8de 100644 --- a/source/_integrations/amcrest.markdown +++ b/source/_integrations/amcrest.markdown @@ -117,6 +117,10 @@ binary_sensors: description: "Return `on` when a motion is detected, `off` when not. Motion detection is enabled by default for most cameras, if this functionality is not working check that it is enabled in Settings > Events > Video Detection. Uses streaming method (see [below](#streaming-vs-polled-binary-sensors))." motion_detected_polled: description: "Return `on` when a motion is detected, `off` when not. Motion detection is enabled by default for most cameras, if this functionality is not working check that it is enabled in Settings > Events > Video Detection. Uses polled method (see [below](#streaming-vs-polled-binary-sensors))." + crossline_detected: + description: "Return `on` when a tripwire tripping is detected, `off` when not. Uses streaming method (see [below](#streaming-vs-polled-binary-sensors))." + crossline_detected_polled: + description: "Return `on` when a tripwire is tripping is detected, `off` when not. Uses polled method (see [below](#streaming-vs-polled-binary-sensors))." online: description: "Return `on` when camera is available (i.e., responding to commands), `off` when not." sensors: @@ -377,6 +381,7 @@ amcrest: password: YOUR_PASSWORD binary_sensors: - motion_detected + - crossline_detected - online sensors: - sdcard From f00dd8f833aebe8cd5f30cbef27356deddaec28a Mon Sep 17 00:00:00 2001 From: elyobelyob Date: Thu, 18 Mar 2021 18:27:26 +0000 Subject: [PATCH 37/65] Url option (#17026) --- source/_integrations/prowl.markdown | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/_integrations/prowl.markdown b/source/_integrations/prowl.markdown index f9ce195bdb34..ea7e84b83e64 100644 --- a/source/_integrations/prowl.markdown +++ b/source/_integrations/prowl.markdown @@ -40,8 +40,9 @@ api_key: The following attributes can be placed `data` for extended functionality. -| Service data attribute | Optional | Description | -| ---------------------- | -------- | ----------- | -| `priority` | yes | Priority level, for more info refer to the [Prowl API documentation](https://www.prowlapp.com/api.php#add). | +| Service data attribute | Optional | Default | Description | +| ---------------------- | -------- | ------- | ----------- | +| `priority` | yes | 0 | Priority level, for more info refer to the [Prowl API documentation](https://www.prowlapp.com/api.php#add). | +| `url` | yes | n/a | URL to be attached, for more info refer to the [Prowl API documentation](https://www.prowlapp.com/api.php#add). | To use notifications, please see the [getting started with automation page](/getting-started/automation/). From 74c562332388e4a68665f7a6d4a4f47871af0233 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hans=20Kr=C3=B6ner?= Date: Fri, 19 Mar 2021 19:53:44 +0100 Subject: [PATCH 38/65] Update documentation for the OpenWeatherMap integration (#17060) --- source/_integrations/openweathermap.markdown | 64 ++++++++++++++------ 1 file changed, 45 insertions(+), 19 deletions(-) diff --git a/source/_integrations/openweathermap.markdown b/source/_integrations/openweathermap.markdown index edd7e5aa66f5..445062bffbba 100644 --- a/source/_integrations/openweathermap.markdown +++ b/source/_integrations/openweathermap.markdown @@ -37,35 +37,61 @@ You need an API key, which is free, but requires a [registration](https://home.o | Mode | Forecast mode, `hourly` for a three-hour forecast, `daily` for daily forecast using a paid API tier, `onecall_hourly` for an hourly forecast up to 2 days, or `onecall_daily` for a daily forecast up to 7 days (ideal for the free tier). | | Language | Language for receiving data (only for `sensor`) | -The integration creates weather entity and also sensors for all available conditions. -Selecting a `onecall` mode with the free tier leverages the One Call API, resulting in updates every 5 minutes and is recommended for both hourly and daily forecast. +The integration creates a weather entity as well as sensors for supported weather conditions. +Selecting a `onecall` forecast mode with the free tier leverages the One Call API, resulting in updates every 5 minutes and is recommended for both hourly and daily forecast. -For each condition `sensor` entity will be created with id: +A `sensor` entity will be created for each supported condition. Their ids will follow the format: `sensor._` -Sensor prints information in language which was selected for integration. +Sensors provide data in the language that was selected when configuring the integration. -All conditions: +
    + +The Weather entity provides data only in English. Home Assistant automatically translates it to the language configured for the frontend. -| Condition | Description | -| :------------- | :----------------------------------- | -| `weather` | A human-readable text summary. | -| `temperature` | Current temperature. | -| `wind_speed` | Wind speed. | -| `wind_bearing` | Wind bearing. | -| `humidity` | Relative humidity. | -| `pressure` | Sea-level air pressure in millibars. | -| `clouds` | Description of cloud coverage. | -| `rain` | Rain volume. | -| `snow` | Snow volume. | -| `condition` | Current weather condition code. | -| `weather_code` | Current weather code. | +
    + +## Supported Weather Conditions + +### Current Weather Conditions + +| Condition | Description | +| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------ | +| `cloud_coverage` | Cloudiness, %. | +| `condition` | [Weather condition](https://developers.home-assistant.io/docs/core/entity/weather/#recommended-values-for-state-and-condition). | +| `dew_point` | Atmospheric temperature below which water droplets begin to condense and dew can form, ºC. | +| `feels_like_temperature` | Temperature accounting for the human perception of weather, ºC. | +| `humidity` | Humidity, %. | +| `precipitation_kind` | The kind of precipitation (Rain, Snow, Snow and Rain, None) for the last hour. | +| `pressure` | Atmospheric pressure at sea level, hPa. | +| `rain` | Rain volume for the last hour, mm. | +| `snow` | Snow volume for the last hour, mm. | +| `temperature` | Temperature, ºC. | +| `uv_index` | UV Index. | +| `weather` | A human-readable description of the [weather condition](https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2). | +| `weather_code` | ID of the [weather condition](https://openweathermap.org/weather-conditions#Weather-Condition-Codes-2). | +| `wind_bearing` | Wind direction, degrees (meteorological). | +| `wind_speed` | Wind speed, metre/sec. | + +### Forecast Weather Conditions
    -Weather entity always will have English language. Home Assistant translate it to user language automatically. +The time period these sensors use depends on the forecast mode selected when configuring the integration: `hourly` or `onecall_hourly` will show conditions for the current hour of the day, while `daily` or `onecall_daily` will show conditions for the current day.
    +| Condition | Description | +| :----------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `forecast_condition` | [Weather condition](https://developers.home-assistant.io/docs/core/entity/weather/#recommended-values-for-state-and-condition) for the forecast's time period. | +| `forecast_precipitation` | Combined Rain and Snow volume for the forecast's time period, mm. | +| `forecast_precipitation_probability` | Probability of precipitation for the forecast's time period. | +| `forecast_pressure` | Atmospheric pressure at sea level for the forecast's time period, hPa. | +| `forecast_temperature` | Maximum temperature for the day. | +| `forecast_temperature_low` | Minimum temperature for the day. | +| `forecast_time` | Time of the forecasted data. | +| `forecast_wind_bearing` | Wind direction for the forecast's time period, degrees (meteorological). | +| `forecast_wind_speed` | Wind speed for the forecast's time period, metre/sec. | + Details about the API are available in the [OpenWeatherMap documentation](https://openweathermap.org/api). From bd4da144858c063be8b3c6b9600d85fe76144e02 Mon Sep 17 00:00:00 2001 From: Antoine Meillet Date: Fri, 19 Mar 2021 21:41:28 +0100 Subject: [PATCH 39/65] Add details about unavailable and unknown states for Prometheus (#17039) Co-authored-by: Franck Nijhof --- source/_integrations/prometheus.markdown | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/source/_integrations/prometheus.markdown b/source/_integrations/prometheus.markdown index b7b7623abe23..3e541e0aa0b9 100644 --- a/source/_integrations/prometheus.markdown +++ b/source/_integrations/prometheus.markdown @@ -179,3 +179,16 @@ When looking into the metrics on the Prometheus side, there will be: - The [client library](https://github.com/prometheus/client_python) provided metrics, which are a bunch of **process_\*** and also a single pseudo-metric **python_info** which contains (not as value but as labels) information about the Python version of the client, i.e., the Home Assistant Python interpreter. Typically, you will only be interested in the first set of metrics. + +## Metrics in unavailable or unknown states + +When the Prometheus exporter starts (typically when Home Assistant starts), all non-excluded entities in an unavailable or unknown state are not be exported until they are available again. If the entity goes into state unavailable or unknown again, the value exported will always be the latest known one. + +While an entity is in those states, the `entity_available` corresponding metric is set to 0. This metric can be used to filter out values while the entity is unavailable or in an unknown state thanks to a [recording rule](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/). + +For example: + +```yaml +- record: "known_temperature_c" + expr: "temperature_c unless entity_available == 0" +``` From 5dd8aea9b0e960fc5f4cb6babe9466ed94257041 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Fri, 19 Mar 2021 15:42:43 -0500 Subject: [PATCH 40/65] Add homeassistant.reload_config_entry service (#16976) --- source/_integrations/homeassistant.markdown | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/_integrations/homeassistant.markdown b/source/_integrations/homeassistant.markdown index cd242cb82acb..1b2768f2e33a 100644 --- a/source/_integrations/homeassistant.markdown +++ b/source/_integrations/homeassistant.markdown @@ -21,6 +21,16 @@ The `homeassistant` integration provides services for controlling Home Assistant Reads the configuration files and checks them for correctness, but **does not** load them into Home Assistant. Creates a persistent notification and log entry if errors are found. +### Service `homeassistant.reload_config_entry` + +Reloads an integration config entry. + +| Service data attribute | Description | +|---------------------------|-------------------------------------------------------| +| `entity_id` | List of entity ids used to reference a config entry. | +| `area_id` | List of area ids used to reference a config entry. | +| `device_id` | List of device ids used to reference a config entry. | + ### Service `homeassistant.reload_core_config` Reloads the core configuration under `homeassistant:` and all linked files. Once loaded the new configuration is applied. New `customize:` information will be applied the next time the state of the entity gets updated. From ed3cfd06219b2893411d92ebe6686e7e7ad0aae4 Mon Sep 17 00:00:00 2001 From: bestlibre Date: Fri, 19 Mar 2021 22:08:52 +0100 Subject: [PATCH 41/65] Add notification with images example (#13943) Co-authored-by: Franck Nijhof --- source/_integrations/matrix.markdown | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/source/_integrations/matrix.markdown b/source/_integrations/matrix.markdown index 9c2bda7d82b0..d334d064aecb 100644 --- a/source/_integrations/matrix.markdown +++ b/source/_integrations/matrix.markdown @@ -175,3 +175,18 @@ default_room: The target room has to be precreated, the room id can be obtained from the rooms settings dialog. Rooms by default have a canonical id of the form `"!:homeserver.tld"`, but can also be allocated aliases like `"#roomname:homeserver.tld"`. Make sure to use quotes around the room id or alias to escape special characters (`!`, and `#`) in YAML. The notifying account may need to be invited to the room, depending on the individual rooms policies. To use notifications, please see the [getting started with automation page](/getting-started/automation/). + +### Images in notification + +It is possible to send images with notifications. To do so, add a list of paths in the notification `data`. + +```yaml +# Example of notification with images +action: + service: notify.matrix_notify + data: + message: "Test with images" + data: + images: + - /path/to/picture.jpg +``` From f0b0e8b8058fdc8c8064a81a651dec5699943e44 Mon Sep 17 00:00:00 2001 From: Dan Klaffenbach Date: Fri, 19 Mar 2021 22:09:41 +0100 Subject: [PATCH 42/65] Add join/unjoin documentation for media_player (#16442) --- source/_integrations/media_player.markdown | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/source/_integrations/media_player.markdown b/source/_integrations/media_player.markdown index 78d48f85693f..60430774f15a 100644 --- a/source/_integrations/media_player.markdown +++ b/source/_integrations/media_player.markdown @@ -14,7 +14,7 @@ Interacts with media players on your network. ## Services ### Media control services -Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, `volume_set`, `volume_mute`, `media_play_pause`, `media_play`, `media_pause`, `media_stop`, `media_next_track`, `media_previous_track`, `clear_playlist`, `shuffle_set`, `repeat_set`, `play_media`, `select_source`, `select_sound_mode` +Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, `volume_set`, `volume_mute`, `media_play_pause`, `media_play`, `media_pause`, `media_stop`, `media_next_track`, `media_previous_track`, `clear_playlist`, `shuffle_set`, `repeat_set`, `play_media`, `select_source`, `select_sound_mode`, `join`, `unjoin` | Service data attribute | Optional | Description | | ---------------------- | -------- | ------------------------------------------------ | @@ -156,6 +156,21 @@ Currently only supported on [Sonos](/integrations/sonos), [Spotify](/integration | `entity_id` | yes | Target a specific media player. For example `media_player.kitchen`| | `repeat` | no | `off`/`all`/`one` for setting repeat mode | +#### Service `media_player.join` + +Allows to group media players together for synchronous playback. Only works on supported multiroom audio systems. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ---------------------------------------------------- | +| `entity_id` | yes | The media player entity whose playback will be expanded to the players specified in `group_members`. | +| `group_members` | no | The player entities which will be synced with the playback from `entity_id`. | + +#### Service `media_player.unjoin` + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ---------------------------------------------------- | +| `entity_id` | yes | Unjoin this media player from any player groups. | + ### Device Class The way media players are displayed in the frontend can be modified in the [customize section](/getting-started/customizing-devices/). The following device classes are supported for media players: From 324ce5c8deb0ddbabfbb93722d7450c00d754c3a Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sun, 21 Mar 2021 21:17:54 -1000 Subject: [PATCH 43/65] Update august to be cloud push (#17074) --- source/_integrations/august.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/august.markdown b/source/_integrations/august.markdown index c357686cd2ff..2d82264b5680 100644 --- a/source/_integrations/august.markdown +++ b/source/_integrations/august.markdown @@ -8,7 +8,7 @@ ha_category: - Camera - Lock ha_release: 0.64 -ha_iot_class: Cloud Polling +ha_iot_class: Cloud Push ha_config_flow: true ha_codeowners: - '@bdraco' From dc1b6f8786a26961255a3d63c29013994b762ef1 Mon Sep 17 00:00:00 2001 From: Dermot Duffy Date: Mon, 22 Mar 2021 07:59:33 -0700 Subject: [PATCH 44/65] Add documentation for Hyperion effect hide option (#16344) --- source/_integrations/hyperion.markdown | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/_integrations/hyperion.markdown b/source/_integrations/hyperion.markdown index d7c6ae197f03..f2e0b0ebbd76 100644 --- a/source/_integrations/hyperion.markdown +++ b/source/_integrations/hyperion.markdown @@ -32,8 +32,9 @@ All configuration options are offered from the frontend. Choose `Options` under relevant entry on the `Integrations` page. Options supported: -- **priority**: The priority for color and effects, make sure this is lower then the streaming sources priority in hyperion itself (typically lower than 200 is appropriate). - +- **Priority**: The priority for color and effects, make sure this is lower then the streaming sources priority in hyperion itself (typically lower than 200 is appropriate). +- **Effects to hide**: An optional selection of effects to hide from the light effects + list. New effects added to the Hyperion server will be shown by default. ## Hyperion Instances This integration supports multiple Hyperion instances running on a single Hyperion From ed89896ab3f3bac673c689077671541a7ce0e8b9 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Mon, 22 Mar 2021 05:39:45 -1000 Subject: [PATCH 45/65] Update homekit for activity based remotes (#17081) --- source/_integrations/homekit.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index cba7290dd815..947a7f8e5725 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -307,7 +307,7 @@ It is recommended to only edit a HomeKit instance in the UI that was created in ### Accessory mode -When exposing a Camera or Television media player (a `media_player` with device class `tv`) to HomeKit, `mode` must be set to `accessory`, and the include filter should be setup to only include a single entity. +When exposing a Camera, Activity based remote (a `remote` that supports activities), or Television media player (a `media_player` with device class `tv`) to HomeKit, `mode` must be set to `accessory`, and the include filter should be setup to only include a single entity. To quickly add all accessory modes entities in the UI: From 28a4c4a642f3071bc560e308b027928d09df7fea Mon Sep 17 00:00:00 2001 From: Kevin Worrel <37058192+dieselrabbit@users.noreply.github.com> Date: Mon, 22 Mar 2021 08:41:31 -0700 Subject: [PATCH 46/65] Update screenlogic from water_heater to climate (#17073) Update screenlogic for move from water_heater to climate --- source/_integrations/screenlogic.markdown | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/_integrations/screenlogic.markdown b/source/_integrations/screenlogic.markdown index be182dacf94d..866349f6c7ab 100644 --- a/source/_integrations/screenlogic.markdown +++ b/source/_integrations/screenlogic.markdown @@ -4,10 +4,10 @@ description: "Instructions on how to integrate a ScreenLogic gateway within Home ha_release: "2021.4" ha_category: - Hub - - Sensor - Binary Sensor + - Climate + - Sensor - Switch - - Water Heater ha_iot_class: "Local Polling" ha_quality_scale: gold ha_config_flow: true @@ -16,10 +16,10 @@ ha_codeowners: - '@dieselrabbit' ha_domain: screenlogic ha_platforms: - - switch - binary_sensor + - climate - sensor - - water_heater + - switch --- The Pentair ScreenLogic integration allows you to integrate your Pentair Intellitouch or EasyTouch pool controller with Home Assistant via the [Pentair ScreenLogic](https://www.pentair.com/en-us/products/residential/pool-spa-equipment/pool-automation/screenlogic2_interfaceforintellitouchandeasytouchautomationsystems.html) gateway. From 9582b227bc2d42aa1468690ba272a394536cb593 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Wed, 24 Mar 2021 15:05:07 -1000 Subject: [PATCH 47/65] Update zeroconf default behavior for most common setups (including Home Assistant Operating System) (#17124) --- source/_integrations/zeroconf.markdown | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/_integrations/zeroconf.markdown b/source/_integrations/zeroconf.markdown index 55f500cf875c..a578cd77ac1f 100644 --- a/source/_integrations/zeroconf.markdown +++ b/source/_integrations/zeroconf.markdown @@ -30,10 +30,10 @@ zeroconf: type: map keys: default_interface: - description: By default, `zeroconf` will attempt to bind to all interfaces. For systems running using network isolation or similar, this may result in `zeroconf` being unavailable. Change this option to `true` if `zeroconf` does not function. + description: By default, `zeroconf` will broadcast on the default interface. For systems that require broadcasting `mdns` on all interfaces, change this option to `false` if `zeroconf` does not function. required: false type: boolean - default: false + default: true ipv6: description: By default, `zeroconf` will enable IPv6 support. If your network has trouble with IPv6 being enabled, you can set this option to `false`. required: false From 6db4074bce5e1b73df1b4559fc24e37959031d2a Mon Sep 17 00:00:00 2001 From: Boris Gulay Date: Thu, 25 Mar 2021 11:18:35 +0300 Subject: [PATCH 48/65] Add new protocol key descr for graphite (#15780) Co-authored-by: Klaas Schoute Co-authored-by: Franck Nijhof --- source/_integrations/graphite.markdown | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/_integrations/graphite.markdown b/source/_integrations/graphite.markdown index 32b19ee28628..03b766a06507 100644 --- a/source/_integrations/graphite.markdown +++ b/source/_integrations/graphite.markdown @@ -29,6 +29,11 @@ port: required: false type: integer default: 2003 +protocol: + description: "Type of communication protocol: `tcp` or `udp`." + required: false + type: string + default: tcp prefix: description: Prefix is the metric prefix in graphite. required: false From 6daf63dbddb1c71ae03b7e36123a0ed7e3e1466e Mon Sep 17 00:00:00 2001 From: Alexey Kustov Date: Thu, 25 Mar 2021 22:38:25 +0400 Subject: [PATCH 49/65] Add opportunity to define token for each message (#16771) --- source/_integrations/notify_events.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_integrations/notify_events.markdown b/source/_integrations/notify_events.markdown index dfac00790a3c..ca1b1e39eb5c 100644 --- a/source/_integrations/notify_events.markdown +++ b/source/_integrations/notify_events.markdown @@ -104,6 +104,7 @@ The following attributes can be placed inside `data` for extended functionality. | `priority` | For recipients which supports priority, the message will be highlighted accordingly.
    Available values: `lowest`, `low`, `normal`, `high`, `highest`. | `images` | Array of images to attach (see item properties below). | `files` | Array of files to attach (see item properties below). +| `token` | Notify.Events channel token (in case you want to override the channel to get this message to). Every item of images and files has the following properties: From 782092ae35132bd479d0c8d1c99ba318dbf573b3 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Fri, 26 Mar 2021 10:02:29 +0100 Subject: [PATCH 50/65] Remove deprecated items, fix typo --- source/_docs/mqtt/discovery.markdown | 2 +- source/_integrations/fan.mqtt.markdown | 33 +------------------------- 2 files changed, 2 insertions(+), 33 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 85f38a6dc1d0..25834c0f317d 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -197,7 +197,7 @@ Supported abbreviations: 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_stat_t': 'preset_mode_state_topic', - 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 581966855f2a..01263e366ab5 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -128,21 +128,6 @@ payload_available: required: false type: string default: online -payload_high_speed: - description: DEPRECATED - The payload that represents the fan's high speed. - required: false - type: string - default: high -payload_low_speed: - description: DEPRECATED - The payload that represents the fan's low speed. - required: false - type: string - default: low -payload_medium_speed: - description: DEPRECATED - The payload that represents the fan's medium speed. - required: false - type: string - default: medium payload_not_available: description: The payload that represents the unavailable state. required: false @@ -207,12 +192,8 @@ retain: required: false type: boolean default: true -speed_command_topic: - description: DEPRECATED - The MQTT topic to publish commands to change speed state. - required: false - type: string speed_range_min: - description: The minimum of numeric output range (`off` not included). + description: The minimum of numeric output range (`off` not included, so `speed_range_min` - 1 represents 0%). required: false type: integer default: 1 @@ -221,18 +202,6 @@ speed_range_max: required: false type: integer default: 100 -speed_state_topic: - description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. - required: false - type: string -speed_value_template: - description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." - required: false - type: string -speeds: - description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." - required: false - type: [string, list] state_topic: description: The MQTT topic subscribed to receive state updates. required: false From 163c4758e2a7add476d6f445c6aa3cb7163cbd47 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Sat, 27 Mar 2021 19:11:09 +0100 Subject: [PATCH 51/65] Support for command templates --- source/_docs/mqtt/discovery.markdown | 3 ++ source/_integrations/fan.mqtt.markdown | 40 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 25834c0f317d..dbb0e9d2dc28 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -154,9 +154,11 @@ Supported abbreviations: 'on_cmd_type': 'on_command_type', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', + 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'pct_cmd_t': 'percentage_command_topic', + 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', @@ -196,6 +198,7 @@ Supported abbreviations: 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 01263e366ab5..bc0878e171f8 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -56,6 +56,10 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. + required: false + type: template command_topic: description: The MQTT topic to publish commands to change the fan state. required: true @@ -111,6 +115,10 @@ optimistic: required: false type: boolean default: "`true` if no state topic defined, else `false`." +oscillation_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `oscillation_command_topic`. + required: false + type: template oscillation_command_topic: description: The MQTT topic to publish commands to change the oscillation state. required: false @@ -153,6 +161,10 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `percentage_command_topic`. + required: false + type: template percentage_command_topic: description: The MQTT topic to publish commands to change the fan speed state based on a percentage. required: false @@ -165,6 +177,10 @@ percentage_value_template: description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. required: false type: string +preset_mode_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `preset_mode_command_topic`. + required: false + type: template preset_mode_command_topic: description: The MQTT topic to publish commands to change the preset mode. required: false @@ -257,3 +273,27 @@ fan: speed_range_min: 1 speed_range_max: 100 ``` + +This example demonstrates how to use command templates. + +```yaml +# Example configuration.yaml +# Example using command templates +fan: + - platform: mqtt + name: "Bedroom Fan" + command_topic: "bedroom_fan/on/set" + command_template: "{ state: '{{ value }}'}" + oscillation_command_topic: "bedroom_fan/oscillation/set" + oscillation_command_template: "{ oscillation: '{{ value }}'}" + percentage_command_topic: "bedroom_fan/speed/percentage" + percentage_command_template: "{ percentage: {{ value }}}" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_mode_command_template: "{ preset_mode: '{{ value }}'}" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" +``` From 1deeb0433dd4ad186e2903e4f460214d4b2430c6 Mon Sep 17 00:00:00 2001 From: Christian Soltenborn Date: Mon, 29 Mar 2021 09:41:52 +0200 Subject: [PATCH 52/65] Added docs for new attributes (#16948) --- source/_integrations/weather.template.markdown | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/source/_integrations/weather.template.markdown b/source/_integrations/weather.template.markdown index c148a45226cc..50235f8b044c 100644 --- a/source/_integrations/weather.template.markdown +++ b/source/_integrations/weather.template.markdown @@ -56,6 +56,10 @@ humidity_template: description: The current humidity. required: true type: template +attribution_template: + description: The attribution to be shown in the frontend. + required: false + type: string pressure_template: description: The current air pressure. required: false @@ -64,6 +68,18 @@ wind_speed_template: description: The current wind speed. required: false type: template +wind_bearing_template: + description: The current wind bearing. + required: false + type: template +ozone_template: + description: The current ozone level. + required: false + type: template +visibility_template: + description: The current visibility. + required: false + type: template forecast_template: description: Daily forecast data. required: false From 18615a11b9a9552856f2613d8c8c0e4d3d001ef6 Mon Sep 17 00:00:00 2001 From: jan iversen Date: Mon, 29 Mar 2021 09:42:18 +0200 Subject: [PATCH 53/65] Update modbus configuration to use new (#16678) Co-authored-by: Franck Nijhof --- .../binary_sensor.modbus.markdown | 87 --- source/_integrations/climate.modbus.markdown | 125 ---- source/_integrations/cover.modbus.markdown | 210 ------ source/_integrations/modbus.markdown | 706 ++++++++++++++++-- source/_integrations/sensor.modbus.markdown | 145 ---- source/_integrations/switch.modbus.markdown | 137 ---- source/_redirects | 7 +- 7 files changed, 665 insertions(+), 752 deletions(-) delete mode 100644 source/_integrations/binary_sensor.modbus.markdown delete mode 100644 source/_integrations/climate.modbus.markdown delete mode 100644 source/_integrations/cover.modbus.markdown delete mode 100644 source/_integrations/sensor.modbus.markdown delete mode 100644 source/_integrations/switch.modbus.markdown diff --git a/source/_integrations/binary_sensor.modbus.markdown b/source/_integrations/binary_sensor.modbus.markdown deleted file mode 100644 index 33424ab389a5..000000000000 --- a/source/_integrations/binary_sensor.modbus.markdown +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "Modbus Binary Sensor" -description: "Instructions on how to set up Modbus binary sensors within Home Assistant." -ha_category: - - Binary Sensor -ha_release: 0.28 -ha_iot_class: Local Push -ha_domain: modbus ---- - -The `modbus` binary sensor allows you to gather data from [Modbus](http://www.modbus.org/) coils. - -## Configuration - -To use your Modbus binary sensors in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -binary_sensor: - - platform: modbus - inputs: - - name: Sensor1 - hub: hub1 - slave: 1 - address: 100 - - name: Sensor2 - hub: hub1 - slave: 1 - address: 110 - input_type: discrete_input -``` - -{% configuration %} -inputs: - description: The array contains a list of coils and discrete inputs to read from. - required: true - type: [map, list] - keys: - name: - description: Name of the sensor. - required: true - type: string - hub: - description: The name of the hub. - required: false - default: modbus_hub - type: string - slave: - description: The number of the slave (Optional for TCP and UDP Modbus). - required: true - type: integer - address: - description: Coil or discrete input Modbus address. - required: true - type: integer - input_type: - description: Modbus input type (coil, discrete_input), default coil. - required: false - type: string - device_class: - description: The [type/class](/integrations/binary_sensor/#device-class) of the binary sensor to set the icon in the frontend. - required: false - type: device_class - default: None -{% endconfiguration %} - -It's possible to change the default 30 seconds scan interval for the sensor updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. - -## Full example - -Example a sensor with a 10 seconds scan interval: - -```yaml -binary_sensor: - - platform: modbus - scan_interval: 10 - inputs: - - name: Sensor1 - hub: hub1 - slave: 1 - address: 100 - - name: Sensor2 - hub: hub1 - slave: 1 - address: 110 - input_type: discrete_input -``` diff --git a/source/_integrations/climate.modbus.markdown b/source/_integrations/climate.modbus.markdown deleted file mode 100644 index 1deeeab1c4b0..000000000000 --- a/source/_integrations/climate.modbus.markdown +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Modbus Climate" -description: "Instructions how to integrate a Modbus thermostat within Home Assistant." -ha_category: - - Climate -ha_release: 0.68 -ha_iot_class: Local Polling -ha_domain: modbus ---- - - -The `modbus` thermostat allows you to use a sensor value (current temperature) and target value (target temperature) from [Modbus](http://www.modbus.org/) registers. - -## Configuration - -To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -modbus: - - name: hub1 - type: tcp - host: IP_ADDRESS - port: 502 - - climates: - - name: Watlow F4T - slave: 1 - data_type: uint - data_count: 1 - scale: 0.1 - offset: 0 - precision: 1 - max_temp: 30 - min_temp: 15 - temp_step: 1 - target_temp_register: 2782 - current_temp_register: 27586 -``` - -{% configuration %} -name: - description: Name of the device - required: true - type: string -slave: - description: The number of the slave (Optional for tcp and upd Modbus, use 1). - required: true - type: integer -target_temp_register: - description: Register number for target temperature (Setpoint). - required: true - type: integer -current_temp_register: - description: Register number for current temperature (Process value). - required: true - type: integer -current_temp_register_type: - description: Modbus register type (holding, input) for current temperature, default holding. - required: false - type: string - default: holding -data_type: - description: Response representation (int, uint, float, custom). If float selected, value will converted to IEEE 754 floating point format. - required: false - type: string - default: float -structure: - description: "If `data_type` is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: `>i`." - required: false - type: string - default: ">f" -data_count: - description: Number of registers to read. - required: false - type: integer - default: 2 -precision: - description: Number of valid decimals. - required: false - type: integer - default: 1 -scale: - description: Scale factor (output = scale * value + offset). - required: false - type: float - default: 1 -offset: - description: Final offset (output = scale * value + offset). - required: false - type: float - default: 0 -max_temp: - description: Maximum setpoint temperature. - required: false - type: integer - default: 35 -min_temp: - description: Maximum setpoint temperature. - required: false - type: integer - default: 5 -temp_step: - description: The supported step size a target temperature can be increased/decreased. - required: false - type: float - default: 0.5 -temperature_unit: - description: Temperature unit reported by the current_temp_register. C or F - required: false - type: string - default: C -scan_interval: - description: Defines the update interval of the sensor in seconds. - required: false - type: integer - default: 15 -{% endconfiguration %} - - -### Services - -| Service | Description | -| ------- | ----------- | -| set_temperature | Set Temperature. Requires `value` to be passed in, which is the desired target temperature. `value` should be in the same type as `data_type` | diff --git a/source/_integrations/cover.modbus.markdown b/source/_integrations/cover.modbus.markdown deleted file mode 100644 index 59f6d3f25a61..000000000000 --- a/source/_integrations/cover.modbus.markdown +++ /dev/null @@ -1,210 +0,0 @@ ---- -title: "Modbus Cover" -description: "Instructions on how to integrate Modbus covers into Home Assistant." -ha_category: - - Cover -ha_release: 0.116 -ha_iot_class: Local Polling -ha_domain: modbus ---- - -The `modbus` cover platform allows you to control [Modbus](http://www.modbus.org/) covers (such as blinds, a roller shutter, or a garage door). - -## Configuration - -At the moment, we support the opening and closing of a cover. You can control your covers either using coils or holding registers. - -Cover that uses the `coil` attribute is not able to determine intermediary states such as opening and closing. Coil stores only two states — "0" means cover closed, and "1" implies cover open. To allow detecting intermediary states, we added an optional `status_register` attribute. It will enable you to write your command (e.g., to open a cover) into a coil, and read current cover status back through the register. Additionally, you can specify values for `state_open`, `state_opening`, `state_closed`, and `state_closing` attributes. These will be matched with the value read from the `status_register`. - -If your cover uses holding register to send commands (defined by the `register` attribute), it can also read the intermediary states. To adjust which value represents what state, you can fine-tune the optional state attributes, like `state_open`. These optional state values are also used for specifying values written into the register. If you specify an optional status_register attribute, cover states will be read from status_register instead of the register used for sending commands. - -To use Modbus covers in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -modbus: - - name: hub1 - type: tcp - host: IP_ADDRESS - port: 502 - - covers: - - name: Door1 - device_class: door - scan_interval: 1 - coil: 0 - - name: Door2 - device_class: door - scan_interval: 1 - coil: 1 - status_register: 1 - - name: Door3 - slave: 2 - device_class: door - scan_interval: 1 - register: 0 - state_open: 1 - state_closed: 0 -``` - -{% configuration %} -covers: - description: The array contains a list of all your Modbus covers. - required: true - type: map - keys: - slave: - description: The number of the slave (can be omitted for tcp and udp Modbus). - required: false - default: 1 - type: integer - name: - description: Name of the switch. - required: true - type: string - coil: - description: Coil address; can be omitted if a register attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. - required: true - type: integer - register: - description: Holding register address; can be omitted if a coil attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. - required: true - type: integer - status_register: - description: An address of an register, from which all the cover states will be read. If you specified `register` attribute, and not `status_register` attribute, your main register will also be used as a status register. - required: false - type: integer - status_register_type: - description: Modbus register type (holding, input), default holding. - required: false - type: string - state_open: - description: A value in `status_register` or `register` representing an open cover. If your configuration uses an `register` attribute, this value will be also written into a holding register to open the cover. - required: false - default: 1 - type: integer - state_closed: - description: A value in `status_register` or `register` representing a closed cover. If your configuration uses an `register` attribute, this value will be also written into a holding register to close the cover. - required: false - default: 0 - type: integer - state_opening: - description: A value in `status_register` or `register` telling us that the cover is opening at the moment. Note that this state should be also supported on your connected Modbus cover. If it won't write this intermediary state into the register, this state won't be detected. - required: false - default: 2 - type: integer - state_closing: - description: A value in `status_register` or `register` telling us that the cover is closing at the moment. Note that this state should be also supported on your connected Modbus cover. If it won't write this intermediary state into the register, this state won't be detected. - required: false - default: 2 - type: integer - device_class: - description: The [type/class](/integrations/cover/#device-class) of the cover to set the icon in the frontend. - required: false - type: device_class - default: None - scan_interval: - description: Defines the update interval of the sensor in seconds. - required: false - type: integer - default: 15 -{% endconfiguration %} - -## Examples - -In this section, you find some real-life examples of how to use this light. - -### Modbus cover controlled by a coil - -This example shows a configuration for a Modbus cover controlled using a coil. Intermediary states like opening/closing are not supported. The cover state is polled from Modbus every 10 seconds. - -```yaml -modbus: - - name: hub1 - type: tcp - host: IP_ADDRESS - port: 502 - - covers: - - name: Door1 - slave: 1 - coil: 1 - device_class: door - scan_interval: 10 - - name: Door2 - slave: 2 - coil: 2 - device_class: door - scan_interval: 10 -``` - -### Modbus cover controlled by a coil, it's state is read from the register - -This example shows a configuration for a Modbus cover controlled using a coil. Actual cover state is read from the `status_register`. We've also specified register values to match with the states open/opening/closed/closing. The cover state is polled from Modbus every 10 seconds. - -```yaml -modbus: - - name: hub1 - type: tcp - host: IP_ADDRESS - port: 502 - - covers: - - name: Door1 - slave: 1 - device_class: door - scan_interval: 10 - coil: 1 - status_register: 1 - status_register_type: input - state_opening: 1 - state_open: 2 - state_closing: 3 - state_closed: 4 -``` - -### Modbus cover controlled by a holding register - -This example shows a configuration for a Modbus cover controlled using a holding register, from which we also read current cover state. We've also specified register values to match with the states open/opening/closed/closing. The cover state is polled from Modbus every 10 seconds. - -```yaml -modbus: - - name: hub1 - type: tcp - host: IP_ADDRESS - port: 502 - - covers: - - name: Door1 - slave: 1 - device_class: door - scan_interval: 10 - register: 1 - state_opening: 1 - state_open: 2 - state_closing: 3 - state_closed: 4 -``` - -### Modbus cover controlled by a holding register, it's state is read from the status register - -This example shows a configuration for a Modbus cover controlled using a holding register. However, cover state is read from a `status_register`. In this case, we've specified only values for `state_open` and `state_closed`, for the rest, default values are used. The cover state is polled from Modbus every 10 seconds. - -```yaml -modbus: - - name: hub1 - type: tcp - host: IP_ADDRESS - port: 502 - - covers: - - name: Door1 - slave: 1 - device_class: door - scan_interval: 10 - register: 1 - status_register: 2 - register_type: holding - state_open: 1 - state_closed: 0 -``` diff --git a/source/_integrations/modbus.markdown b/source/_integrations/modbus.markdown index 1da25a6d5bbb..5d9e7f06b9e2 100644 --- a/source/_integrations/modbus.markdown +++ b/source/_integrations/modbus.markdown @@ -1,6 +1,6 @@ --- title: Modbus -description: Instructions on how to integrate Modbus within Home Assistant. +description: Instructions on how to integrate Modbus and platforms. ha_category: - Hub ha_release: pre 0.7 @@ -23,7 +23,16 @@ It supports various types of devices which can be controlled over serial, TCP, a ## Configuration -The configuration for adding modbus to your installation depends on the connection type, either a network or serial connection. +How to add modbus to your installation depends on the connection type, either a network or serial connection. + +Platforms: + - binary_sensor + - climate + - cover + - sensor + - switch + +are all defined as part of the modbus configuration. The old configuration style, (having each outside the modbus configuration is still supported, but will cause a warning, and will be removed in a later release). ### Network connection @@ -32,40 +41,40 @@ For a network connection, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry for a TCP connection modbus: - name: hub1 - type: tcp - host: IP_ADDRESS - port: 2020 + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 ``` {% configuration %} -type: - description: Type of the connection to Modbus. Possible values are `tcp` (Modbus TCP protocol according to "MODBUS Messaging Implementation Guide version 1.0b" provided by Schneider Automation.), `udp`(Modbus TCP form, but using UDP for transport. It removes the overheads required for TCP.) and `rtuovertcp` (Modbus RTU message transmitted with a TCP/IP wrapper and sent over a network instead of serial lines.). - required: true - type: string +delay: + description: Time to sleep in seconds after connecting and before sending messages. Some modbus-tcp servers need a short delay typically 1-2 seconds in order to prepare the communication. If a server accepts connecting, but there is no response to the requests send, this parameter might help. + required: false + default: 0 + type: integer host: description: The IP address of your Modbus device, e.g., 192.168.1.1. required: true type: string -port: - description: The network port for the communication. - required: true - type: integer name: description: Name for this hub. Must be unique, so it is required when setting up multiple instances. required: false default: modbus_hub type: string +port: + description: The network port for the communication. + required: true + type: integer timeout: description: Timeout for slave response in seconds. required: false default: 3 type: integer -delay: - description: Time to sleep in seconds after connecting and before sending messages. Some modbus-tcp servers need a short delay typically 1-2 seconds in order to prepare the communication. If a server accepts connecting, but there is no response to the requests send, this parameter might help. - required: false - default: 0 - type: integer +type: + description: Type of the connection to Modbus. Possible values are `tcp` (Modbus TCP protocol according to "MODBUS Messaging Implementation Guide version 1.0b" provided by Schneider Automation.), `udp`(Modbus TCP form, but using UDP for transport. It removes the overheads required for TCP.) and `rtuovertcp` (Modbus RTU message transmitted with a TCP/IP wrapper and sent over a network instead of serial lines.). + required: true + type: string {% endconfiguration %} ### Serial connection @@ -75,58 +84,661 @@ For a serial connection, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry for a serial connection modbus: - name: hub1 - type: serial - method: rtu - port: /dev/ttyUSB0 - baudrate: 9600 - stopbits: 1 - bytesize: 8 - parity: N + - name: hub1 + type: serial + method: rtu + port: /dev/ttyUSB0 + baudrate: 9600 + stopbits: 1 + bytesize: 8 + parity: N ``` {% configuration %} -type: - description: "Type of the connection to Modbus, needs to be `serial` for this setup." - required: true - type: string -method: - description: "Method of the connection to Modbus, either `rtu` or `ascii`." - required: true - type: string -port: - description: The port where your Modbus device is connected to your Home Assistant host. - required: true - type: string baudrate: description: The speed for the serial connection. required: true type: integer -stopbits: - description: "The stopbits for the serial connection, either `1` or `2`." - required: true - type: integer bytesize: description: "The bytesize for the serial connection; can be `5`, `6`, `7` or `8`." required: true type: integer -parity: - description: "The parity for the serial connection; can be `E`, `O` or `N`." +delay: + description: Time to sleep in seconds after connecting and before sending messages. Some modbus servers need a short delay typically 1-2 seconds in order to prepare the communication. If a server accepts connecting, but there is no response to the requests send, this parameter might help. + required: false + default: 0 + type: integer +method: + description: "Method of the connection to Modbus, either `rtu` or `ascii`." required: true type: string name: description: Name for this hub. Must be unique, so it is required when setting up multiple instances. required: false - default: default + default: modbus_hub + type: string +parity: + description: "The parity for the serial connection; can be `E`, `O` or `N`." + required: true + type: string +port: + description: The port where your Modbus device is connected to your Home Assistant host. + required: true type: string +stopbits: + description: "The stopbits for the serial connection, either `1` or `2`." + required: true + type: integer timeout: description: Timeout for slave response in seconds. required: false default: 3 type: integer +type: + description: "Type of the connection to Modbus, needs to be `serial` for this setup." + required: true + type: string +{% endconfiguration %} + +### Configuring platform binary sensor + +The `modbus` binary sensor allows you to gather data from [Modbus](http://www.modbus.org/) coils with state ON/OFF. + +To use your Modbus binary sensors in your installation, add the following to your `configuration.yaml` file: +```yaml +# Example configuration.yaml entry for binary_sensor configuration +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + binary_sensors: + - name: Sensor1 + slave: 1 + address: 100 + - name: Sensor2 + address: 110 + input_type: discrete_input +``` +{% configuration %} +binary_sensors: + description: A list of all binary_sensors available in this modbus instance. + required: false + type: [map] + keys: + device_class: + description: Device class to be used for the UI (e.g. "door"). + required: false + type: string + input_type: + description: type of adddress (holding/discrete/coil) + required: false + default: holding + type: integer + name: + description: Name for this binary_sensor. Must be unique. + required: true + type: string + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 + slave: + description: The number of the slave. + required: false + type: integer {% endconfiguration %} -### Multiple connections + +### Configuring platform climate + +To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + climates: + - name: Watlow F4T + slave: 1 + data_type: uint + data_count: 1 + scale: 0.1 + offset: 0 + precision: 1 + max_temp: 30 + min_temp: 15 + temp_step: 1 + target_temp_register: 2782 + current_temp_register: 27586 +``` + +{% configuration %} +climates: + description: A list of all climates available in this modbus instance. + required: false + type: [map] + keys: + current_temp_register: + description: Register number for current temperature (Process value). + required: true + type: integer + current_temp_register_type: + description: Modbus register type (holding, input) for current temperature, default holding. + required: false + type: string + default: holding + data_count: + description: Number of registers to read. + required: false + type: integer + default: 2 + data_type: + description: Response representation (int, uint, float, custom). If float selected, value will converted to IEEE 754 floating point format. + required: false + type: string + default: float + min_temp: + description: Maximum setpoint temperature. + required: false + type: integer + default: 5 + name: + description: Name of the device + required: true + type: string + offset: + description: Final offset (output = scale * value + offset). + required: false + type: float + default: 0 + precision: + description: Number of valid decimals. + required: false + type: integer + default: 1 + scale: + description: Scale factor (output = scale * value + offset). + required: false + type: float + default: 1 + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 + slave: + description: The number of the slave (Optional for tcp and upd Modbus, use 1). + required: true + type: integer + structure: + description: "If `data_type` is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: `>i`." + required: false + type: string + default: ">f" + target_temp_register: + description: Register number for target temperature (Setpoint). + required: true + type: integer + temp_step: + description: The supported step size a target temperature can be increased/decreased. + required: false + type: float + default: 0.5 + temperature_unit: + description: Temperature unit reported by the current_temp_register. C or F + required: false + type: string + default: C +{% endconfiguration %} + +#### Services + +| Service | Description | +| ------- | ----------- | +| set_temperature | Set Temperature. Requires `value` to be passed in, which is the desired target temperature. `value` should be in the same type as `data_type` | + +### Configuring platform cover + +The `modbus` cover platform allows you to control [Modbus](http://www.modbus.org/) covers (such as blinds, a roller shutter, or a garage door). + +At the moment, we support the opening and closing of a cover. You can control your covers either using coils or holding registers. + +Cover that uses the `coil` attribute is not able to determine intermediary states such as opening and closing. Coil stores only two states — "0" means cover closed, and "1" implies cover open. To allow detecting intermediary states, we added an optional `status_register` attribute. It will enable you to write your command (e.g., to open a cover) into a coil, and read current cover status back through the register. Additionally, you can specify values for `state_open`, `state_opening`, `state_closed`, and `state_closing` attributes. These will be matched with the value read from the `status_register`. + +If your cover uses holding register to send commands (defined by the `register` attribute), it can also read the intermediary states. To adjust which value represents what state, you can fine-tune the optional state attributes, like `state_open`. These optional state values are also used for specifying values written into the register. If you specify an optional status_register attribute, cover states will be read from status_register instead of the register used for sending commands. + +To use Modbus covers in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + covers: + - name: Door1 + device_class: door + scan_interval: 1 + coil: 0 + - name: Door2 + device_class: door + scan_interval: 1 + coil: 1 + status_register: 1 + - name: Door3 + slave: 2 + device_class: door + scan_interval: 1 + register: 0 + state_open: 1 + state_closed: 0 +``` + +{% configuration %} +covers: + description: The array contains a list of all your Modbus covers. + required: true + type: map + keys: + coil: + description: Coil address; can be omitted if a register attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. + required: true + type: integer + device_class: + description: The [type/class](/integrations/cover/#device-class) of the cover to set the icon in the frontend. + required: false + type: device_class + default: None + name: + description: Name of the switch. + required: true + type: string + register: + description: Holding register address; can be omitted if a coil attribute is specified. Coil and register attributes are mutually exclusive, and you need to always specify one of them. + required: true + type: integer + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 + slave: + description: The number of the slave (can be omitted for tcp and udp Modbus). + required: false + default: 1 + type: integer + state_open: + description: A value in `status_register` or `register` representing an open cover. If your configuration uses an `register` attribute, this value will be also written into a holding register to open the cover. + required: false + default: 1 + type: integer + state_closed: + description: A value in `status_register` or `register` representing a closed cover. If your configuration uses an `register` attribute, this value will be also written into a holding register to close the cover. + required: false + default: 0 + type: integer + state_opening: + description: A value in `status_register` or `register` telling us that the cover is opening at the moment. Note that this state should be also supported on your connected Modbus cover. If it won't write this intermediary state into the register, this state won't be detected. + required: false + default: 2 + type: integer + state_closing: + description: A value in `status_register` or `register` telling us that the cover is closing at the moment. Note that this state should be also supported on your connected Modbus cover. If it won't write this intermediary state into the register, this state won't be detected. + required: false + default: 2 + type: integer + status_register: + description: An address of an register, from which all the cover states will be read. If you specified `register` attribute, and not `status_register` attribute, your main register will also be used as a status register. + required: false + type: integer + status_register_type: + description: Modbus register type (holding, input), default holding. + required: false + type: string +{% endconfiguration %} + +#### Example: Modbus cover controlled by a coil + +This example shows a configuration for a Modbus cover controlled using a coil. Intermediary states like opening/closing are not supported. The cover state is polled from Modbus every 10 seconds. + +```yaml +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + covers: + - name: Door1 + slave: 1 + coil: 1 + device_class: door + scan_interval: 10 + - name: Door2 + slave: 2 + coil: 2 + device_class: door + scan_interval: 10 +``` + +#### Example: Modbus cover controlled by a coil, it's state is read from the register + +This example shows a configuration for a Modbus cover controlled using a coil. Actual cover state is read from the `status_register`. We've also specified register values to match with the states open/opening/closed/closing. The cover state is polled from Modbus every 10 seconds. + +```yaml +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + covers: + - name: Door1 + slave: 1 + device_class: door + scan_interval: 10 + coil: 1 + status_register: 1 + status_register_type: input + state_opening: 1 + state_open: 2 + state_closing: 3 + state_closed: 4 +``` + +#### Example: Modbus cover controlled by a holding register + +This example shows a configuration for a Modbus cover controlled using a holding register, from which we also read current cover state. We've also specified register values to match with the states open/opening/closed/closing. The cover state is polled from Modbus every 10 seconds. + +```yaml +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + covers: + - name: Door1 + slave: 1 + device_class: door + scan_interval: 10 + register: 1 + state_opening: 1 + state_open: 2 + state_closing: 3 + state_closed: 4 +``` + +#### Example: Modbus cover controlled by a holding register, it's state is read from the status register + +This example shows a configuration for a Modbus cover controlled using a holding register. However, cover state is read from a `status_register`. In this case, we've specified only values for `state_open` and `state_closed`, for the rest, default values are used. The cover state is polled from Modbus every 10 seconds. + +```yaml +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + + covers: + - name: Door1 + slave: 1 + device_class: door + scan_interval: 10 + register: 1 + status_register: 2 + register_type: holding + state_open: 1 + state_closed: 0 +``` + +### Configuring platform sensor + +The `modbus` cover platform allows you to control [Modbus](http://www.modbus.org/) covers (such as blinds, a roller shutter, or a garage door). + + +The `modbus` sensor allows you to gather data from [Modbus](http://www.modbus.org/) registers. + +To use your Modbus sensors in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + sensors: + - name: Sensor1 + unit_of_measurement: °C + slave: 1 + address: 100 + - name: Sensor2 + unit_of_measurement: mg + slave: 1 + register: 110 + count: 2 + - name: Sensor3 + unit_of_measurement: °C + slave: 1 + address: 120 + input_type: input + data_type: float + scale: 0.01 + offset: -273.16 + precision: 2 +``` + +{% configuration %} +sensors: + description: The array contains a list of all your Modbus sensors. + required: true + type: map + keys: + address: + description: Register number. + required: true + type: integer + count: + description: Number of registers to read. + required: false + type: integer + default: 1 + data_type: + description: Response representation (int, uint, float, string, custom). If float selected, value will be converted to IEEE 754 floating point format. + required: false + default: int + type: string + device_class: + description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend. + required: false + type: device_class + default: None + input_type: + description: Modbus register type (holding, input), default holding. + required: false + type: string + name: + description: Name of the sensor. + required: true + type: string + offset: + description: Final offset (output = scale * value + offset). + required: false + default: 0 + type: float + precision: + description: Number of valid decimals. + required: false + default: 0 + type: integer + reverse_order: + description: Reverse the order of registers when count >1. + required: false + default: false + type: boolean + scale: + description: Scale factor (output = scale * value + offset). + required: false + default: 1 + type: float + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 + slave: + description: The number of the slave (Optional for tcp and upd Modbus). + required: true + type: integer + structure: + description: "If `data_type` is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: `>i`." + required: false + type: string + unit_of_measurement: + description: Unit to attach to value. + required: false + type: integer +{% endconfiguration %} + +
    + +If you specify scale or offset as floating point values, double precision floating point arithmetic will be used to calculate final value. This can cause loss of precision for values that are larger than 2^53. + +
    + +#### Full example + +Example a temperature sensor with a 10 seconds scan interval: + +```yaml +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + sensors: + - name: Room_1 + slave: 10 + address: 0 + input_type: holding + unit_of_measurement: °C + count: 1 + scale: 0.1 + offset: 0 + precision: 1 + data_type: integer +``` + +### Configuring platform switch + +The `modbus` switch platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. + +To use your Modbus switches in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + switches: + - name: Switch1 + address: 13 + input_type: coil + - name: Switch2 + slave: 2 + address: 14 + input_type: coil + - name: Register1 + address: 11 + command_on: 1 + command_off: 0 +``` + +{% configuration %} +switches: + description: The array contains a list of all your Modbus switches. + required: true + type: map + keys: + address: + description: Coil number or register + required: true + type: integer + command_on: + description: Value to write to turn on the switch. + required: true + type: integer + command_off: + description: Value to write to turn off the switch. + required: true + type: integer + input_type: + description: type of adddress (holding/discrete/coil) + required: false + default: holding + type: integer + name: + description: Name of the switch. + required: true + type: string + scan_interval: + description: Defines the update interval of the sensor in seconds. + required: false + type: integer + default: 15 + slave: + description: The number of the slave (can be omitted for tcp and udp Modbus). + required: true + type: integer + state_on: + description: Register value when switch is on. + required: false + default: same as command_on + type: integer + state_off: + description: Register value when switch is off. + required: false + default: same as command_off + type: integer + verify_register: + description: Register to readback. + required: false + default: same as register + type: string + verify_state: + description: Define if is possible to readback the status of the switch. + required: false + default: true + type: boolean +{% endconfiguration %} + +#### Full example + +Example switches, for which the state is polled from Modbus every 10 seconds. + +```yaml +modbus: + - name: hub1 + type: tcp + host: IP_ADDRESS + port: 502 + switches: + - name: Switch1 + slave: 1 + address: 13 + input_type: coil + - name: Switch2 + slave: 2 + address: 14 +``` + +#### Multiple connections Multiple connections are possible, add something like the following to your `configuration.yaml` file: diff --git a/source/_integrations/sensor.modbus.markdown b/source/_integrations/sensor.modbus.markdown deleted file mode 100644 index 7c7d03a2cfb8..000000000000 --- a/source/_integrations/sensor.modbus.markdown +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Modbus Sensor -description: "Instructions on how to integrate Modbus sensors into Home Assistant." -ha_category: - - Sensor -ha_release: pre 0.7 -ha_iot_class: Local Push -ha_domain: modbus ---- - -The `modbus` sensor allows you to gather data from [Modbus](http://www.modbus.org/) registers. - -## Configuration - -To use your Modbus sensors in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -sensor: - platform: modbus - registers: - - name: Sensor1 - hub: hub1 - unit_of_measurement: °C - slave: 1 - register: 100 - - name: Sensor2 - hub: hub1 - unit_of_measurement: mg - slave: 1 - register: 110 - count: 2 - - name: Sensor3 - hub: hub1 - unit_of_measurement: °C - slave: 1 - register: 120 - register_type: input - data_type: float - scale: 0.01 - offset: -273.16 - precision: 2 -``` - -{% configuration %} -registers: - description: The array contains a list of relevant registers to read from. - required: true - type: map - keys: - name: - description: Name of the sensor. - required: true - type: string - hub: - description: The name of the hub. - required: false - default: modbus_hub - type: string - slave: - description: The number of the slave (Optional for tcp and upd Modbus). - required: true - type: integer - register: - description: Register number. - required: true - type: integer - register_type: - description: Modbus register type (holding, input), default holding. - required: false - type: string - unit_of_measurement: - description: Unit to attach to value. - required: false - type: integer - device_class: - description: The [type/class](/integrations/sensor/#device-class) of the sensor to set the icon in the frontend. - required: false - type: device_class - default: None - count: - description: Number of registers to read. - required: false - type: integer - default: 1 - reverse_order: - description: Reverse the order of registers when count >1. - required: false - default: false - type: boolean - scale: - description: Scale factor (output = scale * value + offset). - required: false - default: 1 - type: float - offset: - description: Final offset (output = scale * value + offset). - required: false - default: 0 - type: float - precision: - description: Number of valid decimals. - required: false - default: 0 - type: integer - data_type: - description: Response representation (int, uint, float, string, custom). If float selected, value will be converted to IEEE 754 floating point format. - required: false - default: int - type: string - structure: - description: "If `data_type` is custom specified a double-quoted Python struct is expected here, to format the string to unpack the value. See Python documentation for details. Example: `>i`." - required: false - type: string -{% endconfiguration %} - -It's possible to change the default 30 seconds scan interval for the sensor updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. - -
    - -If you specify scale or offset as floating point values, double precision floating point arithmetic will be used to calculate final value. This can cause loss of precision for values that are larger than 2^53. - -
    - -### Full example - -Example a temperature sensor with a 10 seconds scan interval: - -```yaml -sensor: -- platform: modbus - scan_interval: 10 - registers: - - name: Room_1 - hub: hub1 - slave: 10 - register: 0 - register_type: holding - unit_of_measurement: °C - count: 1 - scale: 0.1 - offset: 0 - precision: 1 - data_type: integer -``` diff --git a/source/_integrations/switch.modbus.markdown b/source/_integrations/switch.modbus.markdown deleted file mode 100644 index 0809e71a75c7..000000000000 --- a/source/_integrations/switch.modbus.markdown +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Modbus Switch" -description: "Instructions on how to integrate Modbus switches into Home Assistant." -ha_category: - - Switch -ha_release: pre 0.7 -ha_iot_class: Local Push -ha_domain: modbus ---- - -The `modbus` switch platform allows you to control [Modbus](http://www.modbus.org/) coils or registers. - -## Configuration - -To use your Modbus switches in your installation, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -switch: - platform: modbus - coils: - - name: Switch1 - hub: hub1 - slave: 1 - coil: 13 - - name: Switch2 - slave: 2 - coil: 14 - registers: - - name: Register1 - hub: hub1 - slave: 1 - register: 11 - command_on: 1 - command_off: 0 -``` - -{% configuration %} -coils: - description: A list of relevant coils to read from/write to. - required: false - type: map - keys: - hub: - description: The name of the hub. - required: false - default: default - type: string - slave: - description: The number of the slave (can be omitted for tcp and udp Modbus). - required: true - type: integer - name: - description: Name of the switch. - required: true - type: string - coil: - description: Coil number. - required: true - type: integer -registers: - description: A list of relevant registers to read from/write to. - required: false - type: map - keys: - hub: - description: The hub to use. - required: false - default: default - type: string - slave: - description: The number of the slave (can be omitted for tcp and udp Modbus). - required: true - type: integer - name: - description: Name of the switch. - required: true - type: string - register: - description: Register number. - required: true - type: integer - command_on: - description: Value to write to turn on the switch. - required: true - type: integer - command_off: - description: Value to write to turn off the switch. - required: true - type: integer - verify_state: - description: Define if is possible to readback the status of the switch. - required: false - default: true - type: boolean - verify_register: - description: Register to readback. - required: false - default: same as register - type: string - register_type: - description: Modbus register types are holding or input. - required: false - default: holding - type: string - state_on: - description: Register value when switch is on. - required: false - default: same as command_on - type: integer - state_off: - description: Register value when switch is off. - required: false - default: same as command_off - type: integer -{% endconfiguration %} - -It's possible to change the default 30 seconds scan interval for the switch state updates as shown in the [Platform options](/docs/configuration/platform_options/#scan-interval) documentation. - -### Full example - -Example switches, for which the state is polled from Modbus every 10 seconds. - -```yaml -switch: - platform: modbus - scan_interval: 10 - coils: - - name: Switch1 - hub: hub1 - slave: 1 - coil: 13 - - name: Switch2 - hub: hub1 - slave: 2 - coil: 14 -``` diff --git a/source/_redirects b/source/_redirects index a1fe817cb241..4ad849a4135b 100644 --- a/source/_redirects +++ b/source/_redirects @@ -1073,14 +1073,19 @@ /components/xiaomi /integrations/xiaomi_aqara /integrations/air_quality.xiaomi_miio /integrations/xiaomi_miio /integrations/alarm_control_panel.xiaomi_miio /integrations/xiaomi_miio +/integrations/binary_sensor.modbus /integrations/modbus +/integrations/climate.modbus /integrations/modbus +/integrations/cover.modbus /integrations/modbus /integrations/fan.xiaomi_miio /integrations/xiaomi_miio /integrations/light.xiaomi_miio /integrations/xiaomi_miio +/integrations/lovelace /lovelace /integrations/remote.xiaomi_miio /integrations/xiaomi_miio /integrations/sensor.websocket_api /integrations/websocket_api +/integrations/sensor.modbus /integrations/modbus /integrations/sensor.xiaomi_miio /integrations/xiaomi_miio +/integrations/switch.modbus /integrations/modbus /integrations/switch.xiaomi_miio /integrations/xiaomi_miio /integrations/vacuum.xiaomi_miio /integrations/xiaomi_miio -/integrations/lovelace /lovelace # Renaming components to integrations /components /integrations From 162789f89f8db08b808b75ea562dbdb1b70e5739 Mon Sep 17 00:00:00 2001 From: Jesse Campbell Date: Mon, 29 Mar 2021 03:44:06 -0400 Subject: [PATCH 54/65] New services for managing lock codes on ZHA Zigbee locks (#16947) --- source/_integrations/zha.markdown | 35 ++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) diff --git a/source/_integrations/zha.markdown b/source/_integrations/zha.markdown index 512ce6955663..1dc4f67d97b7 100644 --- a/source/_integrations/zha.markdown +++ b/source/_integrations/zha.markdown @@ -252,12 +252,45 @@ from the same group: ### Service `zha.remove` -This service remove an existing device from the network. +This service removes an existing device from the network. | Data | Optional | Description | | ---- | ---- | ----------- | | `ieee` | no | IEEE address of the device to remove +### Service `zha.set_lock_user_code` + +This service sets a lock code on a Zigbee lock. + +| Data | Optional | Description | +| --------- | ---- | ----------- | +| `code_slot` | no | Which lock code slot to store the code. Ex. 1-32 will work for Kwikset 954 +| `user_code` | no | Code to set on the lock. Ex. Kwikset accepts numbers 4-8 digits in length + +### Service `zha.clear_lock_user_code` + +This service clears a lock code from a Zigbee lock. + +| Data | Optional | Description | +| --------- | ---- | ----------- | +| `code_slot` | no | Which lock code slot to clear + +### Service `zha.enable_lock_user_code` + +This service enables a lock code on a Zigbee lock. + +| Data | Optional | Description | +| --------- | ---- | ----------- | +| `code_slot` | no | Which lock code slot to enable + +### Service `zha.disable_lock_user_code` + +This service disables a lock code on a Zigbee lock. + +| Data | Optional | Description | +| --------- | ---- | ----------- | +| `code_slot` | no | Which lock code slot to disable + ## Adding devices To add a new device: From 4e11ce33180e3d265f4a7d5324330afc95808d5c Mon Sep 17 00:00:00 2001 From: William Scanlon Date: Mon, 29 Mar 2021 04:14:56 -0400 Subject: [PATCH 55/65] Updated econet.markdown for climate updates (#16440) Co-authored-by: Franck Nijhof Co-authored-by: Franck Nijhof --- source/_integrations/econet.markdown | 30 +++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/source/_integrations/econet.markdown b/source/_integrations/econet.markdown index e5360fd0565a..de6cc6b9b822 100644 --- a/source/_integrations/econet.markdown +++ b/source/_integrations/econet.markdown @@ -2,6 +2,9 @@ title: Rheem EcoNet Products description: Instructions on how to integrate Rheem EcoNet water heaters into Home Assistant. ha_category: + - Binary Sensor + - Climate + - Sensor - Water Heater ha_release: 0.61 ha_iot_class: Cloud Push @@ -16,6 +19,31 @@ ha_platforms: - water_heater --- -The `econet` water heater platform is consuming the information provided by a [EcoNet enabled Rheem water heater](https://www.rheem.com/EcoNet/Home). This platform allows you to set the temperature, the operation mode, and away mode. It also provides access to several device sensors depending on your model of water heater. +The EcoNet integration is consuming the information provided by a [EcoNet enabled Rheem water heater or thermostat](https://www.rheem.com/EcoNet/Home). {% include integrations/config_flow.md %} + +## Platforms + +EcoNet devices may be represented by one or more platforms. + +- [Binary Sensor](#binary-sensor) +- [Climate](#climate) +- [Sensor](#sensor) +- [Water Heater](#water-heater) + +### Binary Sensor + +The EcoNet Binary Sensor platform lets you view binary states of sensors associated with your EcoNet thermostat or water heater. For example, if the device is currently running. + +### Climate + +The EcoNet Climate platform lets you control your EcoNet thermostat. Multi-zone HVAC systems will have 1 Climate entity per zone. + +### Sensor + +The EcoNet Sensor platform lets you view sensors associated with your EcoNet thermostat or water heater. For example, alert count or available hot water. + +### Water Heater + +The EcoNet Water Heater platform lets you control your EcoNet water heater. Water Heaters do not report the current water temperature. From 8289a016af49fae9fed1d208ffefb35926495435 Mon Sep 17 00:00:00 2001 From: plomosits Date: Mon, 29 Mar 2021 10:17:07 +0200 Subject: [PATCH 56/65] Improve Docker and Kubernetes support for KNX (#17095) --- source/_integrations/knx.markdown | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/source/_integrations/knx.markdown b/source/_integrations/knx.markdown index 442a7daf4133..3ec42d0378d3 100644 --- a/source/_integrations/knx.markdown +++ b/source/_integrations/knx.markdown @@ -134,6 +134,11 @@ local_ip: description: IP address of the local interface. type: string required: false +route_back: + description: When True the KNXnet/IP Server shall use the IP address and the port number from the IP package received as the target IP address or port number for the response to the KNXnet/IP Client (for NAT / Docker). + type: boolean + default: false + required: false {% endconfiguration %} ### Routing From b304c0f3a3ac2cf76ef133c6b1e44eb85f7509b4 Mon Sep 17 00:00:00 2001 From: chemaaa <187996+chemaaa@users.noreply.github.com> Date: Mon, 29 Mar 2021 11:08:01 +0200 Subject: [PATCH 57/65] Add Legrand Home+ Control Integration document (#16644) Co-authored-by: Klaas Schoute Co-authored-by: Franck Nijhof --- .../_integrations/home_plus_control.markdown | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 source/_integrations/home_plus_control.markdown diff --git a/source/_integrations/home_plus_control.markdown b/source/_integrations/home_plus_control.markdown new file mode 100644 index 000000000000..e1e197ad441e --- /dev/null +++ b/source/_integrations/home_plus_control.markdown @@ -0,0 +1,89 @@ +--- +title: Legrand Home+ Control +description: Instructions on how to integrate Legrand Home+ Control into Home Assistant. +ha_category: + - Switch +ha_release: 2021.4 +ha_iot_class: Cloud Polling +ha_codeowners: + - '@chemaaa' +ha_config_flow: true +ha_domain: home_plus_control +--- + +The Home+ Control integration platform allows you to control a range of Legrand in-wall switches and power outlets that have smart home functionality thanks to their "with Netatmo" capabilities. + +This integration works against the Home+ Control API, which is one of the many APIs offered through the [*Works with Legrand*](https://developer.legrand.com/) program. The API is capable of managing "Legrand/Btcino with Netatmo" devices, such as light switches, power outlets and rolling shutters. + +The devices that this API can manage are offered in different designs across different countries. The details of these can be found [here](https://developer.legrand.com/solutions/wiring-devices-with-netatmo/). + +This Home+ Control integration for Home Assistant currently has support for the following devices: +- Light switches +- Power outlets + +In both cases, the devices are modeled as on/off switches within Home Assistant. + +This integration has been tested to work with the following range of Legrand products: +- Valena Next™ with Netatmo + + +## Authentication + +Before you are able to configure the Legrand Home + Control integration into Home Assistant, you must register with the *Works with Legrand* platform. + +These Legrand APIs rely on Oauth2 authentication, so you must follow these steps to obtain the necessary authentication parameters: + +1. Register an account at . +2. Create a subscription to the *Starter Kit* (currently the only subscription available) and this will generate your `SUBSCRIPTION_KEY`. +3. Register an application, where you will have to define a name, a redirect URL and the scopes of your application. When selecting the scopes, be sure to include all of the `.read` scopes, as well as the `light.write` and `plug.write` scopes to be able to control these modules from the integration. + +Once the registered application is confirmed, you should receive an email containing the `CLIENT_IDENTIFIER` and the `CLIENT_SECRET` which you will be using to set up the authentication flows. The application confirmation email is usually received within a few hours of having issued the request. + +Finally, to set up Oauth2 authentication in Home Assistant you should add the following information to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +home_plus_control: + client_id: CLIENT_IDENTIFIER + client_secret: CLIENT_SECRET + subscription_key: SUBSCRIPTION_KEY +``` + +{% configuration %} +client_id: + description: Client identifier for your registered application on the *Works with Legrand* platform. Received via email. + required: true + type: string +client_secret: + description: Client secret for your registered application on the *Works with Legrand* platform. Received via email. + required: true + type: string +subscription_key: + description: Subscription identifier for your registered account on the *Works with Legrand* platform. Provided upon registration. + required: true + type: string +{% endconfiguration %} + + +At this point, you are now ready to add the Home+ Control integration to your Home Assistant instance as described in the [Configuration](#configuration) section. + + +{% include integrations/config_flow.md %} + + +## API Nomenclature + +Within the context of the Home+ Control API you may come across the following terms: + +* *Plant*: This is the term used to represent a *home* that holds the Legrand devices. In practice, a *plant* is represented by the *Legrand Home+ Control* gateway that acts as the central hub of the rest of the devices in the home network (uses Zigbee). +* *Module*: This is the term used to represent a generic device within the *plant*, i.e., a light, a plug, a remote, etc. +* *Light*: This is the term used to represent a light switch (or a micro-module). It is not modeled as your usual light entity because there are no brightness, color, etc. controls. It is modeled as an on/off switch. +* *Plug*: This is the term used to represent a power outlet. + +Other devices that are mentioned in the API, but that are not currently supported by this integration are: *remotes* (wireless switches), *heaters* and *automations*. + +## API Limitations + +As described in the [authentication](#authentication) section, this integration requires you to set up a subscription in the *Works with Legrand* platform. + +Currently, end-users only have access to the *Starter Kit* subscription which has a major limitation in the number of allowed API requests that are allowed - only 500 API calls per day (counter is reset at 00:00 every day). If this daily quota is ever exceeded, the API will report `403 Forbidden` HTTP responses. From 0f2bc6ad1ee5b2e849da80e39beea7c9c21f7881 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Fri, 26 Mar 2021 10:02:29 +0100 Subject: [PATCH 58/65] Remove deprecated items, fix typo --- source/_docs/mqtt/discovery.markdown | 2 +- source/_integrations/fan.mqtt.markdown | 33 +------------------------- 2 files changed, 2 insertions(+), 33 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 85f38a6dc1d0..25834c0f317d 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -197,7 +197,7 @@ Supported abbreviations: 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_stat_t': 'preset_mode_state_topic', - 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 581966855f2a..01263e366ab5 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -128,21 +128,6 @@ payload_available: required: false type: string default: online -payload_high_speed: - description: DEPRECATED - The payload that represents the fan's high speed. - required: false - type: string - default: high -payload_low_speed: - description: DEPRECATED - The payload that represents the fan's low speed. - required: false - type: string - default: low -payload_medium_speed: - description: DEPRECATED - The payload that represents the fan's medium speed. - required: false - type: string - default: medium payload_not_available: description: The payload that represents the unavailable state. required: false @@ -207,12 +192,8 @@ retain: required: false type: boolean default: true -speed_command_topic: - description: DEPRECATED - The MQTT topic to publish commands to change speed state. - required: false - type: string speed_range_min: - description: The minimum of numeric output range (`off` not included). + description: The minimum of numeric output range (`off` not included, so `speed_range_min` - 1 represents 0%). required: false type: integer default: 1 @@ -221,18 +202,6 @@ speed_range_max: required: false type: integer default: 100 -speed_state_topic: - description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. - required: false - type: string -speed_value_template: - description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." - required: false - type: string -speeds: - description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." - required: false - type: [string, list] state_topic: description: The MQTT topic subscribed to receive state updates. required: false From ccbe58d93d56d7e72905936350bc1afcc8cc5bc3 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Sat, 27 Mar 2021 19:11:09 +0100 Subject: [PATCH 59/65] Support for command templates --- source/_docs/mqtt/discovery.markdown | 3 ++ source/_integrations/fan.mqtt.markdown | 40 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 25834c0f317d..dbb0e9d2dc28 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -154,9 +154,11 @@ Supported abbreviations: 'on_cmd_type': 'on_command_type', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', + 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'pct_cmd_t': 'percentage_command_topic', + 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', @@ -196,6 +198,7 @@ Supported abbreviations: 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 01263e366ab5..bc0878e171f8 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -56,6 +56,10 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. + required: false + type: template command_topic: description: The MQTT topic to publish commands to change the fan state. required: true @@ -111,6 +115,10 @@ optimistic: required: false type: boolean default: "`true` if no state topic defined, else `false`." +oscillation_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `oscillation_command_topic`. + required: false + type: template oscillation_command_topic: description: The MQTT topic to publish commands to change the oscillation state. required: false @@ -153,6 +161,10 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `percentage_command_topic`. + required: false + type: template percentage_command_topic: description: The MQTT topic to publish commands to change the fan speed state based on a percentage. required: false @@ -165,6 +177,10 @@ percentage_value_template: description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. required: false type: string +preset_mode_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `preset_mode_command_topic`. + required: false + type: template preset_mode_command_topic: description: The MQTT topic to publish commands to change the preset mode. required: false @@ -257,3 +273,27 @@ fan: speed_range_min: 1 speed_range_max: 100 ``` + +This example demonstrates how to use command templates. + +```yaml +# Example configuration.yaml +# Example using command templates +fan: + - platform: mqtt + name: "Bedroom Fan" + command_topic: "bedroom_fan/on/set" + command_template: "{ state: '{{ value }}'}" + oscillation_command_topic: "bedroom_fan/oscillation/set" + oscillation_command_template: "{ oscillation: '{{ value }}'}" + percentage_command_topic: "bedroom_fan/speed/percentage" + percentage_command_template: "{ percentage: {{ value }}}" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_mode_command_template: "{ preset_mode: '{{ value }}'}" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" +``` From 6686024b09521a6d084fbe8490af2daddd8ffbfb Mon Sep 17 00:00:00 2001 From: jbouwh Date: Thu, 18 Mar 2021 10:56:21 +0100 Subject: [PATCH 60/65] Update to new entity model introducing percentage and preset modes --- source/_docs/mqtt/discovery.markdown | 9 +++ source/_integrations/fan.mqtt.markdown | 79 +++++++++++++++++++------- 2 files changed, 69 insertions(+), 19 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 3a057e6f9306..54e7ed962b2b 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -156,6 +156,9 @@ Supported abbreviations: 'osc_cmd_t': 'oscillation_command_topic', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', + 'pct_cmd_t': 'percentage_command_topic', + 'pct_stat_t': 'percentage_state_topic', + 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_home': 'payload_arm_home', @@ -192,6 +195,10 @@ Supported abbreviations: 'pow_cmd_t': 'power_command_topic', 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', + 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_stat_t': 'preset_mode_state_topic', + 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', 'rgb_cmd_tpl': 'rgb_command_template', @@ -207,6 +214,8 @@ Supported abbreviations: 'pos_tpl': 'position_template', 'spd_cmd_t': 'speed_command_topic', 'spd_stat_t': 'speed_state_topic', + 'spd_rng_min': 'speed_range_min', + 'spd_rng_max': 'speed_range_max', 'spd_val_tpl': 'speed_value_template', 'spds': 'speeds', 'src_type': 'source_type', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index bd53656f198c..1647a4281285 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -133,17 +133,17 @@ payload_available: type: string default: online payload_high_speed: - description: The payload that represents the fan's high speed. + description: DEPRECATED - The payload that represents the fan's high speed. required: false type: string default: high payload_low_speed: - description: The payload that represents the fan's low speed. + description: DEPRECATED - The payload that represents the fan's low speed. required: false type: string default: low payload_medium_speed: - description: The payload that represents the fan's medium speed. + description: DEPRECATED - The payload that represents the fan's medium speed. required: false type: string default: medium @@ -172,6 +172,35 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_topic: + description: The MQTT topic to publish commands to change the fan speed state based on a percentage. + required: false + type: string +percentage_state_topic: + description: The MQTT topic subscribed to receive fan speed based on percentage. + required: false + type: string +percentage_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. + required: false + type: string +preset_mode_command_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_state_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the preset_mode payload. + required: false + type: string +preset_modes: + description: List of preset modes this fan is capable of running at. Common examples include `auto`, `smart`, `whoosh`, `eco` and `breeze`. + required: false + type: [list] + default: [] qos: description: The maximum QoS level of the state topic. required: false @@ -183,19 +212,29 @@ retain: type: boolean default: true speed_command_topic: - description: The MQTT topic to publish commands to change speed state. + description: DEPRECATED - The MQTT topic to publish commands to change speed state. required: false type: string +speed_range_min: + description: The minimum of numeric output range (`off` not included). + required: false + type: integer + default: 1 +speed_range_max: + description: The maximum of numeric output range (representing 100%). + required: false + type: integer + default: 100 speed_state_topic: - description: The MQTT topic subscribed to receive speed state updates. + description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. required: false type: string speed_value_template: - description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." + description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." required: false type: string speeds: - description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." + description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." required: false type: [string, list] state_topic: @@ -224,10 +263,10 @@ In this section you find some real-life examples of how to use this fan. ### Full configuration -The example below shows a full configuration for a MQTT fan. +The example below shows a full configuration for a MQTT fan using percentage and preset modes. ```yaml -# Example configuration.yaml entry +# Example using percentage based speeds with preset modes configuration.yaml fan: - platform: mqtt name: "Bedroom Fan" @@ -235,19 +274,21 @@ fan: command_topic: "bedroom_fan/on/set" oscillation_state_topic: "bedroom_fan/oscillation/state" oscillation_command_topic: "bedroom_fan/oscillation/set" - speed_state_topic: "bedroom_fan/speed/state" - speed_command_topic: "bedroom_fan/speed/set" + percentage_state_topic: "bedroom_fan/speed/percentage_state" + percentage_command_topic: "bedroom_fan/speed/percentage" + preset_mode_state_topic: "bedroom_fan/speed/preset_mode_state" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" qos: 0 payload_on: "true" payload_off: "false" payload_oscillation_on: "true" payload_oscillation_off: "false" - payload_low_speed: "low" - payload_medium_speed: "medium" - payload_high_speed: "high" - speeds: - - "off" - - low - - medium - - high + speed_range_min: 1 + speed_range_max: 100 ``` From 046f820ad4dfce2d4ff2a24d9d0a0d14eb7afc3e Mon Sep 17 00:00:00 2001 From: jbouwh Date: Fri, 26 Mar 2021 10:02:29 +0100 Subject: [PATCH 61/65] Remove deprecated items, fix typo --- source/_docs/mqtt/discovery.markdown | 2 +- source/_integrations/fan.mqtt.markdown | 33 +------------------------- 2 files changed, 2 insertions(+), 33 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 54e7ed962b2b..7881bbdfaa0a 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -197,7 +197,7 @@ Supported abbreviations: 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_stat_t': 'preset_mode_state_topic', - 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 1647a4281285..96a0078e134e 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -132,21 +132,6 @@ payload_available: required: false type: string default: online -payload_high_speed: - description: DEPRECATED - The payload that represents the fan's high speed. - required: false - type: string - default: high -payload_low_speed: - description: DEPRECATED - The payload that represents the fan's low speed. - required: false - type: string - default: low -payload_medium_speed: - description: DEPRECATED - The payload that represents the fan's medium speed. - required: false - type: string - default: medium payload_not_available: description: The payload that represents the unavailable state. required: false @@ -211,12 +196,8 @@ retain: required: false type: boolean default: true -speed_command_topic: - description: DEPRECATED - The MQTT topic to publish commands to change speed state. - required: false - type: string speed_range_min: - description: The minimum of numeric output range (`off` not included). + description: The minimum of numeric output range (`off` not included, so `speed_range_min` - 1 represents 0%). required: false type: integer default: 1 @@ -225,18 +206,6 @@ speed_range_max: required: false type: integer default: 100 -speed_state_topic: - description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. - required: false - type: string -speed_value_template: - description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." - required: false - type: string -speeds: - description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." - required: false - type: [string, list] state_topic: description: The MQTT topic subscribed to receive state updates. required: false From fce9a0c1fd4c6a3c273f7facfbc39acde2f86af7 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Sat, 27 Mar 2021 19:11:09 +0100 Subject: [PATCH 62/65] Support for command templates --- source/_docs/mqtt/discovery.markdown | 3 ++ source/_integrations/fan.mqtt.markdown | 40 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 7881bbdfaa0a..5599e835d37f 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -154,9 +154,11 @@ Supported abbreviations: 'on_cmd_type': 'on_command_type', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', + 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'pct_cmd_t': 'percentage_command_topic', + 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', @@ -196,6 +198,7 @@ Supported abbreviations: 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 96a0078e134e..b9721dcc7571 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -56,6 +56,10 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. + required: false + type: template command_topic: description: The MQTT topic to publish commands to change the fan state. required: true @@ -115,6 +119,10 @@ optimistic: required: false type: boolean default: "`true` if no state topic defined, else `false`." +oscillation_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `oscillation_command_topic`. + required: false + type: template oscillation_command_topic: description: The MQTT topic to publish commands to change the oscillation state. required: false @@ -157,6 +165,10 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `percentage_command_topic`. + required: false + type: template percentage_command_topic: description: The MQTT topic to publish commands to change the fan speed state based on a percentage. required: false @@ -169,6 +181,10 @@ percentage_value_template: description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. required: false type: string +preset_mode_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `preset_mode_command_topic`. + required: false + type: template preset_mode_command_topic: description: The MQTT topic to publish commands to change the preset mode. required: false @@ -261,3 +277,27 @@ fan: speed_range_min: 1 speed_range_max: 100 ``` + +This example demonstrates how to use command templates. + +```yaml +# Example configuration.yaml +# Example using command templates +fan: + - platform: mqtt + name: "Bedroom Fan" + command_topic: "bedroom_fan/on/set" + command_template: "{ state: '{{ value }}'}" + oscillation_command_topic: "bedroom_fan/oscillation/set" + oscillation_command_template: "{ oscillation: '{{ value }}'}" + percentage_command_topic: "bedroom_fan/speed/percentage" + percentage_command_template: "{ percentage: {{ value }}}" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_mode_command_template: "{ preset_mode: '{{ value }}'}" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" +``` From af3135df7f20618789e91a2e9142b4342a9d5adf Mon Sep 17 00:00:00 2001 From: Martidjen Date: Mon, 29 Mar 2021 12:50:06 +0200 Subject: [PATCH 63/65] Update openthem_gw.markdown (#16904) --- source/_integrations/opentherm_gw.markdown | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/source/_integrations/opentherm_gw.markdown b/source/_integrations/opentherm_gw.markdown index cff008c9358c..9caa472f8ce6 100644 --- a/source/_integrations/opentherm_gw.markdown +++ b/source/_integrations/opentherm_gw.markdown @@ -59,16 +59,14 @@ The precision and floor_temperature settings that were supported in configuratio The OpenTherm Gateway can be further configured through the integration settings in the web interface The following options are available: -{% configuration %} -Precision: - description: "The desired precision for this device. Can be used to match your actual thermostat's precision. Set to `0` to use the default value for your unit preference." - type: float - default: "`0.5` for Celsius and `1.0` for Fahrenheit." +{% configuration_basic %} +Read Precision: + description: "The desired read precision for this device. Used to display the current temperature on the climate entity. Can be used to match your actual thermostat's precision. Set to `0` to use the default value for your unit preference." +Set Precision: + description: "The desired set precision for this device. Used as step size for setting temperature setpoint from the climate entity. Can be used to match your actual thermostat's precision. Set to `0` to use the default value for your unit preference." Floor Temperature: description: "Some thermostats round all temperatures down to the lower value according to their precision. Default behavior for Home Assistant is to round temperatures to the nearest value. Enable this setting to override this behavior and round to the lower value according to the configured precision." - type: boolean - default: Disabled -{% endconfiguration %} +{% endconfiguration_basic %} ## Services From d4abfb59420322c418e3d42916af59a3ea866a19 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Thu, 18 Mar 2021 11:26:32 +0100 Subject: [PATCH 64/65] Support command templates for mqtt fan --- source/_docs/mqtt/discovery.markdown | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 5599e835d37f..c2510335b6da 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -215,12 +215,9 @@ Supported abbreviations: 'set_pos_t': 'set_position_topic', 'pos_t': 'position_topic', 'pos_tpl': 'position_template', - 'spd_cmd_t': 'speed_command_topic', - 'spd_stat_t': 'speed_state_topic', 'spd_rng_min': 'speed_range_min', 'spd_rng_max': 'speed_range_max', 'spd_val_tpl': 'speed_value_template', - 'spds': 'speeds', 'src_type': 'source_type', 'stat_clsd': 'state_closed', 'stat_closing': 'state_closing', @@ -285,7 +282,6 @@ Supported abbreviations for device registry configuration: 'mf': 'manufacturer', 'mdl': 'model', 'sw': 'sw_version', - 'sa': 'suggested_area', ``` ## Support by third-party tools From dfef464e9de415dd5bed8ca9d6358f7a8d0b896b Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Mon, 29 Mar 2021 09:37:16 +0200 Subject: [PATCH 65/65] Support command templates for mqtt fan --- source/_docs/mqtt/discovery.markdown | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 31311c146eda..dbb0e9d2dc28 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -215,8 +215,12 @@ Supported abbreviations: 'set_pos_t': 'set_position_topic', 'pos_t': 'position_topic', 'pos_tpl': 'position_template', + 'spd_cmd_t': 'speed_command_topic', + 'spd_stat_t': 'speed_state_topic', 'spd_rng_min': 'speed_range_min', 'spd_rng_max': 'speed_range_max', + 'spd_val_tpl': 'speed_value_template', + 'spds': 'speeds', 'src_type': 'source_type', 'stat_clsd': 'state_closed', 'stat_closing': 'state_closing',