Sensor entity#

Sensor 是一种提供某些信息的 read-only entity。信息具有一个 value，以及选项性的计量单位。从 homeassistant.components.sensor.SensorEntity 派生 entity platforms。

#属性

#可用的设备类型

如果指定 device class，你的 sensor entity 还需要返回正确的计量单位。

#可用的 state classes

#entity 选项

Sensors 可以由用户配置，这是通过在其 entity registry entry 中存储 sensor entity options 来实现的。

#恢复 sensor 状态

在 restart 或 reload 后恢复 state 的 sensors 不应扩展 RestoreEntity，因为它不存储 native_value，而是存储可能被 sensor base entity 修改的 state。恢复 state 的 sensors 应扩展 RestoreSensor，并从 async_added_to_hass 调用 await self.async_get_last_sensor_data，以访问存储的 native_value 和 native_unit_of_measurement。

#长期统计

Home Assistant 支持将 sensors 存储为 long-term statistics，前提是 entity 具有 正确的 properties。要 opt-in 进入 statistics，sensor 必须将 state_class 设为有效的 state class 之一：SensorStateClass.MEASUREMENT、SensorStateClass.TOTAL 或 SensorStateClass.TOTAL_INCREASING。 对于某些 device classes，statistics 的 unit 会被 normalized，例如使 能够在单个 graph 中绘制多个 sensors。

#不表示总量的 entities

Home Assistant 在 statistics 期间跟踪 min、max 和 mean value。 state_class property 必须设为 SensorStateClass.MEASUREMENT，且 device_class 不能 是 SensorDeviceClass.DATE、SensorDeviceClass.ENUM、SensorDeviceClass.ENERGY、SensorDeviceClass.GAS、SensorDeviceClass.MONETARY、 SensorDeviceClass.TIMESTAMP、SensorDeviceClass.VOLUME 或 SensorDeviceClass.WATER 中的任何一种。

#表示总量的 entities

跟踪 total amount 的 entities 具有一个可能定期重置的 value， 例如本月 energy consumption、今天的 energy production、过去一周用于供暖的 pellets 重量，或 stock portfolio 的年度增长。首次编译 statistics 时 sensor 的 value 用作初始零基准点。

#如何选择 state_class 和 last_reset

建议尽可能使用没有 last_reset 的 state class SensorStateClass.TOTAL，只有在没有 last_reset 的 state class SensorStateClass.TOTAL 不适用于 sensor 时，才应使用 state class SensorStateClass.TOTAL_INCREASING 或带有 last_reset 的 SensorStateClass.TOTAL。

示例：

• Sensor 的 value 从不重置，例如 lifetime total energy consumption 或 production：state_class SensorStateClass.TOTAL，last_reset 未设置或设为 None
• Sensor 的 value 可能重置为 0，且其 value 只能增加：state class SensorStateClass.TOTAL_INCREASING。示例：与 billing cycle 对齐的 energy consumption（例如每月），每次断开连接时重置为 0 的 energy meter
• Sensor 的 value 可能重置为 0，且其 value 既可以增加又可以减少：state class SensorStateClass.TOTAL，在 value 重置时更新 last_reset。示例：与 billing cycle 对齐的 net energy consumption（例如每月）。
• Sensor 的 state 每次 state update 时重置，例如每分钟更新一次、显示过去一分钟 energy consumption 的 sensor：state class SensorStateClass.TOTAL，每次 state change 时更新 last_reset。

#状态类 SensorStateClass.TOTAL

对于 state class 为 SensorStateClass.TOTAL 的 sensors，last_reset attribute 可以 选项性地设置，以获取对 meter cycles 的 manual control。 Sensor 首次添加到 Home Assistant 时的 state 用作初始 零基准点。当 last_reset 改变时，零基准点将设为 0。 如果未设置 last_reset，则计算 sum statistics 时使用 sensor 首次添加时的 value 作为 零基准点。

换句话说：更新 statistics 时的逻辑是用当前 state 与前一个 state 之间的差来更新 sum 列，除非 last_reset 已改变，此时不添加任何内容。

没有 last_reset 的 state class SensorStateClass.TOTAL 示例：

带有 last_reset 的 state class SensorStateClass.TOTAL 示例：

新 meter cycle 开始时初始 state 不为 0、但将 0 用作零基准点的 state class SensorStateClass.TOTAL 示例：

#状态类 SensorStateClass.TOTAL_INCREASING

对于 state_class 为 SensorStateClass.TOTAL_INCREASING 的 sensors，decreasing value 被 解释为新 meter cycle 的开始或 meter 的更换。重要的是，集成要确保从带有 measurement noise 的 sensor 计算 value 时，value 不会错误地减少。 有一定的容差，state change 之间减少 < 10% 不会触发新 meter cycle。此 state class 适用于 gas meters、electricity meters、water meters 等。 计算 sum statistics 时，sensor reading 减少时的 value 不会用作零基准点，而是将零基准点设为 0。

换句话说：更新 statistics 时的逻辑是用当前 state 与前一个 state 之间的差来更新 sum 列，除非该差为负，此时不添加任何内容。

State class SensorStateClass.TOTAL_INCREASING 示例：

Sensor 不重置为 0 的 state class SensorStateClass.TOTAL_INCREASING 示例：

#处理从不支持到支持计量单位的迁移

集成可能有具有自定义计量单位的 sensors，即它们不使用 Home Assistant 常量来设置 units。 在将这样的 sensor 迁移到 Home Assistant unit system 支持的 unit 时，旧的自定义 unit 必须与 Home Assistant 常量的值完全匹配，否则 Home Assistant 会将其视为 unit change。

例如，集成可能已将 energy sensor 的 unit 设为 KWh，这与 UnitOfEnergy.KILO_WATT_HOUR（kWh）的值不同。

在编译 long-term statistics 时会检测到这种 unit change。在没有旧 unit 和新 unit 之间关系的知识的情况下， 会抑制 statistics 的收集并生成关于 unit 不稳定的 warning。

为了便于这些 migration 情况，集成可以提供自定义 unit mapping 来声明任何不支持的 unit 等同于一个支持的 unit。这通过在集成的目录中创建 recorder platform recorder.py 并实现函数 async_custom_equivalent_units，为任何相关的 entity_id 返回一个 equivalent units 字典来完成。 此 mapping 将在 statistics 编译期间收集，并使集成能够平稳过渡到 Home Assistant 的 unit system。

示例实现：

@callback
def async_custom_equivalent_units(hass: HomeAssistant) -> dict[str, dict[str | None, str]]:
    """Return custom equivalent units per entity id."""
    return {
        "sensor.example_sensor_1": {
            "b/s": UnitOfDataRate.BYTES_PER_SECOND, # B/s
        },
        "sensor.example_sensor_2": {
            "KWh": UnitOfEnergy.KILO_WATT_HOUR, # kWh
        },
    }