--- page-title: "CubicPill/china_southern_power_grid_stat: Home Assistant intergration to get statictics from China Southern Power Grid (CSG) 南方电网HA集成" url: https://github.com/CubicPill/china_southern_power_grid_stat date: "2024-12-11 17:22:05" --- ## China Southern Power Grid Statistics [](https://github.com/CubicPill/china_southern_power_grid_stat#china-southern-power-grid-statistics) ## 南方电网电费数据HA集成 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E5%8D%97%E6%96%B9%E7%94%B5%E7%BD%91%E7%94%B5%E8%B4%B9%E6%95%B0%E6%8D%AEha%E9%9B%86%E6%88%90) [![hacs_badge](https://camo.githubusercontent.com/c430acde220d0b69bcab5985d189f6721e04ac42b4cedd417157fc3dc48a5661/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f484143532d44656661756c742d3431424446352e737667)](https://github.com/hacs/integration) [![GitHub release (latest by date)](https://camo.githubusercontent.com/fbf093e16a62934f9abebba800faf9dcb3bbdc0d5a8f1dd813e85e2dfa5551ea/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f637562696370696c6c2f6368696e615f736f75746865726e5f706f7765725f677269645f73746174)](https://github.com/CubicPill/china_southern_power_grid_stat/releases) [![License: GPL v3](https://camo.githubusercontent.com/8a398fc9fbf479a323d2d91b9fcb6fb9c6b4d08e96dbb544488ccbed312115fc/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d47504c76332d626c75652e737667)](https://www.gnu.org/licenses/gpl-3.0) ## 支持功能 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E6%94%AF%E6%8C%81%E5%8A%9F%E8%83%BD) - ✅支持南方电网覆盖范围内的电费数据查询（广东、广西、云南、贵州、海南） - ✅支持使用手机号、短信验证码和密码（可选）登录，支持南网在线APP、微信、支付宝扫码登录 - ✅支持多个南网账户（每个账户一个集成），支持单个账户下的多个缴费号 - ✅数据自动抓取和更新（默认间隔4小时，可配置） - ✅全程GUI配置，无需编辑yaml进行配置（暂不支持yaml配置） 可接入如下数据： - 当前余额和欠费 - 当前阶梯电量数据（档位、阶梯剩余电量、阶梯电价） - 昨日用电量 - 最新一日用电量、电费（取有数据的最近一日） - 本年度总用电量、总电费（非实时，更新到上个月） - 本年度每月用电量、电费（非实时，更新到上个月） - 上年度总用电量、总电费 - 上年度每月用电量、电费 - 当月累计用电量、电费（非实时，有2天左右的延迟） - 当月每日用电量、电费（非实时，有2天左右的延迟） - 上月累计用电量、电费 - 上月每日用电量、电费 ❌**不支持**阶梯电费设置（仅能获取当前所在阶梯）、峰谷电价设置和电费计算（本插件只进行数据抓取和转换，不进行任何计算）， 暂时也没有支持计划（南网暂时没有统一的API），如有需求，建议单独创建对应的电价实体。 ❌因为南网登录API调整，不再支持登录态失效之后自动重新登录，需要手动重新登录。 ## 使用方法 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E4%BD%BF%E7%94%A8%E6%96%B9%E6%B3%95) 使用[HACS](https://hacs.xyz/)或[手动下载安装](https://github.com/CubicPill/china_southern_power_grid_stat/releases) 注意：本集成需求`Home Assistant`最低版本为`2022.11`。 ### 配置界面 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E9%85%8D%E7%BD%AE%E7%95%8C%E9%9D%A2) 支持的登录方式 [![](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_login.png)](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_login.png) 配置界面 [![](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_add_account.png)](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_add_account.png) 添加缴费号 [![](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_select_account.png)](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_select_account.png) 传感器列表 - 余额 - 欠费 - 当前阶梯档位 - 当前阶梯剩余电量 - 当前阶梯电价 - 上月电费 - 上月用电量 - 当月用电量 - 当月电费 - 本年度电费 - 本年度用电量 - 上年度电费 - 上年度用电量 - 最近日用电量 - 最近日电费 - 昨日用电量 传感器额外参数（每月用量、每日用量） [![](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/sensor_attr.png)](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/sensor_attr.png) 参数设置 [![](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_params.png)](https://raw.githubusercontent.com/CubicPill/china_southern_power_grid_stat/master/img/setup_params.png) ### 数据更新策略 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E6%95%B0%E6%8D%AE%E6%9B%B4%E6%96%B0%E7%AD%96%E7%95%A5) 由于上月数据和去年数据在生成之后一般不会发生变化，因此对于上月累计用电量、上月每日用电量、上年度累计用电量、上年度每月用电量，数据更新间隔将会与一般更新间隔有所不同。 具体更新策略如下： 对于上月数据，在每月前3天（1~3日）将会跟随一般更新间隔更新（默认为4小时），其余时间将会停止更新，但数据依然可用。 对于去年数据，在每年一月的前7天（1月1日~1月7日）将会每天更新（在每天第一次触发更新时更新），其余时间将会停止更新，但数据依然可用。 如果需要强制刷新数据，重载集成即可。 ## 一些技术细节 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E4%B8%80%E4%BA%9B%E6%8A%80%E6%9C%AF%E7%BB%86%E8%8A%82) ### 登录接口加密原理 [](https://github.com/CubicPill/china_southern_power_grid_stat#%E7%99%BB%E5%BD%95%E6%8E%A5%E5%8F%A3%E5%8A%A0%E5%AF%86%E5%8E%9F%E7%90%86) 登录接口的请求数据和返回数据都经过加密，其中请求数据经过两层加密：整个请求数据的`AES`加密和密码字段的`RSA` 公钥加密（密钥、公钥具体值见代码）。 加密前的请求数据结构如下： { "areaCode": "xxx", "acctId": "xxx", "logonChan": "xxx", "credType": "xxx", "credentials": "xxx" // <- encrypted with RSA } 返回数据同样经过`AES`加密，密钥与请求数据相同。但返回值其中暂时不包含有用信息，验证状态码正常后可以直接忽略内容。 ### Web端接口和App端接口 [](https://github.com/CubicPill/china_southern_power_grid_stat#web%E7%AB%AF%E6%8E%A5%E5%8F%A3%E5%92%8Capp%E7%AB%AF%E6%8E%A5%E5%8F%A3) 对于南网API相关信息的提取主要通过Web端的抓包和JS代码获取。 之后因为登录态有效期问题，对App端抓包进行比对后切换到App端API。 经过验证，Web端（网上营业厅）和App端（南网在线）的API接口基本相同，差别主要在于： | | Web | App | | --- | --- | --- | | API路径 | ucs/ma/wt/ | ucs/ma/zt/ | | 支持登录方式 | 手机号+验证码（+密码），南网在线/微信/支付宝扫码 | 手机号+验证码（+密码），微信/支付宝跳转登录 | | token有效期 | 几小时（有待进一步确认） | 较长（有待进一步确认） | | Cookies | token包含在cookies中 | 无cookies | | 敏感信息（姓名、地址等） | 部分信息用“\*”隐去 | 有明文全文 | 另外在HTTP请求头上有细微的差别（如：UA），但实际上对于请求的返回结果没有影响。 ### API 实现库 [](https://github.com/CubicPill/china_southern_power_grid_stat#api-%E5%AE%9E%E7%8E%B0%E5%BA%93) 本项目代码中的[`csg_client/__init__.py`](https://github.com/CubicPill/china_southern_power_grid_stat/blob/master/custom_components/china_southern_power_grid_stat/csg_client/__init__.py) 是对南网在线 App API 的实现，可以独立于此项目单独使用。 详细使用方法见`csg_client_demo.py` ## Thank you [](https://github.com/CubicPill/china_southern_power_grid_stat#thank-you) - [lyylyylyylyy](https://github.com/lyylyylyylyy): PR [#30](https://github.com/CubicPill/china_southern_power_grid_stat/pull/30) 短信验证码登录支持 感谢[瀚思彼岸](https://bbs.hassbian.com/)论坛以下帖子作者的辛苦付出，排名不分先后 - [不折腾，超简单接入电费数据](https://bbs.hassbian.com/thread-18474-1-1.html) - [北京电费查询加强版](https://bbs.hassbian.com/thread-13820-1-1.html) - [电费插件（Node-Red流）-广东南方电网](https://bbs.hassbian.com/thread-17830-1-1.html) - [【抄作业】电费插件(NR流)-南网](https://bbs.hassbian.com/thread-18122-1-1.html) 自定义集成教程参考：[Building a Home Assistant Custom Component Part 1: Project Structure and Basics](https://aarongodfrey.dev/home%20automation/building_a_home_assistant_custom_component_part_1/)