> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```python theme={null}
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:

```python theme={null}
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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@cached_property
def last_reset(self) -> datetime | None:
    """Return the time when the sensor was last reset."""
    return self._attr_last_reset
```

## Example Implementation

```python theme={null}
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:

```python theme={null}
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`):

```python theme={null}
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](/api/entity)
* [Device Classes Constants](https://github.com/home-assistant/core/blob/dev/homeassistant/components/sensor/const.py)
* [Demo Sensor Implementation](https://github.com/home-assistant/core/blob/dev/homeassistant/components/demo/sensor.py)