esphome-docs/components/number/index.rst

Number Component
================

.. seo::
    :description: Instructions for setting up number components in ESPHome.
    :image: folder-open.svg

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.
- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend,
  (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI).
  Requires Home Assistant 2021.9 or newer. Defaults to ``false``.
- **entity_category** (*Optional*, string): The category of the entity.
  See https://developers.home-assistant.io/docs/core/entity/#generic-properties
  for a list of available options. Requires Home Assistant 2021.11 or newer.
  Set to ``""`` to remove the default entity category.
- **unit_of_measurement** (*Optional*, string): Manually set the unit
  of measurement for the number. Requires Home Assistant Core 2021.12 or newer.
- **mode** (*Optional*, string): Defines how the number should be displayed in the frontend.
  See https://developers.home-assistant.io/docs/core/entity/number/#properties
  for a list of available options. Requires Home Assistant Core 2021.12 or newer.
  Defaults to ``"auto"``.
- **device_class** (*Optional*, string): The device class for the number.
  See https://developers.home-assistant.io/docs/core/entity/number/#available-device-classes
  for a list of available options.

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-increment_action:

``number.increment`` Action
***************************

This is an :ref:`Action <config-action>` for incrementing a number value by its
step size (default: 1).

.. code-block:: yaml

    - number.increment:
        id: my_number
        cycle: false

    # Shorthand
    - number.increment: my_number

Configuration variables:

- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.
- **cycle** (*Optional*, boolean): Whether or not to set the number to its minimum
  value when the increment pushes the value beyond its maximum value. This will only
  work when the number component uses a minimum and maximum value.
  Defaults to ``true``.

.. _number-decrement_action:

``number.decrement`` Action
***************************

This is an :ref:`Action <config-action>` for decrementing a number value by its
step size (default: 1).

.. code-block:: yaml

    - number.decrement:
        id: my_number
        cycle: false

    # Shorthand
    - number.decrement: my_number

Configuration variables:

- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.
- **cycle** (*Optional*, boolean): Whether or not to set the number to its maximum
  value when the decrement pushes the value below its minimum value. This will only
  work when the number component uses a minimum and maximum value.
  Defaults to ``true``.

.. _number-to-min_action:

``number.to_min`` Action
************************

This is an :ref:`Action <config-action>` seting a number to its minimum value, given
a number component that has a minimum value defined for it.

.. code-block:: yaml

    - number.to_min:
        id: my_number

    # Shorthand
    - number.to_min: my_number

Configuration variables:

- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.

.. _number-to-max_action:

``number.to_max`` Action
************************

This is an :ref:`Action <config-action>` seting a number to its maximum value (given
a number component that has a maximum value defined for it.

.. code-block:: yaml

    - number.to_max:
        id: my_number

    # Shorthand
    - number.to_max: my_number

Configuration variables:

- **id** (**Required**, :ref:`config-id`): The ID of the number component to update.

.. _number-operation_action:

``number.operation`` Action
***************************

This is an :ref:`Action <config-action>` that can be used to perform an operation
on a number component (set to minimum or maximum value, decrement, increment),
using a generic templatable action call.

.. code-block:: yaml

    # Using values
    - number.operation:
        id: my_number
        operation: Increment
        cycle: true

    # Or templated (lambda)
    - number.operation:
        id: my_number
        operation: !lambda "return NUMBER_OP_INCREMENT;"
        cycle: !lambda: "return true;"

Configuration variables:

- **id** (**Required**, :ref:`config-id`): The ID of the number to update.
- **operation** (**Required**, string, :ref:`templatable <config-templatable>`):
  What operation to perform on the number component. One of ``TO_MIN``,
  ``TO_MAX``, ``DECREMENT`` or ``INCREMENT`` (case insensitive). When writing a
  lambda for this field, then return one of the following enum values:
  ``NUMBER_OP_TO_MIN``, ``NUMBER_OP_TO_MAX``, ``NUMBER_OP_DECREMENT`` or
  ``NUMBER_OP_INCREMENT``.
- **cycle** (*Optional*, bool, :ref:`templatable <config-templatable>`):
  Can be used with ``DECREMENT`` or ``INCREMENT`` to specify whether or not to
  wrap around the value when respectively the minimum or maximum value of the
  number is exceeded.

.. _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()``: Make a call for updating 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();

  Check the API reference for information on the methods that are available for
  the ``NumberCall`` object. You can for example also use ``call.number_to_min()``
  to set the number to its minimum value or ``call.number_increment(true)`` to increment
  the number by its step size with the cycle feature enabled.

- ``.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/number.h>`
- :apiref:`NumberCall <number/number_call.h>`
- :ghedit:`Edit`

.. toctree::
    :maxdepth: 1
    :glob:

    *