将网上国网接入 Home Assistant
在文章将公牛智家设备接入 Home Assistant 和将菲斯曼设备接入 Home Assistant 中，笔者分别介绍了通过分析厂商 App，将原本封闭的智能家居设备接入 Home Assistant 的方法。最近，笔者又遇到了一个类似的需求：把「网上国网」中的用电量、电费账单和账户余额也接入 Home Assistant。
网上国网 App 本身已经可以查看每日用电量和月度账单，但每次都要打开 App 查询并不方便，也无法直接参与 Home Assistant 的能源统计和自动化。例如，接入以后可以在家庭仪表盘中统一查看本月累计用电量，在电量异常增加时发送通知，或者结合其他设备分析空调、暖气等大功率电器的使用情况。
目前已经有一些通过国家电网网页获取数据的开源项目，不过这类方案通常需要运行 Docker 和浏览器，利用 Playwright 等工具模拟网页登录；遇到图形验证码时，还可能需要额外配置 OCR 或大模型服务。为了减少部署组件和长期维护成本，笔者开发了原生 Home Assistant 集成 hass-state-grid，直接使用网上国网 App 的接口获取数据，不依赖 Docker、浏览器或验证码识别服务。
从 App 接口开始分析
网上国网并不是简单地把用户名、密码和查询参数放进普通 JSON 请求。App 的登录和业务请求还包含动态 KeyCode、Token、签名以及 SM2/SM4 加密信封，并使用设备指纹判断登录环境。部分关键参数构造位于经过 J2C/VMP 保护的 Native 代码中，直接反编译只能看到被打散的控制流，难以恢复完整语义。
为此，笔者先从静态代码中恢复接口路径、参数来源和调用关系，再结合经过授权的测试账户核对请求与响应。登录参数、加密信封、签名、Token 生命周期管理和设备身份最终都使用 Python 重新实现。设备指纹由集成在本地生成并持久化，同一个 Home Assistant 配置项会长期保持为同一台逻辑设备；删除配置项后，才会生成新的设备身份。
因此，集成在日常运行时不需要启动官方 App，也不需要 Android 模拟器、ADB 或 Frida，相比依赖 Docker 或者浏览器的方案也更简单。
集成提供的数据
配置成功后，每个绑定的用电户号都会作为一个独立设备加入 Home Assistant，并提供以下传感器：
- 上一日用电量：国家电网最新发布的一条日用电量，实际日期记录在
latest_date属性中； - 本月用电量：当前自然月截至最新数据日的累计用电量；
- 上一结算月电量和电费：最近一个已经完成出账的结算周期数据；
- 本年累计电量和电费：月度账单接口给出的年度累计值；
- 账户余额：预付费账户余额，或者后付费账户已有的可用结余；
- 应交金额：后付费账户当前需要缴纳的金额；
- 上月抄表读数：在地区接口支持时，查询最近结算周期结束时的电表读数。
「上一日」和「上一结算月」并不一定严格对应昨天和上一个自然月。国家电网的数据通常会延迟一到两天发布，账单也可能因为地区结算周期而稍晚生成。因此，集成始终保留服务端返回的真实日期，而不会把缺失数据自动填成零。
同一个网上国网账户绑定多个户号时，只需要配置一次，集成会自动创建多个设备。查询范围可以设置为最近一到三个月，默认每十二小时更新一次，也可以在六到二十四小时之间调整。
Home Assistant 能源面板
「本月用电量」和「本年累计电量」使用 Home Assistant 原生的energy设备类型、kWh单位和total_increasing状态类型，因此可以直接添加到能源面板。
笔者推荐选择「本月用电量」，因为它比结算账单更新得更及时。月份切换后累计值会下降，Home Assistant 会将其识别为新的计量周期并继续统计。「本年累计电量」也可以使用，但不要把两个实体同时添加到同一个户号的电网消耗中，否则会重复计算。
「上一日用电量」和「上一结算月电量」属于单日、单月历史快照，并不是连续增长的电表累计值。集成没有为它们设置state_class，因此它们不会出现在能源面板的正常选择列表中，可以避免误选后产生错误统计。
需要注意的是，面向普通居民户号的日用电接口只提供日级数据，而且通常在第二天才发布，所以能源面板不能获得实时功率或精确的小时曲线。它更适合观察长期的日、月用电趋势，而不能替代本地智能电表或功率计。
安装与登录
项目可以通过 HACS 安装：
- 打开 HACS 的「集成」页面，在右上角菜单中选择「自定义存储库」；
- 添加
https://github.com/stevenjoezhang/hass-state-grid，类别选择「集成」； - 搜索并下载「国家电网」，随后重启 Home Assistant；
- 进入「设置 → 设备与服务」，添加「国家电网」集成；
- 输入网上国网的手机号和密码。
如果服务端认为这是新设备，配置流程会自动发送安全验证短信，并继续要求输入六位验证码。验证成功后，设备资料、登录 Token 和必要的户号信息会保存在 Home Assistant 配置项中。Token 失效时，集成会使用已保存的密码自动重新登录；只有服务端再次明确要求新设备验证时，才需要用户重新输入短信验证码。
需要提醒的是，Home Assistant 的配置项会保存网上国网密码，.storage目录和备份文件应当妥善保护，不要上传到公开位置。
总结
hass-state-grid实现了一个不依赖浏览器的网上国网 Home Assistant 集成。安装后只需输入手机号和密码，就可以在 Home Assistant 中查看每日用电、月度账单、年度累计、账户余额和应交金额，并将累计电量接入原生能源面板。
这个项目延续了笔者此前开发 Home Assistant 集成时的思路：尽量把复杂的协议适配隐藏在集成内部，让最终用户只需要面对 Home Assistant 熟悉的设备、实体和配置流程。与此同时，所有数据仍然以国家电网账单为准，集成中的日电量和统计结果只适合家庭自动化与趋势分析，不应作为正式计费或结算依据。