Sensor Platform

API reference for implementing sensor entities in Home Assistant

The sensor platform allows integrations to expose read-only measurement values and state information to Home Assistant. Sensors are one of the most common entity types.

Base Class

All sensor entities inherit from SensorEntity, which is defined in homeassistant.components.sensor.

from homeassistant.components.sensor import SensorEntity

class MySensor(SensorEntity):
    """Representation of a sensor."""

Entity Description

Sensor entities can optionally use SensorEntityDescription to define static metadata:

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

SENSOR_TYPES = [
    SensorEntityDescription(
        key="temperature",
        name="Temperature",
        device_class=SensorDeviceClass.TEMPERATURE,
        native_unit_of_measurement=UnitOfTemperature.CELSIUS,
        state_class=SensorStateClass.MEASUREMENT,
    ),
]

Required Properties

native_value

The current value of the sensor. Can be a number, string, date, or datetime.

@cached_property
def native_value(self) -> StateType | date | datetime | Decimal:
    """Return the value reported by the sensor."""
    return self._attr_native_value

Optional Properties

device_class

Indicates the type of sensor. This affects how the sensor is displayed and what unit conversions are available.

@cached_property
def device_class(self) -> SensorDeviceClass | None:
    """Return the class of this entity."""
    return self._attr_device_class

Common device classes:

• TEMPERATURE - Temperature sensor
• HUMIDITY - Humidity sensor
• POWER - Power consumption
• ENERGY - Energy consumption
• PRESSURE - Pressure
• BATTERY - Battery level
• TIMESTAMP - Date/time value
• ENUM - Enumerated value

native_unit_of_measurement

The unit of measurement for the sensor value.

@cached_property
def native_unit_of_measurement(self) -> str | None:
    """Return the unit of measurement of the sensor."""
    return self._attr_native_unit_of_measurement

state_class

Indicates how the state should be tracked over time. Required for long-term statistics.

@cached_property
def state_class(self) -> SensorStateClass | None:
    """Return the state class of this entity."""
    return self._attr_state_class

Available state classes:

• MEASUREMENT - Instantaneous value (temperature, power)
• TOTAL - Monotonically increasing total (energy consumed)
• TOTAL_INCREASING - Total that can decrease (e.g., water tank level)

suggested_display_precision

Number of decimal places to display in the UI.

@cached_property
def suggested_display_precision(self) -> int | None:
    """Return the suggested number of decimal digits for display."""
    return self._attr_suggested_display_precision

suggested_unit_of_measurement

Override automatic unit conversion to suggest a specific display unit.

@cached_property
def suggested_unit_of_measurement(self) -> str | None:
    """Return the unit which should be used for the sensor's state."""
    return self._attr_suggested_unit_of_measurement

options

For enum sensors, the list of valid values.

@cached_property
def options(self) -> list[str] | None:
    """Return a set of possible options."""
    return self._attr_options

last_reset

For total sensors, when the value was last reset.

@cached_property
def last_reset(self) -> datetime | None:
    """Return the time when the sensor was last reset."""
    return self._attr_last_reset

Example Implementation

from homeassistant.components.sensor import (
    SensorEntity,
    SensorDeviceClass,
    SensorStateClass,
)
from homeassistant.const import UnitOfTemperature
from homeassistant.core import HomeAssistant
from homeassistant.helpers.entity_platform import AddEntitiesCallback

class TemperatureSensor(SensorEntity):
    """Representation of a temperature sensor."""

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

    def __init__(self, name: str, device_id: str) -> None:
        """Initialize the sensor."""
        self._attr_name = name
        self._attr_unique_id = f"{device_id}_temperature"
        self._attr_native_value = None

    async def async_update(self) -> None:
        """Fetch new state data for the sensor."""
        # Fetch data from your device/API
        self._attr_native_value = await self._fetch_temperature()

    async def _fetch_temperature(self) -> float:
        """Fetch temperature from device."""
        # Your implementation here
        return 22.5

RestoreSensor

For sensors that should restore their state after restart:

from homeassistant.components.sensor import RestoreSensor

class MyRestorableSensor(RestoreSensor):
    """Sensor that restores its state."""

    async def async_added_to_hass(self) -> None:
        """Restore last state."""
        await super().async_added_to_hass()
        
        if (last_sensor_data := await self.async_get_last_sensor_data()):
            self._attr_native_value = last_sensor_data.native_value
            self._attr_native_unit_of_measurement = last_sensor_data.native_unit_of_measurement

Real-World Example

From the demo integration (homeassistant/components/demo/sensor.py):

class DemoSensor(SensorEntity):
    """Representation of a Demo sensor."""

    _attr_should_poll = False

    def __init__(
        self,
        unique_id: str,
        name: str,
        state: float,
        device_class: SensorDeviceClass | None,
        state_class: SensorStateClass | None,
        unit_of_measurement: str | None,
        battery: int | None,
    ) -> None:
        """Initialize the sensor."""
        self._attr_device_class = device_class
        self._attr_name = name
        self._attr_native_unit_of_measurement = unit_of_measurement
        self._attr_native_value = state
        self._attr_state_class = state_class
        self._attr_unique_id = unique_id

Important Notes

• Sensors should set _attr_native_value rather than implementing state directly
• The state property is final and handles unit conversion automatically
• For numeric sensors, always set a device_class and/or state_class to enable unit conversion
• Use native_unit_of_measurement for the raw value’s unit; Home Assistant handles conversion
• Sensors with EntityCategory.CONFIG cannot be added (will raise HomeAssistantError)

See Also

• Entity Documentation
• Device Classes Constants
• Demo Sensor Implementation