Creating a scene by snapshotting entities (#11255)

* Initial commit

* snapshot_entities instead of snapshot

source/_integrations/scene.markdown

@@ -96,12 +96,12 @@ Whenever you make a change to your scene configuration, you can call the `scene.
 
 Create a new scene without having to configure it by calling the `scene.create` service. This scene will be discarded after reloading the configuration.
 
-You need to pass a `scene_id` in lowercase and with underscores instead of spaces. You also need to specify the entities in the same format as when configuring the scene.
+You need to pass a `scene_id` in lowercase and with underscores instead of spaces. You also may want to specify the entities in the same format as when configuring the scene. You can also take a snapshot of the current state by using the `snapshot_entities` parameter. In this case, you have to specify the `entity_id` of all entities you want to take a snapshot of. `entities` and `snapshot_entities` can be combined but you have to use at least one of them.
 
 If the scene was previously created by `scene.create`, it will be overwritten. If the scene was created by YAML, nothing happens but a warning in your log files.
 
 ```yaml
-# Example automation
+# Example automation using entities
 automation:
   trigger:
     platform: homeassistant
@@ -119,3 +119,41 @@ automation:
           state: on
           source: HDMI 1
 ```
+
+The following example turns off some entities as soon as a window opens. The states of the entities are restored after the window is closed again.
+
+```yaml
+# Example automation using snapshot
+- alias: Window opened
+  trigger:
+  - platform: state
+    entity_id: binary_sensor.window
+    from: 'off'
+    to: 'on'
+  condition: []
+  action:
+  - service: scene.create
+    data:
+      scene_id: before
+      snapshot_entities:
+      - climate.ecobee
+      - light.ceiling_lights
+  - service: light.turn_off
+    data:
+      entity_id: light.ceiling_lights
+  - service: climate.set_hvac_mode
+    data:
+      entity_id: climate.ecobee
+      hvac_mode: 'off'
+- alias: Window closed
+  trigger:
+  - platform: state
+    entity_id: binary_sensor.window
+    from: 'on'
+    to: 'off'
+  condition: []
+  action:
+  - service: scene.turn_on
+    data:
+      entity_id: scene.before
+```