From 6df1dc182222cea7b1cea840dd4e7cc0efa35d62 Mon Sep 17 00:00:00 2001
From: Andy Castille <me@andycc.dev>
Date: Thu, 12 Sep 2024 21:36:00 -0700
Subject: [PATCH] Document schedule data property (#32560)

* Document schedule data property

* Update schedule helper examples to remove data shorthand syntax
https://github.com/home-assistant/core/pull/116585#pullrequestreview-2280260436

---------

Co-authored-by: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com>
---
 source/_integrations/schedule.markdown | 63 ++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)

diff --git a/source/_integrations/schedule.markdown b/source/_integrations/schedule.markdown
index 9521ac54304..2102cbe54ba 100644
--- a/source/_integrations/schedule.markdown
+++ b/source/_integrations/schedule.markdown
@@ -63,6 +63,43 @@ schedule:
         to: "21:00:00"
 ```
 
+Defining the schedule in YAML also allows adding extra data to each block, which will
+appear as attributes on the schedule helper entity when that block is active. This can
+be used to easily build schedule-based automations.
+
+The `data` key of each block should be a mapping of attribute names to values. In this example,
+the schedule helper entity will have "Brightness" and "Color temp" attributes when
+the blocks are active:
+
+```yaml
+schedule:
+  light_schedule:
+    name: "Light schedule"
+    wednesday:
+      - from: "17:00:00"
+        to: "21:00:00"
+        data:
+          brightness: 100
+          color_temp: 4000
+    thursday:
+      - from: "17:00:00"
+        to: "23:00:00"
+        data:
+          brightness: 90
+          color_temp: 3500
+    friday:
+      - from: "07:00:00"
+        to: "10:00:00"
+        data:
+          brightness: 80
+          color_temp: 3000
+      - from: "16:00:00"
+        to: "23:00:00"
+        data:
+          brightness: 60
+          color_temp: 2500
+```
+
 {% configuration %}
 schedule:
   description: Alias for the schedule. Multiple entries are allowed.
@@ -91,6 +128,11 @@ schedule:
           description: The end time to mark as inactive/off again.
           required: true
           type: time
+        data:
+          description: Additional data to add to the entity's attributes when this block is active.
+          required: false
+          type: map
+          default: {}
 {% endconfiguration %}
 
 ### Attributes
@@ -118,6 +160,27 @@ trigger:
         entity_id: climate.thermostat
 ```
 
+Using the `light_schedule` example from above in an automation might look like this:
+
+{% raw %}
+
+```yaml
+trigger:
+    - platform: state
+      entity_id:
+        - schedule.light_schedule
+      to: "on"
+  action:
+    - service: light.turn_on
+      target:
+        entity_id: climate.thermostat
+      data_template:
+        brightness_pct: "{{ state_attr('schedule.light_schedule', 'brightness') }}"
+        kelvin: "{{ state_attr('schedule.light_schedule, 'temperature') }}"
+```
+
+{% endraw %}
+
 ### Actions
 
 Available action: `schedule.reload`.