Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/esphome/esphome.io/llms.txt

Use this file to discover all available pages before exploring further.

ESPHome uses a consistent set of configuration variable types across all its components. Understanding these types helps you read component documentation, avoid common errors, and write correct YAML configurations the first time. This page documents every built-in type you will encounter in the ESPHome reference.

​
ID

IDs are the primary way ESPHome connects components defined in different parts of your configuration. For example, you define a light component with an id, then reference that same ID in an automation or script to control it at runtime. Naming rules — IDs are converted into C++ variable names, so they must follow C++ identifier conventions:
  • Must start with a letter and can end with numbers
  • Must not have a space in the name
  • Cannot have special characters except the underscore (_)
  • Must not be a C++ reserved keyword (e.g., int, class, return)
  • Must be unique within the configuration file
output:
  - platform: ledc
    id: my_led_output    # ✅ valid — used below
    pin: GPIO2

light:
  - platform: monochromatic
    output: my_led_output  # references the ID above
    name: "Status LED"
ESPHome IDs are internal to the firmware and are not the same as Home Assistant entity IDs. Renaming an ESPHome ID does not affect how the entity appears in Home Assistant.

​
Pin

ESPHome always uses the chip’s internal GPIO numbers. These are integers that can optionally be prefixed with GPIO. 
# Both of these refer to the same physical pin
output:
  - platform: gpio
    pin: 2

output:
  - platform: gpio
    pin: GPIO2
Board aliases — Most development boards define friendly aliases for their exposed pins. For example, the NodeMCU ESP8266 uses silk-screened labels D0 through D8 that map to internal GPIO numbers. Either form is accepted in configuration: 
# NodeMCU ESP8266 — both are equivalent
some_component:
  pin: GPIO16

some_component:
  pin: D0   # D0 is the NodeMCU alias for GPIO16
Supported aliases depend on the board specified in the esphome: or esp8266: / esp32: section. Refer to the specific board’s datasheet or the ESPHome board definitions for the full mapping.

​
Pin Schema

When a component needs more control over a pin beyond just its number, it accepts a pin schema — an expanded mapping that configures direction, pull resistors, inversion, and other electrical characteristics. 
binary_sensor:
  - platform: gpio
    # Simple form — just a number
    pin: GPIO4

    # Advanced form — full pin schema
    pin:
      number: GPIO4
      mode:
        input: true
        pullup: true
      inverted: true

​
Configuration Variables

number (Required, Pin) The GPIO number of the pin, in any form accepted by the Pin type. inverted (Optional, boolean, default: false) When true, all read and write values are logically inverted. Useful when a circuit is wired active-low. 
pin:
  number: GPIO5
  inverted: true   # LOW on the wire = HIGH in ESPHome logic
mode (Optional, string or mapping) Configures the pin’s electrical direction and internal resistors. Accepts either a shorthand string or an explicit mapping. Shorthand strings:
StringEquivalent mapping
INPUTinput: true
OUTPUToutput: true
OUTPUT_OPEN_DRAINoutput: true, open_drain: true
INPUT_PULLUPinput: true, pullup: true
INPUT_PULLDOWNinput: true, pulldown: true
ANALOG(platform-specific analog mode)
INPUT_OUTPUT_OPEN_DRAINinput: true, output: true, open_drain: true
Mapping keys (all optional booleans):
  • input — Configure the pin as a digital input.
  • output — Configure the pin as a digital output.
  • pullup — Enable the internal pull-up resistor.
  • pulldown — Enable the internal pull-down resistor.
  • open_drain — Use open-drain drive mode instead of push-pull.
pin:
  number: GPIO12
  mode:
    input: true
    pullup: true
allow_other_uses (Optional, boolean, default: false) By default, ESPHome raises an error if the same pin number appears in multiple component configurations. Set to true to suppress that error in the rare cases where a pin is intentionally shared between components. ignore_strapping_warning (Optional, boolean, default: false) Certain ESP32 pins are strapping pins sampled at boot to configure initial chip state (e.g., boot mode selection). ESPHome warns when you configure I/O on these pins. If you have verified that your specific circuit will not cause boot issues, set this to true to suppress the warning.
Only suppress strapping pin warnings if you are absolutely certain your hardware design will not interfere with the chip’s boot sequence. Incorrect use can prevent the device from booting.
drive_strength (Optional, string, default: 20mA) (ESP32 with ESP-IDF framework only) Sets the maximum current the pad can source or sink. Options: 5mA, 10mA, 20mA, 40mA. 
pin:
  number: GPIO2
  drive_strength: 40mA
ignore_pin_validation_error (Optional, boolean, default: false) Some GPIO numbers are reserved for internal ESP32 functions (e.g., flash memory on GPIO 6–11). ESPHome raises an error if you try to use them. If your specific board routes these pins differently and you have confirmed they are safe to use, set this to true.

​
Time

Time values are used throughout ESPHome for update_interval, debounce durations, automation delays, and more. Several formats are supported: 
some_component:
  # Unit suffixes
  duration: 1000us    # microseconds
  duration: 1000ms    # milliseconds
  duration: 1.5s      # seconds (decimals allowed)
  duration: 0.5min    # minutes
  duration: 2h        # hours

  # HH:MM and HH:MM:SS — must be quoted
  duration: '2:01'       # 2 hours, 1 minute
  duration: '2:01:30'    # 2 hours, 1 minute, 30 seconds

  # Mapping form — combine multiple units
  duration:
    milliseconds: 10
    seconds: 30
    minutes: 25
    hours: 3
    days: 0
For update_interval specifically, two special values are also accepted: 
sensor:
  - platform: template
    update_interval: never    # pause updates entirely
    update_interval: 0ms      # update every loop() cycle
    update_interval: always   # alias for 0ms
When specifying HH:MM or HH:MM:SS time strings, always wrap them in quotes ('2:01'). Without quotes, the YAML parser interprets the colon as a key-value separator and the value will not parse correctly.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us