通过 Home Assistant 集成查看燃气账单、欠费、用气量、气价等信息，支持能源面板。
- 打开 HACS
- 点击 Integrations
- 点击右上角
?→ Custom repositories - 添加仓库地址:
https://github.com/C3H3-AI/ha-crcgas - 类别选择
Integration - 搜索并安装 "华润燃气"
cp -r crcgas ~/.homeassistant/custom_components/登录微信 华润燃气 小程序，从网络请求头中提取以下三个参数：
| 参数 | 说明 | 来源 |
|---|---|---|
refresh-token |
刷新令牌 | 请求头 |
bo-token |
运营令牌 | 请求头 |
wxCode |
微信授权码 | 请求头 |
- HA → 设置 → 设备与服务 → 添加集成
- 搜索 华润燃气
- 填写
refresh-token、bo-token、wxCode - 完成配置
| 传感器 | 说明 | 单位 | device_class |
|---|---|---|---|
| 欠费金额 | 当前欠费 | CNY | monetary |
| 燃气账户余额 | 账户余额 | CNY | monetary |
| 应收金额 | 本期应收金额 | CNY | monetary |
| 最近缴费金额 | 上次缴费金额 | CNY | monetary |
| 最近缴费时间 | 最近一次缴费时间 | - | - |
| 违约金 | 逾期违约金 | CNY | monetary |
| 违约金起算日期 | 违约金起算日期 | - | - |
| 账单金额 | 本期账单金额 | CNY | monetary |
| 账单月份 | 本期账单月份 | - | - |
| 预估燃气账单 | 按阶梯价计算 | CNY | monetary |
| 累计燃气费用 ⭐ | 历史账单+当前预估 | CNY | monetary |
| 结算状态 | 账单结算状态 | - | - |
| 传感器 | 说明 | 单位 | device_class |
|---|---|---|---|
| 本期表读数 | 燃气表当月读数 | m³ | gas |
| 燃气表总读数 ⭐ | 能源面板专用累计值 | m³ | gas |
| 本期用气量 | 本期用量 | m³ | gas |
| 图表月用气量 | 当月累计 | m³ | gas |
| 本期一阶梯用气量 | 第一阶梯用量 | m³ | gas |
| 本期二阶梯用气量 | 第二阶梯用量 | m³ | gas |
| 本期三阶梯用气量 ⭐ | 第三阶梯用量 | m³ | gas |
| 上期用气量 | 上期用量(参考) | m³ | gas |
| 上期表读数 | 上期燃气表读数 | m³ | gas |
| 年度月均用气量 | 12月平均 | m³ | gas |
| 一阶梯累计已用 | 第一阶梯年度累计 | m³ | gas |
| 二阶梯累计已用 | 第二阶梯年度累计 | m³ | gas |
| 三阶梯累计已用 ⭐ | 第三阶梯年度累计 | m³ | gas |
| 传感器 | 说明 | 单位 |
|---|---|---|
| 一阶梯气价 | 第一阶梯单价 | CNY/m³ |
| 二阶梯气价 | 第二阶梯单价 | CNY/m³ |
| 三阶梯气价 ⭐ | 第三阶梯单价 | CNY/m³ |
| 一阶梯剩余气量 | 第一阶梯余量 | m³ |
| 二阶梯剩余气量 | 第二阶梯余量 | m³ |
| 三阶梯剩余气量 ⭐ | 第三阶梯余量 | m³ |
| 一档总限额 | 第一阶梯年度上限 | m³ |
| 二档总限额 | 第二阶梯年度上限 | m³ |
| 传感器 | 说明 |
|---|---|
| 本期抄表时间 | 上次抄表日期 |
| 上期抄表时间 | 上期抄表日期 |
| 数据撤取时间 | 数据更新时间 |
| 集成状态 | 当前状态（正常/密钥过期等） |
| 年度缴费次数 | 当年缴费次数 |
| 传感器 | 说明 |
|---|---|
| 用气地址 | 用气地址 |
| 燃气公司 | 燃气公司名 |
| 燃气类型 | 天然气/液化气 |
| 购气方式 | 物联网表/IC卡 |
| 户名 | 燃气账户户名 |
| 手机号 | 绑定手机号 |
| 表号 | 燃气表编号 |
| 区域 | 所属区域 |
| 账户状态 | 账户状态 |
| 能源仪表盘燃气 | 能源面板专用（total_increasing） |
| 按钮 | 说明 |
|---|---|
| 刷新数据 | 手动触发数据更新 |
| 抓取历史记录 | 拉取所有历史账单并注入能源面板统计 |
- 保持上次有效值 — API 失败时读数不归零，月初未出账时累计值不变
_safe_float— 自动处理 API 千分位逗号数字，防止崩溃
- API 并行请求 — 4 个接口同时查询，刷新速度从 3-5 秒降至 1-2 秒
- 阶梯气价动态读取 — 从 API 实时获取阶梯上限，不硬编码（含三档0203）
能源面板支持用气量和燃气费用两个维度，推荐配置方式如下：
| 来源 | 说明 | 推荐 |
|---|---|---|
crcgas:monthly_gas_usage |
外部统计（37个月历史） | ✅ 主推 |
sensor.hua_run_ran_qi_ran_qi_zong_xiao_hao_liang |
传感器（total_increasing） |
亦可 |
配置步骤：
- HA → 设置 → 能源 → 燃气来源 → 添加燃气
- 选择
crcgas:monthly_gas_usage（统计来源） - 保存即可
crcgas:monthly_bill_amount 统计包含了每月的燃气费用数据，可配合用气量一起配置到能源面板中，让面板同时显示用量和费用的趋势。
配置步骤：
- 在能源面板的燃气来源中，添加费用统计
- 费用来源选择
crcgas:monthly_bill_amount - 用气量来源选择
crcgas:monthly_gas_usage
- 用气量: 2023年5月 ~ 至今（37个月），首次安装时自动注入
- 燃气费: 2023年5月 ~ 至今（37个月），同步注入
- 自动更新: 新账单出现后自动增量注入，无需重启
- 零外部依赖 — 使用 Python 内置 sqlite3 直写数据库，不依赖 SQLAlchemy
- Token 过期或网络异常时自动推送 HA 通知
- 恢复后通知自动消除
- 每小时主动刷新 Token，无需手动干预
- 过期前 5 分钟紧急刷新，避免服务中断
- 集成状态传感器实时显示当前 Token 状态
| 单位 | 说明 | 示例 |
|---|---|---|
| 小时 | 每 N 小时更新 | 1, 2, 3, 6, 12, 24 |
| 天 | 每天指定时间 | 每天 08:00 |
| 周 | 每周指定星期 | 每周一、三、五 |
| 月 | 每月指定日期 | 每月 1, 15 号 |
提供年度对比、阶梯进度、悬浮提示等功能。
添加：
- 设置 → 仪表盘 → 资源 → 添加资源
- URL:
/local/community/crcgas-card/crcgas-statistics-card.js - 类型: JavaScript 模块
- 编辑仪表盘 → + 添加卡片 → 搜索「华润燃气统计」
功能：
- 📊 双年对比折线/柱状图（m³ / ¥ 切换）
- 🖱️ 鼠标悬停浮标查看月度详情（当年 + 去年同期）
- 📈 Y 轴整数标注，全年 12 月显示
- 🏗️ 一阶阶梯进度条（年度限额对比）
- 🔄 年份翻页查看历史数据
- 🤖 自动检测实体前缀，无需手动配置
type: statistics-graph
entities:
- entity: crcgas:monthly_gas_usage
name: 月度用气量
- entity: crcgas:monthly_bill_amount
name: 月度燃气费
title: 华润燃气 年度趋势
days_to_show: 365
period: month
chart_type: line
stat_types:
- state
- change# 燃气欠费提醒
automation:
- alias: "燃气欠费提醒"
trigger:
- platform: state
entity_id: sensor.crcgas_arrears
condition:
- condition: numeric_state
entity_id: sensor.crcgas_arrears
above: 0
action:
- service: notify.notify
data:
message: "您有燃气欠费 ¥{{ states('sensor.crcgas_arrears') }}"- 检查三个参数是否填写正确
- Token 过期后集成会自动推送通知提醒
- 重新配置即可获取新 Token
- 检查网络连接
- 查看 HA 日志中的集成错误信息
- 尝试重启 HA Core
- 🔧 统计数据修复 — SQLite 注入改用
source=recorder，与 HA Recorder 共享同一套统计基线 - 🔧 旧数据清理 — 自动删除
source=crcgas残留数据，避免双源冲突 - 🔧 启动跳过优化 — 已有历史数据时不再重复删除注入，保障重启速度
- ✨ 三档用气量 + 三档气价 — 支持第三阶梯数据（gasStepList + consPrcInfo 0203）
- ✨ 上期表读数/上期抄表时间 — 显示上次抄表数据
- ✨ 结算状态 — 显示"全部结清"等结算信息
- ✨ 保持上次有效值 — API 失败时读数不归零，月初未出账时累计值不变
- ✨
_safe_float— 自动处理 API 千分位逗号数字，防止崩溃 - 🔧 能源面板修复 — 历史数据同时注入
燃气表总读数和累计燃气费用，解决费用曲线空白 - 🔧 集成状态中文显示 — 修复英文 key 问题（normal → 正常）
- 📊 传感器总数 28 → 34 — 新增 6 个传感器
- 🐛 修复
datetime变量作用域崩溃 — 内嵌 import 导致UnboundLocalError，全部传感器不可用 - 🐛 修复启动时统计数据被覆盖 —
_import_history_statistics中last_ts未定义，从0重新累加 - ✨ 新账单自动增量注入 — 检测到新
applicationNo自动存存储 + 注入统计 - ✨ 账单自动保存到历史存储 — 每次刷新检测新账单，即时保存
- 🔧 传感器名称修复 — 烃气讳公司→燃气公司、烃气类型→燃气类型、上期表観数→上期表读数
- 🔧 累计燃气费用 state_class 修复 —
total_increasing→total（与 monetary 兼容） - 📊 README 更新 — 传感器表格对齐实际名称、能源面板配置说明
- 🐛 修复浮窗负值 — 工具提示用
Math.max(0, ...)防止显示负数 - 💄 标签优化 — 汇总改为"本年用气量""去年同期用气量"
- 🏷️ 期次显示 — 最近一期用气/费用现在显示月份 (如"5月")，不再显示完整时间戳
- 🎨 crcgas-statistics-card 圆点优化 — 折线图数据点缩小为实心 (r3.5)，去白边更清爽
- ✨ crcgas-statistics-card v4.0 通用版重构
- 自动检测 entity_prefix，无需手动配置
- 柱状图/折线图切换，Y轴整数标注
- 鼠标悬停浮动提示（双年数据）
- 一阶阶梯进度条（年度限额对比）
- 2026年同比数据展示
- ✨ 新增传感器 — 一档总限额/二档总限额
- 🐛 修复能源面板负数问题 — 账单未出时总表读数和总费用不再跌为 0，保持上次值不变
- ✨ 燃气表历史累计传感器 — 专为能源面板设计，显示完整历史趋势
- ✨ SQLite 直写统计注入 — 零外部依赖，Python 内置 sqlite3 直写数据库
- ✨ 一键抓取+注入 — 按钮触发时自动删除旧统计并写入历史完整累计数据
- ✨ 启动安全 —
only_missing模式，已有统计时跳过，不删除历史数据 - 🐛 修复 SQLAlchemy 兼容性问题 — HA 2026.6.4 不再依赖 recorder 引擎
- 🐛 修复启动时数据丢失 — 避免重启时误删已注入的历史统计
- ✨ API 并行请求 — 4 个接口同时查询，刷新 1-2 秒
- ✨ 阶梯气价动态读取 — 从 API 实时获取，不硬编码
- ✨ device_class/state_class — 传感器正确分类，支持能源面板
- ✨ 燃气表总读数 — 累计传感器，可直接接入 HA 能源面板
- ✨ 历史数据导入统计系统 — 月度用气量/费用趋势图
- ✨ 集成异常通知 — Token 过期/网络异常自动推送通知
- ✨ 集成状态中文显示 — 正常/密钥过期/网络异常等
- ✨ 精度控制 — 金额固定显示 2 位小数
- 🐛 余额修复 — 获取失败返回不可用，不误报为 0
- 🔧 修复 Token 刷新逻辑：每小时无条件刷新 + 剩余<5分钟紧急刷新
- ✨ 新增紧急刷新定时器（每1分钟检查）
- ✨ 新增独立 Token 刷新定时器，每小时主动检查并刷新 Token
- 🔧 共享 API 实例，Token 刷新状态在
__init__.py和sensor.py间同步 - 🔧 集成启动时立即执行一次 Token 检查
- ✨ 首次启动自动抓取历史记录
- 🐛 修复：删除实体 async_update 避免刷屏
- 🐛 修复：按钮延迟加载 + 非阻塞首次刷新
- ✨ 预估燃气账单传感器
- ✨ native_value 统一返回 float
- ✨ 自动保存用气历史
如果这个集成帮到了你，欢迎请我喝杯咖啡 ☕
| 微信支付 | 支付宝 |
|---|---|
 |
 |