emporia-energy

Emporia Energy Skill 是一款针对 Emporia Vue 智能能源监控设备的专用数据查询工具，通过支持云端 API 与本地 ESPHome 双模式架构，为用户提供灵活的能耗数据获取方案。该技能基于成熟的 PyEmVue 库与 ESPHome 原生 API 构建，能够以 JSON 格式输出结构化能源数据，适用于家庭自动化集成与能源分析场景。

核心用法方面，用户需根据设备固件类型选择工作模式：对于使用原厂固件的设备，启用 cloud 模式并配置 Emporia 账户凭据；对于已刷写 ESPHome 固件的设备，则使用 esphome 模式通过本地网络直连。通过设置相应的环境变量（EMPORIA_EMAIL/PASSWORD 或 ESPHOME_HOST/API_KEY），用户可执行 list、summary 及 circuit <name> 三种命令，分别获取通道列表、能耗概览及特定电路详情。数据查询结果包含时间戳、计量单位、总能耗及 Top 电路排名等关键指标。

显著优点体现在架构设计的灵活性上：双模式支持既满足了开箱即用的便捷性（cloud），又提供了数据主权与隐私保护（local）。基于 Python 的实现确保了跨平台兼容性（Darwin/Linux/Win32），而锁定的依赖版本（pyemvue==0.18.9）保障了运行环境的稳定性。JSON 输出格式便于与 Home Assistant 等智能家居平台或数据分析工具链集成，且所有操作均为只读，不会误修改设备配置。

潜在局限主要包括来源可信度与配置复杂度。作为 T3 级社区项目，其长期维护持续性需用户自行关注。技术层面，用户需具备基础的 Python 环境管理能力（venv/pip），且 ESPHome 模式要求用户已完成设备固件刷写与网络配置，门槛较高。此外，技能仅提供数据查询功能，无法对设备进行配置修改、固件升级或电路控制。

目标群体主要为 Emporia Vue 硬件用户、Home Assistant 智能家居爱好者，以及需要进行家庭能耗监测的数据分析师。对于已构建本地 ESPHome 生态的高级用户，该技能提供了脱离云服务的私有化数据方案；而对于普通用户，cloud 模式提供了低代码的快捷接入方式。

使用风险方面，常规风险包括：cloud 模式依赖 Emporia 云服务可用性与网络连接，存在单点故障与隐私数据外传可能；凭据（邮箱密码或 API Key）需通过环境变量管理，不当配置可能导致敏感信息泄露；Python 依赖环境可能随系统更新产生版本冲突。建议用户为 cloud 模式创建专用受限账户，定期更新依赖库，并优先在本地网络环境使用 ESPHome 模式以降低攻击面。