From fbc506a8e86cb5b383dd98723d0cfdd3c1ab9e73 Mon Sep 17 00:00:00 2001
From: Raman Gupta <7243222+raman325@users.noreply.github.com>
Date: Sun, 22 Aug 2021 04:52:24 -0400
Subject: [PATCH] Add documentation on zwave_js automations (#19008)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>
---
 source/_integrations/zwave_js.markdown | 52 ++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/source/_integrations/zwave_js.markdown b/source/_integrations/zwave_js.markdown
index a348318b25f..8e9e7982407 100644
--- a/source/_integrations/zwave_js.markdown
+++ b/source/_integrations/zwave_js.markdown
@@ -431,6 +431,58 @@ action:
       entity_id: switch.in_wall_dual_relay_switch_2, switch.in_wall_dual_relay_switch_3
 ```
 
+## Automations
+
+### Device automations
+
+Z-Wave JS has support for device triggers and conditions. To use a device automation, use the automation UI to select the "Device" trigger/condition type, and then pick your Z-Wave JS device. Under trigger/condition types, you will see Z-Wave JS specific entries.
+
+### `zwave_js.value_updated` trigger
+
+Z-Wave JS provides the `zwave_js.value_updated` trigger platform which can be used to trigger automations on any Z-Wave JS value update, including Z-Wave values that aren't supported in Home Assistant via entities. While they can't be authored from the automation UI, they can be authored in YAML directly in your `configuration.yaml`.
+
+```yaml
+# Example automation trigger that fires whenever the `latchStatus` value changes from `closed` to `opened` on the three devices (devices will be derived from an entity ID).
+trigger:
+  platform: zwave_js.value_updated
+  # At least one `device_id` or `entity_id` must be provided
+  device_id: 45d7d3230dbb7441473ec883dab294d4  # Garage Door Lock device ID
+  entity_id:
+    - lock.front_lock
+    - lock.back_door
+  # `property` and `command_class` are required
+  command_class: 98 # Door Lock CC
+  property: "latchStatus"
+  # `property_key` and `endpoint` are optional
+  property_key: null
+  endpoint: 0
+  # `from` and `to` will both accept lists of values and the trigger will fire if the value update matches any of the listed values
+  from:
+    - "closed"
+    - "jammed"
+  to: "opened"
+```
+
+#### Available Trigger Data
+
+In addition to the [standard automation trigger data](docs/automation/templating/#all), the `zwave_js.value_updated` trigger platform has additional trigger data available for use.
+
+| Template variable            | Data                                                                                       |
+|------------------------------|--------------------------------------------------------------------------------------------|
+| `trigger.device_id`          | Device ID for the device in the device registry.                                           |
+| `trigger.node_id`            | Z-Wave node ID.                                                                            |
+| `trigger.command_class`      | Command class ID.                                                                          |
+| `trigger.command_class_name` | Command class name.                                                                        |
+| `trigger.property`           | Z-Wave Value's property.                                                                   |
+| `trigger.property_name`      | Z-Wave Value's property name.                                                              |
+| `trigger.property_key`       | Z-Wave Value's property key.                                                               |
+| `trigger.property_key_name`  | Z-Wave Value's property key name.                                                          |
+| `trigger.endpoint`           | Z-Wave Value's endpoint.                                                                   |
+| `trigger.previous_value`     | The previous value for this Z-Wave value (translated to a state name when possible).       |
+| `trigger.previous_value_raw` | The raw previous value for this Z-Wave value (the key of the state when a state is named). |
+| `trigger.current_value`      | The current value for this Z-Wave value (translated to a state name when possible).        |
+| `trigger.current_value_raw`  | The raw current value for this Z-Wave value (the key of the state when a state is named).  |
+
 ## Current Limitations
 
 - 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).