From d41290fa5101817eeef1cc54b457ecb2ea7dc8f6 Mon Sep 17 00:00:00 2001
From: "J. Nick Koston" <nick@koston.org>
Date: Fri, 29 Jan 2021 05:37:44 -0600
Subject: [PATCH] Update fan documentation for entity model separation of fan
 speeds into percentages and presets modes (#16265)

---
 source/_integrations/fan.markdown | 65 ++++++++++++++++++++++++++++---
 1 file changed, 59 insertions(+), 6 deletions(-)

diff --git a/source/_integrations/fan.markdown b/source/_integrations/fan.markdown
index d4cd431ba9d..36ba9c1368f 100644
--- a/source/_integrations/fan.markdown
+++ b/source/_integrations/fan.markdown
@@ -16,7 +16,10 @@ The Fan integration allows you to control and monitor Fan devices.
 ### Fan control services
 
 Available services:
-`fan.set_speed`, `fan.set_direction`, `fan.oscillate`, `fan.turn_on`, `fan.turn_off`, `fan.toggle`
+`fan.set_percentage`, `fan.set_preset_mode`, `fan.set_direction`, `fan.oscillate`, `fan.turn_on`, `fan.turn_off`, `fan.toggle`
+
+Deprecated services:
+`fan.set_speed`
 
 <div class='note'>
 
@@ -24,14 +27,14 @@ Not all fan services may be available for your platform. You can check which ser
 
 </div>
 
-### Service `fan.set_speed`
+### Service `fan.set_percentage`
 
-Sets the speed for fan device.
+Sets the speed percentage for fan device.
 
 | Service data attribute | Optional | Description |
 | ---------------------- | -------- | ----------- |
 | `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
-| `speed` | no | Speed setting
+| `percentage` | no | Percentage speed setting
 
 #### Automation example
 
@@ -41,10 +44,34 @@ automation:
     platform: time
     at: "07:15:00"
   action:
-    - service: fan.set_speed
+    - service: fan.set_percentage
       data:
         entity_id: fan.kitchen
-        speed: low
+        percentage: 33
+```
+
+
+### Service `fan.set_preset_mode`
+
+Sets a preset mode for fan device.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
+| `preset_mode` | no | The preset mode
+
+#### Automation example
+
+```yaml
+automation:
+  trigger:
+    platform: time
+    at: "07:15:00"
+  action:
+    - service: fan.set_preset_mode
+      data:
+        entity_id: fan.kitchen
+        preset_mode: auto
 ```
 
 ### Service `fan.set_direction`
@@ -100,6 +127,8 @@ Turn fan device on. This is only supported if the fan device supports being turn
 | Service data attribute | Optional | Description |
 | ---------------------- | -------- | ----------- |
 | `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
+| `percentage` | yes | Percentage speed setting
+| `preset_mode` | yes | The preset mode
 
 ### Service `fan.turn_off`
 
@@ -108,3 +137,27 @@ Turn fan device off. This is only supported if the fan device supports being tur
 | Service data attribute | Optional | Description |
 | ---------------------- | -------- | ----------- |
 | `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
+
+
+### Deprecated Service `fan.set_speed`
+
+Sets the speed for fan device.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that define the entity ID(s) of fan device(s) to control. To target all fan devices, use `all`.
+| `speed` | no | Speed setting
+
+#### Automation example
+
+```yaml
+automation:
+  trigger:
+    platform: time
+    at: "07:15:00"
+  action:
+    - service: fan.set_speed
+      data:
+        entity_id: fan.kitchen
+        speed: low
+```