From 11ef141bd70a1c00e1c004b376085fa92959f144 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=8D=E6=B1=82=E5=9C=A3=E5=89=91?= Date: Wed, 19 Nov 2025 10:43:47 +0800 Subject: [PATCH] refactor: remove outdated documentation files and enhance README for JackeryHome integration - Deleted obsolete files including CHANGELOG.md, DATA_FORMAT.md, HACS_PUBLISHING_GUIDE.md, MQTT_FIX_SUMMARY.md, TROUBLESHOOTING.md, and test_mqtt.py to streamline the project. - Updated README.md to include detailed architecture design, sensor value processing logic, and improved MQTT topic format explanations. - Enhanced clarity on the integration's coordinator pattern and data flow, ensuring users have comprehensive guidance on setup and usage. --- CHANGELOG.md | 51 ------ DATA_FORMAT.md | 145 ----------------- HACS_PUBLISHING_GUIDE.md | 202 ------------------------ MQTT_FIX_SUMMARY.md | 195 ----------------------- README.md | 75 ++++++--- TROUBLESHOOTING.md | 139 ---------------- custom_components/JackeryHome/README.md | 142 +++++++++++++++-- test_mqtt.py | 97 ------------ 8 files changed, 190 insertions(+), 856 deletions(-) delete mode 100644 CHANGELOG.md delete mode 100644 DATA_FORMAT.md delete mode 100644 HACS_PUBLISHING_GUIDE.md delete mode 100644 MQTT_FIX_SUMMARY.md delete mode 100644 TROUBLESHOOTING.md delete mode 100644 test_mqtt.py diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 7fa1f1d..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,51 +0,0 @@ -# Changelog - -所有重要的项目更改都将记录在此文件中。 - -格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， -项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 - -## [未发布] - -### 计划中 -- 增加更多能源监控功能 -- 支持更多设备类型 - -## [1.1.1] - 2024-12-19 - -### 新增 -- 在数据传输示例中增加能源数据模拟发送功能 -- 支持所有能源类型的累积数据：太阳能、家庭用电、电网购买/出售、电池充放电 -- 能源数据基准从1kWh开始，每次根据功率值增加0.1kWh - -### 改进 -- 简化传感器处理逻辑，直接显示累积值而不进行复杂计算 -- 优化数据传输格式，包含完整的功率和能源数据 - -### 修复 -- 修复能源传感器数据处理逻辑 -- 移除不必要的能源累积计算代码 - -## [1.1.0] - 2024-12-18 - -### 新增 -- 完整的能源监控传感器支持 -- MQTT数据传输示例 -- 支持功率和能源两种数据类型 -- 电池状态监控 - -### 改进 -- 优化传感器配置 -- 改进错误处理 - -## [1.0.6] - 2024-12-17 - -### 修复 -- 修复传感器初始化问题 - -## [1.0.5] - 2024-12-16 - -### 新增 -- 初始版本发布 -- 基础传感器功能 -- MQTT集成 diff --git a/DATA_FORMAT.md b/DATA_FORMAT.md deleted file mode 100644 index d51ac94..0000000 --- a/DATA_FORMAT.md +++ /dev/null @@ -1,145 +0,0 @@ -# 数据传输格式说明 - -## 概述 - -Energy Monitor 系统使用 MQTT 协议进行数据传输，包含两个主要的通信方向： - -1. **Home Assistant → 设备**: 发送数据获取请求 -2. **设备 → Home Assistant**: 返回设备数据 - -## 数据流图 - -``` -Home Assistant 集成 - │ - ▼ - /data/data-get (请求) - │ - ▼ - 设备端处理 - │ - ▼ - /device/data (响应) - │ - ▼ - Home Assistant 集成 - │ - ▼ - 更新传感器状态 -``` - -## 数据格式 - -### 1. 数据获取请求 - -**主题**: `/data/data-get` -**格式**: 纯文本 -**内容**: `get_data` -**频率**: 每秒5次（每0.2秒一次） - -```bash -主题: /data/data-get -内容: get_data -``` - -### 2. 设备数据响应 - -**主题**: `/device/data` -**格式**: JSON -**编码**: UTF-8 - -#### 完整数据格式 - -```json -{ - "solar_power": 1500.5, - "home_power": 1200.0, - "grid_import": 300.0, - "grid_export": 0.0, - "battery_charge": 200.0, - "battery_discharge": 0.0, - "battery_soc": 85.5 -} -``` - -#### 字段说明 - -| 字段名 | 类型 | 单位 | 说明 | -|--------|------|------|------| -| `solar_power` | float | W | 太阳能发电功率 | -| `home_power` | float | W | 家庭用电功率 | -| `grid_import` | float | W | 从电网购买功率 | -| `grid_export` | float | W | 向电网出售功率 | -| `battery_charge` | float | W | 电池充电功率 | -| `battery_discharge` | float | W | 电池放电功率 | -| `battery_soc` | float | % | 电池电量百分比 | - -## 使用示例 - -### Python 设备端示例 - -```python -import json -import paho.mqtt.client as mqtt - -def on_message(client, userdata, msg): - if msg.topic == "/data/data-get": - # 收到数据请求，发送设备数据 - data = { - "solar_power": 1500.5, - "home_power": 1200.0, - "grid_import": 300.0, - "grid_export": 0.0, - "battery_charge": 200.0, - "battery_discharge": 0.0, - "battery_soc": 85.5 - } - - # 发送到 /device/data 主题 - client.publish("/device/data", json.dumps(data)) - -# 设置 MQTT 客户端 -client = mqtt.Client() -client.on_message = on_message -client.connect("192.168.0.101", 1883, 60) -client.subscribe("/data/data-get") -client.loop_forever() -``` - -### 测试命令 - -使用 mosquitto 客户端测试： - -```bash -# 监听数据获取请求 -mosquitto_sub -h 192.168.0.101 -t "/data/data-get" - -# 监听设备数据 -mosquitto_sub -h 192.168.0.101 -t "/device/data" - -# 手动发送数据请求 -mosquitto_pub -h 192.168.0.101 -t "/data/data-get" -m "get_data" - -# 手动发送设备数据 -mosquitto_pub -h 192.168.0.101 -t "/device/data" -m '{"solar_power": 1500.5, "home_power": 1200.0}' -``` - -## 注意事项 - -1. **JSON 格式**: 设备数据必须是有效的 JSON 格式 -2. **数值类型**: 所有功率值应为数字类型（int 或 float） -3. **电量范围**: battery_soc 应在 0-100 之间 -4. **功率单位**: 所有功率值单位为瓦特 (W) -5. **实时性**: 数据应尽可能实时更新 -6. **错误处理**: 设备端应处理数据请求失败的情况 - -## 数据验证 - -Home Assistant 集成会验证接收到的数据： - -- JSON 格式正确性 -- 必需字段存在性 -- 数值类型正确性 -- 数值范围合理性 - -如果数据格式不正确，会在日志中记录警告信息。 diff --git a/HACS_PUBLISHING_GUIDE.md b/HACS_PUBLISHING_GUIDE.md deleted file mode 100644 index bddd444..0000000 --- a/HACS_PUBLISHING_GUIDE.md +++ /dev/null @@ -1,202 +0,0 @@ -# HACS 发布指南 - -本指南将帮助您将 JackeryHome 集成发布到 HACS (Home Assistant Community Store)。 - -## 发布前检查清单 - -### 1. 项目结构检查 -确保项目结构符合 HACS 要求： -``` -jackery_home/ -├── hacs.json # HACS 配置文件 -├── README.md # 项目主文档 -├── LICENSE # 许可证文件 -└── custom_components/ - └── JackeryHome/ - ├── __init__.py # 集成入口 - ├── manifest.json # 集成元数据 - ├── config_flow.py # 配置流程 - ├── sensor.py # 传感器实现 - ├── strings.json # 本地化字符串 - ├── translations/ # 翻译文件 - │ └── zh-Hans.json - └── README.md # 集成技术文档 -``` - -### 2. 配置文件检查 - -#### hacs.json -```json -{ - "name": "JackeryHome", - "content_in_root": false, - "render_readme": true, - "domains": [ - "jackery_home" - ], - "iot_class": "Local Push", - "homeassistant": "2024.1.0" -} -``` - -#### manifest.json -```json -{ - "domain": "jackery_home", - "name": "JackeryHome", - "codeowners": [ - "@suyulin" - ], - "config_flow": true, - "dependencies": [ - "mqtt" - ], - "documentation": "https://github.com/suyulin/jackery_home", - "issue_tracker": "https://github.com/suyulin/jackery_home/issues", - "iot_class": "local_push", - "requirements": [ - "paho-mqtt>=1.6.0" - ], - "version": "1.0.0" -} -``` - -### 3. 代码质量检查 -- [ ] 所有 Python 文件符合 PEP 8 规范 -- [ ] 没有语法错误 -- [ ] 所有导入都正确 -- [ ] 日志记录适当 -- [ ] 错误处理完善 - -## 发布步骤 - -### 步骤 1: 准备发布 -使用提供的发布脚本： -```bash -./prepare_release.sh -``` - -或手动执行以下步骤： - -1. **检查未提交的更改** - ```bash - git status - ``` - -2. **提交所有更改** - ```bash - git add . - git commit -m "准备发布到 HACS" - ``` - -3. **更新版本号** - 编辑 `custom_components/JackeryHome/manifest.json` 中的版本号 - -4. **提交版本更新** - ```bash - git add custom_components/JackeryHome/manifest.json - git commit -m "版本更新至 v1.0.0" - ``` - -### 步骤 2: 推送到 GitHub -```bash -git push origin main -``` - -### 步骤 3: 创建 Git Tag -```bash -git tag -a v1.0.0 -m "Release v1.0.0" -git push origin v1.0.0 -``` - -### 步骤 4: 创建 GitHub Release - -#### 方法一：使用 GitHub Web 界面 -1. 访问 GitHub 仓库 -2. 点击 "Releases" → "Create a new release" -3. 选择刚创建的 tag (v1.0.0) -4. 填写 Release 标题和描述 -5. 点击 "Publish release" - -#### 方法二：使用 GitHub CLI -```bash -gh release create v1.0.0 --title "v1.0.0" --notes "JackeryHome 集成首次发布" -``` - -### 步骤 5: 验证发布 -1. 检查 GitHub Release 是否创建成功 -2. 验证下载链接是否正常 -3. 测试从 HACS 安装是否正常 - -## 用户安装指南 - -### 通过 HACS 安装 -1. **添加自定义存储库** - - 打开 HACS - - 点击右上角三个点 → "自定义存储库" - - 添加仓库 URL：`https://github.com/suyulin/jackery_home` - - 类别选择：`Integration` - - 点击"添加" - -2. **安装集成** - - 在 HACS 中搜索 "JackeryHome" - - 点击"安装" - - 重启 Home Assistant - -3. **配置集成** - - 进入 **设置** → **设备与服务** → **添加集成** - - 搜索 "JackeryHome" - - 按照配置向导完成设置 - -## 常见问题 - -### Q: HACS 中找不到我的集成？ -A: 检查以下几点： -- 确保 `hacs.json` 文件存在且格式正确 -- 确保 `manifest.json` 中的 `domain` 与 `hacs.json` 中的 `domains` 匹配 -- 确保 GitHub Release 已创建 -- 等待 HACS 缓存更新（通常需要几分钟） - -### Q: 安装后集成无法加载？ -A: 检查以下几点： -- 查看 Home Assistant 日志中的错误信息 -- 确保所有依赖项已安装 -- 检查 `manifest.json` 中的 `requirements` 字段 -- 确保代码没有语法错误 - -### Q: 如何更新集成？ -A: 更新流程： -1. 修改代码 -2. 更新 `manifest.json` 中的版本号 -3. 提交更改并推送到 GitHub -4. 创建新的 Git tag 和 Release -5. 用户在 HACS 中会看到更新通知 - -## 最佳实践 - -1. **版本管理** - - 使用语义化版本控制 (SemVer) - - 每次发布都要更新版本号 - - 在 Release 中详细描述更改内容 - -2. **文档维护** - - 保持 README.md 更新 - - 提供清晰的安装和使用说明 - - 包含故障排除指南 - -3. **代码质量** - - 定期检查代码质量 - - 添加适当的错误处理 - - 使用类型提示 - -4. **用户支持** - - 及时回复 Issues - - 提供清晰的错误信息 - - 保持文档更新 - -## 相关链接 - -- [HACS 官方文档](https://hacs.xyz/) -- [Home Assistant 开发文档](https://developers.home-assistant.io/) -- [HACS 集成要求](https://hacs.xyz/docs/publish/requirements) -- [GitHub Actions 示例](https://github.com/hacs/integration/tree/main/.github/workflows) diff --git a/MQTT_FIX_SUMMARY.md b/MQTT_FIX_SUMMARY.md deleted file mode 100644 index c7ce3f5..0000000 --- a/MQTT_FIX_SUMMARY.md +++ /dev/null @@ -1,195 +0,0 @@ -# MQTT 连接问题修复摘要 - -## 问题描述 - -用户遇到 MQTT 连接错误： -``` -[Errno 113] Host is unreachable -WARNING (MainThread) [custom_components.jackery_home.sensor] MQTT not ready: Error talking -``` - -## 根本原因 - -JackeryHome 集成依赖 Home Assistant 的内置 MQTT 组件，但存在以下问题： - -1. **配置流程误导**：配置界面收集了 `mqtt_broker` 和 `mqtt_port` 参数，但这些参数从未被使用 -2. **缺少依赖检查**：没有验证 MQTT 集成是否已配置和可用 -3. **错误提示不明确**：当 MQTT 不可用时，错误消息不够清晰 - -## 实施的修复 - -### 1. 更新 `__init__.py` - 添加 MQTT 可用性检查 - -**变更**： -- 导入 `homeassistant.components.mqtt` 模块 -- 在 `async_setup_entry` 中添加 `mqtt.async_wait_for_mqtt_client()` 检查 -- 如果 MQTT 不可用，返回 `False` 并记录清晰的错误消息 - -**代码**： -```python -# 检查 MQTT 集成是否已配置和可用 -if not await mqtt.async_wait_for_mqtt_client(hass): - _LOGGER.error( - "MQTT integration is not available or not configured. " - "Please set up the MQTT integration first: " - "Settings -> Devices & Services -> Add Integration -> MQTT" - ) - return False -``` - -### 2. 更新 `config_flow.py` - 简化配置并验证 MQTT - -**变更**： -- 移除 `mqtt_broker` 和 `mqtt_port` 配置参数（不再需要） -- 保留 `topic_prefix` 参数（可选配置） -- 在配置时验证 MQTT 集成是否可用 -- 添加 `mqtt_not_configured` 错误处理 - -**更新的配置架构**： -```python -DATA_SCHEMA = vol.Schema( - { - vol.Optional( - "topic_prefix", - default="homeassistant/sensor" - ): str, - } -) -``` - -### 3. 更新 `sensor.py` - 改进错误处理 - -**变更**： -- 在 `async_start()` 中添加 try-except 块捕获订阅错误 -- 改进 MQTT 发布失败时的错误消息 -- 提供更清晰的故障排除指导 - -**改进的错误消息**： -```python -except Exception as mqtt_error: - _LOGGER.warning( - f"MQTT publish failed: {mqtt_error}. " - f"Please check MQTT broker connection. " - f"Will retry in {REQUEST_INTERVAL} seconds..." - ) -``` - -### 4. 更新翻译文件 - -**`strings.json` 和 `zh-Hans.json`**： -- 更新配置描述，说明需要先配置 MQTT 集成 -- 移除 `mqtt_broker` 和 `mqtt_port` 相关文本 -- 添加 `mqtt_not_configured` 错误消息 -- 更新 `single_instance_allowed` 错误消息 - -### 5. 创建故障排除文档 - -**新建 `TROUBLESHOOTING.md`**： -- 详细说明 MQTT 连接问题的原因和解决方案 -- 提供 Mosquitto Add-on 和外部 broker 的配置指南 -- 包含调试步骤和常用命令 -- 说明如何启用详细日志 - -### 6. 更新集成文档 - -**更新 `custom_components/JackeryHome/README.md`**： -- 添加"前置要求"章节，强调 MQTT 依赖 -- 更新安装步骤，包含 HACS 和手动安装方法 -- 更新 MQTT 主题格式说明，反映实际使用的主题 -- 扩展故障排除章节，添加常见问题解决方案 -- 添加调试日志配置示例 - -## manifest.json 中的依赖声明 - -确认 `manifest.json` 中已正确声明 MQTT 依赖： -```json -{ - "dependencies": [ - "mqtt" - ] -} -``` - -这确保 Home Assistant 在加载 JackeryHome 之前先加载 MQTT 组件。 - -## 用户需要采取的操作 - -### 立即操作（修复当前问题）： - -1. **配置 MQTT 集成**： - - 进入 Home Assistant：**设置** → **设备与服务** - - 点击 **添加集成**，搜索 **MQTT** - - 输入正确的 MQTT broker 地址和端口 - - 如果使用 Mosquitto Add-on，broker 地址通常是 `core-mosquitto` 或 `localhost` - -2. **验证 MQTT 连接**： - - 在 MQTT 集成中检查连接状态 - - 应显示"已连接"状态 - -3. **重新加载 JackeryHome 集成**： - - 进入 **设置** → **设备与服务** - - 找到 JackeryHome 集成 - - 点击"重新加载" - -### 更新后操作： - -1. 更新 JackeryHome 集成到最新版本 -2. 如果之前配置过 `mqtt_broker` 和 `mqtt_port`，可以删除这些配置（它们不再使用） -3. 确保 MQTT 集成已正确配置 - -## 技术改进 - -1. **依赖检查**：明确验证 MQTT 组件可用性 -2. **错误处理**：更好的异常捕获和错误消息 -3. **用户体验**：清晰的配置指导和错误提示 -4. **文档完善**：详细的故障排除指南和使用说明 - -## 测试建议 - -### 测试场景 1：MQTT 未配置 - -1. 确保 MQTT 集成未配置 -2. 尝试添加 JackeryHome 集成 -3. **预期结果**：显示"MQTT 集成未配置"错误 - -### 测试场景 2：MQTT 配置但不可达 - -1. 配置 MQTT 集成但使用错误的 broker 地址 -2. 添加 JackeryHome 集成 -3. **预期结果**：集成显示错误，日志中有清晰的错误消息 - -### 测试场景 3：正常工作 - -1. 正确配置 MQTT 集成并连接 -2. 添加 JackeryHome 集成 -3. 运行数据模拟器 -4. **预期结果**：传感器正常创建并显示数据 - -## 向后兼容性 - -- 移除了未使用的 `mqtt_broker` 和 `mqtt_port` 配置选项 -- 保留了 `topic_prefix` 配置选项 -- 现有安装需要确保 MQTT 集成已配置 - -## 相关文件 - -修改的文件： -- `custom_components/JackeryHome/__init__.py` -- `custom_components/JackeryHome/config_flow.py` -- `custom_components/JackeryHome/sensor.py` -- `custom_components/JackeryHome/strings.json` -- `custom_components/JackeryHome/translations/zh-Hans.json` -- `custom_components/JackeryHome/README.md` - -新增的文件： -- `TROUBLESHOOTING.md` -- `MQTT_FIX_SUMMARY.md`（本文件） - -## 下一步 - -1. 测试修复是否解决用户的问题 -2. 根据用户反馈进一步优化 -3. 考虑添加 MQTT 连接状态传感器 -4. 更新 CHANGELOG.md -5. 准备新版本发布 - diff --git a/README.md b/README.md index 4b3a767..13cef35 100644 --- a/README.md +++ b/README.md @@ -20,17 +20,36 @@ 1. **MQTT 模拟器** (`main.py`) - 模拟发送能源监控数据到 MQTT broker 2. **Home Assistant 自定义集成** (`custom_components/JackeryHome/`) - 接收 MQTT 数据并创建传感器实体 +### 集成架构 + +集成采用**协调器模式**（Coordinator Pattern）： +- 所有传感器共享一个 `JackeryDataCoordinator` 实例 +- 统一管理 MQTT 订阅和数据请求 +- 每 5 秒发送一次包含所有传感器 `meter_sn` 的数据请求 +- 自动解析响应并分发给对应的传感器实体 + ## 传感器列表 本项目会创建以下传感器： -- `sensor.solar_power`: 太阳能发电功率（W） -- `sensor.home_power`: 家庭用电功率（W） -- `sensor.grid_import`: 从电网购买功率（W） -- `sensor.grid_export`: 向电网出售功率（W） -- `sensor.battery_charge`: 电池充电功率（W） -- `sensor.battery_discharge`: 电池放电功率（W） -- `sensor.battery_soc`: 电池电量百分比（%） +### 功率传感器（实时监测） + +- `sensor.jackeryhome_solar_power`: 太阳能发电功率（W） +- `sensor.jackeryhome_home_power`: 家庭用电功率（W） +- `sensor.jackeryhome_grid_import`: 从电网购买功率（W） +- `sensor.jackeryhome_grid_export`: 向电网出售功率（W） +- `sensor.jackeryhome_battery_charge`: 电池充电功率（W） +- `sensor.jackeryhome_battery_discharge`: 电池放电功率（W） +- `sensor.jackeryhome_battery_state_of_charge`: 电池电量百分比（%） + +### 能源传感器（用于能源仪表板） + +- `sensor.jackeryhome_solar_energy`: 太阳能发电总量（kWh） +- `sensor.jackeryhome_home_energy`: 家庭用电总量（kWh） +- `sensor.jackeryhome_grid_import_energy`: 电网购买总量（kWh） +- `sensor.jackeryhome_grid_export_energy`: 电网出售总量（kWh） +- `sensor.jackeryhome_battery_charge_energy`: 电池充电总量（kWh） +- `sensor.jackeryhome_battery_discharge_energy`: 电池放电总量（kWh） ## 安装 @@ -102,7 +121,8 @@ 3. **查看传感器数据** - 进入 **开发者工具** → **状态** - - 搜索 "solar_power"、"home_power" 等传感器 + - 搜索 "jackeryhome" 或传感器名称（如 "Solar Power"、"Home Power" 等） + - 实体 ID 格式：`sensor.jackeryhome_{sensor_id}` ## Energy Flow Card Plus 配置 @@ -137,24 +157,42 @@ type: custom:energy-flow-card-plus entities: solar: - entity: sensor.solar_power + entity: sensor.jackeryhome_solar_power name: 太阳能 + icon: mdi:solar-power grid: entity: - consumption: sensor.grid_import # 从电网购买 - production: sensor.grid_export # 向电网出售 + consumption: sensor.jackeryhome_grid_import # 从电网购买 + production: sensor.jackeryhome_grid_export # 向电网出售 name: 电网 + icon: mdi:transmission-tower battery: entity: - consumption: sensor.battery_charge # 充电 - production: sensor.battery_discharge # 放电 - state_of_charge: sensor.battery_soc + consumption: sensor.jackeryhome_battery_charge # 充电 + production: sensor.jackeryhome_battery_discharge # 放电 + state_of_charge: sensor.jackeryhome_battery_state_of_charge name: 电池 + icon: mdi:battery home: - entity: sensor.home_power + entity: sensor.jackeryhome_home_power name: 家庭用电 + icon: mdi:home-lightning-bolt +display_zero_lines: + mode: show + transparency: 50 + grey_color: + - 189 + - 189 + - 189 +w_decimals: 0 +kw_decimals: 2 +color_icons: true +animation_speed: 10 +energy_date_selection: false ``` +**注意**：实体 ID 格式为 `sensor.jackeryhome_{sensor_id}`，其中 `{sensor_id}` 对应传感器 ID（如 `solar_power`、`grid_import` 等）。 + 更多配置选项请查看 `energy_flow_card_config.yaml` 文件。 ## 项目文件说明 @@ -164,11 +202,11 @@ entities: - `custom_components/JackeryHome/`: Home Assistant 自定义集成 - `__init__.py`: 集成入口 - `manifest.json`: 集成元数据 - - `sensor.py`: 传感器平台实现 + - `sensor.py`: 传感器平台实现（包含协调器模式和所有传感器逻辑） - `config_flow.py`: UI 配置流程 - `strings.json`: 本地化字符串 - `translations/zh-Hans.json`: 中文翻译 - - `README.md`: 集成技术文档 + - `README.md`: 集成技术文档（包含架构设计、MQTT 协议格式等） ### 文档和工具 - `INTEGRATION_GUIDE.md`: 详细的集成使用指南 @@ -193,8 +231,9 @@ entities: - 确保 Home Assistant 已配置好 MQTT 集成 - MQTT Broker 需要在运行此脚本之前启动 -- 传感器会每 5 秒更新一次数据 +- 集成会每 5 秒主动请求一次数据（所有传感器共享同一个请求） - 数据为模拟值，用于演示目的 +- 集成会自动从 LWT 消息获取设备序列号，无需手动配置 ## 文档 diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md deleted file mode 100644 index 90cdbf1..0000000 --- a/TROUBLESHOOTING.md +++ /dev/null @@ -1,139 +0,0 @@ -# JackeryHome 故障排除指南 - -## MQTT 连接问题 - -### 问题：Host is unreachable 错误 - -如果您在 Home Assistant 日志中看到以下错误： - -``` -ERROR (MainThread) [homeassistant.components.mqtt.client] Error re-connecting to MQTT server due to exception: [Errno 113] Host is unreachable -WARNING (MainThread) [custom_components.jackery_home.sensor] MQTT not ready: Error talking -``` - -**原因：** -JackeryHome 集成依赖于 Home Assistant 的内置 MQTT 集成。该错误表明 Home Assistant 无法连接到配置的 MQTT broker。 - -**解决方案：** - -#### 1. 确认已安装并配置 MQTT 集成 - -1. 进入 Home Assistant：**设置** → **设备与服务** -2. 检查是否已添加 **MQTT** 集成 -3. 如果没有，点击 **添加集成**，搜索并添加 **MQTT** - -#### 2. 配置正确的 MQTT Broker 地址 - -在 MQTT 集成配置中，确保： - -- **Broker 地址**：填写您的 MQTT broker 的 IP 地址或主机名 - - 如果使用 Mosquitto Add-on：通常是 `localhost` 或 `core-mosquitto` - - 如果使用独立 MQTT broker：填写其 IP 地址（例如 `192.168.1.100`） -- **端口**：默认为 `1883`（或 TLS 加密使用 `8883`） -- **用户名/密码**：如果 broker 需要认证，请填写 - -#### 3. 检查网络连接 - -确保 Home Assistant 可以访问 MQTT broker： - -```bash -# 在 Home Assistant 容器/主机中测试连接 -ping -telnet 1883 -``` - -#### 4. 检查 MQTT Broker 是否运行 - -如果使用 Mosquitto Add-on： -1. 进入 **设置** → **加载项** -2. 找到 **Mosquitto broker** -3. 确认状态为 **已启动** -4. 查看日志确认没有错误 - -#### 5. 重新配置 JackeryHome 集成 - -在 MQTT 集成正确配置后： -1. 进入 **设置** → **设备与服务** -2. 找到 **JackeryHome** 集成 -3. 如果仍有问题，尝试删除并重新添加该集成 - -### 问题：MQTT publish failed - -如果看到 "MQTT publish failed" 错误，但 MQTT 集成已配置： - -1. **重启 MQTT broker** -2. **重启 Home Assistant** -3. 检查 MQTT broker 日志中是否有连接错误 -4. 确认 MQTT broker 没有达到连接限制 - -### 问题：数据未更新 - -如果传感器显示"不可用"或数据不更新： - -1. **检查 MQTT 主题**：确认设备正在向正确的主题发布数据 - - LWT 主题：`v1/iot_gw/gw_lwt` - - 数据主题：`v1/iot_gw/gw/data` - -2. **使用 MQTT Explorer 监控**： - - 安装 MQTT Explorer（桌面应用） - - 连接到您的 broker - - 订阅 `v1/iot_gw/#` 查看是否有数据 - -3. **检查设备序列号**： - - 查看传感器的属性，确认 `device_sn` 是否正确 - - 确认设备已上线并发送了 LWT 消息 - -## 常见配置问题 - -### 使用 Mosquitto Add-on - -推荐配置： -- **Broker**: `core-mosquitto` 或 `localhost` -- **Port**: `1883` - -### 使用外部 MQTT Broker - -1. 确保防火墙允许 1883 端口 -2. 如果使用 Docker，确保网络配置正确 -3. 考虑使用 TLS 加密连接（端口 8883） - -## 调试步骤 - -### 启用详细日志 - -在 `configuration.yaml` 中添加： - -```yaml -logger: - default: info - logs: - custom_components.jackery_home: debug - homeassistant.components.mqtt: debug -``` - -重启 Home Assistant 后，日志将显示更详细的 MQTT 交互信息。 - -### 手动测试 MQTT 连接 - -使用 `mosquitto_pub` 和 `mosquitto_sub` 工具测试： - -```bash -# 订阅主题 -mosquitto_sub -h -t "v1/iot_gw/#" -v - -# 发布测试消息 -mosquitto_pub -h -t "v1/iot_gw/test" -m "test message" -``` - -## 获取帮助 - -如果问题仍未解决，请在 GitHub 上提交 issue，并提供： - -1. Home Assistant 版本 -2. JackeryHome 集成版本 -3. MQTT broker 类型和版本 -4. 完整的错误日志（启用调试日志后） -5. MQTT 集成配置（隐藏敏感信息） - -GitHub 仓库：https://github.com/your-repo/jackery_home - diff --git a/custom_components/JackeryHome/README.md b/custom_components/JackeryHome/README.md index 9598b9e..75c40fe 100644 --- a/custom_components/JackeryHome/README.md +++ b/custom_components/JackeryHome/README.md @@ -4,7 +4,9 @@ ## 功能特性 -该集成会自动创建以下传感器： +该集成采用**协调器模式**（Coordinator Pattern），所有传感器共享一个 `JackeryDataCoordinator` 实例，统一管理 MQTT 订阅和数据请求，提高效率并减少资源占用。 + +### 功率传感器（实时监测） - **Solar Power** (太阳能发电功率) - 单位：W - **Home Power** (家庭负载功率) - 单位：W @@ -14,6 +16,15 @@ - **Battery Discharge** (电池放电功率) - 单位：W - **Battery State of Charge** (电池电量) - 单位：% +### 能源传感器（用于能源仪表板） + +- **Solar Energy** (太阳能发电总量) - 单位：kWh +- **Home Energy** (家庭用电总量) - 单位：kWh +- **Grid Import Energy** (电网购买总量) - 单位：kWh +- **Grid Export Energy** (电网出售总量) - 单位：kWh +- **Battery Charge Energy** (电池充电总量) - 单位：kWh +- **Battery Discharge Energy** (电池放电总量) - 单位：kWh + ## 前置要求 ⚠️ **重要：本集成依赖 Home Assistant 的 MQTT 集成** @@ -66,18 +77,90 @@ config/ 如果 MQTT 集成未配置或不可用，将显示错误提示。 +## 架构设计 + +### 协调器模式 + +集成使用 `JackeryDataCoordinator` 类统一管理所有传感器的数据获取： + +- **单一协调器实例**：所有传感器共享一个协调器，避免重复订阅和请求 +- **统一数据请求**：每 5 秒发送一次 `data_get` 请求，包含所有传感器的 `meter_sn` +- **自动分发数据**：协调器接收响应后，根据 `meter_sn` 自动分发给对应的传感器 +- **设备序列号管理**：通过 LWT 消息自动获取和更新设备序列号 + +### 数据流程 + +1. **启动阶段**： + - 协调器订阅 LWT 主题 (`v1/iot_gw/gw_lwt`) 获取设备序列号 + - 协调器订阅数据响应主题 (`v1/iot_gw/gw/data`) + - 启动定时任务，每 5 秒发送一次数据请求 + +2. **数据请求**： + - 协调器收集所有传感器的 `meter_sn` + - 构造包含所有 `meter_sn` 的 `data_get` 请求 + - 发送到 `v1/iot_gw/cloud/data` 主题 + +3. **数据处理**： + - 接收设备响应（JSON 格式） + - 解析 `meter_list` 中的 `[meter_sn, meter_value]` 数据 + - 根据 `meter_sn` 匹配对应的传感器实体 + - 调用传感器的 `_process_meter_value()` 处理特殊值（如正负分离） + - 更新传感器状态并通知 Home Assistant + ## MQTT 主题格式 集成会订阅以下 MQTT 主题来接收设备数据： - **LWT 主题**: `v1/iot_gw/gw_lwt` - 接收设备上线/离线状态和序列号 -- **数据主题**: `v1/iot_gw/gw/data` - 接收设备响应的传感器数据 + ```json + { + "gw_sn": "26392658575364" + } + ``` + +- **数据响应主题**: `v1/iot_gw/gw/data` - 接收设备响应的传感器数据 + ```json + { + "cmd": "data_get", + "info": { + "dev_list": [ + { + "dev_sn": "ems_26392658575364", + "meter_list": [ + ["1026001", 2500.0], + ["21171201", 1800.0], + ... + ] + } + ] + } + } + ``` 集成会定期向以下主题发送数据请求： - **请求主题**: `v1/iot_gw/cloud/data` - 发送 `data_get` 命令请求传感器数据 + ```json + { + "cmd": "data_get", + "gw_sn": "26392658575364", + "timestamp": "1234567890123", + "token": "5678", + "info": { + "dev_list": [ + { + "dev_sn": "ems_26392658575364", + "meter_list": ["1026001", "21171201", "16930817", ...] + } + ] + } + } + ``` -消息格式遵循 Jackery 设备的标准协议（JSON 格式），包含设备序列号、meter 列表等信息。 +### 数据请求间隔 + +- **默认间隔**：5 秒（`REQUEST_INTERVAL = 5`） +- 所有传感器共享同一个请求，减少 MQTT 消息数量 ## 与模拟器配合使用 @@ -95,8 +178,12 @@ config/ 配置完成后，你可以在以下位置查看传感器： -- **开发者工具** → **状态** → 搜索 "energy_monitor" -- 传感器实体 ID 格式：`sensor.solar_power`、`sensor.home_power` 等 +- **开发者工具** → **状态** → 搜索 "jackery" 或传感器名称 +- 传感器实体 ID 格式：`sensor.solar_power`、`sensor.home_power`、`sensor.solar_energy` 等 +- 每个传感器包含以下属性： + - `sensor_id`: 传感器内部标识 + - `meter_sn`: 对应的 meter 序列号 + - `device_sn`: 设备序列号（从 LWT 消息获取） ## 在 Lovelace 中使用 @@ -140,6 +227,9 @@ entities: 3. 使用 MQTT Explorer 监听 `v1/iot_gw/#` 主题查看消息 4. 查看 Home Assistant 日志：**设置** → **系统** → **日志** 5. 确认传感器属性中的 `device_sn` 是否正确 +6. 检查协调器是否已启动：日志中应看到 "Coordinator subscribed to LWT topic" 和 "Coordinator subscribed to data topic" +7. 确认数据请求是否发送：日志中应看到 "Coordinator sent data_get request" +8. 验证设备响应格式：响应应包含 `cmd: "data_get"` 和正确的 `meter_list` 结构 ### 启用调试日志 @@ -153,13 +243,47 @@ logger: homeassistant.components.mqtt: debug ``` +## 传感器值处理逻辑 + +集成会根据传感器类型对原始 `meter_value` 进行特殊处理： + +- **Grid Import**：仅显示负值（取绝对值），正值显示为 0 +- **Grid Export**：仅显示正值，负值显示为 0 +- **Battery Charge**：仅显示负值（取绝对值），正值显示为 0 +- **Battery Discharge**：仅显示正值，负值显示为 0 +- **Battery SOC**：原始值乘以 0.1 转换为百分比 +- **其他传感器**：直接使用原始值 + +## Meter SN 映射 + +每个传感器对应一个唯一的 `meter_sn`，用于在设备响应中识别数据： + +| 传感器 ID | Meter SN | +|----------|----------| +| `solar_power` | 1026001 | +| `home_power` | 21171201 | +| `grid_import_power` / `grid_export_power` | 16930817 | +| `battery_charge_power` / `battery_discharge_power` | 16931841 | +| `battery_soc` | 21548033 | +| `solar_energy` | 16961537 | +| `home_energy` | 16936961 | +| `grid_import_energy` | 16959489 | +| `grid_export_energy` | 16960513 | +| `battery_charge_energy` | 16952321 | +| `battery_discharge_energy` | 16953345 | + ## 技术细节 +- **架构模式**: 协调器模式（Coordinator Pattern） - **依赖**: Home Assistant MQTT 集成 -- **协议**: MQTT -- **更新方式**: Push（实时推送） -- **传感器类型**: 功率传感器、电池传感器 -- **状态类**: Measurement（测量值） +- **协议**: MQTT (QoS 1) +- **更新方式**: 主动请求 + 推送响应（每 5 秒） +- **传感器类型**: 功率传感器、能源传感器、电池传感器 +- **状态类**: + - 功率传感器：`MEASUREMENT`（测量值） + - 能源传感器：`TOTAL_INCREASING`（累计递增） + - 电池传感器：`MEASUREMENT`（测量值） +- **设备类**: `POWER`、`ENERGY`、`BATTERY` ## 许可证 diff --git a/test_mqtt.py b/test_mqtt.py deleted file mode 100644 index 919bf56..0000000 --- a/test_mqtt.py +++ /dev/null @@ -1,97 +0,0 @@ -#!/usr/bin/env python3 -""" -测试 MQTT 数据发送脚本 -用于测试 JackeryHome 集成是否能正确接收数据 -""" -import json -import time -import paho.mqtt.client as mqtt -import random - -# MQTT 配置 -MQTT_BROKER = "192.168.0.101" # 修改为你的 MQTT Broker 地址 -MQTT_PORT = 1883 -TOPIC_PREFIX = "homeassistant/sensor" - -def on_connect(client, userdata, flags, rc): - """连接回调""" - if rc == 0: - print("✅ 成功连接到 MQTT Broker") - else: - print(f"❌ 连接失败，错误代码: {rc}") - -def on_publish(client, userdata, mid): - """发布回调""" - print(f"📤 消息已发布，ID: {mid}") - -def main(): - """主函数""" - print("🚀 启动 JackeryHome MQTT 测试脚本") - print(f"📡 MQTT Broker: {MQTT_BROKER}:{MQTT_PORT}") - print(f"📂 Topic Prefix: {TOPIC_PREFIX}") - print("-" * 50) - - # 创建 MQTT 客户端 - client = mqtt.Client(client_id="jackery_home_test", callback_api_version=mqtt.CallbackAPIVersion.VERSION2) - client.on_connect = on_connect - client.on_publish = on_publish - - try: - # 连接到 MQTT Broker - print("🔗 正在连接到 MQTT Broker...") - client.connect(MQTT_BROKER, MQTT_PORT, 60) - client.loop_start() - - # 等待连接 - time.sleep(2) - - # 模拟数据 - sensors = { - "solar_power": {"min": 200, "max": 3000, "unit": "W"}, - "home_power": {"min": 500, "max": 3500, "unit": "W"}, - "grid_import": {"min": 0, "max": 2000, "unit": "W"}, - "grid_export": {"min": 0, "max": 1500, "unit": "W"}, - "battery_charge": {"min": 0, "max": 1000, "unit": "W"}, - "battery_discharge": {"min": 0, "max": 1000, "unit": "W"}, - "battery_soc": {"min": 20, "max": 100, "unit": "%"}, - } - - print("📊 开始发送测试数据...") - print("按 Ctrl+C 停止") - print("-" * 50) - - count = 0 - while True: - count += 1 - print(f"\n🔄 第 {count} 轮数据发送:") - - for sensor_id, config in sensors.items(): - # 生成随机值 - value = random.randint(config["min"], config["max"]) - - # 构建主题 - topic = f"{TOPIC_PREFIX}/{sensor_id}/state" - - # 发送数据 - result = client.publish(topic, str(value)) - - if result.rc == mqtt.MQTT_ERR_SUCCESS: - print(f" ✅ {sensor_id}: {value} {config['unit']} -> {topic}") - else: - print(f" ❌ {sensor_id}: 发送失败") - - # 等待 5 秒 - time.sleep(5) - - except KeyboardInterrupt: - print("\n\n⏹️ 用户中断，正在停止...") - except Exception as e: - print(f"\n❌ 发生错误: {e}") - finally: - # 清理资源 - client.loop_stop() - client.disconnect() - print("🔚 测试脚本已停止") - -if __name__ == "__main__": - main()