Merge branch 'next' into time-trigger-offset

tsvi · Sep 12, 2024 · c93da70 · c93da70
2 parents f4fe90e + 7ed9ade
commit c93da70
Show file tree

Hide file tree

Showing 82 changed files with 1,830 additions and 832 deletions.
diff --git a/CODEOWNERS b/CODEOWNERS
@@ -451,6 +451,7 @@ source/_integrations/ld2410_ble.markdown @930913
 source/_integrations/leaone.markdown @bdraco
 source/_integrations/led_ble.markdown @bdraco
 source/_integrations/legrand.markdown @cgtobi
+source/_integrations/lektrico.markdown @lektrico
 source/_integrations/leviton_z_wave.markdown @home-assistant/z-wave
 source/_integrations/lg_netcast.markdown @Drafteed @splinter98
 source/_integrations/lidarr.markdown @tkdrob

diff --git a/source/_docs/asterisk_mbox.markdown b/source/_docs/asterisk_mbox.markdown
diff --git a/source/_docs/automation/trigger.markdown b/source/_docs/automation/trigger.markdown
@@ -31,6 +31,8 @@ An {% term automation %} can be triggered by an {% term event %}, a certain {% t
 - [Sentence trigger](#sentence-trigger)
 - [Multiple triggers](#multiple-triggers)
 - [Multiple Entity IDs for the same Trigger](#multiple-entity-ids-for-the-same-trigger)
+- [Disabling a trigger](#disabling-a-trigger)
+- [Merging lists of triggers](#merging-lists-of-triggers)
 
 ## Trigger ID
 
@@ -1070,3 +1072,28 @@ blueprint:
 ```
 
 {% endraw %}
+
+## Merging lists of triggers
+
+{% caution %}
+This feature requires Home Assistant version 2024.10 or later. If using this in a blueprint, set the `min_version` for the blueprint to at least this version.
+{% endcaution %}
+
+In some advanced cases (like for blueprints with trigger selectors), it may be necessary to insert a second list of triggers into the main trigger list. This can be done by adding a dictionary in the main trigger list with the sole key `triggers`, and the value for that key contains a second list of triggers. These will then be flattened into a single list of triggers. For example:
+
+```yaml
+blueprint:
+  name: Nested Trigger Blueprint
+  domain: automation
+  input:
+    usertrigger:
+      selector:
+        trigger:
+
+trigger:
+  - platform: event
+    event_type: manual_event
+  - triggers: !input usertrigger
+```
+
+This blueprint automation can then be triggered either by the fixed manual_event trigger, or additionally by any triggers selected in the trigger selector. This is also applicable for `wait_for_trigger` action.
diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown
@@ -1091,6 +1091,38 @@ While Jinja natively supports the conversion of an iterable to a `list`, it does
 
 Note that, in Home Assistant, to convert a value to a `list`, a `string`, an `int`, or a `float`, Jinja has built-in functions with names that correspond to each type.
 
+### Iterating multiple objects
+
+The `zip()` function can be used to iterate over multiple collections in one operation.
+
+{% raw %}
+
+```text
+{% set names = ['Living Room', 'Dining Room'] %}
+{% set entities = ['sensor.living_room_temperature', 'sensor.dining_room_temperature'] %}
+{% for name, entity in zip(names, entities) %}
+  The {{ name }} temperature is {{ states(entity) }}
+{% endfor %}
+```
+
+{% endraw %}
+
+`zip()` can also unzip lists.
+
+{% raw %}
+
+```text
+{% set information = [
+  ('Living Room', 'sensor.living_room_temperature'),
+  ('Dining Room', 'sensor.dining_room_temperature')
+] %}
+{% set names, entities = zip(*information) %}
+The names are {{ names | join(', ') }}
+The entities are {{ entities | join(', ') }}
+```
+
+{% endraw %}
+
 ### Functions and filters to process raw data
 
 These functions are used to process raw value's in a `bytes` format to values in a native Python type or vice-versa.
@@ -1148,6 +1180,178 @@ See: [Python regular expression operations](https://docs.python.org/3/library/re
 - Filter `value | regex_findall(find='', ignorecase=False)` will find all regex matches of the find expression in `value` and return the array of matches.
 - Filter `value | regex_findall_index(find='', index=0, ignorecase=False)` will do the same as `regex_findall` and return the match at index.
 
+## Merge action responses
+
+Using action responses we can collect information from various entities at the same time.
+Using the `merge_response` template we can merge several responses into one list.
+
+| Variable       | Description                                     |
+| -------------- | ----------------------------------              |
+| `value`        | The incoming value (must be an action response). |
+
+The `entity_id` key is appended to each dictionary within the template output list as a reference of origin. If the input dictionary already contains an `entity_id` key, the template will fail.
+
+The `value_key` key is appended to each dictionary within the template output list as a reference of origin if the original service call was providing a list of dictionaries, for example, `calendar.get_events` or `weather.get_forecasts`.
+
+Examples of these two keys can be seen in [example merge calendar action response](#example-merge-calendar-action-response) template output.
+
+
+### Example
+
+```yaml
+{% raw %}
+
+{% set combined_forecast = merge_response(response) %}
+{{ combined_forecast[0].precipitation | float(0) | round(1) }}
+
+{% endraw %}
+```
+
+### Example how to sort
+
+Sorting the dictionaries within the list based on a specific key can be done directly by using Jinja's `sort` filter.
+
+```yaml
+{% raw %}
+
+{{ merge_response(calendar_response) | sort(attribute='start') | ... }}
+
+{% endraw %}
+```
+
+### Example merge calendar action response
+
+```json
+{
+  "calendar.sports": {
+    "events": [
+      {
+        "start": "2024-02-27T17:00:00-06:00",
+        "end": "2024-02-27T18:00:00-06:00",
+        "summary": "Basketball vs. Rockets",
+        "description": "",
+      }
+    ]
+  },
+  "calendar.local_furry_events": {"events": []},
+  "calendar.yap_house_schedules": {
+    "events": [
+      {
+        "start": "2024-02-26T08:00:00-06:00",
+        "end": "2024-02-26T09:00:00-06:00",
+        "summary": "Dr. Appt",
+        "description": "",
+      },
+      {
+        "start": "2024-02-28T20:00:00-06:00",
+        "end": "2024-02-28T21:00:00-06:00",
+        "summary": "Bake a cake",
+        "description": "something good",
+      }
+    ]
+  },
+}
+```
+
+```yaml
+{% raw %}
+{{ merge_response(response_variable) }}
+{% endraw %}
+```
+
+```json
+[
+  {
+    "description": "",
+    "end": "2024-02-27T18:00:00-06:00",
+    "entity_id": "calendar.sports",
+    "start": "2024-02-27T17:00:00-06:00",
+    "summary": "Basketball vs. Rockets",
+    "value_key": "events"
+  },
+  {
+    "description": "",
+    "end": "2024-02-26T09:00:00-06:00",
+    "entity_id": "calendar.yap_house_schedules",
+    "start": "2024-02-26T08:00:00-06:00",
+    "summary": "Dr. Appt",
+    "value_key": "events"
+  },
+  {
+    "description": "something good",
+    "end": "2024-02-28T21:00:00-06:00",
+    "entity_id": "calendar.yap_house_schedules",
+    "start": "2024-02-28T20:00:00-06:00",
+    "summary": "Bake a cake",
+    "value_key": "events"
+  }
+]
+```
+
+### Example non-list action responses
+
+```json
+{
+  "vacuum.deebot_n8_plus_1": {
+    "header": {
+      "ver": "0.0.1",
+    },
+    "payloadType": "j",
+    "resp": {
+      "body": {
+        "msg": "ok",
+      },
+    },
+  },
+  "vacuum.deebot_n8_plus_2": {
+    "header": {
+      "ver": "0.0.1",
+    },
+    "payloadType": "j",
+    "resp": {
+      "body": {
+        "msg": "ok",
+      },
+    },
+  },
+}
+```
+
+```yaml
+{% raw %}
+{{ merge_response(response_variable) }}
+{% endraw %}
+```
+
+```json
+[
+  {
+    "entity_id": "vacuum.deebot_n8_plus_1",
+    "header": {
+      "ver": "0.0.1",
+    },
+    "payloadType": "j",
+    "resp": {
+      "body": {
+        "msg": "ok",
+      },
+    },
+  },
+  {
+    "entity_id": "vacuum.deebot_n8_plus_2",
+    "header": {
+      "ver": "0.0.1",
+    },
+    "payloadType": "j",
+    "resp": {
+      "body": {
+        "msg": "ok",
+      },
+    },
+  },
+]
+```
+
 ## Processing incoming data
 
 The other part of templating is processing incoming data. It allows you to modify incoming data and extract only the data you care about. This will only work for platforms and integrations that mention support for this in their documentation.
@@ -1284,7 +1488,7 @@ For actions, command templates are defined to format the outgoing MQTT payload t
 
 {% note %}
 
-Example command template:
+**Example command template with JSON data:**
 
 With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endraw %} renders to:
 
@@ -1298,6 +1502,14 @@ Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used
 
 {% endnote %}
 
+**Example command template with raw data:**
+
+When a command template renders to a valid `bytes` literal, then MQTT will publish this data as raw data. In other cases, a string representation will be published. So:
+
+- Template {% raw %}`{{ "16" }}`{% endraw %} renders to payload encoded string `"16"`.
+- Template {% raw %}`{{ 16 }}`{% endraw %} renders to payload encoded string `"16"`.
+- Template {% raw %}`{{ pack(0x10, ">B") }}`{% endraw %} renders to a raw 1 byte payload `0x10`.
+
 ## Some more things to keep in mind
 
 ### `entity_id` that begins with a number