Sensor entity

A sensor is a read-only entity that reports a value: a temperature, the power a plug draws, the time a device last booted, or one of a fixed list of text states. It can carry a unit of measurement, and Home Assistant converts that unit to what the user prefers. Inherit from SensorEntity, imported from homeassistant.components.sensor.

Use a sensor when the value has more than two states and the user cannot change it. Two states is a binary sensor. A value the user sets is a number, select, or text entity.

You set the value in its native unit, the unit the device or service reports. Never set state or unit_of_measurement yourself: the base class owns them, converts the native value to the unit the user wants, and validates the result.

The generic properties every entity has, like name or available, are on the entity class.

A sensor can never have the config entity category: Home Assistant refuses to add it. Use EntityCategory.DIAGNOSTIC for sensors like signal strength.

The base class picks the unit it shows in this order:

1. A unit the user set in the entity settings.
2. The initial unit, stored in the entity registry for sensors with a unique ID: the suggested_unit_of_measurement, or else the unit the user's unit system prefers for the device class. A sensor without a unique ID uses the suggested_unit_of_measurement directly.
3. The temperature unit of the user's unit system, for sensors with the temperature device class and a native unit of °C or °F.
4. A translated unit: the unit_of_measurement key next to the name in the entity section of strings.json, looked up by translation_key. Use this for units that are words, like "steps". A sensor with a translated unit must not set native_unit_of_measurement.
5. The native_unit_of_measurement.

Users can change the unit of any sensor whose device class has a unit converter, as long as both the native unit and the new unit are valid for that device class.

Use the unit constants from homeassistant.const, like UnitOfTemperature.CELSIUS, instead of writing the unit as a string. A custom string that only looks like a supported unit, like KWh instead of kWh, counts as a different unit.

To restore the value after a restart, inherit from RestoreSensor instead of RestoreEntity. RestoreEntity stores the converted state, which can be in a different unit than the native value. Call await self.async_get_last_sensor_data() in async_added_to_hass to get back the native_value and native_unit_of_measurement.

Do not add extra_state_attributes to a sensor for values that change often. Every state change with changed attributes is written to the database. Create another sensor instead. See state and attributes.

This entity has no supported features.

The device class tells Home Assistant what the sensor measures. It sets the icon, the unit conversion, and how the frontend shows the value. A sensor with a device class and no name is named after its device class, except for enum. See naming.

When you set a device class, the unit must be one of the units listed for it, and the state class must be one the device class allows. Home Assistant logs a warning when they do not match.

Non-numeric device classes take no unit and no state class:

Numeric device classes and their units:

The allowed state classes per device class are in DEVICE_CLASS_STATE_CLASSES in homeassistant/components/sensor/const.py. Most allow only measurement. AREA, DATA_SIZE, DISTANCE, DURATION, and PRECIPITATION allow every state class, and WEIGHT allows measurement, total, and total_increasing. Device classes that count something up, like ENERGY, GAS, WATER, VOLUME, and REACTIVE_ENERGY, allow only total and total_increasing. MONETARY allows only total, and WIND_DIRECTION only measurement_angle.

The state class says what kind of number the value is. Pick it with care: it decides which statistics Home Assistant keeps.

In most cases you want MEASUREMENT, or TOTAL without last_reset.

A sensor with a state class gets long-term statistics, compiled every 5 minutes. For some device classes, the unit of the statistics is normalized, so sensors with different units fit in one graph.

• Measurements (MEASUREMENT and MEASUREMENT_ANGLE) get the minimum, maximum, and mean of each period.
• Totals (TOTAL and TOTAL_INCREASING) get a running sum. The value when statistics are first compiled is the zero point.

• The value never resets, like the lifetime energy use of a device: TOTAL, without last_reset.
• The value only goes up, and sometimes resets to 0, like an energy meter aligned with a billing month: TOTAL_INCREASING.
• The value goes up and down, and resets at known moments, like net energy per billing month: TOTAL, and update last_reset when it resets.
• Every update is a new period, like the energy used in the last minute: TOTAL, and update last_reset with every state change.

With TOTAL, the sum grows by the difference between the new and the old value. When last_reset changes, a new cycle starts from 0: the first value after the reset is added in full. At 16:00 below, the 3 already counts.

With TOTAL_INCREASING, a drop in value starts a new meter cycle, and that cycle also counts from 0, so the first value after the drop is added in full. A drop of less than 10% is treated as noise, not as a reset. Make sure a value you calculate from noisy readings cannot drop by mistake.

If your integration used a custom unit string and moves to a supported unit, statistics see that as a unit change and stop compiling for that sensor. To avoid that, add a recorder.py platform to your integration with an async_custom_equivalent_units function. It returns, per entity ID, which old unit equals which supported unit.

from homeassistant.const import UnitOfEnergy
from homeassistant.core import HomeAssistant, callback


@callback
def async_custom_equivalent_units(
    hass: HomeAssistant,
) -> dict[str, dict[str | None, str]]:
    """Return custom equivalent units per entity ID."""
    return {
        "sensor.example_energy": {"KWh": UnitOfEnergy.KILO_WATT_HOUR},
    }

A sensor has no actions, so there is nothing to implement beyond keeping native_value current. Fetch data in update or async_update, or push it with async_write_ha_state. See updating state.

The state is native_value, converted to the unit shown to the user. Dates and timestamps are written as ISO 8601 strings, and timestamps are converted to UTC. A None value shows as unknown.

A temperature sensor that reads its value from a device:

from homeassistant.components.sensor import (
    SensorDeviceClass,
    SensorEntity,
    SensorStateClass,
)
from homeassistant.const import UnitOfTemperature


class ExampleTemperatureSensor(SensorEntity):
    """Temperature of an example device."""

    _attr_has_entity_name = True
    _attr_device_class = SensorDeviceClass.TEMPERATURE
    _attr_state_class = SensorStateClass.MEASUREMENT
    _attr_native_unit_of_measurement = UnitOfTemperature.CELSIUS
    _attr_suggested_display_precision = 1

    def __init__(self, device: ExampleDevice) -> None:
        """Initialize the sensor."""
        self._device = device
        self._attr_unique_id = f"{device.serial}_temperature"

    async def async_update(self) -> None:
        """Fetch the latest temperature."""
        self._attr_native_value = await self._device.get_temperature()

The sensor has no name, so it is named after its device class: "Temperature".