Add documentation for BSB-Lan hot water schedule action and examples

source/_integrations/bsblan.markdown

@@ -46,6 +46,93 @@ or using a passkey is supported. Use either one.
 - `climate`
 - `water heater`
 
+## Actions
+
+The integration provides the following action.
+
+### Action `bsblan.set_hot_water_schedule`
+
+Sets the hot water heating schedule for your BSB-Lan device. Each day of the week can have one or more time periods when hot water heating should be active.
+
+- **Target**: `device_id`
+  - **Description**: The BSB-Lan device to configure. Use the `target` field with a `device_id` to specify which device you want to set the schedule for.
+  - **Required**: Yes
+- **Data attribute**: `schedule`
+  - **Description**: A schedule object containing one or more day configurations. Each day accepts a string in the format `"HH:MM-HH:MM HH:MM-HH:MM"`. Multiple time periods can be specified, separated by spaces. Use 24-hour time format. Set a day to `null` to clear its schedule. Available days: `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`.
+  - **Required**: Yes
+
+## Examples
+
+The following examples show how to use the BSB-Lan integration actions in Home Assistant automations.
+
+### Setting a weekday and weekend schedule
+
+This example sets different schedules for weekdays and weekends.
+
+```yaml
+action: bsblan.set_hot_water_schedule
+target:
+  device_id: abc123device456
+data:
+  schedule:
+    monday: "06:00-08:00 17:00-21:00"
+    tuesday: "06:00-08:00 17:00-21:00"
+    wednesday: "06:00-08:00 17:00-21:00"
+    thursday: "06:00-08:00 17:00-21:00"
+    friday: "06:00-08:00 17:00-21:00"
+    saturday: "08:00-22:00"
+    sunday: "08:00-22:00"
+```
+
+### Seasonal schedule automation
+
+This example automatically adjusts the hot water schedule based on the season.
+
+{% raw %}
+
+```yaml
+automation:
+  - alias: "Set hot water schedule - winter"
+    triggers:
+      - trigger: state
+        entity_id: sensor.season
+        to: winter
+    actions:
+      - action: bsblan.set_hot_water_schedule
+        target:
+          device_id: "{{ device_id('water_heater.bsblan_hot_water') }}"
+        data:
+          schedule:
+            monday: "05:00-08:30 16:00-23:00"
+            tuesday: "05:00-08:30 16:00-23:00"
+            wednesday: "05:00-08:30 16:00-23:00"
+            thursday: "05:00-08:30 16:00-23:00"
+            friday: "05:00-08:30 16:00-23:00"
+            saturday: "07:00-23:00"
+            sunday: "07:00-23:00"
+
+  - alias: "Set hot water schedule - summer"
+    triggers:
+      - trigger: state
+        entity_id: sensor.season
+        to: summer
+    actions:
+      - action: bsblan.set_hot_water_schedule
+        target:
+          device_id: "{{ device_id('water_heater.bsblan_hot_water') }}"
+        data:
+          schedule:
+            monday: "06:00-07:00 18:00-20:00"
+            tuesday: "06:00-07:00 18:00-20:00"
+            wednesday: "06:00-07:00 18:00-20:00"
+            thursday: "06:00-07:00 18:00-20:00"
+            friday: "06:00-07:00 18:00-20:00"
+            saturday: "08:00-21:00"
+            sunday: "08:00-21:00"
+```
+
+{% endraw %}
+
 For more documentation of the BSBLan device, check the [manual](https://docs.bsb-lan.de).
 
 To see a more detailed listing of the reported systems which are successfully used with BSB-LAN, please follow the corresponding link: