实体注册
实体注册是 Home Assistant 记录实体的注册表。任何添加到 Home Assistant 的实体,如果指定了 unique_id
属性,都会被注册到注册表中。
注册的优点在于,同一个实体将始终获得相同的实体 ID。这也将防止其他实体使用该实体 ID。
用户还可以在实体注册中覆盖实体的名称。设置后,实体注册中的名称将优先于设备可能自我提供的名称。
唯一 ID
用户无法更改唯一 ID 这一点非常重要,因为系统将失去与唯一 ID 相关的所有设置。
实体根据平台类型(例如 light
)、集成名称( 域)(例如 hue)和实体的唯一 ID 的组合在注册表中进行查找。实体的唯一 ID 中不应包含 domain
(例如 your_integration
)和平台类型(例如 light
),因为系统已经考虑到了这些标识符。
如果一个设备具有唯一的 id,但提供多个实体,则将唯一 id 与实体的唯一标识符结合。例如,如果一个设备同时测量温度和湿度,可以使用 {unique_id}-{sensor_type}
唯一识别这些实体。
唯一 ID 要求
可接受的唯一 ID 示例来源
- 设备的序列号
- MAC 地址:使用
homeassistant.helpers.device_registry.format_mac
格式化;只能从设备 API 或发现处理程序获得 MAC 地址。依赖于读取 arp 缓存或本地网络访问的工具,如getmac
,在所有支持的网络环境中可能无法正常工作,因此不被接受。 - 纬度和经度或其他唯一地理位置
- 物理上打印在设备上或烧录到 EEPROM 中的唯一标识符
最后手段的唯一 ID
对于通过配置条目设置的实体,如果没有其他唯一 ID 可用,可以使用 配置条目 ID
作为最后手段。
不可接受的唯一 ID 来源
- IP 地址
- 设备名称
- 主机名
- URL
- 电子邮件地址
- 用户名