Add number and template number docs (#1283)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

components/index.rst

@@ -9,6 +9,7 @@ Components
     cover/index
     fan/index
     light/index
+    number/index
     output/index
     sensor/index
     switch/index

components/number/index.rst

@@ -0,0 +1,188 @@
+Number Component
+================
+
+.. seo::
+    :description: Instructions for setting up number components in ESPHome.
+    :image: folder-open.png
+
+ESPHome has support for components to create a number entity. A number entity is
+like a sensor that can read a value from a device, but is useful when that value
+can be set by the user/frontend.
+
+.. note::
+
+    Home Assistant Core 2021.7 or higher is required for ESPHome number entities to work.
+
+.. _config-number:
+
+Base Number Configuration
+-------------------------
+
+All numbers in ESPHome have a name and an optional icon.
+
+.. code-block:: yaml
+
+    # Example number configuration
+    name: Livingroom Volume
+
+    # Optional variables:
+    icon: "mdi:volume-high"
+
+Configuration variables:
+
+- **name** (**Required**, string): The name for the number.
+- **icon** (*Optional*, icon): Manually set the icon to use for the number in the frontend.
+- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will
+  not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without
+  a ``name`` will implicitly set this to true.
+
+Automations:
+
+- **on_value** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when a new value is published. See :ref:`number-on_value`.
+- **on_value_range** (*Optional*, :ref:`Automation <automation>`): An automation to perform
+  when a published value transition from outside to a range to inside. See :ref:`number-on_value_range`.
+
+MQTT Options:
+
+- All other options from :ref:`MQTT Component <config-mqtt-component>`.
+
+Number Automation
+-----------------
+
+You can access the most recent state of the number in :ref:`lambdas <config-lambda>` using
+``id(number_id).state``.
+
+.. _number-on_value:
+
+``on_value``
+************
+
+This automation will be triggered when a new value is published. In :ref:`Lambdas <config-lambda>`
+you can get the value from the trigger with ``x``.
+
+.. code-block:: yaml
+
+    number:
+      - platform: template
+        # ...
+        on_value:
+          then:
+            - light.turn_on:
+                id: light_1
+                red: !lambda "return x/255;"
+
+Configuration variables: See :ref:`Automation <automation>`.
+
+.. _number-on_value_range:
+
+``on_value_range``
+******************
+
+With this automation you can observe if a number value passes from outside
+a defined range of values to inside a range.
+This trigger will only trigger when the new value is inside the range and the previous value
+was outside the range. On startup, the last state before reboot is restored and if the value crossed
+the boundary during the boot process, the trigger is also executed.
+
+Define the range with ``above`` and ``below``. If only one of them is defined, the interval is half-open.
+So for example ``above: 5`` with no below would mean the range from 5 to positive infinity.
+
+.. code-block:: yaml
+
+    number:
+      - platform: template
+        # ...
+        on_value_range:
+          above: 5
+          below: 10
+          then:
+            - switch.turn_on: relay_1
+
+Configuration variables:
+
+- **above** (*Optional*, float): The minimum for the trigger.
+- **below** (*Optional*, float): The maximum for the trigger.
+- See :ref:`Automation <automation>`.
+
+.. _number-in_range_condition:
+
+``number.in_range`` Condition
+*****************************
+
+This condition passes if the state of the given number is inside a range.
+
+Define the range with ``above`` and ``below``. If only one of them is defined, the interval is half-open.
+So for example ``above: 5`` with no below would mean the range from 5 to positive infinity.
+
+.. code-block:: yaml
+
+    # in a trigger:
+    on_...:
+      if:
+        condition:
+          number.in_range:
+            id: my_number
+            above: 50.0
+        then:
+          - script.execute: my_script
+
+Configuration variables:
+
+- **above** (*Optional*, float): The minimum for the condition.
+- **below** (*Optional*, float): The maximum for the condition.
+
+.. _number-set_action:
+
+``number.set`` Action
+*********************
+
+This is an :ref:`Action <config-action>` for setting a number state.
+
+.. code-block:: yaml
+
+    - number.set:
+        id: my_number
+        value: 42
+
+Configuration variables:
+
+- **id** (**Required**, :ref:`config-id`): The ID of the number to set.
+- **value** (**Required**, float, :ref:`templatable <config-templatable>`):
+  The value to set the number to.
+
+.. _number-lambda_calls:
+
+lambda calls
+************
+
+From :ref:`lambdas <config-lambda>`, you can call several methods on all numbers to do some
+advanced stuff (see the full API Reference for more info).
+
+- ``make_call()``: Set the number value.
+
+  .. code-block:: cpp
+
+      // Within lambda, push a value of 42
+      auto call = id(my_number).make_call();
+      call.set_value(42);
+      call.perform();
+
+- ``.state``: Retrieve the current value of the number. Is ``NAN`` if no value has been read or set.
+
+  .. code-block:: cpp
+
+      // For example, create a custom log message when a value is received:
+      ESP_LOGI("main", "Value of my number: %f", id(my_number).state);
+
+See Also
+--------
+
+- :apiref:`number/number.h`
+- :ghedit:`Edit`
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *

components/number/template.rst

@@ -0,0 +1,52 @@
+Template Number
+===============
+
+.. seo::
+    :description: Instructions for setting up template numbers with ESPHome.
+    :image: description.png
+
+The ``template`` number platform allows you to create a number with templated values
+using :ref:`lambdas <config-lambda>`.
+
+.. code-block:: yaml
+
+    # Example configuration entry
+    number:
+      - platform: template
+        name: "Template number"
+        update_interval: never
+        min_value: 0
+        max_value: 100
+        step: 1
+
+Configuration variables:
+------------------------
+
+- **name** (**Required**, string): The name of the number.
+- **min_value** (**Required**, float): The minimum value this number can be.
+- **max_value** (**Required**, float): The maximum value this number can be.
+- **step** (**Required**, float): The granularity with which the number can be set.
+- **lambda** (*Optional*, :ref:`lambda <config-lambda>`):
+  Lambda to be evaluated every update interval to get the new value of the number.
+- **set_action** (*Optional*, :ref:`Action <config-action>`): The action that should
+  be performed when the remote (like Home Assistant's frontend) requests to set the number value.
+- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the
+  number. Defaults to ``60s``.
+- **optimistic** (*Optional*, boolean): Whether to operate in optimistic mode - when in this mode,
+  any command sent to the template number will immediately update the reported state.
+  Defaults to ``false``.
+- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
+- All other options from :ref:`Sensor <config-number>`.
+
+``number.set`` Action
+----------------------------------
+
+You can also publish a state to a template number from elsewhere in your YAML file
+with the :ref:`number-set_action`.
+
+See Also
+--------
+
+- :ref:`automation`
+- :apiref:`template/number/template_number.h`
+- :ghedit:`Edit`

guides/automations.rst

@@ -379,6 +379,7 @@ All Actions
 - :ref:`rf_bridge.learn <rf_bridge-learn_action>`
 - :ref:`ds1307.read_time <ds1307-read_time_action>` / :ref:`ds1307.write_time <ds1307-write_time_action>`
 - :ref:`cs5460a.restart <cs5460a-restart_action>`
+- :ref:`number.set <number-set_action>`
 
 .. _config-condition:
 
@@ -399,6 +400,7 @@ All Conditions
 - :ref:`text_sensor.state <text_sensor-state_condition>`
 - :ref:`light.is_on <light-is_on_condition>` / :ref:`light.is_off <light-is_off_condition>`
 - :ref:`display.is_displaying_page <display-is_displaying_page-condition>`
+- :ref:`number.in_range <number-in_range_condition>`
 
 All Lambda Calls
 ----------------
@@ -410,6 +412,7 @@ All Lambda Calls
 - :ref:`Cover <cover-lambda_calls>`
 - :ref:`Text Sensor <text_sensor-lambda_calls>`
 - :ref:`Stepper <stepper-lambda_calls>`
+- :ref:`Number <number-lambda_calls>`
 
 .. _delay_action:
 

index.rst

@@ -400,6 +400,14 @@ Climate Components
     Midea Air Conditioner, components/climate/midea_ac, midea.svg
     Anova Cooker, components/climate/anova, anova.png
 
+Number Components
+-----------------
+
+.. imgtable::
+
+    Number Core, components/number/index, folder-open.svg
+    Template Number, components/number/template, description.svg
+
 Misc Components
 ---------------