Skip to main content
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

Build docs developers (and LLMs) love

Get started for freeTalk to us