165 lines
9.1 KiB
Markdown
165 lines
9.1 KiB
Markdown
|
---
|
||
|
|
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)
|
||
|
|
|
||
|
|
[](https://github.com/hacs/integration) [](https://github.com/CubicPill/china_southern_power_grid_stat/releases) [](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_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/sensor_attr.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/)
|