From e784059e838c203538d761fb5ad07dedd840d920 Mon Sep 17 00:00:00 2001
From: Raman Gupta <7243222+raman325@users.noreply.github.com>
Date: Wed, 28 Jul 2021 02:45:01 -0400
Subject: [PATCH] Add documentation on new template functions for devices
 (#18540)

* Add documentation on new template functions for devices

* fix examples

* Update docs

* rename function

* rename back

* Rename template function back
---
 source/_docs/automation/templating.markdown   |  9 +++++++
 .../_docs/configuration/templating.markdown   | 25 +++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/source/_docs/automation/templating.markdown b/source/_docs/automation/templating.markdown
index 6f1d89e1ab6..60d3fc3c92f 100644
--- a/source/_docs/automation/templating.markdown
+++ b/source/_docs/automation/templating.markdown
@@ -18,6 +18,15 @@ The following describes trigger data associated with all platforms.
 | `trigger.id` | Optional trigger `id`, or index of the trigger.
 | `trigger.idx` | Index of the trigger.
 
+### Device
+
+| Template variable | Data |
+| ---- | ---- |
+| `trigger.platform` | Hardcoded: `device`.
+| `trigger.event` | Event object that matched.
+| `trigger.event.event_type` | Event type.
+| `trigger.event.data` | Optional event data.
+
 ### Event
 
 | Template variable | Data |
diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown
index 121aabbae43..d19bd022e79 100644
--- a/source/_docs/configuration/templating.markdown
+++ b/source/_docs/configuration/templating.markdown
@@ -207,6 +207,31 @@ The same thing can also be expressed as a filter:
 
 {% endraw %}
 
+### Devices
+
+- `device_entities(device_id)` returns a list of entities that are associated with a given device ID. Can also be used as a filter.
+- `device_attr(device_or_entity_id, attr_name)` returns the value of `attr_name` for the given device or entity ID. Not supported in [limited templates](#limited-templates).
+- `is_device_attr(device_or_entity_id, attr_name, attr_value)` returns whether the value of `attr_name` for the given device or entity ID matches `attr_value`. Not supported in [limited templates](#limited-templates).
+- `device_id(entity_id)` returns the device ID for a given entity ID. Can also be used as a filter
+
+#### Devices examples
+
+{% raw %}
+
+```text
+{{ device_attr('deadbeefdeadbeefdeadbeefdeadbeef', 'manufacturer') }}  # Sony
+```
+
+```text
+{{ is_device_attr('deadbeefdeadbeefdeadbeefdeadbeef', 'manufacturer', 'Sony') }}  # true
+```
+
+```text
+{{ device_id('sensor.sony') }}  # deadbeefdeadbeefdeadbeefdeadbeef
+```
+
+{% endraw %}
+
 ### Time
 
 `now()` and `utcnow()` are not supported in [limited templates](#limited-templates).