二十二 Home Assistant 实体-传感器

传感器实体

传感器是一种只读实体，用于提供一些信息。信息具有一个值，并且可选地具有一个度量单位。从 homeassistant.components.sensor.SensorEntity 派生实体平台。

属性

提示：属性应始终仅从内存返回信息，不应进行I/O操作（如网络请求）。实现 update() 或 async_update() 来获取数据。

名称	类型	默认值	描述
device_class	字符串	None	传感器类型。
last_reset	datetime.datetime	None	累积传感器（如电表、燃气表、水表等）初始化的时间。如果初始化时间未知，则设置为None。请注意，当实体的状态属性更新时，last_reset 属性返回的 datetime.datetime 将转换为ISO 8601格式的字符串。更改 last_reset 时，state 必须是有效数字。
native_unit_of_measurement	字符串	None	传感器值的[
](https://developers.home-assistant.io/docs/internationalization/core#unit-of-measurement-of-entities)。如果 native_unit_of_measurement 是°C或°F，并且其 device_class 是温度，则传感器的 unit_of_measurement 将是用户配置的首选温度单位，并且传感器的 state 将是经过可选单位转换后的 native_value。
native_value	None、datetime.date、datetime.datetime、decimal.Decimal、float、int、字符串	必需	传感器在其 native_unit_of_measurement 中的值。使用 device_class 可能会限制此属性可以返回的类型。
options	列表	None	如果此传感器提供文本状态，则可以使用此属性提供可能状态的列表。需要设置枚举设备类。不能与 state_class 或 native_unit_of_measurement 组合使用。
state_class	字符串	None	状态类型。如果不为None，则假定传感器为数值型，并将在前端显示为折线图，而不是离散值。
suggested_display_precision	int	None	传感器状态显示时应使用的小数位数。
suggested_unit_of_measurement	字符串	None	用于传感器状态的度量单位。对于具有 unique_id 的传感器，这将用作初始度量单位，用户随后可以覆盖。对于没有 unique_id 的传感器，这将是传感器状态的度量单位。此属性旨在供集成使用，以覆盖自动单位转换规则，例如，使温度传感器始终以°C显示，无论配置的单位系统是偏好°C还是°F，或者使距离传感器始终以英里显示，即使配置的单位系统是公制。

可用设备类别

如果指定设备类别，您的传感器实体还需要返回正确的度量单位。

常量	支持单位	描述
SensorDeviceClass.APPARENT_POWER	VA	视在功率
SensorDeviceClass.AQI	None	空气质量指数
SensorDeviceClass.ATMOSPHERIC_PRESSURE	cbar、bar、hPa、mmHg、inHg、kPa、mbar、Pa、psi	大气压力
SensorDeviceClass.BATTERY	%	电池剩余百分比
SensorDeviceClass.CO2	ppm	二氧化碳浓度
SensorDeviceClass.CO	ppm	一氧化碳浓度
SensorDeviceClass.CURRENT	A、mA	电流
SensorDeviceClass.DATA_RATE	bit/s、kbit/s、Mbit/s、Gbit/s、B/s、kB/s、MB/s、GB/s、KiB/s、MiB/s、GiB/s	数据速率
SensorDeviceClass.DATA_SIZE	bit、kbit、Mbit、Gbit、B、kB、MB、GB、TB、PB、EB、ZB、YB、KiB、MiB、GiB、TiB、PiB、EiB、ZiB、YiB	数据大小
SensorDeviceClass.DATE		日期。要求 native_value 是Python datetime.date 对象或None。
SensorDeviceClass.DISTANCE	km、m、cm、mm、mi、yd、in	通用距离
SensorDeviceClass.DURATION	d、h、min、s、ms	时间段。不应仅因时间流逝而更新。设备或服务需要提供新的数据点才能更新。
SensorDeviceClass.ENERGY	Wh、kWh、MWh、MJ、GJ	能量，此设备类别应用于表示能量消耗的传感器，例如电表。表示随时间变化的功率。不要与功率混淆。
SensorDeviceClass.ENERGY_STORAGE	Wh、kWh、MWh、MJ、GJ	存储能量，此设备类别应用于表示存储能量的传感器，例如当前存储在电池中的电能量或电池容量。表示随时间变化的功率。不要与功率混淆。
SensorDeviceClass.ENUM		传感器具有有限的（非数字）状态集。使用此设备类时，必须将 options 属性设置为可能状态的列表。
SensorDeviceClass.FREQUENCY	Hz、kHz、MHz、GHz	频率
SensorDeviceClass.GAS	m³、ft³、CCF	气体体积。以kWh为单位测量的气体消耗应归类为能量，而不是体积。
SensorDeviceClass.HUMIDITY	%	相对湿度
SensorDeviceClass.ILLUMINANCE	lx	光照水平
SensorDeviceClass.IRRADIANCE	W/m²、BTU/(h·ft²)	辐照度
SensorDeviceClass.MOISTURE	%	湿度
SensorDeviceClass.MONETARY	ISO 4217	货币值及货币单位
SensorDeviceClass.NITROGEN_DIOXIDE	µg/m³	二氧化氮浓度
SensorDeviceClass.NITROGEN_MONOXIDE	µg/m³	一氧化氮浓度
SensorDeviceClass.NITROUS_OXIDE	µg/m³	一氧化二氮浓度
SensorDeviceClass.OZONE	µg/m³	臭氧浓度
SensorDeviceClass.PH	None	水溶液的酸碱度（pH）
SensorDeviceClass.PM1	µg/m³	小于1微米的颗粒物浓度
SensorDeviceClass.PM25	µg/m³	小于2.5微米的颗粒物浓度
SensorDeviceClass.PM10	µg/m³	小于10微米的颗粒物浓度
SensorDeviceClass.POWER	W、kW	功率
SensorDeviceClass.POWER_FACTOR	%、None	功率因数
SensorDeviceClass.PRECIPITATION	cm、in、mm	累积降水量
SensorDeviceClass.PRECIPITATION_INTENSITY	in/d、in/h、mm/d、mm/h	降水强度
SensorDeviceClass.PRESSURE	cbar、bar、hPa、mmHg、inHg、kPa、mbar、Pa、psi	压力
SensorDeviceClass.REACTIVE_POWER	var	无功功率
SensorDeviceClass.SIGNAL_STRENGTH	dB、dBm	信号强度
SensorDeviceClass.SOUND_PRESSURE	dB、dBA	声压
SensorDeviceClass.SPEED	ft/s、in/d、in/h、km/h、kn、m/s、mph、mm/d	通用速度
SensorDeviceClass.SULPHUR_DIOXIDE	µg/m³	二氧化硫浓度
SensorDeviceClass.TEMPERATURE	°C、°F、K	温度
SensorDeviceClass.TIMESTAMP		时间戳。要求 native_value 返回带有时区信息的Python datetime.datetime 对象或None。
SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS	µg/m³	挥发性有机化合物浓度
SensorDeviceClass.VOLATILE_ORGANIC_COMPOUNDS_PARTS	ppm、ppb	挥发性有机化合物比例
SensorDeviceClass.VOLTAGE	V、mV	电压
SensorDeviceClass.VOLUME	L、mL、gal、fl. oz.、m³、ft³、CCF	通用体积，此设备类别应用于表示消耗的传感器，例如车辆消耗的燃料量。
SensorDeviceClass.VOLUME_FLOW_RATE	m³/h、ft³/min、L/min、gal/min	体积流量，此设备类别应用于表示一定体积流量的传感器，例如瞬间消耗的水量。
SensorDeviceClass.VOLUME_STORAGE	L、mL、gal、fl. oz.、m³、ft³、CCF	通用存储体积，此设备类别应用于表示存储体积的传感器，例如油箱中的燃料量。
SensorDeviceClass.WATER	L、gal、m³、ft³、CCF	水消耗
SensorDeviceClass.WEIGHT	kg、g、mg、µg、oz、lb、st	通用质量；使用重量而不是质量以符合日常语言习惯。
SensorDeviceClass.WIND_SPEED	ft/s、km/h、kn、m/s、mph	风速

可用状态类别

注意：为传感器选择状态类别时要谨慎。在大多数情况下，应选择状态类别 measurement 或不带 last_reset 的状态类别 total，如下文“如何选择 state_class 和 last_reset”中进一步解释。

类型	描述
measurement	状态表示当前时间的测量值，而不是历史聚合（如统计数据）或未来预测。应归类为 measurement 的示例有：当前温度、湿度或电功率。不应归类为 measurement 的示例有：明天的预测温度、昨天的能源消耗或任何其他不包括当前测量值的内容。对于支持的传感器，每5分钟更新一次每小时最小值、最大值和平均值的统计数据。
total	状态表示可以增加和减少的总量，例如净电表。自首次添加以来传感器值的累积增长或下降的统计数据每5分钟更新一次。此状态类别不应用于绝对值比累积增长或下降更重要的传感器，例如剩余电池容量或CPU负载；在这种情况下，应使用状态类别 measurement 代替。
total_increasing	与 total 类似，但限制状态表示单调递增的正总量，定期从0重新计数，例如每日消耗的燃气量、每周用水量或终身能源消耗。自首次添加以来传感器值的累积增长的统计数据每5分钟更新一次。减少的值被解释为新计量周期的开始或仪表的更换。

实体选项

传感器可以由用户配置，这是通过将传感器实体选项存储在传感器的实体注册表条目中来完成的。

选项	描述
unit_of_measurement	对于具有压力或温度设备类别的传感器，其度量单位可以被覆盖。

恢复传感器状态

在重启或重新加载后恢复状态的传感器不应扩展 RestoreEntity，因为它不存储 native_value，而是存储可能已被传感器基类实体修改的状态。恢复状态的传感器应扩展 RestoreSensor，并在 async_added_to_hass 中调用 await self.async_get_last_sensor_data 以访问存储的 native_value 和 native_unit_of_measurement。

长期统计数据

如果实体具有正确的属性，Home Assistant支持将传感器存储为长期统计数据。要选择加入统计，传感器必须将 state_class 设置为有效的状态类别之一：measurement、total 或 total_increasing。对于某些设备类别，统计数据的单位会被归一化，例如以便在单个图表中绘制多个传感器。

不表示总量的实体

Home Assistant跟踪统计期间的最小值、最大值和平均值。state_class 属性必须设置为 measurement，并且 device_class 不能是 energy、gas 或 monetary 中的任何一个。

表示总量的实体

跟踪总量的实体具有一个值，该值可能会定期重置，例如本月的能源消耗、今天的能源生产、过去一周用于加热房屋的颗粒重量或股票投资组合的年度增长。首次编译统计数据时传感器的值用作初始零点。

如何选择 state_class 和 last_reset

建议尽可能使用不带 last_reset 的状态类别 total，只有当不带 last_reset 的状态类别 total 不适用于传感器时，才应使用状态类别 total_increasing 或带 last_reset 的状态类别 total。

示例：

1. 传感器的值从不重置，例如终身总能源消耗或生产：state_class 为 total，last_reset 不设置或设置为None。
2. 传感器的值可能重置为0，且其值只能增加：状态类别为 total_increasing。示例：与计费周期对齐的能源消耗，例如每月，每次断开连接时电表重置为0。
3. 传感器的值可能重置为0，且其值可以增加和减少：状态类别为 total，last_reset 在值重置时更新。示例：与计费周期对齐的净能源消耗，例如每月。
4. 传感器的状态随每次状态更新而重置，例如每分钟更新一次过去一分钟的能源消耗的传感器：状态类别为 total，last_reset 随每次状态变化而更新。

状态类别 total

对于具有状态类别 total 的传感器，可以选择设置 last_reset 属性以手动控制计量周期。传感器首次添加到Home Assistant时的状态用作初始零点。当 last_reset 更改时，零点将设置为0。如果未设置 last_reset，则首次添加时传感器的值用作计算总和统计数据时的零点。

状态类别 total_increasing

对于具有状态类别 total_increasing 的传感器，减少的值被解释为新计量周期的开始或仪表的更换。重要的是，集成应确保在从存在测量噪声的传感器计算值时，值不会错误地减少。有一定的容忍度，状态变化之间小于10%的减少不会触发新的计量周期。此状态类别适用于燃气表、电表、水表等。计算总和统计数据时，传感器读数减少时的值不会用作零点，而是将零点设置为0。