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’s sensor domain is the backbone of physical measurement: it reads numeric values from hardware — temperature, humidity, pressure, CO₂, distance, power, and hundreds more — then publishes those values to Home Assistant (or MQTT) in real time. Every sensor platform shares a common base configuration that handles naming, units, filtering, and automation triggers, so once you understand the base, you understand every sensor in ESPHome.

​
Base Sensor Configuration

All sensors inherit these configuration variables. You only need to supply the ones you want to override — sensible defaults are chosen automatically. 
sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Living Room Temperature"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      accuracy_decimals: 1
      filters:
        - sliding_window_moving_average:
            window_size: 5
            send_every: 5
    humidity:
      name: "Living Room Humidity"
      unit_of_measurement: "%"
    update_interval: 60s
​
id
string
Manually specify the ID used for code generation. At least one of id and name must be specified.
​
name
string
The name for the sensor as it appears in Home Assistant. Set to None to inherit the device’s friendly_name.
​
unit_of_measurement
string
Manually set the unit of measurement advertised to Home Assistant (e.g. "°C", "hPa", "W"). Does not perform unit conversion.
​
device_class
string
The Home Assistant device class for the sensor (e.g. temperature, humidity, power). Set to "" to remove a default device class.
​
state_class
string
The Home Assistant state class (measurement, total, total_increasing). Set to "" to remove the default.
​
icon
icon
Manually override the MDI icon shown in the Home Assistant frontend (e.g. "mdi:thermometer").
​
accuracy_decimals
int
Number of digits after the decimal point reported to Home Assistant. Controls display precision; does not change the raw value.
​
filters
list
A list of sensor filters applied in sequence before the value is published.
​
internal
boolean
If true, the sensor will not be exposed to the frontend. Setting only an id without a name implicitly sets this to true. Defaults to false.
​
force_update
boolean
If true, Home Assistant creates a state-changed event even when the value stays the same. Useful for Grafana but increases database size. Defaults to false.
​
disabled_by_default
boolean
If true, the entity is added to Home Assistant but hidden until the user manually enables it. Defaults to false.
​
entity_category
string
The entity category (config, diagnostic). Set to "" to remove the default.
​
expire_after
Time
MQTT only. Time after which the sensor value is marked as expired/unknown if no new update is received.

​
Automation Triggers

​
on_value
Automation
Triggered each time a new filtered value is published. The value is available as x.
​
on_value_range
Automation
Triggered when the published value transitions from outside to inside a defined range (above/below).
​
on_raw_value
Automation
Triggered when a raw value is received, before any filters are applied. The raw value is available as x.

​
Sensor Filters

Filters let you pre-process sensor values before they are published. Define them in a filters: block; they are applied in order. 
filters:
  - offset: 2.0                  # add a fixed offset
  - multiply: 1.05               # scale by a factor
  - calibrate_linear:            # two-point linear calibration
      - 0.0 -> 0.0
      - 100.0 -> 102.5
  - filter_out: 0.0              # drop specific values
  - median:                      # rolling median
      window_size: 5
      send_every: 5
  - sliding_window_moving_average:
      window_size: 15
      send_every: 15
  - exponential_moving_average:
      alpha: 0.1
      send_every: 15
  - calibrate_polynomial:         # polynomial curve calibration
      degree: 2
      datapoints:
        - 0.0 -> 0.0
        - 50.0 -> 48.0
        - 100.0 -> 99.0
  - clamp:                       # restrict value to a range
      min_value: 0.0
      max_value: 100.0
  - round: 1                     # round to N decimal places
  - throttle: 10s                # max one update per 10 s
  - throttle_average: 10s        # average over 10 s window, then publish
  - heartbeat: 60s               # publish at least once per 60 s
  - debounce: 0.5s               # ignore jitter shorter than 0.5 s
  - delta: 0.5                   # only publish if changed by ≥ 0.5
  - lambda: return x * (9.0/5.0) + 32.0;   # arbitrary C++ transform
Combine throttle and delta with or to publish on time or on significant change:
filters:
  - or:
    - throttle: 60s
    - delta: 1.0

​
Converting Celsius to Fahrenheit

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Temperature (°F)"
      filters:
        - lambda: return x * (9.0/5.0) + 32.0;
      unit_of_measurement: "°F"

​
Sensor Automations

​
on_value

Fired after filters pass a new value. Use x for the value. 
sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Temperature"
      on_value:
        then:
          - light.turn_on:
              id: status_led
              red: !lambda "return x / 50.0;"

​
on_value_range

Fired when the value crosses into a defined range. Ideal for threshold-based automation. 
sensor:
  - platform: adc
    pin: GPIO34
    name: "Tank Level"
    on_value_range:
      - below: 10.0
        then:
          - switch.turn_on: pump
      - above: 90.0
        then:
          - switch.turn_off: pump

​
sensor.in_range Condition

on_...:
  if:
    condition:
      sensor.in_range:
        id: my_sensor
        above: 20.0
        below: 80.0
    then:
      - logger.log: "Value is in range"

​
Lambda Calls

// Manually push a value
id(my_sensor).publish_state(42.0);

// Read the current filtered state
float val = id(my_sensor).get_state();

// Read the raw (unfiltered) state
float raw = id(my_sensor).get_raw_state();

DHT Temperature & Humidity

Classic DHT11/DHT22 sensors on a single GPIO pin. Simple, low-cost, and widely available.

BME280 / BME680

Bosch I²C sensors delivering temperature, humidity, pressure — and air quality on the 680.

AHT10 / AHT20

High-accuracy I²C temperature and humidity sensors popular in many IoT boards.

Dallas DS18B20

One-Wire temperature probe. Supports multiple sensors on a single pin with unique addresses.

ADC (Analog to Digital)

Read raw voltages on ADC-capable GPIO pins. Useful for resistive sensors and voltage dividers.

Pulse Counter

Count pulses on a GPIO — ideal for water meters, gas meters, and power meters with S0 output.

INA219 / INA3221

I²C current/power monitor IC. Measure voltage, current, and power on DC circuits up to 26 V.

VL53L0X / VL53L1X

Time-of-flight distance sensors that measure range from 1 cm to 4 m over I²C.
ESPHome supports 200+ sensor platforms. For the full list, visit the ESPHome sensor component documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us