344 lines
10 KiB
ReStructuredText
344 lines
10 KiB
ReStructuredText
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.
|
|
|
|
.. note::
|
|
|
|
If you have a :ref:`friendly_name <esphome-configuration_variables>` set for your device and
|
|
you want the number to use that name, you can set ``name: None``.
|
|
|
|
- **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://www.home-assistant.io/integrations/number/#device-class
|
|
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:
|
|
|
|
*
|