Number Component

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.

Base Number Configuration

All numbers in ESPHome have a name and an optional icon.

# 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.

Automations:

  • on_value (Optional, Automation): An automation to perform when a new value is published. See on_value.

  • on_value_range (Optional, Automation): An automation to perform when a published value transition from outside to a range to inside. See on_value_range.

MQTT Options:

Number Automation

You can access the most recent state of the number in lambdas using id(number_id).state.

on_value

This automation will be triggered when a new value is published. In Lambdas you can get the value from the trigger with x.

number:
  - platform: template
    # ...
    on_value:
      then:
        - light.turn_on:
            id: light_1
            red: !lambda "return x/255;"

Configuration variables: See Automation.

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.

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 Automation.

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.

# 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

This is an Action for setting a number state.

- number.set:
    id: my_number
    value: 42

Configuration variables:

  • id (Required, ID): The ID of the number to set.

  • value (Required, float, templatable): The value to set the number to.

lambda calls

From lambdas, 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.

    // 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.

    // 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