Documentation for fan speed levels (#1056)

* Update speed fan and REST API docs with speed_level

* Update fan docs

* Add configurable speed_levels to speed fan

* Update components/fan/index.rst

Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>

* Changed speed_levels to speed_count to match HA and updated descriptions

Co-authored-by: Guillermo Ruffino <glm.net@gmail.com>

components/fan/index.rst

@@ -7,14 +7,13 @@ Fan Component
 
 With the ``fan`` domain you can create components that appear as fans in
 the Home Assistant frontend. A fan can be switched ON or OFF, optionally
-has a speed setting (``LOW``, ``MEDIUM``, ``HIGH``) and can have an
-oscillate output.
+has a speed level between 1 and the maximum supported speed level of the fan, and can have an
+oscillate and direction output.
 
 This component restores its state on reboot/reset.
 
 .. figure:: images/fan-ui.png
     :align: center
-    :width: 70.0%
 
 .. _config-fan:
 
@@ -93,9 +92,8 @@ Configuration options:
 - **id** (**Required**, :ref:`config-id`): The ID of the fan.
 - **oscillating** (*Optional*, boolean, :ref:`templatable <config-templatable>`):
   Set the oscillation state of the fan. Defaults to not affecting oscillation.
-- **speed** (*Optional*, string, :ref:`templatable <config-templatable>`):
-  Set the speed setting of the fan. One of ``OFF``, ``LOW``, ``MEDIUM``, ``HIGH``.
-  If you template this value, return ``FAN_SPEED_...``, for example ``FAN_SPEED_HIGH``.
+- **speed** (*Optional*, int, :ref:`templatable <config-templatable>`):
+  Set the speed level of the fan. Can be a number between 1 and the maximum speed level of the fan.
 
 Full Fan Index
 --------------

components/fan/speed.rst

@@ -30,15 +30,9 @@ Configuration variables:
   :ref:`output <output>` to use for the oscillation state of this fan. Default is empty.
 - **direction_output** (*Optional*, :ref:`config-id`): The id of the
   :ref:`output <output>` to use for the direction state of the fan. Default is empty.
-- **speed** (*Optional*): Set the float values for each speed setting:
-
-  - **low** (**Required**, float): Set the value for the low speed
-    setting. Must be in range 0 to 1. Defaults to 0.33.
-  - **medium** (**Required**, float): Set the value for the medium speed
-    setting. Must be in range 0 to 1. Defaults to 0.66.
-  - **high** (**Required**, float): Set the value for the high speed
-    setting. Must be in range 0 to 1. Defaults to 1.
-
+- **speed_count** (*Optional*, int): Set the number of supported discrete speed levels. The value is used
+  to calculate the percentages for each speed. E.g. ``2`` means that you have 50% and 100% while ``100``
+  will allow 1% increments in the output. Defaults to ``100``.
 - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
 - All other options from :ref:`Fan Component <config-fan>`.
 

web-api/index.rst

@@ -192,7 +192,7 @@ GET request to ``/fan/<id>``.
       "id": "fan-living_room_fan",
       "state": "ON",
       "value": true,
-      "speed": "high",
+      "speed_level": 2,
       "oscillation": false
     }
 
@@ -200,11 +200,11 @@ GET request to ``/fan/<id>``.
 -  **id**: The id of the fan. Prefixed by ``fan-``.
 -  **state**: The text-based state of the fan as a string.
 -  **value**: The binary (``true``/``false``) state of the fan.
--  **speed**: The speed setting of the fan if it's supported. Either "off", "low", "medium" or "high".
+-  **speed_level**: The speed level of the fan if it's supported. Value is between 1 and the maximum supported by the fan.
 -  **oscillation**: Whether the oscillation setting of the fan is on. Only sent if the fan supports it.
 
 To control the state of the fan, send POST requests to ``/fan/<id>/turn_on``, ``/fan/<id>/turn_off``
 and ``/fan/<id>/toggle``. Turn on additionally supports these optional parameters:
 
--  **speed**: The new speed setting of the fan. Values as above.
+-  **speed_level**: The new speed level of the fan. Values as above.
 -  **oscillation**: The new oscillation setting of the fan. Values as above.